Role::...mitter(3pm)

💖 Role::EventEmitter — the vibe ✨

okay so this is Role::...mitter(3pm), like from the User Contributed Perl Documentation corner of the perl world, and bestie, it's so good. no cap.

---

🌸 NAME 🌸

Role::EventEmitter — it's an event emitter role. that's the whole name. iconic.

---

✨ SYNOPSIS ✨

okay so picture this: you got a class, you give it the role, boom, it can emit events and everyone can subscribe. watch:

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');

see how clean that is?? emit shouts, on listens. that's the whole dynamic. 💅

---

🦋 DESCRIPTION 🦋

Role::EventEmitter is a simple Role::Tiny role for event emitting objects, and it's based on Mojo::EventEmitter. literally built on top of good taste.

and here's the slay part: this role can be applied to any hash-based object class — so like the ones you make with Class::Tiny, Moo, or Moose. whoever you are, whatever you're running, the role will find you. 🫶

---

🌈 EVENTS 🌈

Role::EventEmitter can emit the following events. yes bestie, there's a whole list.

💀 error

$e->on(error => sub {
  my ($e, $err) = @_;
  ...
});

so this one is a special event for errors. and listen: it will not be emitted directly by this role, but it is fatal if unhandled. like, the whole thing dies. so handle it, bestie, please.

$e->on(error => sub {
  my ($e, $err) = @_;
  say "This looks bad: $err";
});

---

🎀 METHODS 🎀

Role::EventEmitter composes the following methods. here they are, one by one, no skips.

💖 catch

$e = $e->catch(sub {...});

Subscribe to the error event. that's it, that's the shortcut.

# Longer version
$e->on(error => sub {...});

💖 emit

$e = $e->emit('foo');
$e = $e->emit('foo', 123);

Emit event. you can pass args too, go wild.

💖 has_subscribers

my $bool = $e->has_subscribers('foo');

Check if event has subscribers. returns a bool, so you get a lil yes or no. vibe check, basically. ✨

💖 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. one and done. it's giving one-time-use. 🦋

$e->once(foo => sub {
  my ($e, @args) = @_;
  ...
});

💖 once_f

my $f = $e->once_f('foo');

Subscribe to event as in once, but it returns a Future that gets marked complete after it's been emitted once. and heads up: this one requires Future to be installed. so check that first, bestie.

my $f = $e->once_f('foo')->on_done(sub {
  my ($e, @args) = @_;
  ...
});

if you wanna unsubscribe the returned Future early, just cancel it:

$f->cancel;

💖 subscribers

my $subscribers = $e->subscribers('foo');

All subscribers for event. all of them. the whole group chat.

# Unsubscribe last subscriber
$e->unsubscribe(foo => $e->subscribers('foo')->[-1]);

# Change order of subscribers
@{$e->subscribers('foo')} = reverse @{$e->subscribers('foo')};

you can literally just reorder them. rearrange the seating chart. 💅

💖 unsubscribe

$e = $e->unsubscribe('foo');
$e = $e->unsubscribe(foo => $cb);

Unsubscribe from event. and important: related Futures will also be cancelled. so it's a full cleanup, not a half one.

---

🔥 DEBUGGING 🔥

want the tea? set the ROLE_EVENTEMITTER_DEBUG environment variable and you'll get some advanced diagnostics info printed to STDERR. look at her go:

ROLE_EVENTEMITTER_DEBUG=1

---

🙈 BUGS 🙈

Report any issues on the public bugtracker. do it, don't be shy. 🫶

---

👑 AUTHOR 👑

Dan Book <dbook@cpan.org>

Code and tests adapted from Mojo::EventEmitter, an event emitter base class by the Mojolicious team. shoutout to the Mojolicious team fr fr. 🌈

---

⭐ 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

like, the whole extended universe. go read them, iykyk. 🦋

---

and that's the page bestie!! 💖 this one's perl v5.32.1, dated 2021-12-10, and it's still eating. go emit something. periodt. 💅✨