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

Comparing AnyEvent-MP/MP.pm (file contents):
Revision 1.74 by root, Mon Aug 31 11:11:27 2009 UTC vs.
Revision 1.82 by root, Mon Sep 7 18:42:09 2009 UTC

 =head1 SYNOPSIS
    use AnyEvent::MP;
-   $NODE      # contains this node's noderef
+   $NODE      # contains this node's node ID
-   NODE       # returns this node's noderef
+   NODE       # returns this node's node ID
-   NODE $port # returns the noderef of the port
    $SELF      # receiving/own port id in rcv callbacks
    # initialise the node so it can send/receive messages
    configure;
-   # ports are message endpoints
+   # ports are message destinations
    # sending messages
    snd $port, type => data...;
    snd $port, @msg;
    snd @msg_with_first_element_being_a_port;
 =head1 CURRENT STATUS
    bin/aemp                - stable.
    AnyEvent::MP            - stable API, should work.
-   AnyEvent::MP::Intro     - uptodate, but incomplete.
+   AnyEvent::MP::Intro     - explains most concepts.
    AnyEvent::MP::Kernel    - mostly stable.
-   AnyEvent::MP::Global    - stable API, protocol not yet final.
+   AnyEvent::MP::Global    - stable but incomplete, protocol not yet final.
-   stay tuned.
+stay tuned.
 =head1 DESCRIPTION
 This module (-family) implements a simple message passing framework.
 on the same or other hosts, and you can supervise entities remotely.
 For an introduction to this module family, see the L<AnyEvent::MP::Intro>
 manual page and the examples under F<eg/>.
-At the moment, this module family is a bit underdocumented.
 =head1 CONCEPTS
 =over 4
 =item port
-A port is something you can send messages to (with the C<snd> function).
+Not to be confused with a TCP port, a "port" is something you can send
+messages to (with the C<snd> function).
 Ports allow you to register C<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.
 =item $nodeid = node_of $port
 Extracts and returns the node ID from a port ID or a node ID.
+=item configure $profile, key => value...
 =item 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
 =item step 1, gathering configuration from profiles
 The function first looks up a profile in the aemp configuration (see the
 L<aemp> commandline utility). The profile name can be specified via the
-named C<profile> parameter. If it is missing, then the nodename (F<uname
+named C<profile> parameter or can simply be the first parameter). If it is
--n>) will be used as profile name.
+missing, then the nodename (F<uname -n>) will be used as profile name.
 The profile data is then gathered as follows:
