diff --git a/core/src/main/java/hudson/model/queue/MappingWorksheet.java b/core/src/main/java/hudson/model/queue/MappingWorksheet.java index d48007852d..98ac130e3d 100644 --- a/core/src/main/java/hudson/model/queue/MappingWorksheet.java +++ b/core/src/main/java/hudson/model/queue/MappingWorksheet.java @@ -25,9 +25,12 @@ package hudson.model.queue; import com.google.common.collect.ImmutableList; import hudson.model.Computer; +import hudson.model.Executor; import hudson.model.Label; +import hudson.model.LoadBalancer; import hudson.model.Node; import hudson.model.Queue; +import hudson.model.Queue.Executable; import hudson.model.Queue.JobOffer; import hudson.model.Queue.Task; @@ -39,6 +42,39 @@ import java.util.List; import java.util.Map; /** + * Defines a mapping problem for answering "where do we execute this task?" + * + *
+ * The heart of the placement problem is a mapping problem. We are given a {@link Task}, + * (which in the general case consists of a set of {@link SubTask}s), and we are also given a number + * of idle {@link Executor}s, and our goal is to find a mapping from the former to the latter, + * which determines where each {@link SubTask} gets executed. + * + *
+ * This mapping is done under two constraints: + * + *
+ * We first fold the former constraint into the problem definition. That is, we now consider + * a set of {@link SubTask}s that need to be co-located as a single {@link WorkChunk}. Similarly, + * we consider a set of all {@link Executor}s from the same node as {@link ExecutorChunk}. + * Now, the problem becomes the weighted matching problem from {@link WorkChunk} to {@link ExecutorChunk}. + * + *
+ * An instance of {@link MappingWorksheet} captures a problem definition, plus which
+ * {@link ExecutorChunk} and {@link WorkChunk} are compatible. The purpose of this class
+ * (and {@link ExecutorChunk} and {@link WorkChunk}) are to expose a lot of convenience methods
+ * to assist various algorithms that produce the solution of this mapping problem,
+ * which is represented as {@link Mapping}.
+ *
+ * @see LoadBalancer#map(Task, MappingWorksheet)
* @author Kohsuke Kawaguchi
*/
public class MappingWorksheet {
@@ -74,16 +110,23 @@ public class MappingWorksheet {
node = computer.getNode();
}
+ /**
+ * Is this executor chunk and the given work chunk compatible? Can the latter be run on the former?
+ */
public boolean canAccept(WorkChunk c) {
return this.size() >= c.size()
&& (c.assignedLabel==null || c.assignedLabel.contains(node));
}
+ /**
+ * Node name.
+ */
public String getName() {
return node.getNodeName();
}
/**
+ * Number of executors in this chunk.
* Alias for size but more readable.
*/
public int capacity() {
@@ -151,6 +194,11 @@ public class MappingWorksheet {
}
}
+ /**
+ * Represents the solution to the mapping problem.
+ * It's a mapping from every {@link WorkChunk} to {@link ExecutorChunk}
+ * that satisfies the constraints.
+ */
public final class Mapping {
// for each WorkChunk, identify ExecutorChunk where it is assigned to.
private final ExecutorChunk[] mapping = new ExecutorChunk[works.size()];
@@ -185,6 +233,9 @@ public class MappingWorksheet {
return mapping.length;
}
+ /**
+ * Checks if the assignments made thus far are valid an within the constraints.
+ */
public boolean isPartiallyValid() {
int[] used = new int[executors.size()];
for (int i=0; i