/ 
Future-AsyncAwait-0.26
River stage three • 63 direct dependents • 116 total dependents
/ Future::AsyncAwait

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

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

Cancellation

Cancelled futures cause a suspended async sub to simply stop running.

async sub fizz
{
   await func();
   say "This is never reached";
}

my $f = fizz();
$f->cancel;

Cancellation requests can propagate backwards into the future the async sub is currently waiting on.

async sub floof
{
   ...
   await $f1;
}

my $f2 = floof();

$f2->cancel;  # $f1 will be cancelled too

This behaviour is still more experimental than the rest of the logic. The following should be noted:

  • There is currently no way to perform the equivalent of "on_cancel" in Future to add a cancellation callback to a future chain.

  • Cancellation propagation is only implemented on Perl version 5.24 and above. An async sub in an earlier perl version will still stop executing if cancelled, but will not propagate the request backwards into the future that the async sub is currently waiting on. See "TODO".

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 the $_ global variable) effectively imply a local-like behaviour, these are also disallowed.

async sub splurt
{
   foreach ( 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

TODO

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.

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>