-First, all remaining key => value pairs (all of which are conviniently
+First, all remaining key => value pairs (all of which are conveniently
 undocumented at the moment) will be interpreted as configuration
 data. Then they will be overwritten by any values specified in the global
 default configuration (see the F<aemp> utility), then the chain of
 profiles chosen by the profile name (and any C<parent> attributes).
 =cut
 sub rcv($@) {
    my $port = shift;
-   my ($noderef, $portid) = split /#/, $port, 2;
+   my ($nodeid, $portid) = split /#/, $port, 2;
-   $NODE{$noderef} == $NODE{""}
+   $NODE{$nodeid} == $NODE{""}
       or Carp::croak "$port: rcv can only be called on local ports, caught";
    while (@_) {
       if (ref $_[0]) {
          if (my $self = $PORT_DATA{$portid}) {
 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.
+In the first form (callback), the callback is simply called with any
+number of C<@reason> elements (no @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
+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.
+As a rule of thumb, monitoring requests should always monitor a port from
+a local port (or callback). The reason is that kill messages might get
+lost, just like any other message. Another less obvious reason is that
+even monitoring requests can get lost (for example, when the connection
+to the other node goes down permanently). When 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
 the first lost message no further messages will be received by the
 port). After the monitoring action was invoked, further messages might get
 delivered again.
-Note that monitoring-actions are one-shot: once messages are lost (and a
+Inter-host-connection timeouts and monitoring depend on the transport
-monitoring alert was raised), they are removed and will not trigger again.
+used. The only transport currently implemented is TCP, and AnyEvent::MP
+relies on TCP to detect node-downs (this can take 10-15 minutes on a
+non-idle connection, and usually around two hours for idle conenctions).
-In the first form (callback), the callback is simply called with any
+This means that monitoring is good for program errors and cleaning up
-number of C<@reason> elements (no @reason means that the port was deleted
+stuff eventually, but they are no replacement for a timeout when you need
-"normally"). Note also that I<< the callback B<must> never die >>, so use
+to ensure some maximum latency.
-C<eval> if unsure.
-In the second form (another port given), the other port (C<$rcvport>)
-will be C<kil>'ed with C<@reason>, iff 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
-C<snd>.
-As a rule of thumb, monitoring requests should always monitor a port from
-a local port (or callback). The reason is that kill messages might get
-lost, just like any other message. Another less obvious reason is that
-even monitoring requests can get lost (for exmaple, when the connection
-to the other node goes down permanently). When monitoring a port locally
-these problems do not exist.
 Example: call a given callback when C<$port> is killed.
    mon $port, sub { warn "port died because of <@_>\n" };
    mon $port, $self => "restart";
 =cut
 sub mon {
-   my ($noderef, $port) = split /#/, shift, 2;
+   my ($nodeid, $port) = split /#/, shift, 2;
-   my $node = $NODE{$noderef} || add_node $noderef;
+   my $node = $NODE{$nodeid} || add_node $nodeid;
    my $cb = @_ ? shift : $SELF || Carp::croak 'mon: called with one argument only, but $SELF not set,';
    unless (ref $cb) {
       if (@_) {
 the package, then the package above the package and so on (e.g.
 C<MyApp::Chat::Server>, C<MyApp::Chat>, C<MyApp>) until the function
 exists or it runs out of package names.
 The init function is then called with the newly-created port as context
-object (C<$SELF>) and the C<@initdata> values as arguments.
+object (C<$SELF>) and the C<@initdata> values as arguments. It I<must>
+call one of the C<rcv> functions to set callbacks on C<$SELF>, otherwise
+the port might not get created.
 A common idiom is to pass a local port, immediately monitor the spawned
 port, and in the remote init function, immediately monitor the passed
 local port. This two-way monitoring ensures that both ports get cleaned up
 when there is a problem.
+C<spawn> guarantees that the C<$initfunc> has no visible effects on the
+caller before C<spawn> returns (by delaying invocation when spawn is
+called for the local node).
 Example: spawn a chat server port on C<$othernode>.
    # this node, executed from within a port context:
    my $server = spawn $othernode, "MyApp::Chat::Server::connect", $SELF;
    mon $server;
 sub _spawn {
    my $port = shift;
    my $init = shift;
+   # rcv will create the actual port
    local $SELF = "$NODE#$port";
    eval {
       &{ load_func $init }
    };
    _self_die if $@;
 }
 sub spawn(@) {
-   my ($noderef, undef) = split /#/, shift, 2;
+   my ($nodeid, undef) = split /#/, shift, 2;
    my $id = "$RUNIQ." . $ID++;
    $_[0] =~ /::/
       or Carp::croak "spawn init function must be a fully-qualified name, caught";
-   snd_to_func $noderef, "AnyEvent::MP::_spawn" => $id, @_;
+   snd_to_func $nodeid, "AnyEvent::MP::_spawn" => $id, @_;
-   "$noderef#$id"
+   "$nodeid#$id"
 }
 =item after $timeout, @msg
 =item after $timeout, $callback
 =item * Node IDs are arbitrary strings in AEMP.
 Erlang relies on special naming and DNS to work everywhere in the same
 way. AEMP relies on each node somehow knowing its own address(es) (e.g. by
-configuraiton or DNS), but will otherwise discover other odes itself.
+configuration or DNS), but will otherwise discover other odes itself.
 =item * Erlang has a "remote ports are like local ports" philosophy, AEMP
 uses "local ports are like remote ports".
 The failure modes for local ports are quite different (runtime errors
 Erlang uses processes that selectively receive messages, and therefore
 needs a queue. AEMP is event based, queuing messages would serve no
 useful purpose. For the same reason the pattern-matching abilities of
 AnyEvent::MP are more limited, as there is little need to be able to
-filter messages without dequeing them.
+filter messages without dequeuing them.
 (But see L<Coro::MP> for a more Erlang-like process model on top of AEMP).
 =item * Erlang sends are synchronous, AEMP sends are asynchronous.
 L<AnyEvent::MP::Kernel> - more, lower-level, stuff.
 L<AnyEvent::MP::Global> - network maintainance and port groups, to find
 your applications.
+L<AnyEvent::MP::LogCatcher> - simple service to display log messages from
+all nodes.
 L<AnyEvent>.
 =head1 AUTHOR
  Marc Lehmann <schmorp@schmorp.de>

Diff Legend

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

Comparing AnyEvent-MP/MP.pm (file contents): Revision 1.74 by root, Mon Aug 31 11:11:27 2009 UTC vs. Revision 1.82 by root, Mon Sep 7 18:42:09 2009 UTC

Diff Legend

Comparing AnyEvent-MP/MP.pm (file contents):
Revision 1.74 by root, Mon Aug 31 11:11:27 2009 UTC vs.
Revision 1.82 by root, Mon Sep 7 18:42:09 2009 UTC