---
name: "Role::EventEmitter"
section: "3pm"
platform: "linux"
package: "librole-eventemitter-perl"
version: "0.003-2"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/Role::EventEmitter"
---

# Role::EventEmitter(3pm)

Event emitter role

## 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