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

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

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

      * Currently this module requires perl version 5.16 or later. Support
      perl version 5.14.

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

      * Support sub signatures in recent perls.

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

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>

