Tom Molesworth > Mixin-Event-Dispatch-1.004 > Mixin::Event::Dispatch

Download:
Mixin-Event-Dispatch-1.004.tar.gz

Dependencies

Annotate this POD

Website

View/Report Bugs
Module Version: 1.004   Source   Latest Release: Mixin-Event-Dispatch-1.006

NAME ^

Mixin::Event::Dispatch - mixin methods for simple event/message dispatch framework

VERSION ^

version 1.004

SYNOPSIS ^

 # Add a handler then invoke it
 package Some::Class;
 use parent qw(Mixin::Event::Dispatch);
 sub new { bless {}, shift }

 my $obj = Some::Class->new;

 # Subscribe to events - subscribers will be called with an event object,
 # and any event parameters, each time the event is raised.
 $obj->subscribe_to_event(another_event => (my $code = sub {
   my $ev = shift;
   warn "[] @_";
 }));
 $obj->invoke_event(another_event => 'like this');
 # should get output 'Event data: like this'
 $obj->unsubscribe_from_event(another_event => $code);

 $obj->trace_events_for(sub {
   $obj->invoke_event(another_event => 'like this');
 });

 # Note that handlers will be called for each instance of an event until they return false,
 # at which point the handler will be removed, so for a permanent handler, make sure to return 1.
 $obj->add_handler_for_event(some_event => sub { my $self = shift; warn "had some_event: @_"; 1; });
 $obj->invoke_event(some_event => 'message here');

 # Attach event handler for all on_XXX named parameters
 package Event::User;
 sub configure {
        my $self = shift;
        my %args = @_;
        $self->add_handler_for_event(
                map { (/^on_(.*)$/) ? ($1 => $args{$_}) : () } keys %args
        );
        return $self;
 }

DESCRIPTION ^

Add this in as a parent to your class, and it'll provide some methods for defining event handlers ("subscribe_to_event" or "add_handler_for_event") and calling them ("invoke_event").

Note that handlers should return 0 for a one-off handler, and 1 if it should be called again on the next event.

SPECIAL EVENTS ^

A single event has been reserved for cases where a callback dies:

METHODS ^

invoke_event

Takes an event parameter, and optional additional parameters that are passed to any callbacks.

 $self->invoke_event('new_message', from => 'fred', subject => 'test message');

Returns $self if a handler was found, undef if not.

subscribe_to_event

Subscribe the given coderef to the named event.

Called with a list of event name and handler pairs. An event name can be any string value. The handler is one of the following:

If you have an overloaded object which is both a Mixin::Event::Dispatch subclass and provides a coderef overload, it will default to event delegation behaviour. To ensure the overloaded coderef is used instead, pass \&$obj instead.

All handlers will be given an event (a Mixin::Event::Dispatch::Event object) as the first parameter, and any passed event parameters as the remainder of @_.

Example usage:

 my $parent = $obj->parent;
 $obj->subscribe_to_event(
   connect => sub { warn shift->name }, # warns 'connect'
   connect => $parent, # $parent->invoke_event(connect => @_)
   connect => \&$parent, # $parent's overloaded &{}
   joined  => 'on_joined', # the on_joined method in $obj
 );

Note that multiple handlers can be assigned to the same event name.

unsubscribe_from_event

Removes the given coderef from the list of handlers for this event.

Expects pairs of (event name, coderef) entries for the events to unsubscribe from.

Example usage:

 $obj->subscribe_to_event(
   some_event => (my $code = sub { }),
 );
 $obj->unsubscribe_from_event(
   some_event => $code,
 );

If you need to unsubscribe from the event currently being handled, try the "unsubscribe" in Mixin::Event::Dispatch::Event method.

Returns $self.

add_handler_for_event

Adds handlers to the stack for the given events.

 $self->add_handler_for_event(
   new_message => sub { warn @_; 1 },
   login => sub { warn @_; 1 },
   logout => sub { warn @_; 1 },
 );

event_handlers

Accessor for the event stack itself - should return a hashref which maps event names to arrayrefs for the currently defined handlers.

clear_event_handlers

Removes all queued event handlers.

Will also be called when defining the first handler to create the initial "event_handlers" entry, should be overridden by subclass if something other than $self->{event_handlers} should be used.

API HISTORY ^

Version 1.000 implemented "subscribe_to_event" and Mixin::Event::Dispatch::Event.

Version 0.002 changed to use "event_handlers" instead of event_stack for storing the available handlers (normally only invoke_event and add_handler_for_event are expected to be called directly).

ROLE vs. MIXIN ^

Most role systems should be able to use this class - either directly, or through a thin wrapper which adds any required boilerplate. Try Moose or Role::Tiny / Moo::Role for that.

Alternatively, you could use this as a component via Class::C3::Componentised.

(I haven't tried any of the above options myself, please let me know if I'm spreading disinformation here)

SEE ALSO ^

There are at least a dozen similar modules already on CPAN, here's a small sample:

Note that some frameworks such as Reflex and POE already have comprehensive message-passing and callback interfaces.

If you're looking for usage examples, try the following:

AUTHOR ^

Tom Molesworth <cpan@entitymodel.com>

with thanks to various helpful people on freenode #perl who suggested making "event_handlers" into an accessor (to support non-hashref objects) and who patiently tried to explain about roles.

LICENSE ^

Copyright Tom Molesworth 2011-2013, based on code originally part of EntityModel. Licensed under the same terms as Perl itself.

syntax highlighting: