NAME

       Mojo::Promise - Promises/A+

SYNOPSIS

         use Mojo::Promise;
         use Mojo::UserAgent;

         # Wrap continuation-passing style APIs with promises
         my $ua = Mojo::UserAgent->new;
         sub get {
           my $promise = Mojo::Promise->new;
           $ua->get(@_ => sub {
             my ($ua, $tx) = @_;
             my $err = $tx->error;
             $promise->resolve($tx) if !$err || $err->{code};
             $promise->reject($err->{message});
           });
           return $promise;
         }

         # Perform non-blocking operations sequentially
         get('http://mojolicious.org')->then(sub {
           my $mojo = shift;
           say $mojo->res->code;
           return get('http://metacpan.org');
         })->then(sub {
           my $cpan = shift;
           say $cpan->res->code;
         })->catch(sub {
           my $err = shift;
           warn "Something went wrong: $err";
         })->wait;

         # Synchronize non-blocking operations (all)
         my $mojo = get('http://mojolicious.org');
         my $cpan = get('http://metacpan.org');
         Mojo::Promise->all($mojo, $cpan)->then(sub {
           my ($mojo, $cpan) = @_;
           say $mojo->[0]->res->code;
           say $cpan->[0]->res->code;
         })->catch(sub {
           my $err = shift;
           warn "Something went wrong: $err";
         })->wait;

         # Synchronize non-blocking operations (race)
         my $mojo = get('http://mojolicious.org');
         my $cpan = get('http://metacpan.org');
         Mojo::Promise->race($mojo, $cpan)->then(sub {
           my $tx = shift;
           say $tx->req->url, ' won!';
         })->catch(sub {
           my $err = shift;
           warn "Something went wrong: $err";
         })->wait;

DESCRIPTION

       Mojo::Promise is a Perl-ish implementation of Promises/A+ <https://promisesaplus.com>.

ATTRIBUTES

       Mojo::Promise implements the following attributes.

   ioloop
         my $loop = $promise->ioloop;
         $promise = $promise->ioloop(Mojo::IOLoop->new);

       Event loop object to control, defaults to the global Mojo::IOLoop singleton.

METHODS

       Mojo::Promise inherits all methods from Mojo::Base and implements the following new ones.

   all
         my $new = Mojo::Promise->all(@promises);
         my $new = $promise->all(@promises);

       Returns a new Mojo::Promise object that either fulfills when all of the passed
       Mojo::Promise objects (including the invocant) have fulfilled or rejects as soon as one of
       them rejects. If the returned promise fulfills, it is fulfilled with the values from the
       fulfilled promises in the same order as the passed promises. This method can be useful for
       aggregating results of multiple promises.

   catch
         my $new = $promise->catch(sub {...});

       Appends a rejection handler callback to the promise, and returns a new Mojo::Promise
       object resolving to the return value of the callback if it is called, or to its original
       fulfillment value if the promise is instead fulfilled.

         # Longer version
         my $new = $promise->then(undef, sub {...});

         # Pass along the rejection reason
         $promise->catch(sub {
           my @reason = @_;
           warn "Something went wrong: $reason[0]";
           return @reason;
         });

         # Change the rejection reason
         $promise->catch(sub {
           my @reason = @_;
           return "This is bad: $reason[0]";
         });

   finally
         my $new = $promise->finally(sub {...});

       Appends a fulfillment and rejection handler to the promise, and returns a new
       Mojo::Promise object resolving to the original fulfillment value or rejection reason.

         # Do something on fulfillment and rejection
         $promise->finally(sub {
           my @value_or_reason = @_;
           say "We are done!";
         });

   race
         my $new = Mojo::Promise->race(@promises);
         my $new = $promise->race(@promises);

       Returns a new Mojo::Promise object that fulfills or rejects as soon as one of the passed
       Mojo::Promise objects (including the invocant) fulfills or rejects, with the value or
       reason from that promise.

   reject
         $promise = $promise->reject(@reason);

       Reject the promise with one or more rejection reasons.

   resolve
         $promise = $promise->resolve(@value);

       Resolve the promise with one or more fulfillment values.

   then
         my $new = $promise->then(sub {...});
         my $new = $promise->then(sub {...}, sub {...});
         my $new = $promise->then(undef, sub {...});

       Appends fulfillment and rejection handlers to the promise, and returns a new Mojo::Promise
       object resolving to the return value of the called handler.

         # Pass along the fulfillment value or rejection reason
         $promise->then(
           sub {
             my @value = @_;
             say "The result is $value[0]";
             return @value;
           },
           sub {
             my @reason = @_;
             warn "Something went wrong: $reason[0]";
             return @reason;
           }
         );

         # Change the fulfillment value or rejection reason
         $promise->then(
           sub {
             my @value = @_;
             return "This is good: $value[0]";
           },
           sub {
             my @reason = @_;
             return "This is bad: $reason[0]";
           }
         );

   wait
         $promise->wait;

       Start "ioloop" and stop it again once the promise has been fulfilled or rejected, does
       nothing when "ioloop" is already running.

SEE ALSO

       Mojolicious, Mojolicious::Guides, <http://mojolicious.org>.