view release on metacpan or  search on metacpan

MP.pm  view on Meta::CPAN

=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

=item snd $port, @msg

Send the given message to the given port, which can identify either a
local or a remote port, and must be a port ID.

While the message can be almost anything, it is highly recommended to
use a string as first element (a port ID, or some word that indicates a
request type etc.) and to consist if only simple perl values (scalars,
arrays, hashes) - if you think you need to pass an object, think again.

The message data logically becomes read-only after a call to this
function: modifying any argument (or values referenced by them) is
forbidden, as there can be considerable time between the call to C<snd>
and the time the message is actually being serialised - in fact, it might
never be copied as within the same process it is simply handed to the
receiving port.

The type of data you can transfer depends on the transport protocol: when
JSON is used, then only strings, numbers and arrays and hashes consisting
of those are allowed (no objects). When Storable is used, then anything
that Storable can serialise and deserialise is allowed, and for the local
node, anything can be passed. Best rely only on the common denominator of
these.

=item $local_port = port

Create a new local port object and returns its port ID. Initially it has
no callbacks set and will throw an error when it receives messages.

=item $local_port = port { my @msg = @_ }

Creates a new local port, and returns its ID. Semantically the same as
creating a port and calling C<rcv $port, $callback> on it.

The block will be called for every message received on the port, with the
global variable C<$SELF> set to the port ID. Runtime errors will cause the
port to be C<kil>ed. The message will be passed as-is, no extra argument