ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/AnyEvent-MP/MP.pm
(Generate patch)

Comparing AnyEvent-MP/MP.pm (file contents):
Revision 1.51 by root, Fri Aug 14 14:07:44 2009 UTC vs.
Revision 1.56 by root, Sat Aug 15 04:12:38 2009 UTC

… …
23 snd $port, type => data...; 23 snd $port, type => data...;
24 snd $port, @msg; 24 snd $port, @msg;
25 snd @msg_with_first_element_being_a_port; 25 snd @msg_with_first_element_being_a_port;
26 26
27 # creating/using ports, the simple way 27 # creating/using ports, the simple way
28 my $somple_port = port { my @msg = @_; 0 }; 28 my $simple_port = port { my @msg = @_; 0 };
29 29
30 # creating/using ports, type matching 30 # creating/using ports, tagged message matching
31 my $port = port; 31 my $port = port;
32 rcv $port, ping => sub { snd $_[0], "pong"; 0 }; 32 rcv $port, ping => sub { snd $_[0], "pong"; 0 };
33 rcv $port, pong => sub { warn "pong received\n"; 0 }; 33 rcv $port, pong => sub { warn "pong received\n"; 0 };
34 34
35 # create a port on another node 35 # create a port on another node
… …
69 69
70=item port 70=item port
71 71
72A port is something you can send messages to (with the C<snd> function). 72A port is something you can send messages to (with the C<snd> function).
73 73
74Some ports allow you to register C<rcv> handlers that can match specific 74Ports allow you to register C<rcv> handlers that can match all or just
75messages. All C<rcv> handlers will receive messages they match, messages 75some messages. Messages will not be queued.
76will not be queued.
77 76
78=item port id - C<noderef#portname> 77=item port id - C<noderef#portname>
79 78
80A port id is normaly the concatenation of a noderef, a hash-mark (C<#>) as 79A port ID is the concatenation of a noderef, a hash-mark (C<#>) as
81separator, and a port name (a printable string of unspecified format). An 80separator, and a port name (a printable string of unspecified format). An
82exception is the the node port, whose ID is identical to its node 81exception is the the node port, whose ID is identical to its node
83reference. 82reference.
84 83
85=item node 84=item node
86 85
87A node is a single process containing at least one port - the node 86A node is a single process containing at least one port - the node port,
88port. You can send messages to node ports to find existing ports or to 87which provides nodes to manage each other remotely, and to create new
89create new ports, among other things. 88ports.
90 89
91Nodes are either private (single-process only), slaves (connected to a 90Nodes are either private (single-process only), slaves (connected to a
92master node only) or public nodes (connectable from unrelated nodes). 91master node only) or public nodes (connectable from unrelated nodes).
93 92
94=item noderef - C<host:port,host:port...>, C<id@noderef>, C<id> 93=item noderef - C<host:port,host:port...>, C<id@noderef>, C<id>
… …
143 kil $SELF, die => $msg; 142 kil $SELF, die => $msg;
144} 143}
145 144
146=item $thisnode = NODE / $NODE 145=item $thisnode = NODE / $NODE
147 146
148The C<NODE> function returns, and the C<$NODE> variable contains 147The C<NODE> function returns, and the C<$NODE> variable contains the
149the noderef of the local node. The value is initialised by a call 148noderef of the local node. The value is initialised by a call to
150to C<become_public> or C<become_slave>, after which all local port 149C<initialise_node>.
151identifiers become invalid.
152 150
153=item $noderef = node_of $port 151=item $noderef = node_of $port
154 152
155Extracts and returns the noderef from a portid or a noderef. 153Extracts and returns the noderef from a port ID or a noderef.
156 154
157=item initialise_node $noderef, $seednode, $seednode... 155=item initialise_node $noderef, $seednode, $seednode...
158 156
159=item initialise_node "slave/", $master, $master... 157=item initialise_node "slave/", $master, $master...
160 158
… …
199At least one additional noderef is required (either by specifying it 197At least one additional noderef is required (either by specifying it
200directly or because it is part of the configuration profile): The node 198directly or because it is part of the configuration profile): The node
201will try to connect to all of them and will become a slave attached to the 199will try to connect to all of them and will become a slave attached to the
202first node it can successfully connect to. 200first node it can successfully connect to.
203 201
202Note that slave nodes cannot change their name, and consequently, their
203master, so if the master goes down, the slave node will not function well
204anymore until it can re-establish conenciton to its master. This makes
205slave nodes unsuitable for long-term nodes or fault-tolerant networks.
206
204=back 207=back
205 208
206This function will block until all nodes have been resolved and, for slave 209This function will block until all nodes have been resolved and, for slave
207nodes, until it has successfully established a connection to a master 210nodes, until it has successfully established a connection to a master
208server. 211server.
209 212
213All the seednodes will also be specially marked to automatically retry
214connecting to them infinitely.
215
210Example: become a public node listening on the guessed noderef, or the one 216Example: become a public node listening on the guessed noderef, or the one
211specified via C<aemp> for the current node. This should be the most common 217specified via C<aemp> for the current node. This should be the most common
212form of invocation for "daemon"-type nodes. 218form of invocation for "daemon"-type nodes.
213 219
214 initialise_node; 220 initialise_node;
… …
279=item snd $port, type => @data 285=item snd $port, type => @data
280 286
281=item snd $port, @msg 287=item snd $port, @msg
282 288
283Send the given message to the given port ID, which can identify either 289Send the given message to the given port ID, which can identify either
284a local or a remote port, and can be either a string or soemthignt hat 290a local or a remote port, and must be a port ID.
285stringifies a sa port ID (such as a port object :).
286 291
287While the message can be about anything, it is highly recommended to use a 292While the message can be about anything, it is highly recommended to use a
288string as first element (a portid, or some word that indicates a request 293string as first element (a port ID, or some word that indicates a request
289type etc.). 294type etc.).
290 295
291The message data effectively becomes read-only after a call to this 296The message data effectively becomes read-only after a call to this
292function: modifying any argument is not allowed and can cause many 297function: modifying any argument is not allowed and can cause many
293problems. 298problems.
… …
351The default callback received all messages not matched by a more specific 356The default callback received all messages not matched by a more specific
352C<tag> match. 357C<tag> match.
353 358
354=item rcv $local_port, tag => $callback->(@msg_without_tag), ... 359=item rcv $local_port, tag => $callback->(@msg_without_tag), ...
355 360
356Register callbacks to be called on messages starting with the given tag on 361Register (or replace) callbacks to be called on messages starting with the
357the given port (and return the port), or unregister it (when C<$callback> 362given tag on the given port (and return the port), or unregister it (when
358is C<$undef>). 363C<$callback> is C<$undef> or missing). There can only be one callback
364registered for each tag.
359 365
360The original message will be passed to the callback, after the first 366The original message will be passed to the callback, after the first
361element (the tag) has been removed. The callback will use the same 367element (the tag) has been removed. The callback will use the same
362environment as the default callback (see above). 368environment as the default callback (see above).
363 369
… …
374 snd $otherport, reply => 380 snd $otherport, reply =>
375 rcv port, 381 rcv port,
376 msg1 => sub { ... }, 382 msg1 => sub { ... },
377 ... 383 ...
378 ; 384 ;
385
386Example: temporarily register a rcv callback for a tag matching some port
387(e.g. for a rpc reply) and unregister it after a message was received.
388
389 rcv $port, $otherport => sub {
390 my @reply = @_;
391
392 rcv $SELF, $otherport;
393 };
379 394
380=cut 395=cut
381 396
382sub rcv($@) { 397sub rcv($@) {
383 my $port = shift; 398 my $port = shift;
… …
659 my $id = "$RUNIQ." . $ID++; 674 my $id = "$RUNIQ." . $ID++;
660 675
661 $_[0] =~ /::/ 676 $_[0] =~ /::/
662 or Carp::croak "spawn init function must be a fully-qualified name, caught"; 677 or Carp::croak "spawn init function must be a fully-qualified name, caught";
663 678
664 ($NODE{$noderef} || add_node $noderef) 679 snd_to_func $noderef, "AnyEvent::MP::_spawn" => $id, @_;
665 ->send (["", "AnyEvent::MP::_spawn" => $id, @_]);
666 680
667 "$noderef#$id" 681 "$noderef#$id"
668} 682}
669 683
670=back 684=back
… …
738convenience functionality. 752convenience functionality.
739 753
740This means that AEMP requires a less tightly controlled environment at the 754This means that AEMP requires a less tightly controlled environment at the
741cost of longer node references and a slightly higher management overhead. 755cost of longer node references and a slightly higher management overhead.
742 756
743=item Erlang has a "remote ports are like local ports" philosophy, AEMP 757=item * Erlang has a "remote ports are like local ports" philosophy, AEMP
744uses "local ports are like remote ports". 758uses "local ports are like remote ports".
745 759
746The failure modes for local ports are quite different (runtime errors 760The failure modes for local ports are quite different (runtime errors
747only) then for remote ports - when a local port dies, you I<know> it dies, 761only) then for remote ports - when a local port dies, you I<know> it dies,
748when a connection to another node dies, you know nothing about the other 762when a connection to another node dies, you know nothing about the other

Diff Legend

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