view release on metacpan or  search on metacpan

lib/AnyEvent/Future.pm  view on Meta::CPAN

   some_async_function( ..., cb => sub { $future->done( @_ ) } );

   print Future->wait_any(
      $future,
      AnyEvent::Future->new_timeout( after => 10 ),
   )->get;

Or

   use AnyEvent::Future qw( as_future_cb );

   print Future->wait_any(
      as_future_cb {
         some_async_function( ..., cb => shift )
      },
      AnyEvent::Future->new_timeout( after => 10 ),
   )->get;

=head1 DESCRIPTION

This subclass of L<Future> integrates with L<AnyEvent>, allowing the C<await>
method to block until the future is ready. It allows C<AnyEvent>-using code to
be written that returns C<Future> instances, so that it can make full use of
C<Future>'s abilities, including L<Future::Utils>, and also that modules using
it can provide a C<Future>-based asynchronous interface of their own.

For a full description on how to use Futures, see the L<Future> documentation.

=cut

# Forward
sub as_future(&);

=head1 CONSTRUCTORS

=cut

=head2 new

   $f = AnyEvent::Future->new

Returns a new leaf future instance, which will allow waiting for its result to
be made available, using the C<await> method.

=cut

=head2 new_delay

   $f = AnyEvent::Future->new_delay( @args )

=head2 new_timeout

   $f = AnyEvent::Future->new_timeout( @args )

Returns a new leaf future instance that will become ready at the time given by
the arguments, which will be passed to the C<< AnyEvent->timer >> method.

C<new_delay> returns a future that will complete successfully at the alotted
time, whereas C<new_timeout> returns a future that will fail with the message
C<Timeout>. This is provided as a simple utility for small use-cases; for a
more find-grained control over the failure message and additional values you
may wish to use C<new_delay> combined with the C<then_fail> method:

   new_delay( after => 10 )
      ->then_fail( "The operation timed out after 10 seconds", timeout => );

=cut

sub new_delay
{
   shift;
   my %args = @_;

   as_future {
      my $f = shift;
      AnyEvent->timer( %args, cb => sub { $f->done } );
   };
}

sub new_timeout
{
   shift;
   my %args = @_;

   as_future {
      my $f = shift;
      AnyEvent->timer( %args, cb => sub { $f->fail( "Timeout" ) } );
   };
}

=head2 from_cv

   $f = AnyEvent::Future->from_cv( $cv )

Returns a new leaf future instance that will become ready when the given
L<AnyEvent::CondVar> instance is ready. The success or failure result of the
future will be the result passed to the condvar's C<send> or C<croak> method.

=cut

sub from_cv
{
   my $class = shift;
   my ( $cv ) = @_;

   my $f = $class->new;

   my $was_cb = $cv->cb;

   $cv->cb( sub {
      my ( $cv ) = @_;
      my @result;
      eval { @result = $cv->recv; 1 } and $f->done( @result ) or
         $f->fail( $@ );

      $was_cb->( @_ ) if $was_cb;
   });

   return $f;
}

=head1 METHODS

=cut

=head2 as_cv

   $cv = $f->as_cv

Returns a new C<AnyEvent::CondVar> instance that wraps the given future; it
will complete with success or failure when the future does.

Note that because C<< AnyEvent::CondVar->croak >> takes only a single string
message for the argument, any subsequent failure detail values from the future
are lost by the condvar. To capture these as well, you may wish to use an
C<on_fail> callback or the C<failure> method, to obtain them.

=cut

sub as_cv
{
   my $self = shift;

   my $cv = AnyEvent->condvar;

   $self->on_done( sub { $cv->send( @_ ) } );
   $self->on_fail( sub { $cv->croak( $_[0] ) } );