File Coverage

blib/lib/Future/AsyncAwait.pm
Criterion Covered Total %
statement 22 26 84.6
branch 3 6 50.0
condition n/a
subroutine 6 6 100.0
pod 0 1 0.0
total 31 39 79.4


line stmt bran cond sub pod time code
1             # You may distribute under the terms of either the GNU General Public License
2             # or the Artistic License (the same terms as Perl itself)
3             #
4             # (C) Paul Evans, 2016-2021 -- leonerd@leonerd.org.uk
5              
6             package Future::AsyncAwait 0.65;
7              
8 44     44   9972278 use v5.14;
  44         388  
9 44     44   251 use warnings;
  44         99  
  44         1104  
10              
11 44     44   232 use Carp;
  44         95  
  44         4663  
12              
13             require XSLoader;
14             XSLoader::load( __PACKAGE__, our $VERSION );
15              
16             require Future; Future->VERSION( '0.48' );
17              
18             if( !Future->can( "AWAIT_WAIT" ) ) {
19 44     44   345 no strict 'refs';
  44         90  
  44         18070  
20             # Future 0.48 had this method; newer futures already provide AWAIT_WAIT
21             *{"Future::AWAIT_WAIT"} = Future->can( "get" );
22             }
23              
24             =head1 NAME
25              
26             C - deferred subroutine syntax for futures
27              
28             =head1 SYNOPSIS
29              
30             use v5.14;
31             use Future::AsyncAwait;
32              
33             async sub do_a_thing
34             {
35             my $first = await do_first_thing();
36              
37             my $second = await do_second_thing();
38              
39             return combine_things( $first, $second );
40             }
41              
42             do_a_thing()->get;
43              
44             =head1 DESCRIPTION
45              
46             This module provides syntax for deferring and resuming subroutines while
47             waiting for Ls to complete. This syntax aims to make code that
48             performs asynchronous operations using futures look neater and more expressive
49             than simply using C chaining and other techniques on the futures
50             themselves. It is also a similar syntax used by a number of other languages;
51             notably C# 5, EcmaScript 6, Python 3, Dart, Rust, C++20.
52              
53             This module is still under active development. While it now seems relatively
54             stable enough for most use-cases and has received a lot of "battle-testing" in
55             a wide variety of scenarios, there may still be the occasional case of memory
56             leak left in it, especially if still-pending futures are abandoned.
57              
58             The new syntax takes the form of two new keywords, C and C.
59              
60             =head2 C
61              
62             The C keyword should appear just before the C keyword that
63             declares a new function. When present, this marks that the function performs
64             its work in a I asynchronous fashion. This has two effects: it
65             permits the body of the function to use the C expression, and it wraps
66             the return value of the function in a L instance.
67              
68             async sub myfunc
69             {
70             return 123;
71             }
72              
73             my $f = myfunc();
74             my $result = $f->get;
75              
76             As well as named function declarations it is also supported on anonymous
77             function expressions.
78              
79             my $code = async sub { return 456 };
80             my $f = $code->();
81             my $result = $f->get;
82              
83             This C-declared function always returns a C instance when
84             invoked. The returned future instance will eventually complete when the
85             function returns, either by the C keyword or by falling off the end;
86             the result of the future will be the return value from the function's code.
87             Alternatively, if the function body throws an exception, this will cause the
88             returned future to fail.
89              
90             If the final expression in the body of the function returns a C, don't
91             forget to C it rather than simply returning it as it is, or else this
92             return value will become double-wrapped - almost certainly not what you
93             wanted.
94              
95             async sub otherfunc { ... }
96              
97             async sub myfunc
98             {
99             ...
100             return await otherfunc();
101             }
102              
103             =head2 C
104              
105             The C keyword forms an expression which takes a C instance as
106             an operand and yields the eventual result of it. Superficially it can be
107             thought of similar to invoking the C method on the future.
108              
109             my $result = await $f;
110              
111             my $result = $f->get;
112              
113             However, the key difference (and indeed the entire reason for being a new
114             syntax keyword) is the behaviour when the future is still pending and is not
115             yet complete. Whereas the simple C method would block until the future is
116             complete, the C keyword causes its entire containing function to become
117             suspended, making it return a new (pending) future instance. It waits in this
118             state until the future it was waiting on completes, at which point it wakes up
119             and resumes execution from the point of the C expression. When the
120             now-resumed function eventually finishes (either by returning a value or
121             throwing an exception), this value is set as the result of the future it had
122             returned earlier.
123              
124             C provides scalar context to its controlling expression.
125              
126             async sub func {
127             # this function is invoked in scalar context
128             }
129              
130             await func();
131              
132             Because the C keyword may cause its containing function to suspend
133             early, returning a pending future instance, it is only allowed inside
134             C-marked subs.
135              
136             The converse is not true; just because a function is marked as C does
137             not require it to make use of the C expression. It is still useful to
138             turn the result of that function into a future, entirely without Cing
139             on any itself.
140              
141             Any function that doesn't actually await anything, and just returns immediate
142             futures can be neatened by this module too.
143              
144             Instead of writing
145              
146             sub imm
147             {
148             ...
149             return Future->done( @result );
150             }
151              
152             you can now simply write
153              
154             async sub imm
155             {
156             ...
157             return @result;
158             }
159              
160             with the added side-benefit that any exceptions thrown by the elided code will
161             be turned into an immediate-failed C rather than making the call
162             itself propagate the exception, which is usually what you wanted when dealing
163             with futures.
164              
165             =head2 await (toplevel)
166              
167             I
168              
169             An C expression is also permitted directly in the main script at
170             toplevel, outside of C. This is implemented by simply invoking the
171             C method on the future value. Thus, the following two lines are directly
172             equivalent:
173              
174             await afunc();
175             afunc()->get;
176              
177             This is provided as a syntax convenience for unit tests, toplevel scripts, and
178             so on. It allows code to be written in a style that can be easily moved into
179             an C, and avoids encouraging "bad habits" of invoking the C
180             method directly.
181              
182             =head2 C
183              
184             I
185              
186             The C keyword declares a block of code which will be run in the event
187             that the future returned by the C is cancelled.
188              
189             async sub f
190             {
191             CANCEL { warn "This task was cancelled"; }
192              
193             await ...
194             }
195              
196             f()->cancel;
197              
198             A C block is a self-contained syntax element, similar to perl
199             constructions like C, and does not need a terminating semicolon.
200              
201             When a C block is encountered during execution of the C,
202             the code in its block is stored for the case that the returned future is
203             cancelled. Each will take effect as it is executed, possibly multiple times if
204             it appears inside a loop, or not at all if it appears conditionally in a
205             branch that was not executed.
206              
207             async sub g
208             {
209             if(0) {
210             CANCEL { warn "This does not happen"; }
211             }
212              
213             foreach my $x ( 1..3 ) {
214             CANCEL { warn "This happens for x=$x"; }
215             }
216              
217             await ...
218             }
219              
220             g()->cancel;
221              
222             C blocks are only invoked if a still-pending future is cancelled. They
223             are discarded without being executed if the function finishes; either
224             successfully or if it throws an exception.
225              
226             =head1 Experimental Features
227              
228             Some of the features of this module are currently marked as experimental. They
229             will provoke warnings in the C category, unless silenced.
230              
231             You can silence this with C but then that will
232             silence every experimental warning, which may hide others unintentionally. For
233             a more fine-grained approach you can instead use the import line for this
234             module to only silence this module's warnings selectively:
235              
236             use Future::AsyncAwait qw( :experimental(cancel) );
237              
238             use Future::AsyncAwait qw( :experimental ); # all of the above
239              
240             =head1 SUPPORTED USES
241              
242             Most cases involving awaiting on still-pending futures should work fine:
243              
244             async sub foo
245             {
246             my ( $f ) = @_;
247              
248             BEFORE();
249             await $f;
250             AFTER();
251             }
252              
253             async sub bar
254             {
255             my ( $f ) = @_;
256              
257             return 1 + await( $f ) + 3;
258             }
259              
260             async sub splot
261             {
262             while( COND ) {
263             await func();
264             }
265             }
266              
267             async sub wibble
268             {
269             if( COND ) {
270             await func();
271             }
272             }
273              
274             async sub wobble
275             {
276             foreach my $var ( THINGs ) {
277             await func();
278             }
279             }
280              
281             async sub wubble
282             {
283             # on perl 5.35.5 and above
284             foreach my ($k, $v) ( KVTHINGs ) {
285             await func();
286             }
287             }
288              
289             async sub quux
290             {
291             my $x = do {
292             await func();
293             };
294             }
295              
296             async sub splat
297             {
298             eval {
299             await func();
300             };
301             }
302              
303             Plain lexical variables are preserved across an C deferral:
304              
305             async sub quux
306             {
307             my $message = "Hello, world\n";
308             await func();
309             print $message;
310             }
311              
312             On perl versions 5.26 and later C syntax supports the C
313             feature if it is enabled:
314              
315             use v5.26;
316             use feature 'signatures';
317              
318             async sub quart($x, $y)
319             {
320             ...
321             }
322              
323             I any exceptions thrown by signature validation (because
324             of too few or too many arguments being passed) are thrown synchronously, and
325             do not result in a failed Future instance.
326              
327             =head2 Cancellation
328              
329             Cancelled futures cause a suspended C to simply stop running.
330              
331             async sub fizz
332             {
333             await func();
334             say "This is never reached";
335             }
336              
337             my $f = fizz();
338             $f->cancel;
339              
340             Cancellation requests can propagate backwards into the future the
341             C is currently waiting on.
342              
343             async sub floof
344             {
345             ...
346             await $f1;
347             }
348              
349             my $f2 = floof();
350              
351             $f2->cancel; # $f1 will be cancelled too
352              
353             This behaviour is still more experimental than the rest of the logic. The
354             following should be noted:
355              
356             =over 4
357              
358             =item *
359              
360             Cancellation propagation is only implemented on Perl version 5.24 and above.
361             An C in an earlier perl version will still stop executing if
362             cancelled, but will not propagate the request backwards into the future that
363             the C is currently waiting on. See L.
364              
365             =back
366              
367             =head1 SUBCLASSING Future
368              
369             By default when an C returns a result or fails immediately before
370             awaiting, it will return a new completed instance of the L class. In
371             order to allow code that wishes to use a different class to represent futures
372             the module import method can be passed the name of a class to use instead.
373              
374             use Future::AsyncAwait future_class => "Subclass::Of::Future";
375              
376             async sub func { ... }
377              
378             This has the usual lexically-scoped effect, applying only to Cs
379             defined within the block; others are unaffected.
380              
381             use Future::AsyncAwait;
382              
383             {
384             use Future::AsyncAwait future_class => "Different::Future";
385             async sub x { ... }
386             }
387              
388             async sub y { ... } # returns a regular Future
389              
390             This will only affect immediate results. If the C keyword has to
391             suspend the function and create a new pending future, it will do this by using
392             the prototype constructor on the future it itself is waiting on, and the usual
393             subclass-respecting semantics of L will remain in effect there. As
394             such it is not usually necessary to use this feature just for wrapping event
395             system modules or other similar situations.
396              
397             Such an alternative subclass should implement the API documented by
398             L.
399              
400             =head1 WITH OTHER MODULES
401              
402             =head2 Syntax::Keyword::Try
403              
404             As of L version 0.10 and L version
405             0.07, cross-module integration tests assert that basic C blocks
406             inside an C work correctly, including those that attempt to
407             C from inside C.
408              
409             use Future::AsyncAwait;
410             use Syntax::Keyword::Try;
411              
412             async sub attempt
413             {
414             try {
415             await func();
416             return "success";
417             }
418             catch {
419             return "failed";
420             }
421             }
422              
423             As of L version 0.50, C blocks are invoked even
424             during cancellation.
425              
426             =head2 Syntax::Keyword::Dynamically
427              
428             As of L version 0.32, cross-module integration tests
429             assert that the C correctly works across an C boundary.
430              
431             use Future::AsyncAwait;
432             use Syntax::Keyword::Dynamically;
433              
434             our $var;
435              
436             async sub trial
437             {
438             dynamically $var = "value";
439              
440             await func();
441              
442             say "Var is still $var";
443             }
444              
445             =head2 Syntax::Keyword::Defer
446              
447             As of L version 0.50, C blocks are invoked even
448             during cancellation.
449              
450             use Future::AsyncAwait;
451             use Syntax::Keyword::Defer;
452              
453             async sub perhaps
454             {
455             defer { say "Cleaning up now" }
456             await $f1;
457             }
458              
459             my $fouter = perhaps();
460             $fouter->cancel;
461              
462             =head2 Object::Pad
463              
464             As of L version 0.38 and L version 0.15, both
465             modules now use L to parse blocks of code. Because of this
466             the two modules can operate together and allow class methods to be written as
467             async subs which await expressions:
468              
469             use Future::AsyncAwait;
470             use Object::Pad;
471              
472             class Example
473             {
474             async method perform($block)
475             {
476             say "$self is performing code";
477             await $block->();
478             say "code finished";
479             }
480             }
481              
482             =head2 Syntax::Keyword::MultiSub
483              
484             As of L version 0.55 and L
485             version 0.02 a cross-module integration test asserts that the C
486             modifier can be applied to C.
487              
488             use Future::AsyncAwait;
489             use Syntax::Keyword::MultiSub;
490              
491             async multi sub f () { return "nothing"; }
492             async multi sub f ($key) { return await get_thing($key); }
493              
494             =cut
495              
496             sub import
497             {
498 37     37   9414 my $class = shift;
499 37         98 my $caller = caller;
500              
501 37         145 $class->import_into( $caller, @_ );
502             }
503              
504             my @EXPERIMENTAL = qw( cancel );
505              
506             sub import_into
507             {
508 37     37 0 77 my $class = shift;
509 37         68 my $caller = shift;
510              
511 37         199 $^H{"Future::AsyncAwait/async"}++; # Just always turn this on
512              
513 37         66180 SYM: while( @_ ) {
514 2         4 my $sym = shift;
515              
516 2 100       62 $^H{"Future::AsyncAwait/future"} = shift, next if $sym eq "future_class";
517              
518 1         3 foreach ( @EXPERIMENTAL ) {
519 1 50       2500 $^H{"Future::AsyncAwait/experimental($_)"}++, next SYM if $sym eq ":experimental($_)";
520             }
521 0 0         if( $sym eq ":experimental" ) {
522 0           $^H{"Future::AsyncAwait/experimental($_)"}++ for @EXPERIMENTAL;
523 0           next SYM;
524             }
525              
526 0           croak "Unrecognised import symbol $sym";
527             }
528             }
529              
530             =head1 SEE ALSO
531              
532             =over 4
533              
534             =item *
535              
536             "Awaiting The Future" - TPC in Amsterdam 2017
537              
538             L L<(slides)|https://docs.google.com/presentation/d/13x5l8Rohv_RjWJ0OTvbsWMXKoNEWREZ4GfKHVykqUvc/edit#slide=id.p>
539              
540             =back
541              
542             =head1 TODO
543              
544             =over 4
545              
546             =item *
547              
548             Suspend and resume with some consideration for the savestack; i.e. the area
549             used to implement C and similar. While in general C support has
550             awkward questions about semantics, there are certain situations and cases
551             where internally-implied localisation of variables would still be useful and
552             can be supported without the semantic ambiguities of generic C.
553              
554             our $DEBUG = 0;
555              
556             async sub quark
557             {
558             local $DEBUG = 1;
559             await func();
560             }
561              
562             Since C loops on non-lexical iterator variables (usually the C<$_>
563             global variable) effectively imply a C-like behaviour, these are also
564             disallowed.
565              
566             async sub splurt
567             {
568             foreach ( LIST ) {
569             await ...
570             }
571             }
572              
573             Some notes on what makes the problem hard can be found at
574              
575             L
576              
577             =item *
578              
579             Currently this module requires perl version 5.16 or later. Additionally,
580             threaded builds of perl earlier than 5.22 are not supported.
581              
582             L
583              
584             L
585              
586             =item *
587              
588             Implement cancel back-propagation for Perl versions earlier than 5.24.
589             Currently this does not work due to some as-yet-unknown effects that
590             installing the back-propagation has, causing future instances to be reclaimed
591             too early.
592              
593             L
594              
595             =back
596              
597             =head1 KNOWN BUGS
598              
599             This is not a complete list of all known issues, but rather a summary of the
600             most notable ones that currently prevent the module from working correctly in
601             a variety of situations. For a complete list of known bugs, see the RT queue
602             at L.
603              
604             =over 4
605              
606             =item *
607              
608             C inside C or C blocks does not work. This is due to the
609             difficulty of detecting the map or grep context from internal perl state at
610             suspend time, sufficient to be able to restore it again when resuming.
611              
612             L
613              
614             As a workaround, consider converting a C expression to the equivalent
615             form using C onto an accumulator array with a C loop:
616              
617             my @results = map { await func($_) } ITEMS;
618              
619             becomes
620              
621             my @results;
622             foreach my $item ( ITEMS ) {
623             push @results, await func($item);
624             }
625              
626             with a similar transformation for C expressions.
627              
628             Alternatively, consider using the C family of functions from
629             L to provide a concurrent version of the same code, which can
630             keep multiple items running concurrently:
631              
632             use Future::Utils qw( fmap );
633              
634             my @results = await fmap { func( shift ) }
635             foreach => [ ITEMS ],
636             concurrent => 5;
637              
638             =item *
639              
640             The default arguments array (C<@_>) is not saved and restored by an C
641             call on perl versions before v5.24. On such older perls, the value seen in the
642             C<@_> array after an await will not be the same as it was before.
643              
644             L
645              
646             As a workaround, make sure to unpack the values out of it into regular lexical
647             variables early on, before the the first C. The values of these
648             lexicals will be saved and restored as normal.
649              
650             async sub f
651             {
652             my ($vars, $go, @here) = @_;
653             # do not make further use of @_ afterwards
654              
655             await thing();
656              
657             # $vars, $go, @here are all fine for use
658             }
659              
660             =back
661              
662             =cut
663              
664             =head1 ACKNOWLEDGEMENTS
665              
666             With thanks to C, C and others from C for
667             assisting with trickier bits of XS logic.
668              
669             Thanks to C for project management and actually reminding me to write
670             some code.
671              
672             Thanks to The Perl Foundation for sponsoring me to continue working on the
673             implementation.
674              
675             =head1 AUTHOR
676              
677             Paul Evans
678              
679             =cut
680              
681             0x55AA;