view release on metacpan or  search on metacpan

local/lib/perl5/Future/Phrasebook.pod  view on Meta::CPAN

function.

 OUTER( INNER() );

The result of the first C<Future> is passed into the code block given to the
C<then> method.

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

=head1 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 C<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;
       }
    });

=head1 EXCEPTION HANDLING

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

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

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

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

Alternatively, the second argument to the C<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 C<Future>. In that case, the C<else> code block can
return an immediate C<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 C<else> block could return a new C<Future> failed with
the same exception, the C<else_with_f> block is passed the failed C<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 C<followed_by> method is similar again, though it invokes the code block
regardless of the success or failure of the initial C<Future>. It can be used
to create C<finally> semantics. By returning the C<Future> instance that it
was passed, the C<followed_by> code ensures it doesn't affect the result of
the operation.

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

Z<>

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