Provided by: libfuture-asyncawait-perl_0.22-1_amd64 bug

NAME

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

SYNOPSIS

          use Future::AsyncAwait;

          async sub do_a_thing
          {
             my $first = await do_first_thing();

             my $second = await do_second_thing();

             return combine_things( $first, $second );
          }

          do_a_thing()->get;

DESCRIPTION

       This module provides syntax for deferring and resuming subroutines while waiting for
       Futures to complete. This syntax aims to make code that performs asynchronous operations
       using futures look neater and more expressive than simply using "then" chaining and other
       techniques on the futures themselves. It is also a similar syntax used by a number of
       other languages; notably C# 5, EcmaScript 6, Python 3, Dart. Rust is considering adding
       it.

       The new syntax takes the form of two new keywords, "async" and "await".

   "async"
       The "async" keyword should appear just before the "sub" keyword that declares a new
       function. When present, this marks that the function performs its work in a potentially
       asynchronous fashion. This has two effects: it permits the body of the function to use the
       "await" expression, and it wraps the return value of the function in a Future instance.

          async sub myfunc
          {
             return 123;
          }

          my $f = myfunc();
          my $result = $f->get;

       This "async"-declared function always returns a "Future" instance when invoked. The
       returned future instance will eventually complete when the function returns, either by the
       "return" keyword or by falling off the end; the result of the future will be the return
       value from the function's code.  Alternatively, if the function body throws an exception,
       this will cause the returned future to fail.

       If the final expression in the body of the function returns a "Future", don't forget to
       "await" it rather than simply returning it as it is, or else this return value will become
       double-wrapped - almost certainly not what you wanted.

          async sub otherfunc { ... }

          async sub myfunc
          {
             ...
             return await otherfunc();
          }

   "await"
       The "await" keyword forms an expression which takes a "Future" instance as an operand and
       yields the eventual result of it. Superficially it can be thought of similar to invoking
       the "get" method on the future.

          my $result = await $f;

          my $result = $f->get;

       However, the key difference (and indeed the entire reason for being a new syntax keyword)
       is the behaviour when the future is still pending and is not yet complete. Whereas the
       simple "get" method would block until the future is complete, the "await" keyword causes
       its entire containing function to become suspended, making it return a new (pending)
       future instance. It waits in this state until the future it was waiting on completes, at
       which point it wakes up and resumes execution from the point of the "await" expression.
       When the now-resumed function eventually finishes (either by returning a value or throwing
       an exception), this value is set as the result of the future it had returned earlier.

       Because the "await" keyword may cause its containing function to suspend early, returning
       a pending future instance, it is only allowed inside "async"-marked subs.

       The converse is not true; just because a function is marked as "async" does not require it
       to make use of the "await" expression. It is still useful to turn the result of that
       function into a future, entirely without "await"ing on any itself.

       Any function that doesn't actually await anything, and just returns immediate futures can
       be neatened by this module too.

       Instead of writing

          sub imm
          {
             ...
             return Future->done( @result );
          }

       you can now simply write

          async sub imm
          {
             ...
             return @result;
          }

       with the added side-benefit that any exceptions thrown by the elided code will be turned
       into an immediate-failed "Future" rather than making the call itself propagate the
       exception, which is usually what you wanted when dealing with futures.

