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, and lately even
       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 forces the return
       value of the function to always be 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.

   "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.

EARLY-VERSION WARNING

       WARNING: The actual semantics in this module are in an early state of implementation. Some things will
       randomly break. 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.

   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 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 ...
             }
          }

       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.

   Async Without Await
       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.

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".

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>

       •   Clean up the implementation; check for and fix memory leaks.

       •   Support older versions of perl than 5.18.

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

       •   Support sub signatures in recent perls.

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

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.

AUTHOR

       Paul Evans <leonerd@leonerd.org.uk>