--- AnyEvent-MP/MP.pm	2009/08/15 04:34:34	1.57
+++ AnyEvent-MP/MP.pm	2009/08/27 07:12:48	1.62
@@ -87,8 +87,9 @@
 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).
+Nodes are either private (single-process only), slaves (can only talk to
+public nodes, but do not need an open port) or public nodes (connectable
+from any other node).
 
 =item noderef - C<host:port,host:port...>, C<id@noderef>, C<id>
 
@@ -128,9 +129,9 @@
 our $VERSION = $AnyEvent::MP::Kernel::VERSION;
 
 our @EXPORT = qw(
-   NODE $NODE *SELF node_of _any_
+   NODE $NODE *SELF node_of after
    resolve_node initialise_node
-   snd rcv mon kil reg psub spawn
+   snd rcv mon mon_guard kil reg psub spawn
    port
 );
 
@@ -182,36 +183,28 @@
 C<initialise_node> or indirectly via a profile or the nodename) must be a
 noderef (possibly unresolved, in which case it will be resolved).
 
-After resolving, the node will bind itself on all endpoints and try to
-connect to all additional C<$seednodes> that are specified. Seednodes are
-optional and can be used to quickly bootstrap the node into an existing
-network.
+After resolving, the node will bind itself on all endpoints.
 
 =item slave nodes
 
 When the C<$noderef> (either as given or overriden by the config file)
 is the special string C<slave/>, then the node will become a slave
-node. Slave nodes cannot be contacted from outside and will route most of
-their traffic to the master node that they attach to.
+node. Slave nodes cannot be contacted from outside, and cannot talk to
+each other (at least in this version of AnyEvent::MP).
 
-At least one additional noderef is required (either by specifying it
-directly or because it is part of the configuration profile): The node
-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.
+Slave nodes work by creating connections to all public nodes, using the
+L<AnyEvent::MP::Global> service.
 
 =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.
+After initialising itself, the node will connect to all additional
+C<$seednodes> that are specified diretcly or via a profile. Seednodes are
+optional and can be used to quickly bootstrap the node into an existing
+network.
 
 All the seednodes will also be specially marked to automatically retry
-connecting to them infinitely.
+connecting to them indefinitely, so make sure that seednodes are really
+reliable and up (this might also change in the future).
 
 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
@@ -224,11 +217,6 @@
 
    initialise_node "slave/";
 
-Example: become a slave node to any of the specified master servers. This
-form is also often used for commandline clients.
-
-   initialise_node "slave/", "master1", "192.168.13.17", "mp.example.net";
-
 Example: become a public node, and try to contact some well-known master
 servers to become part of the network.
 
@@ -398,7 +386,7 @@
    my $port = shift;
    my ($noderef, $portid) = split /#/, $port, 2;
 
-   ($NODE{$noderef} || add_node $noderef) == $NODE{""}
+   $NODE{$noderef} == $NODE{""}
       or Carp::croak "$port: rcv can only be called on local ports, caught";
 
    while (@_) {
@@ -507,6 +495,9 @@
 port). After the monitoring action was invoked, further messages might get
 delivered again.
 
+Note that monitoring-actions are one-shot: once released, they are removed
+and will not trigger 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
@@ -681,6 +672,28 @@
    "$noderef#$id"
 }
 
+=item after $timeout, @msg
+
+=item after $timeout, $callback
+
+Either sends the given message, or call the given callback, after the
+specified number of seconds.
+
+This is simply a utility function that come sin handy at times.
+
+=cut
+
+sub after($@) {
+   my ($timeout, @action) = @_;
+
+   my $t; $t = AE::timer $timeout, 0, sub {
+      undef $t;
+      ref $action[0]
+         ? $action[0]()
+         : snd @action;
+   };
+}
+
 =back
 
 =head1 AnyEvent::MP vs. Distributed Erlang