--- AnyEvent-MP/MP.pm	2009/09/03 20:16:36	1.78
+++ AnyEvent-MP/MP.pm	2009/09/04 21:52:09	1.79
@@ -43,9 +43,9 @@
    AnyEvent::MP            - stable API, should work.
    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
 
@@ -63,7 +63,8 @@
 
 =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
@@ -476,17 +477,6 @@
 messages to it were lost, and optionally return a guard that can be used
 to stop monitoring again.
 
-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
-monitoring alert was raised), 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
@@ -503,6 +493,9 @@
 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
@@ -510,6 +503,23 @@
 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.
+
+Inter-host-connection timeouts and monitoring depend on the transport
+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).
+
+This means that monitoring is good for program errors and cleaning up
+stuff eventually, but they are no replacement for a timeout when you need
+to ensure some maximum latency.
+
 Example: call a given callback when C<$port> is killed.
 
    mon $port, sub { warn "port died because of <@_>\n" };