--- AnyEvent-MP/MP.pm	2009/08/08 21:56:29	1.41
+++ AnyEvent-MP/MP.pm	2009/08/13 01:57:10	1.47
@@ -40,6 +40,15 @@
    mon $port, $otherport       # kill otherport on abnormal death
    mon $port, $otherport, @msg # send message on death
 
+=head1 CURRENT STATUS
+
+   AnyEvent::MP            - stable API, should work
+   AnyEvent::MP::Intro     - outdated
+   AnyEvent::MP::Kernel    - WIP
+   AnyEvent::MP::Transport - mostly stable
+
+   stay tuned.
+
 =head1 DESCRIPTION
 
 This module (-family) implements a simple message passing framework.
@@ -52,7 +61,7 @@
 
 At the moment, this module family is severly broken and underdocumented,
 so do not use. This was uploaded mainly to reserve the CPAN namespace -
-stay tuned! The basic API should be finished, however.
+stay tuned!
 
 =head1 CONCEPTS
 
@@ -107,7 +116,7 @@
 
 package AnyEvent::MP;
 
-use AnyEvent::MP::Base;
+use AnyEvent::MP::Kernel;
 
 use common::sense;
 
@@ -117,7 +126,8 @@
 
 use base "Exporter";
 
-our $VERSION = '0.1';
+our $VERSION = $AnyEvent::MP::Kernel::VERSION;
+
 our @EXPORT = qw(
    NODE $NODE *SELF node_of _any_
    resolve_node initialise_node
@@ -503,15 +513,24 @@
 
 =item $guard = mon $port, $rcvport, @msg
 
-Monitor the given port and do something when the port is killed, and
-optionally return a guard that can be used to stop monitoring again.
+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.
+
+C<mon> effectively guarantees that, in the absence of hardware failures,
+that 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.
 
 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)
+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.
@@ -838,6 +857,41 @@
 
 =back
 
+=head1 RATIONALE
+
+=over 4
+
+=item Why strings for ports and noderefs, why not objects?
+
+We considered "objects", but found that the actual number of methods
+thatc an be called are very low. Since port IDs and noderefs travel over
+the network frequently, the serialising/deserialising would add lots of
+overhead, as well as having to keep a proxy object.
+
+Strings can easily be printed, easily serialised etc. and need no special
+procedures to be "valid".
+
+And a a miniport consists of a single closure stored in a global hash - it
+can't become much cheaper.
+
+=item Why favour JSON, why not real serialising format such as Storable?
+
+In fact, any AnyEvent::MP node will happily accept Storable as framing
+format, but currently there is no way to make a node use Storable by
+default.
+
+The default framing protocol is JSON because a) JSON::XS is many times
+faster for small messages and b) most importantly, after years of
+experience we found that object serialisation is causing more problems
+than it gains: Just like function calls, objects simply do not travel
+easily over the network, mostly because they will always be a copy, so you
+always have to re-think your design.
+
+Keeping your messages simple, concentrating on data structures rather than
+objects, will keep your messages clean, tidy and efficient.
+
+=back
+
 =head1 SEE ALSO
 
 L<AnyEvent>.