Showing posts with label Future::Utils. Show all posts
Showing posts with label Future::Utils. Show all posts

2020/12/10

2020 Perl Advent Calendar - Day 10

<< First | < Prev | Next >

In the past couple of days we've seen some techniques for performing multiple concurrent calls to asynchronous functions and waiting for them all to succeed. Sometimes there are situations when we want to make a number of calls and wait for any one of them to complete and take the first result that arrives, rather than waiting for them all.

The original blog series post on day 21 introduced Future->wait_any which also a list of futures and returns one to represent their combination, in a pattern similar to needs_all. Where needs_all needed all of the components to complete, this one will yield the result of whichever is first to finish - either in success or failure. In effect it creates a race between them.

This is most often seen in order to create timeouts around asynchronous functions. As with the needs_any constructor, it is usually seen directly in an await expression. Its arguments, the component futures it waits on, are often the result of directly calling asynchronous functions. Often there are just two arguments - one future to do some "useful" work and yield a successful result, the other to wait until the timeout and then yield a failure. Whichever completes first will be the result of the wait_any and hence what await will see.

For example, this method from a communication protocol sends a byte over a filehandle, then waits for either a single-byte read back from the filehandle, or a timeout.

use Future::AsyncAwait;
use Future::IO;

async sub _break
{
    my $self = shift;
    my $fh = $self->{fh};
    
    $fh->print("\x00");

    await Future->wait_any(
        Future::IO->sysread($fh, 1),
        Future::IO->sleep(0.05)->then_fail("Timed out"),
    );
}

We will introduce the Future::IO module more fully in a later post. For now, consider that it provides some methods named after core IO functions which return futures and allow the operations to take place asynchronously. In this example the sysread future will complete if there is another byte available on the filehandle, and the sleep future will complete after the given delay. The ->then_fail method is a small shortcut on a future instance, for turning a success into a failure. The result here is that if a new byte is soon available to read from the filehandle then it is returned by the first component future, though if none arrives after 50msec the second future yields a failure, which causes the await to throw an exception up to its own caller.

You may be wondering what happens to the sleep call if the byte is read successfully, or to the sysread if the timeout happens. The answer here is that as well as completing with success or failure, pending future instances can also be cancelled. As soon as one of the component futures that wait_any is waiting for is completed, it will cancel all of the other ones. It is up to the creator of the component futures to determine what should happen at this point. The original blog post series at day 19 introduced the on_cancel method, which the implementation can use to set this behaviour.

When using async/await syntax this is mostly handled automatically. While an async sub is suspended waiting for a future to complete, if its own return-value future is cancelled then this cancellation is propagated down to the future it was waiting on.

Cancellation is mostly a feature of interest to the lowest level implementation of asynchronous systems using futures, and doesn't often need special handling in intermediate layers of logic. For situations where the logic does however need to handle it, you can use a CANCEL block. At time of writing this syntax is still considered experimental, but it is designed to feel similar to my other still-experimental idea of adding FINALLY blocks to core Perl syntax.

use Future::AsyncAwait ':experimental(cancel)';

async sub f
{
   CANCEL { warn "This task was cancelled"; }
 
   await ...
}

It turns out in actual practice to be quite rare to need this ability - I had hoped to be able to paste a real example from some real code, but currently there isn't any on CPAN which actually makes use of this. Hopefully there will eventually be enough actual uses of the syntax to be able to judge the experiment, and see whether it should become stable, or still needs work.

<< First | < Prev | Next >

2020/12/09

2020 Perl Advent Calendar - Day 9

<< First | < Prev | Next >

Yesterday we saw some ways to write concurrent asynchronous code which waits on a few different tasks to complete. Sometimes we want to do the same thing multiple times concurrently but with different data each time. Often it's the case that each item can be processed independently of the others, so it makes sense to try to do several at once.

One approach here is to simply await a future to process each individual item inside a regular foreach loop. This will only work on one item at once, so we won't make use of concurrency.

## A poor idea for iterating a list ##
use Future::AsyncAwait;

foreach my $item (@ITEMS) {
    await PROCESS($item);
}

Another idea is to use map to apply an asynchronous function to every item in the list, and thus start all the items at once, then wait on all those futures using needs_all. This may end up being too concurrent - if the list contained many thousand items we might do too many at once and overload whatever external service or system we are talking to.

## Another poor idea ##
use Future::AsyncAwait;

await Future->needs_all(
    map { PROCCESS($_) } @ITEMS
);

A better middle-ground between these two extremes was introduced in the original blog series on day 18, in the form of the Future::Utils::fmap collection of helper functions. The basic idea of fmap is that it is a future-aware equivalent of Perl's map operator. The fmap function is given a block of code which is expected to return a future, and a list of items. It invokes the code block once for each item in the list, collecting up and waiting on the returned future values, until all the items are done. fmap returns a future to represent the entire operation, which will complete with the results of each individual item.

