NAME Role::EventEmitter - Event emitter role SYNOPSIS package Channel; use Moo; with 'Role::EventEmitter'; # Emit events sub send_message { my $self = shift; $self->emit(message => @_); } package main; # Subscribe to events my $channel_a = Channel->new; $channel_a->on(message => sub { my ($channel, $text) = @_; say "Received message: $text"; }); $channel_a->send_message('All is well'); DESCRIPTION Role::EventEmitter is a simple Role::Tiny role for event emitting objects based on Mojo::EventEmitter. This role can be applied to any hash-based object class such as those created with Class::Tiny, Moo, or Moose. EVENTS Role::EventEmitter can emit the following events. error $e->on(error => sub { my ($e, $err) = @_; ... }); This is a special event for errors, it will not be emitted directly by this role but is fatal if unhandled. $e->on(error => sub { my ($e, $err) = @_; say "This looks bad: $err"; }); METHODS Role::EventEmitter composes the following methods. catch $e = $e->catch(sub {...}); Subscribe to "error" event. # Longer version $e->on(error => sub {...}); emit $e = $e->emit('foo'); $e = $e->emit('foo', 123); Emit event. has_subscribers my $bool = $e->has_subscribers('foo'); Check if event has subscribers. on my $cb = $e->on(foo => sub {...}); Subscribe to event. $e->on(foo => sub { my ($e, @args) = @_; ... }); once my $cb = $e->once(foo => sub {...}); Subscribe to event and unsubscribe again after it has been emitted once. $e->once(foo => sub { my ($e, @args) = @_; ... }); once_f my $f = $e->once_f('foo'); Subscribe to event as in "once", returning a Future that will be marked complete after it has been emitted once. Requires Future to be installed. my $f = $e->once_f('foo')->on_done(sub { my ($e, @args) = @_; ... }); To unsubscribe the returned Future early, cancel it. $f->cancel; subscribers my $subscribers = $e->subscribers('foo'); All subscribers for event. # Unsubscribe last subscriber $e->unsubscribe(foo => $e->subscribers('foo')->[-1]); # Change order of subscribers @{$e->subscribers('foo')} = reverse @{$e->subscribers('foo')}; unsubscribe $e = $e->unsubscribe('foo'); $e = $e->unsubscribe(foo => $cb); Unsubscribe from event. Related Futures will also be cancelled. DEBUGGING You can set the ROLE_EVENTEMITTER_DEBUG environment variable to get some advanced diagnostics information printed to STDERR. ROLE_EVENTEMITTER_DEBUG=1 BUGS Report any issues on the public bugtracker. AUTHOR Dan Book Code and tests adapted from Mojo::EventEmitter, an event emitter base class by the Mojolicious team. COPYRIGHT AND LICENSE Copyright (c) 2008-2015 Sebastian Riedel. Copyright (c) 2015 Dan Book for adaptation to a role and further changes. This is free software, licensed under: The Artistic License 2.0 (GPL Compatible) SEE ALSO Mojo::EventEmitter, Mixin::Event::Dispatch, Beam::Emitter, Event::Distributor