view release on metacpan or  search on metacpan

lib/Future.pm  view on Meta::CPAN

*resolve = sub { shift->done( @_ ) };

# TODO: For efficiency we can implement better versions of these as individual
#  methods know which case is being invoked
*AWAIT_NEW_DONE = *AWAIT_DONE = sub { shift->done( @_ ) };

=head2 fail

   $future->fail( $exception, $category, @details );

Marks that the leaf future has failed, and provides an exception value. This
exception will be thrown by the C<get> method if called. 

The exception must evaluate as a true value; false exceptions are not allowed.
A failure category name and other further details may be provided that will be
returned by the C<failure> method in list context.

If the future is already cancelled, this request is ignored. If the future is
already complete with a result or a failure, an exception is thrown.

If passed a L<Future::Exception> instance (i.e. an object previously thrown by
the C<get>), the additional details will be preserved. This allows the
additional details to be transparently preserved by such code as

   ...
   catch {
      return Future->fail($@);
   }

I<Since version 0.45:> this method is also available under the name C<reject>.

=cut

*reject = sub { shift->fail( @_ ) };

# TODO: For efficiency we can implement better versions of these as individual
#  methods know which case is being invoked
*AWAIT_NEW_FAIL = *AWAIT_FAIL = sub { shift->fail( @_ ) };

=head2 die

   $future->die( $message, $category, @details );

I<Since version 0.09.>

A convenient wrapper around C<fail>. If the exception is a non-reference that
does not end in a linefeed, its value will be extended by the file and line
number of the caller, similar to the logic that C<die> uses.

Returns the C<$future>.

=cut

sub die :method
{
   my $self = shift;
   my ( $exception, @more ) = @_;

   if( !ref $exception and $exception !~ m/\n$/ ) {
      $exception .= sprintf " at %s line %d\n", (caller)[1,2];
   }

   $self->fail( $exception, @more );
}

=head2 on_cancel

   $future->on_cancel( $code );

If the future is not yet ready, adds a callback to be invoked if the future is
cancelled by the C<cancel> method. If the future is already ready the method
is ignored.

If the future is later cancelled, the callbacks will be invoked in the reverse
order to that in which they were registered.

   $on_cancel->( $future );

If passed another C<Future> instance, the passed instance will be cancelled
when the original future is cancelled. In this case, the reference is only
strongly held while the target future remains pending. If it becomes ready,
then there is no point trying to cancel it, and so it is removed from the
originating future's cancellation list.

=cut

*AWAIT_ON_CANCEL = *AWAIT_CHAIN_CANCEL = sub { shift->on_cancel( @_ ) };

=head1 USER METHODS

These methods would primarily be used by users of asynchronous interfaces, on
objects returned by such an interface.

=cut

=head2 on_ready

   $future->on_ready( $code );

If the future is not yet ready, adds a callback to be invoked when the future
is ready. If the future is already ready, invokes it immediately.

In either case, the callback will be passed the future object itself. The
invoked code can then obtain the list of results by calling the C<get> method.

   $on_ready->( $future );

If passed another C<Future> instance, the passed instance will have its
C<done>, C<fail> or C<cancel> methods invoked when the original future
completes successfully, fails, or is cancelled respectively.

Returns the C<$future>.

=cut

*AWAIT_ON_READY = sub { shift->on_ready( @_ ) };

=head2 result

   @result = $future->result;