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

cpanm BeamX::Peer::Emitter

perl -MCPAN -e shell
install BeamX::Peer::Emitter