File Coverage

blib/lib/Future/AsyncAwait/Awaitable.pm
Criterion Covered Total %
statement 5 5 100.0
branch n/a
condition n/a
subroutine 2 2 100.0
pod n/a
total 7 7 100.0


line stmt bran cond sub pod time code
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, 2019-2022 -- leonerd@leonerd.org.uk
5              
6             package Future::AsyncAwait::Awaitable 0.65;
7              
8 1     1   226673 use v5.14;
  1         9  
9 1     1   6 use warnings;
  1         2  
  1         96  
10              
11             =head1 NAME
12              
13             C - the interface required by C
14              
15             =head1 DESCRIPTION
16              
17             This module documents the method interface required by C
18             to operate on future instances returned by expressions invoked by the C
19             keyword, and returned by functions declared by C. This information
20             is largely of relevance to implementors of other module integrations, event
21             systems, or similar. It is not necessary to make regular use of the syntax
22             provided by the module when working with existing event systems.
23              
24             The methods required by this interface are all capitalised and prefixed with
25             C, ensuring they are unlikely to clash with existing methods on a
26             class which may have differing semantics.
27              
28             =head2 Role::Tiny
29              
30             If L is available, this module declares itself to be a role that
31             requires the following named methods. The role supplies no code to the applied
32             class, but can be useful for checking that you have in fact implemented all of
33             the required methods.
34              
35             =head2 Conformance Test
36              
37             To assist implementors of alternative future-like classes, an API conformance
38             test suite is provided by L. You may find
39             this useful to check that your implementation is suitable.
40              
41             =cut
42              
43             if( defined eval { require Role::Tiny } ) {
44             Role::Tiny->import;
45              
46             requires( qw(
47             AWAIT_CLONE AWAIT_NEW_DONE AWAIT_NEW_FAIL
48              
49             AWAIT_DONE AWAIT_FAIL AWAIT_GET
50             AWAIT_IS_READY AWAIT_ON_READY
51             AWAIT_IS_CANCELLED AWAIT_ON_CANCEL
52              
53             AWAIT_WAIT
54             ) );
55             }
56              
57             =head1 CONSTRUCTORS
58              
59             The following methods are expected to create new future instances. They make
60             use of the class set by the prevailing C import argument, if
61             set, or default to C if not.
62              
63             =head2 AWAIT_NEW_DONE
64              
65             Generate a new immediate future that is successful. The future will already be
66             ready and have the list of values set as its result.
67              
68             $f = $CLASS->AWAIT_NEW_DONE( @results )
69              
70             # $f->AWAIT_IS_READY will be true
71             # $f->AWAIT_GET will return @results
72              
73             =head2 AWAIT_NEW_FAIL
74              
75             Generate a new immediate future that is failed. The future will already be
76             ready and invoking the L method will throw the given exception.
77              
78             $f = $CLASS->AWAIT_NEW_FAIL( $message )
79              
80             # $f->AWAIT_IS_READY will be true
81             # $f->AWAIT_GET will throw $message
82              
83             =head1 INSTANCE METHODS
84              
85             =head2 AWAIT_CLONE
86              
87             Generate a new pending future of the same type as an existing one, which is
88             not modified by doing so. It will only be invoked on instances that are
89             currently pending.
90              
91             $new_f = $f->AWAIT_CLONE
92              
93             If the instance has any fields that are required for successful operation
94             (such as application-wide context or event system components) these ought to
95             be copied. The method should not otherwise copy any per-instance state such
96             as pending callbacks or partial results.
97              
98             =head2 AWAIT_DONE
99              
100             Sets the success result of an existing still-pending future. It will only be
101             invoked on future instances that are currently pending.
102              
103             $f->AWAIT_DONE( @results )
104              
105             # $f->AWAIT_IS_READY will now be true
106             # $f->AWAIT_GET will now return @results
107              
108             =head2 AWAIT_FAIL
109              
110             Sets the failure result of an existing still-pending future. It will only be
111             invoked on future instances that are currently pending.
112              
113             $f->AWAIT_FAIL( $message )
114              
115             # $f->AWAIT_IS_READY will now be true
116             # $f->AWAIT_GET will now throw $message
117              
118             =head2 AWAIT_IS_READY
119              
120             Returns true if a future is ready (successful, failed or cancelled); false if
121             still pending.
122              
123             $bool = $f->AWAIT_IS_READY
124              
125             =head2 AWAIT_IS_CANCELLED
126              
127             Returns true is a future has already been cancelled; false if still pending,
128             successful or failed.
129              
130             $bool = $f->AWAIT_IS_CANCELLED
131              
132             An implementation that does not support cancellation can simply return a
133             constant false here:
134              
135             sub AWAIT_IS_CANCELLED { 0 }
136              
137             =head2 AWAIT_GET
138              
139             Yields the result of a successful future (or just the first value if called in
140             scalar context). Throws the failure message as an exception if called on a a
141             failed one. Will not be invoked on a pending or cancelled future.
142              
143             @result = $f->AWAIT_GET
144             $result = $f->AWAIT_GET
145             $f->AWAIT_GET
146              
147             =head2 AWAIT_ON_READY
148              
149             Attach a new CODE reference to be invoked when the future becomes ready (by
150             success or failure). The arguments and context that C<$code> is invoked with
151             are unspecified.
152              
153             $f->AWAIT_ON_READY( $code )
154              
155             =head2 AWAIT_CHAIN_CANCEL
156              
157             Attach a future instance to be cancelled when another one is cancelled.
158              
159             $f1->AWAIT_CHAIN_CANCEL( $f2 )
160              
161             When C<$f1> is cancelled, then C<$f2> is cancelled. There is no link from
162             C<$f2> back to C<$f1> - whenever C<$f2> changes state here, nothing special
163             happens to C<$f1>.
164              
165             An implementation that does not support cancellation can simply ignore this
166             method.
167              
168             sub AWAIT_CHAIN_CANCEL { }
169              
170             An older version of this API specification named this C, but
171             that name will be repurposed for attaching code blocks in a later version.
172              
173             =head2 AWAIT_ON_CANCEL
174              
175             Attach a new CODE reference to be invoked when the future is cancelled.
176              
177             $f->AWAIT_ON_CANCEL( $code )
178              
179             An implementation that does not support cancellation can simply ignore this
180             method.
181              
182             sub AWAIT_ON_CANCEL { }
183              
184             =head2 AWAIT_WAIT
185              
186             Called by the toplevel C expression in order to run the event system
187             and wait for the instance to be ready. It should return results or throw an
188             exception in the same manner as L.
189              
190             @result = $f->AWAIT_WAIT
191             $result = $f->AWAIT_WAIT
192             $f->AWAIT_WAIT
193              
194             =cut
195              
196             =head1 AUTHOR
197              
198             Paul Evans
199              
200             =cut
201              
202             0x55AA;