view release on metacpan or  search on metacpan

MP.pm  view on Meta::CPAN

   after
);

our $SELF;

sub _self_die() {
   my $msg = $@;
   $msg =~ s/\n+$// unless ref $msg;
   kil $SELF, die => $msg;
}

=item $thisnode = NODE / $NODE

The C<NODE> function returns, and the C<$NODE> variable contains, the node
ID of the node running in the current process. This value is initialised by
a call to C<configure>.

=item $nodeid = node_of $port

Extracts and returns the node ID from a port ID or a node ID.

=item $is_local = port_is_local $port

Returns true iff the port is a local port.

=item configure $profile, key => value...

=item configure key => value...

Before a node can talk to other nodes on the network (i.e. enter
"distributed mode") it has to configure itself - the minimum a node needs
to know is its own name, and optionally it should know the addresses of
some other nodes in the network to discover other nodes.

This function configures a node - it must be called exactly once (or
never) before calling other AnyEvent::MP functions.

The key/value pairs are basically the same ones as documented for the
F<aemp> command line utility (sans the set/del prefix), with these additions:

=over 4

=item norc => $boolean (default false)

If true, then the rc file (e.g. F<~/.perl-anyevent-mp>) will I<not>
be consulted - all configuration options must be specified in the
C<configure> call.

=item force => $boolean (default false)

IF true, then the values specified in the C<configure> will take
precedence over any values configured via the rc file. The default is for
the rc file to override any options specified in the program.

=back

=over 4

=item step 1, gathering configuration from profiles

The function first looks up a profile in the aemp configuration (see the
L<aemp> commandline utility). The profile name can be specified via the
named C<profile> parameter or can simply be the first parameter). If it is
missing, then the nodename (F<uname -n>) will be used as profile name.

The profile data is then gathered as follows:

First, all remaining key => value pairs (all of which are conveniently
undocumented at the moment) will be interpreted as configuration
data. Then they will be overwritten by any values specified in the global
default configuration (see the F<aemp> utility), then the chain of
profiles chosen by the profile name (and any C<parent> attributes).

That means that the values specified in the profile have highest priority
and the values specified directly via C<configure> have lowest priority,
and can only be used to specify defaults.

If the profile specifies a node ID, then this will become the node ID of
this process. If not, then the profile name will be used as node ID, with
a unique randoms tring (C</%u>) appended.

The node ID can contain some C<%> sequences that are expanded: C<%n>
is expanded to the local nodename, C<%u> is replaced by a random
strign to make the node unique. For example, the F<aemp> commandline
utility uses C<aemp/%n/%u> as nodename, which might expand to
C<aemp/cerebro/ZQDGSIkRhEZQDGSIkRhE>.

=item step 2, bind listener sockets

The next step is to look up the binds in the profile, followed by binding
aemp protocol listeners on all binds specified (it is possible and valid
to have no binds, meaning that the node cannot be contacted from the
outside. This means the node cannot talk to other nodes that also have no
binds, but it can still talk to all "normal" nodes).

If the profile does not specify a binds list, then a default of C<*> is
used, meaning the node will bind on a dynamically-assigned port on every
local IP address it finds.

=item step 3, connect to seed nodes

As the last step, the seed ID list from the profile is passed to the
L<AnyEvent::MP::Global> module, which will then use it to keep
connectivity with at least one node at any point in time.

=back

Example: become a distributed node using the local node name as profile.
This should be the most common form of invocation for "daemon"-type nodes.

   configure

Example: become a semi-anonymous node. This form is often used for
commandline clients.

   configure nodeid => "myscript/%n/%u";

Example: configure a node using a profile called seed, which is suitable
for a seed node as it binds on all local addresses on a fixed port (4040,
customary for aemp).