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.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
40 39
41=head1 CURRENT STATUS 40=head1 CURRENT STATUS
42 41
43 bin/aemp - stable. 42 bin/aemp - stable.
44 AnyEvent::MP - stable API, should work. 43 AnyEvent::MP - stable API, should work.
45 AnyEvent::MP::Intro - uptodate, but incomplete. 44 AnyEvent::MP::Intro - explains most concepts.
46 AnyEvent::MP::Kernel - mostly stable. 45 AnyEvent::MP::Kernel - mostly stable.
47 AnyEvent::MP::Global - stable API, protocol not yet final. 46 AnyEvent::MP::Global - stable but incomplete, protocol not yet final.
48 47
49 stay tuned. 48stay tuned.
50 49
51=head1 DESCRIPTION 50=head1 DESCRIPTION
52 51
53This module (-family) implements a simple message passing framework. 52This module (-family) implements a simple message passing framework.
54 53
56on the same or other hosts, and you can supervise entities remotely. 55on the same or other hosts, and you can supervise entities remotely.
57 56
58For 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>
59manual page and the examples under F<eg/>. 58manual page and the examples under F<eg/>.
60 59
61At the moment, this module family is a bit underdocumented.
62
63=head1 CONCEPTS 60=head1 CONCEPTS
64 61
65=over 4 62=over 4
66 63
67=item port 64=item port
68 65
69A 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).
70 68
71Ports 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
72some messages. Messages send to ports will not be queued, regardless of 70some messages. Messages send to ports will not be queued, regardless of
73anything was listening for them or not. 71anything was listening for them or not.
74 72
85 83
86Nodes are either public (have one or more listening ports) or private 84Nodes are either public (have one or more listening ports) or private
87(no listening ports). Private nodes cannot talk to other private nodes 85(no listening ports). Private nodes cannot talk to other private nodes
88currently. 86currently.
89 87
90=item node ID - C<[a-za-Z0-9_\-.:]+> 88=item node ID - C<[A-Z_][a-zA-Z0-9_\-.:]*>
91 89
92A 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
93network. Depending on the configuration used, node IDs can look like a 91network. Depending on the configuration used, node IDs can look like a
94hostname, 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
95doesn't interpret node IDs in any way. 93doesn't interpret node IDs in any way.
99Nodes 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
100each 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
101endpoints - binds. Currently, only standard C<ip:port> specifications can 99endpoints - binds. Currently, only standard C<ip:port> specifications can
102be used, which specify TCP ports to listen on. 100be used, which specify TCP ports to listen on.
103 101
104=item seeds - C<host:port> 102=item seed nodes
105 103
106When 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
107about 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
108network. This node is called a seed. 106network. This node is called a seed.
109 107
110Seeds 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
111are 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
112be available. When nodes run out of connections (e.g. due to a network 117should always be available.
113error), they try to re-establish connections to some seednodes again to
114join the network.
115 118
116Apart from being sued for seeding, seednodes are not special in any way - 119=item seeds - C<host:port>
117every 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.
118 128
119=back 129=back
120 130
121=head1 VARIABLES/FUNCTIONS 131=head1 VARIABLES/FUNCTIONS
122 132
138 148
139our $VERSION = $AnyEvent::MP::Kernel::VERSION; 149our $VERSION = $AnyEvent::MP::Kernel::VERSION;
140 150
141our @EXPORT = qw( 151our @EXPORT = qw(
142 NODE $NODE *SELF node_of after 152 NODE $NODE *SELF node_of after
143 initialise_node 153 configure
144 snd rcv mon mon_guard kil reg psub spawn 154 snd rcv mon mon_guard kil reg psub spawn
145 port 155 port
146); 156);
147 157
148our $SELF; 158our $SELF;
155 165
156=item $thisnode = NODE / $NODE 166=item $thisnode = NODE / $NODE
157 167
158The 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
159ID 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
160a call to C<initialise_node>. 170a call to C<configure>.
161 171
162=item $nodeid = node_of $port 172=item $nodeid = node_of $port
163 173
164Extracts 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.
165 175
166=item initialise_node $profile_name, key => value... 176=item configure $profile, key => value...
177
178=item configure key => value...
167 179
168Before 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
169"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
170to 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
171some other nodes in the network to discover other nodes. 183some other nodes in the network to discover other nodes.
172 184
173This function initialises a node - it must be called exactly once (or 185This function configures a node - it must be called exactly once (or
174never) before calling other AnyEvent::MP functions. 186never) before calling other AnyEvent::MP functions.
175 187
176The first argument is a profile name. If it is C<undef> or missing, then 188=over 4
177the current nodename will be used instead (i.e. F<uname -n>).
178 189
190=item step 1, gathering configuration from profiles
191
179The 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
180L<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.
181 196
197The profile data is then gathered as follows:
198
182First, all remaining key => value pairs (all of which are conviniently 199First, all remaining key => value pairs (all of which are conveniently
183undocumented at the moment) will be used. Then they will be overwritten by 200undocumented at the moment) will be interpreted as configuration
184any values specified in the global default configuration (see the F<aemp> 201data. Then they will be overwritten by any values specified in the global
185utility), then the chain of profiles selected, if any. That means that 202default configuration (see the F<aemp> utility), then the chain of
203profiles chosen by the profile name (and any C<parent> attributes).
204
186the values specified in the profile have highest priority and the values 205That means that the values specified in the profile have highest priority
187specified via C<initialise_node> have lowest priority. 206and the values specified directly via C<configure> have lowest priority,
207and can only be used to specify defaults.
188 208
189If 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
190this 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
191special 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
192 214
193The 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
194aemp protocol listeners on all binds specified (it is possible and valid 216aemp protocol listeners on all binds specified (it is possible and valid
195to 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
196outside. 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
197binds, but it can still talk to all "normal" nodes). 219binds, but it can still talk to all "normal" nodes).
198 220
199If the profile does not specify a binds list, then a default of C<*> is 221If the profile does not specify a binds list, then a default of C<*> is
200used. 222used, meaning the node will bind on a dynamically-assigned port on every
223local IP address it finds.
201 224
225=item step 3, connect to seed nodes
226
202Lastly, the seeds list from the profile is passed to the 227As 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 228L<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. 229connectivity with at least one node at any point in time.
205 230
206Example: become a distributed node listening on the guessed noderef, or 231=back
207the 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.
208most common form of invocation for "daemon"-type nodes. 234This should be the most common form of invocation for "daemon"-type nodes.
209 235
210 initialise_node; 236 configure
211 237
212Example: become an anonymous node. This form is often used for commandline 238Example: become an anonymous node. This form is often used for commandline
213clients. 239clients.
214 240
215 initialise_node "anon/"; 241 configure nodeid => "anon/";
216 242
217Example: become a distributed node. If there is no profile of the given 243Example: configure a node using a profile called seed, which si suitable
218name, 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,
219on the resulting addresses. 245customary for aemp).
220 246
221 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)"
222 258
223=item $SELF 259=item $SELF
224 260
225Contains 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>
226blocks. 262blocks.
348 384
349=cut 385=cut
350 386
351sub rcv($@) { 387sub rcv($@) {
352 my $port = shift; 388 my $port = shift;
353 my ($noderef, $portid) = split /#/, $port, 2; 389 my ($nodeid, $portid) = split /#/, $port, 2;
354 390
355 $NODE{$noderef} == $NODE{""} 391 $NODE{$nodeid} == $NODE{""}
356 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";
357 393
358 while (@_) { 394 while (@_) {
359 if (ref $_[0]) { 395 if (ref $_[0]) {
360 if (my $self = $PORT_DATA{$portid}) { 396 if (my $self = $PORT_DATA{$portid}) {
451 487
452Monitor 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
453messages 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
454to stop monitoring again. 490to stop monitoring again.
455 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
456C<mon> effectively guarantees that, in the absence of hardware failures, 518C<mon> effectively guarantees that, in the absence of hardware failures,
457after starting the monitor, either all messages sent to the port will 519after starting the monitor, either all messages sent to the port will
458arrive, or the monitoring action will be invoked after possible message 520arrive, or the monitoring action will be invoked after possible message
459loss has been detected. No messages will be lost "in between" (after 521loss has been detected. No messages will be lost "in between" (after
460the first lost message no further messages will be received by the 522the first lost message no further messages will be received by the
461port). After the monitoring action was invoked, further messages might get 523port). After the monitoring action was invoked, further messages might get
462delivered again. 524delivered again.
463 525
464Note that monitoring-actions are one-shot: once messages are lost (and a 526Inter-host-connection timeouts and monitoring depend on the transport
465monitoring 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).
466 530
467In the first form (callback), the callback is simply called with any 531This means that monitoring is good for program errors and cleaning up
468number 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
469"normally"). Note also that I<< the callback B<must> never die >>, so use 533to 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 534
490Example: call a given callback when C<$port> is killed. 535Example: call a given callback when C<$port> is killed.
491 536
492 mon $port, sub { warn "port died because of <@_>\n" }; 537 mon $port, sub { warn "port died because of <@_>\n" };
493 538
500 mon $port, $self => "restart"; 545 mon $port, $self => "restart";
501 546
502=cut 547=cut
503 548
504sub mon { 549sub mon {
505 my ($noderef, $port) = split /#/, shift, 2; 550 my ($nodeid, $port) = split /#/, shift, 2;
506 551
507 my $node = $NODE{$noderef} || add_node $noderef; 552 my $node = $NODE{$nodeid} || add_node $nodeid;
508 553
509 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,';
510 555
511 unless (ref $cb) { 556 unless (ref $cb) {
512 if (@_) { 557 if (@_) {
588the 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.
589C<MyApp::Chat::Server>, C<MyApp::Chat>, C<MyApp>) until the function 634C<MyApp::Chat::Server>, C<MyApp::Chat>, C<MyApp>) until the function
590exists or it runs out of package names. 635exists or it runs out of package names.
591 636
592The 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
593object (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.
594 641
595A 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
596port, and in the remote init function, immediately monitor the passed 643port, and in the remote init function, immediately monitor the passed
597local 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
598when there is a problem. 645when there is a problem.
599 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
600Example: spawn a chat server port on C<$othernode>. 651Example: spawn a chat server port on C<$othernode>.
601 652
602 # this node, executed from within a port context: 653 # this node, executed from within a port context:
603 my $server = spawn $othernode, "MyApp::Chat::Server::connect", $SELF; 654 my $server = spawn $othernode, "MyApp::Chat::Server::connect", $SELF;
604 mon $server; 655 mon $server;
618 669
619sub _spawn { 670sub _spawn {
620 my $port = shift; 671 my $port = shift;
621 my $init = shift; 672 my $init = shift;
622 673
674 # rcv will create the actual port
623 local $SELF = "$NODE#$port"; 675 local $SELF = "$NODE#$port";
624 eval { 676 eval {
625 &{ load_func $init } 677 &{ load_func $init }
626 }; 678 };
627 _self_die if $@; 679 _self_die if $@;
628} 680}
629 681
630sub spawn(@) { 682sub spawn(@) {
631 my ($noderef, undef) = split /#/, shift, 2; 683 my ($nodeid, undef) = split /#/, shift, 2;
632 684
633 my $id = "$RUNIQ." . $ID++; 685 my $id = "$RUNIQ." . $ID++;
634 686
635 $_[0] =~ /::/ 687 $_[0] =~ /::/
636 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";
637 689
638 snd_to_func $noderef, "AnyEvent::MP::_spawn" => $id, @_; 690 snd_to_func $nodeid, "AnyEvent::MP::_spawn" => $id, @_;
639 691
640 "$noderef#$id" 692 "$nodeid#$id"
641} 693}
642 694
643=item after $timeout, @msg 695=item after $timeout, @msg
644 696
645=item after $timeout, $callback 697=item after $timeout, $callback
684 736
685=item * Node IDs are arbitrary strings in AEMP. 737=item * Node IDs are arbitrary strings in AEMP.
686 738
687Erlang 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
688way. 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
689configuraiton or DNS), but will otherwise discover other odes itself. 741configuration or DNS), but will otherwise discover other odes itself.
690 742
691=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
692uses "local ports are like remote ports". 744uses "local ports are like remote ports".
693 745
694The failure modes for local ports are quite different (runtime errors 746The failure modes for local ports are quite different (runtime errors
707 759
708Erlang uses processes that selectively receive messages, and therefore 760Erlang uses processes that selectively receive messages, and therefore
709needs a queue. AEMP is event based, queuing messages would serve no 761needs a queue. AEMP is event based, queuing messages would serve no
710useful purpose. For the same reason the pattern-matching abilities of 762useful purpose. For the same reason the pattern-matching abilities of
711AnyEvent::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
712filter messages without dequeing them. 764filter messages without dequeuing them.
713 765
714(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).
715 767
716=item * Erlang sends are synchronous, AEMP sends are asynchronous. 768=item * Erlang sends are synchronous, AEMP sends are asynchronous.
717 769
823L<AnyEvent::MP::Kernel> - more, lower-level, stuff. 875L<AnyEvent::MP::Kernel> - more, lower-level, stuff.
824 876
825L<AnyEvent::MP::Global> - network maintainance and port groups, to find 877L<AnyEvent::MP::Global> - network maintainance and port groups, to find
826your applications. 878your applications.
827 879
880L<AnyEvent::MP::LogCatcher> - simple service to display log messages from
881all nodes.
882
828L<AnyEvent>. 883L<AnyEvent>.
829 884
830=head1 AUTHOR 885=head1 AUTHOR
831 886
832 Marc Lehmann <schmorp@schmorp.de> 887 Marc Lehmann <schmorp@schmorp.de>

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines