Promise CLASS

This class represents a promise that a certain operation will eventually arrive at a conclusion, upon which a result or exception can be demanded.

The promise is the primary means in Julian to perform asynchronous programming. Its API is heavily inspired by JavaScript. In general, a user creates a Promise with a Function, and continues it with following operations that can be triggered either on successful completion or abortion. The continuation itself is a new promise, thus enabling the creation of the promise chain, which would run on its own thread, without blocking the thread from which the chain is created and invoked.

Many I/O APIs provides asynchronous methods which return Promises. These API serve as the starting point for most users in their asynchronous programming. However, the programmers may also create their own Promises and even control their completion through a handle. See Asychronous Programming for more details.

Parent Class

Object

All Members

Type	Name	Signature
constructor	Promise	`public Promise(Function)`
constructor	Promise	`protected Promise()`
method^S	defer	`public static DeferredPromise defer()`
method	error	`public Promise error(Function)`
method	fin	`public Promise fin(Function)`
method	getResult	`public var getResult(bool)`
method^S	start	`public static Promise start()`
method^S	start	`public static Promise start(Function)`
method	then	`public Promise then(Function)`
method	then	`public Promise then(Function, Function)`
method	toString	`public String toString()`
method^S	whenAll	`public static Promise whenAll(System.Concurrency.Promise[])`
method^S	whenAny	`public static Promise whenAny(System.Concurrency.Promise[])`

Constructors

`public Promise(Function f)`

Create a promise and start immediately.

Parameters

f A function to call with this promise.

`protected Promise()`

Create a promise but assign no operation to it. Therefore the promise will linger on PENDING state.

This constructor is reserved only for subclasses and is subject to removal in the future.

Methods

`public static DeferredPromise defer()`

A factory method to create a deferred promise, which is now staying on PENDING state.

Returns

A promise that is pending.

See Also

System.Concurrency.DeferredPromise

`public Promise error(Function e)`

Continue this promise with a function on rejection. If this promise eventually resolves, the given function won't run, and the result will be propagated to the new promise. See then(Function s, Function e) for more details about the Function's signature.

Parameters

e The function to continue upon error.

Returns

A new promise within which the given function is invoked, if the current one rejects. If the current one resolves, the result is propagated to the new promise, which would not run the given function.

`public Promise fin(Function f)`

Always continue this promise with a function on settlement of this promise. See then(Function s, Function e) for more details about the Function's signature.

Parameters

f The function to continue upon settlement, regardless of the result.

Returns

A new promise within which the given function is invoked.

`public var getResult(bool throwOnError)`

Get the result or faulting exception of this promise.

This method will block if the promise has not completed yet.

Parameters

throwOnError true to re-throw the faulting exception if the promise rejected.

Returns

the result, or exception in case of rejection.

`public static Promise start()`

A factory method to start a promise that immediately resolves with null.

Returns

A resolved promise whose result is null.

`public static Promise start(Function f)`

A factory method to start a promise with a specified function.

Parameters

f A function to call with this promise.

Returns

A promise that has been kicked off with the given function.

`public Promise then(Function s)`

Continue this promise with a function on resolution. If this promise eventually rejects, the given function won't run, and the exception will be propagated to the new promise. See then(Function s, Function e) for more details about the Function's signature.

Parameters

s The function to continue upon success.

Returns

A new promise within which the given function is invoked, if the current one resolves. If the current one rejects, the exception is propagated to the new promise, which would not run the given function.

`public Promise then(Function s, Function e)`

Continue this promise with one of two function, one for resolution, the other rejection.

The function to continue with can take up to two arguments: the first one an untyped value which is either the result produced by the previous promise, or exception that faulted the previous promise. The second value is a PromiseHandle referring to the current promise. Since this function is to be invoked dynamically, it's legal to pass any number of arguments, although only the first two will be heeded.

Parameters

s The function to continue upon resolution.
e The function to continue upon rejection.

Returns

A new promise within which one of the two given functions is invoked.

`public String toString()`

Get a textual description of this promise at its current state. If the promise is settled, the string representation of the result, or the error message of the faulting exception, will be included in this message.

Returns

a textual description of this promise at its current state.

`public static Promise whenAll(Promise[] proms)`

Wait until all of the Promises are settled, either in success or failure.

Parameters

proms The promises to wait for.

Returns

A promise that will be settled when all the promises get settled, with their result or exception carried over in an array of Any. Note the result at a certain index can be null if the corresponding Promise in the given array is null or is resolved with null.

`public static Promise whenAny(Promise[] proms)`

Wait until any of the Promises is settled, either in success or failure.

Parameters

proms The promises to wait for.

Returns

A promise that will be settled when the first promise gets settled, with the latter's result or exception carried over.