NAME

       Promise::XS - Fast promises in Perl

SYNOPSIS

           use Promise::XS ();

           my $deferred = Promise::XS::deferred();

           # Do one of these once you have the result of your operation:
           $deferred->resolve( 'foo', 'bar' );
           $deferred->reject( 'oh', 'no!' );

           # Give this to your caller:
           my $promise = $deferred->promise();

       The following aggregator functions are exposed:

           # Resolves with a list of arrayrefs, one per promise.
           # Rejects with the results from the first rejected promise.
           # Non-promises will be passed through as resolve values.
           my $all_p = Promise::XS::all( $promise1, $promise2, 'abc' .. );

           # Resolves/rejects with the results from the first
           # resolved or rejected promise.
           my $race_p = Promise::XS::race( $promise3, $promise4, .. );

       For compatibility with preexisting libraries, all() may also be called as collect().

       The following also exist:

           my $pre_resolved_promise = Promise::XS::resolved('already', 'done');

           my $pre_rejected_promise = Promise::XS::rejected('it’s', 'bad');

       All of "Promise::XS"’s static functions may be exported at load time, e.g., "use Promise::XS
       qw(deferred)".

DESCRIPTION

       This module exposes a Promise interface with its major parts implemented in XS for speed. It is a fork
       and refactor of AnyEvent::XSPromises. That module’s interface, a “bare-bones” subset of that from
       Promises, is retained.

STATUS

       This module is stable, well-tested, and suitable for production use.

DIFFERENCES FROM ECMASCRIPT PROMISES

       This library is built for compatibility with pre-existing Perl promise libraries. It thus exhibits some
       salient differences from how ECMAScript promises work:

       •   Neither  the  resolve()  method  of  deferred  objects nor the resolved() convenience function define
           behavior when given a promise object.

       •   The all() and race() functions accept a list of  promises,  not  a  “scalar-array-thing”  (ECMAScript
           “arrays” being what in Perl we call “array references”). So whereas in ECMAScript you do:

               Promise.all( [ promise1, promise2 ] );

           … in this library it’s:

               Promise::XS::all( $promise1, $promise2 );

       •   Promise resolutions and rejections may contain multiple values.  (But see "AVOID MULTIPLES" below.)

       See Promise::ES6 for an interface that imitates ECMAScript promises more closely.

AVOID MULTIPLES

       For  compatibility  with  preexisting  Perl promise libraries, Promise::XS allows a promise to resolve or
       reject with multiple values. This behavior, while eminently “perlish”, allows for some weird cases  where
       the  relevant  standards  don’t apply: for example, what happens if multiple promises are returned from a
       promise callback? Or even just a single promise plus extra returns?

       Promise::XS tries to help you catch such cases by throwing a warning if multiple  return  values  from  a
       callback  contain  a  promise  as the first member. For best results, though—and consistency with promise
       implementations outside Perl—resolve/reject all promises with single values.

DIFFERENCES FROM Promises ET AL.

   Empty or uninitialized rejection values
       Perl helpfully warns (under the "warnings" pragma, anyhow) when you  die(undef)  since  an  uninitialized
       value isn’t useful as an error report and likely indicates a problem in the error-handling logic.

       Promise  rejections  fulfill  the  same role in asynchronous code that exceptions do in synchronous code.
       Thus, Promise::XS mimics Perl’s behavior: if a rejection value list lacks a defined value, a  warning  is
       thrown. This can happen if the value list is either empty or contains exclusively uninitialized values.

   finally()
       This  module  implements  ECMAScript’s  finally()  interface,  which differs from that in some other Perl
       promise implementations.

       Given the following …

           my $new = $p->finally( $callback );

       •   $callback receives no arguments.

       •   If $callback returns anything but a single, rejected promise, $new has the same status as $p.

       •   If $callback throws, or if it returns a single, rejected promise, $new is rejected with the  relevant
           value(s).

ASYNC/AWAIT SUPPORT

       This module is Promise::AsyncAwait-compatible.  Once you load that module you can do nifty stuff like:

           use Promise::AsyncAwait;

           async sub do_stuff {
               return 1 + await fetch_number_p();
           }

           my $one_plus_number = await do_stuff();

       … which roughly equates to:

           sub do_stuff {
               return fetch_number_p()->then( sub { 1 + $foo } );
           }

           do_stuff->then( sub {
               $one_plus_number = shift;
           } );

       NOTE: As of this writing, DEBUGGING-enabled perls trigger assertion failures in Future::AsyncAwait (which
       underlies Promise::AsyncAwait).  If you’re not sure what that means, you probably don’t need to worry. :)

EVENT LOOPS

       By default this library uses no event loop. This is a generally usable configuration; however, it’ll be a
       bit  different  from  how  promises usually work in evented contexts (e.g., JavaScript) because callbacks
       will execute immediately rather than at the end of  the  event  loop  as  the  Promises/A+  specification
       requires.  Following  this  pattern  facilitates  use  of recursive promises without exceeding call stack
       limits.

       To achieve full Promises/A+ compliance it’s necessary to integrate with an  event  loop  interface.  This
       library supports three such interfaces:

       •   AnyEvent:

               Promise::XS::use_event('AnyEvent');

       •   IO::Async - note the need for an IO::Async::Loop instance as argument:

               Promise::XS::use_event('IO::Async', $loop_object);

       •   Mojo::IOLoop:

               Promise::XS::use_event('Mojo::IOLoop');

       Note  that  all  three  of  the  above are event loop interfaces. They aren’t event loops themselves, but
       abstractions over various event loops.  See each one’s documentation for details  about  supported  event
       loops.

MEMORY LEAK DETECTION

       Any promise created while $Promise::XS::DETECT_MEMORY_LEAKS is truthy will throw a warning if it survives
       until global destruction.

SUBCLASSING

       You  can  re-bless  a  Promise::XS::Promise  instance  into  a  different class, and then(), catch(), and
       finally() will assign their newly-created promise into that other class. (It follows that the other class
       must subclass Promise::XS::Promise.) This can be useful, e.g., for implementing mid-flight controls  like
       cancellation.

TODO

       •   all() and race() should ideally be implemented in XS.

KNOWN ISSUES

       •   Interpreter-based threads may or may not work.

       •   This  module  interacts badly with Perl’s fork() implementation on Windows. There may be a workaround
           possible, but none is implemented for now.

SEE ALSO

       Besides AnyEvent::XSPromises and Promises, you may like Promise::ES6, which mimics ECMAScript’s “Promise”
       class <https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise> as  much
       as  possible.   It  can  even  (experimentally)  use  this  module as a backend, which helps but is still
       significantly slower than using this module directly.

perl v5.38.2                                       2024-03-31                                   Promise::XS(3pm)