• Modules
    • By category
    • By name
    • Most popular
    • Most downloaded
    • Repository
  • Register
  • Log in
  • Help
    • Start using Ceylon Herd
    • Publish your first module
    • Module publishing guidelines
    • All about Ceylon
    • Keyboard Shortcuts

    • s Focus search module bar
      ? Open this information panel
      j Move selection down
      k Move selection up
      enter Open current selection
Module info
Name
vietj / vietj.promises
Deprecated : see ceylon.promises
Description

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.
Last Published Nov 13, 2013
Stats Downloads (JVM): 6161
Downloads (JS): 0
Source downloads: 7348
Module links Home
Code repository
Issue tracker
Imported By
Browse
List of published versions
0.5.0 JVM JVM: 1.0.0 (outdated) Published Nov 13, 2013 Browse
View docs
0.4.1 JVM JVM: M6 (outdated) Published Sep 24, 2013 Browse
View docs
0.4.0 JVM JVM: M6 (outdated) Published Sep 23, 2013 Browse
View docs
0.3.5 JVM JVM: M5 (outdated) Published Jun 30, 2013 Browse
View docs
0.3.4 JVM JVM: M5 (outdated) Published Jun 30, 2013 Browse
View docs
0.3.3 JVM JVM: M5 (outdated) Published Jun 16, 2013 Browse
View docs
0.3.2 JVM JVM: M5 (outdated) Published Jun 16, 2013 Browse
View docs
0.3.1 JVM JVM: M5 (outdated) Published Jun 14, 2013 Browse
View docs
0.3.0 JVM JVM: M5 (outdated) Published Jun 9, 2013 Browse
View docs
0.2.1 JVM JVM: M5 (outdated) Published Jun 3, 2013 Browse
View docs
0.2.0 JVM JVM: M5 (outdated) Published Jun 2, 2013 Browse
View docs
0.1.0 JVM JVM: M5 (outdated) Published Jun 2, 2013 Browse
View docs
You must be logged in to comment.

Ceylon Herd v1.24 Copyright 2012-2023 Red Hat. About