File Coverage

blib/lib/Promise/XS.pm

Criterion	Covered	Total	%
statement	30	43	69.7
branch	2	10	20.0
condition			n/a
subroutine	9	13	69.2
pod	2	3	66.6
total	43	69	62.3

package Promise::XS;

use strict;
use warnings;

our $VERSION;

BEGIN {
    $VERSION = '0.20';
}

=encoding utf-8

=head1 NAME

Promise::XS - Fast promises in Perl

=head1 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, C may also be called
as C.

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 C’s static functions may be exported at load time,
e.g., C.

=head1 DESCRIPTION

=begin html



=end html

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

=head1 STATUS

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

=head1 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:

=over

=item * Neither the C method of deferred objects
nor the C convenience function define behavior when given
a promise object.

=item * The C and C 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 );

=item * Promise resolutions and rejections may contain multiple values.
(But see L below.)

=back

See L for an interface that imitates ECMAScript promises
more closely.

=head1 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 I
values.

=head1 DIFFERENCES FROM L ET AL.

=head2 Empty or uninitialized rejection values

Perl helpfully warns (under the C pragma, anyhow) when you
C 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.

=head2 C

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

Given the following …

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

=over

=item * C<$callback> receives I arguments.

=item * If C<$callback> returns anything but a single, rejected promise,
C<$new> has the same status as C<$p>.

=item * If C<$callback> throws, or if it returns a single, rejected promise,
C<$new> is rejected with the relevant value(s).

=back

=head1 ASYNC/AWAIT SUPPORT

This module is L-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;
    } );

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

=head1 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:

=over

=item * L:

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

=item * L - note the need for an L instance
as argument:

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

=item * L:

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

=back

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

=head1 MEMORY LEAK DETECTION

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

=head1 SUBCLASSING

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

=head1 TODO

=over

=item * C and C should ideally be implemented in XS.

=back

=head1 KNOWN ISSUES

=over

=item * Interpreter-based threads may or may not work.

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

=back

=cut

use Exporter 'import';
our @EXPORT_OK= qw/all collect deferred resolved rejected/;

use Promise::XS::Deferred ();
use Promise::XS::Promise ();

our $DETECT_MEMORY_LEAKS;

use constant DEFERRAL_CR => {
    AnyEvent => \&Promise::XS::Deferred::set_deferral_AnyEvent,
    'IO::Async' => \&Promise::XS::Deferred::set_deferral_IOAsync,
    'Mojo::IOLoop' => \&Promise::XS::Deferred::set_deferral_Mojo,
};

# convenience
*deferred = *Promise::XS::Deferred::create;

require XSLoader;
XSLoader::load('Promise::XS', $VERSION);

sub use_event {
    my ($name, @args) = @_;

    if (my $cr = DEFERRAL_CR()->{$name}) {
        $cr->(@args);
    }
    else {
        my @known = sort keys %{ DEFERRAL_CR() };
        die( __PACKAGE__ . ": unknown event engine: $name (must be one of: @known)" );
    }
}

# called from XS
sub _convert_to_our_promise {
    my $thenable = shift;
    my $deferred= Promise::XS::Deferred::create();
    my $called;

    local $@;
    eval {
        $thenable->then(sub {
            return if $called++;
            $deferred->resolve(@_);
        }, sub {
            return if $called++;
            $deferred->reject(@_);
        });
        1;
    } or do {
        my $error= $@;
        if (!$called++) {
            $deferred->reject($error);
        }
    };

    # This promise is purely internal, so let’s not warn
    # when its rejection is unhandled.
    $deferred->clear_unhandled_rejection();

    return $deferred->promise;
}

#----------------------------------------------------------------------
# Aggregator functions
sub all {
    return Promise::XS::Promise->all(@_);
}

sub race {
    return Promise::XS::Promise->race(@_);
}

# Compatibility with other promise interfaces.
*collect = *all;

#----------------------------------------------------------------------

=head1 SEE ALSO

Besides L and L, you may like L,
which mimics L 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.

=cut

1;