1Future::AsyncAwait(3) User Contributed Perl DocumentationFuture::AsyncAwait(3)
2
6 "Future::AsyncAwait" - deferred subroutine syntax for futures
7
9 use v5.14;
10 use Future::AsyncAwait;
11 async sub do_a_thing
13 {
14 my $first = await do_first_thing();
15 my $second = await do_second_thing();
17 return combine_things( $first, $second );
19 }
20 do_a_thing()->get;
22
24 This module provides syntax for deferring and resuming subroutines
25 while waiting for Futures to complete. This syntax aims to make code
26 that performs asynchronous operations using futures look neater and
27 more expressive than simply using "then" chaining and other techniques
28 on the futures themselves. It is also a similar syntax used by a number
29 of other languages; notably C# 5, EcmaScript 6, Python 3, Dart, Rust,
30 C++20.
31 This module is still under active development. While it now seems
33 relatively stable enough for most use-cases and has received a lot of
34 "battle-testing" in a wide variety of scenarios, there may still be the
35 occasional case of memory leak left in it, especially if still-pending
36 futures are abandoned.
37 The new syntax takes the form of two new keywords, "async" and "await".
39 "async"
41 The "async" keyword should appear just before the "sub" keyword that
42 declares a new function. When present, this marks that the function
43 performs its work in a potentially asynchronous fashion. This has two
44 effects: it permits the body of the function to use the "await"
45 expression, and it wraps the return value of the function in a Future
46 instance.
47 async sub myfunc
49 {
50 return 123;
51 }
52 my $f = myfunc();
54 my $result = $f->get;
55 As well as named function declarations it is also supported on
57 anonymous function expressions.
58 my $code = async sub { return 456 };
60 my $f = $code->();
61 my $result = $f->get;
62 This "async"-declared function always returns a "Future" instance when
64 invoked. The returned future instance will eventually complete when the
65 function returns, either by the "return" keyword or by falling off the
66 end; the result of the future will be the return value from the
67 function's code. Alternatively, if the function body throws an
68 exception, this will cause the returned future to fail.
69 If the final expression in the body of the function returns a "Future",
71 don't forget to "await" it rather than simply returning it as it is, or
72 else this return value will become double-wrapped - almost certainly
73 not what you wanted.
74 async sub otherfunc { ... }
76 async sub myfunc
78 {
79 ...
80 return await otherfunc();
81 }
82 "await"
84 The "await" keyword forms an expression which takes a "Future" instance
85 as an operand and yields the eventual result of it. Superficially it
86 can be thought of similar to invoking the "get" method on the future.
87 my $result = await $f;
89 my $result = $f->get;
91 However, the key difference (and indeed the entire reason for being a
93 new syntax keyword) is the behaviour when the future is still pending
94 and is not yet complete. Whereas the simple "get" method would block
95 until the future is complete, the "await" keyword causes its entire
96 containing function to become suspended, making it return a new
97 (pending) future instance. It waits in this state until the future it
98 was waiting on completes, at which point it wakes up and resumes
99 execution from the point of the "await" expression. When the now-
100 resumed function eventually finishes (either by returning a value or
101 throwing an exception), this value is set as the result of the future
102 it had returned earlier.
103 "await" provides scalar context to its controlling expression.
105 async sub func {
107 # this function is invoked in scalar context
108 }
109 await func();
111 Because the "await" keyword may cause its containing function to
113 suspend early, returning a pending future instance, it is only allowed
114 inside "async"-marked subs.
115 The converse is not true; just because a function is marked as "async"
117 does not require it to make use of the "await" expression. It is still
118 useful to turn the result of that function into a future, entirely
119 without "await"ing on any itself.
120 Any function that doesn't actually await anything, and just returns
122 immediate futures can be neatened by this module too.
123 Instead of writing
125 sub imm
127 {
128 ...
129 return Future->done( @result );
130 }
131 you can now simply write
133 async sub imm
135 {
136 ...
137 return @result;
138 }
139 with the added side-benefit that any exceptions thrown by the elided
141 code will be turned into an immediate-failed "Future" rather than
142 making the call itself propagate the exception, which is usually what
143 you wanted when dealing with futures.
144 await (toplevel)
146 Since version 0.47.
147 An "await" expression is also permitted directly in the main script at
149 toplevel, outside of "async sub". This is implemented by simply
150 invoking the "get" method on the future value. Thus, the following two
151 lines are directly equivalent:
152 await afunc();
154 afunc()->get;
155 This is provided as a syntax convenience for unit tests, toplevel
157 scripts, and so on. It allows code to be written in a style that can be
158 easily moved into an "async sub", and avoids encouraging "bad habits"
159 of invoking the "get" method directly.
160 "CANCEL"
162 Experimental. Since version 0.44.
163 The "CANCEL" keyword declares a block of code which will be run in the
165 event that the future returned by the "async sub" is cancelled.
166 async sub f
168 {
169 CANCEL { warn "This task was cancelled"; }
170 await ...
172 }
173 f()->cancel;
175 A "CANCEL" block is a self-contained syntax element, similar to perl
177 constructions like "BEGIN", and does not need a terminating semicolon.
178 When a "CANCEL" block is encountered during execution of the "async
180 sub", the code in its block is stored for the case that the returned
181 future is cancelled. Each will take effect as it is executed, possibly
182 multiple times if it appears inside a loop, or not at all if it appears
183 conditionally in a branch that was not executed.
184 async sub g
186 {
187 if(0) {
188 CANCEL { warn "This does not happen"; }
189 }
190 foreach my $x ( 1..3 ) {
192 CANCEL { warn "This happens for x=$x"; }
193 }
194 await ...
196 }
197 g()->cancel;
199 "CANCEL" blocks are only invoked if a still-pending future is
201 cancelled. They are discarded without being executed if the function
202 finishes; either successfully or if it throws an exception.
203
205 Some of the features of this module are currently marked as
206 experimental. They will provoke warnings in the "experimental"
207 category, unless silenced.
208 You can silence this with "no warnings 'experimental'" but then that
210 will silence every experimental warning, which may hide others
211 unintentionally. For a more fine-grained approach you can instead use
212 the import line for this module to only silence this module's warnings
213 selectively:
214 use Future::AsyncAwait qw( :experimental(cancel) );
216 use Future::AsyncAwait qw( :experimental ); # all of the above
218
220 Most cases involving awaiting on still-pending futures should work
221 fine:
222 async sub foo
224 {
225 my ( $f ) = @_;
226 BEFORE();
228 await $f;
229 AFTER();
230 }
231 async sub bar
233 {
234 my ( $f ) = @_;
235 return 1 + await( $f ) + 3;
237 }
238 async sub splot
240 {
241 while( COND ) {
242 await func();
243 }
244 }
245 async sub wibble
247 {
248 if( COND ) {
249 await func();
250 }
251 }
252 async sub wobble
254 {
255 foreach my $var ( THINGs ) {
256 await func();
257 }
258 }
259 async sub wubble
261 {
262 # on perl 5.35.5 and above
263 foreach my ($k, $v) ( KVTHINGs ) {
264 await func();
265 }
266 }
267 async sub quux
269 {
270 my $x = do {
271 await func();
272 };
273 }
274 async sub splat
276 {
277 eval {
278 await func();
279 };
280 }
281 Plain lexical variables are preserved across an "await" deferral:
283 async sub quux
285 {
286 my $message = "Hello, world\n";
287 await func();
288 print $message;
289 }
290 On perl versions 5.26 and later "async sub" syntax supports the
292 "signatures" feature if it is enabled:
293 use v5.26;
295 use feature 'signatures';
296 async sub quart($x, $y)
298 {
299 ...
300 }
301 Since version 0.55 any exceptions thrown by signature validation
303 (because of too few or too many arguments being passed) are thrown
304 synchronously, and do not result in a failed Future instance.
305 Cancellation
307 Cancelled futures cause a suspended "async sub" to simply stop running.
308 async sub fizz
310 {
311 await func();
312 say "This is never reached";
313 }
314 my $f = fizz();
316 $f->cancel;
317 Cancellation requests can propagate backwards into the future the
319 "async sub" is currently waiting on.
320 async sub floof
322 {
323 ...
324 await $f1;
325 }
326 my $f2 = floof();
328 $f2->cancel; # $f1 will be cancelled too
330 This behaviour is still more experimental than the rest of the logic.
332 The following should be noted:
333 • Cancellation propagation is only implemented on Perl version 5.24
335 and above. An "async sub" in an earlier perl version will still
336 stop executing if cancelled, but will not propagate the request
337 backwards into the future that the "async sub" is currently waiting
338 on. See "TODO".
339
341 By default when an "async sub" returns a result or fails immediately
342 before awaiting, it will return a new completed instance of the Future
343 class. In order to allow code that wishes to use a different class to
344 represent futures the module import method can be passed the name of a
345 class to use instead.
346 use Future::AsyncAwait future_class => "Subclass::Of::Future";
348 async sub func { ... }
350 This has the usual lexically-scoped effect, applying only to "async
352 sub"s defined within the block; others are unaffected.
353 use Future::AsyncAwait;
355 {
357 use Future::AsyncAwait future_class => "Different::Future";
358 async sub x { ... }
359 }
360 async sub y { ... } # returns a regular Future
362 This will only affect immediate results. If the "await" keyword has to
364 suspend the function and create a new pending future, it will do this
365 by using the prototype constructor on the future it itself is waiting
366 on, and the usual subclass-respecting semantics of "new" in Future will
367 remain in effect there. As such it is not usually necessary to use this
368 feature just for wrapping event system modules or other similar
369 situations.
370 Such an alternative subclass should implement the API documented by
372 Future::AsyncAwait::Awaitable.
373
375 Syntax::Keyword::Try
376 As of Future::AsyncAwait version 0.10 and Syntax::Keyword::Try version
377 0.07, cross-module integration tests assert that basic "try/catch"
378 blocks inside an "async sub" work correctly, including those that
379 attempt to "return" from inside "try".
380 use Future::AsyncAwait;
382 use Syntax::Keyword::Try;
383 async sub attempt
385 {
386 try {
387 await func();
388 return "success";
389 }
390 catch {
391 return "failed";
392 }
393 }
394 As of Future::AsyncAwait version 0.50, "finally" blocks are invoked
396 even during cancellation.
397 Syntax::Keyword::Dynamically
399 As of Future::AsyncAwait version 0.32, cross-module integration tests
400 assert that the "dynamically" correctly works across an "await"
401 boundary.
402 use Future::AsyncAwait;
404 use Syntax::Keyword::Dynamically;
405 our $var;
407 async sub trial
409 {
410 dynamically $var = "value";
411 await func();
413 say "Var is still $var";
415 }
416 Syntax::Keyword::Defer
418 As of Future::AsyncAwait version 0.50, "defer" blocks are invoked even
419 during cancellation.
420 use Future::AsyncAwait;
422 use Syntax::Keyword::Defer;
423 async sub perhaps
425 {
426 defer { say "Cleaning up now" }
427 await $f1;
428 }
429 my $fouter = perhaps();
431 $fouter->cancel;
432 Object::Pad
434 As of Future::AsyncAwait version 0.38 and Object::Pad version 0.15,
435 both modules now use XS::Parse::Sublike to parse blocks of code.
436 Because of this the two modules can operate together and allow class
437 methods to be written as async subs which await expressions:
438 use Future::AsyncAwait;
440 use Object::Pad;
441 class Example
443 {
444 async method perform($block)
445 {
446 say "$self is performing code";
447 await $block->();
448 say "code finished";
449 }
450 }
451 Syntax::Keyword::MultiSub
453 As of Future::AsyncAwait version 0.55 and Syntax::Keyword::MultiSub
454 version 0.02 a cross-module integration test asserts that the "multi"
455 modifier can be applied to "async sub".
456 use Future::AsyncAwait;
458 use Syntax::Keyword::MultiSub;
459 async multi sub f () { return "nothing"; }
461 async multi sub f ($key) { return await get_thing($key); }
462
464 • "Awaiting The Future" - TPC in Amsterdam 2017
465 <https://www.youtube.com/watch?v=Xf7rStpNaT0> (slides)
467 <https://docs.google.com/presentation/d/13x5l8Rohv_RjWJ0OTvbsWMXKoNEWREZ4GfKHVykqUvc/edit#slide=id.p>
468
470 • Suspend and resume with some consideration for the savestack; i.e.
471 the area used to implement "local" and similar. While in general
472 "local" support has awkward questions about semantics, there are
473 certain situations and cases where internally-implied localisation
474 of variables would still be useful and can be supported without the
475 semantic ambiguities of generic "local".
476 our $DEBUG = 0;
478 async sub quark
480 {
481 local $DEBUG = 1;
482 await func();
483 }
484 Since "foreach" loops on non-lexical iterator variables (usually
486 the $_ global variable) effectively imply a "local"-like behaviour,
487 these are also disallowed.
488 async sub splurt
490 {
491 foreach ( LIST ) {
492 await ...
493 }
494 }
495 Some notes on what makes the problem hard can be found at
497 <https://rt.cpan.org/Ticket/Display.html?id=122793>
499 • Currently this module requires perl version 5.16 or later.
501 Additionally, threaded builds of perl earlier than 5.22 are not
502 supported.
503 <https://rt.cpan.org/Ticket/Display.html?id=122252>
505 <https://rt.cpan.org/Ticket/Display.html?id=124351>
507 • Implement cancel back-propagation for Perl versions earlier than
509 5.24. Currently this does not work due to some as-yet-unknown
510 effects that installing the back-propagation has, causing future
511 instances to be reclaimed too early.
512 <https://rt.cpan.org/Ticket/Display.html?id=129202>
514
516 This is not a complete list of all known issues, but rather a summary
517 of the most notable ones that currently prevent the module from working
518 correctly in a variety of situations. For a complete list of known
519 bugs, see the RT queue at
520 <https://rt.cpan.org/Dist/Display.html?Name=Future-AsyncAwait>.
521 • "await" inside "map" or "grep" blocks does not work. This is due to
523 the difficulty of detecting the map or grep context from internal
524 perl state at suspend time, sufficient to be able to restore it
525 again when resuming.
526 <https://rt.cpan.org/Ticket/Display.html?id=129748>
528 As a workaround, consider converting a "map" expression to the
530 equivalent form using "push" onto an accumulator array with a
531 "foreach" loop:
532 my @results = map { await func($_) } ITEMS;
534 becomes
536 my @results;
538 foreach my $item ( ITEMS ) {
539 push @results, await func($item);
540 }
541 with a similar transformation for "grep" expressions.
543 Alternatively, consider using the "fmap*" family of functions from
545 Future::Utils to provide a concurrent version of the same code,
546 which can keep multiple items running concurrently:
547 use Future::Utils qw( fmap );
549 my @results = await fmap { func( shift ) }
551 foreach => [ ITEMS ],
552 concurrent => 5;
553
555 With thanks to "Zefram", "ilmari" and others from "irc.perl.org/#p5p"
556 for assisting with trickier bits of XS logic.
557 Thanks to "genio" for project management and actually reminding me to
559 write some code.
560 Thanks to The Perl Foundation for sponsoring me to continue working on
562 the implementation.
563
565 Paul Evans <leonerd@leonerd.org.uk>
566perl v5.36.0 2022-11-22 Future::AsyncAwait(3)