public abstract class QueueTaskDispatcher extends Object implements ExtensionPoint
To register your dispatcher implementations, put @Extension
on your subtypes.
ExtensionPoint.LegacyInstancesAreScopedToHudson
Constructor and Description |
---|
QueueTaskDispatcher() |
Modifier and Type | Method and Description |
---|---|
static ExtensionList<QueueTaskDispatcher> |
all()
All registered
QueueTaskDispatcher s. |
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) |
@Deprecated @CheckForNull public CauseOfBlockage canTake(Node node, Queue.Task task)
canTake(Node, Queue.BuildableItem)
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 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.)
@CheckForNull public CauseOfBlockage canTake(Node node, Queue.BuildableItem item)
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 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.)
@CheckForNull public CauseOfBlockage canRun(Queue.Item item)
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 QueueTaskDispatcher
s 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.
QueueTaskDispatcher
is concerned. Otherwise return an object that indicates why
the build is blocked.public static ExtensionList<QueueTaskDispatcher> all()
QueueTaskDispatcher
s.Copyright © 2004–2022. All rights reserved.