Package hudson.model.queue

Class 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

    • 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