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



Annotate this POD


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


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


version 1.004


 # 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 = @_;
                map { (/^on_(.*)$/) ? ($1 => $args{$_}) : () } keys %args
        return $self;


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.


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



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


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:

   some_event => (my $code = sub { }),
   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.


Adds handlers to the stack for the given events.

   new_message => sub { warn @_; 1 },
   login => sub { warn @_; 1 },
   logout => sub { warn @_; 1 },


Accessor for the event stack itself - should return a hashref which maps event names to arrayrefs for the currently defined 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.


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


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)


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:


Tom Molesworth <>

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.


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

syntax highlighting: