Package hudson.model

Class Queue

java.lang.Object
hudson.model.ResourceController
hudson.model.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:

  • Field Details

    • XSTREAM

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

  • Constructor Details

  • Method Details

    • getLoadBalancer

      public LoadBalancer getLoadBalancer()

    • setLoadBalancer

      public void setLoadBalancer(@NonNull LoadBalancer loadBalancer)

    • getSorter

      public QueueSorter getSorter()

    • 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)
      Deprecated.
      as of 1.311 Use schedule(AbstractProject)

    • schedule

      @CheckForNull public Queue.WaitingItem schedule(AbstractProject p)
      Schedule a new build for this project.
      See Also:

    • 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

    • schedule

      @Deprecated public Queue.WaitingItem schedule(Queue.Task p, int quietPeriod, List<Action> actions)
      Deprecated.
      as of 1.521 Use schedule2(Task, int, List)

    • 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

    • add

      @Deprecated public boolean add(Queue.Task p, int quietPeriod)
      Deprecated.
      as of 1.311 Use schedule(Task, int)

    • schedule

      @CheckForNull public Queue.WaitingItem schedule(Queue.Task p, int quietPeriod)

    • add

      @Deprecated public boolean add(Queue.Task p, int quietPeriod, Action... actions)
      Deprecated.
      as of 1.311 Use schedule(Task, int, Action...)

    • schedule

      @CheckForNull public Queue.WaitingItem schedule(Queue.Task p, int quietPeriod, Action... actions)
      Convenience wrapper method around schedule(Task, int, List)

    • schedule2

      @NonNull public ScheduleResult schedule2(Queue.Task p, int quietPeriod, Action... actions)
      Convenience wrapper method around schedule2(Task, int, List)

    • 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, jakarta.servlet.ServletException
      Called from queue.jelly and queue-items.jelly.
      Throws:
      IOException
      jakarta.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)

    • getBuildableItems

      public List<Queue.BuildableItem> getBuildableItems(Computer c)
      Gets all the Queue.BuildableItems that are waiting for an executor in the given Computer.

    • getBuildableItems

      public List<Queue.BuildableItem> getBuildableItems()
      Gets the snapshot of all Queue.BuildableItems.

    • getPendingItems

      public List<Queue.BuildableItem> getPendingItems()
      Gets the snapshot of all Queue.BuildableItems.

    • getBlockedItems

      protected List<Queue.BlockedItem> getBlockedItems()
      Gets the snapshot of all Queue.BlockedItems.

    • getLeftItems

      public Collection<Queue.LeftItem> getLeftItems()
      Returns the snapshot of all Queue.LeftItems.
      Since:
      1.519

    • 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

    • getUnblockedTasks

      public Set<Queue.Task> getUnblockedTasks()
      Works just like getUnblockedItems() but return tasks.
      Since:
      1.402

    • isPending

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

    • countBuildableItemsFor

      public int countBuildableItemsFor(@CheckForNull Label l)
      How many Queue.BuildableItems are assigned for the given label?
      Parameters:
      l - Label to be checked. If null, any label will be accepted. If you want to count Queue.BuildableItems without assigned labels, use strictCountBuildableItemsFor(hudson.model.Label).
      Returns:
      Number of Queue.BuildableItems for the specified label.

    • 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.

    • runWithLock

      public static <T extends Throwable> void runWithLock(ThrowingRunnable<T> runnable) throws T
      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.
      Throws:
      T - if the runnable throws an exception.
      Since:
      TODO

    • withLock

      public static void withLock(Runnable runnable)
      Prefer runWithLock(jenkins.util.ThrowingRunnable<T>).
      Since:
      1.592

    • callWithLock

      public static <V, T extends Throwable> V callWithLock(ThrowingCallable<V,T> callable) throws T
      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
      Since:
      TODO

    • withLock

      public static <V, T extends Throwable> V withLock(hudson.remoting.Callable<V,T> callable) throws T
      Prefer callWithLock(jenkins.util.ThrowingCallable<V, T>).
      Throws:
      T
      Since:
      1.592

    • withLock

      public static <V> V withLock(Callable<V> callable) throws Exception
      Prefer callWithLock(jenkins.util.ThrowingCallable<V, T>).
      Throws:
      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

    • tryWithLock

      public static boolean tryWithLock(Runnable runnable, Duration timeout) throws InterruptedException
      Invokes the supplied Runnable if the Queue lock was obtained within the given timeout.
      Parameters:
      runnable - the operation to perform.
      Returns:
      true if the lock was acquired within the timeout and the operation was performed.
      Throws:
      InterruptedException
      Since:
      2.529

    • 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

    • _await

      protected void _await() throws InterruptedException
      Overrides:
      _await in class ResourceController
      Throws:
      InterruptedException

    • _signalAll

      protected void _signalAll()
      Overrides:
      _signalAll in class ResourceController

    • _runWithLock

      protected <T extends Throwable> void _runWithLock(ThrowingRunnable<T> runnable) throws T
      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:
      _runWithLock in class ResourceController
      Type Parameters:
      T - the type of exception.
      Parameters:
      runnable - the operation to perform.
      Throws:
      T - the exception of the runnable
      Since:
      TODO

    • _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

    • _tryWithLock

      protected boolean _tryWithLock(Runnable runnable, Duration timeout) throws InterruptedException
      Invokes the supplied Runnable if the Queue lock was obtained within the given timeout
      Parameters:
      runnable - the operation to perform.
      Returns:
      true if the lock was acquired within the timeout and the operation was performed.
      Throws:
      InterruptedException
      Since:
      2.529

    • _callWithLock

      protected <V, T extends Throwable> V _callWithLock(ThrowingCallable<V,T> callable) throws T
      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:
      _callWithLock 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
      Since:
      TODO

    • _withLock

      protected <V, T extends Throwable> V _withLock(hudson.remoting.Callable<V,T> callable) throws T
      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
      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.)

    • ifBlockedByHudsonShutdown

      @Deprecated public static boolean ifBlockedByHudsonShutdown(Queue.Task task)
      Deprecated.
      Use isBlockedByShutdown(hudson.model.Queue.Task) instead.

    • isBlockedByShutdown

      public static boolean isBlockedByShutdown(Queue.Task task)
      Checks whether a task should not be scheduled because Jenkins.isQuietingDown().
      Parameters:
      task - some queue task
      Returns:
      true if Jenkins.isQuietingDown() unless this is a Queue.NonBlockingTask
      Since:
      1.598

    • getApi

      public Api getApi()

    • getInstance

      @CLIResolver public static Queue getInstance()

    • init

      @Initializer(after=JOB_CONFIG_ADAPTED) public static void init(Jenkins h)
      Restores the queue content during the start up.