edu.emory.mathcs.util.concurrent
Class AsyncTask

java.lang.Object
  extended byedu.emory.mathcs.util.concurrent.AsyncTask
All Implemented Interfaces:
Future
Direct Known Subclasses:
SecureAsyncTask

public class AsyncTask
extends java.lang.Object
implements Future

A class maintaining a single reference variable serving as the result of an operation. The result cannot be accessed until it has been set.

This class is intended primarily for subclassing. Typical usage scenario is to create a new instance and invoke createPerformer, thus obtaining runnable that will execute specified task and set results in that instance. Note that such obtained runnable should be executed only once -- subsequent execution attempts will fail due to "task already completed" condition.

See Also:
Executor

Nested Class Summary
static interface AsyncTask.Cancellable
           
 
Field Summary
protected  AsyncTask.Cancellable cancellationHandler
          Wrapper for the thread in which async task is executed, or the task itself if it implements AsyncTask.Cancellable.
 
Constructor Summary
protected AsyncTask()
           
protected AsyncTask(Callback cb)
           
 
Method Summary
 boolean cancel(boolean mayInterruptIfRunning)
          Attempts to cancel execution of this task.
protected  AsyncTask.Cancellable createCancellationHandler(Callable call)
          Overridable cancellation policy that governs what should be done upon cancellation of tasks that have already started running.
protected  java.lang.Runnable createPerformer(Callable call, boolean disableStackTraces)
          Creates a runnable that will execute specified call and then mark this AsyncTask with the result of that call.
 java.lang.Object get()
          Waits if necessary for the computation to complete, and then retrieves its result.
 java.lang.Object get(long timeout, TimeUnit tunit)
          Waits if necessary for at most the given time for the computation to complete, and then retrieves its result, if available.
 boolean isCancelled()
          Returns true if this task was cancelled before it completed normally.
 boolean isDone()
          Checks if the task has completed.
protected  void setCompleted(java.lang.Object result)
          Marks the task as completed.
protected  void setFailed(java.lang.Throwable exception)
          Marks the task as failed.
static AsyncTask start(Executor executor, Callable call)
          Schedules specified task with given executor, and returns completion handle that can be used to access the result or to cancel the task.
static AsyncTask start(Executor executor, Callable call, Callback cb)
          Schedules specified task with given executor, and returns completion handle that can be used to access the result or to cancel the task.
static AsyncTask start(Executor executor, Callable call, Callback cb, boolean disableStackTraces)
          Schedules specified task with given executor, and returns completion handle that can be used to access the result or to cancel the task.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

cancellationHandler

protected AsyncTask.Cancellable cancellationHandler
Wrapper for the thread in which async task is executed, or the task itself if it implements AsyncTask.Cancellable. Set by the thread that is just about to start executing the task.

Constructor Detail

AsyncTask

protected AsyncTask()

AsyncTask

protected AsyncTask(Callback cb)
Method Detail

isDone

public boolean isDone()
Checks if the task has completed. Not synchronized to improve concurrency, using "volatile" instead

Specified by:
isDone in interface Future
Returns:
true if task completed, false otherwise.

cancel

public boolean cancel(boolean mayInterruptIfRunning)
Description copied from interface: Future
Attempts to cancel execution of this task. This attempt will fail if the task has already completed, has already been cancelled, or could not be cancelled for some other reason. If successful, and this task has not started when cancel is called, this task should never run. If the task has already started, then the mayInterruptIfRunning parameter determines whether the thread executing this task should be interrupted in an attempt to stop the task.

After this method returns, subsequent calls to Future.isDone() will always return true. Subsequent calls to Future.isCancelled() will always return true if this method returned true.

Specified by:
cancel in interface Future
Parameters:
mayInterruptIfRunning - true if the thread executing this task should be interrupted; otherwise, in-progress tasks are allowed to complete
Returns:
false if the task could not be cancelled, typically because it has already completed normally; true otherwise

isCancelled

public boolean isCancelled()
Description copied from interface: Future
Returns true if this task was cancelled before it completed normally.

Specified by:
isCancelled in interface Future
Returns:
true if this task was cancelled before it completed

setCompleted

protected void setCompleted(java.lang.Object result)
Marks the task as completed.

Parameters:
result - the result of a task.

setFailed

protected void setFailed(java.lang.Throwable exception)
Marks the task as failed.

Parameters:
exception - the cause of abrupt completion.
Throws:
java.lang.IllegalStateException - if task had been completed already.

get

public java.lang.Object get()
                     throws java.lang.InterruptedException,
                            ExecutionException
