Mojo::Promise - Promises/A+

       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.

       You can set the "MOJO_PROMISE_DEBUG" environment variable to get some  advanced  diagnostics  information
       printed to "STDERR".

         MOJO_PROMISE_DEBUG=1

       Mojo::Promise is a Perl-ish implementation of Promises/A+ <https://promisesaplus.com> and a superset of
       ES6 Promises <https://duckduckgo.com/?q=n%20Promise>.

       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.

   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 (@reason) {
           warn "Something went wrong: $reason[0]";
           return @reason;
         });

         # Change the rejection reason
         $promise->catch(sub (@reason) { "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.

         # 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 ($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 (@value) {
             say "The result is $value[0]";
             return @value;
           },
           sub (@reason) {
             warn "Something went wrong: $reason[0]";
             return @reason;
           }
         );

         # Change the fulfillment value or rejection reason
         $promise->then(
           sub (@value)  { return "This is good: $value[0]" },
           sub (@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.

   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".

   wait
         $promise->wait;

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

       Mojo::Promise - Promises/A+

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

perl v5.40.0                                       2024-12-07                                 Mojo::Promise(3pm)

       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.

         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 ($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 ($mojo) {
           say $mojo->res->code;
           return get_p('https://metacpan.org');
         })->then(sub ($cpan) {
           say $cpan->res->code;
         })->catch(sub ($err) {
           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 ($mojo, $cpan) {
           say $mojo->[0]->res->code;
           say $cpan->[0]->res->code;
         })->catch(sub ($err) {
           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 ($tx) {
           say $tx->req->url, ' won!';
         })->catch(sub ($err) {
           warn "Something went wrong: $err";
         })->wait;