Package hudson.model

Class Queue

  • All Implemented Interfaces:
    Saveable
    @ExportedBean
public class Queue
extends ResourceController
implements Saveable
    Build queue.

    This class implements the core scheduling logic. Queue.Task represents the executable task that are placed in the queue. While in the queue, it's wrapped into Queue.Item so that we can keep track of additional data used for deciding what to execute when.

    Items in queue goes through several stages, as depicted below: 

    
 (enter) --> waitingList --+--> blockedProjects
                           |        ^
                           |        |
                           |        v
                           +--> buildables ---> pending ---> left
                                    ^              |
                                    |              |
                                    +---(rarely)---+

    Note: In the normal case of events pending items only move to left. However they can move back if the node they are assigned to execute on disappears before their Executor thread starts, where the node is removed before the Queue.Executable has been instantiated it is safe to move the pending item back to buildable. Once the Queue.Executable has been instantiated the only option is to let the Queue.Executable bomb out as soon as it starts to try an execute on the node that no longer exists.

    In addition, at any stage, an item can be removed from the queue (for example, when the user cancels a job in the queue.) See the corresponding field for their exact meanings.

    Author:
    Kohsuke Kawaguchi
    See Also:
    QueueListener, QueueTaskDispatcher

    • Field Detail

      • XSTREAM

        public static final com.thoughtworks.xstream.XStream XSTREAM
        This XStream instance is used to persist Queue.Tasks.

    • Constructor Detail

      • Queue

        public Queue​(@NonNull
             LoadBalancer loadBalancer)

    • Method Detail

      • setLoadBalancer

        public void setLoadBalancer​(@NonNull
                            LoadBalancer loadBalancer)

      • setSorter

        public void setSorter​(QueueSorter sorter)

      • load

        public void load()
        Loads the queue contents that was saved.

      • save

        public void save()
        Persists the queue contents to the disk.
        Specified by:
        save in interface Saveable

      • clear

        public void clear()
        Wipes out all the items currently in the queue, as if all of them are cancelled at once.

      • add

        @Deprecated
public boolean add​(AbstractProject p,
                   int quietPeriod)
        Deprecated.
        as of 1.311 Use schedule(Task, int)
        Schedules a new build with a custom quiet period.

        Left for backward compatibility with <1.114.

        Since:
        1.105

      • schedule2

        @NonNull
