1Future::AsyncAwait::AwaUistearblCeo(n3t)ributed Perl DocFuumteunrtea:t:iAosnyncAwait::Awaitable(3)
2
6 "Future::AsyncAwait::Awaitable" - the interface required by
7 "Future::AsyncAwait"
8
10 This module documents the method interface required by
11 "Future::AsyncAwait" to operate on future instances returned by
12 expressions invoked by the "await" keyword, and returned by functions
13 declared by "async sub". This information is largely of relevance to
14 implementors of other module integrations, event systems, or similar.
15 It is not necessary to make regular use of the syntax provided by the
16 module when working with existing event systems.
17 The methods required by this interface are all capitalised and prefixed
19 with "AWAIT_...", ensuring they are unlikely to clash with existing
20 methods on a class which may have differing semantics.
21 Role::Tiny
23 If Role::Tiny is available, this module declares itself to be a role
24 that requires the following named methods. The role supplies no code to
25 the applied class, but can be useful for checking that you have in fact
26 implemented all of the required methods.
27 Conformance Test
29 To assist implementors of alternative future-like classes, an API
30 conformance test suite is provided by
31 Test::Future::AsyncAwait::Awaitable. You may find this useful to check
32 that your implementation is suitable.
33
35 The following methods are expected to create new future instances. They
36 make use of the class set by the prevailing "future_class" import
37 argument, if set, or default to "Future" if not.
38 AWAIT_NEW_DONE
40 Generate a new immediate future that is successful. The future will
41 already be ready and have the list of values set as its result.
42 $f = $CLASS->AWAIT_NEW_DONE( @results )
44 # $f->AWAIT_IS_READY will be true
46 # $f->AWAIT_GET will return @results
47 AWAIT_NEW_FAIL
49 Generate a new immediate future that is failed. The future will already
50 be ready and invoking the "AWAIT_GET" method will throw the given
51 exception.
52 $f = $CLASS->AWAIT_NEW_FAIL( $message )
54 # $f->AWAIT_IS_READY will be true
56 # $f->AWAIT_GET will throw $message
57
59 AWAIT_CLONE
60 Generate a new pending future of the same type as an existing one,
61 which is not modified by doing so. It will only be invoked on instances
62 that are currently pending.
63 $new_f = $f->AWAIT_CLONE
65 If the instance has any fields that are required for successful
67 operation (such as application-wide context or event system components)
68 these ought to be copied. The method should not otherwise copy any per-
69 instance state such as pending callbacks or partial results.
70 AWAIT_DONE
72 Sets the success result of an existing still-pending future. It will
73 only be invoked on future instances that are currently pending.
74 $f->AWAIT_DONE( @results )
76 # $f->AWAIT_IS_READY will now be true
78 # $f->AWAIT_GET will now return @results
79 AWAIT_FAIL
81 Sets the failure result of an existing still-pending future. It will
82 only be invoked on future instances that are currently pending.
83 $f->AWAIT_FAIL( $message )
85 # $f->AWAIT_IS_READY will now be true
87 # $f->AWAIT_GET will now throw $message
88 AWAIT_IS_READY
90 Returns true if a future is ready (successful, failed or cancelled);
91 false if still pending.
92 $bool = $f->AWAIT_IS_READY
94 AWAIT_IS_CANCELLED
96 Returns true is a future has already been cancelled; false if still
97 pending, successful or failed.
98 $bool = $f->AWAIT_IS_CANCELLED
100 An implementation that does not support cancellation can simply return
102 a constant false here:
103 sub AWAIT_IS_CANCELLED { 0 }
105 AWAIT_GET
107 Yields the result of a successful future (or just the first value if
108 called in scalar context). Throws the failure message as an exception
109 if called on a a failed one. Will not be invoked on a pending or
110 cancelled future.
111 @result = $f->AWAIT_GET
113 $result = $f->AWAIT_GET
114 $f->AWAIT_GET
115 AWAIT_ON_READY
117 Attach a new CODE reference to be invoked when the future becomes ready
118 (by success or failure). The arguments and context that $code is
119 invoked with are unspecified.
120 $f->AWAIT_ON_READY( $code )
122 AWAIT_CHAIN_CANCEL
124 Attach a future instance to be cancelled when another one is cancelled.
125 $f1->AWAIT_CHAIN_CANCEL( $f2 )
127 When $f1 is cancelled, then $f2 is cancelled. There is no link from $f2
129 back to $f1 - whenever $f2 changes state here, nothing special happens
130 to $f1.
131 An implementation that does not support cancellation can simply ignore
133 this method.
134 sub AWAIT_CHAIN_CANCEL { }
136 An older version of this API specification named this
138 "AWAIT_ON_CANCEL", but that name will be repurposed for attaching code
139 blocks in a later version.
140 AWAIT_ON_CANCEL
142 Attach a new CODE reference to be invoked when the future is cancelled.
143 $f->AWAIT_ON_CANCEL( $code )
145 An implementation that does not support cancellation can simply ignore
147 this method.
148 sub AWAIT_ON_CANCEL { }
150 AWAIT_WAIT
152 Called by the toplevel "await" expression in order to run the event
153 system and wait for the instance to be ready. It should return results
154 or throw an exception in the same manner as "AWAIT_GET".
155 @result = $f->AWAIT_WAIT
157 $result = $f->AWAIT_WAIT
158 $f->AWAIT_WAIT
159
161 Paul Evans <leonerd@leonerd.org.uk>
162perl v5.36.0 2022-11-22 Future::AsyncAwait::Awaitable(3)