@ExportedBean public class Queue extends ResourceController implements Saveable
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 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.
QueueListener,
QueueTaskDispatcher| Modifier and Type | Class and Description |
|---|---|
class |
Queue.BlockedItem
Item in the blockedProjects stage. |
static class |
Queue.BuildableItem
Item in the buildables stage. |
static interface |
Queue.Executable
Represents the real meat of the computation run by
Executor. |
static interface |
Queue.FlyweightTask
Marks
Queue.Tasks that do not consume Executor. |
static class |
Queue.Item
Item in a queue.
|
class |
Queue.JobOffer
Data structure created for each idle
Executor. |
static class |
Queue.LeftItem
|
static interface |
Queue.NonBlockingTask
Marks
Queue.Tasks that are not affected by the Jenkins.isQuietingDown() quieting down},
because these tasks keep other tasks executing. |
static class |
Queue.NotWaitingItem
Common part between
Queue.BlockedItem and BuildableItem. |
static interface |
Queue.QueueAction
An optional interface for actions on Queue.Item.
|
static class |
Queue.QueueDecisionHandler
Extension point for deciding if particular job should be scheduled or not.
|
class |
Queue.StubItem
A Stub class for
Item which exposes only the name of the Task to be displayed when the user
has DISCOVERY permissions only. |
static class |
Queue.StubTask
A Stub class for
Queue.Task which exposes only the name of the Task to be displayed when the user
has DISCOVERY permissions only. |
static interface |
Queue.Task
Task whose execution is controlled by the queue.
|
static interface |
Queue.TransientTask
Marks
Queue.Tasks that are not persisted. |
static class |
Queue.WaitingItem
Item in the waitingList stage. |
| Modifier and Type | Field and Description |
|---|---|
static com.thoughtworks.xstream.XStream |
XSTREAM
This
XStream instance is used to persist Queue.Tasks. |
| Constructor and Description |
|---|
Queue(LoadBalancer loadBalancer) |
| Modifier and Type | Method and Description |
|---|---|
protected void |
_await() |
protected void |
_signalAll() |
protected boolean |
_tryWithLock(Runnable runnable)
|
protected <V> V |
_withLock(Callable<V> callable)
Some operations require to be performed with the
Queue lock held. |
protected <V,T extends Throwable> |
_withLock(hudson.remoting.Callable<V,T> callable)
Some operations require to be performed with the
Queue lock held. |
protected void |
_withLock(Runnable runnable)
Some operations require to be performed with the
Queue lock held. |
boolean |
add(AbstractProject p)
Deprecated.
as of 1.311
Use
schedule(AbstractProject) |
boolean |
add(AbstractProject p,
int quietPeriod)
Deprecated.
as of 1.311
Use
schedule(Task, int) |
boolean |
add(Queue.Task p,
int quietPeriod)
Deprecated.
as of 1.311
Use
schedule(Task, int) |
boolean |
add(Queue.Task p,
int quietPeriod,
Action... actions)
Deprecated.
as of 1.311
Use
schedule(Task, int, Action...) |
boolean |
cancel(Queue.Item item) |
boolean |
cancel(Queue.Task p)
Cancels the item in the queue.
|
void |
clear()
Wipes out all the items currently in the queue, as if all of them are cancelled at once.
|
void |
clearLeftItems()
Immediately clear the
getLeftItems() cache. |
boolean |
contains(Queue.Task t)
Returns true if this queue contains the said project.
|
int |
countBuildableItems()
Counts all the
BuildableItems currently in the queue. |
int |
countBuildableItemsFor(Label l)
How many
BuildableItems are assigned for the given label? |
org.kohsuke.stapler.HttpResponse |
doCancelItem(long id)
Called from
queue.jelly and entries.jelly. |
Api |
getApi() |
List<Queue.Item> |
getApproximateItemsQuickly()
Deprecated.
Use
getItems() directly. As of 1.607 the approximation is no longer needed. |
protected List<Queue.BlockedItem> |
getBlockedItems()
Gets the snapshot of all
Queue.BlockedItems. |
List<Queue.BuildableItem> |
getBuildableItems()
Gets the snapshot of all
BuildableItems. |
List<Queue.BuildableItem> |
getBuildableItems(Computer c)
Gets all the
BuildableItems that are waiting for an executor in the given Computer. |
Queue.StubItem[] |
getDiscoverableItems()
Returns an array of Item for which it is only visible the name of the task.
|
static Queue |
getInstance() |
Queue.Item |
getItem(long id) |
Queue.Item |
getItem(Queue.Task t)
Gets the information about the queue item for the given project.
|
Queue.Item[] |
getItems()
Gets a snapshot of items in the queue.
|
List<Queue.Item> |
getItems(Queue.Task t)
Gets the information about the queue item for the given project.
|
Collection<Queue.LeftItem> |
getLeftItems()
Returns the snapshot of all
Queue.LeftItems. |
LoadBalancer |
getLoadBalancer() |
List<Queue.BuildableItem> |
getPendingItems()
Gets the snapshot of all
BuildableItems. |
QueueSorter |
getSorter() |
List<Queue.Item> |
getUnblockedItems()
Gets all items that are in the queue but not blocked
|
Set<Queue.Task> |
getUnblockedTasks()
Works just like
getUnblockedItems() but return tasks. |
static boolean |
ifBlockedByHudsonShutdown(Queue.Task task)
Deprecated.
Use
isBlockedByShutdown(hudson.model.Queue.Task) instead. |
static void |
init(Jenkins h)
Restores the queue content during the start up.
|
static boolean |
isBlockedByShutdown(Queue.Task task)
Checks whether a task should not be scheduled because
Jenkins.isQuietingDown(). |
boolean |
isEmpty() |
boolean |
isPending(Queue.Task t)
Is the given task currently pending execution?
|
void |
load()
Loads the queue contents that was
saved. |
void |
maintain()
Queue maintenance.
|
void |
save()
Persists the queue contents to the disk.
|
Queue.WaitingItem |
schedule(AbstractProject p)
Schedule a new build for this project.
|
Queue.WaitingItem |
schedule(Queue.Task p,
int quietPeriod) |
Queue.WaitingItem |
schedule(Queue.Task p,
int quietPeriod,
Action... actions)
Convenience wrapper method around
schedule(Task, int, List) |
Queue.WaitingItem |
schedule(Queue.Task p,
int quietPeriod,
List<Action> actions)
Deprecated.
as of 1.521
Use
schedule2(Task, int, List) |
ScheduleResult |
schedule2(Queue.Task p,
int quietPeriod,
Action... actions)
Convenience wrapper method around
schedule2(Task, int, List) |
ScheduleResult |
schedule2(Queue.Task p,
int quietPeriod,
List<Action> actions)
Schedules an execution of a task.
|
Future<?> |
scheduleMaintenance()
Checks the queue and runs anything that can be run.
|
void |
setLoadBalancer(LoadBalancer loadBalancer) |
void |
setSorter(QueueSorter sorter) |
int |
strictCountBuildableItemsFor(Label l)
How many
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. |
static boolean |
tryWithLock(Runnable runnable)
|
static <V> V |
withLock(Callable<V> callable)
Some operations require to be performed with the
Queue lock held. |
static <V,T extends Throwable> |
withLock(hudson.remoting.Callable<V,T> callable)
Some operations require the
Queue lock held. |
static void |
withLock(Runnable runnable)
Some operations require to be performed with the
Queue lock held. |
static <V> Callable<V> |
wrapWithLock(Callable<V> callable)
|
static <V,T extends Throwable> |
wrapWithLock(hudson.remoting.Callable<V,T> callable)
Wraps a
Callable with the Queue lock held. |
static Runnable |
wrapWithLock(Runnable runnable)
|
canRun, execute, getBlockingActivity, getMissingResourcepublic static final com.thoughtworks.xstream.XStream XSTREAM
XStream instance is used to persist Queue.Tasks.public Queue(@Nonnull LoadBalancer loadBalancer)
public LoadBalancer getLoadBalancer()
public void setLoadBalancer(@Nonnull LoadBalancer loadBalancer)
public QueueSorter getSorter()
public void setSorter(QueueSorter sorter)
public void load()
saved.public void save()
@CLIMethod(name="clear-queue") public void clear()
@Deprecated public boolean add(AbstractProject p)
schedule(AbstractProject)@CheckForNull public Queue.WaitingItem schedule(AbstractProject p)
schedule(Task, int)@Deprecated public boolean add(AbstractProject p, int quietPeriod)
schedule(Task, int)Left for backward compatibility with <1.114.
@Deprecated public Queue.WaitingItem schedule(Queue.Task p, int quietPeriod, List<Action> actions)
schedule2(Task, int, List)@Nonnull public ScheduleResult schedule2(Queue.Task p, int quietPeriod, List<Action> actions)
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 avaialable to everyone.
For the convenience of the caller, this list can contain null, and those will be silently ignored.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 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.@Deprecated public boolean add(Queue.Task p, int quietPeriod)
schedule(Task, int)@CheckForNull public Queue.WaitingItem schedule(Queue.Task p, int quietPeriod)
@Deprecated public boolean add(Queue.Task p, int quietPeriod, Action... actions)
schedule(Task, int, Action...)@CheckForNull public Queue.WaitingItem schedule(Queue.Task p, int quietPeriod, Action... actions)
schedule(Task, int, List)@Nonnull public ScheduleResult schedule2(Queue.Task p, int quietPeriod, Action... actions)
schedule2(Task, int, List)public boolean cancel(Queue.Task p)
public boolean cancel(Queue.Item item)
public org.kohsuke.stapler.HttpResponse doCancelItem(@QueryParameter
long id)
throws IOException,
javax.servlet.ServletException
queue.jelly and entries.jelly.IOExceptionjavax.servlet.ServletExceptionpublic boolean isEmpty()
@Exported(inline=true) public Queue.Item[] getItems()
@Restricted(value=org.kohsuke.accmod.restrictions.NoExternalUse.class) @Exported(inline=true) public Queue.StubItem[] getDiscoverableItems()
@Deprecated public List<Queue.Item> getApproximateItemsQuickly()
getItems() directly. As of 1.607 the approximation is no longer needed.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.
public Queue.Item getItem(long id)
public List<Queue.BuildableItem> getBuildableItems(Computer c)
BuildableItems that are waiting for an executor in the given Computer.public List<Queue.BuildableItem> getBuildableItems()
BuildableItems.public List<Queue.BuildableItem> getPendingItems()
BuildableItems.protected List<Queue.BlockedItem> getBlockedItems()
Queue.BlockedItems.public Collection<Queue.LeftItem> getLeftItems()
Queue.LeftItems.public void clearLeftItems()
getLeftItems() cache.
Useful for tests which need to verify that no links to a build remain.public List<Queue.Item> getUnblockedItems()
public Set<Queue.Task> getUnblockedTasks()
getUnblockedItems() but return tasks.public boolean isPending(Queue.Task t)
@Nonnegative public int countBuildableItemsFor(@CheckForNull Label l)
BuildableItems are assigned for the given label?l - Label to be checked. If null, any label will be accepted.
If you want to count BuildableItems without assigned labels,
use strictCountBuildableItemsFor(hudson.model.Label).BuildableItems for the specified label.@Nonnegative public int strictCountBuildableItemsFor(@CheckForNull Label l)
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.l - Label to be checked. If null, only jobs without assigned labels
will be taken into the account.BuildableItems for the specified label.public int countBuildableItems()
BuildableItems currently in the queue.public Queue.Item getItem(Queue.Task t)
public List<Queue.Item> getItems(Queue.Task t)
public boolean contains(Queue.Task t)
@WithBridgeMethods(value=void.class) public Future<?> scheduleMaintenance()
When conditions are changed, this method should be invoked.
This wakes up one Executor so that it will maintain a queue.
public static void withLock(Runnable runnable)
Queue lock held. Use one of these methods rather
than locking directly on Queue in order to allow for future refactoring.runnable - the operation to perform.public static <V,T extends Throwable> V withLock(hudson.remoting.Callable<V,T> callable) throws T extends Throwable
Queue lock held. Use one of these methods rather
than locking directly on Queue in order to allow for future refactoring.V - the type of return valueT - the type of exception.callable - the operation to perform.T - the exception of the callableT extends Throwablepublic static <V> V withLock(Callable<V> callable) throws Exception
Queue lock held. Use one of these methods rather
than locking directly on Queue in order to allow for future refactoring.V - the type of return valuecallable - the operation to perform.Exception - if the callable throws an exception.public static boolean tryWithLock(Runnable runnable)
runnable - the operation to perform.true if the lock was available and the operation was performed.public static Runnable wrapWithLock(Runnable runnable)
runnable - the operation to wrap.public static <V,T extends Throwable> hudson.remoting.Callable<V,T> wrapWithLock(hudson.remoting.Callable<V,T> callable)
Callable with the Queue lock held.callable - the operation to wrap.public static <V> Callable<V> wrapWithLock(Callable<V> callable)
callable - the operation to wrap.protected void _await()
throws InterruptedException
_await in class ResourceControllerInterruptedExceptionprotected void _signalAll()
_signalAll in class ResourceControllerprotected void _withLock(Runnable runnable)
Queue lock held. Use one of these methods rather
than locking directly on Queue in order to allow for future refactoring._withLock in class ResourceControllerrunnable - the operation to perform.protected boolean _tryWithLock(Runnable runnable)
runnable - the operation to perform.true if the lock was available and the operation was performed.protected <V,T extends Throwable> V _withLock(hudson.remoting.Callable<V,T> callable) throws T extends Throwable
Queue lock held. Use one of these methods rather
than locking directly on Queue in order to allow for future refactoring.V - the type of return valueT - the type of exception.callable - the operation to perform.T - the exception of the callableT extends Throwableprotected <V> V _withLock(Callable<V> callable) throws Exception
Queue lock held. Use one of these methods rather
than locking directly on Queue in order to allow for future refactoring._withLock in class ResourceControllerV - the type of return valuecallable - the operation to perform.Exception - if the callable throws an exception.public void maintain()
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.)
@Deprecated public static boolean ifBlockedByHudsonShutdown(Queue.Task task)
isBlockedByShutdown(hudson.model.Queue.Task) instead.public static boolean isBlockedByShutdown(Queue.Task task)
Jenkins.isQuietingDown().task - some queue taskJenkins.isQuietingDown() unless this is a Queue.NonBlockingTaskpublic Api getApi()
@CLIResolver public static Queue getInstance()
@Initializer(after=JOB_LOADED) public static void init(Jenkins h)
Copyright © 2019. All rights reserved.