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.Object
public boolean equals(java.lang.Object obj)
equals
in class java.lang.Object
public java.lang.String toString()
toString
in class java.lang.Object
public Task<T> asTask()
asTask
in interface TaskAdaptable<T>
public void initInternalFuture(<any> result)
TaskInternal
ExecutorService
initInternalFuture
in interface TaskInternal<T>
public long getQueuedTimeUtc()
getQueuedTimeUtc
in interface TaskInternal<T>
public long getSubmitTimeUtc()
Task
Task.isSubmitted()
returns the time when the task was submitted; or -1 otherwisegetSubmitTimeUtc
in interface Task<T>
public long getStartTimeUtc()
Task
Task.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()
Task
Task.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()
Task
getSubmittedByTask
in interface Task<T>
public java.lang.String getSubmittedByTaskId()
Task
getSubmittedByTaskId
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()
Task
isSubmitted
in interface Task<T>
public boolean isBegun()
Task
public 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)
Task
Future.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 TaskInternalCancellableWithMode
public boolean isCancelled()
public boolean isDone(boolean andTaskNotRunning)
Task
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.
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()
Task
Future.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.InterruptedException
java.util.concurrent.ExecutionException
public T getUnchecked()
Task
#get()
, but propagating checked exceptions as unchecked for convenience.getUnchecked
in interface Task<T>
public void blockUntilStarted()
Task
blockUntilStarted
in interface Task<T>
public boolean blockUntilStarted(Duration timeout)
blockUntilStarted
in interface TaskInternal<T>
public void blockUntilEnded()
Task
Either 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)
Task
Task.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.InterruptedException
java.util.concurrent.ExecutionException
java.util.concurrent.TimeoutException
public 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)
TaskInternal
TaskInternal.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)
TaskInternal
TaskInternal.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()
TaskInternal
getProxyTarget
in interface TaskInternal<T>