org.jboss.threads

Interface AsyncFuture<T>

All Superinterfaces:

AsyncCancellable, Future<T>

All Known Implementing Classes:

AsyncFutureTask

public interface AsyncFuture<T>
extends Future<T>, AsyncCancellable

This interface represents the result of an asynchronous future task, which provides all the features of Future while also adding several additional convenience methods and the ability to add asynchronous callbacks.

Author:

David M. Lloyd

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static class	AsyncFuture.AbstractListener<T,A> An abstract base class for an implementation of the Listener interface.
static interface	AsyncFuture.Listener<T,A> A listener for an asynchronous future computation result.
static class	AsyncFuture.Status The possible statuses of an AsyncFuture.

Method Summary

Modifier and Type	Method and Description
<A> void	addListener(AsyncFuture.Listener<? super T,A> listener, A attachment) Add an asynchronous listener to be called when this operation completes.
void	asyncCancel(boolean interruptionDesired) Handle an asynchronous cancellation.
AsyncFuture.Status	await() Wait if necessary for this operation to complete, returning the outcome.
AsyncFuture.Status	await(long timeout, TimeUnit unit) Wait if necessary for this operation to complete, returning the outcome, which may include AsyncFuture.Status.WAITING if the timeout expires before the operation completes.
AsyncFuture.Status	awaitUninterruptibly() Wait (uninterruptibly) if necessary for this operation to complete, returning the outcome.
AsyncFuture.Status	awaitUninterruptibly(long timeout, TimeUnit unit) Wait if necessary for this operation to complete, returning the outcome, which may include AsyncFuture.Status.WAITING if the timeout expires before the operation completes.
boolean	cancel(boolean interruptionDesired) Synchronously cancel a task, blocking uninterruptibly until it is known whether such cancellation was successful.
AsyncFuture.Status	getStatus() Get (poll) the current status of the asynchronous operation.
T	getUninterruptibly() Waits (uninterruptibly) if necessary for the computation to complete, and then retrieves the result.
T	getUninterruptibly(long timeout, TimeUnit unit) Waits (uninterruptibly) if necessary for at most the given time for the computation to complete, and then retrieves the result, if available.

Methods inherited from interface java.util.concurrent.Future

get, get, isCancelled, isDone

Method Detail

await

AsyncFuture.Status await()
                  throws InterruptedException

Wait if necessary for this operation to complete, returning the outcome. The outcome will be one of AsyncFuture.Status.COMPLETE, AsyncFuture.Status.CANCELLED, or AsyncFuture.Status.FAILED.

Returns:

the outcome

Throws:

InterruptedException - if execution was interrupted while waiting

await

AsyncFuture.Status await(long timeout,
                         TimeUnit unit)
                  throws InterruptedException

Wait if necessary for this operation to complete, returning the outcome, which may include AsyncFuture.Status.WAITING if the timeout expires before the operation completes.

Parameters:

timeout - the maximum time to wait

unit - the time unit of the timeout argument

Returns:

the outcome

Throws:

InterruptedException - if execution was interrupted while waiting

getUninterruptibly

T getUninterruptibly()
              throws CancellationException,
                     ExecutionException

Waits (uninterruptibly) if necessary for the computation to complete, and then retrieves the result.

Returns:

the computed result

Throws:

CancellationException - if the computation was cancelled

ExecutionException - if the computation threw an exception

getUninterruptibly

T getUninterruptibly(long timeout,
                     TimeUnit unit)
              throws CancellationException,
                     ExecutionException,
                     TimeoutException

Waits (uninterruptibly) if necessary for at most the given time for the computation to complete, and then retrieves the result, if available.

Parameters:

timeout - the maximum time to wait

unit - the time unit of the timeout argument

Returns:

the computed result

Throws:

CancellationException - if the computation was cancelled

ExecutionException - if the computation threw an exception

TimeoutException - if the wait timed out

awaitUninterruptibly

AsyncFuture.Status awaitUninterruptibly()

Wait (uninterruptibly) if necessary for this operation to complete, returning the outcome. The outcome will be one of AsyncFuture.Status.COMPLETE, AsyncFuture.Status.CANCELLED, or AsyncFuture.Status.FAILED.

Returns:

the outcome

awaitUninterruptibly

AsyncFuture.Status awaitUninterruptibly(long timeout,
                                        TimeUnit unit)

Wait if necessary for this operation to complete, returning the outcome, which may include AsyncFuture.Status.WAITING if the timeout expires before the operation completes.

Parameters:

timeout - the maximum time to wait

unit - the time unit of the timeout argument

Returns:

the outcome

getStatus

AsyncFuture.Status getStatus()

Get (poll) the current status of the asynchronous operation.

Returns:

the current status

addListener

<A> void addListener(AsyncFuture.Listener<? super T,A> listener,
                     A attachment)

Add an asynchronous listener to be called when this operation completes.

Type Parameters:

A - the attachment type

Parameters:

listener - the listener to add

attachment - the attachment to pass in

cancel

boolean cancel(boolean interruptionDesired)

Synchronously cancel a task, blocking uninterruptibly until it is known whether such cancellation was successful. Note that the Future.cancel(boolean) is somewhat unclear about blocking semantics. It is recommended to use asyncCancel(boolean) instead.

Specified by:

cancel in interface Future<T>

Parameters:

interruptionDesired - if interruption is desired (if available)

Returns:

true if cancel succeeded, false otherwise

asyncCancel

void asyncCancel(boolean interruptionDesired)

Handle an asynchronous cancellation. Does not block, and may be called more than once; in particular, this method may be re-invoked to set the interruptionDesired flag even if it has already been called without that flag set before. Otherwise, this method is idempotent, and thus may be called more than once without additional effect.

Specified by:

asyncCancel in interface AsyncCancellable

Parameters:

interruptionDesired - true if interruption of threads is desired