--- AnyEvent-MP/MP.pm	2009/08/14 15:13:20	1.52
+++ AnyEvent-MP/MP.pm	2009/08/15 04:12:38	1.56
@@ -25,7 +25,7 @@
    snd @msg_with_first_element_being_a_port;
 
    # creating/using ports, the simple way
-   my $somple_port = port { my @msg = @_; 0 };
+   my $simple_port = port { my @msg = @_; 0 };
 
    # creating/using ports, tagged message matching
    my $port = port;
@@ -71,22 +71,21 @@
 
 A port is something you can send messages to (with the C<snd> function).
 
-Some ports allow you to register C<rcv> handlers that can match specific
-messages. All C<rcv> handlers will receive messages they match, messages
-will not be queued.
+Ports allow you to register C<rcv> handlers that can match all or just
+some messages. Messages will not be queued.
 
 =item port id - C<noderef#portname>
 
-A port id is normaly the concatenation of a noderef, a hash-mark (C<#>) as
+A port ID is the concatenation of a noderef, a hash-mark (C<#>) as
 separator, and a port name (a printable string of unspecified format). An
 exception is the the node port, whose ID is identical to its node
 reference.
 
 =item node
 
-A node is a single process containing at least one port - the node
-port. You can send messages to node ports to find existing ports or to
-create new ports, among other things.
+A node is a single process containing at least one port - the node port,
+which provides nodes to manage each other remotely, and to create new
+ports.
 
 Nodes are either private (single-process only), slaves (connected to a
 master node only) or public nodes (connectable from unrelated nodes).
@@ -200,12 +199,20 @@
 will try to connect to all of them and will become a slave attached to the
 first node it can successfully connect to.
 
+Note that slave nodes cannot change their name, and consequently, their
+master, so if the master goes down, the slave node will not function well
+anymore until it can re-establish conenciton to its master. This makes
+slave nodes unsuitable for long-term nodes or fault-tolerant networks.
+
 =back
 
 This function will block until all nodes have been resolved and, for slave
 nodes, until it has successfully established a connection to a master
 server.
 
+All the seednodes will also be specially marked to automatically retry
+connecting to them infinitely.
+
 Example: become a public node listening on the guessed noderef, or the one
 specified via C<aemp> for the current node. This should be the most common
 form of invocation for "daemon"-type nodes.
@@ -351,9 +358,10 @@
 
 =item rcv $local_port, tag => $callback->(@msg_without_tag), ...
 
-Register callbacks to be called on messages starting with the given tag on
-the given port (and return the port), or unregister it (when C<$callback>
-is C<$undef>).
+Register (or replace) callbacks to be called on messages starting with the
+given tag on the given port (and return the port), or unregister it (when
+C<$callback> is C<$undef> or missing). There can only be one callback
+registered for each tag.
 
 The original message will be passed to the callback, after the first
 element (the tag) has been removed. The callback will use the same
@@ -375,6 +383,15 @@
          ...
    ;
 
+Example: temporarily register a rcv callback for a tag matching some port
+(e.g. for a rpc reply) and unregister it after a message was received.
+
+   rcv $port, $otherport => sub {
+      my @reply = @_;
+
+      rcv $SELF, $otherport;
+   };
+
 =cut
 
 sub rcv($@) {
@@ -659,8 +676,7 @@
    $_[0] =~ /::/
       or Carp::croak "spawn init function must be a fully-qualified name, caught";
 
-   ($NODE{$noderef} || add_node $noderef)
-      ->send (["", "AnyEvent::MP::_spawn" => $id, @_]);
+   snd_to_func $noderef, "AnyEvent::MP::_spawn" => $id, @_;
 
    "$noderef#$id"
 }
@@ -738,7 +754,7 @@
 This means that AEMP requires a less tightly controlled environment at the
 cost of longer node references and a slightly higher management overhead.
 
-=item Erlang has a "remote ports are like local ports" philosophy, AEMP
+=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