Future::Utils(3) User Contributed Perl Documentation Future::Utils(3)NAME
"Future::Utils" - utility functions for working with "Future" objects
SYNOPSIS
use Future::Utils qw( call_with_escape );
my $result_f = call_with_escape {
my $escape_f = shift;
my $f = ...
$escape_f->done( "immediate result" );
...
};
use Future::Utils qw( repeat try_repeat try_repeat_until_success );
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 = try_repeat {
my $trial_f = ...
return $trial_f;
} while => sub { ... };
my $eventual_f = try_repeat_until_success {
...
return $trial_f;
};
my $eventual_f = try_repeat_until_success {
my $item = shift;
...
return $trial_f;
} foreach => \@items;
use Future::Utils qw( fmap_concat fmap_scalar fmap_void );
my $result_f = fmap_concat {
my $item = shift;
...
return $item_f;
} foreach => \@items, concurrent => 4;
my $result_f = fmap_scalar {
my $item = shift;
...
return $item_f;
} foreach => \@items, concurrent => 8;
my $done_f = fmap_void {
my $item = shift;
...
return $item_f;
} foreach => \@items, concurrent => 10;
INVOKING A BLOCK OF CODE
$f = call { CODE }
The "call" function invokes a block of code that returns a future, and
simply returns the future it returned. The code is wrapped in an "eval
{}" block, so that if it throws an exception this is turned into an
immediate failed "Future". If the code does not return a "Future", then
an immediate failed "Future" instead.
(This is equivalent to using "Future->call", but is duplicated here for
completeness).
$f = call_with_escape { CODE }
The "call_with_escape" function invokes a block of code that returns a
future, and passes in a separate future (called here an "escape
future"). Normally this is equivalent to the simple "call" function.
However, if the code captures this future and completes it by calling
"done" or "fail" on it, the future returned by "call_with_escape"
immediately completes with this result, and the future returned by the
code itself is cancelled.
This can be used to implement short-circuit return from an iterating
loop or complex sequence of code, or immediate fail that bypasses
failure handling logic in the code itself, or several other code
patterns.
$f = $code->( $escape_f )
(This can be considered similar to "call-with-escape-continuation" as
found in some Scheme implementations).
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 first time the code block is
called, it is passed no arguments, and each subsequent invocation is
passed the previous trial 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.
If some specific subclass or instance of "Future" is required as the
return value, it can be passed as the "return" argument. Otherwise the
return value will be constructed by cloning the first non-immediate
trial "Future".
$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->( $previous_trial_f )
$again = $while->( $trial_f )
If the $code block dies entirely and throws an exception, this will be
caught and considered as an immediately-failed "Future" with the
exception as the future's failure. The exception will not be propagated
to the caller.
$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->( $previous_trial_f )
$accept = $until->( $trial_f )
$future = repeat { CODE } foreach => ARRAY, otherwise => CODE
Calls the "CODE" block once for each value obtained from the array,
passing in the value as the first argument (before the previous trial
future). When there are no more items left in the array, the
"otherwise" code is invoked once and passed the last trial future, if
there was one, otherwise "undef" if the list was originally empty. The
result of the eventual future will be the result of the future returned
from "otherwise".
The referenced array may be modified by this operation.
$trial_f = $code->( $item, $previous_trial_f )
$final_f = $otherwise->( $last_trial_f )
The "otherwise" code is optional; if not supplied then the result of
the eventual future will simply be that of the last trial.
$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.
If a "while" or "until" condition is combined with "otherwise", the
"otherwise" code will only be run if the array was entirely exhausted.
If the operation is terminated early due to the "while" or "until"
condition being satisfied, the eventual result will simply be that of
the last trial that was executed.
$future = repeat { CODE } generate => CODE, otherwise => CODE
Calls the "CODE" block once for each value obtained from the generator
code, passing in the value as the first argument (before the previous
trial future). When the generator returns an empty list, the
"otherwise" code is invoked and passed the last trial future, if there
was one, otherwise "undef" if the generator never returned a value. The
result of the eventual future will be the result of the future returned
from "otherwise".
$trial_f = $code->( $item, $previous_trial_f )
$final_f = $otherwise->( $last_trial_f )
( $item ) = $generate->()
The generator is called in list context but should return only one item
per call. Subsequent values will be ignored. When it has no more items
to return it should return an empty list.
For backward compatibility this function will allow a "while" or
"until" condition that requests a failure be repeated, but it will
print a one-time warning if it has to do that. To apply repeating
behaviour that can catch and retry failures, use "try_repeat" instead.
$future = try_repeat { CODE } ...
A variant of "repeat" that doesn't warn when the trial fails and the
condition code asks for it to be repeated.
In some later version the "repeat" function will be changed so that if
a trial future fails, then the eventual future will immediately fail as
well, making its semantics a little closer to that of a "while {}" loop
in Perl. Code that specifically wishes to catch failures in trial
futures and retry the block should use "try_repeat" specifically.
$future = try_repeat_until_success { CODE } ...
A shortcut to calling "try_repeat" with an ending condition that simply
tests for a successful result from a future. May be combined with
"foreach" or "generate".
This function used to be called "repeat_until_success", and is
currently aliased as this name as well.
APPLYING A FUNCTION TO A LIST
The "fmap" family of functions provide a way to call a block of code
that returns a Future (called here an "item future") once per item in a
given list, or returned by a generator function. The "fmap*" functions
themselves return a "Future" to represent the ongoing operation, which
completes when every item's future has completed.
While this behaviour can also be implemented using "repeat", the main
reason to use an "fmap" function is that the individual item operations
are considered as independent, and thus more than one can be
outstanding concurrently. An argument can be passed to the function to
indicate how many items to start initially, and thereafter it will keep
that many of them running concurrently until all of the items are done,
or until any of them fail. If an individual item future fails, the
overall result future will be marked as failing with the same failure,
and any other pending item futures that are outstanding at the time
will be cancelled.
The following named arguments are common to each "fmap*" function:
foreach => ARRAY
Provides the list of items to iterate over, as an "ARRAY"
reference.
The referenced array will be modified by this operation,
"shift"ing one item from it each time. The can "push" more
items to this array as it runs, and they will be included in
the iteration.
generate => CODE
Provides the list of items to iterate over, by calling the
generator function once for each required item. The function
should return a single item, or an empty list to indicate it
has no more items.
( $item ) = $generate->()
This function will be invoked each time any previous item
future has completed and may be called again even after it has
returned empty.
concurrent => INT
Gives the number of item futures to keep outstanding. By
default this value will be 1 (i.e. no concurrency); larger
values indicate that multiple item futures will be started at
once.
return => Future
Normally, a new instance is returned by cloning the first non-
immediate future returned as an item future. By passing a new
instance as the "return" argument, the result will be put into
the given instance. This can be used to return subclasses, or
specific instances.
In each case, the main code block will be called once for each item in
the list, passing in the item as the only argument:
$item_f = $code->( $item )
The expected return value from each item's future, and the value
returned from the result future will differ in each function's case;
they are documented below.
$future = fmap_concat { CODE } ...
This version of "fmap" expects each item future to return a list of
zero or more values, and the overall result will be the concatenation
of all these results. It acts like a future-based equivalent to Perl's
"map" operator.
The results are returned in the order of the original input values, not
in the order their futures complete in. Because of the intermediate
storage of "ARRAY" references and final flattening operation used to
implement this behaviour, this function is slightly less efficient than
"fmap_scalar" or "fmap_void" in cases where item futures are expected
only ever to return one, or zero values, respectively.
This function is also available under the name of simply "fmap" to
emphasise its similarity to perl's "map" keyword.
$future = fmap_scalar { CODE } ...
This version of "fmap" acts more like the "map" functions found in
Scheme or Haskell; it expects that each item future returns only one
value, and the overall result will be a list containing these, in order
of the original input items. If an item future returns more than one
value the others will be discarded. If it returns no value, then
"undef" will be substituted in its place so that the result list
remains in correspondence with the input list.
This function is also available under the shorter name of "fmap1".
$future = fmap_void { CODE } ...
This version of "fmap" does not collect any results from its item
futures, it simply waits for them all to complete. Its result future
will provide no values.
While not a map in the strictest sense, this variant is still useful as
a way to control concurrency of a function call iterating over a list
of items, obtaining its results by some other means (such as side-
effects on captured variables, or some external system).
This function is also available under the shorter name of "fmap0".
AUTHOR
Paul Evans <leonerd@leonerd.org.uk>
perl v5.18.2 2014-05-14 Future::Utils(3)
