bayou.async

Class Promise<T>

java.lang.Object

bayou.async.Promise<T>

All Implemented Interfaces:

Async<T>

public class Promise<T>
extends Object
implements Async<T>

An implementation of `Async` for result producers.

A result producer creates a Promise<T> and presents it to result consumers as Async<T>. The result producer later completes the Async when the result is available, through `succeed(), fail(), or complete()` methods.

The cancellation request

Each `cancel(reason)` sends a cancellation request to this Promise. However, only the 1st request, before completion of this promise, is effective. We call it the cancellation request for this Promise. Other requests are ignored.

Cancellation Listener

The result producer can register cancellation listeners, through `onCancel(listener)`, to react to the cancellation request.

Multiple cancellation listeners can be registered. A result producing process may involve a series of steps, and each step requires a different cancellation listener. We consider that once a step is completed, its cancellation listener becomes useless. For the sake of garbage collection, a registered cancellation listener is discarded when the next one is registered, or when the Promise is completed. The Promise keeps at most one cancellation listener at a time.

When the cancellation request arrives, the current registered cancellation listener (if any) is triggered. Any future cancellation listener is triggered as soon as it's registered (if before completion).

If you do need multiple concurrent cancellation listeners, you can register one master listener, and manage sub-listeners by yourself.

Associated Fiber

At the time of construction `new Promise()`, the current fiber is associated with this Promise. Note that the fiber can be null, which is not a fatal problem.

Constructor Summary

Constructors

Constructor and Description
Promise() Create a Promise, to be completed later.

Method Summary

Instance Methods
void	succeed(T v) Complete this Promise with success of value `v`.
void	fail(Exception e) Complete this Promise with failure of exception `e`.
void	complete(Result<T> result) Complete this Promise with `result`.
void	onCancel(Consumer<Exception> listener) Register a cancellation listener.
Exception	pollCancel() Poll the cancellation request.
Result<T>	pollResult() Implements Async.pollResult().
void	onCompletion(Consumer<Result<T>> callback) Implements Async.onCompletion(Consumer).
void	cancel(Exception reason) Implements Async.cancel(Exception).
String	toString() Implements Object.toString().
void	fiberTracePush() Add the current thread stack trace to the fiber stack trace.
void	fiberTracePop() Remove the last pushed fiber stack trace.

Methods inherited from class java.lang.Object

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

Methods inherited from interface bayou.async.Async

catch__, catch_, covary, finally_, finally_, isCompleted, map, map, peek, peek, sync, then, then, timeout, transform

Constructor Detail

Promise

public Promise()

Create a Promise, to be completed later.

Every Promise should eventually be completed.

The current fiber is associated with this Promise.

Note: this constructor automatically does a fiberTracePush(); if that's not desired, do fiberTracePop() immediately after construction. If a Promise is created but never completed, the fiber stack trace it pushed in the constructor may never be popped.

Method Detail

succeed

public void succeed(T v)
             throws IllegalStateException

Complete this Promise with success of value `v`.

This method is equivalent to `complete(Result.success(v))`.

Parameters:

v - the success value; can be null.

Throws:

IllegalStateException - if this Promise has already been completed.

fail

public void fail(Exception e)
          throws IllegalStateException

Complete this Promise with failure of exception `e`.

This method is equivalent to `complete(Result.failure(e))`.

Parameters:

e - the failure exception; must be non-null.

Throws:

IllegalStateException - if this Promise has already been completed.

complete

public void complete(Result<T> result)
              throws IllegalStateException

Complete this Promise with `result`.

Multiple complete() calls are not tolerated. This method can only be invoked if this promise has not been completed.

Throws:

IllegalStateException - if this Promise has already been completed.

onCancel

public void onCancel(Consumer<Exception> listener)

Register a cancellation listener. A cancellation listener may be triggered if/when the cancellation request arrives.

If this Promise has been completed, this method has no effect.

This listener may cause the previous registered listener to be discarded.

The `listener` will be invoked in the current executor.

pollCancel

public Exception pollCancel()

Poll the cancellation request.

If this Promise has not been completed, and cancel(reason) was invoked, this method returns `reason` of the cancellation request; otherwise returns null.

This method is needed by some result producers to poll and react to cancellation requests. Note that once this Promise is completed, this method returns null -- the producer should have no need for this method after completion.

pollResult

public Result<T> pollResult()

Implements Async.pollResult().

Specified by:

pollResult in interface Async<T>

onCompletion

public void onCompletion(Consumer<Result<T>> callback)

Implements Async.onCompletion(Consumer).

Specified by:

onCompletion in interface Async<T>

cancel

public void cancel(Exception reason)

Implements Async.cancel(Exception).

Send a cancellation request to this Promise, which may trigger current/future cancellation listeners.

Specified by:

cancel in interface Async<T>

toString

public String toString()

Implements Object.toString().

Overrides:

toString in class Object

fiberTracePush

public void fiberTracePush()

Add the current thread stack trace to the fiber stack trace.

If Fiber.enableTrace==false, or the associated fiber is null, this method has no effect.

This method is used by the result producer at strategic code locations to establish informative fiber stack trace. For example

     promise.fiberTracePush();              // line[1]
     addEventListener( (event) ->
     {
         promise.fiberTracePop();
         handle event...
     });
 

while the result producer is awaiting the event, the fiber stack trace will show line[1] at the top.

Note: the constructor Promise() automatically does a `fiberTracePush()`; if that's not desired, do a `fiberTracePop()` immediately after construction.

fiberTracePop

public void fiberTracePop()

Remove the last pushed fiber stack trace. See fiberTracePush().

If Fiber.enableTrace==false, or the associated fiber is null, this method has no effect.

On completion of this Promise, all previously pushed fiber stack traces by this Promise will be popped automatically.