Async-MergePoint
view release on metacpan or search on metacpan
{
"abstract" : "resynchronise diverged control flow",
"author" : [
"Paul Evans <leonerd@leonerd.org.uk>"
],
"dynamic_config" : 1,
"generated_by" : "Module::Build version 0.38, CPAN::Meta::Converter version 2.110930",
"license" : [
"perl_5"
],
"meta-spec" : {
"url" : "http://search.cpan.org/perldoc?CPAN::Meta::Spec",
---
abstract: 'resynchronise diverged control flow'
author:
- 'Paul Evans <leonerd@leonerd.org.uk>'
build_requires:
Test::Fatal: 0
Test::More: 0
dynamic_config: 1
generated_by: 'Module::Build version 0.38, CPAN::Meta::Converter version 2.110930'
license: perl
meta-spec:
url: http://module-build.sourceforge.net/META-spec-v1.4.html
NAME
"Async::MergePoint" - resynchronise diverged control flow
SYNOPSIS
use Async::MergePoint;
my $merge = Async::MergePoint->new(
needs => [ "leaves", "water" ],
);
my $water;
Kettle->boil(
# Make tea using $water and $tea_leaves
}
);
DESCRIPTION
Often in program logic, multiple different steps need to be taken that
are independent of each other, but their total result is needed before
the next step can be taken. In synchonous code, the usual approach is to
do them sequentially.
An asynchronous or event-based program could do this, but if each step
involves some IO idle time, better overall performance can often be
gained by running the steps in parallel. A "Async::MergePoint" object
can then be used to wait for all of the steps to complete, before
passing the combined result of each step on to the next stage.
A merge point maintains a set of outstanding operations it is waiting
on; these are arbitrary string values provided at the object's
construction. Each time the "done()" method is called, the named item is
marked as being complete. When all of the required items are so marked,
the "on_finished" continuation is invoked.
For use cases where code may be split across several different lexical
scopes, it may not be convenient or possible to share a lexical
variable, to pass on the result of some asynchronous operation. In these
cases, when an item is marked as complete a value can also be provided
which contains the results of that step. The "on_finished" callback is
passed a hash (in list form, rather than by reference) of the collected
item values.
This module was originally part of the IO::Async distribution, but was
removed under the inspiration of Pedro Melo's Async::Hooks distribution,
because it doesn't itself contain anything IO-specific.
CONSTRUCTOR
This method throws an exception if the MergePoint is already closed.
$merge->done( $item, $value )
This method informs the merge point that the $item is now ready, and
passes it a value to store, to be passed into the "on_finished"
continuation. If this call gives the final remaining item being waited
for, the "on_finished" continuation is called within it, and the method
will not return until it has completed.
EXAMPLES
Asynchronous Plugins
Consider a program using "Module::Pluggable" to provide a plugin
architecture to respond to events, where sometimes the response to an
event may require asynchronous work. A "MergePoint" object can be used
to coordinate the responses from the plugins to this event.
my $merge = Async::MergePoint->new();
foreach my $plugin ( $self->plugins ) {
$plugin->handle_event( "event", $merge, @args );
}
$merge->close( on_finished => sub {
my %results = @_;
handling the event synchonously could perform something such as:
sub handle_event
{
my ( $event, $merge, @args ) = @_;
....
$merge->needs( __PACKAGE__ );
$merge->done( __PACKAGE__ => $result );
}
Whereas, to handle the event asynchronously the plugin can instead
perform:
sub handle_event
{
my ( $event, $merge, @args ) = @_;
....
$merge->needs( __PACKAGE__ );
sometime_later( sub {
$merge->done( __PACKAGE__ => $result );
lib/Async/MergePoint.pm view on Meta::CPAN
use strict;
use warnings;
our $VERSION = '0.04';
use Carp;
=head1 NAME
C<Async::MergePoint> - resynchronise diverged control flow
=head1 SYNOPSIS
use Async::MergePoint;
my $merge = Async::MergePoint->new(
needs => [ "leaves", "water" ],
);
my $water;
lib/Async/MergePoint.pm view on Meta::CPAN
}
);
=head1 DESCRIPTION
Often in program logic, multiple different steps need to be taken that are
independent of each other, but their total result is needed before the next
step can be taken. In synchonous code, the usual approach is to do them
sequentially.
An asynchronous or event-based program could do this, but if each step
involves some IO idle time, better overall performance can often be gained by
running the steps in parallel. A C<Async::MergePoint> object can then be used
to wait for all of the steps to complete, before passing the combined result
of each step on to the next stage.
A merge point maintains a set of outstanding operations it is waiting on;
these are arbitrary string values provided at the object's construction. Each
time the C<done()> method is called, the named item is marked as being
complete. When all of the required items are so marked, the C<on_finished>
continuation is invoked.
For use cases where code may be split across several different lexical scopes,
it may not be convenient or possible to share a lexical variable, to pass on
the result of some asynchronous operation. In these cases, when an item is
marked as complete a value can also be provided which contains the results of
that step. The C<on_finished> callback is passed a hash (in list form, rather
than by reference) of the collected item values.
This module was originally part of the L<IO::Async> distribution, but was
removed under the inspiration of Pedro Melo's L<Async::Hooks> distribution,
because it doesn't itself contain anything IO-specific.
=cut
lib/Async/MergePoint.pm view on Meta::CPAN
delete $self->{needs}->{$item};
$self->{items}->{$item} = $value;
if( !keys %{ $self->{needs} } and $self->{on_finished} ) {
$self->{on_finished}->( %{$self->{items}} );
}
}
=head1 EXAMPLES
=head2 Asynchronous Plugins
Consider a program using C<Module::Pluggable> to provide a plugin architecture
to respond to events, where sometimes the response to an event may require
asynchronous work. A C<MergePoint> object can be used to coordinate the
responses from the plugins to this event.
my $merge = Async::MergePoint->new();
foreach my $plugin ( $self->plugins ) {
$plugin->handle_event( "event", $merge, @args );
}
$merge->close( on_finished => sub {
my %results = @_;
lib/Async/MergePoint.pm view on Meta::CPAN
event synchonously could perform something such as:
sub handle_event
{
my ( $event, $merge, @args ) = @_;
....
$merge->needs( __PACKAGE__ );
$merge->done( __PACKAGE__ => $result );
}
Whereas, to handle the event asynchronously the plugin can instead perform:
sub handle_event
{
my ( $event, $merge, @args ) = @_;
....
$merge->needs( __PACKAGE__ );
sometime_later( sub {
$merge->done( __PACKAGE__ => $result );
} );
( run in 0.539 second using v1.01-cache-2.11-cpan-0d8aa00de5b )