Net::Object::Peer

Net::Object::Peer is a Moo Role which implements a publish/subscribe
peer-to-peer messaging system, based upon Beam::Emitter. Objects in the
network may broadcast events to all subscribers or may send events to a
particular subscriber.

Subscriptions and unsubscriptions are tracked and messages will be sent
to affected objects upon request.

While Net::Object::Peer is designed around the concept of nodes being
objects with methods as event handlers, it retains Beam::Emitter's
ability to register code references as well.

Net::Object::Peer::Cookbook provides some recipes.

  Usage

As Net::Object::Peer is purely peer based with no common message bus, a
network is built up by creating a set of network nodes and linking them
via subscriptions.

  my $n1 = Node->new( name => 'N1' );
  my $n2 = Node->new( name => 'N2' );

  $n1->subscribe( $n2, 'changed' );

Here $n1 *subscribes to* $n2's "changed" event. By default, $n1's
"_cb_changed" method is invoked when $n2 emits a "changed" event.

  Events

An emitter must register the events that it will emit. Here's how

1   Class defaults

    A default set of events for the class may be specified by defining
    the "default_events" class method, which should return a list of
    event names:

      sub default_events{ qw[ evt1 evt2 evt3 ] }

2   Object defaults

    During object construction, the events attribute may be used to
    specify a list of events.

3   Runtime manipulation

    The "events" object method may be used to overwrite the list of
    events.

When a subscriber recieves an event, its registered handler for that
event type is invoked. If the object creating the event used the "emit"
or "send" methods,

  $emitter->emit( $event_name );

the event handler will be invoked as

  $subscriber->method( $event );

where $event is an object derived from the Net::Object::Peer::Event
class. (This assumes that the handler is a method; it may be a simple
callback).

If the event was created with the "emit_args" or "send_args" methods,

  $emitter->emit_args( $event_name, @arguments );

the event handler will invoked as

  $subscriber->method( @arguments );

   Subscription and Unsubscription Events

When a subscriber registers one or more event handlers with an emitter
via the subscriber's "subscribe" method, the emitter's
"_notify_subscribed" method will be invoked (if it exists) as

  $emitter->_notify_subscribed( $subscriber, @event_names );

If the subscription already exists, it will be unsubscribed and then
resubscribed.

After a subscriber de-registers a handler, either explicitly via
"unsubscribe" or when the object is destroyed, it will "emit" an
"unsubscribed" event with a Net::Object::Peer::UnsubscribeEvent object
as a payload.

While emitters are not automatically subscribed to "unsubscribed"
events, this is easily accomplished by adding code to the emitters'
"_notify_subscribed" method.

   Detach Events

When an object is destroyed, it emits a "detach" event after
unsubscribing from other peers' events.

INSTALLATION

This is a Perl module distribution. It should be installed with whichever
tool you use to manage your installation of Perl, e.g. any of

  cpanm .
  cpan  .
  cpanp -i .

Consult http://www.cpan.org/modules/INSTALL.html for further instruction.
Should you wish to install this module manually, the procedure is

  perl Makefile.PL
  make
  make test
  make install

COPYRIGHT AND LICENSE

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

This is free software, licensed under:

  The GNU General Public License, Version 3, June 2007