BETA-VERSION WARNING

       This module is still relatively new. While it seems stable enough for small-scale
       development and experimental testing, don't expect to be able to use this module reliably
       in production yet. It doesn't memory leak in most simple cases, but I don't have a great
       amount of confidence that there aren't still some corner-cases left which do.

       That said, using it just in places like unit-tests and short-term scripts it does appear
       to be quite stable, so do try experimenting with it in this sort of situation, and let me
       know what does and doesn't work.

   Things That Work
       Most cases involving awaiting on still-pending futures should work fine:

          async sub foo
          {
             my ( $f ) = @_;

             BEFORE();
             await $f;
             AFTER();
          }

          async sub bar
          {
             my ( $f ) = @_;

             return 1 + await( $f ) + 3;
          }

          async sub splot
          {
             while( COND ) {
                await func();
             }
          }

          async sub wibble
          {
             if( COND ) {
                await func();
             }
          }

          async sub wobble
          {
             foreach my $var ( THINGs ) {
                await func();
             }
          }

          async sub quux
          {
             my $x = do {
                await func();
             };
          }

          async sub splat
          {
             eval {
                await func();
             };
          }

       Plain lexical variables are preserved across an "await" deferral:

          async sub quux
          {
             my $message = "Hello, world\n";
             await func();
             print $message;
          }

   Things That Don't Yet Work
       "local" variable assignments inside an "async" function will confuse the suspend
       mechanism:

          our $DEBUG = 0;

          async sub quark
          {
             local $DEBUG = 1;
             await func();
          }

       Since "foreach" loops on non-lexical iterator variables (usually package variables)
       effectively imply a "local"-like behaviour, these are also disallowed.

          our $VAR;

          async sub splurt
          {
             foreach $VAR ( LIST ) {
                await ...
             }
          }

       As "map" and "grep" involve implicit "local" behaviour on the $_ variable, they also don't
       support "await" inside them.

          async sub quoo
          {
             grep { await ... } LIST;
          }

          async sub bah
          {
             map { await ... } LIST;
          }

       Additionally, complications with the savestack appear to be affecting some uses of
       package-level "our" variables captured by async functions:

          our $VAR;

          async sub bork
          {
             print "VAR is $VAR\n";
             await func();
          }

       See also the "TODO" list for further things.

WITH OTHER MODULES

   Syntax::Keyword::Try
       As of "Future::AsyncAwait" version 0.10 and Syntax::Keyword::Try version 0.07, cross-
       module integration tests assert that basic "try/catch" blocks inside an "async sub" work
       correctly, including those that attempt to "return" from inside "try".

          use Syntax::Keyword::Try;

          async sub attempt
          {
             try {
                await func();
                return "success";
             }
             catch {
                return "failed";
             }
          }

SEE ALSO

       ·   "Awaiting The Future" - TPC in Amsterdam 2017

           <https://www.youtube.com/watch?v=Xf7rStpNaT0> (slides)
           <https://docs.google.com/presentation/d/13x5l8Rohv_RjWJ0OTvbsWMXKoNEWREZ4GfKHVykqUvc/edit#slide=id.p>

TODO

       ·   Suspend and resume with some consideration for the savestack; i.e. the area used to
           implement "local" and similar. While in general "local" support has awkward questions
           about semantics, there are certain situations and cases where internally-implied
           localisation of variables would still be useful and can be supported without the
           semantic ambiguities of generic "local".

           Some notes on what makes the problem hard can be found at

           <https://rt.cpan.org/Ticket/Display.html?id=122793>

       ·   Currently this module requires perl version 5.16 or later. Additionally, threaded
           builds of perl earlier than 5.22 are not supported.

           <https://rt.cpan.org/Ticket/Display.html?id=122252>

           <https://rt.cpan.org/Ticket/Display.html?id=124351>

       ·   Support sub signatures in recent perls.

           <https://rt.cpan.org/Ticket/Display.html?id=123465>

KNOWN BUGS

       This is not a complete list of all known issues, but rather a summary of the most notable
       ones that currently prevent the module from working correctly in a variety of situations.
       For a complete list of known bugs, see the RT queue at
       <https://rt.cpan.org/Dist/Display.html?Name=Future-AsyncAwait>.

       ·   In some situations, foreach values on computed lists of expressions may lose values. A
           workaround for this is to calculate values ahead of time into a lexical array, and
           iterate over that.

           <https://rt.cpan.org/Ticket/Display.html?id=128619>

ACKNOWLEDGEMENTS

       With thanks to "Zefram", "ilmari" and others from "irc.perl.org/#p5p" for assisting with
       trickier bits of XS logic.

       Thanks to "genio" for project management and actually reminding me to write some code.

       Thanks to The Perl Foundation for sponsoring me to continue working on the implementation.

AUTHOR

       Paul Evans <leonerd@leonerd.org.uk>