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 awaiting on any itself.
EARLY-VERSION WARNING
WARNING: The actual semantics in this module are in an early state of
implementation. Some things work but most do not. Don't expect to be
able to use this module for much real code yet.
Things That Work Already
Any function that doesn't actually await anything, and just returns
immediate futures is already working fine with this module.
Instead of writing
sub foo
{
...
return Future->done( @result );
}
you can now simply write
async sub foo
{
...
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.
In addition, some simple cases involving awaiting on still-pending
futures should be working:
async sub bar
{
my ( $f ) = @_;
return 1 + await( $f ) + 3;
}
async sub splot
{
while( COND ) {
await func();
}
}
async sub wibble
{
if( COND ) {
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
Any code that attempts to await from inside any sort of foreach loop
does not currently work:
async sub wobble
{
foreach ( THINGs ) {
await func();
}
}
local variable assignments inside an async function will confuse the
suspend mechanism:
our $DEBUG = 0;
async sub quark
{
local $DEBUG = 1;
await func();
}
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.
TODO
* Suspend and resume over foreach loops, in all their various
flavours.
* Suspend and resume with some consideration for the savestack; i.e.
the area used to implement local and similar:
* Clean up the implementation; check for and fix memory leaks.
* Support older versions of perl than 5.24.
https://rt.cpan.org/Ticket/Display.html?id=122252
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>