Provide richer information to QueueTaskDispatcher.

changelog.html

@@ -55,7 +55,9 @@ Upcoming changes</a>
 <!-- Record your changes in the trunk here. -->
 <div id="trunk" style="display:none"><!--=TRUNK-BEGIN=-->
 <ul class=image>
-  <li class=>
+  <li class=rfe>
+    Provide more information to <tt>QueueTaskDispatcher</tt>
+    (<a href="https://groups.google.com/d/topic/jenkinsci-dev/H1o_essBS_A/discussion">thread</a>)
 </ul>
 </div><!--=TRUNK-END=-->
 

core/src/main/java/hudson/model/Node.java

@@ -285,9 +285,25 @@ public abstract class Node extends AbstractModelObject implements Reconfigurable
      * task cannot be run.
      *
      * @since 1.360
+     * @deprecated as of 1.413
+     *      Use {@link #canTake(Queue.BuildableItem)}
      */
     public CauseOfBlockage canTake(Task task) {
-        Label l = task.getAssignedLabel();
+        return null;
+    }
+
+    /**
+     * Called by the {@link Queue} to determine whether or not this node can
+     * take the given task. The default checks include whether or not this node
+     * is part of the task's assigned label, whether this node is in
+     * {@link Mode#EXCLUSIVE} mode if it is not in the task's assigned label,
+     * and whether or not any of this node's {@link NodeProperty}s say that the
+     * task cannot be run.
+     *
+     * @since 1.413
+     */
+    public CauseOfBlockage canTake(Queue.BuildableItem item) {
+        Label l = item.task.getAssignedLabel();
         if(l!=null && !l.contains(this))
             return CauseOfBlockage.fromMessage(Messages._Node_LabelMissing(getNodeName(),l));   // the task needs to be executed on label that this node doesn't have.
 
@@ -297,7 +313,7 @@ public abstract class Node extends AbstractModelObject implements Reconfigurable
         // Check each NodeProperty to see whether they object to this node
         // taking the task
         for (NodeProperty prop: getNodeProperties()) {
-            CauseOfBlockage c = prop.canTake(task);
+            CauseOfBlockage c = prop.canTake(item);
             if (c!=null)    return c;
         }
 

core/src/main/java/hudson/model/Queue.java

@@ -201,15 +201,15 @@ public class Queue extends ResourceController implements Saveable {
         /**
          * Verifies that the {@link Executor} represented by this object is capable of executing the given task.
          */
-        public boolean canTake(Task task) {
+        public boolean canTake(BuildableItem item) {
             Node node = getNode();
             if (node==null)     return false;   // this executor is about to die
 
-            if(node.canTake(task)!=null)
+            if(node.canTake(item)!=null)
                 return false;   // this node is not able to take the task
 
             for (QueueTaskDispatcher d : QueueTaskDispatcher.all())
-                if (d.canTake(node,task)!=null)
+                if (d.canTake(node,item)!=null)
                     return false;
 
             return isAvailable();
@@ -614,7 +614,7 @@ public class Queue extends ResourceController implements Saveable {
     private void _getBuildableItems(Computer c, ItemList<BuildableItem> col, List<BuildableItem> result) {
         Node node = c.getNode();
         for (BuildableItem p : col.values()) {
-            if (node.canTake(p.task) == null)
+            if (node.canTake(p) == null)
                 result.add(p);
         }
     }
@@ -791,7 +791,7 @@ public class Queue extends ResourceController implements Saveable {
 
                     List<JobOffer> candidates = new ArrayList<JobOffer>(parked.size());
                     for (JobOffer j : parked.values())
-                        if(j.canTake(p.task))
+                        if(j.canTake(p))
                             candidates.add(j);
 
                     MappingWorksheet ws = new MappingWorksheet(p, candidates);

core/src/main/java/hudson/model/queue/QueueTaskDispatcher.java

@@ -30,6 +30,7 @@ import hudson.ExtensionPoint;
 import hudson.model.Hudson;
 import hudson.model.Node;
 import hudson.model.Queue;
+import hudson.model.Queue.BuildableItem;
 import hudson.model.Queue.Task;
 
 /**
@@ -59,8 +60,37 @@ public abstract class QueueTaskDispatcher implements ExtensionPoint {
      * Vetos are additive. When multiple {@link QueueTaskDispatcher}s are in the system,
      * the task won't run on the given node if any one of them returns a non-null value.
      * (This relationship is also the same with built-in check logic.)
+     *
+     * @deprecated since 1.413
+     *      Use {@link #canTake(Node, BuildableItem)}
      */
-    public abstract CauseOfBlockage canTake(Node node, Task task);
+    public CauseOfBlockage canTake(Node node, Task task) {
+        return null;
+    }
+
+    /**
+     * Called whenever {@link Queue} is considering to execute the given task on a given node.
+     *
+     * <p>
+     * Implementations can return null to indicate that the assignment is fine, or it can return
+     * a non-null instance to block the execution of the task on the given node.
+     *
+     * <p>
+     * Queue doesn't remember/cache the response from dispatchers, and instead it'll keep asking.
+     * The upside of this is that it's very easy to block execution for a limited time period (
+     * as you just need to return null when it's ready to execute.) The downside of this is that
+     * the decision needs to be made quickly.
+     *
+     * <p>
+     * Vetos are additive. When multiple {@link QueueTaskDispatcher}s are in the system,
+     * the task won't run on the given node if any one of them returns a non-null value.
+     * (This relationship is also the same with built-in check logic.)
+     *
+     * @sine 1.413
+     */
+    public CauseOfBlockage canTake(Node node, BuildableItem item) {
+        return canTake(node,item.task); // backward compatible behaviour
+    }
 
     /**
      * All registered {@link QueueTaskDispatcher}s.

core/src/main/java/hudson/slaves/NodeProperty.java

@@ -28,6 +28,7 @@ import hudson.FilePath;
 import hudson.Launcher;
 import hudson.DescriptorExtensionList;
 import hudson.model.Descriptor.FormException;
+import hudson.model.Queue.BuildableItem;
 import hudson.model.ReconfigurableDescribable;
 import hudson.model.queue.CauseOfBlockage;
 import hudson.scm.SCM;
@@ -85,11 +86,25 @@ public abstract class NodeProperty<N extends Node> implements ReconfigurableDesc
      * associated node. By default, this method returns <code>null</code>.
      *
      * @since 1.360
+     * @deprecated as of 1.413
+     *      Use {@link #canTake(BuildableItem)}
      */
     public CauseOfBlockage canTake(Task task) {
         return null;
     }
 
+    /**
+     * Called by the {@link Node} to help determine whether or not it should
+     * take the given task. Individual properties can return a non-null value
+     * here if there is some reason the given task should not be run on its
+     * associated node. By default, this method returns <code>null</code>.
+     *
+     * @since 1.413
+     */
+    public CauseOfBlockage canTake(BuildableItem item) {
+        return canTake(item.task);  // backward compatible behaviour
+    }
+
     /**
      * Runs before the {@link SCM#checkout(AbstractBuild, Launcher, FilePath, BuildListener, File)} runs, and performs a set up.
      * Can contribute additional properties to the environment.