view release on metacpan or  search on metacpan

MP.pm  view on Meta::CPAN

=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).

   # use the aemp commandline utility
   # aemp profile seed binds '*:4040'

   # then use it
   configure profile => "seed";

   # or simply use aemp from the shell again:
   # aemp run profile seed

   # or provide a nicer-to-remember nodeid
   # aemp run profile seed nodeid "$(hostname)"

=item $SELF

Contains the current port id while executing C<rcv> callbacks or C<psub>
blocks.

=item *SELF, SELF, %SELF, @SELF...

Due to some quirks in how perl exports variables, it is impossible to
just export C<$SELF>, all the symbols named C<SELF> are exported by this
module, but only C<$SELF> is currently used.

=item snd $port, type => @data