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.71 by root, Sun Aug 30 19:52:56 2009 UTC vs.
Revision 1.117 by root, Wed Oct 27 06:32:39 2010 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
35 # destroy a port again
36 kil $port; # "normal" kill
37 kil $port, my_error => "everything is broken"; # error kill
38
36 # monitoring 39 # monitoring
37 mon $port, $cb->(@msg) # callback is invoked on death 40 mon $localport, $cb->(@msg) # callback is invoked on death
38 mon $port, $otherport # kill otherport on abnormal death 41 mon $localport, $otherport # kill otherport on abnormal death
39 mon $port, $otherport, @msg # send message on death 42 mon $localport, $otherport, @msg # send message on death
43
44 # temporarily execute code in port context
45 peval $port, sub { die "kill the port!" };
46
47 # execute callbacks in $SELF port context
48 my $timer = AE::timer 1, 0, psub {
49 die "kill the port, delayed";
50 };
40 51
41=head1 CURRENT STATUS 52=head1 CURRENT STATUS
42 53
43 bin/aemp - stable. 54 bin/aemp - stable.
44 AnyEvent::MP - stable API, should work. 55 AnyEvent::MP - stable API, should work.
45 AnyEvent::MP::Intro - uptodate, but incomplete. 56 AnyEvent::MP::Intro - explains most concepts.
46 AnyEvent::MP::Kernel - mostly stable. 57 AnyEvent::MP::Kernel - mostly stable API.
47 AnyEvent::MP::Global - stable API, protocol not yet final. 58 AnyEvent::MP::Global - stable API.
48
49 stay tuned.
50 59
51=head1 DESCRIPTION 60=head1 DESCRIPTION
52 61
53This module (-family) implements a simple message passing framework. 62This module (-family) implements a simple message passing framework.
54 63
56on the same or other hosts, and you can supervise entities remotely. 65on the same or other hosts, and you can supervise entities remotely.
57 66
58For an introduction to this module family, see the L<AnyEvent::MP::Intro> 67For an introduction to this module family, see the L<AnyEvent::MP::Intro>
59manual page and the examples under F<eg/>. 68manual page and the examples under F<eg/>.
60 69
61At the moment, this module family is a bit underdocumented.
62
63=head1 CONCEPTS 70=head1 CONCEPTS
64 71
65=over 4 72=over 4
66 73
67=item port 74=item port
68 75
69A port is something you can send messages to (with the C<snd> function). 76Not to be confused with a TCP port, a "port" is something you can send
77messages to (with the C<snd> function).
70 78
71Ports allow you to register C<rcv> handlers that can match all or just 79Ports allow you to register C<rcv> handlers that can match all or just
72some messages. Messages send to ports will not be queued, regardless of 80some messages. Messages send to ports will not be queued, regardless of
73anything was listening for them or not. 81anything was listening for them or not.
74 82
85 93
86Nodes are either public (have one or more listening ports) or private 94Nodes are either public (have one or more listening ports) or private
87(no listening ports). Private nodes cannot talk to other private nodes 95(no listening ports). Private nodes cannot talk to other private nodes
88currently. 96currently.
89 97
90=item node ID - C<[a-za-Z0-9_\-.:]+> 98=item node ID - C<[A-Za-z0-9_\-.:]*>
91 99
92A node ID is a string that uniquely identifies the node within a 100A node ID is a string that uniquely identifies the node within a
93network. Depending on the configuration used, node IDs can look like a 101network. Depending on the configuration used, node IDs can look like a
94hostname, a hostname and a port, or a random string. AnyEvent::MP itself 102hostname, a hostname and a port, or a random string. AnyEvent::MP itself
95doesn't interpret node IDs in any way. 103doesn't interpret node IDs in any way.
99Nodes can only talk to each other by creating some kind of connection to 107Nodes can only talk to each other by creating some kind of connection to
100each other. To do this, nodes should listen on one or more local transport 108each other. To do this, nodes should listen on one or more local transport
101endpoints - binds. Currently, only standard C<ip:port> specifications can 109endpoints - binds. Currently, only standard C<ip:port> specifications can
102be used, which specify TCP ports to listen on. 110be used, which specify TCP ports to listen on.
103 111
104=item seeds - C<host:port> 112=item seed nodes
105 113
106When a node starts, it knows nothing about the network. To teach the node 114When a node starts, it knows nothing about the network. To teach the node
107about the network it first has to contact some other node within the 115about the network it first has to contact some other node within the
108network. This node is called a seed. 116network. This node is called a seed.
109 117
110Seeds are transport endpoint(s) of as many nodes as one wants. Those nodes 118Apart from the fact that other nodes know them as seed nodes and they have
119to have fixed listening addresses, seed nodes are perfectly normal nodes -
120any node can function as a seed node for others.
121
122In addition to discovering the network, seed nodes are also used to
123maintain the network and to connect nodes that otherwise would have
124trouble connecting. They form the backbone of an AnyEvent::MP network.
125
111are expected to be long-running, and at least one of those should always 126Seed nodes are expected to be long-running, and at least one seed node
112be available. When nodes run out of connections (e.g. due to a network 127should always be available. They should also be relatively responsive - a
113error), they try to re-establish connections to some seednodes again to 128seed node that blocks for long periods will slow down everybody else.
114join the network.
115 129
116Apart from being sued for seeding, seednodes are not special in any way - 130=item seeds - C<host:port>
117every public node can be a seednode. 131
132Seeds are transport endpoint(s) (usually a hostname/IP address and a
133TCP port) of nodes that should be used as seed nodes.
134
135The nodes listening on those endpoints are expected to be long-running,
136and at least one of those should always be available. When nodes run out
137of connections (e.g. due to a network error), they try to re-establish
138connections to some seednodes again to join the network.
118 139
119=back 140=back
120 141
121=head1 VARIABLES/FUNCTIONS 142=head1 VARIABLES/FUNCTIONS
122 143
134 155
135use AE (); 156use AE ();
136 157
137use base "Exporter"; 158use base "Exporter";
138 159
139our $VERSION = $AnyEvent::MP::Kernel::VERSION; 160our $VERSION = 1.29;
140 161
141our @EXPORT = qw( 162our @EXPORT = qw(
142 NODE $NODE *SELF node_of after 163 NODE $NODE *SELF node_of after
143 initialise_node 164 configure
144 snd rcv mon mon_guard kil reg psub spawn 165 snd rcv mon mon_guard kil psub peval spawn cal
145 port 166 port
146); 167);
147 168
148our $SELF; 169our $SELF;
149 170
155 176
156=item $thisnode = NODE / $NODE 177=item $thisnode = NODE / $NODE
157 178
158The C<NODE> function returns, and the C<$NODE> variable contains, the node 179The 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 180ID of the node running in the current process. This value is initialised by
160a call to C<initialise_node>. 181a call to C<configure>.
161 182
162=item $nodeid = node_of $port 183=item $nodeid = node_of $port
163 184
164Extracts and returns the node ID from a port ID or a node ID. 185Extracts and returns the node ID from a port ID or a node ID.
165 186
166=item initialise_node $profile_name, key => value... 187=item configure $profile, key => value...
188
189=item configure key => value...
167 190
168Before a node can talk to other nodes on the network (i.e. enter 191Before 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 192"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 193to know is its own name, and optionally it should know the addresses of
171some other nodes in the network to discover other nodes. 194some other nodes in the network to discover other nodes.
172 195
196The key/value pairs are basically the same ones as documented for the
197F<aemp> command line utility (sans the set/del prefix).
198
173This function initialises a node - it must be called exactly once (or 199This function configures a node - it must be called exactly once (or
174never) before calling other AnyEvent::MP functions. 200never) before calling other AnyEvent::MP functions.
175 201
176The first argument is a profile name. If it is C<undef> or missing, then 202=over 4
177the current nodename will be used instead (i.e. F<uname -n>).
178 203
204=item step 1, gathering configuration from profiles
205
179The function first looks up the profile in the aemp configuration (see the 206The function first looks up a profile in the aemp configuration (see the
180L<aemp> commandline utility). the profile is calculated as follows: 207L<aemp> commandline utility). The profile name can be specified via the
208named C<profile> parameter or can simply be the first parameter). If it is
209missing, then the nodename (F<uname -n>) will be used as profile name.
181 210
211The profile data is then gathered as follows:
212
182First, all remaining key => value pairs (all of which are conviniently 213First, all remaining key => value pairs (all of which are conveniently
183undocumented at the moment) will be used. Then they will be overwritten by 214undocumented at the moment) will be interpreted as configuration
184any values specified in the global default configuration (see the F<aemp> 215data. Then they will be overwritten by any values specified in the global
185utility), then the chain of profiles selected, if any. That means that 216default configuration (see the F<aemp> utility), then the chain of
217profiles chosen by the profile name (and any C<parent> attributes).
218
186the values specified in the profile have highest priority and the values 219That means that the values specified in the profile have highest priority
187specified via C<initialise_node> have lowest priority. 220and the values specified directly via C<configure> have lowest priority,
221and can only be used to specify defaults.
188 222
189If the profile specifies a node ID, then this will become the node ID of 223If the profile specifies a node ID, then this will become the node ID of
190this process. If not, then the profile name will be used as node ID. The 224this process. If not, then the profile name will be used as node ID. The
191special node ID of C<anon/> will be replaced by a random node ID. 225special node ID of C<anon/> will be replaced by a random node ID.
226
227=item step 2, bind listener sockets
192 228
193The next step is to look up the binds in the profile, followed by binding 229The next step is to look up the binds in the profile, followed by binding
194aemp protocol listeners on all binds specified (it is possible and valid 230aemp protocol listeners on all binds specified (it is possible and valid
195to have no binds, meaning that the node cannot be contacted form the 231to have no binds, meaning that the node cannot be contacted form the
196outside. This means the node cannot talk to other nodes that also have no 232outside. This means the node cannot talk to other nodes that also have no
197binds, but it can still talk to all "normal" nodes). 233binds, but it can still talk to all "normal" nodes).
198 234
199If the profile does not specify a binds list, then a default of C<*> is 235If the profile does not specify a binds list, then a default of C<*> is
200used. 236used, meaning the node will bind on a dynamically-assigned port on every
237local IP address it finds.
201 238
239=item step 3, connect to seed nodes
240
202Lastly, the seeds list from the profile is passed to the 241As the last step, the seeds list from the profile is passed to the
203L<AnyEvent::MP::Global> module, which will then use it to keep 242L<AnyEvent::MP::Global> module, which will then use it to keep
204connectivity with at least on of those seed nodes at any point in time. 243connectivity with at least one node at any point in time.
205 244
206Example: become a distributed node listening on the guessed noderef, or 245=back
207the one specified via C<aemp> for the current node. This should be the 246
247Example: become a distributed node using the local node name as profile.
208most common form of invocation for "daemon"-type nodes. 248This should be the most common form of invocation for "daemon"-type nodes.
209 249
210 initialise_node; 250 configure
211 251
212Example: become an anonymous node. This form is often used for commandline 252Example: become an anonymous node. This form is often used for commandline
213clients. 253clients.
214 254
215 initialise_node "anon/"; 255 configure nodeid => "anon/";
216 256
217Example: become a distributed node. If there is no profile of the given 257Example: configure a node using a profile called seed, which si suitable
218name, or no binds list was specified, resolve C<localhost:4044> and bind 258for a seed node as it binds on all local addresses on a fixed port (4040,
219on the resulting addresses. 259customary for aemp).
220 260
221 initialise_node "localhost:4044"; 261 # use the aemp commandline utility
262 # aemp profile seed nodeid anon/ binds '*:4040'
263
264 # then use it
265 configure profile => "seed";
266
267 # or simply use aemp from the shell again:
268 # aemp run profile seed
269
270 # or provide a nicer-to-remember nodeid
271 # aemp run profile seed nodeid "$(hostname)"
222 272
223=item $SELF 273=item $SELF
224 274
225Contains the current port id while executing C<rcv> callbacks or C<psub> 275Contains the current port id while executing C<rcv> callbacks or C<psub>
226blocks. 276blocks.
336 msg1 => sub { ... }, 386 msg1 => sub { ... },
337 ... 387 ...
338 ; 388 ;
339 389
340Example: temporarily register a rcv callback for a tag matching some port 390Example: temporarily register a rcv callback for a tag matching some port
341(e.g. for a rpc reply) and unregister it after a message was received. 391(e.g. for an rpc reply) and unregister it after a message was received.
342 392
343 rcv $port, $otherport => sub { 393 rcv $port, $otherport => sub {
344 my @reply = @_; 394 my @reply = @_;
345 395
346 rcv $SELF, $otherport; 396 rcv $SELF, $otherport;
348 398
349=cut 399=cut
350 400
351sub rcv($@) { 401sub rcv($@) {
352 my $port = shift; 402 my $port = shift;
353 my ($noderef, $portid) = split /#/, $port, 2; 403 my ($nodeid, $portid) = split /#/, $port, 2;
354 404
355 $NODE{$noderef} == $NODE{""} 405 $NODE{$nodeid} == $NODE{""}
356 or Carp::croak "$port: rcv can only be called on local ports, caught"; 406 or Carp::croak "$port: rcv can only be called on local ports, caught";
357 407
358 while (@_) { 408 while (@_) {
359 if (ref $_[0]) { 409 if (ref $_[0]) {
360 if (my $self = $PORT_DATA{$portid}) { 410 if (my $self = $PORT_DATA{$portid}) {
361 "AnyEvent::MP::Port" eq ref $self 411 "AnyEvent::MP::Port" eq ref $self
362 or Carp::croak "$port: rcv can only be called on message matching ports, caught"; 412 or Carp::croak "$port: rcv can only be called on message matching ports, caught";
363 413
364 $self->[2] = shift; 414 $self->[0] = shift;
365 } else { 415 } else {
366 my $cb = shift; 416 my $cb = shift;
367 $PORT{$portid} = sub { 417 $PORT{$portid} = sub {
368 local $SELF = $port; 418 local $SELF = $port;
369 eval { &$cb }; _self_die if $@; 419 eval { &$cb }; _self_die if $@;
370 }; 420 };
371 } 421 }
372 } elsif (defined $_[0]) { 422 } elsif (defined $_[0]) {
373 my $self = $PORT_DATA{$portid} ||= do { 423 my $self = $PORT_DATA{$portid} ||= do {
374 my $self = bless [$PORT{$port} || sub { }, { }, $port], "AnyEvent::MP::Port"; 424 my $self = bless [$PORT{$portid} || sub { }, { }, $port], "AnyEvent::MP::Port";
375 425
376 $PORT{$portid} = sub { 426 $PORT{$portid} = sub {
377 local $SELF = $port; 427 local $SELF = $port;
378 428
379 if (my $cb = $self->[1]{$_[0]}) { 429 if (my $cb = $self->[1]{$_[0]}) {
401 } 451 }
402 452
403 $port 453 $port
404} 454}
405 455
456=item peval $port, $coderef[, @args]
457
458Evaluates the given C<$codref> within the contetx of C<$port>, that is,
459when the code throews an exception the C<$port> will be killed.
460
461Any remaining args will be passed to the callback. Any return values will
462be returned to the caller.
463
464This is useful when you temporarily want to execute code in the context of
465a port.
466
467Example: create a port and run some initialisation code in it's context.
468
469 my $port = port { ... };
470
471 peval $port, sub {
472 init
473 or die "unable to init";
474 };
475
476=cut
477
478sub peval($$) {
479 local $SELF = shift;
480 my $cb = shift;
481
482 if (wantarray) {
483 my @res = eval { &$cb };
484 _self_die if $@;
485 @res
486 } else {
487 my $res = eval { &$cb };
488 _self_die if $@;
489 $res
490 }
491}
492
406=item $closure = psub { BLOCK } 493=item $closure = psub { BLOCK }
407 494
408Remembers C<$SELF> and creates a closure out of the BLOCK. When the 495Remembers C<$SELF> and creates a closure out of the BLOCK. When the
409closure is executed, sets up the environment in the same way as in C<rcv> 496closure is executed, sets up the environment in the same way as in C<rcv>
410callbacks, i.e. runtime errors will cause the port to get C<kil>ed. 497callbacks, i.e. runtime errors will cause the port to get C<kil>ed.
498
499The effect is basically as if it returned C<< sub { peval $SELF, sub {
500BLOCK }, @_ } >>.
411 501
412This is useful when you register callbacks from C<rcv> callbacks: 502This is useful when you register callbacks from C<rcv> callbacks:
413 503
414 rcv delayed_reply => sub { 504 rcv delayed_reply => sub {
415 my ($delay, @reply) = @_; 505 my ($delay, @reply) = @_;
451 541
452Monitor the given port and do something when the port is killed or 542Monitor the given port and do something when the port is killed or
453messages to it were lost, and optionally return a guard that can be used 543messages to it were lost, and optionally return a guard that can be used
454to stop monitoring again. 544to stop monitoring again.
455 545
546In the first form (callback), the callback is simply called with any
547number of C<@reason> elements (no @reason means that the port was deleted
548"normally"). Note also that I<< the callback B<must> never die >>, so use
549C<eval> if unsure.
550
551In the second form (another port given), the other port (C<$rcvport>)
552will be C<kil>'ed with C<@reason>, if a @reason was specified, i.e. on
553"normal" kils nothing happens, while under all other conditions, the other
554port is killed with the same reason.
555
556The third form (kill self) is the same as the second form, except that
557C<$rvport> defaults to C<$SELF>.
558
559In the last form (message), a message of the form C<@msg, @reason> will be
560C<snd>.
561
562Monitoring-actions are one-shot: once messages are lost (and a monitoring
563alert was raised), they are removed and will not trigger again.
564
565As a rule of thumb, monitoring requests should always monitor a port from
566a local port (or callback). The reason is that kill messages might get
567lost, just like any other message. Another less obvious reason is that
568even monitoring requests can get lost (for example, when the connection
569to the other node goes down permanently). When monitoring a port locally
570these problems do not exist.
571
456C<mon> effectively guarantees that, in the absence of hardware failures, 572C<mon> effectively guarantees that, in the absence of hardware failures,
457after starting the monitor, either all messages sent to the port will 573after starting the monitor, either all messages sent to the port will
458arrive, or the monitoring action will be invoked after possible message 574arrive, or the monitoring action will be invoked after possible message
459loss has been detected. No messages will be lost "in between" (after 575loss has been detected. No messages will be lost "in between" (after
460the first lost message no further messages will be received by the 576the first lost message no further messages will be received by the
461port). After the monitoring action was invoked, further messages might get 577port). After the monitoring action was invoked, further messages might get
462delivered again. 578delivered again.
463 579
464Note that monitoring-actions are one-shot: once messages are lost (and a 580Inter-host-connection timeouts and monitoring depend on the transport
465monitoring alert was raised), they are removed and will not trigger again. 581used. The only transport currently implemented is TCP, and AnyEvent::MP
582relies on TCP to detect node-downs (this can take 10-15 minutes on a
583non-idle connection, and usually around two hours for idle connections).
466 584
467In the first form (callback), the callback is simply called with any 585This means that monitoring is good for program errors and cleaning up
468number of C<@reason> elements (no @reason means that the port was deleted 586stuff eventually, but they are no replacement for a timeout when you need
469"normally"). Note also that I<< the callback B<must> never die >>, so use 587to ensure some maximum latency.
470C<eval> if unsure.
471
472In the second form (another port given), the other port (C<$rcvport>)
473will be C<kil>'ed with C<@reason>, iff a @reason was specified, i.e. on
474"normal" kils nothing happens, while under all other conditions, the other
475port is killed with the same reason.
476
477The third form (kill self) is the same as the second form, except that
478C<$rvport> defaults to C<$SELF>.
479
480In the last form (message), a message of the form C<@msg, @reason> will be
481C<snd>.
482
483As a rule of thumb, monitoring requests should always monitor a port from
484a local port (or callback). The reason is that kill messages might get
485lost, just like any other message. Another less obvious reason is that
486even monitoring requests can get lost (for exmaple, when the connection
487to the other node goes down permanently). When monitoring a port locally
488these problems do not exist.
489 588
490Example: call a given callback when C<$port> is killed. 589Example: call a given callback when C<$port> is killed.
491 590
492 mon $port, sub { warn "port died because of <@_>\n" }; 591 mon $port, sub { warn "port died because of <@_>\n" };
493 592
500 mon $port, $self => "restart"; 599 mon $port, $self => "restart";
501 600
502=cut 601=cut
503 602
504sub mon { 603sub mon {
505 my ($noderef, $port) = split /#/, shift, 2; 604 my ($nodeid, $port) = split /#/, shift, 2;
506 605
507 my $node = $NODE{$noderef} || add_node $noderef; 606 my $node = $NODE{$nodeid} || add_node $nodeid;
508 607
509 my $cb = @_ ? shift : $SELF || Carp::croak 'mon: called with one argument only, but $SELF not set,'; 608 my $cb = @_ ? shift : $SELF || Carp::croak 'mon: called with one argument only, but $SELF not set,';
510 609
511 unless (ref $cb) { 610 unless (ref $cb) {
512 if (@_) { 611 if (@_) {
521 } 620 }
522 621
523 $node->monitor ($port, $cb); 622 $node->monitor ($port, $cb);
524 623
525 defined wantarray 624 defined wantarray
526 and AnyEvent::Util::guard { $node->unmonitor ($port, $cb) } 625 and ($cb += 0, AnyEvent::Util::guard { $node->unmonitor ($port, $cb) })
527} 626}
528 627
529=item $guard = mon_guard $port, $ref, $ref... 628=item $guard = mon_guard $port, $ref, $ref...
530 629
531Monitors the given C<$port> and keeps the passed references. When the port 630Monitors the given C<$port> and keeps the passed references. When the port
554 653
555=item kil $port[, @reason] 654=item kil $port[, @reason]
556 655
557Kill the specified port with the given C<@reason>. 656Kill the specified port with the given C<@reason>.
558 657
559If no C<@reason> is specified, then the port is killed "normally" (ports 658If no C<@reason> is specified, then the port is killed "normally" -
560monitoring other ports will not necessarily die because a port dies 659monitor callback will be invoked, but the kil will not cause linked ports
561"normally"). 660(C<mon $mport, $lport> form) to get killed.
562 661
563Otherwise, linked ports get killed with the same reason (second form of 662If a C<@reason> is specified, then linked ports (C<mon $mport, $lport>
564C<mon>, see above). 663form) get killed with the same reason.
565 664
566Runtime errors while evaluating C<rcv> callbacks or inside C<psub> blocks 665Runtime errors while evaluating C<rcv> callbacks or inside C<psub> blocks
567will be reported as reason C<< die => $@ >>. 666will be reported as reason C<< die => $@ >>.
568 667
569Transport/communication errors are reported as C<< transport_error => 668Transport/communication errors are reported as C<< transport_error =>
588the package, then the package above the package and so on (e.g. 687the package, then the package above the package and so on (e.g.
589C<MyApp::Chat::Server>, C<MyApp::Chat>, C<MyApp>) until the function 688C<MyApp::Chat::Server>, C<MyApp::Chat>, C<MyApp>) until the function
590exists or it runs out of package names. 689exists or it runs out of package names.
591 690
592The init function is then called with the newly-created port as context 691The init function is then called with the newly-created port as context
593object (C<$SELF>) and the C<@initdata> values as arguments. 692object (C<$SELF>) and the C<@initdata> values as arguments. It I<must>
693call one of the C<rcv> functions to set callbacks on C<$SELF>, otherwise
694the port might not get created.
594 695
595A common idiom is to pass a local port, immediately monitor the spawned 696A common idiom is to pass a local port, immediately monitor the spawned
596port, and in the remote init function, immediately monitor the passed 697port, and in the remote init function, immediately monitor the passed
597local port. This two-way monitoring ensures that both ports get cleaned up 698local port. This two-way monitoring ensures that both ports get cleaned up
598when there is a problem. 699when there is a problem.
599 700
701C<spawn> guarantees that the C<$initfunc> has no visible effects on the
702caller before C<spawn> returns (by delaying invocation when spawn is
703called for the local node).
704
600Example: spawn a chat server port on C<$othernode>. 705Example: spawn a chat server port on C<$othernode>.
601 706
602 # this node, executed from within a port context: 707 # this node, executed from within a port context:
603 my $server = spawn $othernode, "MyApp::Chat::Server::connect", $SELF; 708 my $server = spawn $othernode, "MyApp::Chat::Server::connect", $SELF;
604 mon $server; 709 mon $server;
618 723
619sub _spawn { 724sub _spawn {
620 my $port = shift; 725 my $port = shift;
621 my $init = shift; 726 my $init = shift;
622 727
728 # rcv will create the actual port
623 local $SELF = "$NODE#$port"; 729 local $SELF = "$NODE#$port";
624 eval { 730 eval {
625 &{ load_func $init } 731 &{ load_func $init }
626 }; 732 };
627 _self_die if $@; 733 _self_die if $@;
628} 734}
629 735
630sub spawn(@) { 736sub spawn(@) {
631 my ($noderef, undef) = split /#/, shift, 2; 737 my ($nodeid, undef) = split /#/, shift, 2;
632 738
633 my $id = "$RUNIQ." . $ID++; 739 my $id = "$RUNIQ." . $ID++;
634 740
635 $_[0] =~ /::/ 741 $_[0] =~ /::/
636 or Carp::croak "spawn init function must be a fully-qualified name, caught"; 742 or Carp::croak "spawn init function must be a fully-qualified name, caught";
637 743
638 snd_to_func $noderef, "AnyEvent::MP::_spawn" => $id, @_; 744 snd_to_func $nodeid, "AnyEvent::MP::_spawn" => $id, @_;
639 745
640 "$noderef#$id" 746 "$nodeid#$id"
641} 747}
642 748
643=item after $timeout, @msg 749=item after $timeout, @msg
644 750
645=item after $timeout, $callback 751=item after $timeout, $callback
662 ? $action[0]() 768 ? $action[0]()
663 : snd @action; 769 : snd @action;
664 }; 770 };
665} 771}
666 772
773=item cal $port, @msg, $callback[, $timeout]
774
775A simple form of RPC - sends a message to the given C<$port> with the
776given contents (C<@msg>), but adds a reply port to the message.
777
778The reply port is created temporarily just for the purpose of receiving
779the reply, and will be C<kil>ed when no longer needed.
780
781A reply message sent to the port is passed to the C<$callback> as-is.
782
783If an optional time-out (in seconds) is given and it is not C<undef>,
784then the callback will be called without any arguments after the time-out
785elapsed and the port is C<kil>ed.
786
787If no time-out is given (or it is C<undef>), then the local port will
788monitor the remote port instead, so it eventually gets cleaned-up.
789
790Currently this function returns the temporary port, but this "feature"
791might go in future versions unless you can make a convincing case that
792this is indeed useful for something.
793
794=cut
795
796sub cal(@) {
797 my $timeout = ref $_[-1] ? undef : pop;
798 my $cb = pop;
799
800 my $port = port {
801 undef $timeout;
802 kil $SELF;
803 &$cb;
804 };
805
806 if (defined $timeout) {
807 $timeout = AE::timer $timeout, 0, sub {
808 undef $timeout;
809 kil $port;
810 $cb->();
811 };
812 } else {
813 mon $_[0], sub {
814 kil $port;
815 $cb->();
816 };
817 }
818
819 push @_, $port;
820 &snd;
821
822 $port
823}
824
667=back 825=back
668 826
669=head1 AnyEvent::MP vs. Distributed Erlang 827=head1 AnyEvent::MP vs. Distributed Erlang
670 828
671AnyEvent::MP got lots of its ideas from distributed Erlang (Erlang node 829AnyEvent::MP got lots of its ideas from distributed Erlang (Erlang node
672== aemp node, Erlang process == aemp port), so many of the documents and 830== aemp node, Erlang process == aemp port), so many of the documents and
673programming techniques employed by Erlang apply to AnyEvent::MP. Here is a 831programming techniques employed by Erlang apply to AnyEvent::MP. Here is a
674sample: 832sample:
675 833
676 http://www.Erlang.se/doc/programming_rules.shtml 834 http://www.erlang.se/doc/programming_rules.shtml
677 http://Erlang.org/doc/getting_started/part_frame.html # chapters 3 and 4 835 http://erlang.org/doc/getting_started/part_frame.html # chapters 3 and 4
678 http://Erlang.org/download/Erlang-book-part1.pdf # chapters 5 and 6 836 http://erlang.org/download/erlang-book-part1.pdf # chapters 5 and 6
679 http://Erlang.org/download/armstrong_thesis_2003.pdf # chapters 4 and 5 837 http://erlang.org/download/armstrong_thesis_2003.pdf # chapters 4 and 5
680 838
681Despite the similarities, there are also some important differences: 839Despite the similarities, there are also some important differences:
682 840
683=over 4 841=over 4
684 842
685=item * Node IDs are arbitrary strings in AEMP. 843=item * Node IDs are arbitrary strings in AEMP.
686 844
687Erlang relies on special naming and DNS to work everywhere in the same 845Erlang relies on special naming and DNS to work everywhere in the same
688way. AEMP relies on each node somehow knowing its own address(es) (e.g. by 846way. AEMP relies on each node somehow knowing its own address(es) (e.g. by
689configuraiton or DNS), but will otherwise discover other odes itself. 847configuration or DNS), and possibly the addresses of some seed nodes, but
848will otherwise discover other nodes (and their IDs) itself.
690 849
691=item * Erlang has a "remote ports are like local ports" philosophy, AEMP 850=item * Erlang has a "remote ports are like local ports" philosophy, AEMP
692uses "local ports are like remote ports". 851uses "local ports are like remote ports".
693 852
694The failure modes for local ports are quite different (runtime errors 853The failure modes for local ports are quite different (runtime errors
707 866
708Erlang uses processes that selectively receive messages, and therefore 867Erlang uses processes that selectively receive messages, and therefore
709needs a queue. AEMP is event based, queuing messages would serve no 868needs a queue. AEMP is event based, queuing messages would serve no
710useful purpose. For the same reason the pattern-matching abilities of 869useful purpose. For the same reason the pattern-matching abilities of
711AnyEvent::MP are more limited, as there is little need to be able to 870AnyEvent::MP are more limited, as there is little need to be able to
712filter messages without dequeing them. 871filter messages without dequeuing them.
713 872
714(But see L<Coro::MP> for a more Erlang-like process model on top of AEMP). 873(But see L<Coro::MP> for a more Erlang-like process model on top of AEMP).
715 874
716=item * Erlang sends are synchronous, AEMP sends are asynchronous. 875=item * Erlang sends are synchronous, AEMP sends are asynchronous.
717 876
719so does not need a queue that can overflow). AEMP sends are immediate, 878so does not need a queue that can overflow). AEMP sends are immediate,
720connection establishment is handled in the background. 879connection establishment is handled in the background.
721 880
722=item * Erlang suffers from silent message loss, AEMP does not. 881=item * Erlang suffers from silent message loss, AEMP does not.
723 882
724Erlang makes few guarantees on messages delivery - messages can get lost 883Erlang implements few guarantees on messages delivery - messages can get
725without any of the processes realising it (i.e. you send messages a, b, 884lost without any of the processes realising it (i.e. you send messages a,
726and c, and the other side only receives messages a and c). 885b, and c, and the other side only receives messages a and c).
727 886
728AEMP guarantees correct ordering, and the guarantee that after one message 887AEMP guarantees (modulo hardware errors) correct ordering, and the
729is lost, all following ones sent to the same port are lost as well, until 888guarantee that after one message is lost, all following ones sent to the
730monitoring raises an error, so there are no silent "holes" in the message 889same port are lost as well, until monitoring raises an error, so there are
731sequence. 890no silent "holes" in the message sequence.
732 891
733=item * Erlang can send messages to the wrong port, AEMP does not. 892=item * Erlang can send messages to the wrong port, AEMP does not.
734 893
735In Erlang it is quite likely that a node that restarts reuses a process ID 894In Erlang it is quite likely that a node that restarts reuses a process ID
736known to other nodes for a completely different process, causing messages 895known to other nodes for a completely different process, causing messages
793overhead, as well as having to keep a proxy object everywhere. 952overhead, as well as having to keep a proxy object everywhere.
794 953
795Strings can easily be printed, easily serialised etc. and need no special 954Strings can easily be printed, easily serialised etc. and need no special
796procedures to be "valid". 955procedures to be "valid".
797 956
798And as a result, a miniport consists of a single closure stored in a 957And as a result, a port with just a default receiver consists of a single
799global hash - it can't become much cheaper. 958code reference stored in a global hash - it can't become much cheaper.
800 959
801=item Why favour JSON, why not a real serialising format such as Storable? 960=item Why favour JSON, why not a real serialising format such as Storable?
802 961
803In fact, any AnyEvent::MP node will happily accept Storable as framing 962In fact, any AnyEvent::MP node will happily accept Storable as framing
804format, but currently there is no way to make a node use Storable by 963format, but currently there is no way to make a node use Storable by
820 979
821L<AnyEvent::MP::Intro> - a gentle introduction. 980L<AnyEvent::MP::Intro> - a gentle introduction.
822 981
823L<AnyEvent::MP::Kernel> - more, lower-level, stuff. 982L<AnyEvent::MP::Kernel> - more, lower-level, stuff.
824 983
825L<AnyEvent::MP::Global> - network maintainance and port groups, to find 984L<AnyEvent::MP::Global> - network maintenance and port groups, to find
826your applications. 985your applications.
986
987L<AnyEvent::MP::DataConn> - establish data connections between nodes.
988
989L<AnyEvent::MP::LogCatcher> - simple service to display log messages from
990all nodes.
827 991
828L<AnyEvent>. 992L<AnyEvent>.
829 993
830=head1 AUTHOR 994=head1 AUTHOR
831 995

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines