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.76 by root, Mon Aug 31 18:45:05 2009 UTC vs.
Revision 1.122 by root, Wed Feb 29 18:44:59 2012 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
30 rcv $port, pong => sub { warn "pong received\n" }; 30 rcv $port, pong => sub { warn "pong received\n" };
31 31
32 # create a port on another node 32 # create a port on another node
33 my $port = spawn $node, $initfunc, @initdata; 33 my $port = spawn $node, $initfunc, @initdata;
34 34
35 # destroy a port again
36 kil $port; # "normal" kill
37 kil $port, my_error => "everything is broken"; # error kill
38
35 # monitoring 39 # monitoring
36 mon $port, $cb->(@msg) # callback is invoked on death 40 mon $localport, $cb->(@msg) # callback is invoked on death
37 mon $port, $otherport # kill otherport on abnormal death 41 mon $localport, $otherport # kill otherport on abnormal death
38 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 };
39 51
40=head1 CURRENT STATUS 52=head1 CURRENT STATUS
41 53
42 bin/aemp - stable. 54 bin/aemp - stable.
43 AnyEvent::MP - stable API, should work. 55 AnyEvent::MP - stable API, should work.
44 AnyEvent::MP::Intro - epxlains most concepts. 56 AnyEvent::MP::Intro - explains most concepts.
45 AnyEvent::MP::Kernel - mostly stable. 57 AnyEvent::MP::Kernel - mostly stable API.
46 AnyEvent::MP::Global - stable API, protocol not yet final. 58 AnyEvent::MP::Global - stable API.
47
48 stay tuned.
49 59
50=head1 DESCRIPTION 60=head1 DESCRIPTION
51 61
52This module (-family) implements a simple message passing framework. 62This module (-family) implements a simple message passing framework.
53 63
61 71
62=over 4 72=over 4
63 73
64=item port 74=item port
65 75
66A 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).
67 78
68Ports 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
69some messages. Messages send to ports will not be queued, regardless of 80some messages. Messages send to ports will not be queued, regardless of
70anything was listening for them or not. 81anything was listening for them or not.
71 82
83Ports are represented by (printable) strings called "port IDs".
84
72=item port ID - C<nodeid#portname> 85=item port ID - C<nodeid#portname>
73 86
74A port ID is the concatenation of a node ID, a hash-mark (C<#>) as 87A port ID is the concatenation of a node ID, a hash-mark (C<#>) as
75separator, and a port name (a printable string of unspecified format). 88separator, and a port name (a printable string of unspecified format).
76 89
80which enables nodes to manage each other remotely, and to create new 93which enables nodes to manage each other remotely, and to create new
81ports. 94ports.
82 95
83Nodes are either public (have one or more listening ports) or private 96Nodes are either public (have one or more listening ports) or private
84(no listening ports). Private nodes cannot talk to other private nodes 97(no listening ports). Private nodes cannot talk to other private nodes
85currently. 98currently, but all nodes can talk to public nodes.
86 99
100Nodes is represented by (printable) strings called "node IDs".
101
87=item node ID - C<[a-za-Z0-9_\-.:]+> 102=item node ID - C<[A-Za-z0-9_\-.:]*>
88 103
89A node ID is a string that uniquely identifies the node within a 104A node ID is a string that uniquely identifies the node within a
90network. Depending on the configuration used, node IDs can look like a 105network. Depending on the configuration used, node IDs can look like a
91hostname, a hostname and a port, or a random string. AnyEvent::MP itself 106hostname, a hostname and a port, or a random string. AnyEvent::MP itself
92doesn't interpret node IDs in any way. 107doesn't interpret node IDs in any way except to uniquely identify a node.
93 108
94=item binds - C<ip:port> 109=item binds - C<ip:port>
95 110
96Nodes can only talk to each other by creating some kind of connection to 111Nodes can only talk to each other by creating some kind of connection to
97each other. To do this, nodes should listen on one or more local transport 112each other. To do this, nodes should listen on one or more local transport
113endpoints - binds.
114
98endpoints - binds. Currently, only standard C<ip:port> specifications can 115Currently, only standard C<ip:port> specifications can be used, which
99be used, which specify TCP ports to listen on. 116specify TCP ports to listen on. So a bind is basically just a tcp socket
117in listening mode thta accepts conenctions form other nodes.
100 118
119=item seed nodes
120
121When a node starts, it knows nothing about the network it is in - it
122needs to connect to at least one other node that is already in the
123network. These other nodes are called "seed nodes".
124
125Seed nodes themselves are not special - they are seed nodes only because
126some other node I<uses> them as such, but any node can be used as seed
127node for other nodes, and eahc node cna use a different set of seed nodes.
128
129In addition to discovering the network, seed nodes are also used to
130maintain the network - all nodes using the same seed node form are part of
131the same network. If a network is split into multiple subnets because e.g.
132the network link between the parts goes down, then using the same seed
133nodes for all nodes ensures that eventually the subnets get merged again.
134
135Seed nodes are expected to be long-running, and at least one seed node
136should always be available. They should also be relatively responsive - a
137seed node that blocks for long periods will slow down everybody else.
138
139For small networks, it's best if every node uses the same set of seed
140nodes. For large networks, it can be useful to specify "regional" seed
141nodes for most nodes in an area, and use all seed nodes as seed nodes for
142each other. What's important is that all seed nodes connections form a
143complete graph, so that the network cannot split into separate subnets
144forever.
145
146Seed nodes are represented by seed IDs.
147
101=item seeds - C<host:port> 148=item seed IDs - C<host:port>
102 149
103When a node starts, it knows nothing about the network. To teach the node 150Seed IDs are transport endpoint(s) (usually a hostname/IP address and a
104about the network it first has to contact some other node within the 151TCP port) of nodes that should be used as seed nodes.
105network. This node is called a seed.
106 152
107Seeds are transport endpoint(s) of as many nodes as one wants. Those nodes 153=item global nodes
108are expected to be long-running, and at least one of those should always
109be available. When nodes run out of connections (e.g. due to a network
110error), they try to re-establish connections to some seednodes again to
111join the network.
112 154
113Apart from being sued for seeding, seednodes are not special in any way - 155An AEMP network needs a discovery service - nodes need to know how to
114every public node can be a seednode. 156connect to other nodes they only know by name. In addition, AEMP offers a
157distributed "group database", which maps group names to a list of strings
158- for example, to register worker ports.
159
160A network needs at least one global node to work, and allows every node to
161be a global node.
162
163Any node that loads the L<AnyEvent::MP::Global> module becomes a global
164node and tries to keep connections to all other nodes. So while it can
165make sense to make every node "global" in small networks, it usually makes
166sense to only make seed nodes into global nodes in large networks (nodes
167keep connections to seed nodes and global nodes, so makign them the same
168reduces overhead).
115 169
116=back 170=back
117 171
118=head1 VARIABLES/FUNCTIONS 172=head1 VARIABLES/FUNCTIONS
119 173
121 175
122=cut 176=cut
123 177
124package AnyEvent::MP; 178package AnyEvent::MP;
125 179
180use AnyEvent::MP::Config ();
126use AnyEvent::MP::Kernel; 181use AnyEvent::MP::Kernel;
182use AnyEvent::MP::Kernel qw(%NODE %PORT %PORT_DATA $UNIQ $RUNIQ $ID);
127 183
128use common::sense; 184use common::sense;
129 185
130use Carp (); 186use Carp ();
131 187
132use AE (); 188use AE ();
133 189
134use base "Exporter"; 190use base "Exporter";
135 191
136our $VERSION = $AnyEvent::MP::Kernel::VERSION; 192our $VERSION = $AnyEvent::MP::Config::VERSION;
137 193
138our @EXPORT = qw( 194our @EXPORT = qw(
139 NODE $NODE *SELF node_of after 195 NODE $NODE *SELF node_of after
140 configure 196 configure
141 snd rcv mon mon_guard kil reg psub spawn 197 snd rcv mon mon_guard kil psub peval spawn cal
142 port 198 port
143); 199);
144 200
145our $SELF; 201our $SELF;
146 202
158 214
159=item $nodeid = node_of $port 215=item $nodeid = node_of $port
160 216
161Extracts and returns the node ID from a port ID or a node ID. 217Extracts and returns the node ID from a port ID or a node ID.
162 218
219=item configure $profile, key => value...
220
163=item configure key => value... 221=item configure key => value...
164 222
165Before a node can talk to other nodes on the network (i.e. enter 223Before a node can talk to other nodes on the network (i.e. enter
166"distributed mode") it has to configure itself - the minimum a node needs 224"distributed mode") it has to configure itself - the minimum a node needs
167to know is its own name, and optionally it should know the addresses of 225to know is its own name, and optionally it should know the addresses of
168some other nodes in the network to discover other nodes. 226some other nodes in the network to discover other nodes.
169 227
170This function configures a node - it must be called exactly once (or 228This function configures a node - it must be called exactly once (or
171never) before calling other AnyEvent::MP functions. 229never) before calling other AnyEvent::MP functions.
172 230
231The key/value pairs are basically the same ones as documented for the
232F<aemp> command line utility (sans the set/del prefix), with two additions:
233
234=over 4
235
236=item norc => $boolean (default false)
237
238If true, then the rc file (e.g. F<~/.perl-anyevent-mp>) will I<not>
239be consulted - all configuraiton options must be specified in the
240C<configure> call.
241
242=item force => $boolean (default false)
243
244IF true, then the values specified in the C<configure> will take
245precedence over any values configured via the rc file. The default is for
246the rc file to override any options specified in the program.
247
248=back
249
173=over 4 250=over 4
174 251
175=item step 1, gathering configuration from profiles 252=item step 1, gathering configuration from profiles
176 253
177The function first looks up a profile in the aemp configuration (see the 254The function first looks up a profile in the aemp configuration (see the
178L<aemp> commandline utility). The profile name can be specified via the 255L<aemp> commandline utility). The profile name can be specified via the
179named C<profile> parameter. If it is missing, then the nodename (F<uname 256named C<profile> parameter or can simply be the first parameter). If it is
180-n>) will be used as profile name. 257missing, then the nodename (F<uname -n>) will be used as profile name.
181 258
182The profile data is then gathered as follows: 259The profile data is then gathered as follows:
183 260
184First, all remaining key => value pairs (all of which are conviniently 261First, all remaining key => value pairs (all of which are conveniently
185undocumented at the moment) will be interpreted as configuration 262undocumented at the moment) will be interpreted as configuration
186data. Then they will be overwritten by any values specified in the global 263data. Then they will be overwritten by any values specified in the global
187default configuration (see the F<aemp> utility), then the chain of 264default configuration (see the F<aemp> utility), then the chain of
188profiles chosen by the profile name (and any C<parent> attributes). 265profiles chosen by the profile name (and any C<parent> attributes).
189 266
190That means that the values specified in the profile have highest priority 267That means that the values specified in the profile have highest priority
191and the values specified directly via C<configure> have lowest priority, 268and the values specified directly via C<configure> have lowest priority,
192and can only be used to specify defaults. 269and can only be used to specify defaults.
193 270
194If the profile specifies a node ID, then this will become the node ID of 271If the profile specifies a node ID, then this will become the node ID of
195this process. If not, then the profile name will be used as node ID. The 272this process. If not, then the profile name will be used as node ID, with
196special node ID of C<anon/> will be replaced by a random node ID. 273a slash (C</>) attached.
274
275If the node ID (or profile name) ends with a slash (C</>), then a random
276string is appended to make it unique.
197 277
198=item step 2, bind listener sockets 278=item step 2, bind listener sockets
199 279
200The next step is to look up the binds in the profile, followed by binding 280The next step is to look up the binds in the profile, followed by binding
201aemp protocol listeners on all binds specified (it is possible and valid 281aemp protocol listeners on all binds specified (it is possible and valid
207used, meaning the node will bind on a dynamically-assigned port on every 287used, meaning the node will bind on a dynamically-assigned port on every
208local IP address it finds. 288local IP address it finds.
209 289
210=item step 3, connect to seed nodes 290=item step 3, connect to seed nodes
211 291
212As the last step, the seeds list from the profile is passed to the 292As the last step, the seed ID list from the profile is passed to the
213L<AnyEvent::MP::Global> module, which will then use it to keep 293L<AnyEvent::MP::Global> module, which will then use it to keep
214connectivity with at least one node at any point in time. 294connectivity with at least one node at any point in time.
215 295
216=back 296=back
217 297
218Example: become a distributed node using the locla node name as profile. 298Example: become a distributed node using the local node name as profile.
219This should be the most common form of invocation for "daemon"-type nodes. 299This should be the most common form of invocation for "daemon"-type nodes.
220 300
221 configure 301 configure
222 302
223Example: become an anonymous node. This form is often used for commandline 303Example: become an anonymous node. This form is often used for commandline
224clients. 304clients.
225 305
226 configure nodeid => "anon/"; 306 configure nodeid => "anon/";
227 307
228Example: configure a node using a profile called seed, which si suitable 308Example: configure a node using a profile called seed, which is suitable
229for a seed node as it binds on all local addresses on a fixed port (4040, 309for a seed node as it binds on all local addresses on a fixed port (4040,
230customary for aemp). 310customary for aemp).
231 311
232 # use the aemp commandline utility 312 # use the aemp commandline utility
233 # aemp profile seed nodeid anon/ binds '*:4040' 313 # aemp profile seed binds '*:4040'
234 314
235 # then use it 315 # then use it
236 configure profile => "seed"; 316 configure profile => "seed";
237 317
238 # or simply use aemp from the shell again: 318 # or simply use aemp from the shell again:
308sub _kilme { 388sub _kilme {
309 die "received message on port without callback"; 389 die "received message on port without callback";
310} 390}
311 391
312sub port(;&) { 392sub port(;&) {
313 my $id = "$UNIQ." . $ID++; 393 my $id = "$UNIQ." . ++$ID;
314 my $port = "$NODE#$id"; 394 my $port = "$NODE#$id";
315 395
316 rcv $port, shift || \&_kilme; 396 rcv $port, shift || \&_kilme;
317 397
318 $port 398 $port
357 msg1 => sub { ... }, 437 msg1 => sub { ... },
358 ... 438 ...
359 ; 439 ;
360 440
361Example: temporarily register a rcv callback for a tag matching some port 441Example: temporarily register a rcv callback for a tag matching some port
362(e.g. for a rpc reply) and unregister it after a message was received. 442(e.g. for an rpc reply) and unregister it after a message was received.
363 443
364 rcv $port, $otherport => sub { 444 rcv $port, $otherport => sub {
365 my @reply = @_; 445 my @reply = @_;
366 446
367 rcv $SELF, $otherport; 447 rcv $SELF, $otherport;
380 if (ref $_[0]) { 460 if (ref $_[0]) {
381 if (my $self = $PORT_DATA{$portid}) { 461 if (my $self = $PORT_DATA{$portid}) {
382 "AnyEvent::MP::Port" eq ref $self 462 "AnyEvent::MP::Port" eq ref $self
383 or Carp::croak "$port: rcv can only be called on message matching ports, caught"; 463 or Carp::croak "$port: rcv can only be called on message matching ports, caught";
384 464
385 $self->[2] = shift; 465 $self->[0] = shift;
386 } else { 466 } else {
387 my $cb = shift; 467 my $cb = shift;
388 $PORT{$portid} = sub { 468 $PORT{$portid} = sub {
389 local $SELF = $port; 469 local $SELF = $port;
390 eval { &$cb }; _self_die if $@; 470 eval { &$cb }; _self_die if $@;
391 }; 471 };
392 } 472 }
393 } elsif (defined $_[0]) { 473 } elsif (defined $_[0]) {
394 my $self = $PORT_DATA{$portid} ||= do { 474 my $self = $PORT_DATA{$portid} ||= do {
395 my $self = bless [$PORT{$port} || sub { }, { }, $port], "AnyEvent::MP::Port"; 475 my $self = bless [$PORT{$portid} || sub { }, { }, $port], "AnyEvent::MP::Port";
396 476
397 $PORT{$portid} = sub { 477 $PORT{$portid} = sub {
398 local $SELF = $port; 478 local $SELF = $port;
399 479
400 if (my $cb = $self->[1]{$_[0]}) { 480 if (my $cb = $self->[1]{$_[0]}) {
422 } 502 }
423 503
424 $port 504 $port
425} 505}
426 506
507=item peval $port, $coderef[, @args]
508
509Evaluates the given C<$codref> within the contetx of C<$port>, that is,
510when the code throews an exception the C<$port> will be killed.
511
512Any remaining args will be passed to the callback. Any return values will
513be returned to the caller.
514
515This is useful when you temporarily want to execute code in the context of
516a port.
517
518Example: create a port and run some initialisation code in it's context.
519
520 my $port = port { ... };
521
522 peval $port, sub {
523 init
524 or die "unable to init";
525 };
526
527=cut
528
529sub peval($$) {
530 local $SELF = shift;
531 my $cb = shift;
532
533 if (wantarray) {
534 my @res = eval { &$cb };
535 _self_die if $@;
536 @res
537 } else {
538 my $res = eval { &$cb };
539 _self_die if $@;
540 $res
541 }
542}
543
427=item $closure = psub { BLOCK } 544=item $closure = psub { BLOCK }
428 545
429Remembers C<$SELF> and creates a closure out of the BLOCK. When the 546Remembers C<$SELF> and creates a closure out of the BLOCK. When the
430closure is executed, sets up the environment in the same way as in C<rcv> 547closure is executed, sets up the environment in the same way as in C<rcv>
431callbacks, i.e. runtime errors will cause the port to get C<kil>ed. 548callbacks, i.e. runtime errors will cause the port to get C<kil>ed.
549
550The effect is basically as if it returned C<< sub { peval $SELF, sub {
551BLOCK }, @_ } >>.
432 552
433This is useful when you register callbacks from C<rcv> callbacks: 553This is useful when you register callbacks from C<rcv> callbacks:
434 554
435 rcv delayed_reply => sub { 555 rcv delayed_reply => sub {
436 my ($delay, @reply) = @_; 556 my ($delay, @reply) = @_;
472 592
473Monitor the given port and do something when the port is killed or 593Monitor the given port and do something when the port is killed or
474messages to it were lost, and optionally return a guard that can be used 594messages to it were lost, and optionally return a guard that can be used
475to stop monitoring again. 595to stop monitoring again.
476 596
597In the first form (callback), the callback is simply called with any
598number of C<@reason> elements (no @reason means that the port was deleted
599"normally"). Note also that I<< the callback B<must> never die >>, so use
600C<eval> if unsure.
601
602In the second form (another port given), the other port (C<$rcvport>)
603will be C<kil>'ed with C<@reason>, if a @reason was specified, i.e. on
604"normal" kils nothing happens, while under all other conditions, the other
605port is killed with the same reason.
606
607The third form (kill self) is the same as the second form, except that
608C<$rvport> defaults to C<$SELF>.
609
610In the last form (message), a message of the form C<@msg, @reason> will be
611C<snd>.
612
613Monitoring-actions are one-shot: once messages are lost (and a monitoring
614alert was raised), they are removed and will not trigger again.
615
616As a rule of thumb, monitoring requests should always monitor a port from
617a local port (or callback). The reason is that kill messages might get
618lost, just like any other message. Another less obvious reason is that
619even monitoring requests can get lost (for example, when the connection
620to the other node goes down permanently). When monitoring a port locally
621these problems do not exist.
622
477C<mon> effectively guarantees that, in the absence of hardware failures, 623C<mon> effectively guarantees that, in the absence of hardware failures,
478after starting the monitor, either all messages sent to the port will 624after starting the monitor, either all messages sent to the port will
479arrive, or the monitoring action will be invoked after possible message 625arrive, or the monitoring action will be invoked after possible message
480loss has been detected. No messages will be lost "in between" (after 626loss has been detected. No messages will be lost "in between" (after
481the first lost message no further messages will be received by the 627the first lost message no further messages will be received by the
482port). After the monitoring action was invoked, further messages might get 628port). After the monitoring action was invoked, further messages might get
483delivered again. 629delivered again.
484 630
485Note that monitoring-actions are one-shot: once messages are lost (and a 631Inter-host-connection timeouts and monitoring depend on the transport
486monitoring alert was raised), they are removed and will not trigger again. 632used. The only transport currently implemented is TCP, and AnyEvent::MP
633relies on TCP to detect node-downs (this can take 10-15 minutes on a
634non-idle connection, and usually around two hours for idle connections).
487 635
488In the first form (callback), the callback is simply called with any 636This means that monitoring is good for program errors and cleaning up
489number of C<@reason> elements (no @reason means that the port was deleted 637stuff eventually, but they are no replacement for a timeout when you need
490"normally"). Note also that I<< the callback B<must> never die >>, so use 638to ensure some maximum latency.
491C<eval> if unsure.
492
493In the second form (another port given), the other port (C<$rcvport>)
494will be C<kil>'ed with C<@reason>, iff a @reason was specified, i.e. on
495"normal" kils nothing happens, while under all other conditions, the other
496port is killed with the same reason.
497
498The third form (kill self) is the same as the second form, except that
499C<$rvport> defaults to C<$SELF>.
500
501In the last form (message), a message of the form C<@msg, @reason> will be
502C<snd>.
503
504As a rule of thumb, monitoring requests should always monitor a port from
505a local port (or callback). The reason is that kill messages might get
506lost, just like any other message. Another less obvious reason is that
507even monitoring requests can get lost (for exmaple, when the connection
508to the other node goes down permanently). When monitoring a port locally
509these problems do not exist.
510 639
511Example: call a given callback when C<$port> is killed. 640Example: call a given callback when C<$port> is killed.
512 641
513 mon $port, sub { warn "port died because of <@_>\n" }; 642 mon $port, sub { warn "port died because of <@_>\n" };
514 643
542 } 671 }
543 672
544 $node->monitor ($port, $cb); 673 $node->monitor ($port, $cb);
545 674
546 defined wantarray 675 defined wantarray
547 and AnyEvent::Util::guard { $node->unmonitor ($port, $cb) } 676 and ($cb += 0, AnyEvent::Util::guard { $node->unmonitor ($port, $cb) })
548} 677}
549 678
550=item $guard = mon_guard $port, $ref, $ref... 679=item $guard = mon_guard $port, $ref, $ref...
551 680
552Monitors the given C<$port> and keeps the passed references. When the port 681Monitors the given C<$port> and keeps the passed references. When the port
575 704
576=item kil $port[, @reason] 705=item kil $port[, @reason]
577 706
578Kill the specified port with the given C<@reason>. 707Kill the specified port with the given C<@reason>.
579 708
580If no C<@reason> is specified, then the port is killed "normally" (ports 709If no C<@reason> is specified, then the port is killed "normally" -
581monitoring other ports will not necessarily die because a port dies 710monitor callback will be invoked, but the kil will not cause linked ports
582"normally"). 711(C<mon $mport, $lport> form) to get killed.
583 712
584Otherwise, linked ports get killed with the same reason (second form of 713If a C<@reason> is specified, then linked ports (C<mon $mport, $lport>
585C<mon>, see above). 714form) get killed with the same reason.
586 715
587Runtime errors while evaluating C<rcv> callbacks or inside C<psub> blocks 716Runtime errors while evaluating C<rcv> callbacks or inside C<psub> blocks
588will be reported as reason C<< die => $@ >>. 717will be reported as reason C<< die => $@ >>.
589 718
590Transport/communication errors are reported as C<< transport_error => 719Transport/communication errors are reported as C<< transport_error =>
609the package, then the package above the package and so on (e.g. 738the package, then the package above the package and so on (e.g.
610C<MyApp::Chat::Server>, C<MyApp::Chat>, C<MyApp>) until the function 739C<MyApp::Chat::Server>, C<MyApp::Chat>, C<MyApp>) until the function
611exists or it runs out of package names. 740exists or it runs out of package names.
612 741
613The init function is then called with the newly-created port as context 742The init function is then called with the newly-created port as context
614object (C<$SELF>) and the C<@initdata> values as arguments. 743object (C<$SELF>) and the C<@initdata> values as arguments. It I<must>
744call one of the C<rcv> functions to set callbacks on C<$SELF>, otherwise
745the port might not get created.
615 746
616A common idiom is to pass a local port, immediately monitor the spawned 747A common idiom is to pass a local port, immediately monitor the spawned
617port, and in the remote init function, immediately monitor the passed 748port, and in the remote init function, immediately monitor the passed
618local port. This two-way monitoring ensures that both ports get cleaned up 749local port. This two-way monitoring ensures that both ports get cleaned up
619when there is a problem. 750when there is a problem.
620 751
752C<spawn> guarantees that the C<$initfunc> has no visible effects on the
753caller before C<spawn> returns (by delaying invocation when spawn is
754called for the local node).
755
621Example: spawn a chat server port on C<$othernode>. 756Example: spawn a chat server port on C<$othernode>.
622 757
623 # this node, executed from within a port context: 758 # this node, executed from within a port context:
624 my $server = spawn $othernode, "MyApp::Chat::Server::connect", $SELF; 759 my $server = spawn $othernode, "MyApp::Chat::Server::connect", $SELF;
625 mon $server; 760 mon $server;
639 774
640sub _spawn { 775sub _spawn {
641 my $port = shift; 776 my $port = shift;
642 my $init = shift; 777 my $init = shift;
643 778
779 # rcv will create the actual port
644 local $SELF = "$NODE#$port"; 780 local $SELF = "$NODE#$port";
645 eval { 781 eval {
646 &{ load_func $init } 782 &{ load_func $init }
647 }; 783 };
648 _self_die if $@; 784 _self_die if $@;
649} 785}
650 786
651sub spawn(@) { 787sub spawn(@) {
652 my ($nodeid, undef) = split /#/, shift, 2; 788 my ($nodeid, undef) = split /#/, shift, 2;
653 789
654 my $id = "$RUNIQ." . $ID++; 790 my $id = "$RUNIQ." . ++$ID;
655 791
656 $_[0] =~ /::/ 792 $_[0] =~ /::/
657 or Carp::croak "spawn init function must be a fully-qualified name, caught"; 793 or Carp::croak "spawn init function must be a fully-qualified name, caught";
658 794
659 snd_to_func $nodeid, "AnyEvent::MP::_spawn" => $id, @_; 795 snd_to_func $nodeid, "AnyEvent::MP::_spawn" => $id, @_;
660 796
661 "$nodeid#$id" 797 "$nodeid#$id"
662} 798}
799
663 800
664=item after $timeout, @msg 801=item after $timeout, @msg
665 802
666=item after $timeout, $callback 803=item after $timeout, $callback
667 804
683 ? $action[0]() 820 ? $action[0]()
684 : snd @action; 821 : snd @action;
685 }; 822 };
686} 823}
687 824
825=item cal $port, @msg, $callback[, $timeout]
826
827A simple form of RPC - sends a message to the given C<$port> with the
828given contents (C<@msg>), but adds a reply port to the message.
829
830The reply port is created temporarily just for the purpose of receiving
831the reply, and will be C<kil>ed when no longer needed.
832
833A reply message sent to the port is passed to the C<$callback> as-is.
834
835If an optional time-out (in seconds) is given and it is not C<undef>,
836then the callback will be called without any arguments after the time-out
837elapsed and the port is C<kil>ed.
838
839If no time-out is given (or it is C<undef>), then the local port will
840monitor the remote port instead, so it eventually gets cleaned-up.
841
842Currently this function returns the temporary port, but this "feature"
843might go in future versions unless you can make a convincing case that
844this is indeed useful for something.
845
846=cut
847
848sub cal(@) {
849 my $timeout = ref $_[-1] ? undef : pop;
850 my $cb = pop;
851
852 my $port = port {
853 undef $timeout;
854 kil $SELF;
855 &$cb;
856 };
857
858 if (defined $timeout) {
859 $timeout = AE::timer $timeout, 0, sub {
860 undef $timeout;
861 kil $port;
862 $cb->();
863 };
864 } else {
865 mon $_[0], sub {
866 kil $port;
867 $cb->();
868 };
869 }
870
871 push @_, $port;
872 &snd;
873
874 $port
875}
876
688=back 877=back
689 878
690=head1 AnyEvent::MP vs. Distributed Erlang 879=head1 AnyEvent::MP vs. Distributed Erlang
691 880
692AnyEvent::MP got lots of its ideas from distributed Erlang (Erlang node 881AnyEvent::MP got lots of its ideas from distributed Erlang (Erlang node
693== aemp node, Erlang process == aemp port), so many of the documents and 882== aemp node, Erlang process == aemp port), so many of the documents and
694programming techniques employed by Erlang apply to AnyEvent::MP. Here is a 883programming techniques employed by Erlang apply to AnyEvent::MP. Here is a
695sample: 884sample:
696 885
697 http://www.Erlang.se/doc/programming_rules.shtml 886 http://www.erlang.se/doc/programming_rules.shtml
698 http://Erlang.org/doc/getting_started/part_frame.html # chapters 3 and 4 887 http://erlang.org/doc/getting_started/part_frame.html # chapters 3 and 4
699 http://Erlang.org/download/Erlang-book-part1.pdf # chapters 5 and 6 888 http://erlang.org/download/erlang-book-part1.pdf # chapters 5 and 6
700 http://Erlang.org/download/armstrong_thesis_2003.pdf # chapters 4 and 5 889 http://erlang.org/download/armstrong_thesis_2003.pdf # chapters 4 and 5
701 890
702Despite the similarities, there are also some important differences: 891Despite the similarities, there are also some important differences:
703 892
704=over 4 893=over 4
705 894
706=item * Node IDs are arbitrary strings in AEMP. 895=item * Node IDs are arbitrary strings in AEMP.
707 896
708Erlang relies on special naming and DNS to work everywhere in the same 897Erlang relies on special naming and DNS to work everywhere in the same
709way. AEMP relies on each node somehow knowing its own address(es) (e.g. by 898way. AEMP relies on each node somehow knowing its own address(es) (e.g. by
710configuraiton or DNS), but will otherwise discover other odes itself. 899configuration or DNS), and possibly the addresses of some seed nodes, but
900will otherwise discover other nodes (and their IDs) itself.
711 901
712=item * Erlang has a "remote ports are like local ports" philosophy, AEMP 902=item * Erlang has a "remote ports are like local ports" philosophy, AEMP
713uses "local ports are like remote ports". 903uses "local ports are like remote ports".
714 904
715The failure modes for local ports are quite different (runtime errors 905The failure modes for local ports are quite different (runtime errors
724ports being the special case/exception, where transport errors cannot 914ports being the special case/exception, where transport errors cannot
725occur. 915occur.
726 916
727=item * Erlang uses processes and a mailbox, AEMP does not queue. 917=item * Erlang uses processes and a mailbox, AEMP does not queue.
728 918
729Erlang uses processes that selectively receive messages, and therefore 919Erlang uses processes that selectively receive messages out of order, and
730needs a queue. AEMP is event based, queuing messages would serve no 920therefore needs a queue. AEMP is event based, queuing messages would serve
731useful purpose. For the same reason the pattern-matching abilities of 921no useful purpose. For the same reason the pattern-matching abilities
732AnyEvent::MP are more limited, as there is little need to be able to 922of AnyEvent::MP are more limited, as there is little need to be able to
733filter messages without dequeing them. 923filter messages without dequeuing them.
734 924
735(But see L<Coro::MP> for a more Erlang-like process model on top of AEMP). 925This is not a philosophical difference, but simply stems from AnyEvent::MP
926being event-based, while Erlang is process-based.
927
928You cna have a look at L<Coro::MP> for a more Erlang-like process model on
929top of AEMP and Coro threads.
736 930
737=item * Erlang sends are synchronous, AEMP sends are asynchronous. 931=item * Erlang sends are synchronous, AEMP sends are asynchronous.
738 932
739Sending messages in Erlang is synchronous and blocks the process (and 933Sending messages in Erlang is synchronous and blocks the process until
934a conenction has been established and the message sent (and so does not
740so does not need a queue that can overflow). AEMP sends are immediate, 935need a queue that can overflow). AEMP sends return immediately, connection
741connection establishment is handled in the background. 936establishment is handled in the background.
742 937
743=item * Erlang suffers from silent message loss, AEMP does not. 938=item * Erlang suffers from silent message loss, AEMP does not.
744 939
745Erlang makes few guarantees on messages delivery - messages can get lost 940Erlang implements few guarantees on messages delivery - messages can get
746without any of the processes realising it (i.e. you send messages a, b, 941lost without any of the processes realising it (i.e. you send messages a,
747and c, and the other side only receives messages a and c). 942b, and c, and the other side only receives messages a and c).
748 943
749AEMP guarantees correct ordering, and the guarantee that after one message 944AEMP guarantees (modulo hardware errors) correct ordering, and the
750is lost, all following ones sent to the same port are lost as well, until 945guarantee that after one message is lost, all following ones sent to the
751monitoring raises an error, so there are no silent "holes" in the message 946same port are lost as well, until monitoring raises an error, so there are
752sequence. 947no silent "holes" in the message sequence.
948
949If you want your software to be very reliable, you have to cope with
950corrupted and even out-of-order messages in both Erlang and AEMP. AEMP
951simply tries to work better in common error cases, such as when a network
952link goes down.
753 953
754=item * Erlang can send messages to the wrong port, AEMP does not. 954=item * Erlang can send messages to the wrong port, AEMP does not.
755 955
756In Erlang it is quite likely that a node that restarts reuses a process ID 956In Erlang it is quite likely that a node that restarts reuses an Erlang
757known to other nodes for a completely different process, causing messages 957process ID known to other nodes for a completely different process,
758destined for that process to end up in an unrelated process. 958causing messages destined for that process to end up in an unrelated
959process.
759 960
760AEMP never reuses port IDs, so old messages or old port IDs floating 961AEMP does not reuse port IDs, so old messages or old port IDs floating
761around in the network will not be sent to an unrelated port. 962around in the network will not be sent to an unrelated port.
762 963
763=item * Erlang uses unprotected connections, AEMP uses secure 964=item * Erlang uses unprotected connections, AEMP uses secure
764authentication and can use TLS. 965authentication and can use TLS.
765 966
768 969
769=item * The AEMP protocol is optimised for both text-based and binary 970=item * The AEMP protocol is optimised for both text-based and binary
770communications. 971communications.
771 972
772The AEMP protocol, unlike the Erlang protocol, supports both programming 973The AEMP protocol, unlike the Erlang protocol, supports both programming
773language independent text-only protocols (good for debugging) and binary, 974language independent text-only protocols (good for debugging), and binary,
774language-specific serialisers (e.g. Storable). By default, unless TLS is 975language-specific serialisers (e.g. Storable). By default, unless TLS is
775used, the protocol is actually completely text-based. 976used, the protocol is actually completely text-based.
776 977
777It has also been carefully designed to be implementable in other languages 978It has also been carefully designed to be implementable in other languages
778with a minimum of work while gracefully degrading functionality to make the 979with a minimum of work while gracefully degrading functionality to make the
779protocol simple. 980protocol simple.
780 981
781=item * AEMP has more flexible monitoring options than Erlang. 982=item * AEMP has more flexible monitoring options than Erlang.
782 983
783In Erlang, you can chose to receive I<all> exit signals as messages 984In Erlang, you can chose to receive I<all> exit signals as messages or
784or I<none>, there is no in-between, so monitoring single processes is 985I<none>, there is no in-between, so monitoring single Erlang processes is
785difficult to implement. Monitoring in AEMP is more flexible than in 986difficult to implement.
786Erlang, as one can choose between automatic kill, exit message or callback 987
787on a per-process basis. 988Monitoring in AEMP is more flexible than in Erlang, as one can choose
989between automatic kill, exit message or callback on a per-port basis.
788 990
789=item * Erlang tries to hide remote/local connections, AEMP does not. 991=item * Erlang tries to hide remote/local connections, AEMP does not.
790 992
791Monitoring in Erlang is not an indicator of process death/crashes, in the 993Monitoring in Erlang is not an indicator of process death/crashes, in the
792same way as linking is (except linking is unreliable in Erlang). 994same way as linking is (except linking is unreliable in Erlang).
814overhead, as well as having to keep a proxy object everywhere. 1016overhead, as well as having to keep a proxy object everywhere.
815 1017
816Strings can easily be printed, easily serialised etc. and need no special 1018Strings can easily be printed, easily serialised etc. and need no special
817procedures to be "valid". 1019procedures to be "valid".
818 1020
819And as a result, a miniport consists of a single closure stored in a 1021And as a result, a port with just a default receiver consists of a single
820global hash - it can't become much cheaper. 1022code reference stored in a global hash - it can't become much cheaper.
821 1023
822=item Why favour JSON, why not a real serialising format such as Storable? 1024=item Why favour JSON, why not a real serialising format such as Storable?
823 1025
824In fact, any AnyEvent::MP node will happily accept Storable as framing 1026In fact, any AnyEvent::MP node will happily accept Storable as framing
825format, but currently there is no way to make a node use Storable by 1027format, but currently there is no way to make a node use Storable by
841 1043
842L<AnyEvent::MP::Intro> - a gentle introduction. 1044L<AnyEvent::MP::Intro> - a gentle introduction.
843 1045
844L<AnyEvent::MP::Kernel> - more, lower-level, stuff. 1046L<AnyEvent::MP::Kernel> - more, lower-level, stuff.
845 1047
846L<AnyEvent::MP::Global> - network maintainance and port groups, to find 1048L<AnyEvent::MP::Global> - network maintenance and port groups, to find
847your applications. 1049your applications.
1050
1051L<AnyEvent::MP::DataConn> - establish data connections between nodes.
1052
1053L<AnyEvent::MP::LogCatcher> - simple service to display log messages from
1054all nodes.
848 1055
849L<AnyEvent>. 1056L<AnyEvent>.
850 1057
851=head1 AUTHOR 1058=head1 AUTHOR
852 1059

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines