org.eclipse.equinox.concurrent.future

Interface IFuture<ResultType>

Type Parameters:

ResultType - the type that will be returned by get() and/or get(long)

All Known Subinterfaces:

IListenableFuture<ResultType>

All Known Implementing Classes:

AbstractFuture, AbstractListenableFuture, SingleOperationFuture, SingleOperationListenableFuture

public interface IFuture<ResultType>

A future represents the future outcome of some operation(s).

The expected usage of a future is as a return value from some operation that is to be executed asynchronously and then return some result.

So, for example, a simple usage of an IFuture would be:

 IFuture future = foo();
 ...
 Object result = future.get();
 

Clients generally will hold onto the future for some amount of time, and then call get() or get(long) to retrieve the result of the operation. They may also call hasValue() to determine whether any values have been provided to the future (if true, meaning that subsequent calls to get() will not block), or isDone() to determine if all operations and results have been completed.

If hasValue() is true, then the client may access status information associated with the completed operation(s) via getStatus(). Until hasValue() is true, getStatus() will be null.

Since:

1.1

See Also:

IStatus

Method Summary

Modifier and Type	Method and Description
boolean	cancel() Cancel the operation
ResultType	get() Waits if necessary for one or more operations to complete, and then returns result(s).
ResultType	get(long waitTimeInMillis) Waits if necessary for one or more operations to complete, and then returns result(s).
IStatus	getStatus() Get status for operation.
boolean	hasValue() Returns true if any underlying operation(s) have completed.
boolean	isDone() Returns true if all underlying operation(s) have been completed.

Method Detail

cancel

boolean cancel()

Cancel the operation

Returns:

false if the operation could not be canceled, typically because it has already completed normally; true otherwise

get

ResultType get()
        throws java.lang.InterruptedException,
               OperationCanceledException

Waits if necessary for one or more operations to complete, and then returns result(s). This method will block until either a) at least one result is available; or b) at least one operation throws an exception.

Returns:

Object result of the asynchronous operation(s)

Throws:

java.lang.InterruptedException - if thread calling this method is interrupted.

OperationCanceledException - if the operation has been canceled via progress monitor #getProgressMonitor().

get

ResultType get(long waitTimeInMillis)
        throws java.lang.InterruptedException,
               TimeoutException,
               OperationCanceledException

Waits if necessary for one or more operations to complete, and then returns result(s). This method will block until either a) at least one result is available; or b) at least one operation throws an exception.

Parameters:

waitTimeInMillis - the maximum time to wait in milliseconds for the operation(s) to complete.

Returns:

Object result of the asynchronous operation(s)

Throws:

java.lang.InterruptedException - if thread calling this method is interrupted.

TimeoutException - if the given wait time is exceeded without getting result.

OperationCanceledException - if the operation has been canceled via progress monitor #getProgressMonitor().

getStatus

IStatus getStatus()

Get status for operation. Will return null until at least one operation(s) are complete.

If hasValue() returns true, this method will return a non-null IStatus. If hasValue() returns false, this method will return null.

Note that the returned IStatus instance may be an IMultiStatus, meaning that multiple operations have completed or are pending completion.

Returns:

IStatus the status of completed operation(s). Will return null if hasValue() returns false.

See Also:

hasValue()

hasValue

boolean hasValue()

Returns true if any underlying operation(s) have completed.

If this future represents access to just one operation, then this method and isDone() will always return the same value. That is, when a single operation has a value, it is then considered done/completed and both isDone() and this method will return true.

If this future represents multiple operations, then this method will return true when any of the operations have completed. Until the first operation is completed, it will return false.

Returns:

true if any operations represented by this future have completed.

isDone

boolean isDone()

Returns true if all underlying operation(s) have been completed.

If this future represents access to just one operation, then this method and hasValue() will always return the same value. That is, when a single operation has a value, it is then considered done/completed and both hasValue() and #isDone will return true.

If this future represents multiple operations, then this method will only return true when all of the operations have completed. Until all operations have completed, it will return false.

Completion can be due to normal operation completion, an exception, or user cancellation -- in all of these cases, this method will return true if all underlying operation(s) have been completed.

Returns:

true if all operation(s) have completed in some manner.