This module is an implementation of the "Promise/A+" pattern for asynchronous programming. Promises are meant to be a way to better deal with the resulting callback spaghetti that can often result in asynchronous programs.

The version of this module is being bumped up to 0.90 as the first step towards 1.0 in which the goal is to have full Promises/A+ spec compatibility. This is a departure to the previous goal of being compatible with the Promises/A spec, this means that behavior may change in subtle ways (we will attempt to document this completely and clearly whenever possible).

It is HIGHLY recommended that you test things very thoroughly before upgrading to this version.

In version up to and including 0.08 there was a bug in how rejected promises were handled. According to the spec, a rejected callback can:

Rethrow the exception, in which case the next rejected handler in the chain would be called, or

Handle the exception (by not dieing), in which case the next resolved handler in the chain would be called.

In previous versions of Promises, this last step was handled incorrectly: a rejected handler had no way of handling the exception. Once a promise was rejected, only rejected handlers in the chain would be called.

This module is actually Event Loop agnostic, the SYNOPSIS above uses AnyEvent::HTTP, but that is just an example, it can work with any of the existing event loops out on CPAN. Over the next few releases I will try to add in documentation illustrating each of the different event loops and how best to use Promises with them.

We are, with some differences, following the API spec called "Promise/A" (and the clarification that is called "Promise/A+") which was created by the Node.JS community. This is, for the most part, the same API that is implemented in the latest jQuery and in the YUI Deferred plug-in (though some purists argue that they both go it wrong, google it if you care). We differ in some respects to this spec, mostly because Perl idioms and best practices are not the same as Javascript idioms and best practices. However, the one important difference that should be noted is that "Promise/A+" strongly suggests that the callbacks given to then should be run asynchronously (meaning in the next turn of the event loop). We do not do this by default, because doing so would bind us to a given event loop implementation, which we very much want to avoid. However we now allow you to specify an event loop "backend" when using Promises, and assuming a Deferred backend has been written it will provide this feature accordingly.

As mentioned above, the default Promises::Deferred class calls the success or error then() callback synchronously, because it isn't tied to a particular event loop. However, it is recommended that you use the appropriate Deferred backend for whichever event loop you are running.

Typically an application uses a single event loop, so all Promises should use the same event-loop. Module implementers should just use the Promises class directly:

package MyClass;
use Promises qw(deferred collect);

End users should specify which Deferred backend they wish to use. For instance if you are using AnyEvent, you can do:

use Promises backend => ['AnyEvent'];
use MyClass;

The Promises returned by MyClass will automatically use whichever event loop AnyEvent is using.

Scala has a notion of Promises and an associated idea of Futures as well. The differences and similarities between this module and the Promises found in Scalar are highlighted in depth in a cookbook entry below.

The only export for this module is the collect function, which accepts an array of Promises::Promise objects and then returns a Promises::Promise object which will be called once all the @promises have completed (either as an error or as a success). The eventual result of the returned promise object will be an array of all the results (or errors) of each of the @promises in the order in which they where passed to collect originally.

If collect is passed a value that is not a promise, it'll be wrapped in an arrayref and passed through.