NAME

VERSION

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

CALLBACKS

    sub {...}

or an object which has been overloaded to allow calling as a coderef:

    use AnyEvent;

    my $cv = AnyEvent->cond_var;
    fetch_it('http://metacpan.org')
        ->then( sub { say "Success"; return @_ })
        ->then( $cv, sub { $cv->croak(@_)} )

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 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, both of which are optional. 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 will be called on error, and will be passed all the values that were sent to the corresponding "reject". It should be noted that this method will always return a new Promises::Promise instance so that you can chain things if you like.

The success and error callbacks are wrapped in an "eval" block, so you can safely call "die()" within a callback to signal an error without killing your application. If an exception is caught, the next link in the chain will be "reject"'ed and receive the exception in @_.

If this is the last link in the chain, and there is no $error callback, the error will be swallowed silently. 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.

"catch( $error )"

This method registers a a single error callback. It is the equivalent of calling:

    $promise->then( sub {@_}, $error );
    

"done( $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".

Unlike the "then()" method, "done()" returns an empty list specifically to break the chain and to avoid deep recursion. See the explanation in Promises::Cookbook::Recursion.

Also unlike the "then()" method, "done()" callbacks are not wrapped in an "eval" block, so calling "die()" is not safe. What will happen if a "done" callback calls "die()" depends on which event loop you are running: the pure Perl AnyEvent::Loop will throw an exception, while EV and Mojo::IOLoop will warn and continue running.

"finally( $callback )"

This method is like the "finally" keyword in a "try"/"catch" block. It will execute regardless of whether the promise has been resolved or rejected. Typically it is used to clean up resources, like closing open files etc. It returns a Promises::Promise and so can be chained. The return value is discarded and the success or failure of the "finally" callback will have no effect on promises further down the chain.

"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 predicate method against the status value, it returns true if the status is "IN_PROGRESS".

"is_resolved"

This is a predicate method against the status value, it returns true if the status is "RESOLVED".

"is_rejected"

This is a predicate method against the status value, it returns true if the status is "REJECTED".

"is_unfulfilled"

This is a predicate method against the status value, it returns true if the status is still "IN_PROGRESS".

"is_fulfilled"

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

"is_failed"

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

AUTHOR

COPYRIGHT AND LICENSE

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