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.
STABILITY WARNING
This module is still relatively new and under active development. While
it now seems relatively stable enough for most use-cases, there may
still be a number of memory leaks left in it, especially if
still-pending futures are abandoned.
While it seems stable enough for small-scale development and
experimental testing, take care when using this module in production,
as some growth in memory over time may be observed. Careful use of
monitoring and periodic restarts of long-running processes may be a
wise precaution.
That said, using this module in places like unit-tests and short-term
scripts 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.
SUPPORTED USES
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;
}
On perl versions 5.26 and later async sub syntax supports the
signatures feature if it is enabled:
use 5.026;
use feature 'signatures';
async sub quart($x, $y)
{
...
}
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".
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 Future::AsyncAwait;
use Syntax::Keyword::Try;
async sub attempt
{
try {
await func();
return "success";
}
catch {
return "failed";
}
}
Syntax::Keyword::Dynamically
As of Future::AsyncAwait version 0.32, cross-module integration tests
assert that the dynamically correctly works across an await boundary.
use Future::AsyncAwait;
use Syntax::Keyword::Dynamically;
our $var;
async sub trial
{
dynamically $var = "value";
await func();
say "Var is still $var";
}
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.
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 ...
}
}
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
* Implement cancel back-propagation for Perl versions earlier than
5.24. Currently this does not work due to some as-yet-unknown effects
that installing the back-propagation has, causing future instances to
be reclaimed too early.
https://rt.cpan.org/Ticket/Display.html?id=129202
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.
* await inside map or grep blocks does not work. This is due to the
difficulty of detecting the map or grep context from internal perl
state at suspend time, sufficient to be able to restore it again when
resuming.
https://rt.cpan.org/Ticket/Display.html?id=129748
As a workaround, consider converting a map expression to the
equivalent form using push onto an accumulator array with a foreach
loop:
my @results = map { await func($_) } ITEMS;
becomes
my @results;
foreach my $item ( ITEMS ) {
push @results, await func($item);
}
with a similar transformation for grep expressions.
Alternatively, consider using the fmap* family of functions from
Future::Utils to provide a concurrent version of the same code, which
can keep multiple items running concurrently:
use Future::Utils qw( fmap );
my @results = await fmap { func( shift ) }
foreach => [ ITEMS ],
concurrent => 5;
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>