public ScheduleResult schedule2​(Queue.Task p,
                                int quietPeriod,
                                List<Action> actions)
        Schedules an execution of a task.
        Parameters:
        actions - These actions can be used for associating information scoped to a particular build, to the task being queued. Upon the start of the build, these Actions will be automatically added to the Run object, and hence available to everyone. For the convenience of the caller, this list can contain null, and those will be silently ignored.
        Returns:
        ScheduleResult.Refused if Jenkins refused to add this task into the queue (for example because the system is about to shutdown.) Otherwise the task is either merged into existing items in the queue (in which case you get ScheduleResult.Existing instance back), or a new item gets created in the queue (in which case you get ScheduleResult.Created. Note the nature of the queue is that such Queue.Item only captures the state of the item at a particular moment, and by the time you inspect the object, some of its information can be already stale. That said, one can still look at Queue.Item.future, Queue.Item.getId(), etc.
        Since:
        1.311

      • cancel

        public boolean cancel​(Queue.Task p)
        Cancels the item in the queue. If the item is scheduled more than once, cancels the first occurrence.
        Returns:
        true if the project was indeed in the queue and was removed. false if this was no-op.

      • cancel

        public boolean cancel​(Queue.Item item)

      • doCancelItem

        public org.kohsuke.stapler.HttpResponse doCancelItem​(@QueryParameter
                                                     long id)
                                              throws IOException,
                                                     javax.servlet.ServletException
        Called from queue.jelly and queue-items.jelly.
        Throws:
        IOException
        javax.servlet.ServletException

      • isEmpty

        public boolean isEmpty()

      • getItems

        @Exported(inline=true)
public Queue.Item[] getItems()
        Gets a snapshot of items in the queue. Generally speaking the array is sorted such that the items that are most likely built sooner are at the end.

      • getDiscoverableItems

        @Restricted(org.kohsuke.accmod.restrictions.NoExternalUse.class)
@Exported(inline=true)
public Queue.StubItem[] getDiscoverableItems()
        Returns an array of Item for which it is only visible the name of the task. Generally speaking the array is sorted such that the items that are most likely built sooner are at the end.

      • getApproximateItemsQuickly

        @Deprecated
public List<Queue.Item> getApproximateItemsQuickly()
        Deprecated.
        Use getItems() directly. As of 1.607 the approximation is no longer needed.
        Like getItems(), but returns an approximation that might not be completely up-to-date.

        At the expense of accuracy, this method does not usually lock Queue and therefore is faster in a highly concurrent situation.

        The list obtained is an accurate snapshot of the queue at some point in the past. The snapshot is updated and normally no more than one second old, but this is a soft commitment that might get violated when the lock on Queue is highly contended.

        This method is primarily added to make UI threads run faster.

        Since:
        1.483

      • getItem

        public Queue.Item getItem​(long id)

      • clearLeftItems

        public void clearLeftItems()
        Immediately clear the getLeftItems() cache. Useful for tests which need to verify that no links to a build remain.
        Since:
        1.519

      • getUnblockedItems

        public List<Queue.Item> getUnblockedItems()
        Gets all items that are in the queue but not blocked
        Since:
        1.402

      • isPending

        public boolean isPending​(Queue.Task t)
        Is the given task currently pending execution?

      • strictCountBuildableItemsFor

        public int strictCountBuildableItemsFor​(@CheckForNull
                                        Label l)
        How many Queue.BuildableItems are assigned for the given label?

        The implementation is quite similar to countBuildableItemsFor(hudson.model.Label), but it has another behavior for null parameters.

        Parameters:
        l - Label to be checked. If null, only jobs without assigned labels will be taken into the account.
        Returns:
        Number of Queue.BuildableItems for the specified label.
        Since:
        1.615

      • countBuildableItems

        public int countBuildableItems()
        Counts all the Queue.BuildableItems currently in the queue.

      • getItem

        public Queue.Item getItem​(Queue.Task t)
        Gets the information about the queue item for the given project.
        Returns:
        null if the project is not in the queue.

      • getItems

        public List<Queue.Item> getItems​(Queue.Task t)
        Gets the information about the queue item for the given project.
        Returns:
        empty if the project is not in the queue.

      • contains

        public boolean contains​(Queue.Task t)
        Returns true if this queue contains the said project.

      • scheduleMaintenance

        @WithBridgeMethods(void.class)
public Future<?> scheduleMaintenance()
        Checks the queue and runs anything that can be run.

        When conditions are changed, this method should be invoked.

        This wakes up one Executor so that it will maintain a queue.

      • withLock

        public static void withLock​(Runnable runnable)
        Some operations require to be performed with the Queue lock held. Use one of these methods rather than locking directly on Queue in order to allow for future refactoring.
        Parameters:
        runnable - the operation to perform.
        Since:
        1.592

      • withLock

        public static <V,​T extends Throwable> V withLock​(hudson.remoting.Callable<V,​T> callable)
                                                throws T extends Throwable
        Some operations require the Queue lock held. Use one of these methods rather than locking directly on Queue in order to allow for future refactoring.
        Type Parameters:
        V - the type of return value
        T - the type of exception.
        Parameters:
        callable - the operation to perform.
        Returns:
        the result of the callable.
        Throws:
        T - the exception of the callable
        T extends Throwable
        Since:
        1.592

      • withLock

        public static <V> V withLock​(Callable<V> callable)
                      throws Exception
        Some operations require to be performed with the Queue lock held. Use one of these methods rather than locking directly on Queue in order to allow for future refactoring.
        Type Parameters:
        V - the type of return value
        Parameters:
        callable - the operation to perform.
        Returns:
        the result of the callable.
        Throws:
        Exception - if the callable throws an exception.
        Since:
        1.592

      • tryWithLock

        public static boolean tryWithLock​(Runnable runnable)
        Invokes the supplied Runnable if the Queue lock was obtained without blocking.
        Parameters:
        runnable - the operation to perform.
        Returns:
        true if the lock was available and the operation was performed.
        Since:
        1.618

      • wrapWithLock

        public static Runnable wrapWithLock​(Runnable runnable)
        Wraps a Runnable with the Queue lock held.
        Parameters:
        runnable - the operation to wrap.
        Since:
        1.618

      • wrapWithLock

        public static <V,​T extends Throwable> hudson.remoting.Callable<V,​T> wrapWithLock​(hudson.remoting.Callable<V,​T> callable)
        Wraps a Callable with the Queue lock held.
        Parameters:
        callable - the operation to wrap.
        Since:
        1.618

      • wrapWithLock

        public static <V> Callable<V> wrapWithLock​(Callable<V> callable)
        Wraps a Callable with the Queue lock held.
        Parameters:
        callable - the operation to wrap.
        Since:
        1.618

      • _withLock

        protected void _withLock​(Runnable runnable)
        Some operations require to be performed with the Queue lock held. Use one of these methods rather than locking directly on Queue in order to allow for future refactoring.
        Overrides:
        _withLock in class ResourceController
        Parameters:
        runnable - the operation to perform.
        Since:
        1.592

      • _tryWithLock

        protected boolean _tryWithLock​(Runnable runnable)
        Invokes the supplied Runnable if the Queue lock was obtained without blocking.
        Parameters:
        runnable - the operation to perform.
        Returns:
        true if the lock was available and the operation was performed.
        Since:
        1.618

      • _withLock

        protected <V,​T extends Throwable> V _withLock​(hudson.remoting.Callable<V,​T> callable)
                                             throws T extends Throwable
        Some operations require to be performed with the Queue lock held. Use one of these methods rather than locking directly on Queue in order to allow for future refactoring.
        Overrides:
        _withLock in class ResourceController
        Type Parameters:
        V - the type of return value
        T - the type of exception.
        Parameters:
        callable - the operation to perform.
        Returns:
        the result of the callable.
        Throws:
        T - the exception of the callable
        T extends Throwable
        Since:
        1.592

      • _withLock

        protected <V> V _withLock​(Callable<V> callable)
                   throws Exception
        Some operations require to be performed with the Queue lock held. Use one of these methods rather than locking directly on Queue in order to allow for future refactoring.
        Overrides:
        _withLock in class ResourceController
        Type Parameters:
        V - the type of return value
        Parameters:
        callable - the operation to perform.
        Returns:
        the result of the callable.
        Throws:
        Exception - if the callable throws an exception.
        Since:
        1.592

      • maintain

        public void maintain()
        Queue maintenance.

        Move projects between waitingList, blockedProjects, buildables, and pendings appropriately.

        Jenkins internally invokes this method by itself whenever there's a change that can affect the scheduling (such as new node becoming online, # of executors change, a task completes execution, etc.), and it also gets invoked periodically (see Queue.MaintainTask.)

      • getApi

        public Api getApi()