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.69 by root, Sun Aug 30 18:51:49 2009 UTC vs.
Revision 1.84 by root, Tue Sep 8 01:42:14 2009 UTC

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
38 mon $port, $otherport # kill otherport on abnormal death 37 mon $port, $otherport # kill otherport on abnormal death
39 mon $port, $otherport, @msg # send message on death 38 mon $port, $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 - mostly stable 45 AnyEvent::MP::Kernel - mostly stable.
46 AnyEvent::MP::Global - mostly stable 46 AnyEvent::MP::Global - stable but incomplete, protocol not yet final.
47 AnyEvent::MP::Node - mostly stable, but internal anyways
48 AnyEvent::MP::Transport - mostly stable, but internal anyways
49 47
50 stay tuned. 48stay tuned.
51 49
52=head1 DESCRIPTION 50=head1 DESCRIPTION
53 51
54This module (-family) implements a simple message passing framework. 52This module (-family) implements a simple message passing framework.
55 53
57on the same or other hosts, and you can supervise entities remotely. 55on the same or other hosts, and you can supervise entities remotely.
58 56
59For an introduction to this module family, see the L<AnyEvent::MP::Intro> 57For an introduction to this module family, see the L<AnyEvent::MP::Intro>
60manual page and the examples under F<eg/>. 58manual page and the examples under F<eg/>.
61 59
62At the moment, this module family is a bit underdocumented.
63
64=head1 CONCEPTS 60=head1 CONCEPTS
65 61
66=over 4 62=over 4
67 63
68=item port 64=item port
69 65
70A port is something you can send messages to (with the C<snd> function). 66Not to be confused with a TCP port, a "port" is something you can send
67messages to (with the C<snd> function).
71 68
72Ports allow you to register C<rcv> handlers that can match all or just 69Ports 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 70some messages. Messages send to ports will not be queued, regardless of
74anything was listening for them or not. 71anything was listening for them or not.
75 72
86 83
87Nodes are either public (have one or more listening ports) or private 84Nodes are either public (have one or more listening ports) or private
88(no listening ports). Private nodes cannot talk to other private nodes 85(no listening ports). Private nodes cannot talk to other private nodes
89currently. 86currently.
90 87
91=item node ID - C<[a-za-Z0-9_\-.:]+> 88=item node ID - C<[A-Z_][a-zA-Z0-9_\-.:]*>
92 89
93A node ID is a string that uniquely identifies the node within a 90A node ID is a string that uniquely identifies the node within a
94network. Depending on the configuration used, node IDs can look like a 91network. Depending on the configuration used, node IDs can look like a
95hostname, a hostname and a port, or a random string. AnyEvent::MP itself 92hostname, a hostname and a port, or a random string. AnyEvent::MP itself
96doesn't interpret node IDs in any way. 93doesn't interpret node IDs in any way.
100Nodes can only talk to each other by creating some kind of connection to 97Nodes can only talk to each other by creating some kind of connection to
101each other. To do this, nodes should listen on one or more local transport 98each other. To do this, nodes should listen on one or more local transport
102endpoints - binds. Currently, only standard C<ip:port> specifications can 99endpoints - binds. Currently, only standard C<ip:port> specifications can
103be used, which specify TCP ports to listen on. 100be used, which specify TCP ports to listen on.
104 101
105=item seeds - C<host:port> 102=item seed nodes
106 103
107When a node starts, it knows nothing about the network. To teach the node 104When a node starts, it knows nothing about the network. To teach the node
108about the network it first has to contact some other node within the 105about the network it first has to contact some other node within the
109network. This node is called a seed. 106network. This node is called a seed.
110 107
111Seeds are transport endpoint(s) of as many nodes as one wants. Those nodes 108Apart from the fact that other nodes know them as seed nodes and they have
109to have fixed listening addresses, seed nodes are perfectly normal nodes -
110any node can function as a seed node for others.
111
112In addition to discovering the network, seed nodes are also used to
113maintain the network and to connect nodes that otherwise would have
114trouble connecting. They form the backbone of the AnyEvent::MP network.
115
112are expected to be long-running, and at least one of those should always 116Seed nodes are expected to be long-running, and at least one seed node
113be available. When nodes run out of connections (e.g. due to a network 117should always be available.
114error), they try to re-establish connections to some seednodes again to
115join the network.
116 118
117Apart from being sued for seeding, seednodes are not special in any way - 119=item seeds - C<host:port>
118every public node can be a seednode. 120
121Seeds are transport endpoint(s) (usually a hostname/IP address and a
122TCP port) of nodes thta should be used as seed nodes.
123
124The nodes listening on those endpoints are expected to be long-running,
125and at least one of those should always be available. When nodes run out
126of connections (e.g. due to a network error), they try to re-establish
127connections to some seednodes again to join the network.
119 128
120=back 129=back
121 130
122=head1 VARIABLES/FUNCTIONS 131=head1 VARIABLES/FUNCTIONS
123 132
139 148
140our $VERSION = $AnyEvent::MP::Kernel::VERSION; 149our $VERSION = $AnyEvent::MP::Kernel::VERSION;
141 150
142our @EXPORT = qw( 151our @EXPORT = qw(
143 NODE $NODE *SELF node_of after 152 NODE $NODE *SELF node_of after
144 initialise_node 153 configure
145 snd rcv mon mon_guard kil reg psub spawn 154 snd rcv mon mon_guard kil reg psub spawn
146 port 155 port
147); 156);
148 157
149our $SELF; 158our $SELF;
156 165
157=item $thisnode = NODE / $NODE 166=item $thisnode = NODE / $NODE
158 167
159The C<NODE> function returns, and the C<$NODE> variable contains, the node 168The C<NODE> function returns, and the C<$NODE> variable contains, the node
160ID of the node running in the current process. This value is initialised by 169ID of the node running in the current process. This value is initialised by
161a call to C<initialise_node>. 170a call to C<configure>.
162 171
163=item $nodeid = node_of $port 172=item $nodeid = node_of $port
164 173
165Extracts and returns the node ID from a port ID or a node ID. 174Extracts and returns the node ID from a port ID or a node ID.
166 175
167=item initialise_node $profile_name, key => value... 176=item configure $profile, key => value...
177
178=item configure key => value...
168 179
169Before a node can talk to other nodes on the network (i.e. enter 180Before a node can talk to other nodes on the network (i.e. enter
170"distributed mode") it has to initialise itself - the minimum a node needs 181"distributed mode") it has to configure itself - the minimum a node needs
171to know is its own name, and optionally it should know the addresses of 182to know is its own name, and optionally it should know the addresses of
172some other nodes in the network to discover other nodes. 183some other nodes in the network to discover other nodes.
173 184
174This function initialises a node - it must be called exactly once (or 185This function configures a node - it must be called exactly once (or
175never) before calling other AnyEvent::MP functions. 186never) before calling other AnyEvent::MP functions.
176 187
177The first argument is a profile name. If it is C<undef> or missing, then 188=over 4
178the current nodename will be used instead (i.e. F<uname -n>).
179 189
190=item step 1, gathering configuration from profiles
191
180The function first looks up the profile in the aemp configuration (see the 192The function first looks up a profile in the aemp configuration (see the
181L<aemp> commandline utility). the profile is calculated as follows: 193L<aemp> commandline utility). The profile name can be specified via the
194named C<profile> parameter or can simply be the first parameter). If it is
195missing, then the nodename (F<uname -n>) will be used as profile name.
182 196
183First, all remaining key => value pairs will be used. Then they will be 197The profile data is then gathered as follows:
184overwritten by any values specified in the global default configuration 198
185(see the F<aemp> utility), then the chain of profiles selected, if 199First, all remaining key => value pairs (all of which are conveniently
200undocumented at the moment) will be interpreted as configuration
201data. Then they will be overwritten by any values specified in the global
202default configuration (see the F<aemp> utility), then the chain of
203profiles chosen by the profile name (and any C<parent> attributes).
204
186any. That means that the values specified in the profile have highest 205That means that the values specified in the profile have highest priority
187priority and the values specified via C<initialise_node> have lowest 206and the values specified directly via C<configure> have lowest priority,
188priority. 207and can only be used to specify defaults.
189 208
190If the profile specifies a node ID, then this will become the node ID of 209If the profile specifies a node ID, then this will become the node ID of
191this process. If not, then the profile name will be used as node ID. The 210this process. If not, then the profile name will be used as node ID. The
192special node ID of C<anon/> will be replaced by a random node ID. 211special node ID of C<anon/> will be replaced by a random node ID.
212
213=item step 2, bind listener sockets
193 214
194The next step is to look up the binds in the profile, followed by binding 215The next step is to look up the binds in the profile, followed by binding
195aemp protocol listeners on all binds specified (it is possible and valid 216aemp protocol listeners on all binds specified (it is possible and valid
196to have no binds, meaning that the node cannot be contacted form the 217to have no binds, meaning that the node cannot be contacted form the
197outside. This means the node cannot talk to other nodes that also have no 218outside. This means the node cannot talk to other nodes that also have no
198binds, but it can still talk to all "normal" nodes). 219binds, but it can still talk to all "normal" nodes).
199 220
200If the profile does not specify a binds list, then the node ID will be 221If the profile does not specify a binds list, then a default of C<*> is
201treated as if it were of the form C<host:port>, which will be resolved and 222used, meaning the node will bind on a dynamically-assigned port on every
202used as binds list. 223local IP address it finds.
203 224
225=item step 3, connect to seed nodes
226
204Lastly, the seeds list from the profile is passed to the 227As the last step, the seeds list from the profile is passed to the
205L<AnyEvent::MP::Global> module, which will then use it to keep 228L<AnyEvent::MP::Global> module, which will then use it to keep
206connectivity with at least on of those seed nodes at any point in time. 229connectivity with at least one node at any point in time.
207 230
208Example: become a distributed node listening on the guessed noderef, or 231=back
209the one specified via C<aemp> for the current node. This should be the 232
233Example: become a distributed node using the locla node name as profile.
210most common form of invocation for "daemon"-type nodes. 234This should be the most common form of invocation for "daemon"-type nodes.
211 235
212 initialise_node; 236 configure
213 237
214Example: become an anonymous node. This form is often used for commandline 238Example: become an anonymous node. This form is often used for commandline
215clients. 239clients.
216 240
217 initialise_node "anon/"; 241 configure nodeid => "anon/";
218 242
219Example: become a distributed node. If there is no profile of the given 243Example: configure a node using a profile called seed, which si suitable
220name, or no binds list was specified, resolve C<localhost:4044> and bind 244for a seed node as it binds on all local addresses on a fixed port (4040,
221on the resulting addresses. 245customary for aemp).
222 246
223 initialise_node "localhost:4044"; 247 # use the aemp commandline utility
248 # aemp profile seed nodeid anon/ binds '*:4040'
249
250 # then use it
251 configure profile => "seed";
252
253 # or simply use aemp from the shell again:
254 # aemp run profile seed
255
256 # or provide a nicer-to-remember nodeid
257 # aemp run profile seed nodeid "$(hostname)"
224 258
225=item $SELF 259=item $SELF
226 260
227Contains the current port id while executing C<rcv> callbacks or C<psub> 261Contains the current port id while executing C<rcv> callbacks or C<psub>
228blocks. 262blocks.
350 384
351=cut 385=cut
352 386
353sub rcv($@) { 387sub rcv($@) {
354 my $port = shift; 388 my $port = shift;
355 my ($noderef, $portid) = split /#/, $port, 2; 389 my ($nodeid, $portid) = split /#/, $port, 2;
356 390
357 $NODE{$noderef} == $NODE{""} 391 $NODE{$nodeid} == $NODE{""}
358 or Carp::croak "$port: rcv can only be called on local ports, caught"; 392 or Carp::croak "$port: rcv can only be called on local ports, caught";
359 393
360 while (@_) { 394 while (@_) {
361 if (ref $_[0]) { 395 if (ref $_[0]) {
362 if (my $self = $PORT_DATA{$portid}) { 396 if (my $self = $PORT_DATA{$portid}) {
453 487
454Monitor the given port and do something when the port is killed or 488Monitor the given port and do something when the port is killed or
455messages to it were lost, and optionally return a guard that can be used 489messages to it were lost, and optionally return a guard that can be used
456to stop monitoring again. 490to stop monitoring again.
457 491
492In the first form (callback), the callback is simply called with any
493number of C<@reason> elements (no @reason means that the port was deleted
494"normally"). Note also that I<< the callback B<must> never die >>, so use
495C<eval> if unsure.
496
497In the second form (another port given), the other port (C<$rcvport>)
498will be C<kil>'ed with C<@reason>, if a @reason was specified, i.e. on
499"normal" kils nothing happens, while under all other conditions, the other
500port is killed with the same reason.
501
502The third form (kill self) is the same as the second form, except that
503C<$rvport> defaults to C<$SELF>.
504
505In the last form (message), a message of the form C<@msg, @reason> will be
506C<snd>.
507
508Monitoring-actions are one-shot: once messages are lost (and a monitoring
509alert was raised), they are removed and will not trigger again.
510
511As a rule of thumb, monitoring requests should always monitor a port from
512a local port (or callback). The reason is that kill messages might get
513lost, just like any other message. Another less obvious reason is that
514even monitoring requests can get lost (for example, when the connection
515to the other node goes down permanently). When monitoring a port locally
516these problems do not exist.
517
458C<mon> effectively guarantees that, in the absence of hardware failures, 518C<mon> effectively guarantees that, in the absence of hardware failures,
459after starting the monitor, either all messages sent to the port will 519after starting the monitor, either all messages sent to the port will
460arrive, or the monitoring action will be invoked after possible message 520arrive, or the monitoring action will be invoked after possible message
461loss has been detected. No messages will be lost "in between" (after 521loss has been detected. No messages will be lost "in between" (after
462the first lost message no further messages will be received by the 522the first lost message no further messages will be received by the
463port). After the monitoring action was invoked, further messages might get 523port). After the monitoring action was invoked, further messages might get
464delivered again. 524delivered again.
465 525
466Note that monitoring-actions are one-shot: once messages are lost (and a 526Inter-host-connection timeouts and monitoring depend on the transport
467monitoring alert was raised), they are removed and will not trigger again. 527used. The only transport currently implemented is TCP, and AnyEvent::MP
528relies on TCP to detect node-downs (this can take 10-15 minutes on a
529non-idle connection, and usually around two hours for idle conenctions).
468 530
469In the first form (callback), the callback is simply called with any 531This means that monitoring is good for program errors and cleaning up
470number of C<@reason> elements (no @reason means that the port was deleted 532stuff eventually, but they are no replacement for a timeout when you need
471"normally"). Note also that I<< the callback B<must> never die >>, so use 533to ensure some maximum latency.
472C<eval> if unsure.
473
474In the second form (another port given), the other port (C<$rcvport>)
475will be C<kil>'ed with C<@reason>, iff a @reason was specified, i.e. on
476"normal" kils nothing happens, while under all other conditions, the other
477port is killed with the same reason.
478
479The third form (kill self) is the same as the second form, except that
480C<$rvport> defaults to C<$SELF>.
481
482In the last form (message), a message of the form C<@msg, @reason> will be
483C<snd>.
484
485As a rule of thumb, monitoring requests should always monitor a port from
486a local port (or callback). The reason is that kill messages might get
487lost, just like any other message. Another less obvious reason is that
488even monitoring requests can get lost (for exmaple, when the connection
489to the other node goes down permanently). When monitoring a port locally
490these problems do not exist.
491 534
492Example: call a given callback when C<$port> is killed. 535Example: call a given callback when C<$port> is killed.
493 536
494 mon $port, sub { warn "port died because of <@_>\n" }; 537 mon $port, sub { warn "port died because of <@_>\n" };
495 538
502 mon $port, $self => "restart"; 545 mon $port, $self => "restart";
503 546
504=cut 547=cut
505 548
506sub mon { 549sub mon {
507 my ($noderef, $port) = split /#/, shift, 2; 550 my ($nodeid, $port) = split /#/, shift, 2;
508 551
509 my $node = $NODE{$noderef} || add_node $noderef; 552 my $node = $NODE{$nodeid} || add_node $nodeid;
510 553
511 my $cb = @_ ? shift : $SELF || Carp::croak 'mon: called with one argument only, but $SELF not set,'; 554 my $cb = @_ ? shift : $SELF || Carp::croak 'mon: called with one argument only, but $SELF not set,';
512 555
513 unless (ref $cb) { 556 unless (ref $cb) {
514 if (@_) { 557 if (@_) {
590the package, then the package above the package and so on (e.g. 633the package, then the package above the package and so on (e.g.
591C<MyApp::Chat::Server>, C<MyApp::Chat>, C<MyApp>) until the function 634C<MyApp::Chat::Server>, C<MyApp::Chat>, C<MyApp>) until the function
592exists or it runs out of package names. 635exists or it runs out of package names.
593 636
594The init function is then called with the newly-created port as context 637The init function is then called with the newly-created port as context
595object (C<$SELF>) and the C<@initdata> values as arguments. 638object (C<$SELF>) and the C<@initdata> values as arguments. It I<must>
639call one of the C<rcv> functions to set callbacks on C<$SELF>, otherwise
640the port might not get created.
596 641
597A common idiom is to pass a local port, immediately monitor the spawned 642A common idiom is to pass a local port, immediately monitor the spawned
598port, and in the remote init function, immediately monitor the passed 643port, and in the remote init function, immediately monitor the passed
599local port. This two-way monitoring ensures that both ports get cleaned up 644local port. This two-way monitoring ensures that both ports get cleaned up
600when there is a problem. 645when there is a problem.
601 646
647C<spawn> guarantees that the C<$initfunc> has no visible effects on the
648caller before C<spawn> returns (by delaying invocation when spawn is
649called for the local node).
650
602Example: spawn a chat server port on C<$othernode>. 651Example: spawn a chat server port on C<$othernode>.
603 652
604 # this node, executed from within a port context: 653 # this node, executed from within a port context:
605 my $server = spawn $othernode, "MyApp::Chat::Server::connect", $SELF; 654 my $server = spawn $othernode, "MyApp::Chat::Server::connect", $SELF;
606 mon $server; 655 mon $server;
620 669
621sub _spawn { 670sub _spawn {
622 my $port = shift; 671 my $port = shift;
623 my $init = shift; 672 my $init = shift;
624 673
674 # rcv will create the actual port
625 local $SELF = "$NODE#$port"; 675 local $SELF = "$NODE#$port";
626 eval { 676 eval {
627 &{ load_func $init } 677 &{ load_func $init }
628 }; 678 };
629 _self_die if $@; 679 _self_die if $@;
630} 680}
631 681
632sub spawn(@) { 682sub spawn(@) {
633 my ($noderef, undef) = split /#/, shift, 2; 683 my ($nodeid, undef) = split /#/, shift, 2;
634 684
635 my $id = "$RUNIQ." . $ID++; 685 my $id = "$RUNIQ." . $ID++;
636 686
637 $_[0] =~ /::/ 687 $_[0] =~ /::/
638 or Carp::croak "spawn init function must be a fully-qualified name, caught"; 688 or Carp::croak "spawn init function must be a fully-qualified name, caught";
639 689
640 snd_to_func $noderef, "AnyEvent::MP::_spawn" => $id, @_; 690 snd_to_func $nodeid, "AnyEvent::MP::_spawn" => $id, @_;
641 691
642 "$noderef#$id" 692 "$nodeid#$id"
643} 693}
644 694
645=item after $timeout, @msg 695=item after $timeout, @msg
646 696
647=item after $timeout, $callback 697=item after $timeout, $callback
686 736
687=item * Node IDs are arbitrary strings in AEMP. 737=item * Node IDs are arbitrary strings in AEMP.
688 738
689Erlang relies on special naming and DNS to work everywhere in the same 739Erlang relies on special naming and DNS to work everywhere in the same
690way. AEMP relies on each node somehow knowing its own address(es) (e.g. by 740way. AEMP relies on each node somehow knowing its own address(es) (e.g. by
691configuraiton or DNS), but will otherwise discover other odes itself. 741configuration or DNS), but will otherwise discover other odes itself.
692 742
693=item * Erlang has a "remote ports are like local ports" philosophy, AEMP 743=item * Erlang has a "remote ports are like local ports" philosophy, AEMP
694uses "local ports are like remote ports". 744uses "local ports are like remote ports".
695 745
696The failure modes for local ports are quite different (runtime errors 746The failure modes for local ports are quite different (runtime errors
709 759
710Erlang uses processes that selectively receive messages, and therefore 760Erlang uses processes that selectively receive messages, and therefore
711needs a queue. AEMP is event based, queuing messages would serve no 761needs a queue. AEMP is event based, queuing messages would serve no
712useful purpose. For the same reason the pattern-matching abilities of 762useful purpose. For the same reason the pattern-matching abilities of
713AnyEvent::MP are more limited, as there is little need to be able to 763AnyEvent::MP are more limited, as there is little need to be able to
714filter messages without dequeing them. 764filter messages without dequeuing them.
715 765
716(But see L<Coro::MP> for a more Erlang-like process model on top of AEMP). 766(But see L<Coro::MP> for a more Erlang-like process model on top of AEMP).
717 767
718=item * Erlang sends are synchronous, AEMP sends are asynchronous. 768=item * Erlang sends are synchronous, AEMP sends are asynchronous.
719 769
825L<AnyEvent::MP::Kernel> - more, lower-level, stuff. 875L<AnyEvent::MP::Kernel> - more, lower-level, stuff.
826 876
827L<AnyEvent::MP::Global> - network maintainance and port groups, to find 877L<AnyEvent::MP::Global> - network maintainance and port groups, to find
828your applications. 878your applications.
829 879
880L<AnyEvent::MP::LogCatcher> - simple service to display log messages from
881all nodes.
882
830L<AnyEvent>. 883L<AnyEvent>.
831 884
832=head1 AUTHOR 885=head1 AUTHOR
833 886
834 Marc Lehmann <schmorp@schmorp.de> 887 Marc Lehmann <schmorp@schmorp.de>

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines