[ViewVC] Diff of: cvs/cvsroot/AnyEvent-MP/MP.pm

Comparing cvsroot/AnyEvent-MP/MP.pm (file contents):
Revision 1.50 by root, Fri Aug 14 14:01:05 2009 UTC vs.
Revision 1.54 by root, Fri Aug 14 16:15:37 2009 UTC

    snd $port, type => data...;
    snd $port, @msg;
    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, type matching
+   # creating/using ports, tagged message matching
    my $port = port;
    rcv $port, ping => sub { snd $_[0], "pong"; 0 };
    rcv $port, pong => sub { warn "pong received\n"; 0 };
    # create a port on another node
 =item port
 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
+Ports allow you to register C<rcv> handlers that can match all or just
-messages. All C<rcv> handlers will receive messages they match, messages
+some messages. Messages will not be queued.
-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
+A node is a single process containing at least one port - the node port,
-port. You can send messages to node ports to find existing ports or to
+which provides nodes to manage each other remotely, and to create new
-create new ports, among other things.
+ports.
 Nodes are either private (single-process only), slaves (connected to a
 master node only) or public nodes (connectable from unrelated nodes).
 =item noderef - C<host:port,host:port...>, C<id@noderef>, C<id>
    kil $SELF, die => $msg;
 }
 =item $thisnode = NODE / $NODE
-The C<NODE> function returns, and the C<$NODE> variable contains
+The C<NODE> function returns, and the C<$NODE> variable contains the
-the noderef of the local node. The value is initialised by a call
+noderef of the local node. The value is initialised by a call to
-to C<become_public> or C<become_slave>, after which all local port
+C<initialise_node>.
-identifiers become invalid.
 =item $noderef = node_of $port
-Extracts and returns the noderef from a portid or a noderef.
+Extracts and returns the noderef from a port ID or a noderef.
 =item initialise_node $noderef, $seednode, $seednode...
 =item initialise_node "slave/", $master, $master...
 =item snd $port, type => @data
 =item snd $port, @msg
 Send the given message to the given port ID, which can identify either
-a local or a remote port, and can be either a string or soemthignt hat
+a local or a remote port, and must be a port ID.
-stringifies a sa port ID (such as a port object :).
 While the message can be about anything, it is highly recommended to use a
-string as first element (a portid, or some word that indicates a request
+string as first element (a port ID, or some word that indicates a request
 type etc.).
 The message data effectively becomes read-only after a call to this
 function: modifying any argument is not allowed and can cause many
 problems.
 The default callback received all messages not matched by a more specific
 C<tag> match.
 =item rcv $local_port, tag => $callback->(@msg_without_tag), ...
-Register callbacks to be called on messages starting with the given tag on
+Register (or replace) callbacks to be called on messages starting with the
-the given port (and return the port), or unregister it (when C<$callback>
+given tag on the given port (and return the port), or unregister it (when
-is C<$undef>).
+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
 environment as the default callback (see above).
    snd $otherport, reply =>
       rcv port,
          msg1 => sub { ... },
          ...
    ;
+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($@) {
    my $port = shift;
 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 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
+only) then for remote ports - when a local port dies, you I<know> it dies,
+when a connection to another node dies, you know nothing about the other
+port.
+Erlang pretends remote ports are as reliable as local ports, even when
+they are not.
+AEMP encourages a "treat remote ports differently" philosophy, with local
+ports being the special case/exception, where transport errors cannot
+occur.
 =item * Erlang uses processes and a mailbox, AEMP does not queue.
-Erlang uses processes that selctively receive messages, and therefore
+Erlang uses processes that selectively receive messages, and therefore
-needs a queue. AEMP is event based, queuing messages would serve no useful
+needs a queue. AEMP is event based, queuing messages would serve no
-purpose.
+useful purpose. For the same reason the pattern-matching abilities of
+AnyEvent::MP are more limited, as there is little need to be able to
+filter messages without dequeing them.
 (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
+Sending messages in Erlang is synchronous and blocks the process (and
-sends are immediate, connection establishment is handled in the
+so does not need a queue that can overflow). AEMP sends are immediate,
-background.
+connection establishment is handled in the background.
-=item * Erlang can silently lose messages, AEMP cannot.
+=item * Erlang suffers from silent message loss, AEMP does not.
 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).
 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
+In Erlang it is quite likely that a node that restarts reuses a process ID
-ID known to other nodes for a completely different process, causing
+known to other nodes for a completely different process, causing messages
-messages destined for that process to end up in an unrelated process.
+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

Diff Legend

-–
+Removed lines
-+
+Added lines
-<
+Changed lines
->
+Changed lines

Comparing cvsroot/AnyEvent-MP/MP.pm (file contents): Revision 1.50 by root, Fri Aug 14 14:01:05 2009 UTC vs. Revision 1.54 by root, Fri Aug 14 16:15:37 2009 UTC

Diff Legend

Comparing cvsroot/AnyEvent-MP/MP.pm (file contents):
Revision 1.50 by root, Fri Aug 14 14:01:05 2009 UTC vs.
Revision 1.54 by root, Fri Aug 14 16:15:37 2009 UTC