@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.Task s that do not consume Executor . |
static class |
Queue.Item
Item in a queue.
|
static class |
Queue.JobOffer
Data structure created for each idle
Executor . |
static class |
Queue.LeftItem
|
static interface |
Queue.NonBlockingTask
Marks
Queue.Task s 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.
|
static class |
Queue.Saver
Schedule
save() call for near future once items change. |
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.Task s 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.Task s. |
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
BuildableItem s currently in the queue. |
int |
countBuildableItemsFor(Label l)
How many
BuildableItem s are assigned for the given label? |
org.kohsuke.stapler.HttpResponse |
doCancelItem(long id)
Called from
queue.jelly and queue-items.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.BlockedItem s. |
List<Queue.BuildableItem> |
getBuildableItems()
Gets the snapshot of all
BuildableItem s. |
List<Queue.BuildableItem> |
getBuildableItems(Computer c)
Gets all the
BuildableItem s 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.LeftItem s. |
LoadBalancer |
getLoadBalancer() |
List<Queue.BuildableItem> |
getPendingItems()
Gets the snapshot of all
BuildableItem s. |
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
BuildableItem s are assigned for the given label? |
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, getMissingResource
public static final com.thoughtworks.xstream.XStream XSTREAM
XStream
instance is used to persist Queue.Task
s.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()
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 Action
s 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.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 queue-items.jelly
.IOException
javax.servlet.ServletException
public 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)
BuildableItem
s that are waiting for an executor in the given Computer
.public List<Queue.BuildableItem> getBuildableItems()
BuildableItem
s.public List<Queue.BuildableItem> getPendingItems()
BuildableItem
s.protected List<Queue.BlockedItem> getBlockedItems()
Queue.BlockedItem
s.public Collection<Queue.LeftItem> getLeftItems()
Queue.LeftItem
s.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)
public int countBuildableItemsFor(@CheckForNull Label l)
BuildableItem
s are assigned for the given label?l
- Label to be checked. If null, any label will be accepted.
If you want to count BuildableItem
s without assigned labels,
use strictCountBuildableItemsFor(hudson.model.Label)
.BuildableItem
s for the specified label.public int strictCountBuildableItemsFor(@CheckForNull Label l)
BuildableItem
s 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.BuildableItem
s for the specified label.public int countBuildableItems()
BuildableItem
s 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 Throwable
public 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 ResourceController
InterruptedException
protected void _signalAll()
_signalAll
in class ResourceController
protected 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 ResourceController
runnable
- 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._withLock
in class ResourceController
V
- the type of return valueT
- the type of exception.callable
- the operation to perform.T
- the exception of the callableT extends Throwable
protected <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 ResourceController
V
- 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.NonBlockingTask
public Api getApi()
@CLIResolver public static Queue getInstance()
@Initializer(after=JOB_CONFIG_ADAPTED) public static void init(Jenkins h)
Copyright © 2004–2021. All rights reserved.