NAME¶

"Future::Phrasebook" - coding examples for "Future" and "Future::Utils"

This documentation-only module provides a phrasebook-like approach to giving examples on how to use Future and Future::Utils to structure Future-driven asynchronous or concurrent logic. As with any inter-dialect phrasebook it is structured into pairs of examples; each given first in a traditional call/return Perl style, and second in a style using Futures. In each case, the generic function or functions in the example are named in "ALL_CAPITALS()" to make them stand out.

In the examples showing use of Futures, any function that is expected to return a "Future" instance is named with a leading "F_" prefix. Each example is also constructed so as to yield an overall future in a variable called "$f", which represents the entire operation.

SEQUENCING¶

The simplest example of a sequencing operation is simply running one piece of code, then immediately running a second. In call/return code we can just place one after the other.

 FIRST();
 SECOND();

Using a Future it is necessary to await the result of the first "Future" before calling the second.

 my $f = F_FIRST()
    ->then( sub { F_SECOND(); } );

Here, the anonymous closure is invoked once the "Future" returned by "F_FIRST()" succeeds. Because "then" invokes the code block only if the first Future succeeds, it shortcircuits around failures similar to the way that "die()" shortcircuits around thrown exceptions. A "Future" representing the entire combination is returned by the method.

Because the "then" method itself returns a "Future" representing the overall operation, it can itself be further chained.

 FIRST();
 SECOND();
 THIRD();

 my $f = F_FIRST()
    ->then( sub { F_SECOND(); } )
    ->then( sub { F_THIRD(); } );

See below for examples of ways to handle exceptions.

 OUTER( INNER() );

 my $f = F_INNER()
    ->then( sub { F_OUTER( @_ ) } );

CONDITIONALS¶

It may be that the result of one function call is used to determine whether or not another operation is taken.

 if( COND() == $value ) {
    ACTION();
 }

Because the "then_with_f" code block is given the first future in addition to its results it can decide whether to call the second function to return a new future, or simply return the one it was given.

 my $f = F_COND()
    ->then_with_f( sub {
       my ( $f_cond, $result ) = @_;
       if( $result == $value ) {
          return F_ACTION();
       }
       else {
          return $f_cond;
       }
    });

EXCEPTION HANDLING¶

In regular call/return style code, if any function throws an exception, the remainder of the block is not executed, the containing "try" or "eval" is aborted, and control is passed to the corresponding "catch" or line after the "eval".

 try {
    FIRST();
 }
 catch {
    my $e = $_;
    ERROR( $e );
 };

The "else" method on a "Future" can be used here. It behaves similar to "then", but is only invoked if the initial "Future" fails; not if it succeeds.

 my $f = F_FIRST()
    ->else( sub { F_ERROR( @_ ); } );

Alternatively, the second argument to the "then" method can be applied, which is invoked only on case of failure.

 my $f = F_FIRST()
    ->then( undef, sub { F_ERROR( @_ ); } );

Often it may be the case that the failure-handling code is in fact immediate, and doesn't return a "Future". In that case, the "else" code block can return an immediate "Future" instance.

 my $f = F_FIRST()
    ->else( sub {
       ERROR( @_ );
       return Future->done;
    });

Sometimes the failure handling code simply needs to be aware of the failure, but rethrow it further up.

 try {
    FIRST();
 }
 catch {
    my $e = $_;
    ERROR( $e );
    die $e;
 };

In this case, while the "else" block could return a new "Future" failed with the same exception, the "else_with_f" block is passed the failed "Future" itself in addition to the failure details so it can just return that.

 my $f = F_FIRST()
    ->else_with_f( sub {
       my ( $f1, @failure ) = @_;
       ERROR( @failure );
       return $f1;
    });

The "followed_by" method is similar again, though it invokes the code block regardless of the success or failure of the initial "Future". It can be used to create "finally" semantics. By returning the "Future" instance that it was passed, the "followed_by" code ensures it doesn't affect the result of the operation.

 try {
    FIRST();
 }
 catch {
    ERROR( $_ );
 }
 finally {
    CLEANUP();
 };

 my $f = F_FIRST()
    ->else( sub {
       ERROR( @_ );
       return Future->done;
    })
    ->followed_by( sub {
       CLEANUP();
       return shift;
    });

ITERATION¶

To repeat a single block of code multiple times, a "while" block is often used.

 while( COND() ) {
    FUNC();
 }

The "Future::Utils::repeat" function can be used to repeatedly iterate a given "Future"-returning block of code until its ending condition is satisfied.

 use Future::Utils qw( repeat );
 my $f = repeat {
    F_FUNC();
 } while => sub { COND() };

Unlike the statement nature of perl's "while" block, this "repeat" "Future" can yield a value; the value returned by "$f->get" is the result of the final trial of the code block.

