From Code to Community: Sponsoring The Perl and Raku Conference 2025 Learn more

 / 
Role-EventEmitter-0.003
River stage one • 2 direct dependents • 4 total dependents
/ Role::EventEmitter

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 <dbook@cpan.org>

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