NAME
Mixin::Event::Dispatch - mixin methods for simple event/message dispatch framework
VERSION
version 0.003
SYNOPSIS
# Add a handler then invoke it
my $obj = Some::Class->new;
$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 ("add_event_handler") 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:
event_error
- if a handler is available, this will be called instead of dying whenever any other handler dies. If anevent_error
handler also fails, then this error will be re-thrown. As with the other handlers, you can have more than oneevent_error
handler.
API HISTORY
Note that 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).
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.
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.
WHY NOT A ROLE?
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.
SEE ALSO
There are at least a dozen similar modules already on CPAN, eventually I'll add a list of them here.
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. Licensed under the same terms as Perl itself.