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.55 by root, Fri Aug 14 23:17:17 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
… …
279=item snd $port, type => @data 277=item snd $port, type => @data
280 278
281=item snd $port, @msg 279=item snd $port, @msg
282 280
283Send the given message to the given port ID, which can identify either 281Send 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 282a local or a remote port, and must be a port ID.
285stringifies a sa port ID (such as a port object :).
286 283
287While the message can be about anything, it is highly recommended to use a 284While 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 285string as first element (a port ID, or some word that indicates a request
289type etc.). 286type etc.).
290 287
291The message data effectively becomes read-only after a call to this 288The message data effectively becomes read-only after a call to this
292function: modifying any argument is not allowed and can cause many 289function: modifying any argument is not allowed and can cause many
293problems. 290problems.
… …
351The default callback received all messages not matched by a more specific 348The default callback received all messages not matched by a more specific
352C<tag> match. 349C<tag> match.
353 350
354=item rcv $local_port, tag => $callback->(@msg_without_tag), ... 351=item rcv $local_port, tag => $callback->(@msg_without_tag), ...
355 352
356Register callbacks to be called on messages starting with the given tag on 353Register (or replace) callbacks to be called on messages starting with the
357the given port (and return the port), or unregister it (when C<$callback> 354given tag on the given port (and return the port), or unregister it (when
358is C<$undef>). 355C<$callback> is C<$undef> or missing). There can only be one callback
356registered for each tag.
359 357
360The original message will be passed to the callback, after the first 358The original message will be passed to the callback, after the first
361element (the tag) has been removed. The callback will use the same 359element (the tag) has been removed. The callback will use the same
362environment as the default callback (see above). 360environment as the default callback (see above).
363 361
… …
374 snd $otherport, reply => 372 snd $otherport, reply =>
375 rcv port, 373 rcv port,
376 msg1 => sub { ... }, 374 msg1 => sub { ... },
377 ... 375 ...
378 ; 376 ;
377
378Example: temporarily register a rcv callback for a tag matching some port
379(e.g. for a rpc reply) and unregister it after a message was received.
380
381 rcv $port, $otherport => sub {
382 my @reply = @_;
383
384 rcv $SELF, $otherport;
385 };
379 386
380=cut 387=cut
381 388
382sub rcv($@) { 389sub rcv($@) {
383 my $port = shift; 390 my $port = shift;
… …
659 my $id = "$RUNIQ." . $ID++; 666 my $id = "$RUNIQ." . $ID++;
660 667
661 $_[0] =~ /::/ 668 $_[0] =~ /::/
662 or Carp::croak "spawn init function must be a fully-qualified name, caught"; 669 or Carp::croak "spawn init function must be a fully-qualified name, caught";
663 670
664 ($NODE{$noderef} || add_node $noderef) 671 snd_to_func $noderef, "AnyEvent::MP::_spawn" => $id, @_;
665 ->send (["", "AnyEvent::MP::_spawn" => $id, @_]);
666 672
667 "$noderef#$id" 673 "$noderef#$id"
668} 674}
669 675
670=back 676=back
… …
738convenience functionality. 744convenience functionality.
739 745
740This means that AEMP requires a less tightly controlled environment at the 746This means that AEMP requires a less tightly controlled environment at the
741cost of longer node references and a slightly higher management overhead. 747cost of longer node references and a slightly higher management overhead.
742 748
743=item Erlang has a "remote ports are like local ports" philosophy, AEMP 749=item * Erlang has a "remote ports are like local ports" philosophy, AEMP
744uses "local ports are like remote ports". 750uses "local ports are like remote ports".
745 751
746The failure modes for local ports are quite different (runtime errors 752The 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, 753only) 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 754when a connection to another node dies, you know nothing about the other

Diff Legend

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