view release on metacpan or  search on metacpan

README  view on Meta::CPAN

           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:

           my $port = port {
              my @msg = @_;
              ...
              kil $SELF;
           };

    rcv $local_port, $callback->(@msg)
        Replaces the default callback on the specified port. There is no way
        to remove the default callback: use "sub { }" to disable it, or
        better "kil" the port when it is no longer needed.

        The global $SELF (exported by this module) contains $port while
        executing the callback. Runtime errors during callback execution
        will result in the port being "kil"ed.

        The default callback receives all messages not matched by a more
        specific "tag" match.

    rcv $local_port, tag => $callback->(@msg_without_tag), ...
        Register (or replace) callbacks to be called on messages starting
        with the given tag on the given port (and return the port), or
        unregister it (when $callback is $undef or missing). There can only
        be one callback registered for each tag.

        The original message will be passed to the callback, after the first
        element (the tag) has been removed. The callback will use the same
        environment as the default callback (see above).

        Example: create a port and bind receivers on it in one go.

          my $port = rcv port,
             msg1 => sub { ... },
             msg2 => sub { ... },
          ;

        Example: create a port, bind receivers and send it in a message
        elsewhere in one go:

           snd $otherport, reply =>
              rcv port,
                 msg1 => sub { ... },
                 ...
           ;

        Example: temporarily register a rcv callback for a tag matching some
        port (e.g. for an rpc reply) and unregister it after a message was
        received.

           rcv $port, $otherport => sub {
              my @reply = @_;

              rcv $SELF, $otherport;
           };

    peval $port, $coderef[, @args]
        Evaluates the given $codref within the context of $port, that is,
        when the code throws an exception the $port will be killed.

        Any remaining args will be passed to the callback. Any return values
        will be returned to the caller.

        This is useful when you temporarily want to execute code in the
        context of a port.

        Example: create a port and run some initialisation code in it's
        context.

           my $port = port { ... };

           peval $port, sub {
              init
                 or die "unable to init";
           };

    $closure = psub { BLOCK }
        Remembers $SELF and creates a closure out of the BLOCK. When the
        closure is executed, sets up the environment in the same way as in
        "rcv" callbacks, i.e. runtime errors will cause the port to get
        "kil"ed.

        The effect is basically as if it returned "sub { peval $SELF, sub {
        BLOCK }, @_ }".

        This is useful when you register callbacks from "rcv" callbacks:

           rcv delayed_reply => sub {
              my ($delay, @reply) = @_;
              my $timer = AE::timer $delay, 0, psub {
                 snd @reply, $SELF;
              };
           };

    $guard = mon $port, $rcvport # kill $rcvport when $port dies
    $guard = mon $port # kill $SELF when $port dies
    $guard = mon $port, $cb->(@reason) # call $cb when $port dies
    $guard = mon $port, $rcvport, @msg # send a message when $port dies
        Monitor the given port and do something when the port is killed or
        messages to it were lost, and optionally return a guard that can be
        used to stop monitoring again.

        The first two forms distinguish between "normal" and "abnormal"
        kil's:

        In the first form (another port given), if the $port is "kil"'ed
        with a non-empty reason, the other port ($rcvport) will be kil'ed
        with the same reason. That is, on "normal" kil's nothing happens,
        while under all other conditions, the other port is killed with the
        same reason.

        The second form (kill self) is the same as the first form, except
        that $rvport defaults to $SELF.

        The remaining forms don't distinguish between "normal" and
        "abnormal" kil's - it's up to the callback or receiver to check
        whether the @reason is empty and act accordingly.

        In the third form (callback), the callback is simply called with any