NAME

Event::Join - join multiple "events" into one

SYNOPSIS

    use Event::Join;

    my $joiner = Event::Join->new(
        on_completion => sub {
            my $events = shift;
            say 'Child exited with status '. $events->{child_done};
        },
        events => [qw/stdout_closed child_done/],
    );

    watch_fh $stdout, on_eof  => sub { $joiner->send_event('stdout_closed') };
    watch_child $pid, on_exit => sub { $joiner->send_event('child_done', $_[0]) };

    start_main_loop;

DESCRIPTION

When writing event-based programs, you often want to wait for a number of events to occur, and then do something. This module allows you to do that without blocking. It simply acts as a receiver for a number of events, and then calls a callback when all events have occurred.

Note that although I mainly use this for "real" event-based programming, the technique is rather versatile. A config file parser could be implemented like this:

   my $parsed_doc;
   my $parser_state = Event::Join->new(
       events        => [qw/username password machine_name/],
       on_completion => sub { $parsed_doc = shift },
   );

   while(!$parsed_doc && (my $line = <$fh>)){
       chomp $line;
       my ($k, $v) = split /:/, $line;
       $parser_state->send_event($k, $v);
   }

   say 'Username is '. $parsed_doc->{username};

METHODS

new

Create an instance. Needs to be passed events, an arrayref of valid event names, and on_completion, a coderef to call after all events have been received. This coderef is passed a hashref of events and their values, and will only ever be called once (or not at all, if the events never arrive).

send_event( $event_name, [$event_value] )

Send an event. $event_name is required, and must be an event that was passed to the constructor. An exception will be thrown if the name is not valid.

$event_value is optional; is is the value that goes into the hash to be passed to the callback. It can be true or false -- its value does not affect whether or not the completino callback is called.

Finally, an exception is thrown if an event is sent more than once.

event_sent( $event_name )

Returns true if the event has been sent, false otherwise. Note that the true value is not the value that was passed to send_event, it is just an arbitrary non-false value.

event_sender_for( $event_name )

Returns a coderef that sends $event_name when run. The first argument to the coderef will become the second argument to send_event.

PATCHES

Is the module totally broken? Patch my repository at:

    http://github.com/jrockway/event-join

AUTHOR

Jonathan Rockway <jrockway@cpan.org>

COPYRIGHT

Copyright (c) 2009 Jonathan Rockway.

This module is Free Software. You may distribute it under the same terms as Perl itself.