--- AnyEvent-MP/MP.pm 2009/08/14 14:01:05 1.50 +++ AnyEvent-MP/MP.pm 2009/08/16 02:55:16 1.58 @@ -25,9 +25,9 @@ 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 }; @@ -71,22 +71,21 @@ A port is something you can send messages to (with the C function). -Some ports allow you to register C handlers that can match specific -messages. All C handlers will receive messages they match, messages -will not be queued. +Ports allow you to register C handlers that can match all or just +some messages. Messages will not be queued. =item port id - C -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 -port. You can send messages to node ports to find existing ports or to -create new ports, among other things. +A node is a single process containing at least one port - the node port, +which provides nodes to manage each other remotely, and to create new +ports. Nodes are either private (single-process only), slaves (connected to a master node only) or public nodes (connectable from unrelated nodes). @@ -145,14 +144,13 @@ =item $thisnode = NODE / $NODE -The C function returns, and the C<$NODE> variable contains -the noderef of the local node. The value is initialised by a call -to C or C, after which all local port -identifiers become invalid. +The C function returns, and the C<$NODE> variable contains the +noderef of the local node. The value is initialised by a call to +C. =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... @@ -201,12 +199,20 @@ 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 for the current node. This should be the most common form of invocation for "daemon"-type nodes. @@ -281,11 +287,10 @@ =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 -stringifies a sa port ID (such as a port object :). +a local or a remote port, and must be a port ID. 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 @@ -353,9 +358,10 @@ =item rcv $local_port, tag => $callback->(@msg_without_tag), ... -Register callbacks to be called on messages starting with the given tag on -the given port (and return the port), or unregister it (when C<$callback> -is C<$undef>). +Register (or replace) callbacks to be called on messages starting with the +given tag on the given port (and return the port), or unregister it (when +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 @@ -377,13 +383,22 @@ ... ; +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 (@_) { @@ -492,6 +507,9 @@ 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 never die >>, so use @@ -661,60 +679,13 @@ $_[0] =~ /::/ or Carp::croak "spawn init function must be a fully-qualified name, caught"; - ($NODE{$noderef} || add_node $noderef) - ->send (["", "AnyEvent::MP::_spawn" => $id, @_]); + snd_to_func $noderef, "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. - -=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 message. - - snd $NODE, time => $myport, timereply => 1, 2; - # => snd $myport, timereply => 1, 2,