NAME

       AnyEvent::XSPromises - Another Promises library, this time implemented in XS for performance

SYNOPSIS

           use AnyEvent::XSPromises qw/deferred/;
           use AnyEvent::YACurl;

           sub do_request {
               my $request_args= @_;

               my $deferred= deferred;
               AnyEvent::YACurl->new({})->request(
                   sub {
                       my ($response, $error)= @_;
                       if ($error) { $deferred->reject($error); return; }
                       $deferred->resolve($response);
                   },
                   $request_args
               );

               return $deferred->promise;
           }

DESCRIPTION

       This library provides a Promises interface, written in XS for performance, conforming to the Promises/A+
       specification.

       Performance may not immediately seem important, but when promises are used as the building block for
       sending thousands of database queries per second from a single Perl process, those extra microseconds
       suddenly start to matter.

API

   AnyEvent::XSPromises
       deferred()
           "deferred"  is  the  main entry point for using promises. This function will return a Deferred Object
           that must be resolved or rejected after some event completes.

               sub get_perl {
                   my $d= deferred;
                   http_get("https://perl.org", sub {
                       $d->resolve(@_);
                   });
                   return $d->promise;
               }

       collect(...)
           "collect" makes a promise out of a collection of  other  promises  (thenables).  If  all  inputs  get
           resolved,  the  promise  will  be  resolved with the outputs of each. If any input gets rejected, the
           promise will be rejected with its reason.

           Because of how context (array vs scalar) works in Perl, all outputs are wrapped in an arrayref.

               collect(
                   resolved(1),
                   resolved(2)
               )->then(sub {
                   # @_ is now ( [1], [2] )
               })

       resolved(...)
           Shortcut for creating a promise that has been resolved with the given inputs

               resolved(5)->then(sub {
                   my $five= shift;
               })

       rejected(...)
           Shortcut for creating a promise that has been rejected with the given inputs. See "resolved"

   Deferred objects
       $d->promise()
           Gets a thenable promise associated to the Deferred object.

               my $d= deferred;
               ...
               return $d->promise;

       $d->resolve(...)
           Resolves the deferred object (assigns a value). All associated  promises  will  have  their  callback
           invoked in the next event loop iteration.

       $d->reject(...)
           Rejects  the  deferred object (assigns a reason for why it failed). All associated promises will have
           their callback invoked in the next event loop iteration.

       $d->is_in_progress()
           Returns true iff the "reject" or "resolve" method has not been called yet. Useful for racing multiple
           code paths to resolve/reject a single deferred object, like one would do to build a timeout.

               sub get_with_timeout {
                   my $d= deferred;
                   my $timer; $timer= AE::timer 1, 0, sub {
                       undef $timer;
                       $d->reject("Timed out") if $d->is_in_progress;
                   };

                   http_get("https://perl.org", sub {
                       my $result= shift
                       $d->resolve($result) if $d->is_in_progress;
                   });

           This method is intentionally not available on promise objects.

   Promise objects
       $p->then($on_resolve, $on_reject)
           Registers the given "on_resolve" and/or "on_reject" callback  on  the  promise,  and  returns  a  new
           promise.

       $p->catch($on_reject)
           Similar to "then", but only takes "on_reject".

       $p->finally($on_finally)
           Register  a  callback  on the promise that will be invoked once it completes. The callback is quietly
           executed but cannot change the output or status of the  promise.  Returns  a  promise  that  will  be
           resolved/rejected based on the original promise.

COMPARISON TO OTHER PROMISES LIBRARIES

       Promises
           Promises  is  a  pure-Perl  Promises  implementation that allows selecting one of multiple event loop
           backends. However, this backend is defined globally and the documentation suggests that it  would  be
           best  if  only  the  application  developer picks a backend. This means that libraries cannot know up
           front which event loop backend they have to use, and they need to support  all  event  loops  or  the
           library  would  break  if  a different event loop is chosen. This has lead library authors to mandate
           that the selected backend is AnyEvent, defying the purpose of backend selection other than for  usage
           in scripts that do not need compatibility with other code such as libraries from CPAN.

           The  library  also  trades  performance  and  resilience  for  a  few features that are not needed to
           implement the Promises/A+ specification.

           Promises from this library are compatible with ours if the backend is set to "AE" or "AnyEvent".

       AnyEvent::Promises
           AnyEvent::Promises is another pure-Perl Promises implementation. It is a lot simpler  than  Promises,
           but  comes  with  performance  implications,  and has not been very hardened against developer error.
           Since it is also based on AnyEvent, and comes with an identical "then($on_resolve, $on_reject)"  API,
           its promises are fully compatible with ours and can be freely passed around between the two libraries
           if necessary.

AUTHOR

       Tom van der Woerdt <tvdw@cpan.org>

perl v5.38.2                                       2024-03-31                          AnyEvent::XSPromises(3pm)