view release on metacpan or  search on metacpan

MP.pm  view on Meta::CPAN

=back

=head1 PORTING FROM AnyEvent::MP VERSION 1.X

AEMP version 2 has a few major incompatible changes compared to version 1:

=over 4

=item 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

C<grp_reg> is a no-brainer (just replace by C<db_reg>), but C<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
C<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.

C<grp_mon> can be replaced by C<db_mon> with minor changes - C<db_mon>
passes a hash as first argument, and an extra C<$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.
     ...
  };

=item Nodes not longer connect to all other nodes.

In AEMP 1.x, every node automatically loads the L<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 (C<mon $node, ...>), which will attempt to
create the connection (and notify you when the connection fails).

=item Listener-less nodes (nodes without binds) are gone.

And are not coming back, at least not in their old form. If no C<binds>
are specified for a node, AnyEvent::MP assumes a default of C<*:*>.

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

=item $AnyEvent::MP::Kernel::WARN has gone.

AnyEvent has acquired a logging framework (L<AnyEvent::Log>), and AEMP now
uses this, and so should your programs.

Every module now documents what kinds of messages it generates, with
AnyEvent::MP acting as a catch all.

On the positive side, this means that instead of setting
C<PERL_ANYEVENT_MP_WARNLEVEL>, you can get away by setting C<AE_VERBOSE> -
much less to type.

=back

=head1 LOGGING

AnyEvent::MP does not normally log anything by itself, but since it is the
root of the context hierarchy for AnyEvent::MP modules, it will receive
all log messages by submodules.

=head1 SEE ALSO

L<AnyEvent::MP::Intro> - a gentle introduction.

L<AnyEvent::MP::Kernel> - more, lower-level, stuff.

L<AnyEvent::MP::Global> - network maintenance and port groups, to find
your applications.

L<AnyEvent::MP::DataConn> - establish data connections between nodes.

L<AnyEvent::MP::LogCatcher> - simple service to display log messages from