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

Comparing AnyEvent-MP/MP.pm (file contents):
Revision 1.50 by root, Fri Aug 14 14:01:05 2009 UTC vs.
Revision 1.58 by root, Sun Aug 16 02:55:16 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...
 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.
 =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.
+All the seednodes will also be specially marked to automatically retry
+connecting to them infinitely.
 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
 form of invocation for "daemon"-type nodes.
    initialise_node;
 =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).
       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;
    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 (@_) {
       if (ref $_[0]) {
          if (my $self = $PORT_DATA{$portid}) {
 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 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
 C<eval> if unsure.
    my $id = "$RUNIQ." . $ID++;
    $_[0] =~ /::/
       or Carp::croak "spawn init function must be a fully-qualified name, caught";
-   ($NODE{$noderef} || add_node $noderef)
+   snd_to_func $noderef, "AnyEvent::MP::_spawn" => $id, @_;
-      ->send (["", "AnyEvent::MP::_spawn" => $id, @_]);
    "$noderef#$id"
 }
-=back
-=head1 NODE MESSAGES
-Nodes understand the following messages sent to them. Many of them take
-arguments called C<@reply>, which will simply be used to compose a reply
-message - C<$reply[0]> is the port to reply to, C<$reply[1]> the type and
-the remaining arguments are simply the message data.
-While other messages exist, they are not public and subject to change.
-=over 4
-=cut
-=item lookup => $name, @reply
-Replies with the port ID of the specified well-known port, or C<undef>.
-=item devnull => ...
-Generic data sink/CPU heat conversion.
-=item relay => $port, @msg
-Simply forwards the message to the given port.
-=item eval => $string[ @reply]
-Evaluates the given string. If C<@reply> is given, then a message of the
-form C<@reply, $@, @evalres> is sent.
-Example: crash another node.
-   snd $othernode, eval => "exit";
-=item time => @reply
-Replies the the current node time to C<@reply>.
-Example: tell the current node to send the current time to C<$myport> in a
-C<timereply> message.
-   snd $NODE, time => $myport, timereply => 1, 2;
-   # => snd $myport, timereply => 1, 2, <time>
 =back
 =head1 AnyEvent::MP vs. Distributed Erlang
 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 AnyEvent-MP/MP.pm (file contents): Revision 1.50 by root, Fri Aug 14 14:01:05 2009 UTC vs. Revision 1.58 by root, Sun Aug 16 02:55:16 2009 UTC

Diff Legend

Comparing AnyEvent-MP/MP.pm (file contents):
Revision 1.50 by root, Fri Aug 14 14:01:05 2009 UTC vs.
Revision 1.58 by root, Sun Aug 16 02:55:16 2009 UTC