A module that provides Promises/A+ semantics adapted to the Ceylon language.

This implementation conforms to the Promises/A+ specification although it is not a formal implementation due to the adaptation to the Ceylon language and type system. However it attempts to respect the meaning of the specification and the same terminology.

The modules provides:

• the [[Thenable]] interface forming the ground of promises, implemented primarily by the [[Promise]] interface.
• the [[Promise]] interface conforming to the specification, a promise is a [[Thenable]] for a single value.
• the [[Deferred]] type providing support for the [[Promise]] interface.
• the [[Term]] interface for combining promises into a conjonction promise.

Goal

If a function cannot return a value or throw an exception without blocking, it can return a promise instead. A promise is an object that represents the return value or the thrown exception that the function may eventually provide. A promise can also be used as a proxy for a remote object to overcome latency.

Usage

Promise

The [[Promise]] interface expose the then_ method allowing interested parties to be notified when the promise makes a transition to the fulfilled or the rejected status:

Promise<String> promise = getPromise();
promise.then_(
    (String s) => print("The promise is resolved with " + s),
    (Exception e) => print("The promise is rejected with " + e.message));

The first function is called the onFulfilled callback and the second function is called the onRejected callback. The onRejected function is optional.

Deferred

A [[Deferred]] object provides an implementation of the [[Promise]] interface and can be transitionned to a fulfillment or a reject resolution. It should remain private to the part of the code using it and only its promise should be visible.

The [[Promise]] of a deferred can be retrieved with its promise field.

value deferred = Deferred<String>();
return deferred.promise;

The [[Deferred]] object implements the [[Transitionnable]] interface which provides two methods for resolving the promise:

• resolve: resolves the promise with a value
• reject: rejects the promise with an reason of type Exception

For example:

value deferred = Deferred<String>();
void doOperation() {
  try {
    String val = getValue();
    deferred.resolve(val);
  }
  catch(Exception e) {
    deferred.reject(e);
  }
}

Chaining promises

When invoking the then_ method the onFulfilled and onRejected callbacks can return a value. The then_ method returns a new promise that will resolve with the value of the callback. This promise will be rejected if the callback invocation fails.

Promise<Integer> promiseOfInteger = getPromiseOfInteger();
Promise<String> promiseOfString = promiseOfInteger.then_((Integer i) => i.string);
promiseOfString.then_((String s) => print("Completed with " + s));

or shorter

getPromiseOfInteger().then_((Integer i) => i.string).then_((String s) => print("Completed with " + s));

Combining promises

Promises can be combined into a single promise that is resolved when all the combined promises are resolved. If one of the promise is rejected then the combined promise is rejected.

Promise<String> promiseOfInteger = getPromiseOfString();
Promise<Integer> promiseOfString = getPromiseOfInteger();
promiseOfInteger.and(promiseOfString).then_(
    (Integer i, String s) => print("All resolved"),
    (Exception e) => print("One failed"));

There are two things to note here:

• the order of the arguments in the callback is in reverse order of the chaining.
• the return type of combined promise is not [[Promise]] but [[Thenable]].

Always

The always method of a promise allows to be notified when the promise is fulfilled or rejected, it takes as argument of the callback an alternative of the promise value type and reason type:

promise.always((String|Integer) p => print("done!");

Always is useful for implementing a finally clause in a chain of promise.

Feeding with a promise

Deferred can be transitionned with promises instead of a value:

Deferred<String> deferred1 = getDeferred1();
Deferred<String> deferred2 = getDeferred2();
deferred1.resolve(deferred2);

Similarly the callback can return a promise instead of a value:

Deferred<String> deferred = Deferred<String>();
promise.then__((String s) => deferred.promise);

Future

Sometimes it is convenient to block until a promise is resolved, for this purpose a promise can be turned into a [[Future]] via its future:

Promise<String> promise = getPromise();
Future<String|Exception> future = promise.future();
String|Exception resolution = future.get(10000);

Keep in mind that this is not the way you should use promises as this defeats the non blocking model. Nevertheless can be useful to block (for instance: unit testing purposes).

Thread safety

The implementation is thread safe and use non blocking algorithm for maintaining the state of a deferred object.

Differences with the original specification:

• the then must return before onFulfilled or onRejected is called is not implemented, therefore the invocation occurs inside the invocation of then.
• the Promise Resolution Procedure is implemented for objects or promises but not for thenable as it requires a language with dynamic typing.