r39439 - in /trunk/libasync-mergepoint-perl: Build.PL Changes LICENSE MANIFEST META.yml Makefile.PL README debian/changelog lib/Async/MergePoint.pm t/01mergepoint.t t/02lateclose.t t/03lateneeds.t t/99pod.t
jawnsy-guest at users.alioth.debian.org
jawnsy-guest at users.alioth.debian.org
Tue Jul 7 03:57:31 UTC 2009
Author: jawnsy-guest
Date: Tue Jul 7 03:57:25 2009
New Revision: 39439
URL: http://svn.debian.org/wsvn/pkg-perl/?sc=1&rev=39439
Log:
No release necessary
* New upstream release
+ Adds some tests
Added:
trunk/libasync-mergepoint-perl/LICENSE
- copied unchanged from r39438, branches/upstream/libasync-mergepoint-perl/current/LICENSE
trunk/libasync-mergepoint-perl/README
- copied unchanged from r39438, branches/upstream/libasync-mergepoint-perl/current/README
trunk/libasync-mergepoint-perl/t/02lateclose.t
- copied unchanged from r39438, branches/upstream/libasync-mergepoint-perl/current/t/02lateclose.t
trunk/libasync-mergepoint-perl/t/03lateneeds.t
- copied unchanged from r39438, branches/upstream/libasync-mergepoint-perl/current/t/03lateneeds.t
trunk/libasync-mergepoint-perl/t/99pod.t
- copied unchanged from r39438, branches/upstream/libasync-mergepoint-perl/current/t/99pod.t
Modified:
trunk/libasync-mergepoint-perl/Build.PL
trunk/libasync-mergepoint-perl/Changes
trunk/libasync-mergepoint-perl/MANIFEST
trunk/libasync-mergepoint-perl/META.yml
trunk/libasync-mergepoint-perl/Makefile.PL
trunk/libasync-mergepoint-perl/debian/changelog
trunk/libasync-mergepoint-perl/lib/Async/MergePoint.pm
trunk/libasync-mergepoint-perl/t/01mergepoint.t
Modified: trunk/libasync-mergepoint-perl/Build.PL
URL: http://svn.debian.org/wsvn/pkg-perl/trunk/libasync-mergepoint-perl/Build.PL?rev=39439&op=diff
==============================================================================
--- trunk/libasync-mergepoint-perl/Build.PL (original)
+++ trunk/libasync-mergepoint-perl/Build.PL Tue Jul 7 03:57:25 2009
@@ -12,6 +12,8 @@
},
license => 'perl',
create_makefile_pl => 'traditional',
+ create_license => 1,
+ create_readme => 1,
);
$build->create_build_script;
Modified: trunk/libasync-mergepoint-perl/Changes
URL: http://svn.debian.org/wsvn/pkg-perl/trunk/libasync-mergepoint-perl/Changes?rev=39439&op=diff
==============================================================================
--- trunk/libasync-mergepoint-perl/Changes (original)
+++ trunk/libasync-mergepoint-perl/Changes Tue Jul 7 03:57:25 2009
@@ -1,4 +1,10 @@
Revision history for Async-MergePoint
+
+0.03 CHANGES:
+ * use warnings
+ * Allow setting 'on_finished' handler after creation; allow extending
+ the 'needs' keys until then.
+ * Various small updates to keep CPANTS happy
0.02 BUGFIXES:
* Remember to rename IO::Async::MergePoint as Async::MergePoint in
Modified: trunk/libasync-mergepoint-perl/MANIFEST
URL: http://svn.debian.org/wsvn/pkg-perl/trunk/libasync-mergepoint-perl/MANIFEST?rev=39439&op=diff
==============================================================================
--- trunk/libasync-mergepoint-perl/MANIFEST (original)
+++ trunk/libasync-mergepoint-perl/MANIFEST Tue Jul 7 03:57:25 2009
@@ -1,7 +1,12 @@
Build.PL
Changes
lib/Async/MergePoint.pm
+LICENSE
+Makefile.PL
MANIFEST This list of files
+META.yml
+README
t/01mergepoint.t
-Makefile.PL
-META.yml
+t/02lateclose.t
+t/03lateneeds.t
+t/99pod.t
Modified: trunk/libasync-mergepoint-perl/META.yml
URL: http://svn.debian.org/wsvn/pkg-perl/trunk/libasync-mergepoint-perl/META.yml?rev=39439&op=diff
==============================================================================
--- trunk/libasync-mergepoint-perl/META.yml (original)
+++ trunk/libasync-mergepoint-perl/META.yml Tue Jul 7 03:57:25 2009
@@ -1,8 +1,8 @@
---
name: Async-MergePoint
-version: 0.02
+version: 0.03
author:
- - 'Paul Evans E<lt>leonerd at leonerd.org.ukE<gt>'
+ - 'Paul Evans <leonerd at leonerd.org.uk>'
abstract: resynchronise diverged control flow
license: perl
resources:
@@ -13,8 +13,8 @@
provides:
Async::MergePoint:
file: lib/Async/MergePoint.pm
- version: 0.02
-generated_by: Module::Build version 0.3
+ version: 0.03
+generated_by: Module::Build version 0.33
meta-spec:
- url: http://module-build.sourceforge.net/META-spec-v1.2.html
- version: 1.2
+ url: http://module-build.sourceforge.net/META-spec-v1.4.html
+ version: 1.4
Modified: trunk/libasync-mergepoint-perl/Makefile.PL
URL: http://svn.debian.org/wsvn/pkg-perl/trunk/libasync-mergepoint-perl/Makefile.PL?rev=39439&op=diff
==============================================================================
--- trunk/libasync-mergepoint-perl/Makefile.PL (original)
+++ trunk/libasync-mergepoint-perl/Makefile.PL Tue Jul 7 03:57:25 2009
@@ -1,4 +1,4 @@
-# Note: this file was auto-generated by Module::Build::Compat version 0.30
+# Note: this file was auto-generated by Module::Build::Compat version 0.33
use ExtUtils::MakeMaker;
WriteMakefile
(
Modified: trunk/libasync-mergepoint-perl/debian/changelog
URL: http://svn.debian.org/wsvn/pkg-perl/trunk/libasync-mergepoint-perl/debian/changelog?rev=39439&op=diff
==============================================================================
--- trunk/libasync-mergepoint-perl/debian/changelog (original)
+++ trunk/libasync-mergepoint-perl/debian/changelog Tue Jul 7 03:57:25 2009
@@ -1,8 +1,14 @@
-libasync-mergepoint-perl (0.02-2) UNRELEASED; urgency=low
+libasync-mergepoint-perl (0.03-1) UNRELEASED; urgency=low
+ No release necessary
+
+ * New upstream release
+ + Adds some tests
+
+ [ Nathan Handler ]
* debian/watch: Update to ignore development releases.
- -- Nathan Handler <nhandler at ubuntu.com> Sat, 06 Jun 2009 01:32:45 +0000
+ -- Jonathan Yu <frequency at cpan.org> Mon, 06 Jul 2009 20:00:22 -0400
libasync-mergepoint-perl (0.02-1) unstable; urgency=low
Modified: trunk/libasync-mergepoint-perl/lib/Async/MergePoint.pm
URL: http://svn.debian.org/wsvn/pkg-perl/trunk/libasync-mergepoint-perl/lib/Async/MergePoint.pm?rev=39439&op=diff
==============================================================================
--- trunk/libasync-mergepoint-perl/lib/Async/MergePoint.pm (original)
+++ trunk/libasync-mergepoint-perl/lib/Async/MergePoint.pm Tue Jul 7 03:57:25 2009
@@ -6,8 +6,9 @@
package Async::MergePoint;
use strict;
-
-our $VERSION = '0.02';
+use warnings;
+
+our $VERSION = '0.03';
use Carp;
@@ -21,19 +22,22 @@
my $merge = Async::MergePoint->new(
needs => [ "leaves", "water" ],
-
+ );
+
+ my $water;
+ Kettle->boil(
+ on_boiled => sub { $water = shift; $merge->done( "water" ); }
+ );
+
+ my $tea_leaves;
+ Cupboard->get_tea_leaves(
+ on_fetched => sub { $tea_leaves = shift; $merge->done( "leaves" ); }
+ );
+
+ $merge->close(
on_finished => sub {
- my %items = @_;
- # Make tea using $items{leaves} and $items{water}
+ # Make tea using $water and $tea_leaves
}
- );
-
- Kettle->boil(
- on_boiled => sub { $merge->done( "water", $_[0] ) }
- );
-
- Cupboard->get_tea_leaves(
- on_fetched => sub { $merge->done( "leaves", $_[0] ) }
);
=head1 DESCRIPTION
@@ -55,9 +59,12 @@
complete. When all of the required items are so marked, the C<on_finished>
continuation is invoked.
-When an item is marked as complete, a value can also be provided, which would
-contain 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.
+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,
@@ -78,8 +85,50 @@
=item needs => ARRAY
-An array containing unique item names to wait on. The order of this array is
-not significant.
+Optional. An array containing unique item names to wait on. The order of this
+array is not significant.
+
+=item on_finished => CODE
+
+Optional. CODE reference to the continuation for when the merge point becomes
+ready. If provided, will be passed to the C<close> method.
+
+=back
+
+=cut
+
+sub new
+{
+ my $class = shift;
+ my ( %params ) = @_;
+
+ my $self = bless {
+ needs => {},
+ items => {},
+ }, $class;
+
+ if( $params{needs} ) {
+ ref $params{needs} eq 'ARRAY' or croak "Expected 'needs' to be an ARRAY ref";
+ $self->needs( @{ $params{needs} } );
+ }
+
+ if( $params{on_finished} ) {
+ $self->close( on_finished => $params{on_finished} );
+ }
+
+ return $self;
+}
+
+=head1 METHODS
+
+=cut
+
+=head2 $merge->close( %params )
+
+Allows an C<on_finished> continuation to be set if one was not provided to the
+constructor.
+
+=over 8
=item on_finished => CODE
@@ -96,31 +145,52 @@
the values passed to the C<done()> method for each one. Note that this is
passed as a list, not as a HASH reference.
-=cut
-
-sub new
-{
- my $class = shift;
- my ( %params ) = @_;
-
- ref $params{needs} eq 'ARRAY' or croak "Expected 'needs' to be an ARRAY ref";
+While this feature can be used to pass data from the component parts back up
+into the continuation, it may be more direct to use normal lexical variables
+instead. This method allows the continuation to be placed after the blocks of
+code that execute the component parts, so it reads downwards, and may make it
+more readable.
+
+=cut
+
+sub close
+{
+ my $self = shift;
+ my %params = @_;
+
ref $params{on_finished} eq 'CODE' or croak "Expected 'on_finished' to be a CODE ref";
- # Store these as a hash for ease of deletion
- my %needs = map { $_ => 1 } @{ $params{needs} };
-
- my $self = bless {
- needs => \%needs,
- items => {},
- on_finished => $params{on_finished},
- }, $class;
-
- return $self;
-}
-
-=head1 METHODS
-
-=cut
+ $self->{on_finished} and croak "Already have an 'on_finished', can't set another";
+
+ $self->{on_finished} = $params{on_finished};
+
+ if( !keys %{ $self->{needs} } ) {
+ # Execute it now
+ $self->{on_finished}->( %{$self->{items}} );
+ }
+}
+
+=head2 $merge->needs( @keys )
+
+When called on an open MergePoint (i.e. one that does not yet have an
+C<on_finished> continuation), this method adds extra key names to the set of
+outstanding names. The order of this list is not significant.
+
+This method throws an exception if the MergePoint is already closed.
+
+=cut
+
+sub needs
+{
+ my $self = shift;
+
+ $self->{on_finished} and croak "Cannot add extra keys to a closed MergePoint";
+
+ foreach my $key ( @_ ) {
+ $self->{needs}{$key} and croak "Already need '$key'";
+ $self->{needs}{$key}++;
+ }
+}
=head2 $merge->done( $item, $value )
@@ -142,7 +212,7 @@
delete $self->{needs}->{$item};
$self->{items}->{$item} = $value;
- if( !keys %{ $self->{needs} } ) {
+ if( !keys %{ $self->{needs} } and $self->{on_finished} ) {
$self->{on_finished}->( %{$self->{items}} );
}
}
@@ -152,6 +222,51 @@
__END__
+=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 = @_;
+ print "All plugins have recognised $event\n";
+ } );
+
+Each plugin that wishes to handle the event can use its own package name, for
+example, as its unique key name for the MergePoint. A plugin 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 );
+ } );
+ }
+
=head1 AUTHOR
-Paul Evans E<lt>leonerd at leonerd.org.ukE<gt>
+Paul Evans <leonerd at leonerd.org.uk>
Modified: trunk/libasync-mergepoint-perl/t/01mergepoint.t
URL: http://svn.debian.org/wsvn/pkg-perl/trunk/libasync-mergepoint-perl/t/01mergepoint.t?rev=39439&op=diff
==============================================================================
--- trunk/libasync-mergepoint-perl/t/01mergepoint.t (original)
+++ trunk/libasync-mergepoint-perl/t/01mergepoint.t Tue Jul 7 03:57:25 2009
@@ -2,16 +2,10 @@
use strict;
-use Test::More tests => 11;
+use Test::More tests => 9;
use Test::Exception;
use Async::MergePoint;
-
-dies_ok( sub { Async::MergePoint->new( on_finished => sub { "DUMMY" } ) },
- 'No needs' );
-
-dies_ok( sub { Async::MergePoint->new( needs => ['foo'] ) },
- 'No on_finished' );
dies_ok( sub { Async::MergePoint->new( needs => "hello", on_finished => sub { "DUMMY" } ) },
'needs not ARRAY' );
More information about the Pkg-perl-cvs-commits
mailing list