.\" Automatically generated by Pod::Man 4.10 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Mojo::Promise 3pm"
.TH Mojo::Promise 3pm "2019-02-05" "perl v5.28.1" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Mojo::Promise \- Promises/A+
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\&  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;
\&      if   (!$err || $err\->{code}) { $promise\->resolve($tx) }
\&      else                         { $promise\->reject($err\->{message}) }
\&    });
\&    return $promise;
\&  }
\&
\&  # Perform non\-blocking operations sequentially
\&  get(\*(Aqhttps://mojolicious.org\*(Aq)\->then(sub {
\&    my $mojo = shift;
\&    say $mojo\->res\->code;
\&    return get(\*(Aqhttps://metacpan.org\*(Aq);
\&  })\->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(\*(Aqhttps://mojolicious.org\*(Aq);
\&  my $cpan = get(\*(Aqhttps://metacpan.org\*(Aq);
\&  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(\*(Aqhttps://mojolicious.org\*(Aq);
\&  my $cpan = get(\*(Aqhttps://metacpan.org\*(Aq);
\&  Mojo::Promise\->race($mojo, $cpan)\->then(sub {
\&    my $tx = shift;
\&    say $tx\->req\->url, \*(Aq won!\*(Aq;
\&  })\->catch(sub {
\&    my $err = shift;
\&    warn "Something went wrong: $err";
\&  })\->wait;
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Mojo::Promise is a Perl-ish implementation of
Promises/A+ <https://promisesaplus.com>.
.SH "STATES"
.IX Header "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.
.PP
A promise can be in one of three states:
.IP "pending" 2
.IX Item "pending"
Initial state, neither fulfilled nor rejected.
.IP "fulfilled" 2
.IX Item "fulfilled"
Meaning that the operation completed successfully.
.IP "rejected" 2
.IX Item "rejected"
Meaning that the operation failed.
.PP
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
\&\*(L"then\*(R" method are called.
.SH "ATTRIBUTES"
.IX Header "ATTRIBUTES"
Mojo::Promise implements the following attributes.
.SS "ioloop"
.IX Subsection "ioloop"
.Vb 2
\&  my $loop = $promise\->ioloop;
\&  $promise = $promise\->ioloop(Mojo::IOLoop\->new);
.Ve
.PP
Event loop object to control, defaults to the global Mojo::IOLoop singleton.
Note that this attribute is weakened.
.SH "METHODS"
.IX Header "METHODS"
Mojo::Promise inherits all methods from Mojo::Base and implements
the following new ones.
.SS "all"
.IX Subsection "all"
.Vb 1
\&  my $new = Mojo::Promise\->all(@promises);
.Ve
.PP
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. This method can
be useful for aggregating results of multiple promises.
.SS "catch"
.IX Subsection "catch"
.Vb 1
\&  my $new = $promise\->catch(sub {...});
.Ve
.PP
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.
.PP
.Vb 2
\&  # 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]";
\&  });
.Ve
.SS "clone"
.IX Subsection "clone"
.Vb 1
\&  my $new = $promise\->clone;
.Ve
.PP
Return a new Mojo::Promise object cloned from this promise that is still
pending.
.SS "finally"
.IX Subsection "finally"
.Vb 1
\&  my $new = $promise\->finally(sub {...});
.Ve
.PP
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.
.PP
.Vb 5
\&  # Do something on fulfillment and rejection
\&  $promise\->finally(sub {
\&    my @value_or_reason = @_;
\&    say "We are done!";
\&  });
.Ve
.SS "race"
.IX Subsection "race"
.Vb 1
\&  my $new = Mojo::Promise\->race(@promises);
.Ve
.PP
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.
.SS "reject"
.IX Subsection "reject"
.Vb 2
\&  my $new  = Mojo::Promise\->reject(@reason);
\&  $promise = $promise\->reject(@reason);
.Ve
.PP
Build rejected Mojo::Promise object or reject the promise with one or more
rejection reasons.
.PP
.Vb 2
\&  # Longer version
\&  my $promise = Mojo::Promise\->new\->reject(@reason);
.Ve
.SS "resolve"
.IX Subsection "resolve"
.Vb 2
\&  my $new  = Mojo::Promise\->resolve(@value);
\&  $promise = $promise\->resolve(@value);
.Ve
.PP
Build resolved Mojo::Promise object or resolve the promise with one or more
fulfillment values.
.PP
.Vb 2
\&  # Longer version
\&  my $promise = Mojo::Promise\->new\->resolve(@value);
.Ve
.SS "then"
.IX Subsection "then"
.Vb 3
\&  my $new = $promise\->then(sub {...});
\&  my $new = $promise\->then(sub {...}, sub {...});
\&  my $new = $promise\->then(undef, sub {...});
.Ve
.PP
Appends fulfillment and rejection handlers to the promise, and returns a new
Mojo::Promise object resolving to the return value of the called handler.
.PP
.Vb 10
\&  # 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]";
\&    }
\&  );
.Ve
.SS "timeout"
.IX Subsection "timeout"
.Vb 3
\&  my $new  = Mojo::Promise\->timeout(5 => \*(AqTimeout!\*(Aq);
\&  $promise = $promise\->timeout(5 => \*(AqTimeout!\*(Aq);
\&  $promise = $promise\->timeout(5);
.Ve
.PP
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 \f(CW\*(C`Promise timeout\*(C'\fR. Note that this
method is \s-1EXPERIMENTAL\s0 and might change without warning!
.SS "wait"
.IX Subsection "wait"
.Vb 1
\&  $promise\->wait;
.Ve
.PP
Start \*(L"ioloop\*(R" and stop it again once the promise has been fulfilled or
rejected, does nothing when \*(L"ioloop\*(R" is already running.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Mojolicious, Mojolicious::Guides, <https://mojolicious.org>.