NAME

Future::Utils - utility functions for working with Future objects

SYNOPSIS

use Future::Utils qw( repeat );

my $eventual_f = repeat {
   my $trial_f = ...
   return $trial_f;
} while => sub { my $f = shift; return want_more($f) };

my $eventual_f = repeat {
   ...
   return $trail_f;
} until => sub { my $f = shift; return acceptable($f) };

my $eventual_f = repeat {
   my $item = shift;
   ...
   return $trial_f;
} foreach => \@items;

my $eventual_f = repeat_until_success {
   ...
   return $trial_f;
};

my $eventual_f = repeat_until_success {
   my $item = shift;
   ...
   return $trial_f;
} foreach => \@items;

REPEATING A BLOCK OF CODE

The repeat function provides a way to repeatedly call a block of code that returns a Future (called here a "trial future") until some ending condition is satisfied. The repeat function itself returns a Future to represent running the repeating loop until that end condition (called here the "eventual future").

The result of the eventual future is the result of the last trial future.

If the eventual future is cancelled, the latest trial future will be cancelled.

The eventual future is obtained by calling the new clone constructor on the first trial future returned by calling the code block the first time, allowing it to correctly respect subclassing.

$future = repeat { CODE } while => CODE

Repeatedly calls the CODE block while the while condition returns a true value. Each time the trial future completes, the while condition is passed the trial future.

$trial_f = $code->()
$again = $while->( $trial_f )

$future = repeat { CODE } until => CODE

Repeatedly calls the CODE block until the until condition returns a true value. Each time the trial future completes, the until condition is passed the trial future.

$trial_f = $code->()
$accept = $while->( $trial_f )

$future = repeat { CODE } foreach => ARRAY

Calls the CODE block once for each value obtained from the array. The result of the eventual future will be the result from the final trial. The referenced array may be modified by this operation.

$trial_f = $code->( $item )

$future = repeat { CODE } foreach => ARRAY, while => CODE

$future = repeat { CODE } foreach => ARRAY, until => CODE

Combines the effects of foreach with while or until. Calls the CODE block once for each value obtained from the array, until the array is exhausted or the given ending condition is satisfied.

$future = repeat_until_success { CODE } ...

A shortcut to calling repeat with an ending condition that simply tests for a successful result from a future. May be combined with foreach.

AUTHOR

Paul Evans <leonerd@leonerd.org.uk>