NAME

Promises::Deferred - An implementation of Promises in Perl

VERSION

version 0.05

SYNOPSIS

use Promises::Deferred;

sub fetch_it {
    my ($uri) = @_;
    my $d = Promises::Deferred->new;
    http_get $uri => sub {
        my ($body, $headers) = @_;
        $headers->{Status} == 200
            ? $d->resolve( decode_json( $body ) )
            : $d->reject( $body )
    };
    $d->promise;
}

DESCRIPTION

This class is meant only to be used by an implementor, meaning users of your functions/classes/modules should always interact with the associated promise object, but you (as the implementor) should use this class. Think of this as the engine that drives the promises and the promises as the steering wheels that control the direction taken.

METHODS

new

This will construct an instance, it takes no arguments.

promise

This will return a Promises::Promise that can be used as a handle for this object. It will return a new one every time it is called.

status

This will return the status of the the asynchronous operation, which will be either 'in progress', 'resolved' or 'rejected'. These three strings are also constants in this package (IN_PROGRESS, RESOLVED and REJECTED respectively), which can be used to check these values.

result

This will return the result that has been passed to either the resolve or reject methods. It will always return an ARRAY reference since both resolve and reject take a variable number of arguments.

then( $callback, ?$error )

This method is used to register two callbacks, the first $callback will be called on success and it will be passed all the values that were sent to the corresponding call to resolve. The second, $error is optional and will be called on error, and will be passed the all the values that were sent to the corresponding reject. It should be noted that this method will always return the associated Promises::Promise instance so that you can chain things if you like.

If this is the last link in the chain, and there is no $error callback, the error be silent. You can still find it by checking the result method, but no action will be taken. If this is not the last link in the chain, and no $error is specified, we will attempt to bubble the error to the next link in the chain. This allows error handling to be consolidated at the point in the chain where it makes the most sense.

resolve( @args )

This is the method to call upon the successful completion of your asynchronous operation, meaning typically you would call this within the callback that you gave to the asynchronous function/method. It takes an arbitrary list of arguments and captures them as the result of this promise (so obviously they can be retrieved with the result method).

reject( @args )

This is the method to call when an error occurs during your asynchronous operation, meaning typically you would call this within the callback that you gave to the asynchronous function/method. It takes an arbitrary list of arguments and captures them as the result of this promise (so obviously they can be retrieved with the result method).

is_in_progress

This is a predicte method against the status value, it returns true of the status is IN_PROGRESS.

is_resolving

This is a predicte method against the status value, it returns true of the status is RESOLVING.

is_rejecting

This is a predicte method against the status value, it returns true of the status is REJECTING.

is_resolved

This is a predicte method against the status value, it returns true of the status is RESOLVED.

is_rejected

This is a predicte method against the status value, it returns true of the status is REJECTED.

is_unfulfilled

This is a predicte method against the status value, it returns true of the status is still IN_PROGRESS.

is_fulfilled

This is a predicte method against the status value, it returns true of the status is RESOLVED or if the status if RESOLVING.

is_failed

This is a predicte method against the status value, it returns true of the status is REJECTED or if the status if REJECTING.

AUTHOR

Stevan Little <stevan.little@iinteractive.com>

COPYRIGHT AND LICENSE

This software is copyright (c) 2012 by Infinity Interactive, Inc..

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.