NAME
    AnyEvent::MP - multi-processing/message-passing framework

SYNOPSIS
       use AnyEvent::MP;

       $NODE      # contains this node's noderef
       NODE       # returns this node's noderef
       NODE $port # returns the noderef of the port

       snd $port, type => data...;

       $SELF      # receiving/own port id in rcv callbacks

       rcv $port, smartmatch => $cb->($port, @msg);

       # examples:
       rcv $port2, ping => sub { snd $_[0], "pong"; 0 };
       rcv $port1, pong => sub { warn "pong received\n" };
       snd $port2, ping => $port1;

       # more, smarter, matches (_any_ is exported by this module)
       rcv $port, [child_died => $pid] => sub { ...
       rcv $port, [_any_, _any_, 3] => sub { .. $_[2] is 3

DESCRIPTION
    This module (-family) implements a simple message passing framework.

    Despite its simplicity, you can securely message other processes running
    on the same or other hosts.

    For an introduction to this module family, see the AnyEvent::MP::Intro
    manual page.

    At the moment, this module family is severly broken and underdocumented,
    so do not use. This was uploaded mainly to reserve the CPAN namespace -
    stay tuned! The basic API should be finished, however.

CONCEPTS
    port
        A port is something you can send messages to with the "snd"
        function, and you can register "rcv" handlers with. All "rcv"
        handlers will receive messages they match, messages will not be
        queued.

    port id - "noderef#portname"
        A port id is always the noderef, a hash-mark ("#") as separator,
        followed by a port name (a printable string of unspecified format).

    node
        A node is a single process containing at least one port - the node
        port. You can send messages to node ports to let them create new
        ports, among other things.

        Initially, nodes are either private (single-process only) or hidden
        (connected to a master node only). Only when they epxlicitly "become
        public" can you send them messages from unrelated other nodes.

    noderef - "host:port,host:port...", "id@noderef", "id"
        A noderef is a string that either uniquely identifies a given node
        (for private and hidden nodes), or contains a recipe on how to reach
        a given node (for public nodes).

VARIABLES/FUNCTIONS
    $thisnode = NODE / $NODE
        The "NODE" function returns, and the $NODE variable contains the
        noderef of the local node. The value is initialised by a call to
        "become_public" or "become_slave", after which all local port
        identifiers become invalid.

    $noderef = node_of $portid
        Extracts and returns the noderef from a portid or a noderef.

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

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

    snd $portid, type => @data
    snd $portid, @msg
        Send the given message to the given port ID, which can identify
        either a local or a remote port, and can be either a string or
        soemthignt hat stringifies a sa port ID (such as a port object :).

        While the message can be about anything, it is highly recommended to
        use a string as first element (a portid, or some word that indicates
        a request type etc.).

        The message data effectively becomes read-only after a call to this
        function: modifying any argument is not allowed and can cause many
        problems.

        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.

    kil $portid[, @reason]
        Kill the specified port with the given @reason.

        If no @reason is specified, then the port is killed "normally"
        (linked ports will not be kileld, or even notified).

        Otherwise, linked ports get killed with the same reason (second form
        of "mon", see below).

        Runtime errors while evaluating "rcv" callbacks or inside "psub"
        blocks will be reported as reason "die => $@".

        Transport/communication errors are reported as "transport_error =>
        $message".

    $guard = mon $portid, $cb->(@reason)
    $guard = mon $portid, $otherport
    $guard = mon $portid, $otherport, @msg
        Monitor the given port and do something when the port is killed.

        In the first form, the callback is simply called with any number of
        @reason elements (no @reason means that the port was deleted
        "normally"). Note also that *the callback must never die*, so use
        "eval" if unsure.

        In the second form, the other port will be "kil"'ed with @reason,
        iff a @reason was specified, i.e. on "normal" kils nothing happens,
        while under all other conditions, the other port is killed with the
        same reason.

        In the last form, a message of the form "@msg, @reason" will be
        "snd".

        Example: call a given callback when $port is killed.

           mon $port, sub { warn "port died because of <@_>\n" };

        Example: kill ourselves when $port is killed abnormally.

           mon $port, $self;

        Example: send us a restart message another $port is killed.

           mon $port, $self => "restart";

    $guard = mon_guard $port, $ref, $ref...
        Monitors the given $port and keeps the passed references. When the
        port is killed, the references will be freed.

        Optionally returns a guard that will stop the monitoring.

        This function is useful when you create e.g. timers or other
        watchers and want to free them when the port gets killed:

          $port->rcv (start => sub {
             my $timer; $timer = mon_guard $port, AE::timer 1, 1, sub {
                undef $timer if 0.9 < rand;
             });
          });

    lnk $port1, $port2
        Link two ports. This is simply a shorthand for:

           mon $port1, $port2;
           mon $port2, $port1;

        It means that if either one is killed abnormally, the other one gets
        killed as well.

    $local_port = port
        Create a new local port object that supports message matching.

    $portid = port { my @msg = @_; $finished }
        Creates a "mini port", that is, a very lightweight port without any
        pattern matching behind it, and returns its ID.

        The block will be called for every message received on the port.
        When the callback returns a true value its job is considered "done"
        and the port will be destroyed. Otherwise it will stay alive.

        The message will be passed as-is, no extra argument (i.e. no port
        id) will be passed to the callback.

        If you need the local port id in the callback, this works nicely:

           my $port; $port = miniport {
              snd $otherport, reply => $port;
           };

    reg $portid, $name
        Registers the given port under the name $name. If the name already
        exists it is replaced.

        A port can only be registered under one well known name.

        A port automatically becomes unregistered when it is killed.

    rcv $portid, tagstring => $callback->(@msg), ...
    rcv $portid, $smartmatch => $callback->(@msg), ...
    rcv $portid, [$smartmatch...] => $callback->(@msg), ...
        Register callbacks to be called on matching messages on the given
        port.

        The callback has to return a true value when its work is done, after
        which is will be removed, or a false value in which case it will
        stay registered.

        The global $SELF (exported by this module) contains $portid while
        executing the callback.

        Runtime errors wdurign callback execution will result in the port
        being "kil"ed.

        If the match is an array reference, then it will be matched against
        the first elements of the message, otherwise only the first element
        is being matched.

        Any element in the match that is specified as "_any_" (a function
        exported by this module) matches any single element of the message.

        While not required, it is highly recommended that the first matching
        element is a string identifying the message. The one-string-only
        match is also the most efficient match (by far).

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

        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;
              };
           };

