[ViewVC] Diff of: cvs/AnyEvent-MP/MP.pm

Comparing AnyEvent-MP/MP.pm (file contents):
Revision 1.138 by root, Thu Mar 22 00:48:29 2012 UTC vs.
Revision 1.139 by root, Thu Mar 22 20:07:31 2012 UTC

          $res
       }
    }
 }
+=item $guard = mon $port, $rcvport          # kill $rcvport when $port dies
+=item $guard = mon $port                    # kill $SELF when $port dies
 =item $guard = mon $port, $cb->(@reason)    # call $cb when $port dies
-=item $guard = mon $port, $rcvport          # kill $rcvport when $port dies
-=item $guard = mon $port                    # kill $SELF when $port dies
 =item $guard = mon $port, $rcvport, @msg    # send a message when $port dies
 Monitor the given port and do something when the port is killed or
 messages to it were lost, and optionally return a guard that can be used
 to stop monitoring again.
+The first two forms distinguish between "normal" and "abnormal" kil's:
+In the first form (another port given), if the C<$port> is C<kil>'ed with
+a non-empty reason, the other port (C<$rcvport>) will be kil'ed with the
+same reason. That is, on "normal" kil's nothing happens, while under all
+other conditions, the other port is killed with the same reason.
+The second form (kill self) is the same as the first form, except that
+C<$rvport> defaults to C<$SELF>.
+The remaining forms don't distinguish between "normal" and "abnormal" kil's
+- it's up to the callback or receiver to check whether the C<@reason> is
+empty and act accordingly.
-In the first form (callback), the callback is simply called with any
+In the third form (callback), the callback is simply called with any
-number of C<@reason> elements (no @reason means that the port was deleted
+number of C<@reason> elements (empty @reason means that the port was deleted
 "normally"). Note also that I<< the callback B<must> never die >>, so use
 C<eval> if unsure.
-In the second form (another port given), the other port (C<$rcvport>)
-will be C<kil>'ed with C<@reason>, if 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.
-The third form (kill self) is the same as the second form, except that
-C<$rvport> defaults to C<$SELF>.
-In the last form (message), a message of the form C<@msg, @reason> will be
+In the last form (message), a message of the form C<$rcvport, @msg,
-C<snd>.
+@reason> will be C<snd>.
 Monitoring-actions are one-shot: once messages are lost (and a monitoring
-alert was raised), they are removed and will not trigger again.
+alert was raised), they are removed and will not trigger again, even if it
+turns out that the port is still alive.
-As a rule of thumb, monitoring requests should always monitor a port from
+As a rule of thumb, monitoring requests should always monitor a remote
-a local port (or callback). The reason is that kill messages might get
+port locally (using a local C<$rcvport> or a callback). The reason is that
-lost, just like any other message. Another less obvious reason is that
+kill messages might get lost, just like any other message. Another less
-even monitoring requests can get lost (for example, when the connection
+obvious reason is that even monitoring requests can get lost (for example,
-to the other node goes down permanently). When monitoring a port locally
+when the connection to the other node goes down permanently). When
-these problems do not exist.
+monitoring a port locally these problems do not exist.
 C<mon> effectively guarantees that, in the absence of hardware failures,
 after starting the monitor, either all messages sent to the port will
 arrive, or the monitoring action will be invoked after possible message
 loss has been detected. No messages will be lost "in between" (after
 =back
 =head1 PORTING FROM AnyEvent::MP VERSION 1.X
-AEMP version 2 has three major incompatible changes compared to version 1:
+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.
 AnyEvent::MP now comes with a distributed database that is more
-powerful. It's database families map closely to ports, but the API has
+powerful. Its database families map closely to port groups, but the API
-minor differences:
+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>
+C<grp_reg> is a no-brainer (just replace by C<db_reg>), but C<grp_get> is
-is no longer instant, because the local node might not have a copy of
+no longer instant, because the local node might not have a copy of the
-the group. This can be partially remedied by using C<db_mon> to keep an
+group. You can either modify your code to allow for a callback, or use
-updated copy of the group:
+C<db_mon> to keep an updated copy of the group:
   my $local_group_copy;
-  db_mon $group => sub { $local_group_copy = shift };
+  db_mon $group => sub { $local_group_copy = $_[0] };
-  # no keys %$local_group_copy always returns the most up-to-date
+  # now "keys %$local_group_copy" always returns the most up-to-date
   # list of ports in the group.
-C<grp_mon> can almost be replaced by C<db_mon>:
+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, $lde) = @_;
      $ports = [keys %$ports];
 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.
+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 now assumes a default of C<*:*>.
+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,
 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>,
+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 sinc eit is the
+root of the contetx hierarchy for AnyEvent::MP modules, it will receive
+all log messages by submodules.
 =head1 SEE ALSO
 L<AnyEvent::MP::Intro> - a gentle introduction.

Diff Legend

-–
+Removed lines
-+
+Added lines
-<
+Changed lines
->
+Changed lines

Comparing AnyEvent-MP/MP.pm (file contents): Revision 1.138 by root, Thu Mar 22 00:48:29 2012 UTC vs. Revision 1.139 by root, Thu Mar 22 20:07:31 2012 UTC

Diff Legend

Comparing AnyEvent-MP/MP.pm (file contents):
Revision 1.138 by root, Thu Mar 22 00:48:29 2012 UTC vs.
Revision 1.139 by root, Thu Mar 22 20:07:31 2012 UTC