--- AnyEvent-MP/MP.pm	2009/08/04 18:46:16	1.23
+++ AnyEvent-MP/MP.pm	2009/08/04 22:13:45	1.27
@@ -90,7 +90,7 @@
 
 use base "Exporter";
 
-our $VERSION = '0.02';
+our $VERSION = '0.1';
 our @EXPORT = qw(
    NODE $NODE *SELF node_of _any_
    become_slave become_public
@@ -247,6 +247,16 @@
    mon $port, sub { 0 && @refs }
 }
 
+=item lnk $port1, $port2
+
+Link two ports. This is simply a shorthand for:
+
+   mon $port1, $port2;
+   mon $port2, $port1;
+
+It means that if either one is killed abnormally, the other one gets
+killed as well.
+
 =item $local_port = port
 
 Create a new local port object that supports message matching.
@@ -500,6 +510,82 @@
 
 =back
 
+=head1 AnyEvent::MP vs. Distributed Erlang
+
+AnyEvent::MP got lots of its ideas from distributed erlang (erlang node
+== aemp node, erlang process == aemp port), so many of the documents and
+programming techniques employed by erlang apply to AnyEvent::MP. Here is a
+sample:
+
+   http://www.erlang.se/doc/programming_rules.shtml
+   http://erlang.org/doc/getting_started/part_frame.html # chapters 3 and 4
+   http://erlang.org/download/erlang-book-part1.pdf      # chapters 5 and 6
+   http://erlang.org/download/armstrong_thesis_2003.pdf  # chapters 4 and 5
+
+Despite the similarities, there are also some important differences:
+
+=over 4
+
+=item * Node references contain the recipe on how to contact them.
+
+Erlang relies on special naming and DNS to work everywhere in the
+same way. AEMP relies on each node knowing it's own address(es), with
+convenience functionality.
+
+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 uses processes and a mailbox, AEMP does not queue.
+
+Erlang uses processes that selctively receive messages, and therefore
+needs a queue. AEMP is event based, queuing messages would serve no useful
+purpose.
+
+(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.
+
+Sending messages in erlang is synchronous and blocks the process. AEMP
+sends are immediate, connection establishment is handled in the
+background.
+
+=item * Erlang can silently lose messages, AEMP cannot.
+
+Erlang makes few guarantees on messages delivery - messages can get lost
+without any of the processes realising it (i.e. you send messages a, b,
+and c, and the other side only receives messages a and c).
+
+AEMP guarantees correct ordering, and the guarantee that there are no
+holes in the message sequence.
+
+=item * In erlang, processes can be declared dead and later be found to be
+alive.
+
+In erlang it can happen that a monitored process is declared dead and
+linked processes get killed, but later it turns out that the process is
+still alive - and can receive messages.
+
+In AEMP, when port monitoring detects a port as dead, then that port will
+eventually be killed - it cannot happen that a node detects a port as dead
+and then later sends messages to it, finding it is still alive.
+
+=item * Erlang can send messages to the wrong port, AEMP does not.
+
+In erlang it is quite possible that a node that restarts reuses a process
+ID known to other nodes for a completely different process, causing
+messages destined for that process to end up in an unrelated process.
+
+AEMP never reuses port IDs, so old messages or old port IDs floating
+around in the network will not be sent to an unrelated port.
+
+=item * Erlang uses unprotected connections, AEMP uses secure
+authentication and can use TLS.
+
+AEMP can use a proven protocol - SSL/TLS - to protect connections and
+securely authenticate nodes.
+
+=back
+
 =head1 SEE ALSO
 
 L<AnyEvent>.