Async-MergePoint

 view release on metacpan or  search on metacpan

META.json  view on Meta::CPAN

{
   "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",

META.yml  view on Meta::CPAN

---
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

README  view on Meta::CPAN

NAME
    "Async::MergePoint" - resynchronise diverged control flow

SYNOPSIS
     use Async::MergePoint;

     my $merge = Async::MergePoint->new(
        needs => [ "leaves", "water" ],
     );

     my $water;
     Kettle->boil(

README  view on Meta::CPAN

           # 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

README  view on Meta::CPAN

    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 = @_;

README  view on Meta::CPAN

    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 );
    } );