view release on metacpan or  search on metacpan

MP.pm  view on Meta::CPAN

   db_keys   $family => $cb->(\@keys)
   db_values $family => $cb->(\@values)

   # distributed database - monitoring a family
   db_mon $family => $cb->(\%familyhash, \@added, \@changed, \@deleted)

=head1 DESCRIPTION

This module (-family) implements a simple message passing framework.

Despite its simplicity, you can securely message other processes running
on the same or other hosts, and you can supervise entities remotely.

For an introduction to this module family, see the L<AnyEvent::MP::Intro>
manual page and the examples under F<eg/>.

=head1 CONCEPTS

=over 4

=item port

Not to be confused with a TCP port, a "port" is something you can send
messages to (with the C<snd> function).

Ports allow you to register C<rcv> handlers that can match all or just
some messages. Messages send to ports will not be queued, regardless of
anything was listening for them or not.

Ports are represented by (printable) strings called "port IDs".

=item port ID - C<nodeid#portname>

A port ID is the concatenation of a node ID, a hash-mark (C<#>)
as separator, and a port name (a printable string of unspecified
format created by AnyEvent::MP).

=item node

A node is a single process containing at least one port - the node port,
which enables nodes to manage each other remotely, and to create new
ports.

Nodes are either public (have one or more listening ports) or private
(no listening ports). Private nodes cannot talk to other private nodes
currently, but all nodes can talk to public nodes.

Nodes is represented by (printable) strings called "node IDs".

=item node ID - C<[A-Za-z0-9_\-.:]*>

A node ID is a string that uniquely identifies the node within a
network. Depending on the configuration used, node IDs can look like a
hostname, a hostname and a port, or a random string. AnyEvent::MP itself
doesn't interpret node IDs in any way except to uniquely identify a node.

=item binds - C<ip:port>

Nodes can only talk to each other by creating some kind of connection to
each other. To do this, nodes should listen on one or more local transport
endpoints - binds.

Currently, only standard C<ip:port> specifications can be used, which
specify TCP ports to listen on. So a bind is basically just a tcp socket
in listening mode that accepts connections from other nodes.

=item seed nodes

When a node starts, it knows nothing about the network it is in - it
needs to connect to at least one other node that is already in the
network. These other nodes are called "seed nodes".

Seed nodes themselves are not special - they are seed nodes only because
some other node I<uses> them as such, but any node can be used as seed
node for other nodes, and eahc node can use a different set of seed nodes.

In addition to discovering the network, seed nodes are also used to
maintain the network - all nodes using the same seed node are part of the
same network. If a network is split into multiple subnets because e.g. the
network link between the parts goes down, then using the same seed nodes
for all nodes ensures that eventually the subnets get merged again.

Seed nodes are expected to be long-running, and at least one seed node
should always be available. They should also be relatively responsive - a
seed node that blocks for long periods will slow down everybody else.

For small networks, it's best if every node uses the same set of seed
nodes. For large networks, it can be useful to specify "regional" seed
nodes for most nodes in an area, and use all seed nodes as seed nodes for
each other. What's important is that all seed nodes connections form a
complete graph, so that the network cannot split into separate subnets
forever.

Seed nodes are represented by seed IDs.

=item seed IDs - C<host:port>

Seed IDs are transport endpoint(s) (usually a hostname/IP address and a
TCP port) of nodes that should be used as seed nodes.

=item global nodes

An AEMP network needs a discovery service - nodes need to know how to
connect to other nodes they only know by name. In addition, AEMP offers a
distributed "group database", which maps group names to a list of strings
- for example, to register worker ports.

A network needs at least one global node to work, and allows every node to
be a global node.

Any node that loads the L<AnyEvent::MP::Global> module becomes a global
node and tries to keep connections to all other nodes. So while it can
make sense to make every node "global" in small networks, it usually makes
sense to only make seed nodes into global nodes in large networks (nodes
keep connections to seed nodes and global nodes, so making them the same
reduces overhead).

=back

=head1 VARIABLES/FUNCTIONS

=over 4

=cut

package AnyEvent::MP;

use AnyEvent::MP::Config ();
use AnyEvent::MP::Kernel;
use AnyEvent::MP::Kernel qw(
   %NODE %PORT %PORT_DATA $UNIQ $RUNIQ $ID
   add_node load_func

   NODE $NODE
   configure
   node_of port_is_local
   snd kil
   db_set db_del
   db_mon db_family db_keys db_values
);

use common::sense;

use Carp ();

use AnyEvent ();
use Guard ();

use base "Exporter";

our $VERSION = '2.02'; # also in MP/Config.pm

our @EXPORT = qw(
   NODE $NODE
   configure
   node_of port_is_local
   snd kil
   db_set db_del