Description copied from interface: Future
Waits if necessary for the computation to complete, and then retrieves its result.

Specified by:
get in interface Future
Returns:
the computed result
Throws:
ExecutionException - if the computation threw an exception
java.lang.InterruptedException - if the current thread was interrupted while waiting

get

public java.lang.Object get(long timeout,
                            TimeUnit tunit)
                     throws java.lang.InterruptedException,
                            ExecutionException,
                            TimeoutException
Description copied from interface: Future
Waits if necessary for at most the given time for the computation to complete, and then retrieves its result, if available.

Specified by:
get in interface Future
Parameters:
timeout - the maximum time to wait
tunit - the time unit of the timeout argument
Returns:
the computed result
Throws:
java.lang.InterruptedException - if the current thread was interrupted while waiting
ExecutionException - if the computation threw an exception
TimeoutException - if the wait timed out

start

public static AsyncTask start(Executor executor,
                              Callable call)
Schedules specified task with given executor, and returns completion handle that can be used to access the result or to cancel the task. Later, if task completes successfully, the handle is marked completed with the result that has been returned from the task. If the task ends with an exception, the handle is marked failed with cause being that exception. In such case, as a debugging aid, current stack trace (that is, that of this method's invoker) is appended to the original stack trace.

Parameters:
executor - the executor to use
call - the task to schedule
Returns:
completion handle that can be used to access the result or cancel the task.

start

public static AsyncTask start(Executor executor,
                              Callable call,
                              Callback cb)
Schedules specified task with given executor, and returns completion handle that can be used to access the result or to cancel the task. Later, if task completes successfully, the handle is marked completed with the result that has been returned from the task. If the task ends with an exception, the handle is marked failed with cause being that exception. In such case, as a debugging aid, current stack trace (that is, that of this method's invoker) is appended to the original stack trace.

Parameters:
executor - the executor to use
call - the task to schedule
cb - callback to invoke upon completion
Returns:
completion handle that can be used to access the result or cancel the task.

start

public static AsyncTask start(Executor executor,
                              Callable call,
                              Callback cb,
                              boolean disableStackTraces)
Schedules specified task with given executor, and returns completion handle that can be used to access the result or to cancel the task. Later, if task completes successfully, the handle is marked completed with the result that has been returned from the task. If the task ends with an exception, the handle is marked failed with cause being that exception. In such case, as a debugging aid, current stack trace (that is, that of this method's invoker) is appended to the original stack trace unless the disableStackTraces parameter is set to false

Parameters:
executor - the executor to use
call - the task to schedule
cb - callback to invoke upon completion
disableStackTraces - if true, does not append invoker stack trace to traces of exceptions thrown during task execution
Returns:
completion handle that can be used to access the result or cancel the task.

createPerformer

protected java.lang.Runnable createPerformer(Callable call,
                                             boolean disableStackTraces)
Creates a runnable that will execute specified call and then mark this AsyncTask with the result of that call. If the call completes successfully, this AsyncTask is marked completed with the result returned by the call. If the call throws an exception, the AsyncTask is marked as failed with cause being that exception. The stack trace of the thread in which the performer is created is appended to the failure cause stack trace unless the disableStackTraces parameter is set to false.

This method is intended to be used by subclasses. Runnable returned from this method should be executed only once -- subsequent execution attempts will fail due to "task already completed" condition.

Parameters:
call - the call to execute
disableStackTraces - if true, does not append invoker stack trace to traces of exceptions thrown during execution of the runnable
Returns:
runnable that will execute specified call and set the result of this AsyncTask upon completion

createCancellationHandler

protected AsyncTask.Cancellable createCancellationHandler(Callable call)
Overridable cancellation policy that governs what should be done upon cancellation of tasks that have already started running. This method is invoked in the worker thread by the runnable created by createPerformer, before invoking the actual call. The cancellationHandler returned from this method is then stored in this AsyncTask. Later, if the user attempts cancellation while the call is already executing, the request is delegated to the handler which must then supply the appropriate action and indication of success or failure.

The default implementation behaves as follows. If the callable for which the cancellation handler is requested implements AsyncTask.Cancellable itself, that callable itself is returned as its own cancellation handler; in other words, the cancellation policy will be supplied directly by the callable implementation. Otherwise, the default behavior is to interrupt the worker thread if the mayInterruptIfRunning parameter is set to true, and fail in the other case.

Parameters:
call - the call for which the cancellation handler is requested
Returns:
cancellation handler that handles cancellation attempts while the task is already executing