view release on metacpan or  search on metacpan

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

#  You may distribute under the terms of either the GNU General Public License
#  or the Artistic License (the same terms as Perl itself)
#
#  (C) Paul Evans, 2014-2021 -- leonerd@leonerd.org.uk

package AnyEvent::Future 0.05;

use v5.14;
use warnings;

use base qw( Future );
Future->VERSION( '0.49' ); # ->set_udata

use Exporter 'import';
our @EXPORT_OK = qw(
   as_future
   as_future_cb
);

use AnyEvent;

=head1 NAME

C<AnyEvent::Future> - use L<Future> with L<AnyEvent>

=head1 SYNOPSIS

   use AnyEvent;
   use AnyEvent::Future;

   my $future = AnyEvent::Future->new;

   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 {