Future::AsyncAwait(3pm)

1Future::AsyncAwait(3) User Contributed Perl DocumentationFuture::AsyncAwait(3)
2
3
4

NAME

6       "Future::AsyncAwait" - deferred subroutine syntax for futures
7

SYNOPSIS

9          use v5.14;
10          use Future::AsyncAwait;
11
12          async sub do_a_thing
13          {
14             my $first = await do_first_thing();
15
16             my $second = await do_second_thing();
17
18             return combine_things( $first, $second );
19          }
20
21          do_a_thing()->get;
22

DESCRIPTION

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 is
30       considering adding it.
31
32       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
38       The new syntax takes the form of two new keywords, "async" and "await".
39
40   "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
48          async sub myfunc
49          {
50             return 123;
51          }
52
53          my $f = myfunc();
54          my $result = $f->get;
55
56       As well as named function declarations it is also supported on
57       anonymous function expressions.
58
59          my $code = async sub { return 456 };
60          my $f = $code->();
61          my $result = $f->get;
62
63       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
70       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
75          async sub otherfunc { ... }
76
77          async sub myfunc
78          {
79             ...
80             return await otherfunc();
81          }
82
83   "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
88          my $result = await $f;
89
90          my $result = $f->get;
91
92       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
104       "await" provides scalar context to its controlling expression.
105
106          async sub func {
107             # this function is invoked in scalar context
108          }
109
110          await func();
111
112       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
116       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
121       Any function that doesn't actually await anything, and just returns
122       immediate futures can be neatened by this module too.
123
124       Instead of writing
125
126          sub imm
127          {
128             ...
129             return Future->done( @result );
130          }
131
132       you can now simply write
133
134          async sub imm
135          {
136             ...
137             return @result;
138          }
139
140       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
145   await (toplevel)
146       Since version 0.47.
147
148       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
153          await afunc();
154          afunc()->get;
155
156       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
161   "CANCEL"
162       Experimental. Since version 0.44.
163
164       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
167          async sub f
168          {
169             CANCEL { warn "This task was cancelled"; }
170
171             await ...
172          }
173
174          f()->cancel;
175
176       A "CANCEL" block is a self-contained syntax element, similar to perl
177       constructions like "BEGIN", and does not need a terminating semicolon.
178
179       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
185          async sub g
186          {
187             if(0) {
188                CANCEL { warn "This does not happen"; }
189             }
190
191             foreach my $x ( 1..3 ) {
192                CANCEL { warn "This happens for x=$x"; }
193             }
194
195             await ...
196          }
197
198          g()->cancel;
199
200       "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

Experimental Features

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
209       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
215          use Future::AsyncAwait qw( :experimental(cancel) );
216
217          use Future::AsyncAwait qw( :experimental );  # all of the above
218

SUPPORTED USES

220       Most cases involving awaiting on still-pending futures should work
221       fine:
222
223          async sub foo
224          {
225             my ( $f ) = @_;
226
227             BEFORE();
228             await $f;
229             AFTER();
230          }
231
232          async sub bar
233          {
234             my ( $f ) = @_;
235
236             return 1 + await( $f ) + 3;
237          }
238
239          async sub splot
240          {
241             while( COND ) {
242                await func();
243             }
244          }
245
246          async sub wibble
247          {
248             if( COND ) {
249                await func();
250             }
251          }
252
253          async sub wobble
254          {
255             foreach my $var ( THINGs ) {
256                await func();
257             }
258          }
259
260          async sub quux
261          {
262             my $x = do {
263                await func();
264             };
265          }
266
267          async sub splat
268          {
269             eval {
270                await func();
271             };
272          }
273
274       Plain lexical variables are preserved across an "await" deferral:
275
276          async sub quux
277          {
278             my $message = "Hello, world\n";
279             await func();
280             print $message;
281          }
282
283       On perl versions 5.26 and later "async sub" syntax supports the
284       "signatures" feature if it is enabled:
285
286          use v5.26;
287          use feature 'signatures';
288
289          async sub quart($x, $y)
290          {
291             ...
292          }
293
294   Cancellation
295       Cancelled futures cause a suspended "async sub" to simply stop running.
296
297          async sub fizz
298          {
299             await func();
300             say "This is never reached";
301          }
302
303          my $f = fizz();
304          $f->cancel;
305
306       Cancellation requests can propagate backwards into the future the
307       "async sub" is currently waiting on.
308
309          async sub floof
310          {
311             ...
312             await $f1;
313          }
314
315          my $f2 = floof();
316
317          $f2->cancel;  # $f1 will be cancelled too
318
319       This behaviour is still more experimental than the rest of the logic.
320       The following should be noted:
321
322       ·   There is currently no way to perform the equivalent of "on_cancel"
323           in Future to add a cancellation callback to a future chain.
324
325       ·   Cancellation propagation is only implemented on Perl version 5.24
326           and above.  An "async sub" in an earlier perl version will still
327           stop executing if cancelled, but will not propagate the request
328           backwards into the future that the "async sub" is currently waiting
329           on. See "TODO".
330

SUBCLASSING Future

