NAME

BeamX::Peer::Emitter - Beam::Emitter with peer-to-peer messaging

VERSION

version 0.003

SYNOPSIS

 use 5.10.0;
 use Safe::Isa;
 
 sub fmt_msg {
     $_[0]->$_isa( 'Beam::Event' )
       ? sprintf( "received event '%s' from node %s", $_[0]->name, $_[0]->emitter->id )
       : join( ' ', @_ );
 }
 
 
 package Node {
 
     use Safe::Isa;
     use Moo;
     with 'BeamX::Peer::Emitter';
 
     has id => (
         is       => 'ro',
         required => 1,
     );
 
     sub recv {
 
         my $self = shift;
 
         say $self->id, ': ', &::fmt_msg;
     }
 
 }
 
 my $n1 = Node->new( id => 'N1' );
 my $n2 = Node->new( id => 'N2' );
 
 
 # standard Beam::Emitter event
 $n1->subscribe( 'alert', sub { say 'non-peer: ', &fmt_msg  } );
 
 # explicit peer event
 $n1->subscribe( 'alert', sub { $n2->recv( @_ ) }, peer => $n2 );
 
 say "Broadcast Event object:";
 $n1->emit( 'alert' );
 
 say "\nSend Event object directly to \$n2";
 $n1->send( $n2, 'alert' );
 
 say "\nBroadcast arbitrary args";
 $n1->emit_args( 'alert', q[Server's Down!] );
 
 say "\nSend arbitrary args directly to \$n2";
 $n1->send_args( $n2, 'alert', q[Let's get coffee!] );

Results in:

  Broadcast Event object:
  non-peer: received event 'alert' from node N1
  N2: received event 'alert' from node N1

  Send Event object directly to $n2
  N2: received event 'alert' from node N1

  Broadcast arbitrary args
  non-peer: Server's Down!
  N2: Server's Down!

  Send arbitrary args directly to $n2
  N2: Let's get coffee!

DESCRIPTION

BeamX::Peer::Emitter is a role (based upon Beam::Emitter) which adds the ability to notify individual subscribers (peers) of events to Beam::Emitter's publish/subscribe capabilities.

METHODS

subscribe

  # subscribe as Beam::Emitter does
  $emitter->subscribe( $event_name, $subref, [, %args] );

Subscribe to the named event from $emitter. $subref will be called when the event is emitted.

By default, the emitter tracks the listener with an object of class BeamX::Peer::Listener. %args is used to pass arguments to its constructor.

To enable $emitter to send the event directly to a $peer via the send method, specify the peer with the peer key in %args.

  $emitter->subscribe( $event_name, $subref, peer => $peer, %args );

To use a different listener class, subclass BeamX::Peer::Emitter and pass its name via the class key in %args.

  $emitter->subscribe( $event_name, $subref, class => MyListener, %args );

send

  $emitter->send( $peer, $event_name [, %args] );

Send the named event to the specified peer. %args is a list of name, value pairs to pass to the Beam::Event constructor; use the class key to specify an alternate event class.

send_args

  $emitter->send_args( $peer, $event_name, @args] );

Send the named event to the specified peer. @args will be passed to the subscribed callback.

SEE ALSO

Beam::Emitter

AUTHOR

Diab Jerius <djerius@cpan.org>

COPYRIGHT AND LICENSE

This software is Copyright (c) 2016 by the Smithsonian Astrophysical Observatory.

This is free software, licensed under:

  The GNU General Public License, Version 3, June 2007