Here, the condition function it expected to return its result immediately. If the repeat condition function itself returns a "Future", it can be combined along with the loop body. The trial "Future" returned by the code block is passed to the "while" condition function.

 my $f = repeat {
    F_FUNC()
       ->followed_by( sub { F_COND(); } );
 } while => sub { shift->result };

The condition can be negated by using "until" instead

 until( HALTING_COND() ) {
    FUNC();
 }

 my $f = repeat {
    F_FUNC();
 } until => sub { HALTING_COND() };

 while(1) {
    TRIAL();
 }

 my $f = repeat {
    F_TRIAL();
 } until => sub { shift->failure };

 my $f = try_repeat {
    F_TRIAL();
 } while => sub { shift->failure };

 while(1) {
    eval { TRIAL(); 1 } and last;
 }

 my $f = try_repeat_until_success {
    F_TRIAL();
 };

 foreach my $thing ( @THINGS ) {
    INSPECT( $thing );
 }

 my $f = repeat {
    my $thing = shift;
    F_INSPECT( $thing );
 } foreach => \@THINGS;

 sub WALK
 {
    my ( $item ) = @_;
    ...
    WALK($_) foreach CHILDREN($item);
 }

 sub WALK
 {
    my @more = ( $root );
    while( @more ) {
       my $item = shift @more;
       ...
       unshift @more, CHILDREN($item)
    }
 }

 my @more = ( $root );
 my $f = fmap_void {
    my $item = shift;
    ...->on_done( sub {
       unshift @more, @CHILDREN;
    })
 } foreach => \@more;

SHORT-CIRCUITING¶

Sometimes a result is determined that should be returned through several levels of control structure. Regular Perl code has such keywords as "return" to return a value from a function immediately, or "last" for immediately stopping execution of a loop.

 sub func {
    foreach my $item ( @LIST ) {
       if( COND($item) ) {
          return $item;
       }
    }
    return MAKE_NEW_ITEM();
 }

The "Future::Utils::call_with_escape" function allows this general form of control flow, by calling a block of code that is expected to return a future, and itself returning a future. Under normal circumstances the result of this future propagates through to the one returned by "call_with_escape".

However, the code is also passed in a future value, called here the "escape future". If the code captures this future and completes it (either by calling "done" or "fail"), then the overall returned future immediately completes with that result instead, and the future returned by the code block is cancelled.

 my $f = call_with_escape {
    my $escape_f = shift;
    ( repeat {
       my $item = shift;
       COND($item)->then( sub {
          my ( $result ) = @_;
          if( $result ) {
             $escape_f->done( $item );
          }
          return Future->done;
       })
    } foreach => \@ITEMS )->then( sub {
       MAKE_NEW_ITEM();
    });
 };

Here, if $escape_f is completed by the condition test, the future chain returned by the code (that is, the "then" chain of the "repeat" block followed by "MAKE_NEW_ITEM()") will be cancelled, and $f itself will receive this result.

CONCURRENCY¶

This final section of the phrasebook demonstrates a number of abilities that are simple to do with "Future" but can't easily be done with regular call/return style programming, because they all involve an element of concurrency. In these examples the comparison with regular call/return code will be somewhat less accurate because of the inherent ability for the "Future"-using version to behave concurrently.

 { FIRST_A(); FIRST_B() }
 SECOND();

 my $f = Future->wait_all( FIRST_A(), FIRST_B() )
    ->then( sub { SECOND() } );

 SECOND( FIRST_A(), FIRST_B() );

 my $f = Future->wait_all( FIRST_A(), FIRST_B() )
    ->then( sub {
       my ( $f_a, $f_b ) = @_
       SECOND( $f_a->result, $f_b->result );
    } );

 my $f = Future->needs_all( FIRST_A(), FIRST_B() )
    ->then( sub { SECOND( @_ ) } );

 my @RESULT = map { FUNC( $_ ) } @ITEMS;
 PROCESS( @RESULT );

 my $f = Future->needs_all( map { F_FUNC( $_ ) } @ITEMS )
    ->then( sub {
       my @RESULT = @_;
       F_PROCESS( @RESULT )
    } );

 my $f = fmap {
    my $item = shift;
    F_FUNC( $item )
 } foreach => \@ITEMS;

 my $f = fmap {
    my $item = shift;
    F_FUNC( $item )
 } foreach => \@ITEMS, concurrent => 10;

 foreach my $item ( @ITEMS ) {
    FUNC( $item );
 }

 my $f = fmap_void {
    my $item = shift;
    F_FIRST( $item )
 } foreach => \@ITEMS, concurrent => 10;

AUTHOR¶

Paul Evans <leonerd@leonerd.org.uk>