Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/grinnz/role-eventemitter

Role::EventEmitter - Event emitter role
https://github.com/grinnz/role-eventemitter

Last synced: 5 days ago
JSON representation

Role::EventEmitter - Event emitter role

Awesome Lists containing this project

README 

        
=pod



=head1 NAME



Role::EventEmitter - Event emitter role



=head1 SYNOPSIS



  package Channel;

  use Class::Tiny; # or object system of choice

  use Role::Tiny::With;

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



=head1 DESCRIPTION



L is a simple L role for event emitting objects

based on L. This role can be applied to any hash-based

object class such as those created with L, L, or L.



=head1 EVENTS



L can emit the following events.



=head2 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";

  });



=head1 METHODS



L composes the following methods.



=head2 catch



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



Subscribe to L"error"> event.



  # Longer version

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



=head2 emit



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

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



Emit event.



=head2 has_subscribers



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



Check if event has subscribers.



=head2 on



  my $cb = $e->on(foo => sub {...});



Subscribe to event.



  $e->on(foo => sub {

    my ($e, @args) = @_;

    ...

  });



=head2 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) = @_;

    ...

  });



=head2 once_f



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



Subscribe to event as in L"once">, returning a L that will be marked

complete after it has been emitted once. Requires L to be installed.



  my $f = $e->once_f('foo')->on_done(sub {

    my ($e, @args) = @_;

    ...

  });



To unsubscribe the returned L early, cancel it or any subsequent

chained L.



  $f->cancel;



=head2 once_p



  my $p = $e->once_p('foo');



Subscribe to event as in L"once">, returning a L that will be

resolved after it has been emitted once. Requires L to be

installed. Note that promises will not settle (or continue the chain) until the

next tick of the L.



  my $p = $e->once_p('foo')->then(sub {

    my ($e, @args) = @_;

    ...

  });

  $e->emit('foo');

  $p->wait;



Resolving or rejecting the originally returned L will

unsubscribe it early. Note that this must be done on the returned promise and

not a chained promise!



  my $p = $e->once_p('foo');

  $p->then(sub { ... });

  $p->reject;



=head2 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')};



=head2 unsubscribe



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

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



Unsubscribe from event. Related Futures will also be cancelled.



=head1 DEBUGGING



You can set the C environment variable to get some

advanced diagnostics information printed to C.



  ROLE_EVENTEMITTER_DEBUG=1



=head1 BUGS



Report any issues on the public bugtracker.



=head1 AUTHOR



Dan Book 



Code and tests adapted from L, an event emitter base class

by the L team.



=head1 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)



=head1 SEE ALSO



L, L, L,

L



=cut