view release on metacpan or  search on metacpan

README  view on Meta::CPAN

        step 1, gathering configuration from profiles
            The function first looks up a profile in the aemp configuration
            (see the aemp commandline utility). The profile name can be
            specified via the named "profile" parameter or can simply be the
            first parameter). If it is missing, then the nodename (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 aemp
            utility), then the chain of profiles chosen by the profile name
            (and any "parent" attributes).

            That means that the values specified in the profile have highest
            priority and the values specified directly via "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 ("/%u") appended.

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

        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
            "*" is used, meaning the node will bind on a
            dynamically-assigned port on every local IP address it finds.

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

        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)"

    $SELF
        Contains the current port id while executing "rcv" callbacks or
        "psub" blocks.

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

    snd $port, type => @data
    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
        "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.

    $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.

    $local_port = port { my @msg = @_ }
        Creates a new local port, and returns its ID. Semantically the same
        as creating a port and calling "rcv $port, $callback" on it.

        The block will be called for every message received on the port,
        with the global variable $SELF set to the port ID. Runtime errors
        will cause the port to be "kil"ed. The message will be passed as-is,
        no extra argument (i.e. no port ID) will be passed to the callback.

        If you want to stop/destroy the port, simply "kil" it: