view release on metacpan or  search on metacpan

README  view on Meta::CPAN

       # distributed database - modification
       db_set $family => $subkey [=> $value]  # add a subkey
       db_del $family => $subkey...           # delete one or more subkeys
       db_reg $family => $port [=> $value]    # register a port

       # distributed database - queries
       db_family $family => $cb->(\%familyhash)
       db_keys   $family => $cb->(\@keys)
       db_values $family => $cb->(\@values)

       # distributed database - monitoring a family
       db_mon $family => $cb->(\%familyhash, \@added, \@changed, \@deleted)

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, and you can supervise entities remotely.

    For an introduction to this module family, see the AnyEvent::MP::Intro
    manual page and the examples under eg/.

CONCEPTS
    port
        Not to be confused with a TCP port, a "port" is something you can
        send messages to (with the "snd" function).

        Ports allow you to register "rcv" handlers that can match all or
        just some messages. Messages send to ports will not be queued,
        regardless of anything was listening for them or not.

        Ports are represented by (printable) strings called "port IDs".

    port ID - "nodeid#portname"
        A port ID is the concatenation of a node ID, a hash-mark ("#") as
        separator, and a port name (a printable string of unspecified format
        created by AnyEvent::MP).

    node
        A node is a single process containing at least one port - the node
        port, which enables nodes to manage each other remotely, and to
        create new ports.

        Nodes are either public (have one or more listening ports) or
        private (no listening ports). Private nodes cannot talk to other
        private nodes currently, but all nodes can talk to public nodes.

        Nodes is represented by (printable) strings called "node IDs".

    node ID - "[A-Za-z0-9_\-.:]*"
        A node ID is a string that uniquely identifies the node within a
        network. Depending on the configuration used, node IDs can look like
        a hostname, a hostname and a port, or a random string. AnyEvent::MP
        itself doesn't interpret node IDs in any way except to uniquely
        identify a node.

    binds - "ip:port"
        Nodes can only talk to each other by creating some kind of
        connection to each other. To do this, nodes should listen on one or
        more local transport endpoints - binds.

        Currently, only standard "ip:port" specifications can be used, which
        specify TCP ports to listen on. So a bind is basically just a tcp
        socket in listening mode that accepts connections from other nodes.

    seed nodes
        When a node starts, it knows nothing about the network it is in - it
        needs to connect to at least one other node that is already in the
        network. These other nodes are called "seed nodes".

        Seed nodes themselves are not special - they are seed nodes only
        because some other node *uses* them as such, but any node can be
        used as seed node for other nodes, and eahc node can use a different
        set of seed nodes.

        In addition to discovering the network, seed nodes are also used to
        maintain the network - all nodes using the same seed node are part
        of the same network. If a network is split into multiple subnets
        because e.g. the network link between the parts goes down, then
        using the same seed nodes for all nodes ensures that eventually the
        subnets get merged again.

        Seed nodes are expected to be long-running, and at least one seed
        node should always be available. They should also be relatively
        responsive - a seed node that blocks for long periods will slow down
        everybody else.

        For small networks, it's best if every node uses the same set of
        seed nodes. For large networks, it can be useful to specify
        "regional" seed nodes for most nodes in an area, and use all seed
        nodes as seed nodes for each other. What's important is that all
        seed nodes connections form a complete graph, so that the network
        cannot split into separate subnets forever.

        Seed nodes are represented by seed IDs.

    seed IDs - "host:port"
        Seed IDs are transport endpoint(s) (usually a hostname/IP address
        and a TCP port) of nodes that should be used as seed nodes.

    global nodes
        An AEMP network needs a discovery service - nodes need to know how
        to connect to other nodes they only know by name. In addition, AEMP
        offers a distributed "group database", which maps group names to a
        list of strings - for example, to register worker ports.

        A network needs at least one global node to work, and allows every
        node to be a global node.

        Any node that loads the AnyEvent::MP::Global module becomes a global
        node and tries to keep connections to all other nodes. So while it
        can make sense to make every node "global" in small networks, it
        usually makes sense to only make seed nodes into global nodes in
        large networks (nodes keep connections to seed nodes and global
        nodes, so making them the same reduces overhead).

VARIABLES/FUNCTIONS
    $thisnode = NODE / $NODE
        The "NODE" function returns, and the $NODE variable contains, the
        node ID of the node running in the current process. This value is
        initialised by a call to "configure".

    $nodeid = node_of $port
        Extracts and returns the node ID from a port ID or a node ID.

    $is_local = port_is_local $port
        Returns true iff the port is a local port.

    configure $profile, key => value...
    configure key => value...
        Before a node can talk to other nodes on the network (i.e. enter
        "distributed mode") it has to configure itself - the minimum a node
        needs to know is its own name, and optionally it should know the
        addresses of some other nodes in the network to discover other
        nodes.

        This function configures a node - it must be called exactly once (or
        never) before calling other AnyEvent::MP functions.

        The key/value pairs are basically the same ones as documented for
        the aemp command line utility (sans the set/del prefix), with these
        additions:

        norc => $boolean (default false)
            If true, then the rc file (e.g. ~/.perl-anyevent-mp) will *not*
            be consulted - all configuration options must be specified in
            the "configure" call.

        force => $boolean (default false)
            IF true, then the values specified in the "configure" will take
            precedence over any values configured via the rc file. The
            default is for the rc file to override any options specified in
            the program.

        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