view release on metacpan or  search on metacpan

lib/Async/Trampoline.pm  view on Meta::CPAN

        +-- Resolved
            +-- Error
            +-- Value

=for test

In B<Incomplete> states, the Async will be processed in the future.
At some point, the Async will transition to a completed state.

In C<async> and C<await> callbacks,
the Async will be updated to the state of the return value of that callback.

B<Completed> states are terminal.
The Asyncs are not subject to further processing.

A B<Cancelled> Async represents an aborted computation.
They have no value.
Cancellation is not an error,
but C<run_until_completion()> will die when the Async was cancelled.
You can cancel a computation via the C<async_cancel> constructor.
Cancellation is useful to abort loops,

lib/Async/Trampoline.pm  view on Meta::CPAN

=head1 CREATING ASYNCS

=head2 async

    $async = async { ... };

Create an Incomplete Async with a code block.
The callback must return an Async.
When the Async is evaluated,
this Async is updated to the state of the returned Async.

=head2 async_value

    $async = async_value @values;

Create a Value Async containing a list of values.
Use this to return values from an Async callback.

=head2 async_error

lib/Async/Trampoline.pm  view on Meta::CPAN

    $async = await [@dependencies] => sub {
        my (@results) = @_;
        # ...
        return $new_async;
    };

Wait until the C<$dependency> or C<@dependencies> Asyncs have a value,
then call the callback with the values as arguments.
If a dependency was cancelled or has an error,
the async is updated to that state.
The callback must return an Async.
Use this to chain Asyncs.
It does not directly return the values.

=head2 resolved_or

=head2 value_or

=for test
    $first_async = async { async_value };
    $alternative_async = async { async_value };
    $second_async = $alternative_async;

    $async = $first_async->resolved_or($alternative_async);
    $async = $first_async->value_or($alternative_async);

Evaluate the C<$first_async>.
Upon success, the Async is updated to the state of the C<$first_async>.
On failure, the C<$second_async> is evaluated instead.
This creates a new Async that will be updated
when the dependencies become available.

B<resolved_or> succeeds on Value or Error, and fails on Cancelled.
Use this as a fallback against cancellation.

B<value_or> only succeeds on Value, and fails on Cancelled or Error.
Use this as a try-catch to provide default values upon errors.

=head2 complete_then

=head2 resolved_then

=head2 value_then

    $async = $first_async->complete_then($second_async);
    $async = $first_async->resolved_then($second_async);
    $async = $first_async->value_then($second_async);

Evaluate the C<$first_async>.
Upon success, the C<$second_async> is evaluated.
On failure, the Async is updated to the state of the C<$first_async>.
This creates a new Async that will be updated
when the dependencies become available.

B<complete_then> always succeeds (Cancelled, Error, Value).

B<resolved_then> succeeds on Error or Value, and fails on Cancelled.

B<value_then> succeeds on Value, and fails on Cancelled or Error.
With regards to error propagation,
C<< $x->value_then($y) >>
behaves just like