The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Mojolicious-8.43
River stage four • 943 direct dependents • 1041 total dependents
495 ++
/ Mojo::Promise

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_p {
    my $promise = Mojo::Promise->new;
    $ua->get(@_ => sub {
      my ($ua, $tx) = @_;
      my $err = $tx->error;
      if   (!$err || $err->{code}) { $promise->resolve($tx) }
      else                         { $promise->reject($err->{message}) }
    });
    return $promise;
  }

  # Perform non-blocking operations sequentially
  get_p('https://mojolicious.org')->then(sub {
    my $mojo = shift;
    say $mojo->res->code;
    return get('https://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_p('https://mojolicious.org');
  my $cpan = get_p('https://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_p('https://mojolicious.org');
  my $cpan = get_p('https://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+ and a superset of ES6 Promises.

STATES

A promise is an object representing the eventual completion or failure of a non-blocking operation. It allows non-blocking functions to return values, like blocking functions. But instead of immediately returning the final value, the non-blocking function returns a promise to supply the value at some point in the future.

A promise can be in one of three states:

pending

Initial state, neither fulfilled nor rejected.

fulfilled

Meaning that the operation completed successfully.

rejected

Meaning that the operation failed.

A pending promise can either be fulfilled with a value or rejected with a reason. When either happens, the associated handlers queued up by a promise's "then" method are called.

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. Note that this attribute is weakened.

METHODS

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

all

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

Returns a new Mojo::Promise object that either fulfills when all of the passed Mojo::Promise objects 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.

all_settled

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

Returns a new Mojo::Promise object that fulfills when all of the passed Mojo::Promise objects have fulfilled or rejected, with hash references that describe the outcome of each promise.

any

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

Returns a new Mojo::Promise object that fulfills as soon as one of the passed Mojo::Promise objects fulfills, with the value from that promise. If no promises fulfill, it is rejected with the reasons from the rejected promises in the same order as the passed promises. Note that this method is EXPERIMENTAL and might change without warning!

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]";
  });

clone

  my $new = $promise->clone;

Return a new Mojo::Promise object cloned from this promise that is still pending.

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 {
    say "We are done!";
  });

map

  my $new = Mojo::Promise->map(sub {...}, @items);
  my $new = Mojo::Promise->map({concurrency => 3}, sub {...}, @items);

Apply a function that returns a Mojo::Promise to each item in a list of items while optionally limiting concurrency. Returns a Mojo::Promise that collects the results in the same manner as "all". If any item's promise is rejected, any remaining items which have not yet been mapped will not be. Note that this method is EXPERIMENTAL and might change without warning!

  # Perform 3 requests at a time concurrently
  Mojo::Promise->map({concurrency => 3}, sub { $ua->get_p($_) }, @urls)
    ->then(sub{ say $_->[0]->res->dom->at('title')->text for @_ });

These options are currently available:

concurrency
  concurrency => 3

The maximum number of items that are in progress at the same time.

new

  my $promise = Mojo::Promise->new;
  my $promise = Mojo::Promise->new(sub {...});

Construct a new Mojo::Promise object.

  # Wrap a continuation-passing style API
  my $promise = Mojo::Promise->new(sub {
    my ($resolve, $reject) = @_;
    Mojo::IOLoop->timer(5 => sub {
      if (int rand 2) { $resolve->('Lucky!') }
      else            { $reject->('Unlucky!') }
    });
  });

race

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

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

reject

  my $new  = Mojo::Promise->reject(@reason);
  $promise = $promise->reject(@reason);

Build rejected Mojo::Promise object or reject the promise with one or more rejection reasons.

  # Longer version
  my $promise = Mojo::Promise->new->reject(@reason);

resolve

  my $new  = Mojo::Promise->resolve(@value);
  $promise = $promise->resolve(@value);

Build resolved Mojo::Promise object or resolve the promise with one or more fulfillment values.

  # Longer version
  my $promise = Mojo::Promise->new->resolve(@value);

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]";
    }
  );

timer

  my $new  = Mojo::Promise->timer(5 => 'Success!');
  $promise = $promise->timer(5 => 'Success!');
  $promise = $promise->timer(5);

Create a new Mojo::Promise object with a timer or attach a timer to an existing promise. The promise will be resolved after the given amount of time in seconds with or without a value. Note that this method is EXPERIMENTAL and might change without warning!

timeout

  my $new  = Mojo::Promise->timeout(5 => 'Timeout!');
  $promise = $promise->timeout(5 => 'Timeout!');
  $promise = $promise->timeout(5);

Create a new Mojo::Promise object with a timeout or attach a timeout to an existing promise. The promise will be rejected after the given amount of time in seconds with a reason, which defaults to Promise timeout. Note that this method is EXPERIMENTAL and might change without warning!

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, https://mojolicious.org.