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>