FUNCTIONS FOR NODES
    become_public endpoint...
        Tells the node to become a public node, i.e. reachable from other
        nodes.

        If no arguments are given, or the first argument is "undef", then
        AnyEvent::MP tries to bind on port 4040 on all IP addresses that the
        local nodename resolves to.

        Otherwise the first argument must be an array-reference with
        transport endpoints ("ip:port", "hostname:port") or port numbers (in
        which case the local nodename is used as hostname). The endpoints
        are all resolved and will become the node reference.

NODE MESSAGES
    Nodes understand the following messages sent to them. Many of them take
    arguments called @reply, which will simply be used to compose a reply
    message - $reply[0] is the port to reply to, $reply[1] the type and the
    remaining arguments are simply the message data.

    lookup => $name, @reply
        Replies with the port ID of the specified well-known port, or
        "undef".

    devnull => ...
        Generic data sink/CPU heat conversion.

    relay => $port, @msg
        Simply forwards the message to the given port.

    eval => $string[ @reply]
        Evaluates the given string. If @reply is given, then a message of
        the form "@reply, $@, @evalres" is sent.

        Example: crash another node.

           snd $othernode, eval => "exit";

    time => @reply
        Replies the the current node time to @reply.

        Example: tell the current node to send the current time to $myport
        in a "timereply" message.

           snd $NODE, time => $myport, timereply => 1, 2;
           # => snd $myport, timereply => 1, 2, <time>

SEE ALSO
    AnyEvent.

AUTHOR
     Marc Lehmann <schmorp@schmorp.de>
     http://home.schmorp.de/

