org.eclipse.wst.jsdt.chromium.util

## Class AsyncFuture<T>

- java.lang.Object
- - org.eclipse.wst.jsdt.chromium.util.AsyncFuture<T>

Type Parameters:
  `T` - type of the future result

    public abstract class AsyncFuture<T>
    extends java.lang.Object

Represents a result of asynchronous operation. Unlike `Future`, the result may be obtained both synchronously (blocking getter method) and asynchronously.

The class provides a low-level service and should be used with `AtomicReference` class. `AsyncFutureRef` offers a slightly more convenient interface for the price of extra object (you may find it significant when there are tons of operations).

The owner of the future operation must have a permanent field of type `AtomicReference<AsyncFuture>`. It will consequently have the following values:

1. null -- operation is idle (hasn't been started yet); user will start it some time later;
2. `AsyncFuture` instance that is performing the operation;
3. `AsyncFuture` stub instance that simply keeps a result value and returns it very quickly;

The user only creates an empty `AtomicReference` object. Not before the result value is actually needed the other objects are created and the operation is started. This is typically happens in some getter. The method should:

- check the reference; if it still holds null value, the user should initialize it by `initializeReference(java.util.concurrent.atomic.AtomicReference<org.eclipse.wst.jsdt.chromium.util.AsyncFuture<T>>, org.eclipse.wst.jsdt.chromium.util.AsyncFuture.Operation<T>)` method; at this moment the operation is actually prepared and starts; if several threads are doing this simultaneously only one operation will be actually started;
- read `AsyncFuture` instance from the reference -- is will be not null at this moment;
- get the result from it by `getSync()` or `getAsync(org.eclipse.wst.jsdt.chromium.util.AsyncFuture.Callback<? super T>, org.eclipse.wst.jsdt.chromium.SyncCallback)` methods.

### Nested Class Summary

Nested Classes
`static interface` `AsyncFuture.Callback<RES>` A callback used in operation and in `getAsync(org.eclipse.wst.jsdt.chromium.util.AsyncFuture.Callback<? super T>, org.eclipse.wst.jsdt.chromium.SyncCallback)` method.
`static interface` `AsyncFuture.Operation<RES>` An operation that asynchronously results in a value of type RES.
`static class` `AsyncFuture.SyncOperation<RES>` Helper class that presents operation meant to be executed synchronously in the current thread as an asynchronous `AsyncFuture.Operation` suitable for `AsyncFuture`.

### Constructor Summary

Constructors
Constructor and Description
`AsyncFuture()`

### Method Summary

All Methods Static Methods Instance Methods Abstract Methods Concrete Methods
`abstract RelayOk` `getAsync(AsyncFuture.Callback<? super T> callback, SyncCallback syncCallback)` Obtains the operation result.
`abstract T` `getSync()` Returns the operation result.
`static <T> void` `initializeReference(java.util.concurrent.atomic.AtomicReference<AsyncFuture<T>> ref, AsyncFuture.Operation<T> operation)` Initializes the reference with the a new instance of `AsyncFuture` if the reference still holds null.
`static <T> void` `initializeReference(java.util.concurrent.atomic.AtomicReference<AsyncFuture<T>> ref, AsyncFuture.Operation<T> operation, boolean forceRefresh)` Operation may work synchronously.
`static <T> void` `initializeTrivial(java.util.concurrent.atomic.AtomicReference<AsyncFuture<T>> ref, T result)` Initializes the reference with the a new instance of `AsyncFuture` that already holds a result.
`abstract boolean` `isDone()` Returns whether the operation is done.
`static <T> void` `reinitializeReference(java.util.concurrent.atomic.AtomicReference<AsyncFuture<T>> ref, AsyncFuture.Operation<T> operation)` Initializes the reference with the a new instance of `AsyncFuture`.

### Methods inherited from class java.lang.Object

`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

### Constructor Detail

#### AsyncFuture

    public AsyncFuture()

### Method Detail

#### initializeReference

    public static <T> void initializeReference(java.util.concurrent.atomic.AtomicReference<AsyncFuture<T>> ref,
                                               AsyncFuture.Operation<T> operation)

Initializes the reference with the a new instance of `AsyncFuture` if the reference still holds null. This has a semantics of starting the operation. If the reference already holds non-null value, the method does nothing.

This method is thread-safe.

#### reinitializeReference

    public static <T> void reinitializeReference(java.util.concurrent.atomic.AtomicReference<AsyncFuture<T>> ref,
                                                 AsyncFuture.Operation<T> operation)

Initializes the reference with the a new instance of `AsyncFuture`. This always works even if the reference has already been initialized. This has a semantics of re-starting the operation and obtaining the new result after this call.

This method is thread-safe.

#### initializeTrivial

    public static <T> void initializeTrivial(java.util.concurrent.atomic.AtomicReference<AsyncFuture<T>> ref,
                                             T result)

Initializes the reference with the a new instance of `AsyncFuture` that already holds a result. This method skips the calculation phase and may be needed to support some trivial cases.

This method is thread-safe.

#### initializeReference

    public static <T> void initializeReference(java.util.concurrent.atomic.AtomicReference<AsyncFuture<T>> ref,
                                               AsyncFuture.Operation<T> operation,
                                               boolean forceRefresh)

Operation may work synchronously. This method will block in this case.

#### getSync

    public abstract T getSync()
                       throws MethodIsBlockingException

Returns the operation result. If the result is not ready yet, the method will block until the operation finished.

Returns:
  the operation result
Throws:
  `MethodIsBlockingException`
See Also:
  `isDone()`

#### getAsync

    public abstract RelayOk getAsync(AsyncFuture.Callback<? super T> callback,
                                     SyncCallback syncCallback)

Obtains the operation result. The result is passed to callback immediately (synchronously) or asynchronosuly later.

Parameters:
  `callback` - may be null
  `syncCallback` - may be null

#### isDone

    public abstract boolean isDone()

Returns whether the operation is done. If the method returns true, the following calls to `getSync()` will return immediately. The following calls to `getSync()` of other instance of `AsyncFuture` that is held in the reference will also be non-blocking, until `reinitializeReference(java.util.concurrent.atomic.AtomicReference<org.eclipse.wst.jsdt.chromium.util.AsyncFuture<T>>, org.eclipse.wst.jsdt.chromium.util.AsyncFuture.Operation<T>)` is called with this reference.