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.64 by root, Fri Aug 28 00:58:44 2009 UTC vs.
Revision 1.92 by root, Tue Sep 22 14:13:33 2009 UTC

1=head1 NAME 1=head1 NAME
2 2
3AnyEvent::MP - multi-processing/message-passing framework 3AnyEvent::MP - erlang-style multi-processing/message-passing framework
4 4
5=head1 SYNOPSIS 5=head1 SYNOPSIS
6 6
7 use AnyEvent::MP; 7 use AnyEvent::MP;
8 8
9 $NODE # contains this node's noderef 9 $NODE # contains this node's node ID
10 NODE # returns this node's noderef 10 NODE # returns this node's node ID
11 NODE $port # returns the noderef of the port
12 11
13 $SELF # receiving/own port id in rcv callbacks 12 $SELF # receiving/own port id in rcv callbacks
14 13
15 # initialise the node so it can send/receive messages 14 # initialise the node so it can send/receive messages
16 initialise_node; 15 configure;
17 16
18 # ports are message endpoints 17 # ports are message destinations
19 18
20 # sending messages 19 # sending messages
21 snd $port, type => data...; 20 snd $port, type => data...;
22 snd $port, @msg; 21 snd $port, @msg;
23 snd @msg_with_first_element_being_a_port; 22 snd @msg_with_first_element_being_a_port;
24 23
25 # creating/using ports, the simple way 24 # creating/using ports, the simple way
26 my $simple_port = port { my @msg = @_; 0 }; 25 my $simple_port = port { my @msg = @_ };
27 26
28 # creating/using ports, tagged message matching 27 # creating/using ports, tagged message matching
29 my $port = port; 28 my $port = port;
30 rcv $port, ping => sub { snd $_[0], "pong"; 0 }; 29 rcv $port, ping => sub { snd $_[0], "pong" };
31 rcv $port, pong => sub { warn "pong received\n"; 0 }; 30 rcv $port, pong => sub { warn "pong received\n" };
32 31
33 # create a port on another node 32 # create a port on another node
34 my $port = spawn $node, $initfunc, @initdata; 33 my $port = spawn $node, $initfunc, @initdata;
35 34
36 # monitoring 35 # monitoring
37 mon $port, $cb->(@msg) # callback is invoked on death 36 mon $localport, $cb->(@msg) # callback is invoked on death
38 mon $port, $otherport # kill otherport on abnormal death 37 mon $localport, $otherport # kill otherport on abnormal death
39 mon $port, $otherport, @msg # send message on death 38 mon $localport, $otherport, @msg # send message on death
40 39
41=head1 CURRENT STATUS 40=head1 CURRENT STATUS
42 41
42 bin/aemp - stable.
43 AnyEvent::MP - stable API, should work 43 AnyEvent::MP - stable API, should work.
44 AnyEvent::MP::Intro - outdated 44 AnyEvent::MP::Intro - explains most concepts.
45 AnyEvent::MP::Kernel - WIP
46 AnyEvent::MP::Transport - mostly stable 45 AnyEvent::MP::Kernel - mostly stable API.
47 46 AnyEvent::MP::Global - stable API.
48 stay tuned.
49 47
50=head1 DESCRIPTION 48=head1 DESCRIPTION
51 49
52This module (-family) implements a simple message passing framework. 50This module (-family) implements a simple message passing framework.
53 51
54Despite its simplicity, you can securely message other processes running 52Despite its simplicity, you can securely message other processes running
55on the same or other hosts. 53on the same or other hosts, and you can supervise entities remotely.
56 54
57For an introduction to this module family, see the L<AnyEvent::MP::Intro> 55For an introduction to this module family, see the L<AnyEvent::MP::Intro>
58manual page. 56manual page and the examples under F<eg/>.
59
60At the moment, this module family is severly broken and underdocumented,
61so do not use. This was uploaded mainly to reserve the CPAN namespace -
62stay tuned!
63 57
64=head1 CONCEPTS 58=head1 CONCEPTS
65 59
66=over 4 60=over 4
67 61
68=item port 62=item port
69 63
70A port is something you can send messages to (with the C<snd> function). 64Not to be confused with a TCP port, a "port" is something you can send
65messages to (with the C<snd> function).
71 66
72Ports allow you to register C<rcv> handlers that can match all or just 67Ports allow you to register C<rcv> handlers that can match all or just
73some messages. Messages send to ports will not be queued, regardless of 68some messages. Messages send to ports will not be queued, regardless of
74anything was listening for them or not. 69anything was listening for them or not.
75 70
76=item port ID - C<noderef#portname> 71=item port ID - C<nodeid#portname>
77 72
78A port ID is the concatenation of a noderef, a hash-mark (C<#>) as 73A port ID is the concatenation of a node ID, a hash-mark (C<#>) as
79separator, and a port name (a printable string of unspecified format). An 74separator, and a port name (a printable string of unspecified format).
80exception is the the node port, whose ID is identical to its node
81reference.
82 75
83=item node 76=item node
84 77
85A node is a single process containing at least one port - the node port, 78A node is a single process containing at least one port - the node port,
86which provides nodes to manage each other remotely, and to create new 79which enables nodes to manage each other remotely, and to create new
87ports. 80ports.
88 81
89Nodes are either private (single-process only), slaves (can only talk to 82Nodes are either public (have one or more listening ports) or private
90public nodes, but do not need an open port) or public nodes (connectable 83(no listening ports). Private nodes cannot talk to other private nodes
91from any other node). 84currently.
92 85
93=item node ID - C<[a-za-Z0-9_\-.:]+> 86=item node ID - C<[A-Z_][a-zA-Z0-9_\-.:]*>
94 87
95A node ID is a string that uniquely identifies the node within a 88A node ID is a string that uniquely identifies the node within a
96network. Depending on the configuration used, node IDs can look like a 89network. Depending on the configuration used, node IDs can look like a
97hostname, a hostname and a port, or a random string. AnyEvent::MP itself 90hostname, a hostname and a port, or a random string. AnyEvent::MP itself
98doesn't interpret node IDs in any way. 91doesn't interpret node IDs in any way.
102Nodes can only talk to each other by creating some kind of connection to 95Nodes can only talk to each other by creating some kind of connection to
103each other. To do this, nodes should listen on one or more local transport 96each other. To do this, nodes should listen on one or more local transport
104endpoints - binds. Currently, only standard C<ip:port> specifications can 97endpoints - binds. Currently, only standard C<ip:port> specifications can
105be used, which specify TCP ports to listen on. 98be used, which specify TCP ports to listen on.
106 99
107=item seeds - C<host:port> 100=item seed nodes
108 101
109When a node starts, it knows nothing about the network. To teach the node 102When a node starts, it knows nothing about the network. To teach the node
110about the network it first has to contact some other node within the 103about the network it first has to contact some other node within the
111network. This node is called a seed. 104network. This node is called a seed.
112 105
113Seeds are transport endpoint(s) of as many nodes as one wants. Those nodes 106Apart from the fact that other nodes know them as seed nodes and they have
107to have fixed listening addresses, seed nodes are perfectly normal nodes -
108any node can function as a seed node for others.
109
110In addition to discovering the network, seed nodes are also used to
111maintain the network and to connect nodes that otherwise would have
112trouble connecting. They form the backbone of an AnyEvent::MP network.
113
114are expected to be long-running, and at least one of those should always 114Seed nodes are expected to be long-running, and at least one seed node
115be available. When nodes run out of connections (e.g. due to a network 115should always be available. They should also be relatively responsive - a
116error), they try to re-establish connections to some seednodes again to 116seed node that blocks for long periods will slow down everybody else.
117join the network. 117
118=item seeds - C<host:port>
119
120Seeds are transport endpoint(s) (usually a hostname/IP address and a
121TCP port) of nodes thta should be used as seed nodes.
122
123The nodes listening on those endpoints are expected to be long-running,
124and at least one of those should always be available. When nodes run out
125of connections (e.g. due to a network error), they try to re-establish
126connections to some seednodes again to join the network.
118 127
119=back 128=back
120 129
121=head1 VARIABLES/FUNCTIONS 130=head1 VARIABLES/FUNCTIONS
122 131
138 147
139our $VERSION = $AnyEvent::MP::Kernel::VERSION; 148our $VERSION = $AnyEvent::MP::Kernel::VERSION;
140 149
141our @EXPORT = qw( 150our @EXPORT = qw(
142 NODE $NODE *SELF node_of after 151 NODE $NODE *SELF node_of after
143 resolve_node initialise_node 152 configure
144 snd rcv mon mon_guard kil reg psub spawn 153 snd rcv mon mon_guard kil psub spawn cal
145 port 154 port
146); 155);
147 156
148our $SELF; 157our $SELF;
149 158
153 kil $SELF, die => $msg; 162 kil $SELF, die => $msg;
154} 163}
155 164
156=item $thisnode = NODE / $NODE 165=item $thisnode = NODE / $NODE
157 166
158The C<NODE> function returns, and the C<$NODE> variable contains the node 167The C<NODE> function returns, and the C<$NODE> variable contains, the node
159ID of the node running in the current process. This value is initialised by 168ID of the node running in the current process. This value is initialised by
160a call to C<initialise_node>. 169a call to C<configure>.
161 170
162=item $nodeid = node_of $port 171=item $nodeid = node_of $port
163 172
164Extracts and returns the node ID part from a port ID or a node ID. 173Extracts and returns the node ID from a port ID or a node ID.
165 174
166=item initialise_node $profile_name 175=item configure $profile, key => value...
176
177=item configure key => value...
167 178
168Before a node can talk to other nodes on the network (i.e. enter 179Before a node can talk to other nodes on the network (i.e. enter
169"distributed mode") it has to initialise itself - the minimum a node needs 180"distributed mode") it has to configure itself - the minimum a node needs
170to know is its own name, and optionally it should know the addresses of 181to know is its own name, and optionally it should know the addresses of
171some other nodes in the network to discover other nodes. 182some other nodes in the network to discover other nodes.
172 183
173This function initialises a node - it must be called exactly once (or 184This function configures a node - it must be called exactly once (or
174never) before calling other AnyEvent::MP functions. 185never) before calling other AnyEvent::MP functions.
175 186
176The first argument is a profile name. If it is C<undef> or missing, then 187=over 4
177the current nodename will be used instead (i.e. F<uname -n>).
178 188
189=item step 1, gathering configuration from profiles
190
179The function then looks up the profile in the aemp configuration (see the 191The function first looks up a profile in the aemp configuration (see the
180L<aemp> commandline utility). 192L<aemp> commandline utility). The profile name can be specified via the
193named C<profile> parameter or can simply be the first parameter). If it is
194missing, then the nodename (F<uname -n>) will be used as profile name.
195
196The profile data is then gathered as follows:
197
198First, all remaining key => value pairs (all of which are conveniently
199undocumented at the moment) will be interpreted as configuration
200data. Then they will be overwritten by any values specified in the global
201default configuration (see the F<aemp> utility), then the chain of
202profiles chosen by the profile name (and any C<parent> attributes).
203
204That means that the values specified in the profile have highest priority
205and the values specified directly via C<configure> have lowest priority,
206and can only be used to specify defaults.
181 207
182If the profile specifies a node ID, then this will become the node ID of 208If the profile specifies a node ID, then this will become the node ID of
183this process. If not, then the profile name will be used as node ID. The 209this process. If not, then the profile name will be used as node ID. The
184special node ID of C<anon/> will be replaced by a random node ID. 210special node ID of C<anon/> will be replaced by a random node ID.
211
212=item step 2, bind listener sockets
185 213
186The next step is to look up the binds in the profile, followed by binding 214The next step is to look up the binds in the profile, followed by binding
187aemp protocol listeners on all binds specified (it is possible and valid 215aemp protocol listeners on all binds specified (it is possible and valid
188to have no binds, meaning that the node cannot be contacted form the 216to have no binds, meaning that the node cannot be contacted form the
189outside. This means the node cannot talk to other nodes that also have no 217outside. This means the node cannot talk to other nodes that also have no
190binds, but it can still talk to all "normal" nodes). 218binds, but it can still talk to all "normal" nodes).
191 219
192If the profile does not specify a binds list, then the node ID will be 220If the profile does not specify a binds list, then a default of C<*> is
193treated as if it were of the form C<host:port>, which will be resolved and 221used, meaning the node will bind on a dynamically-assigned port on every
194used as binds list. 222local IP address it finds.
195 223
224=item step 3, connect to seed nodes
225
196Lastly, the seeds list from the profile is passed to the 226As the last step, the seeds list from the profile is passed to the
197L<AnyEvent::MP::Global> module, which will then use it to keep 227L<AnyEvent::MP::Global> module, which will then use it to keep
198connectivity with at least on of those seed nodes at any point in time. 228connectivity with at least one node at any point in time.
199 229
200Example: become a distributed node listening on the guessed noderef, or 230=back
201the one specified via C<aemp> for the current node. This should be the 231
232Example: become a distributed node using the local node name as profile.
202most common form of invocation for "daemon"-type nodes. 233This should be the most common form of invocation for "daemon"-type nodes.
203 234
204 initialise_node; 235 configure
205 236
206Example: become an anonymous node. This form is often used for commandline 237Example: become an anonymous node. This form is often used for commandline
207clients. 238clients.
208 239
209 initialise_node "anon/"; 240 configure nodeid => "anon/";
210 241
211Example: become a distributed node. If there is no profile of the given 242Example: configure a node using a profile called seed, which si suitable
212name, or no binds list was specified, resolve C<localhost:4044> and bind 243for a seed node as it binds on all local addresses on a fixed port (4040,
213on the resulting addresses. 244customary for aemp).
214 245
215 initialise_node "localhost:4044"; 246 # use the aemp commandline utility
247 # aemp profile seed nodeid anon/ binds '*:4040'
248
249 # then use it
250 configure profile => "seed";
251
252 # or simply use aemp from the shell again:
253 # aemp run profile seed
254
255 # or provide a nicer-to-remember nodeid
256 # aemp run profile seed nodeid "$(hostname)"
216 257
217=item $SELF 258=item $SELF
218 259
219Contains the current port id while executing C<rcv> callbacks or C<psub> 260Contains the current port id while executing C<rcv> callbacks or C<psub>
220blocks. 261blocks.
221 262
222=item SELF, %SELF, @SELF... 263=item *SELF, SELF, %SELF, @SELF...
223 264
224Due to some quirks in how perl exports variables, it is impossible to 265Due to some quirks in how perl exports variables, it is impossible to
225just export C<$SELF>, all the symbols called C<SELF> are exported by this 266just export C<$SELF>, all the symbols named C<SELF> are exported by this
226module, but only C<$SELF> is currently used. 267module, but only C<$SELF> is currently used.
227 268
228=item snd $port, type => @data 269=item snd $port, type => @data
229 270
230=item snd $port, @msg 271=item snd $port, @msg
231 272
232Send the given message to the given port ID, which can identify either 273Send the given message to the given port, which can identify either a
233a local or a remote port, and must be a port ID. 274local or a remote port, and must be a port ID.
234 275
235While the message can be about anything, it is highly recommended to use a 276While the message can be almost anything, it is highly recommended to
236string as first element (a port ID, or some word that indicates a request 277use a string as first element (a port ID, or some word that indicates a
237type etc.). 278request type etc.) and to consist if only simple perl values (scalars,
279arrays, hashes) - if you think you need to pass an object, think again.
238 280
239The message data effectively becomes read-only after a call to this 281The message data logically becomes read-only after a call to this
240function: modifying any argument is not allowed and can cause many 282function: modifying any argument (or values referenced by them) is
241problems. 283forbidden, as there can be considerable time between the call to C<snd>
284and the time the message is actually being serialised - in fact, it might
285never be copied as within the same process it is simply handed to the
286receiving port.
242 287
243The type of data you can transfer depends on the transport protocol: when 288The type of data you can transfer depends on the transport protocol: when
244JSON is used, then only strings, numbers and arrays and hashes consisting 289JSON is used, then only strings, numbers and arrays and hashes consisting
245of those are allowed (no objects). When Storable is used, then anything 290of those are allowed (no objects). When Storable is used, then anything
246that Storable can serialise and deserialise is allowed, and for the local 291that Storable can serialise and deserialise is allowed, and for the local
247node, anything can be passed. 292node, anything can be passed. Best rely only on the common denominator of
293these.
248 294
249=item $local_port = port 295=item $local_port = port
250 296
251Create a new local port object and returns its port ID. Initially it has 297Create a new local port object and returns its port ID. Initially it has
252no callbacks set and will throw an error when it receives messages. 298no callbacks set and will throw an error when it receives messages.
337 383
338=cut 384=cut
339 385
340sub rcv($@) { 386sub rcv($@) {
341 my $port = shift; 387 my $port = shift;
342 my ($noderef, $portid) = split /#/, $port, 2; 388 my ($nodeid, $portid) = split /#/, $port, 2;
343 389
344 $NODE{$noderef} == $NODE{""} 390 $NODE{$nodeid} == $NODE{""}
345 or Carp::croak "$port: rcv can only be called on local ports, caught"; 391 or Carp::croak "$port: rcv can only be called on local ports, caught";
346 392
347 while (@_) { 393 while (@_) {
348 if (ref $_[0]) { 394 if (ref $_[0]) {
349 if (my $self = $PORT_DATA{$portid}) { 395 if (my $self = $PORT_DATA{$portid}) {
428 $res 474 $res
429 } 475 }
430 } 476 }
431} 477}
432 478
433=item $guard = mon $port, $cb->(@reason) 479=item $guard = mon $port, $cb->(@reason) # call $cb when $port dies
434 480
435=item $guard = mon $port, $rcvport 481=item $guard = mon $port, $rcvport # kill $rcvport when $port dies
436 482
437=item $guard = mon $port 483=item $guard = mon $port # kill $SELF when $port dies
438 484
439=item $guard = mon $port, $rcvport, @msg 485=item $guard = mon $port, $rcvport, @msg # send a message when $port dies
440 486
441Monitor the given port and do something when the port is killed or 487Monitor the given port and do something when the port is killed or
442messages to it were lost, and optionally return a guard that can be used 488messages to it were lost, and optionally return a guard that can be used
443to stop monitoring again. 489to stop monitoring again.
444
445C<mon> effectively guarantees that, in the absence of hardware failures,
446that after starting the monitor, either all messages sent to the port
447will arrive, or the monitoring action will be invoked after possible
448message loss has been detected. No messages will be lost "in between"
449(after the first lost message no further messages will be received by the
450port). After the monitoring action was invoked, further messages might get
451delivered again.
452
453Note that monitoring-actions are one-shot: once released, they are removed
454and will not trigger again.
455 490
456In the first form (callback), the callback is simply called with any 491In the first form (callback), the callback is simply called with any
457number of C<@reason> elements (no @reason means that the port was deleted 492number of C<@reason> elements (no @reason means that the port was deleted
458"normally"). Note also that I<< the callback B<must> never die >>, so use 493"normally"). Note also that I<< the callback B<must> never die >>, so use
459C<eval> if unsure. 494C<eval> if unsure.
460 495
461In the second form (another port given), the other port (C<$rcvport>) 496In the second form (another port given), the other port (C<$rcvport>)
462will be C<kil>'ed with C<@reason>, iff a @reason was specified, i.e. on 497will be C<kil>'ed with C<@reason>, if a @reason was specified, i.e. on
463"normal" kils nothing happens, while under all other conditions, the other 498"normal" kils nothing happens, while under all other conditions, the other
464port is killed with the same reason. 499port is killed with the same reason.
465 500
466The third form (kill self) is the same as the second form, except that 501The third form (kill self) is the same as the second form, except that
467C<$rvport> defaults to C<$SELF>. 502C<$rvport> defaults to C<$SELF>.
468 503
469In the last form (message), a message of the form C<@msg, @reason> will be 504In the last form (message), a message of the form C<@msg, @reason> will be
470C<snd>. 505C<snd>.
506
507Monitoring-actions are one-shot: once messages are lost (and a monitoring
508alert was raised), they are removed and will not trigger again.
471 509
472As a rule of thumb, monitoring requests should always monitor a port from 510As a rule of thumb, monitoring requests should always monitor a port from
473a local port (or callback). The reason is that kill messages might get 511a local port (or callback). The reason is that kill messages might get
474lost, just like any other message. Another less obvious reason is that 512lost, just like any other message. Another less obvious reason is that
475even monitoring requests can get lost (for exmaple, when the connection 513even monitoring requests can get lost (for example, when the connection
476to the other node goes down permanently). When monitoring a port locally 514to the other node goes down permanently). When monitoring a port locally
477these problems do not exist. 515these problems do not exist.
478 516
517C<mon> effectively guarantees that, in the absence of hardware failures,
518after starting the monitor, either all messages sent to the port will
519arrive, or the monitoring action will be invoked after possible message
520loss has been detected. No messages will be lost "in between" (after
521the first lost message no further messages will be received by the
522port). After the monitoring action was invoked, further messages might get
523delivered again.
524
525Inter-host-connection timeouts and monitoring depend on the transport
526used. The only transport currently implemented is TCP, and AnyEvent::MP
527relies on TCP to detect node-downs (this can take 10-15 minutes on a
528non-idle connection, and usually around two hours for idle conenctions).
529
530This means that monitoring is good for program errors and cleaning up
531stuff eventually, but they are no replacement for a timeout when you need
532to ensure some maximum latency.
533
479Example: call a given callback when C<$port> is killed. 534Example: call a given callback when C<$port> is killed.
480 535
481 mon $port, sub { warn "port died because of <@_>\n" }; 536 mon $port, sub { warn "port died because of <@_>\n" };
482 537
483Example: kill ourselves when C<$port> is killed abnormally. 538Example: kill ourselves when C<$port> is killed abnormally.
489 mon $port, $self => "restart"; 544 mon $port, $self => "restart";
490 545
491=cut 546=cut
492 547
493sub mon { 548sub mon {
494 my ($noderef, $port) = split /#/, shift, 2; 549 my ($nodeid, $port) = split /#/, shift, 2;
495 550
496 my $node = $NODE{$noderef} || add_node $noderef; 551 my $node = $NODE{$nodeid} || add_node $nodeid;
497 552
498 my $cb = @_ ? shift : $SELF || Carp::croak 'mon: called with one argument only, but $SELF not set,'; 553 my $cb = @_ ? shift : $SELF || Carp::croak 'mon: called with one argument only, but $SELF not set,';
499 554
500 unless (ref $cb) { 555 unless (ref $cb) {
501 if (@_) { 556 if (@_) {
509 } 564 }
510 } 565 }
511 566
512 $node->monitor ($port, $cb); 567 $node->monitor ($port, $cb);
513 568
569 $cb += 0;
570
514 defined wantarray 571 defined wantarray
515 and AnyEvent::Util::guard { $node->unmonitor ($port, $cb) } 572 and AnyEvent::Util::guard { $node->unmonitor ($port, $cb) }
516} 573}
517 574
518=item $guard = mon_guard $port, $ref, $ref... 575=item $guard = mon_guard $port, $ref, $ref...
521is killed, the references will be freed. 578is killed, the references will be freed.
522 579
523Optionally returns a guard that will stop the monitoring. 580Optionally returns a guard that will stop the monitoring.
524 581
525This function is useful when you create e.g. timers or other watchers and 582This function is useful when you create e.g. timers or other watchers and
526want to free them when the port gets killed: 583want to free them when the port gets killed (note the use of C<psub>):
527 584
528 $port->rcv (start => sub { 585 $port->rcv (start => sub {
529 my $timer; $timer = mon_guard $port, AE::timer 1, 1, sub { 586 my $timer; $timer = mon_guard $port, AE::timer 1, 1, psub {
530 undef $timer if 0.9 < rand; 587 undef $timer if 0.9 < rand;
531 }); 588 });
532 }); 589 });
533 590
534=cut 591=cut
543 600
544=item kil $port[, @reason] 601=item kil $port[, @reason]
545 602
546Kill the specified port with the given C<@reason>. 603Kill the specified port with the given C<@reason>.
547 604
548If no C<@reason> is specified, then the port is killed "normally" (linked 605If no C<@reason> is specified, then the port is killed "normally" (ports
549ports will not be kileld, or even notified). 606monitoring other ports will not necessarily die because a port dies
607"normally").
550 608
551Otherwise, linked ports get killed with the same reason (second form of 609Otherwise, linked ports get killed with the same reason (second form of
552C<mon>, see below). 610C<mon>, see above).
553 611
554Runtime errors while evaluating C<rcv> callbacks or inside C<psub> blocks 612Runtime errors while evaluating C<rcv> callbacks or inside C<psub> blocks
555will be reported as reason C<< die => $@ >>. 613will be reported as reason C<< die => $@ >>.
556 614
557Transport/communication errors are reported as C<< transport_error => 615Transport/communication errors are reported as C<< transport_error =>
562=item $port = spawn $node, $initfunc[, @initdata] 620=item $port = spawn $node, $initfunc[, @initdata]
563 621
564Creates a port on the node C<$node> (which can also be a port ID, in which 622Creates a port on the node C<$node> (which can also be a port ID, in which
565case it's the node where that port resides). 623case it's the node where that port resides).
566 624
567The port ID of the newly created port is return immediately, and it is 625The port ID of the newly created port is returned immediately, and it is
568permissible to immediately start sending messages or monitor the port. 626possible to immediately start sending messages or to monitor the port.
569 627
570After the port has been created, the init function is 628After the port has been created, the init function is called on the remote
571called. This function must be a fully-qualified function name 629node, in the same context as a C<rcv> callback. This function must be a
572(e.g. C<MyApp::Chat::Server::init>). To specify a function in the main 630fully-qualified function name (e.g. C<MyApp::Chat::Server::init>). To
573program, use C<::name>. 631specify a function in the main program, use C<::name>.
574 632
575If the function doesn't exist, then the node tries to C<require> 633If the function doesn't exist, then the node tries to C<require>
576the package, then the package above the package and so on (e.g. 634the package, then the package above the package and so on (e.g.
577C<MyApp::Chat::Server>, C<MyApp::Chat>, C<MyApp>) until the function 635C<MyApp::Chat::Server>, C<MyApp::Chat>, C<MyApp>) until the function
578exists or it runs out of package names. 636exists or it runs out of package names.
579 637
580The init function is then called with the newly-created port as context 638The init function is then called with the newly-created port as context
581object (C<$SELF>) and the C<@initdata> values as arguments. 639object (C<$SELF>) and the C<@initdata> values as arguments. It I<must>
640call one of the C<rcv> functions to set callbacks on C<$SELF>, otherwise
641the port might not get created.
582 642
583A common idiom is to pass your own port, monitor the spawned port, and 643A common idiom is to pass a local port, immediately monitor the spawned
584in the init function, monitor the original port. This two-way monitoring 644port, and in the remote init function, immediately monitor the passed
585ensures that both ports get cleaned up when there is a problem. 645local port. This two-way monitoring ensures that both ports get cleaned up
646when there is a problem.
647
648C<spawn> guarantees that the C<$initfunc> has no visible effects on the
649caller before C<spawn> returns (by delaying invocation when spawn is
650called for the local node).
586 651
587Example: spawn a chat server port on C<$othernode>. 652Example: spawn a chat server port on C<$othernode>.
588 653
589 # this node, executed from within a port context: 654 # this node, executed from within a port context:
590 my $server = spawn $othernode, "MyApp::Chat::Server::connect", $SELF; 655 my $server = spawn $othernode, "MyApp::Chat::Server::connect", $SELF;
605 670
606sub _spawn { 671sub _spawn {
607 my $port = shift; 672 my $port = shift;
608 my $init = shift; 673 my $init = shift;
609 674
675 # rcv will create the actual port
610 local $SELF = "$NODE#$port"; 676 local $SELF = "$NODE#$port";
611 eval { 677 eval {
612 &{ load_func $init } 678 &{ load_func $init }
613 }; 679 };
614 _self_die if $@; 680 _self_die if $@;
615} 681}
616 682
617sub spawn(@) { 683sub spawn(@) {
618 my ($noderef, undef) = split /#/, shift, 2; 684 my ($nodeid, undef) = split /#/, shift, 2;
619 685
620 my $id = "$RUNIQ." . $ID++; 686 my $id = "$RUNIQ." . $ID++;
621 687
622 $_[0] =~ /::/ 688 $_[0] =~ /::/
623 or Carp::croak "spawn init function must be a fully-qualified name, caught"; 689 or Carp::croak "spawn init function must be a fully-qualified name, caught";
624 690
625 snd_to_func $noderef, "AnyEvent::MP::_spawn" => $id, @_; 691 snd_to_func $nodeid, "AnyEvent::MP::_spawn" => $id, @_;
626 692
627 "$noderef#$id" 693 "$nodeid#$id"
628} 694}
629 695
630=item after $timeout, @msg 696=item after $timeout, @msg
631 697
632=item after $timeout, $callback 698=item after $timeout, $callback
633 699
634Either sends the given message, or call the given callback, after the 700Either sends the given message, or call the given callback, after the
635specified number of seconds. 701specified number of seconds.
636 702
637This is simply a utility function that come sin handy at times. 703This is simply a utility function that comes in handy at times - the
704AnyEvent::MP author is not convinced of the wisdom of having it, though,
705so it may go away in the future.
638 706
639=cut 707=cut
640 708
641sub after($@) { 709sub after($@) {
642 my ($timeout, @action) = @_; 710 my ($timeout, @action) = @_;
647 ? $action[0]() 715 ? $action[0]()
648 : snd @action; 716 : snd @action;
649 }; 717 };
650} 718}
651 719
720=item cal $port, @msg, $callback[, $timeout]
721
722A simple form of RPC - sends a message to the given C<$port> with the
723given contents (C<@msg>), but adds a reply port to the message.
724
725The reply port is created temporarily just for the purpose of receiving
726the reply, and will be C<kil>ed when no longer needed.
727
728A reply message sent to the port is passed to the C<$callback> as-is.
729
730If an optional time-out (in seconds) is given and it is not C<undef>,
731then the callback will be called without any arguments after the time-out
732elapsed and the port is C<kil>ed.
733
734If no time-out is given, then the local port will monitor the remote port
735instead, so it eventually gets cleaned-up.
736
737Currently this function returns the temporary port, but this "feature"
738might go in future versions unless you can make a convincing case that
739this is indeed useful for something.
740
741=cut
742
743sub cal(@) {
744 my $timeout = ref $_[-1] ? undef : pop;
745 my $cb = pop;
746
747 my $port = port {
748 undef $timeout;
749 kil $SELF;
750 &$cb;
751 };
752
753 if (defined $timeout) {
754 $timeout = AE::timer $timeout, 0, sub {
755 undef $timeout;
756 kil $port;
757 $cb->();
758 };
759 } else {
760 mon $_[0], sub {
761 kil $port;
762 $cb->();
763 };
764 }
765
766 push @_, $port;
767 &snd;
768
769 $port
770}
771
652=back 772=back
653 773
654=head1 AnyEvent::MP vs. Distributed Erlang 774=head1 AnyEvent::MP vs. Distributed Erlang
655 775
656AnyEvent::MP got lots of its ideas from distributed Erlang (Erlang node 776AnyEvent::MP got lots of its ideas from distributed Erlang (Erlang node
665 785
666Despite the similarities, there are also some important differences: 786Despite the similarities, there are also some important differences:
667 787
668=over 4 788=over 4
669 789
670=item * Node references contain the recipe on how to contact them. 790=item * Node IDs are arbitrary strings in AEMP.
671 791
672Erlang relies on special naming and DNS to work everywhere in the 792Erlang relies on special naming and DNS to work everywhere in the same
673same way. AEMP relies on each node knowing it's own address(es), with 793way. AEMP relies on each node somehow knowing its own address(es) (e.g. by
674convenience functionality. 794configuration or DNS), but will otherwise discover other odes itself.
675
676This means that AEMP requires a less tightly controlled environment at the
677cost of longer node references and a slightly higher management overhead.
678 795
679=item * Erlang has a "remote ports are like local ports" philosophy, AEMP 796=item * Erlang has a "remote ports are like local ports" philosophy, AEMP
680uses "local ports are like remote ports". 797uses "local ports are like remote ports".
681 798
682The failure modes for local ports are quite different (runtime errors 799The failure modes for local ports are quite different (runtime errors
695 812
696Erlang uses processes that selectively receive messages, and therefore 813Erlang uses processes that selectively receive messages, and therefore
697needs a queue. AEMP is event based, queuing messages would serve no 814needs a queue. AEMP is event based, queuing messages would serve no
698useful purpose. For the same reason the pattern-matching abilities of 815useful purpose. For the same reason the pattern-matching abilities of
699AnyEvent::MP are more limited, as there is little need to be able to 816AnyEvent::MP are more limited, as there is little need to be able to
700filter messages without dequeing them. 817filter messages without dequeuing them.
701 818
702(But see L<Coro::MP> for a more Erlang-like process model on top of AEMP). 819(But see L<Coro::MP> for a more Erlang-like process model on top of AEMP).
703 820
704=item * Erlang sends are synchronous, AEMP sends are asynchronous. 821=item * Erlang sends are synchronous, AEMP sends are asynchronous.
705 822
711 828
712Erlang makes few guarantees on messages delivery - messages can get lost 829Erlang makes few guarantees on messages delivery - messages can get lost
713without any of the processes realising it (i.e. you send messages a, b, 830without any of the processes realising it (i.e. you send messages a, b,
714and c, and the other side only receives messages a and c). 831and c, and the other side only receives messages a and c).
715 832
716AEMP guarantees correct ordering, and the guarantee that there are no 833AEMP guarantees correct ordering, and the guarantee that after one message
717holes in the message sequence. 834is lost, all following ones sent to the same port are lost as well, until
718 835monitoring raises an error, so there are no silent "holes" in the message
719=item * In Erlang, processes can be declared dead and later be found to be 836sequence.
720alive.
721
722In Erlang it can happen that a monitored process is declared dead and
723linked processes get killed, but later it turns out that the process is
724still alive - and can receive messages.
725
726In AEMP, when port monitoring detects a port as dead, then that port will
727eventually be killed - it cannot happen that a node detects a port as dead
728and then later sends messages to it, finding it is still alive.
729 837
730=item * Erlang can send messages to the wrong port, AEMP does not. 838=item * Erlang can send messages to the wrong port, AEMP does not.
731 839
732In Erlang it is quite likely that a node that restarts reuses a process ID 840In Erlang it is quite likely that a node that restarts reuses a process ID
733known to other nodes for a completely different process, causing messages 841known to other nodes for a completely different process, causing messages
737around in the network will not be sent to an unrelated port. 845around in the network will not be sent to an unrelated port.
738 846
739=item * Erlang uses unprotected connections, AEMP uses secure 847=item * Erlang uses unprotected connections, AEMP uses secure
740authentication and can use TLS. 848authentication and can use TLS.
741 849
742AEMP can use a proven protocol - SSL/TLS - to protect connections and 850AEMP can use a proven protocol - TLS - to protect connections and
743securely authenticate nodes. 851securely authenticate nodes.
744 852
745=item * The AEMP protocol is optimised for both text-based and binary 853=item * The AEMP protocol is optimised for both text-based and binary
746communications. 854communications.
747 855
748The AEMP protocol, unlike the Erlang protocol, supports both 856The AEMP protocol, unlike the Erlang protocol, supports both programming
749language-independent text-only protocols (good for debugging) and binary, 857language independent text-only protocols (good for debugging) and binary,
750language-specific serialisers (e.g. Storable). 858language-specific serialisers (e.g. Storable). By default, unless TLS is
859used, the protocol is actually completely text-based.
751 860
752It has also been carefully designed to be implementable in other languages 861It has also been carefully designed to be implementable in other languages
753with a minimum of work while gracefully degrading fucntionality to make the 862with a minimum of work while gracefully degrading functionality to make the
754protocol simple. 863protocol simple.
755 864
756=item * AEMP has more flexible monitoring options than Erlang. 865=item * AEMP has more flexible monitoring options than Erlang.
757 866
758In Erlang, you can chose to receive I<all> exit signals as messages 867In Erlang, you can chose to receive I<all> exit signals as messages
761Erlang, as one can choose between automatic kill, exit message or callback 870Erlang, as one can choose between automatic kill, exit message or callback
762on a per-process basis. 871on a per-process basis.
763 872
764=item * Erlang tries to hide remote/local connections, AEMP does not. 873=item * Erlang tries to hide remote/local connections, AEMP does not.
765 874
766Monitoring in Erlang is not an indicator of process death/crashes, 875Monitoring in Erlang is not an indicator of process death/crashes, in the
767as linking is (except linking is unreliable in Erlang). 876same way as linking is (except linking is unreliable in Erlang).
768 877
769In AEMP, you don't "look up" registered port names or send to named ports 878In AEMP, you don't "look up" registered port names or send to named ports
770that might or might not be persistent. Instead, you normally spawn a port 879that might or might not be persistent. Instead, you normally spawn a port
771on the remote node. The init function monitors the you, and you monitor 880on the remote node. The init function monitors you, and you monitor the
772the remote port. Since both monitors are local to the node, they are much 881remote port. Since both monitors are local to the node, they are much more
773more reliable. 882reliable (no need for C<spawn_link>).
774 883
775This also saves round-trips and avoids sending messages to the wrong port 884This also saves round-trips and avoids sending messages to the wrong port
776(hard to do in Erlang). 885(hard to do in Erlang).
777 886
778=back 887=back
779 888
780=head1 RATIONALE 889=head1 RATIONALE
781 890
782=over 4 891=over 4
783 892
784=item Why strings for ports and noderefs, why not objects? 893=item Why strings for port and node IDs, why not objects?
785 894
786We considered "objects", but found that the actual number of methods 895We considered "objects", but found that the actual number of methods
787thatc an be called are very low. Since port IDs and noderefs travel over 896that can be called are quite low. Since port and node IDs travel over
788the network frequently, the serialising/deserialising would add lots of 897the network frequently, the serialising/deserialising would add lots of
789overhead, as well as having to keep a proxy object. 898overhead, as well as having to keep a proxy object everywhere.
790 899
791Strings can easily be printed, easily serialised etc. and need no special 900Strings can easily be printed, easily serialised etc. and need no special
792procedures to be "valid". 901procedures to be "valid".
793 902
794And a a miniport consists of a single closure stored in a global hash - it 903And as a result, a miniport consists of a single closure stored in a
795can't become much cheaper. 904global hash - it can't become much cheaper.
796 905
797=item Why favour JSON, why not real serialising format such as Storable? 906=item Why favour JSON, why not a real serialising format such as Storable?
798 907
799In fact, any AnyEvent::MP node will happily accept Storable as framing 908In fact, any AnyEvent::MP node will happily accept Storable as framing
800format, but currently there is no way to make a node use Storable by 909format, but currently there is no way to make a node use Storable by
801default. 910default (although all nodes will accept it).
802 911
803The default framing protocol is JSON because a) JSON::XS is many times 912The default framing protocol is JSON because a) JSON::XS is many times
804faster for small messages and b) most importantly, after years of 913faster for small messages and b) most importantly, after years of
805experience we found that object serialisation is causing more problems 914experience we found that object serialisation is causing more problems
806than it gains: Just like function calls, objects simply do not travel 915than it solves: Just like function calls, objects simply do not travel
807easily over the network, mostly because they will always be a copy, so you 916easily over the network, mostly because they will always be a copy, so you
808always have to re-think your design. 917always have to re-think your design.
809 918
810Keeping your messages simple, concentrating on data structures rather than 919Keeping your messages simple, concentrating on data structures rather than
811objects, will keep your messages clean, tidy and efficient. 920objects, will keep your messages clean, tidy and efficient.
812 921
813=back 922=back
814 923
815=head1 SEE ALSO 924=head1 SEE ALSO
816 925
926L<AnyEvent::MP::Intro> - a gentle introduction.
927
928L<AnyEvent::MP::Kernel> - more, lower-level, stuff.
929
930L<AnyEvent::MP::Global> - network maintainance and port groups, to find
931your applications.
932
933L<AnyEvent::MP::LogCatcher> - simple service to display log messages from
934all nodes.
935
817L<AnyEvent>. 936L<AnyEvent>.
818 937
819=head1 AUTHOR 938=head1 AUTHOR
820 939
821 Marc Lehmann <schmorp@schmorp.de> 940 Marc Lehmann <schmorp@schmorp.de>

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines