view release on metacpan or  search on metacpan

README  view on Meta::CPAN

        This also saves round-trips and avoids sending messages to the wrong
        port (hard to do in Erlang).

RATIONALE
    Why strings for port and node IDs, why not objects?
        We considered "objects", but found that the actual number of methods
        that can be called are quite low. Since port and node IDs travel
        over the network frequently, the serialising/deserialising would add
        lots of overhead, as well as having to keep a proxy object
        everywhere.

        Strings can easily be printed, easily serialised etc. and need no
        special procedures to be "valid".

        And as a result, a port with just a default receiver consists of a
        single code reference stored in a global hash - it can't become much
        cheaper.

    Why favour JSON, why not a real serialising format such as Storable?
        In fact, any AnyEvent::MP node will happily accept Storable as
        framing format, but currently there is no way to make a node use
        Storable by default (although all nodes will accept it).

        The default framing protocol is JSON because a) JSON::XS is many
        times faster for small messages and b) most importantly, after years
        of experience we found that object serialisation is causing more
        problems than it solves: Just like function calls, objects simply do
        not travel easily over the network, mostly because they will always
        be a copy, so you always have to re-think your design.

        Keeping your messages simple, concentrating on data structures
        rather than objects, will keep your messages clean, tidy and
        efficient.

PORTING FROM AnyEvent::MP VERSION 1.X
    AEMP version 2 has a few major incompatible changes compared to version
    1:

    AnyEvent::MP::Global no longer has group management functions.
        At least not officially - the grp_* functions are still exported and
        might work, but they will be removed in some later release.

        AnyEvent::MP now comes with a distributed database that is more
        powerful. Its database families map closely to port groups, but the
        API has changed (the functions are also now exported by
        AnyEvent::MP). Here is a rough porting guide:

          grp_reg $group, $port                      # old
          db_reg $group, $port                       # new

          $list = grp_get $group                     # old
          db_keys $group, sub { my $list = shift }   # new

          grp_mon $group, $cb->(\@ports, $add, $del) # old
          db_mon $group, $cb->(\%ports, $add, $change, $del) # new

        "grp_reg" is a no-brainer (just replace by "db_reg"), but "grp_get"
        is no longer instant, because the local node might not have a copy
        of the group. You can either modify your code to allow for a
        callback, or use "db_mon" to keep an updated copy of the group:

          my $local_group_copy;
          db_mon $group => sub { $local_group_copy = $_[0] };

          # now "keys %$local_group_copy" always returns the most up-to-date
          # list of ports in the group.

        "grp_mon" can be replaced by "db_mon" with minor changes - "db_mon"
        passes a hash as first argument, and an extra $chg argument that can
        be ignored:

          db_mon $group => sub {
             my ($ports, $add, $chg, $del) = @_;
             $ports = [keys %$ports];

             # now $ports, $add and $del are the same as
             # were originally passed by grp_mon.
             ...
          };

    Nodes not longer connect to all other nodes.
        In AEMP 1.x, every node automatically loads the AnyEvent::MP::Global
        module, which in turn would create connections to all other nodes in
        the network (helped by the seed nodes).

        In version 2.x, global nodes still connect to all other global
        nodes, but other nodes don't - now every node either is a global
        node itself, or attaches itself to another global node.

        If a node isn't a global node itself, then it attaches itself to one
        of its seed nodes. If that seed node isn't a global node yet, it
        will automatically be upgraded to a global node.

        So in many cases, nothing needs to be changed - one just has to make
        sure that all seed nodes are meshed together with the other seed
        nodes (as with AEMP 1.x), and other nodes specify them as seed
        nodes. This is most easily achieved by specifying the same set of
        seed nodes for all nodes in the network.

        Not opening a connection to every other node is usually an
        advantage, except when you need the lower latency of an already
        established connection. To ensure a node establishes a connection to
        another node, you can monitor the node port ("mon $node, ..."),
        which will attempt to create the connection (and notify you when the
        connection fails).

    Listener-less nodes (nodes without binds) are gone.
        And are not coming back, at least not in their old form. If no
        "binds" are specified for a node, AnyEvent::MP assumes a default of
        "*:*".

        There are vague plans to implement some form of routing domains,
        which might or might not bring back listener-less nodes, but don't
        count on it.

        The fact that most connections are now optional somewhat mitigates
        this, as a node can be effectively unreachable from the outside
        without any problems, as long as it isn't a global node and only
        reaches out to other nodes (as opposed to being contacted from other
        nodes).