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.TransientTask 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 exeucte when.

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

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

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

Nested Class Summary

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.TransientTasks that do not consume Executor.
static class	Queue.Item Item in a queue.
class	Queue.JobOffer Data structure created for each idle Executor.
static interface	Queue.NonBlockingTask Marks Queue.TransientTasks 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 interface	Queue.Task Task whose execution is controlled by the queue.
static interface	Queue.TransientTask Marks Queue.TransientTasks that are not persisted.
static class	Queue.WaitingItem Item in the waitingList stage.

Field Summary

static com.thoughtworks.xstream.XStream

XSTREAM This XStream instance is used to persist Queue.TransientTasks.

Fields inherited from interface hudson.model.Saveable

NOOP

Constructor Summary

Queue(LoadBalancer loadBalancer)

Method Summary

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.
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(int id) Called from queue.jelly and entries.jelly.
Api	getApi()
List<Queue.Item>	getApproximateItemsQuickly() Like getItems(), but returns an approximation that might not be completely up-to-date.
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.
static Queue	getInstance()
Queue.Item	getItem(int 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.
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)
static void	init(Jenkins h) Restores the queue content during the start up.
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.
WorkUnit	pop() Called by the executor to fetch something to build next.
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) Schedules an execution of a task.
void	scheduleMaintenance() Checks the queue and runs anything that can be run.
void	setLoadBalancer(LoadBalancer loadBalancer)
void	setSorter(QueueSorter sorter)

Methods inherited from class hudson.model.ResourceController

canRun, execute, getBlockingActivity, getMissingResource

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

XSTREAM

public static final com.thoughtworks.xstream.XStream XSTREAM

This XStream instance is used to persist Queue.TransientTasks.

Constructor Detail

Queue

public Queue(LoadBalancer loadBalancer)

Method Detail

getLoadBalancer

public LoadBalancer getLoadBalancer()

setLoadBalancer

public void setLoadBalancer(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

@CLIMethod(name="clear-queue")
public void clear()

Wipes out all the items currently in the queue, as if all of them are cancelled at once.

add

public boolean add(AbstractProject p)

Deprecated. as of 1.311 Use schedule(AbstractProject)

schedule

public Queue.WaitingItem schedule(AbstractProject p)

Schedule a new build for this project.

Returns:

true if the project is actually added to the queue. false if the queue contained it and therefore the add() was noop

add

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

public Queue.WaitingItem schedule(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 avaialable to everyone. For the convenience of the caller, this list can contain null, and those will be silently ignored.

Returns:

null if this task is already in the queue and therefore the add operation was no-op. Otherwise indicates the Queue.WaitingItem object added, although 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.id, etc.

Since:

1.311

add

public boolean add(Queue.Task p,
                   int quietPeriod)

Deprecated. as of 1.311 Use schedule(Task, int)

schedule

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

add

public boolean add(Queue.Task p,
                   int quietPeriod,
                   Action... actions)

Deprecated. as of 1.311 Use schedule(Task, int, Action...)

schedule

public Queue.WaitingItem schedule(Queue.Task p,
                                  int quietPeriod,
                                  Action... actions)

Convenience wrapper method around schedule(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
                                                     int id)
                                              throws IOException,
                                                     javax.servlet.ServletException

Called from queue.jelly and entries.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.

getApproximateItemsQuickly

public List<Queue.Item> getApproximateItemsQuickly()

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(int id)

getBuildableItems

public List<Queue.BuildableItem> getBuildableItems(Computer c)

Gets all the BuildableItems that are waiting for an executor in the given Computer.

getBuildableItems

public List<Queue.BuildableItem> getBuildableItems()

Gets the snapshot of all BuildableItems.

getPendingItems

public List<Queue.BuildableItem> getPendingItems()

Gets the snapshot of all BuildableItems.

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(Label l)

How many BuildableItems are assigned for the given label?

countBuildableItems

public int countBuildableItems()

Counts all the 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:

null if the project is not in the queue.

contains

public boolean contains(Queue.Task t)

Returns true if this queue contains the said project.

pop

public WorkUnit pop()
             throws InterruptedException

Called by the executor to fetch something to build next.

This method blocks until a next project becomes buildable.

Throws:

InterruptedException

scheduleMaintenance

public void 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.

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 MaintainTask.)

ifBlockedByHudsonShutdown

public static boolean ifBlockedByHudsonShutdown(Queue.Task task)

getApi

public Api getApi()

getInstance

@CLIResolver
public static Queue getInstance()

init

@Initializer(after=JOB_LOADED)
public static void init(Jenkins h)

Restores the queue content during the start up.