jenkins.model.queue

Class AsynchronousExecution

java.lang.Object

java.lang.Throwable

java.lang.Exception

java.lang.RuntimeException

jenkins.model.queue.AsynchronousExecution

All Implemented Interfaces:

Serializable

public abstract class AsynchronousExecution
extends RuntimeException

Special means of indicating that an executable will proceed in the background without consuming a native thread (Executor). May be thrown from Queue.Executable.run() after doing any preparatory work synchronously.

Executor.isActive() will remain true (even though Thread.isAlive() is not) until completed(java.lang.Throwable) is called. The thrower will need to hold on to a reference to this instance as a handle to call completed(java.lang.Throwable).

The execution may not extend into another Jenkins session; if you wish to model a long-running execution, you must schedule a new task after restart. This class is not serializable anyway.

Mainly intended for use with OneOffExecutor (from a Queue.FlyweightTask), of which there could be many, but could also be used with a heavyweight executor even though the number of executors is bounded by node configuration.

ResourceController/ResourceActivity/ResourceList/Resource are not currently supported. Nor are Queue.Task.getSubTasks() other than the primary task.

Since:

1.607

See Also:

Serialized Form

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	AsynchronousExecution() Constructor for subclasses.

Method Summary

Modifier and Type	Method and Description
abstract boolean	blocksRestart() Allows an executable to indicate whether it is currently doing something which should prevent Jenkins from being shut down safely.
void	completed(Throwable error) To be called when the task is actually complete.
abstract boolean	displayCell() Allows an executable to control whether or not to display executorCell.jelly.
Executor	getExecutor() Obtains the associated executor.
abstract void	interrupt(boolean forShutdown) Called in lieu of Thread.interrupt() by Executor.interrupt() and its overloads.
void	maybeComplete() If there is a pending completion notification, deliver it to the executor.
void	setExecutorWithoutCompleting(Executor executor) Set the executor without notifying it about task completion.

Methods inherited from class java.lang.Throwable

addSuppressed, fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, getSuppressed, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString

Methods inherited from class java.lang.Object

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

Constructor Detail

AsynchronousExecution

protected AsynchronousExecution()

Constructor for subclasses.

Method Detail

interrupt

public abstract void interrupt(boolean forShutdown)

Called in lieu of Thread.interrupt() by Executor.interrupt() and its overloads. As with the standard Java method, you are requested to cease work as soon as possible, but there is no enforcement of this. You might also want to call Executor.recordCauseOfInterruption(hudson.model.Run<?, ?>, hudson.model.TaskListener) on getExecutor().

Parameters:

forShutdown - if true, this interruption is because Jenkins is shutting down (and thus Computer.interrupt() was called from Jenkins.cleanUp()); otherwise, a normal interrupt such as by Executor.doStop()

blocksRestart

public abstract boolean blocksRestart()

Allows an executable to indicate whether it is currently doing something which should prevent Jenkins from being shut down safely. You may return false if it is fine for an administrator to exit/restart Jenkins despite this executable still being running. (If so, interrupt(boolean) will be passed forShutdown=true.)

Returns:

traditionally always true

See Also:

RestartListener.Default.isReadyToRestart()

displayCell

public abstract boolean displayCell()

Allows an executable to control whether or not to display executorCell.jelly.

If this method returns false, the asynchronous execution becomes invisible from UI.

Returns:

traditionally always true

getExecutor

@CheckForNull
public final Executor getExecutor()

Obtains the associated executor.

Returns:

Associated Executor. May be null if setExecutorWithoutCompleting(hudson.model.Executor) has not been called yet.

setExecutorWithoutCompleting

@Restricted(value=org.kohsuke.accmod.restrictions.NoExternalUse.class)
public final void setExecutorWithoutCompleting(@NonNull
                                                                                                                      Executor executor)

Set the executor without notifying it about task completion. The caller must also call maybeComplete() after releasing any problematic locks.

maybeComplete

@Restricted(value=org.kohsuke.accmod.restrictions.NoExternalUse.class)
public final void maybeComplete()

If there is a pending completion notification, deliver it to the executor. Must be called after setExecutorWithoutCompleting(Executor).

completed

public final void completed(@CheckForNull
                            Throwable error)

To be called when the task is actually complete.

Parameters:

error - normally null (preferable to handle errors yourself), but may be specified to simulate an exception from Queue.Executable.run(), as per ExecutorListener.taskCompletedWithProblems(hudson.model.Executor, hudson.model.Queue.Task, long, java.lang.Throwable)