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

SYNOPSIS
       use AnyEvent::MP;

       NODE    # returns this node identifier
       $NODE   # contains this node identifier

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

       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.

    At the moment, this module family is severly brokena nd underdocumented,
    so do not use. This was uploaded mainly to resreve the CPAN namespace -
    stay tuned!

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
    NODE / $NODE
        The "NODE ()" function and the $NODE variable contain 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.

    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.

    $local_port = create_port
        Create a new local port object. See the next section for allowed
        methods.

METHODS FOR PORT OBJECTS
    "$port"
        A port object stringifies to its port ID, so can be used directly
        for "snd" operations.

    $port->rcv (type => $callback->($port, @msg))
    $port->rcv ($smartmatch => $callback->($port, @msg))
    $port->rcv ([$smartmatch...] => $callback->($port, @msg))
        Register a callback 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.

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

    $port->register ($name)
        Registers the given port under the well known name $name. If the
        name already exists it is replaced.

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

    $port->destroy
        Explicitly destroy/remove/nuke/vaporise the port.

        Ports are normally kept alive by there mere existance alone, and
        need to be destroyed explicitly.

FUNCTIONS FOR NODES
    mon $noderef, $callback->($noderef, $status, $)
        Monitors the given noderef.

    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.

    wkp => $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/