332       By default when an "async sub" returns a result or fails immediately
333       before awaiting, it will return a new completed instance of the Future
334       class. In order to allow code that wishes to use a different class to
335       represent futures the module import method can be passed the name of a
336       class to use instead.
337
338          use Future::AsyncAwait future_class => "Subclass::Of::Future";
339
340          async sub func { ... }
341
342       This has the usual lexically-scoped effect, applying only to "async
343       sub"s defined within the block; others are unaffected.
344
345          use Future::AsyncAwait;
346
347          {
348             use Future::AsyncAwait future_class => "Different::Future";
349             async sub x { ... }
350          }
351
352          async sub y { ... }  # returns a regular Future
353
354       This will only affect immediate results. If the "await" keyword has to
355       suspend the function and create a new pending future, it will do this
356       by using the prototype constructor on the future it itself is waiting
357       on, and the usual subclass-respecting semantics of "new" in Future will
358       remain in effect there. As such it is not usually necessary to use this
359       feature just for wrapping event system modules or other similar
360       situations.
361
362       Such an alternative subclass should implement the API documented by
363       Future::AsyncAwait::Awaitable.
364

WITH OTHER MODULES

366   Syntax::Keyword::Try
367       As of Future::AsyncAwait version 0.10 and Syntax::Keyword::Try version
368       0.07, cross-module integration tests assert that basic "try/catch"
369       blocks inside an "async sub" work correctly, including those that
370       attempt to "return" from inside "try".
371
372          use Future::AsyncAwait;
373          use Syntax::Keyword::Try;
374
375          async sub attempt
376          {
377             try {
378                await func();
379                return "success";
380             }
381             catch {
382                return "failed";
383             }
384          }
385
386   Syntax::Keyword::Dynamically
387       As of Future::AsyncAwait version 0.32, cross-module integration tests
388       assert that the "dynamically" correctly works across an "await"
389       boundary.
390
391          use Future::AsyncAwait;
392          use Syntax::Keyword::Dynamically;
393
394          our $var;
395
396          async sub trial
397          {
398             dynamically $var = "value";
399
400             await func();
401
402             say "Var is still $var";
403          }
404
405   Object::Pad
406       As of Future::AsyncAwait version 0.38 and Object::Pad version 0.15,
407       both modules now use XS::Parse::Sublike to parse blocks of code.
408       Because of this the two modules can operate together and allow class
409       methods to be written as async subs which await expressions:
410
411          use Future::AsyncAwait;
412          use Object::Pad;
413
414          class Example
415          {
416             async method perform($block)
417             {
418                say "$self is performing code";
419                await $block->();
420                say "code finished";
421             }
422          }
423

TODO

431       ·   Suspend and resume with some consideration for the savestack; i.e.
432           the area used to implement "local" and similar. While in general
433           "local" support has awkward questions about semantics, there are
434           certain situations and cases where internally-implied localisation
435           of variables would still be useful and can be supported without the
436           semantic ambiguities of generic "local".
437
438              our $DEBUG = 0;
439
440              async sub quark
441              {
442                 local $DEBUG = 1;
443                 await func();
444              }
445
446           Since "foreach" loops on non-lexical iterator variables (usually
447           the $_ global variable) effectively imply a "local"-like behaviour,
448           these are also disallowed.
449
450              async sub splurt
451              {
452                 foreach ( LIST ) {
453                    await ...
454                 }
455              }
456
457           Some notes on what makes the problem hard can be found at
458
459           <https://rt.cpan.org/Ticket/Display.html?id=122793>
460
461       ·   Currently this module requires perl version 5.16 or later.
462           Additionally, threaded builds of perl earlier than 5.22 are not
463           supported.
464
465           <https://rt.cpan.org/Ticket/Display.html?id=122252>
466
467           <https://rt.cpan.org/Ticket/Display.html?id=124351>
468
469       ·   Implement cancel back-propagation for Perl versions earlier than
470           5.24.  Currently this does not work due to some as-yet-unknown
471           effects that installing the back-propagation has, causing future
472           instances to be reclaimed too early.
473
474           <https://rt.cpan.org/Ticket/Display.html?id=129202>
475

KNOWN BUGS

477       This is not a complete list of all known issues, but rather a summary
478       of the most notable ones that currently prevent the module from working
479       correctly in a variety of situations. For a complete list of known
480       bugs, see the RT queue at
481       <https://rt.cpan.org/Dist/Display.html?Name=Future-AsyncAwait>.
482
483       ·   "await" inside "map" or "grep" blocks does not work. This is due to
484           the difficulty of detecting the map or grep context from internal
485           perl state at suspend time, sufficient to be able to restore it
486           again when resuming.
487
488           <https://rt.cpan.org/Ticket/Display.html?id=129748>
489
490           As a workaround, consider converting a "map" expression to the
491           equivalent form using "push" onto an accumulator array with a
492           "foreach" loop:
493
494              my @results = map { await func($_) } ITEMS;
495
496           becomes
497
498              my @results;
499              foreach my $item ( ITEMS ) {
500                 push @results, await func($item);
501              }
502
503           with a similar transformation for "grep" expressions.
504
505           Alternatively, consider using the "fmap*" family of functions from
506           Future::Utils to provide a concurrent version of the same code,
507           which can keep multiple items running concurrently:
508
509              use Future::Utils qw( fmap );
510
511              my @results = await fmap { func( shift ) }
512                 foreach    => [ ITEMS ],
513                 concurrent => 5;
514

ACKNOWLEDGEMENTS

516       With thanks to "Zefram", "ilmari" and others from "irc.perl.org/#p5p"
517       for assisting with trickier bits of XS logic.
518
519       Thanks to "genio" for project management and actually reminding me to
520       write some code.
521
522       Thanks to The Perl Foundation for sponsoring me to continue working on
523       the implementation.
524

AUTHOR

526       Paul Evans <leonerd@leonerd.org.uk>
527
528
529
530perl v5.32.1                      2021-03-26             Future::AsyncAwait(3)