AsyncFuture
Date: 2012-06-29

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## org.chromium.sdk.util
Class AsyncFuture<T>

    java.lang.Object
      org.chromium.sdk.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.chromium.sdk.util.AsyncFuture.Operation)` 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.chromium.sdk.util.AsyncFuture.Callback, org.chromium.sdk.SyncCallback)` methods.

Nested Class Summary
`static interface` | `AsyncFuture.Callback<RES>` A callback used in operation and in `getAsync(org.chromium.sdk.util.AsyncFuture.Callback, org.chromium.sdk.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
`AsyncFuture()`

Method Summary
`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.chromium.sdk.util.AsyncFuture.Operation)` is called with this reference.

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD