1# You may distribute under the terms of either the GNU General Public License 2# or the Artistic License (the same terms as Perl itself) 3# 4# (C) Paul Evans, 2013 -- leonerd@leonerd.org.uk 5 6package IO::Async::Future; 7 8use strict; 9use warnings; 10 11our $VERSION = '0.800'; 12 13use base qw( Future ); 14Future->VERSION( '0.05' ); # to respect subclassing 15 16use Carp; 17 18=head1 NAME 19 20C<IO::Async::Future> - use L<Future> with L<IO::Async> 21 22=head1 SYNOPSIS 23 24 use IO::Async::Loop; 25 26 my $loop = IO::Async::Loop->new; 27 28 my $future = $loop->new_future; 29 30 $loop->watch_time( after => 3, code => sub { $future->done( "Done" ) } ); 31 32 print $future->get, "\n"; 33 34=head1 DESCRIPTION 35 36This subclass of L<Future> stores a reference to the L<IO::Async::Loop> 37instance that created it, allowing the C<await> method to block until the 38Future is ready. These objects should not be constructed directly; instead 39the C<new_future> method on the containing Loop should be used. 40 41For a full description on how to use Futures, see the L<Future> documentation. 42 43=cut 44 45=head1 CONSTRUCTORS 46 47New C<IO::Async::Future> objects should be constructed by using the following 48methods on the C<Loop>. For more detail see the L<IO::Async::Loop> 49documentation. 50 51 $future = $loop->new_future 52 53Returns a new pending Future. 54 55 $future = $loop->delay_future( %args ) 56 57Returns a new Future that will become done at a given time. 58 59 $future = $loop->timeout_future( %args ) 60 61Returns a new Future that will become failed at a given time. 62 63=cut 64 65sub new 66{ 67 my $proto = shift; 68 my $self = $proto->SUPER::new; 69 70 if( ref $proto ) { 71 $self->{loop} = $proto->{loop}; 72 } 73 else { 74 $self->{loop} = shift; 75 } 76 77 return $self; 78} 79 80=head1 METHODS 81 82=cut 83 84=head2 loop 85 86 $loop = $future->loop 87 88Returns the underlying L<IO::Async::Loop> object. 89 90=cut 91 92sub loop 93{ 94 my $self = shift; 95 return $self->{loop}; 96} 97 98sub await 99{ 100 my $self = shift; 101 $self->{loop}->await( $self ); 102} 103 104=head2 done_later 105 106 $future->done_later( @result ) 107 108A shortcut to calling the C<done> method in a C<later> idle watch on the 109underlying Loop object. Ensures that a returned Future object is not ready 110immediately, but will wait for the next IO round. 111 112Like C<done>, returns C<$future> itself to allow easy chaining. 113 114=cut 115 116sub done_later 117{ 118 my $self = shift; 119 my @result = @_; 120 121 $self->loop->later( sub { $self->done( @result ) } ); 122 123 return $self; 124} 125 126=head2 fail_later 127 128 $future->fail_later( $exception, @details ) 129 130A shortcut to calling the C<fail> method in a C<later> idle watch on the 131underlying Loop object. Ensures that a returned Future object is not ready 132immediately, but will wait for the next IO round. 133 134Like C<fail>, returns C<$future> itself to allow easy chaining. 135 136=cut 137 138sub fail_later 139{ 140 my $self = shift; 141 my ( $exception, @details ) = @_; 142 143 $exception or croak "Expected a true exception"; 144 145 $self->loop->later( sub { $self->fail( $exception, @details ) } ); 146 147 return $self; 148} 149 150=head1 AUTHOR 151 152Paul Evans <leonerd@leonerd.org.uk> 153 154=cut 155 1560x55AA; 157