public class BasicTask<T> extends java.lang.Object implements TaskInternal<T>
Task to be executed.
A Task is a wrapper for an executable unit, such as a Runnable or
Callable (Closure support is deprecated), and will run in its own Thread.
The task can be given an optional displayName and description in its constructor (as named
arguments in the first Map parameter). It is guaranteed to have Object.notify() called
once whenever the task starts running and once again when the task is about to complete. Due to
the way executors work it is ugly to guarantee notification after completion, so instead we
notify just before then expect the user to call get() - which will throw errors if the underlying job
did so - or blockUntilEnded() which will not throw errors.
| Modifier and Type | Class and Description |
|---|---|
static class |
BasicTask.SubmissionErrorCatchingExecutor |
static interface |
BasicTask.TaskFinalizer |
TaskInternal.TaskCancellationMode| Modifier and Type | Field and Description |
|---|---|
java.lang.String |
description |
java.lang.String |
displayName |
static BasicTask.TaskFinalizer |
NO_OP |
static BasicTask.TaskFinalizer |
WARN_IF_NOT_RUN |
| Constructor and Description |
|---|
BasicTask(java.util.concurrent.Callable<T> job) |
BasicTask(java.util.Map<?,?> flags,
java.util.concurrent.Callable<T> job) |
BasicTask(java.util.Map<?,?> flags,
java.lang.Runnable job) |
BasicTask(java.lang.Runnable job) |
| Modifier and Type | Method and Description |
|---|---|
void |
addListener(java.lang.Runnable listener,
java.util.concurrent.Executor executor) |
void |
applyTagModifier(<any> modifier) |
Task<T> |
asTask() |
void |
blockUntilEnded()
Causes calling thread to block until the task is ended.
|
boolean |
blockUntilEnded(Duration timeout)
As
Task.blockUntilEnded(), but returning after the given timeout;
true if the task has ended and false otherwise |
void |
blockUntilStarted()
Causes calling thread to block until the task is started.
|
boolean |
blockUntilStarted(Duration timeout) |
boolean |
cancel() |
boolean |
cancel(boolean mayInterruptIfRunning)
As
Future.cancel(boolean). |
boolean |
cancel(TaskInternal.TaskCancellationMode mode) |
boolean |
equals(java.lang.Object obj) |
T |
get() |
T |
get(Duration duration)
As
#get(long, java.util.concurrent.TimeUnit) |
T |
get(long timeout,
java.util.concurrent.TimeUnit unit) |
java.lang.String |
getBlockingDetails()
returns a textual message giving details while the task is blocked
|
Task<?> |
getBlockingTask()
returns a task that this task is blocked on
|
java.lang.String |
getDescription() |
java.lang.String |
getDisplayName() |
long |
getEndTimeUtc()
if
Task.isDone() (for any reason) returns the time when the task ended;
guaranteed to be >= Task.getStartTimeUtc() > 0 if ended, or -1 otherwise |
java.lang.Object |
getExtraStatusText() |
java.lang.String |
getId() |
java.util.concurrent.Future<T> |
getInternalFuture()
returns the underlying future where this task's results will come in; see
#initInternalFuture(ListenableFuture) |
java.util.concurrent.Callable<T> |
getJob() |
ExecutionList |
getListeners() |
java.util.Set<java.lang.Object> |
getMutableTags() |
Task<?> |
getProxyTarget()
if a task is a proxy for another one (used mainly for internal tasks),
this returns the "real" task represented by this one
|
long |
getQueuedTimeUtc()
if the job is queued for submission (e.g.
|
long |
getStartTimeUtc()
if
Task.isBegun() returns the time when the task was starts;
guaranteed to be >= Task.getSubmitTimeUtc() > 0 if started, or -1 otherwise |
java.lang.String |
getStatusDetail(boolean multiline)
Returns detailed status, suitable for a hover
Plain-text format, with new-lines (and sometimes extra info) if multiline enabled.
|
java.lang.String |
getStatusSummary()
Returns a brief status string
Plain-text format.
|
Task<?> |
getSubmittedByTask()
task which submitted this task, if was submitted by a task
|
java.lang.String |
getSubmittedByTaskId()
task which submitted this task, if was submitted by a task
|
long |
getSubmitTimeUtc()
if
Task.isSubmitted() returns the time when the task was submitted; or -1 otherwise |
java.util.Set<java.lang.Object> |
getTags() |
java.lang.Thread |
getThread()
the thread where the task is running, if it is running
|
T |
getUnchecked()
As
#get(), but propagating checked exceptions as unchecked for convenience. |
T |
getUnchecked(Duration duration)
As
#get(), but propagating checked exceptions as unchecked for convenience
(including a TimeoutException if the duration expires) |
int |
hashCode() |
void |
ignoreIfNotRun() |
void |
initInternalFuture(<any> result)
sets the internal future object used to record the association to a job submitted to an
ExecutorService |
boolean |
isBegun()
Whether task has started running.
|
boolean |
isCancelled() |
boolean |
isDone()
As
Future.isDone(). |
boolean |
isDone(boolean andTaskNotRunning)
As
Task.isDone(), identical if the argument is false, but by supplying true
this will also check Task.getEndTimeUtc() if Task.isBegun()
to guarantee that the task is no longer running. |
boolean |
isError()
Returns true if the task has had an error.
|
boolean |
isQueued() |
boolean |
isQueuedAndNotSubmitted() |
boolean |
isQueuedOrSubmitted() |
boolean |
isSubmitted()
Whether task has been submitted
Submitted tasks are normally expected to start running then complete,
but unsubmitted tasks are sometimes passed around for someone else to submit them.
|
void |
markQueued()
marks the task as queued for execution
|
void |
resetBlockingDetails() |
void |
resetBlockingTask() |
void |
runListeners()
On task completion runs the listeners which have been registered using
#addListener(Runnable, java.util.concurrent.Executor). |
java.lang.String |
setBlockingDetails(java.lang.String blockingDetails)
allows a task user to specify why a task is blocked; for use immediately before a blocking/wait,
and typically cleared immediately afterwards; referenced by management api to inspect a task
which is blocking
|
Task<?> |
setBlockingTask(Task<?> blockingTask)
as
TaskInternal.setBlockingDetails(String) but records a task which is blocking,
for use e.g. |
void |
setEndTimeUtc(long val) |
void |
setExtraStatusText(java.lang.Object extraStatus) |
void |
setFinalizer(BasicTask.TaskFinalizer f) |
void |
setJob(java.util.concurrent.Callable<T> job) |
void |
setStartTimeUtc(long val) |
void |
setSubmittedByTask(Maybe<Task<?>> taskM,
java.lang.String taskId)
Variant of
TaskInternal.setSubmittedByTask(Task) which allows better support for GC'd tasks. |
void |
setSubmittedByTask(Task<?> task) |
void |
setSubmitTimeUtc(long val) |
void |
setThread(java.lang.Thread thread) |
java.lang.String |
toString() |
boolean |
uncancel()
doesn't resume it, just means if something was cancelled but not submitted it could now be submitted;
probably going to be removed and perhaps some mechanism for running again made available
|
public final java.lang.String displayName
public final java.lang.String description
public static final BasicTask.TaskFinalizer WARN_IF_NOT_RUN
public static final BasicTask.TaskFinalizer NO_OP
public BasicTask(java.util.concurrent.Callable<T> job)
public BasicTask(java.util.Map<?,?> flags,
java.util.concurrent.Callable<T> job)
public BasicTask(java.lang.Runnable job)
public BasicTask(java.util.Map<?,?> flags,
java.lang.Runnable job)
public int hashCode()
hashCode in class java.lang.Objectpublic boolean equals(java.lang.Object obj)
equals in class java.lang.Objectpublic java.lang.String toString()
toString in class java.lang.Objectpublic Task<T> asTask()
asTask in interface TaskAdaptable<T>public void initInternalFuture(<any> result)
TaskInternalExecutorServiceinitInternalFuture in interface TaskInternal<T>public long getQueuedTimeUtc()
getQueuedTimeUtc in interface TaskInternal<T>public long getSubmitTimeUtc()
TaskTask.isSubmitted() returns the time when the task was submitted; or -1 otherwisegetSubmitTimeUtc in interface Task<T>public long getStartTimeUtc()
TaskTask.isBegun() returns the time when the task was starts;
guaranteed to be >= Task.getSubmitTimeUtc() > 0 if started, or -1 otherwisegetStartTimeUtc in interface Task<T>public long getEndTimeUtc()
TaskTask.isDone() (for any reason) returns the time when the task ended;
guaranteed to be >= Task.getStartTimeUtc() > 0 if ended, or -1 otherwisegetEndTimeUtc in interface Task<T>public java.util.concurrent.Future<T> getInternalFuture()
TaskInternal#initInternalFuture(ListenableFuture)getInternalFuture in interface TaskInternal<T>public Task<?> getSubmittedByTask()
TaskgetSubmittedByTask in interface Task<T>public java.lang.String getSubmittedByTaskId()
TaskgetSubmittedByTaskId in interface Task<T>public java.lang.Thread getThread()
public boolean isQueued()
isQueued in interface TaskInternal<T>public boolean isQueuedOrSubmitted()
isQueuedOrSubmitted in interface TaskInternal<T>public boolean isQueuedAndNotSubmitted()
isQueuedAndNotSubmitted in interface TaskInternal<T>public boolean isSubmitted()
TaskisSubmitted in interface Task<T>public boolean isBegun()
Taskpublic void markQueued()
markQueued in interface TaskInternal<T>public final boolean cancel()
cancel in interface TaskInternal<T>public boolean uncancel()
public final boolean cancel(boolean mayInterruptIfRunning)
TaskFuture.cancel(boolean). Note that Task.isDone() and Task.blockUntilEnded(Duration) return immediately
once a task is cancelled, consistent with the underlying FutureTask behaviour.
TODO Fine-grained control over underlying jobs, e.g. to ensure anything represented by this task is actually completed,
is not (yet) publicly exposed. See the convenience method blockUntilInternalTasksEnded in the Tasks set of helpers
for more discussion.public boolean cancel(TaskInternal.TaskCancellationMode mode)
cancel in interface TaskInternalCancellableWithModepublic boolean isCancelled()
public boolean isDone(boolean andTaskNotRunning)
TaskTask.isDone(), identical if the argument is false, but by supplying true
this will also check Task.getEndTimeUtc() if Task.isBegun()
to guarantee that the task is no longer running.
Task.isDone() will return true for cancelled tasks even if they are still running.
In a task hierarchy, the threads of tasks submitted by this may still be ongoing.
To determine their completion, inspect the ExecutionManager.
public boolean isDone()
TaskFuture.isDone(). In particular if cancelled, this will return true
as soon as it is cancelled. The thread for this task may still be running,
if the cancellation (often an interruption, but may be weaker) has not applied,
and submitted threads may also be running depending on cancellation parameters.
#get() is guaranteed to return immediately, throwing in the case of cancellation
prior to completion (and including the case above where a thread may still be running).
To check whether cancelled threads for this task have completed, use #isDone(boolean)).
inspect Task.getEndTimeUtc(), which is guaranteed to be set when threads complete
if the thread is started (as determinable by whether Task.getStartTimeUtc() is set).
(The threads of submitted/child tasks will usually be independent; to determine their
completion requires inspecting the ExecutionManager.)
public boolean isError()
get() will throw an exception when it completes (including cancel).
Implementations may set this true before completion if they have that insight, or
(the default) they may compute it lazily after completion (returning false before completion).public T get() throws java.lang.InterruptedException, java.util.concurrent.ExecutionException
java.lang.InterruptedExceptionjava.util.concurrent.ExecutionExceptionpublic T getUnchecked()
Task#get(), but propagating checked exceptions as unchecked for convenience.getUnchecked in interface Task<T>public void blockUntilStarted()
TaskblockUntilStarted in interface Task<T>public boolean blockUntilStarted(Duration timeout)
blockUntilStarted in interface TaskInternal<T>public void blockUntilEnded()
TaskEither normally or by cancellation or error, but without throwing error on cancellation or error. (Errors are logged at debug.)
blockUntilEnded in interface Task<T>public boolean blockUntilEnded(Duration timeout)
TaskTask.blockUntilEnded(), but returning after the given timeout;
true if the task has ended and false otherwiseblockUntilEnded in interface Task<T>public T get(long timeout, java.util.concurrent.TimeUnit unit) throws java.lang.InterruptedException, java.util.concurrent.ExecutionException, java.util.concurrent.TimeoutException
java.lang.InterruptedExceptionjava.util.concurrent.ExecutionExceptionjava.util.concurrent.TimeoutExceptionpublic T get(Duration duration) throws java.lang.InterruptedException, java.util.concurrent.ExecutionException, java.util.concurrent.TimeoutException
Task#get(long, java.util.concurrent.TimeUnit)public T getUnchecked(Duration duration)
Task#get(), but propagating checked exceptions as unchecked for convenience
(including a TimeoutException if the duration expires)getUnchecked in interface Task<T>public java.lang.String getStatusSummary()
getStatusSummary in interface Task<T>public java.lang.String getStatusDetail(boolean multiline)
getStatusDetail in interface Task<T>public java.lang.String getDisplayName()
getDisplayName in interface Task<T>public java.lang.String getDescription()
getDescription in interface Task<T>public java.lang.String setBlockingDetails(java.lang.String blockingDetails)
setBlockingDetails in interface TaskInternal<T>public Task<?> setBlockingTask(Task<?> blockingTask)
TaskInternalTaskInternal.setBlockingDetails(String) but records a task which is blocking,
for use e.g. in a gui to navigate to the current active subtask
returns previous blocking task, in case caller wishes to recall and restore it
setBlockingTask in interface TaskInternal<T>public void resetBlockingDetails()
resetBlockingDetails in interface TaskInternal<T>public void resetBlockingTask()
resetBlockingTask in interface TaskInternal<T>public java.lang.String getBlockingDetails()
getBlockingDetails in interface TaskInternal<T>public Task<?> getBlockingTask()
getBlockingTask in interface TaskInternal<T>public void setExtraStatusText(java.lang.Object extraStatus)
setExtraStatusText in interface TaskInternal<T>public java.lang.Object getExtraStatusText()
getExtraStatusText in interface TaskInternal<T>public void ignoreIfNotRun()
public void setFinalizer(BasicTask.TaskFinalizer f)
public void addListener(java.lang.Runnable listener,
java.util.concurrent.Executor executor)
public void runListeners()
TaskInternal#addListener(Runnable, java.util.concurrent.Executor).
Doeas not run immediately on cancellation, it waits for the task to recognize it is cancelled.
runListeners in interface TaskInternal<T>public void setEndTimeUtc(long val)
setEndTimeUtc in interface TaskInternal<T>public void setThread(java.lang.Thread thread)
setThread in interface TaskInternal<T>public java.util.concurrent.Callable<T> getJob()
getJob in interface TaskInternal<T>public void setJob(java.util.concurrent.Callable<T> job)
setJob in interface TaskInternal<T>public ExecutionList getListeners()
getListeners in interface TaskInternal<T>public void setSubmitTimeUtc(long val)
setSubmitTimeUtc in interface TaskInternal<T>public void setSubmittedByTask(Task<?> task)
setSubmittedByTask in interface TaskInternal<T>public void setSubmittedByTask(Maybe<Task<?>> taskM, java.lang.String taskId)
TaskInternalTaskInternal.setSubmittedByTask(Task) which allows better support for GC'd tasks.setSubmittedByTask in interface TaskInternal<T>public java.util.Set<java.lang.Object> getMutableTags()
getMutableTags in interface TaskInternal<T>public void setStartTimeUtc(long val)
setStartTimeUtc in interface TaskInternal<T>public void applyTagModifier(<any> modifier)
applyTagModifier in interface TaskInternal<T>public Task<?> getProxyTarget()
TaskInternalgetProxyTarget in interface TaskInternal<T>