hudson.model.queue

Class QueueTaskDispatcher

java.lang.Object

hudson.model.queue.QueueTaskDispatcher

All Implemented Interfaces:

ExtensionPoint

public abstract class QueueTaskDispatcher
extends Object
implements ExtensionPoint

Vetos the execution of a task on a node

To register your dispatcher implementations, put @Extension on your subtypes.

Since:

1.360

Author:

Kohsuke Kawaguchi

Nested Class Summary

Nested classes/interfaces inherited from interface hudson.ExtensionPoint

ExtensionPoint.LegacyInstancesAreScopedToHudson

Constructor Summary

Constructors

Constructor and Description
QueueTaskDispatcher()

Method Summary

Modifier and Type	Method and Description
static ExtensionList<QueueTaskDispatcher>	all() All registered QueueTaskDispatchers.
CauseOfBlockage	canRun(Queue.Item item) Called whenever Queue is considering if Queue.Item is ready to execute immediately (which doesn't necessarily mean that it gets executed right away — it's still subject to executor availability), or if it should be considered blocked.
CauseOfBlockage	canTake(Node node, Queue.BuildableItem item) Called when Queue is deciding where to execute the given task.
CauseOfBlockage	canTake(Node node, Queue.Task task) Deprecated. since 1.413 Use canTake(Node, Queue.BuildableItem)

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

QueueTaskDispatcher

public QueueTaskDispatcher()

Method Detail

canTake

@Deprecated
 @CheckForNull
public CauseOfBlockage canTake(Node node,
                                                          Queue.Task task)

Deprecated. since 1.413 Use canTake(Node, Queue.BuildableItem)

Called whenever Queue is considering to execute the given task on a given node.

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.

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.

Vetos are additive. When multiple QueueTaskDispatchers 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.)

canTake

@CheckForNull
public CauseOfBlockage canTake(Node node,
                                             Queue.BuildableItem item)

Called when Queue is deciding where to execute the given task.

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.

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.

This method is primarily designed to fine-tune where the execution should take place. If the execution shouldn't commence anywhere at all, implementation should use canRun(Queue.Item) instead so that Jenkins understands the difference between "this node isn't the right place for this work" vs "the time isn't right for this work to execute." This affects the provisioning behaviour with elastic Jenkins deployments.

Vetos are additive. When multiple QueueTaskDispatchers 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.)

Since:

1.413

canRun

@CheckForNull
public CauseOfBlockage canRun(Queue.Item item)

Called whenever Queue is considering if Queue.Item is ready to execute immediately (which doesn't necessarily mean that it gets executed right away — it's still subject to executor availability), or if it should be considered blocked.

Compared to canTake(Node, Queue.BuildableItem), this version tells Jenkins that the task is simply not ready to execute, even if there's available executor. This is more efficient than canTake(Node, Queue.BuildableItem), and it sends the right signal to Jenkins so that it won't use Cloud to try to provision new executors.

Vetos are additive. When multiple QueueTaskDispatchers are in the system, the task is considered blocked if any one of them returns a non-null value. (This relationship is also the same with built-in check logic.)

If a QueueTaskDispatcher returns non-null from this method, the task is placed into the 'blocked' state, and generally speaking it stays in this state for a few seconds before its state gets re-evaluated. If a QueueTaskDispatcher wants the blockage condition to be re-evaluated earlier, call Queue.scheduleMaintenance() to initiate that process.

Returns:

null to indicate that the item is ready to proceed to the buildable state as far as this QueueTaskDispatcher is concerned. Otherwise return an object that indicates why the build is blocked.

Since:

1.427

all

public static ExtensionList<QueueTaskDispatcher> all()

All registered QueueTaskDispatchers.