1Future::AsyncAwait::AwaUistearblCeo(n3t)ributed Perl DocFuumteunrtea:t:iAosnyncAwait::Awaitable(3)
2
3
4

NAME

6       "Future::AsyncAwait::Awaitable" - the interface required by
7       "Future::AsyncAwait"
8

DESCRIPTION

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
18       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
22   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
28   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

CONSTRUCTORS

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
39   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
43          $f = $CLASS->AWAIT_NEW_DONE( @results )
44
45          # $f->AWAIT_IS_READY will be true
46          # $f->AWAIT_GET will return @results
47
48   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
53          $f = $CLASS->AWAIT_NEW_FAIL( $message )
54
55          # $f->AWAIT_IS_READY will be true
56          # $f->AWAIT_GET will throw $message
57

INSTANCE METHODS

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
64          $new_f = $f->AWAIT_CLONE
65
66       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
71   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
75          $f->AWAIT_DONE( @results )
76
77          # $f->AWAIT_IS_READY will now be true
78          # $f->AWAIT_GET will now return @results
79
80   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
84          $f->AWAIT_FAIL( $message )
85
86          # $f->AWAIT_IS_READY will now be true
87          # $f->AWAIT_GET will now throw $message
88
89   AWAIT_IS_READY
90       Returns true if a future is ready (successful, failed or cancelled);
91       false if still pending.
92
93          $bool = $f->AWAIT_IS_READY
94
95   AWAIT_IS_CANCELLED
96       Returns true is a future has already been cancelled; false if still
97       pending, successful or failed.
98
99          $bool = $f->AWAIT_IS_CANCELLED
100
101       An implementation that does not support cancellation can simply return
102       a constant false here:
103
104          sub AWAIT_IS_CANCELLED { 0 }
105
106   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
112          @result = $f->AWAIT_GET
113          $result = $f->AWAIT_GET
114          $f->AWAIT_GET
115
116   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
121          $f->AWAIT_ON_READY( $code )
122
123   AWAIT_CHAIN_CANCEL
124       Attach a future instance to be cancelled when another one is cancelled.
125
126          $f1->AWAIT_CHAIN_CANCEL( $f2 )
127
128       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
132       An implementation that does not support cancellation can simply ignore
133       this method.
134
135          sub AWAIT_CHAIN_CANCEL { }
136
137       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
141   AWAIT_ON_CANCEL
142       Attach a new CODE reference to be invoked when the future is cancelled.
143
144          $f->AWAIT_ON_CANCEL( $code )
145
146       An implementation that does not support cancellation can simply ignore
147       this method.
148
149          sub AWAIT_ON_CANCEL { }
150
151   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
156          @result = $f->AWAIT_WAIT
157          $result = $f->AWAIT_WAIT
158          $f->AWAIT_WAIT
159

AUTHOR

161       Paul Evans <leonerd@leonerd.org.uk>
162
163
164
165perl v5.36.0                      2022-11-22  Future::AsyncAwait::Awaitable(3)
Impressum