The fmap family actually contains three individual functions, which all operate in the same basic manner. The difference between them is in how they handle return values from each individual item block - fmap_concat can handle an entire list from each item and concatenates all the results together for its overall result, fmap_scalar expects exactly one result per item, and fmap_void does not collect up any results at all; running the code block simply for its side-effects.

Since fmap expects a future-returning function and itself returns a future it is also idea for use with async/await syntax. It can be invoked in an await expression and passed an async sub to operate on.

This somewhat-paraphrased example uses the GET method of a Net::Async::HTTP user agent object to concurrently fetch and JSON-decode a collection of data from multiple API endpoints of some remote service.

use feature 'signatures';
use Future::AsyncAwait;
use Future::Utils qw( fmap_scalar );
use JSON::MaybeUTF8 qw( decode_json_utf8 );

use Net::Async::HTTP;
my $ua = Net::Async::HTTP->new;
...

my @urls = ...

my @data = await fmap_scalar(async sub ($url) {
    my $response = await $ua->GET($url);
    return decode_json_utf8($response->content);
}, foreach => \@urls, concurrent => 16);

A few things should be noted about this example. First is that the async sub syntax is used explicitly to create an asynchronous function to pass as the first argument to the fmap_scalar function. Second is the use of the concurrent parameter, telling the function how many items to keep running concurrently. Finally, the list of items has to be passed in an array reference rather than a plain flat list.

These facts all come about because the fmap functions are just plain Perl functions and not special syntax, as opposed to the real syntax provided by the async and await keywords. Whereas these two keywords were inspired by a whole collection of other languages which have all adopted it as a standard pattern, there is not much existing design on the problem of bounded concurrency map-style syntax. This particular area remains a matter of ongoing design and discussion. Thoughts welcome ;)

<< First | < Prev | Next >

2020/12/07

2020 Perl Advent Calendar - Day 7

<< First | < Prev | Next >

So far in this advent series we've been following the progression from the original posts from 2013. In the next few posts we'll take things in a slightly different order. There will be a few new things to see about async/await syntax, but before we move onto that I want to continue the subject from the past couple of days, and cover the remaining the situations in which asynchronous programming with async/await follows the same shape and style as regular synchronous programming.

The original day 15 post introduced the Future::Utils::repeat helper function, for taking a single block of future-returning code, and calling it repeatedly until some condition is satisfied. The resulting code does behave somewhat like a regular perl while loop, though the syntax notation of it looks nothing like it. Using async/await, conversely, this sort of behaviour can simply be written with a regular while loop. Recalling that an await expression can be placed anywhere inside an async sub, we can simply wait for an intermediate result inside the body of the loop, before continuing.

This example from a module that communicates with a microcontroller needs to wait for the chip to not be busy. It can simply await a read of the current status and look for the busy bit inside a while loop.

use Future::AsyncAwait;

async sub await_nvm_not_busy
{
    my $self = shift;
    
    my $timeout = 50;
    while(--$timeout) {
        (await $self->load_nvm_status) & NVMCTRL_STATUS_FBUSY
            or last;
        
        await Future::IO->sleep(0.01);
    }
}

In fact, we can even put the await expression inside the loop condition itself. A different chip communication module for a radio transmitter uses this to wait for the chip to enter transmit state.

use Future::AsyncAwait;

async sub start_tx
{
    my $self = shift;
    
    await $self->command(CMD_STX);
    1 until (await $self->read_marcstate) eq "TX";
}

In both of these cases, we have to put the await expression in parentheses because of operator precedence, but other than that the logic reads just as short and tidy as it would for synchronous code.

Day 16 of the original series introduced another form of the Future::Utils::repeat helper for iterating over a given list of items. As before, this isn't necessary when using async/await syntax because we can just put an await expression somewhere inside a foreach loop to achieve the same effect.

For example, this somewhat-simplified example from a module that communicates with memory chips uses a regular foreach loop to iterate over a range of addresses to read.

use feature 'signature';
use Future::AsyncAwait;

async sub read_eeprom(%opts)
{
    my $start = $opts{start} // 0;
    my $stop  = $opts{stop} // MAXADDR;
    
    my $bytes = "";
    
    foreach my $addr ($start .. $stop-1) {
        await $self->set_address($addr);
        $bytes .= await $self->read_byte();
    }
    
    return $bytes;
}

Now we have a good overview of what code shapes are identical with async/await synta we'll next take a look at some new abilities we can gain from the ability to run things concurrently. While we first saw a few glimpses of that back on Day 3 this time, there are still a number of new things left to see.

<< First | < Prev | Next >