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