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 Cancellation
303 Cancelled futures cause a suspended "async sub" to simply stop running.
304 async sub fizz
306 {
307 await func();
308 say "This is never reached";
309 }
310 my $f = fizz();
312 $f->cancel;
313 Cancellation requests can propagate backwards into the future the
315 "async sub" is currently waiting on.
316 async sub floof
318 {
319 ...
320 await $f1;
321 }
322 my $f2 = floof();
324 $f2->cancel; # $f1 will be cancelled too
326 This behaviour is still more experimental than the rest of the logic.
328 The following should be noted:
329 • Cancellation propagation is only implemented on Perl version 5.24
331 and above. An "async sub" in an earlier perl version will still
332 stop executing if cancelled, but will not propagate the request
333 backwards into the future that the "async sub" is currently waiting
334 on. See "TODO".
335
337 By default when an "async sub" returns a result or fails immediately
338 before awaiting, it will return a new completed instance of the Future
339 class. In order to allow code that wishes to use a different class to
340 represent futures the module import method can be passed the name of a
341 class to use instead.
342 use Future::AsyncAwait future_class => "Subclass::Of::Future";
344 async sub func { ... }
346 This has the usual lexically-scoped effect, applying only to "async
348 sub"s defined within the block; others are unaffected.
349 use Future::AsyncAwait;
351 {
353 use Future::AsyncAwait future_class => "Different::Future";
354 async sub x { ... }
355 }
356 async sub y { ... } # returns a regular Future
358 This will only affect immediate results. If the "await" keyword has to
360 suspend the function and create a new pending future, it will do this
361 by using the prototype constructor on the future it itself is waiting
362 on, and the usual subclass-respecting semantics of "new" in Future will
363 remain in effect there. As such it is not usually necessary to use this
364 feature just for wrapping event system modules or other similar
365 situations.
366 Such an alternative subclass should implement the API documented by
368 Future::AsyncAwait::Awaitable.
369
371 Syntax::Keyword::Try
372 As of Future::AsyncAwait version 0.10 and Syntax::Keyword::Try version
373 0.07, cross-module integration tests assert that basic "try/catch"
374 blocks inside an "async sub" work correctly, including those that
375 attempt to "return" from inside "try".
376 use Future::AsyncAwait;
378 use Syntax::Keyword::Try;
379 async sub attempt
381 {
382 try {
383 await func();
384 return "success";
385 }
386 catch {
387 return "failed";
388 }
389 }
390 As of Future::AsyncAwait version 0.50, "finally" blocks are invoked
392 even during cancellation.
393 Syntax::Keyword::Dynamically
395 As of Future::AsyncAwait version 0.32, cross-module integration tests
396 assert that the "dynamically" correctly works across an "await"
397 boundary.
398 use Future::AsyncAwait;
400 use Syntax::Keyword::Dynamically;
401 our $var;
403 async sub trial
405 {
406 dynamically $var = "value";
407 await func();
409 say "Var is still $var";
411 }
412 Syntax::Keyword::Defer
414 As of Future::AsyncAwait version 0.50, "defer" blocks are invoked even
415 during cancellation.
416 use Future::AsyncAwait;
418 use Syntax::Keyword::Defer;
419 async sub perhaps
421 {
422 defer { say "Cleaning up now" }
423 await $f1;
424 }
425 my $fouter = perhaps();
427 $fouter->cancel;
428 Object::Pad
430 As of Future::AsyncAwait version 0.38 and Object::Pad version 0.15,
431 both modules now use XS::Parse::Sublike to parse blocks of code.
432 Because of this the two modules can operate together and allow class
433 methods to be written as async subs which await expressions:
434 use Future::AsyncAwait;
436 use Object::Pad;
437 class Example
439 {
440 async method perform($block)
441 {
442 say "$self is performing code";
443 await $block->();
444 say "code finished";
445 }
446 }
447
449 • "Awaiting The Future" - TPC in Amsterdam 2017
450 <https://www.youtube.com/watch?v=Xf7rStpNaT0> (slides)
452 <https://docs.google.com/presentation/d/13x5l8Rohv_RjWJ0OTvbsWMXKoNEWREZ4GfKHVykqUvc/edit#slide=id.p>
453
455 • Suspend and resume with some consideration for the savestack; i.e.
456 the area used to implement "local" and similar. While in general
457 "local" support has awkward questions about semantics, there are
458 certain situations and cases where internally-implied localisation
459 of variables would still be useful and can be supported without the
460 semantic ambiguities of generic "local".
461 our $DEBUG = 0;
463 async sub quark
465 {
466 local $DEBUG = 1;
467 await func();
468 }
469 Since "foreach" loops on non-lexical iterator variables (usually
471 the $_ global variable) effectively imply a "local"-like behaviour,
472 these are also disallowed.
473 async sub splurt
475 {
476 foreach ( LIST ) {
477 await ...
478 }
479 }
480 Some notes on what makes the problem hard can be found at
482 <https://rt.cpan.org/Ticket/Display.html?id=122793>
484 • Currently this module requires perl version 5.16 or later.
486 Additionally, threaded builds of perl earlier than 5.22 are not
487 supported.
488 <https://rt.cpan.org/Ticket/Display.html?id=122252>
490 <https://rt.cpan.org/Ticket/Display.html?id=124351>
492 • Implement cancel back-propagation for Perl versions earlier than
494 5.24. Currently this does not work due to some as-yet-unknown
495 effects that installing the back-propagation has, causing future
496 instances to be reclaimed too early.
497 <https://rt.cpan.org/Ticket/Display.html?id=129202>
499
501 This is not a complete list of all known issues, but rather a summary
502 of the most notable ones that currently prevent the module from working
503 correctly in a variety of situations. For a complete list of known
504 bugs, see the RT queue at
505 <https://rt.cpan.org/Dist/Display.html?Name=Future-AsyncAwait>.
506 • "await" inside "map" or "grep" blocks does not work. This is due to
508 the difficulty of detecting the map or grep context from internal
509 perl state at suspend time, sufficient to be able to restore it
510 again when resuming.
511 <https://rt.cpan.org/Ticket/Display.html?id=129748>
513 As a workaround, consider converting a "map" expression to the
515 equivalent form using "push" onto an accumulator array with a
516 "foreach" loop:
517 my @results = map { await func($_) } ITEMS;
519 becomes
521 my @results;
523 foreach my $item ( ITEMS ) {
524 push @results, await func($item);
525 }
526 with a similar transformation for "grep" expressions.
528 Alternatively, consider using the "fmap*" family of functions from
530 Future::Utils to provide a concurrent version of the same code,
531 which can keep multiple items running concurrently:
532 use Future::Utils qw( fmap );
534 my @results = await fmap { func( shift ) }
536 foreach => [ ITEMS ],
537 concurrent => 5;
538
540 With thanks to "Zefram", "ilmari" and others from "irc.perl.org/#p5p"
541 for assisting with trickier bits of XS logic.
542 Thanks to "genio" for project management and actually reminding me to
544 write some code.
545 Thanks to The Perl Foundation for sponsoring me to continue working on
547 the implementation.
548
550 Paul Evans <leonerd@leonerd.org.uk>
551perl v5.34.0 2021-10-27 Future::AsyncAwait(3)