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.53 by root, Fri Aug 14 15:31:21 2009 UTC vs.
Revision 1.149 by root, Wed Aug 17 19:44:07 2016 UTC

1=head1 NAME 1=head1 NAME
2 2
3AnyEvent::MP - multi-processing/message-passing framework 3AnyEvent::MP - erlang-style multi-processing/message-passing framework
4 4
5=head1 SYNOPSIS 5=head1 SYNOPSIS
6 6
7 use AnyEvent::MP; 7 use AnyEvent::MP;
8 8
9 $NODE # contains this node's noderef 9 $NODE # contains this node's node ID
10 NODE # returns this node's noderef 10 NODE # returns this node's node ID
11 NODE $port # returns the noderef of the port
12 11
13 $SELF # receiving/own port id in rcv callbacks 12 $SELF # receiving/own port id in rcv callbacks
14 13
15 # initialise the node so it can send/receive messages 14 # initialise the node so it can send/receive messages
16 initialise_node; # -OR- 15 configure;
17 initialise_node "localhost:4040"; # -OR-
18 initialise_node "slave/", "localhost:4040"
19 16
20 # ports are message endpoints 17 # ports are message destinations
21 18
22 # sending messages 19 # sending messages
23 snd $port, type => data...; 20 snd $port, type => data...;
24 snd $port, @msg; 21 snd $port, @msg;
25 snd @msg_with_first_element_being_a_port; 22 snd @msg_with_first_element_being_a_port;
26 23
27 # creating/using ports, the simple way 24 # creating/using ports, the simple way
28 my $simple_port = port { my @msg = @_; 0 }; 25 my $simple_port = port { my @msg = @_ };
29 26
30 # creating/using ports, tagged message matching 27 # creating/using ports, tagged message matching
31 my $port = port; 28 my $port = port;
32 rcv $port, ping => sub { snd $_[0], "pong"; 0 }; 29 rcv $port, ping => sub { snd $_[0], "pong" };
33 rcv $port, pong => sub { warn "pong received\n"; 0 }; 30 rcv $port, pong => sub { warn "pong received\n" };
34 31
35 # create a port on another node 32 # create a port on another node
36 my $port = spawn $node, $initfunc, @initdata; 33 my $port = spawn $node, $initfunc, @initdata;
37 34
35 # destroy a port again
36 kil $port; # "normal" kill
37 kil $port, my_error => "everything is broken"; # error kill
38
38 # monitoring 39 # monitoring
39 mon $port, $cb->(@msg) # callback is invoked on death 40 mon $port, $cb->(@msg) # callback is invoked on death
40 mon $port, $otherport # kill otherport on abnormal death 41 mon $port, $localport # kill localport on abnormal death
41 mon $port, $otherport, @msg # send message on death 42 mon $port, $localport, @msg # send message on death
42 43
43=head1 CURRENT STATUS 44 # temporarily execute code in port context
45 peval $port, sub { die "kill the port!" };
44 46
45 AnyEvent::MP - stable API, should work 47 # execute callbacks in $SELF port context
46 AnyEvent::MP::Intro - outdated 48 my $timer = AE::timer 1, 0, psub {
47 AnyEvent::MP::Kernel - WIP 49 die "kill the port, delayed";
48 AnyEvent::MP::Transport - mostly stable 50 };
49 51
50 stay tuned. 52 # distributed database - modification
53 db_set $family => $subkey [=> $value] # add a subkey
54 db_del $family => $subkey... # delete one or more subkeys
55 db_reg $family => $port [=> $value] # register a port
56
57 # distributed database - queries
58 db_family $family => $cb->(\%familyhash)
59 db_keys $family => $cb->(\@keys)
60 db_values $family => $cb->(\@values)
61
62 # distributed database - monitoring a family
63 db_mon $family => $cb->(\%familyhash, \@added, \@changed, \@deleted)
51 64
52=head1 DESCRIPTION 65=head1 DESCRIPTION
53 66
54This module (-family) implements a simple message passing framework. 67This module (-family) implements a simple message passing framework.
55 68
56Despite its simplicity, you can securely message other processes running 69Despite its simplicity, you can securely message other processes running
57on the same or other hosts. 70on the same or other hosts, and you can supervise entities remotely.
58 71
59For an introduction to this module family, see the L<AnyEvent::MP::Intro> 72For an introduction to this module family, see the L<AnyEvent::MP::Intro>
60manual page. 73manual page and the examples under F<eg/>.
61
62At the moment, this module family is severly broken and underdocumented,
63so do not use. This was uploaded mainly to reserve the CPAN namespace -
64stay tuned!
65 74
66=head1 CONCEPTS 75=head1 CONCEPTS
67 76
68=over 4 77=over 4
69 78
70=item port 79=item port
71 80
72A port is something you can send messages to (with the C<snd> function). 81Not to be confused with a TCP port, a "port" is something you can send
82messages to (with the C<snd> function).
73 83
74Ports allow you to register C<rcv> handlers that can match all or just 84Ports allow you to register C<rcv> handlers that can match all or just
75some messages. Messages will not be queued. 85some messages. Messages send to ports will not be queued, regardless of
86anything was listening for them or not.
76 87
88Ports are represented by (printable) strings called "port IDs".
89
77=item port id - C<noderef#portname> 90=item port ID - C<nodeid#portname>
78 91
79A port ID is the concatenation of a noderef, a hash-mark (C<#>) as 92A port ID is the concatenation of a node ID, a hash-mark (C<#>)
80separator, and a port name (a printable string of unspecified format). An 93as separator, and a port name (a printable string of unspecified
81exception is the the node port, whose ID is identical to its node 94format created by AnyEvent::MP).
82reference.
83 95
84=item node 96=item node
85 97
86A node is a single process containing at least one port - the node port, 98A node is a single process containing at least one port - the node port,
87which provides nodes to manage each other remotely, and to create new 99which enables nodes to manage each other remotely, and to create new
88ports. 100ports.
89 101
90Nodes are either private (single-process only), slaves (connected to a 102Nodes are either public (have one or more listening ports) or private
91master node only) or public nodes (connectable from unrelated nodes). 103(no listening ports). Private nodes cannot talk to other private nodes
104currently, but all nodes can talk to public nodes.
92 105
93=item noderef - C<host:port,host:port...>, C<id@noderef>, C<id> 106Nodes is represented by (printable) strings called "node IDs".
94 107
95A node reference is a string that either simply identifies the node (for 108=item node ID - C<[A-Za-z0-9_\-.:]*>
96private and slave nodes), or contains a recipe on how to reach a given
97node (for public nodes).
98 109
99This recipe is simply a comma-separated list of C<address:port> pairs (for 110A node ID is a string that uniquely identifies the node within a
100TCP/IP, other protocols might look different). 111network. Depending on the configuration used, node IDs can look like a
112hostname, a hostname and a port, or a random string. AnyEvent::MP itself
113doesn't interpret node IDs in any way except to uniquely identify a node.
101 114
102Node references come in two flavours: resolved (containing only numerical 115=item binds - C<ip:port>
103addresses) or unresolved (where hostnames are used instead of addresses).
104 116
105Before using an unresolved node reference in a message you first have to 117Nodes can only talk to each other by creating some kind of connection to
106resolve it. 118each other. To do this, nodes should listen on one or more local transport
119endpoints - binds.
120
121Currently, only standard C<ip:port> specifications can be used, which
122specify TCP ports to listen on. So a bind is basically just a tcp socket
123in listening mode that accepts connections from other nodes.
124
125=item seed nodes
126
127When a node starts, it knows nothing about the network it is in - it
128needs to connect to at least one other node that is already in the
129network. These other nodes are called "seed nodes".
130
131Seed nodes themselves are not special - they are seed nodes only because
132some other node I<uses> them as such, but any node can be used as seed
133node for other nodes, and eahc node can use a different set of seed nodes.
134
135In addition to discovering the network, seed nodes are also used to
136maintain the network - all nodes using the same seed node are part of the
137same network. If a network is split into multiple subnets because e.g. the
138network link between the parts goes down, then using the same seed nodes
139for all nodes ensures that eventually the subnets get merged again.
140
141Seed nodes are expected to be long-running, and at least one seed node
142should always be available. They should also be relatively responsive - a
143seed node that blocks for long periods will slow down everybody else.
144
145For small networks, it's best if every node uses the same set of seed
146nodes. For large networks, it can be useful to specify "regional" seed
147nodes for most nodes in an area, and use all seed nodes as seed nodes for
148each other. What's important is that all seed nodes connections form a
149complete graph, so that the network cannot split into separate subnets
150forever.
151
152Seed nodes are represented by seed IDs.
153
154=item seed IDs - C<host:port>
155
156Seed IDs are transport endpoint(s) (usually a hostname/IP address and a
157TCP port) of nodes that should be used as seed nodes.
158
159=item global nodes
160
161An AEMP network needs a discovery service - nodes need to know how to
162connect to other nodes they only know by name. In addition, AEMP offers a
163distributed "group database", which maps group names to a list of strings
164- for example, to register worker ports.
165
166A network needs at least one global node to work, and allows every node to
167be a global node.
168
169Any node that loads the L<AnyEvent::MP::Global> module becomes a global
170node and tries to keep connections to all other nodes. So while it can
171make sense to make every node "global" in small networks, it usually makes
172sense to only make seed nodes into global nodes in large networks (nodes
173keep connections to seed nodes and global nodes, so making them the same
174reduces overhead).
107 175
108=back 176=back
109 177
110=head1 VARIABLES/FUNCTIONS 178=head1 VARIABLES/FUNCTIONS
111 179
113 181
114=cut 182=cut
115 183
116package AnyEvent::MP; 184package AnyEvent::MP;
117 185
186use AnyEvent::MP::Config ();
118use AnyEvent::MP::Kernel; 187use AnyEvent::MP::Kernel;
188use AnyEvent::MP::Kernel qw(
189 %NODE %PORT %PORT_DATA $UNIQ $RUNIQ $ID
190 add_node load_func
191
192 NODE $NODE
193 configure
194 node_of port_is_local
195 snd kil
196 db_set db_del
197 db_mon db_family db_keys db_values
198);
119 199
120use common::sense; 200use common::sense;
121 201
122use Carp (); 202use Carp ();
123 203
124use AE (); 204use AnyEvent ();
205use Guard ();
125 206
126use base "Exporter"; 207use base "Exporter";
127 208
128our $VERSION = $AnyEvent::MP::Kernel::VERSION; 209our $VERSION = $AnyEvent::MP::Config::VERSION;
129 210
130our @EXPORT = qw( 211our @EXPORT = qw(
131 NODE $NODE *SELF node_of _any_ 212 NODE $NODE
132 resolve_node initialise_node 213 configure
133 snd rcv mon kil reg psub spawn 214 node_of port_is_local
134 port 215 snd kil
216 db_set db_del
217 db_mon db_family db_keys db_values
218
219 *SELF
220
221 port rcv mon mon_guard psub peval spawn cal
222 db_set db_del db_reg
223 db_mon db_family db_keys db_values
224
225 after
135); 226);
136 227
137our $SELF; 228our $SELF;
138 229
139sub _self_die() { 230sub _self_die() {
142 kil $SELF, die => $msg; 233 kil $SELF, die => $msg;
143} 234}
144 235
145=item $thisnode = NODE / $NODE 236=item $thisnode = NODE / $NODE
146 237
147The C<NODE> function returns, and the C<$NODE> variable contains the 238The C<NODE> function returns, and the C<$NODE> variable contains, the node
148noderef of the local node. The value is initialised by a call to 239ID of the node running in the current process. This value is initialised by
149C<initialise_node>. 240a call to C<configure>.
150 241
151=item $noderef = node_of $port 242=item $nodeid = node_of $port
152 243
153Extracts and returns the noderef from a port ID or a noderef. 244Extracts and returns the node ID from a port ID or a node ID.
154 245
155=item initialise_node $noderef, $seednode, $seednode... 246=item $is_local = port_is_local $port
156 247
157=item initialise_node "slave/", $master, $master... 248Returns true iff the port is a local port.
158 249
250=item configure $profile, key => value...
251
252=item configure key => value...
253
159Before a node can talk to other nodes on the network it has to initialise 254Before a node can talk to other nodes on the network (i.e. enter
160itself - the minimum a node needs to know is it's own name, and optionally 255"distributed mode") it has to configure itself - the minimum a node needs
161it should know the noderefs of some other nodes in the network. 256to know is its own name, and optionally it should know the addresses of
257some other nodes in the network to discover other nodes.
162 258
163This function initialises a node - it must be called exactly once (or 259This function configures a node - it must be called exactly once (or
164never) before calling other AnyEvent::MP functions. 260never) before calling other AnyEvent::MP functions.
165 261
166All arguments (optionally except for the first) are noderefs, which can be 262The key/value pairs are basically the same ones as documented for the
167either resolved or unresolved. 263F<aemp> command line utility (sans the set/del prefix), with these additions:
168
169The first argument will be looked up in the configuration database first
170(if it is C<undef> then the current nodename will be used instead) to find
171the relevant configuration profile (see L<aemp>). If none is found then
172the default configuration is used. The configuration supplies additional
173seed/master nodes and can override the actual noderef.
174
175There are two types of networked nodes, public nodes and slave nodes:
176 264
177=over 4 265=over 4
178 266
179=item public nodes 267=item norc => $boolean (default false)
180 268
181For public nodes, C<$noderef> (supplied either directly to 269If true, then the rc file (e.g. F<~/.perl-anyevent-mp>) will I<not>
182C<initialise_node> or indirectly via a profile or the nodename) must be a 270be consulted - all configuration options must be specified in the
183noderef (possibly unresolved, in which case it will be resolved). 271C<configure> call.
184 272
185After resolving, the node will bind itself on all endpoints and try to 273=item force => $boolean (default false)
186connect to all additional C<$seednodes> that are specified. Seednodes are
187optional and can be used to quickly bootstrap the node into an existing
188network.
189 274
190=item slave nodes 275IF true, then the values specified in the C<configure> will take
191 276precedence over any values configured via the rc file. The default is for
192When the C<$noderef> (either as given or overriden by the config file) 277the rc file to override any options specified in the program.
193is the special string C<slave/>, then the node will become a slave
194node. Slave nodes cannot be contacted from outside and will route most of
195their traffic to the master node that they attach to.
196
197At least one additional noderef is required (either by specifying it
198directly or because it is part of the configuration profile): The node
199will try to connect to all of them and will become a slave attached to the
200first node it can successfully connect to.
201 278
202=back 279=back
203 280
204This function will block until all nodes have been resolved and, for slave
205nodes, until it has successfully established a connection to a master
206server.
207
208Example: become a public node listening on the guessed noderef, or the one
209specified via C<aemp> for the current node. This should be the most common
210form of invocation for "daemon"-type nodes.
211
212 initialise_node;
213
214Example: become a slave node to any of the the seednodes specified via
215C<aemp>. This form is often used for commandline clients.
216
217 initialise_node "slave/";
218
219Example: become a slave node to any of the specified master servers. This
220form is also often used for commandline clients.
221
222 initialise_node "slave/", "master1", "192.168.13.17", "mp.example.net";
223
224Example: become a public node, and try to contact some well-known master
225servers to become part of the network.
226
227 initialise_node undef, "master1", "master2";
228
229Example: become a public node listening on port C<4041>.
230
231 initialise_node 4041;
232
233Example: become a public node, only visible on localhost port 4044.
234
235 initialise_node "localhost:4044";
236
237=item $cv = resolve_node $noderef
238
239Takes an unresolved node reference that may contain hostnames and
240abbreviated IDs, resolves all of them and returns a resolved node
241reference.
242
243In addition to C<address:port> pairs allowed in resolved noderefs, the
244following forms are supported:
245
246=over 4 281=over 4
247 282
248=item the empty string 283=item step 1, gathering configuration from profiles
249 284
250An empty-string component gets resolved as if the default port (4040) was 285The function first looks up a profile in the aemp configuration (see the
251specified. 286L<aemp> commandline utility). The profile name can be specified via the
287named C<profile> parameter or can simply be the first parameter). If it is
288missing, then the nodename (F<uname -n>) will be used as profile name.
252 289
253=item naked port numbers (e.g. C<1234>) 290The profile data is then gathered as follows:
254 291
255These are resolved by prepending the local nodename and a colon, to be 292First, all remaining key => value pairs (all of which are conveniently
256further resolved. 293undocumented at the moment) will be interpreted as configuration
294data. Then they will be overwritten by any values specified in the global
295default configuration (see the F<aemp> utility), then the chain of
296profiles chosen by the profile name (and any C<parent> attributes).
257 297
258=item hostnames (e.g. C<localhost:1234>, C<localhost>) 298That means that the values specified in the profile have highest priority
299and the values specified directly via C<configure> have lowest priority,
300and can only be used to specify defaults.
259 301
260These are resolved by using AnyEvent::DNS to resolve them, optionally 302If the profile specifies a node ID, then this will become the node ID of
261looking up SRV records for the C<aemp=4040> port, if no port was 303this process. If not, then the profile name will be used as node ID, with
262specified. 304a unique randoms tring (C</%u>) appended.
305
306The node ID can contain some C<%> sequences that are expanded: C<%n>
307is expanded to the local nodename, C<%u> is replaced by a random
308strign to make the node unique. For example, the F<aemp> commandline
309utility uses C<aemp/%n/%u> as nodename, which might expand to
310C<aemp/cerebro/ZQDGSIkRhEZQDGSIkRhE>.
311
312=item step 2, bind listener sockets
313
314The next step is to look up the binds in the profile, followed by binding
315aemp protocol listeners on all binds specified (it is possible and valid
316to have no binds, meaning that the node cannot be contacted from the
317outside. This means the node cannot talk to other nodes that also have no
318binds, but it can still talk to all "normal" nodes).
319
320If the profile does not specify a binds list, then a default of C<*> is
321used, meaning the node will bind on a dynamically-assigned port on every
322local IP address it finds.
323
324=item step 3, connect to seed nodes
325
326As the last step, the seed ID list from the profile is passed to the
327L<AnyEvent::MP::Global> module, which will then use it to keep
328connectivity with at least one node at any point in time.
263 329
264=back 330=back
331
332Example: become a distributed node using the local node name as profile.
333This should be the most common form of invocation for "daemon"-type nodes.
334
335 configure
336
337Example: become a semi-anonymous node. This form is often used for
338commandline clients.
339
340 configure nodeid => "myscript/%n/%u";
341
342Example: configure a node using a profile called seed, which is suitable
343for a seed node as it binds on all local addresses on a fixed port (4040,
344customary for aemp).
345
346 # use the aemp commandline utility
347 # aemp profile seed binds '*:4040'
348
349 # then use it
350 configure profile => "seed";
351
352 # or simply use aemp from the shell again:
353 # aemp run profile seed
354
355 # or provide a nicer-to-remember nodeid
356 # aemp run profile seed nodeid "$(hostname)"
265 357
266=item $SELF 358=item $SELF
267 359
268Contains the current port id while executing C<rcv> callbacks or C<psub> 360Contains the current port id while executing C<rcv> callbacks or C<psub>
269blocks. 361blocks.
270 362
271=item SELF, %SELF, @SELF... 363=item *SELF, SELF, %SELF, @SELF...
272 364
273Due to some quirks in how perl exports variables, it is impossible to 365Due to some quirks in how perl exports variables, it is impossible to
274just export C<$SELF>, all the symbols called C<SELF> are exported by this 366just export C<$SELF>, all the symbols named C<SELF> are exported by this
275module, but only C<$SELF> is currently used. 367module, but only C<$SELF> is currently used.
276 368
277=item snd $port, type => @data 369=item snd $port, type => @data
278 370
279=item snd $port, @msg 371=item snd $port, @msg
280 372
281Send the given message to the given port ID, which can identify either 373Send the given message to the given port, which can identify either a
282a local or a remote port, and must be a port ID. 374local or a remote port, and must be a port ID.
283 375
284While the message can be about anything, it is highly recommended to use a 376While the message can be almost anything, it is highly recommended to
285string as first element (a port ID, or some word that indicates a request 377use a string as first element (a port ID, or some word that indicates a
286type etc.). 378request type etc.) and to consist if only simple perl values (scalars,
379arrays, hashes) - if you think you need to pass an object, think again.
287 380
288The message data effectively becomes read-only after a call to this 381The message data logically becomes read-only after a call to this
289function: modifying any argument is not allowed and can cause many 382function: modifying any argument (or values referenced by them) is
290problems. 383forbidden, as there can be considerable time between the call to C<snd>
384and the time the message is actually being serialised - in fact, it might
385never be copied as within the same process it is simply handed to the
386receiving port.
291 387
292The type of data you can transfer depends on the transport protocol: when 388The type of data you can transfer depends on the transport protocol: when
293JSON is used, then only strings, numbers and arrays and hashes consisting 389JSON is used, then only strings, numbers and arrays and hashes consisting
294of those are allowed (no objects). When Storable is used, then anything 390of those are allowed (no objects). When Storable is used, then anything
295that Storable can serialise and deserialise is allowed, and for the local 391that Storable can serialise and deserialise is allowed, and for the local
296node, anything can be passed. 392node, anything can be passed. Best rely only on the common denominator of
393these.
297 394
298=item $local_port = port 395=item $local_port = port
299 396
300Create a new local port object and returns its port ID. Initially it has 397Create a new local port object and returns its port ID. Initially it has
301no callbacks set and will throw an error when it receives messages. 398no callbacks set and will throw an error when it receives messages.
320 417
321=cut 418=cut
322 419
323sub rcv($@); 420sub rcv($@);
324 421
325sub _kilme { 422my $KILME = sub {
326 die "received message on port without callback"; 423 (my $tag = substr $_[0], 0, 30) =~ s/([\x20-\x7e])/./g;
327} 424 kil $SELF, unhandled_message => "no callback found for message '$tag'";
425};
328 426
329sub port(;&) { 427sub port(;&) {
330 my $id = "$UNIQ." . $ID++; 428 my $id = $UNIQ . ++$ID;
331 my $port = "$NODE#$id"; 429 my $port = "$NODE#$id";
332 430
333 rcv $port, shift || \&_kilme; 431 rcv $port, shift || $KILME;
334 432
335 $port 433 $port
336} 434}
337 435
338=item rcv $local_port, $callback->(@msg) 436=item rcv $local_port, $callback->(@msg)
343 441
344The global C<$SELF> (exported by this module) contains C<$port> while 442The global C<$SELF> (exported by this module) contains C<$port> while
345executing the callback. Runtime errors during callback execution will 443executing the callback. Runtime errors during callback execution will
346result in the port being C<kil>ed. 444result in the port being C<kil>ed.
347 445
348The default callback received all messages not matched by a more specific 446The default callback receives all messages not matched by a more specific
349C<tag> match. 447C<tag> match.
350 448
351=item rcv $local_port, tag => $callback->(@msg_without_tag), ... 449=item rcv $local_port, tag => $callback->(@msg_without_tag), ...
352 450
353Register callbacks to be called on messages starting with the given tag on 451Register (or replace) callbacks to be called on messages starting with the
354the given port (and return the port), or unregister it (when C<$callback> 452given tag on the given port (and return the port), or unregister it (when
355is C<$undef>). 453C<$callback> is C<$undef> or missing). There can only be one callback
454registered for each tag.
356 455
357The original message will be passed to the callback, after the first 456The original message will be passed to the callback, after the first
358element (the tag) has been removed. The callback will use the same 457element (the tag) has been removed. The callback will use the same
359environment as the default callback (see above). 458environment as the default callback (see above).
360 459
372 rcv port, 471 rcv port,
373 msg1 => sub { ... }, 472 msg1 => sub { ... },
374 ... 473 ...
375 ; 474 ;
376 475
476Example: temporarily register a rcv callback for a tag matching some port
477(e.g. for an rpc reply) and unregister it after a message was received.
478
479 rcv $port, $otherport => sub {
480 my @reply = @_;
481
482 rcv $SELF, $otherport;
483 };
484
377=cut 485=cut
378 486
379sub rcv($@) { 487sub rcv($@) {
380 my $port = shift; 488 my $port = shift;
381 my ($noderef, $portid) = split /#/, $port, 2; 489 my ($nodeid, $portid) = split /#/, $port, 2;
382 490
383 ($NODE{$noderef} || add_node $noderef) == $NODE{""} 491 $nodeid eq $NODE
384 or Carp::croak "$port: rcv can only be called on local ports, caught"; 492 or Carp::croak "$port: rcv can only be called on local ports, caught";
385 493
386 while (@_) { 494 while (@_) {
387 if (ref $_[0]) { 495 if (ref $_[0]) {
388 if (my $self = $PORT_DATA{$portid}) { 496 if (my $self = $PORT_DATA{$portid}) {
389 "AnyEvent::MP::Port" eq ref $self 497 "AnyEvent::MP::Port" eq ref $self
390 or Carp::croak "$port: rcv can only be called on message matching ports, caught"; 498 or Carp::croak "$port: rcv can only be called on message matching ports, caught";
391 499
392 $self->[2] = shift; 500 $self->[0] = shift;
393 } else { 501 } else {
394 my $cb = shift; 502 my $cb = shift;
395 $PORT{$portid} = sub { 503 $PORT{$portid} = sub {
396 local $SELF = $port; 504 local $SELF = $port;
397 eval { &$cb }; _self_die if $@; 505 eval { &$cb }; _self_die if $@;
398 }; 506 };
399 } 507 }
400 } elsif (defined $_[0]) { 508 } elsif (defined $_[0]) {
401 my $self = $PORT_DATA{$portid} ||= do { 509 my $self = $PORT_DATA{$portid} ||= do {
402 my $self = bless [$PORT{$port} || sub { }, { }, $port], "AnyEvent::MP::Port"; 510 my $self = bless [$PORT{$portid} || sub { }, { }, $port], "AnyEvent::MP::Port";
403 511
404 $PORT{$portid} = sub { 512 $PORT{$portid} = sub {
405 local $SELF = $port; 513 local $SELF = $port;
406 514
407 if (my $cb = $self->[1]{$_[0]}) { 515 if (my $cb = $self->[1]{$_[0]}) {
429 } 537 }
430 538
431 $port 539 $port
432} 540}
433 541
542=item peval $port, $coderef[, @args]
543
544Evaluates the given C<$codref> within the contetx of C<$port>, that is,
545when the code throws an exception the C<$port> will be killed.
546
547Any remaining args will be passed to the callback. Any return values will
548be returned to the caller.
549
550This is useful when you temporarily want to execute code in the context of
551a port.
552
553Example: create a port and run some initialisation code in it's context.
554
555 my $port = port { ... };
556
557 peval $port, sub {
558 init
559 or die "unable to init";
560 };
561
562=cut
563
564sub peval($$) {
565 local $SELF = shift;
566 my $cb = shift;
567
568 if (wantarray) {
569 my @res = eval { &$cb };
570 _self_die if $@;
571 @res
572 } else {
573 my $res = eval { &$cb };
574 _self_die if $@;
575 $res
576 }
577}
578
434=item $closure = psub { BLOCK } 579=item $closure = psub { BLOCK }
435 580
436Remembers C<$SELF> and creates a closure out of the BLOCK. When the 581Remembers C<$SELF> and creates a closure out of the BLOCK. When the
437closure is executed, sets up the environment in the same way as in C<rcv> 582closure is executed, sets up the environment in the same way as in C<rcv>
438callbacks, i.e. runtime errors will cause the port to get C<kil>ed. 583callbacks, i.e. runtime errors will cause the port to get C<kil>ed.
584
585The effect is basically as if it returned C<< sub { peval $SELF, sub {
586BLOCK }, @_ } >>.
439 587
440This is useful when you register callbacks from C<rcv> callbacks: 588This is useful when you register callbacks from C<rcv> callbacks:
441 589
442 rcv delayed_reply => sub { 590 rcv delayed_reply => sub {
443 my ($delay, @reply) = @_; 591 my ($delay, @reply) = @_;
467 $res 615 $res
468 } 616 }
469 } 617 }
470} 618}
471 619
472=item $guard = mon $port, $cb->(@reason) 620=item $guard = mon $port, $rcvport # kill $rcvport when $port dies
473 621
474=item $guard = mon $port, $rcvport 622=item $guard = mon $port # kill $SELF when $port dies
475 623
476=item $guard = mon $port 624=item $guard = mon $port, $cb->(@reason) # call $cb when $port dies
477 625
478=item $guard = mon $port, $rcvport, @msg 626=item $guard = mon $port, $rcvport, @msg # send a message when $port dies
479 627
480Monitor the given port and do something when the port is killed or 628Monitor the given port and do something when the port is killed or
481messages to it were lost, and optionally return a guard that can be used 629messages to it were lost, and optionally return a guard that can be used
482to stop monitoring again. 630to stop monitoring again.
483 631
632The first two forms distinguish between "normal" and "abnormal" kil's:
633
634In the first form (another port given), if the C<$port> is C<kil>'ed with
635a non-empty reason, the other port (C<$rcvport>) will be kil'ed with the
636same reason. That is, on "normal" kil's nothing happens, while under all
637other conditions, the other port is killed with the same reason.
638
639The second form (kill self) is the same as the first form, except that
640C<$rvport> defaults to C<$SELF>.
641
642The remaining forms don't distinguish between "normal" and "abnormal" kil's
643- it's up to the callback or receiver to check whether the C<@reason> is
644empty and act accordingly.
645
646In the third form (callback), the callback is simply called with any
647number of C<@reason> elements (empty @reason means that the port was deleted
648"normally"). Note also that I<< the callback B<must> never die >>, so use
649C<eval> if unsure.
650
651In the last form (message), a message of the form C<$rcvport, @msg,
652@reason> will be C<snd>.
653
654Monitoring-actions are one-shot: once messages are lost (and a monitoring
655alert was raised), they are removed and will not trigger again, even if it
656turns out that the port is still alive.
657
658As a rule of thumb, monitoring requests should always monitor a remote
659port locally (using a local C<$rcvport> or a callback). The reason is that
660kill messages might get lost, just like any other message. Another less
661obvious reason is that even monitoring requests can get lost (for example,
662when the connection to the other node goes down permanently). When
663monitoring a port locally these problems do not exist.
664
484C<mon> effectively guarantees that, in the absence of hardware failures, 665C<mon> effectively guarantees that, in the absence of hardware failures,
485that after starting the monitor, either all messages sent to the port 666after starting the monitor, either all messages sent to the port will
486will arrive, or the monitoring action will be invoked after possible 667arrive, or the monitoring action will be invoked after possible message
487message loss has been detected. No messages will be lost "in between" 668loss has been detected. No messages will be lost "in between" (after
488(after the first lost message no further messages will be received by the 669the first lost message no further messages will be received by the
489port). After the monitoring action was invoked, further messages might get 670port). After the monitoring action was invoked, further messages might get
490delivered again. 671delivered again.
491 672
492In the first form (callback), the callback is simply called with any 673Inter-host-connection timeouts and monitoring depend on the transport
493number of C<@reason> elements (no @reason means that the port was deleted 674used. The only transport currently implemented is TCP, and AnyEvent::MP
494"normally"). Note also that I<< the callback B<must> never die >>, so use 675relies on TCP to detect node-downs (this can take 10-15 minutes on a
495C<eval> if unsure. 676non-idle connection, and usually around two hours for idle connections).
496 677
497In the second form (another port given), the other port (C<$rcvport>) 678This means that monitoring is good for program errors and cleaning up
498will be C<kil>'ed with C<@reason>, iff a @reason was specified, i.e. on 679stuff eventually, but they are no replacement for a timeout when you need
499"normal" kils nothing happens, while under all other conditions, the other 680to ensure some maximum latency.
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
508As a rule of thumb, monitoring requests should always monitor a port from
509a local port (or callback). The reason is that kill messages might get
510lost, just like any other message. Another less obvious reason is that
511even monitoring requests can get lost (for exmaple, when the connection
512to the other node goes down permanently). When monitoring a port locally
513these problems do not exist.
514 681
515Example: call a given callback when C<$port> is killed. 682Example: call a given callback when C<$port> is killed.
516 683
517 mon $port, sub { warn "port died because of <@_>\n" }; 684 mon $port, sub { warn "port died because of <@_>\n" };
518 685
525 mon $port, $self => "restart"; 692 mon $port, $self => "restart";
526 693
527=cut 694=cut
528 695
529sub mon { 696sub mon {
530 my ($noderef, $port) = split /#/, shift, 2; 697 my ($nodeid, $port) = split /#/, shift, 2;
531 698
532 my $node = $NODE{$noderef} || add_node $noderef; 699 my $node = $NODE{$nodeid} || add_node $nodeid;
533 700
534 my $cb = @_ ? shift : $SELF || Carp::croak 'mon: called with one argument only, but $SELF not set,'; 701 my $cb = @_ ? shift : $SELF || Carp::croak 'mon: called with one argument only, but $SELF not set,';
535 702
536 unless (ref $cb) { 703 unless (ref $cb) {
537 if (@_) { 704 if (@_) {
546 } 713 }
547 714
548 $node->monitor ($port, $cb); 715 $node->monitor ($port, $cb);
549 716
550 defined wantarray 717 defined wantarray
551 and AnyEvent::Util::guard { $node->unmonitor ($port, $cb) } 718 and ($cb += 0, Guard::guard { $node->unmonitor ($port, $cb) })
552} 719}
553 720
554=item $guard = mon_guard $port, $ref, $ref... 721=item $guard = mon_guard $port, $ref, $ref...
555 722
556Monitors the given C<$port> and keeps the passed references. When the port 723Monitors the given C<$port> and keeps the passed references. When the port
557is killed, the references will be freed. 724is killed, the references will be freed.
558 725
559Optionally returns a guard that will stop the monitoring. 726Optionally returns a guard that will stop the monitoring.
560 727
561This function is useful when you create e.g. timers or other watchers and 728This function is useful when you create e.g. timers or other watchers and
562want to free them when the port gets killed: 729want to free them when the port gets killed (note the use of C<psub>):
563 730
564 $port->rcv (start => sub { 731 $port->rcv (start => sub {
565 my $timer; $timer = mon_guard $port, AE::timer 1, 1, sub { 732 my $timer; $timer = mon_guard $port, AE::timer 1, 1, psub {
566 undef $timer if 0.9 < rand; 733 undef $timer if 0.9 < rand;
567 }); 734 });
568 }); 735 });
569 736
570=cut 737=cut
579 746
580=item kil $port[, @reason] 747=item kil $port[, @reason]
581 748
582Kill the specified port with the given C<@reason>. 749Kill the specified port with the given C<@reason>.
583 750
584If no C<@reason> is specified, then the port is killed "normally" (linked 751If no C<@reason> is specified, then the port is killed "normally" -
585ports will not be kileld, or even notified). 752monitor callback will be invoked, but the kil will not cause linked ports
753(C<mon $mport, $lport> form) to get killed.
586 754
587Otherwise, linked ports get killed with the same reason (second form of 755If a C<@reason> is specified, then linked ports (C<mon $mport, $lport>
588C<mon>, see below). 756form) get killed with the same reason.
589 757
590Runtime errors while evaluating C<rcv> callbacks or inside C<psub> blocks 758Runtime errors while evaluating C<rcv> callbacks or inside C<psub> blocks
591will be reported as reason C<< die => $@ >>. 759will be reported as reason C<< die => $@ >>.
592 760
593Transport/communication errors are reported as C<< transport_error => 761Transport/communication errors are reported as C<< transport_error =>
594$message >>. 762$message >>.
595 763
596=cut 764Common idioms:
765
766 # silently remove yourself, do not kill linked ports
767 kil $SELF;
768
769 # report a failure in some detail
770 kil $SELF, failure_mode_1 => "it failed with too high temperature";
771
772 # do not waste much time with killing, just die when something goes wrong
773 open my $fh, "<file"
774 or die "file: $!";
597 775
598=item $port = spawn $node, $initfunc[, @initdata] 776=item $port = spawn $node, $initfunc[, @initdata]
599 777
600Creates a port on the node C<$node> (which can also be a port ID, in which 778Creates a port on the node C<$node> (which can also be a port ID, in which
601case it's the node where that port resides). 779case it's the node where that port resides).
602 780
603The port ID of the newly created port is return immediately, and it is 781The port ID of the newly created port is returned immediately, and it is
604permissible to immediately start sending messages or monitor the port. 782possible to immediately start sending messages or to monitor the port.
605 783
606After the port has been created, the init function is 784After the port has been created, the init function is called on the remote
607called. This function must be a fully-qualified function name 785node, in the same context as a C<rcv> callback. This function must be a
608(e.g. C<MyApp::Chat::Server::init>). To specify a function in the main 786fully-qualified function name (e.g. C<MyApp::Chat::Server::init>). To
609program, use C<::name>. 787specify a function in the main program, use C<::name>.
610 788
611If the function doesn't exist, then the node tries to C<require> 789If the function doesn't exist, then the node tries to C<require>
612the package, then the package above the package and so on (e.g. 790the package, then the package above the package and so on (e.g.
613C<MyApp::Chat::Server>, C<MyApp::Chat>, C<MyApp>) until the function 791C<MyApp::Chat::Server>, C<MyApp::Chat>, C<MyApp>) until the function
614exists or it runs out of package names. 792exists or it runs out of package names.
615 793
616The init function is then called with the newly-created port as context 794The init function is then called with the newly-created port as context
617object (C<$SELF>) and the C<@initdata> values as arguments. 795object (C<$SELF>) and the C<@initdata> values as arguments. It I<must>
796call one of the C<rcv> functions to set callbacks on C<$SELF>, otherwise
797the port might not get created.
618 798
619A common idiom is to pass your own port, monitor the spawned port, and 799A common idiom is to pass a local port, immediately monitor the spawned
620in the init function, monitor the original port. This two-way monitoring 800port, and in the remote init function, immediately monitor the passed
621ensures that both ports get cleaned up when there is a problem. 801local port. This two-way monitoring ensures that both ports get cleaned up
802when there is a problem.
803
804C<spawn> guarantees that the C<$initfunc> has no visible effects on the
805caller before C<spawn> returns (by delaying invocation when spawn is
806called for the local node).
622 807
623Example: spawn a chat server port on C<$othernode>. 808Example: spawn a chat server port on C<$othernode>.
624 809
625 # this node, executed from within a port context: 810 # this node, executed from within a port context:
626 my $server = spawn $othernode, "MyApp::Chat::Server::connect", $SELF; 811 my $server = spawn $othernode, "MyApp::Chat::Server::connect", $SELF;
641 826
642sub _spawn { 827sub _spawn {
643 my $port = shift; 828 my $port = shift;
644 my $init = shift; 829 my $init = shift;
645 830
831 # rcv will create the actual port
646 local $SELF = "$NODE#$port"; 832 local $SELF = "$NODE#$port";
647 eval { 833 eval {
648 &{ load_func $init } 834 &{ load_func $init }
649 }; 835 };
650 _self_die if $@; 836 _self_die if $@;
651} 837}
652 838
653sub spawn(@) { 839sub spawn(@) {
654 my ($noderef, undef) = split /#/, shift, 2; 840 my ($nodeid, undef) = split /#/, shift, 2;
655 841
656 my $id = "$RUNIQ." . $ID++; 842 my $id = $RUNIQ . ++$ID;
657 843
658 $_[0] =~ /::/ 844 $_[0] =~ /::/
659 or Carp::croak "spawn init function must be a fully-qualified name, caught"; 845 or Carp::croak "spawn init function must be a fully-qualified name, caught";
660 846
661 ($NODE{$noderef} || add_node $noderef) 847 snd_to_func $nodeid, "AnyEvent::MP::_spawn" => $id, @_;
662 ->send (["", "AnyEvent::MP::_spawn" => $id, @_]);
663 848
664 "$noderef#$id" 849 "$nodeid#$id"
665} 850}
666 851
852
853=item after $timeout, @msg
854
855=item after $timeout, $callback
856
857Either sends the given message, or call the given callback, after the
858specified number of seconds.
859
860This is simply a utility function that comes in handy at times - the
861AnyEvent::MP author is not convinced of the wisdom of having it, though,
862so it may go away in the future.
863
864=cut
865
866sub after($@) {
867 my ($timeout, @action) = @_;
868
869 my $t; $t = AE::timer $timeout, 0, sub {
870 undef $t;
871 ref $action[0]
872 ? $action[0]()
873 : snd @action;
874 };
875}
876
877#=item $cb2 = timeout $seconds, $cb[, @args]
878
879=item cal $port, @msg, $callback[, $timeout]
880
881A simple form of RPC - sends a message to the given C<$port> with the
882given contents (C<@msg>), but adds a reply port to the message.
883
884The reply port is created temporarily just for the purpose of receiving
885the reply, and will be C<kil>ed when no longer needed.
886
887A reply message sent to the port is passed to the C<$callback> as-is.
888
889If an optional time-out (in seconds) is given and it is not C<undef>,
890then the callback will be called without any arguments after the time-out
891elapsed and the port is C<kil>ed.
892
893If no time-out is given (or it is C<undef>), then the local port will
894monitor the remote port instead, so it eventually gets cleaned-up.
895
896Currently this function returns the temporary port, but this "feature"
897might go in future versions unless you can make a convincing case that
898this is indeed useful for something.
899
900=cut
901
902sub cal(@) {
903 my $timeout = ref $_[-1] ? undef : pop;
904 my $cb = pop;
905
906 my $port = port {
907 undef $timeout;
908 kil $SELF;
909 &$cb;
910 };
911
912 if (defined $timeout) {
913 $timeout = AE::timer $timeout, 0, sub {
914 undef $timeout;
915 kil $port;
916 $cb->();
917 };
918 } else {
919 mon $_[0], sub {
920 kil $port;
921 $cb->();
922 };
923 }
924
925 push @_, $port;
926 &snd;
927
928 $port
929}
930
667=back 931=back
668 932
669=head1 NODE MESSAGES 933=head1 DISTRIBUTED DATABASE
670 934
671Nodes understand the following messages sent to them. Many of them take 935AnyEvent::MP comes with a simple distributed database. The database will
672arguments called C<@reply>, which will simply be used to compose a reply 936be mirrored asynchronously on all global nodes. Other nodes bind to one
673message - C<$reply[0]> is the port to reply to, C<$reply[1]> the type and 937of the global nodes for their needs. Every node has a "local database"
674the remaining arguments are simply the message data. 938which contains all the values that are set locally. All local databases
939are merged together to form the global database, which can be queried.
675 940
676While other messages exist, they are not public and subject to change. 941The database structure is that of a two-level hash - the database hash
942contains hashes which contain values, similarly to a perl hash of hashes,
943i.e.:
677 944
945 $DATABASE{$family}{$subkey} = $value
946
947The top level hash key is called "family", and the second-level hash key
948is called "subkey" or simply "key".
949
950The family must be alphanumeric, i.e. start with a letter and consist
951of letters, digits, underscores and colons (C<[A-Za-z][A-Za-z0-9_:]*>,
952pretty much like Perl module names.
953
954As the family namespace is global, it is recommended to prefix family names
955with the name of the application or module using it.
956
957The subkeys must be non-empty strings, with no further restrictions.
958
959The values should preferably be strings, but other perl scalars should
960work as well (such as C<undef>, arrays and hashes).
961
962Every database entry is owned by one node - adding the same family/subkey
963combination on multiple nodes will not cause discomfort for AnyEvent::MP,
964but the result might be nondeterministic, i.e. the key might have
965different values on different nodes.
966
967Different subkeys in the same family can be owned by different nodes
968without problems, and in fact, this is the common method to create worker
969pools. For example, a worker port for image scaling might do this:
970
971 db_set my_image_scalers => $port;
972
973And clients looking for an image scaler will want to get the
974C<my_image_scalers> keys from time to time:
975
976 db_keys my_image_scalers => sub {
977 @ports = @{ $_[0] };
978 };
979
980Or better yet, they want to monitor the database family, so they always
981have a reasonable up-to-date copy:
982
983 db_mon my_image_scalers => sub {
984 @ports = keys %{ $_[0] };
985 };
986
987In general, you can set or delete single subkeys, but query and monitor
988whole families only.
989
990If you feel the need to monitor or query a single subkey, try giving it
991it's own family.
992
678=over 4 993=over
994
995=item $guard = db_set $family => $subkey [=> $value]
996
997Sets (or replaces) a key to the database - if C<$value> is omitted,
998C<undef> is used instead.
999
1000When called in non-void context, C<db_set> returns a guard that
1001automatically calls C<db_del> when it is destroyed.
1002
1003=item db_del $family => $subkey...
1004
1005Deletes one or more subkeys from the database family.
1006
1007=item $guard = db_reg $family => $port => $value
1008
1009=item $guard = db_reg $family => $port
1010
1011=item $guard = db_reg $family
1012
1013Registers a port in the given family and optionally returns a guard to
1014remove it.
1015
1016This function basically does the same as:
1017
1018 db_set $family => $port => $value
1019
1020Except that the port is monitored and automatically removed from the
1021database family when it is kil'ed.
1022
1023If C<$value> is missing, C<undef> is used. If C<$port> is missing, then
1024C<$SELF> is used.
1025
1026This function is most useful to register a port in some port group (which
1027is just another name for a database family), and have it removed when the
1028port is gone. This works best when the port is a local port.
679 1029
680=cut 1030=cut
681 1031
682=item lookup => $name, @reply 1032sub db_reg($$;$) {
1033 my $family = shift;
1034 my $port = @_ ? shift : $SELF;
683 1035
684Replies with the port ID of the specified well-known port, or C<undef>. 1036 my $clr = sub { db_del $family => $port };
1037 mon $port, $clr;
685 1038
686=item devnull => ... 1039 db_set $family => $port => $_[0];
687 1040
688Generic data sink/CPU heat conversion. 1041 defined wantarray
1042 and &Guard::guard ($clr)
1043}
689 1044
690=item relay => $port, @msg 1045=item db_family $family => $cb->(\%familyhash)
691 1046
692Simply forwards the message to the given port. 1047Queries the named database C<$family> and call the callback with the
1048family represented as a hash. You can keep and freely modify the hash.
693 1049
694=item eval => $string[ @reply] 1050=item db_keys $family => $cb->(\@keys)
695 1051
696Evaluates the given string. If C<@reply> is given, then a message of the 1052Same as C<db_family>, except it only queries the family I<subkeys> and passes
697form C<@reply, $@, @evalres> is sent. 1053them as array reference to the callback.
698 1054
699Example: crash another node. 1055=item db_values $family => $cb->(\@values)
700 1056
701 snd $othernode, eval => "exit"; 1057Same as C<db_family>, except it only queries the family I<values> and passes them
1058as array reference to the callback.
702 1059
703=item time => @reply 1060=item $guard = db_mon $family => $cb->(\%familyhash, \@added, \@changed, \@deleted)
704 1061
705Replies the the current node time to C<@reply>. 1062Creates a monitor on the given database family. Each time a key is
1063set or is deleted the callback is called with a hash containing the
1064database family and three lists of added, changed and deleted subkeys,
1065respectively. If no keys have changed then the array reference might be
1066C<undef> or even missing.
706 1067
707Example: tell the current node to send the current time to C<$myport> in a 1068If not called in void context, a guard object is returned that, when
708C<timereply> message. 1069destroyed, stops the monitor.
709 1070
710 snd $NODE, time => $myport, timereply => 1, 2; 1071The family hash reference and the key arrays belong to AnyEvent::MP and
711 # => snd $myport, timereply => 1, 2, <time> 1072B<must not be modified or stored> by the callback. When in doubt, make a
1073copy.
1074
1075As soon as possible after the monitoring starts, the callback will be
1076called with the intiial contents of the family, even if it is empty,
1077i.e. there will always be a timely call to the callback with the current
1078contents.
1079
1080It is possible that the callback is called with a change event even though
1081the subkey is already present and the value has not changed.
1082
1083The monitoring stops when the guard object is destroyed.
1084
1085Example: on every change to the family "mygroup", print out all keys.
1086
1087 my $guard = db_mon mygroup => sub {
1088 my ($family, $a, $c, $d) = @_;
1089 print "mygroup members: ", (join " ", keys %$family), "\n";
1090 };
1091
1092Exmaple: wait until the family "My::Module::workers" is non-empty.
1093
1094 my $guard; $guard = db_mon My::Module::workers => sub {
1095 my ($family, $a, $c, $d) = @_;
1096 return unless %$family;
1097 undef $guard;
1098 print "My::Module::workers now nonempty\n";
1099 };
1100
1101Example: print all changes to the family "AnyEvent::Fantasy::Module".
1102
1103 my $guard = db_mon AnyEvent::Fantasy::Module => sub {
1104 my ($family, $a, $c, $d) = @_;
1105
1106 print "+$_=$family->{$_}\n" for @$a;
1107 print "*$_=$family->{$_}\n" for @$c;
1108 print "-$_=$family->{$_}\n" for @$d;
1109 };
1110
1111=cut
712 1112
713=back 1113=back
714 1114
715=head1 AnyEvent::MP vs. Distributed Erlang 1115=head1 AnyEvent::MP vs. Distributed Erlang
716 1116
717AnyEvent::MP got lots of its ideas from distributed Erlang (Erlang node 1117AnyEvent::MP got lots of its ideas from distributed Erlang (Erlang node
718== aemp node, Erlang process == aemp port), so many of the documents and 1118== aemp node, Erlang process == aemp port), so many of the documents and
719programming techniques employed by Erlang apply to AnyEvent::MP. Here is a 1119programming techniques employed by Erlang apply to AnyEvent::MP. Here is a
720sample: 1120sample:
721 1121
722 http://www.Erlang.se/doc/programming_rules.shtml 1122 http://www.erlang.se/doc/programming_rules.shtml
723 http://Erlang.org/doc/getting_started/part_frame.html # chapters 3 and 4 1123 http://erlang.org/doc/getting_started/part_frame.html # chapters 3 and 4
724 http://Erlang.org/download/Erlang-book-part1.pdf # chapters 5 and 6 1124 http://erlang.org/download/erlang-book-part1.pdf # chapters 5 and 6
725 http://Erlang.org/download/armstrong_thesis_2003.pdf # chapters 4 and 5 1125 http://erlang.org/download/armstrong_thesis_2003.pdf # chapters 4 and 5
726 1126
727Despite the similarities, there are also some important differences: 1127Despite the similarities, there are also some important differences:
728 1128
729=over 4 1129=over 4
730 1130
731=item * Node references contain the recipe on how to contact them. 1131=item * Node IDs are arbitrary strings in AEMP.
732 1132
733Erlang relies on special naming and DNS to work everywhere in the 1133Erlang relies on special naming and DNS to work everywhere in the same
734same way. AEMP relies on each node knowing it's own address(es), with 1134way. AEMP relies on each node somehow knowing its own address(es) (e.g. by
735convenience functionality. 1135configuration or DNS), and possibly the addresses of some seed nodes, but
1136will otherwise discover other nodes (and their IDs) itself.
736 1137
737This means that AEMP requires a less tightly controlled environment at the
738cost of longer node references and a slightly higher management overhead.
739
740=item Erlang has a "remote ports are like local ports" philosophy, AEMP 1138=item * Erlang has a "remote ports are like local ports" philosophy, AEMP
741uses "local ports are like remote ports". 1139uses "local ports are like remote ports".
742 1140
743The failure modes for local ports are quite different (runtime errors 1141The failure modes for local ports are quite different (runtime errors
744only) then for remote ports - when a local port dies, you I<know> it dies, 1142only) then for remote ports - when a local port dies, you I<know> it dies,
745when a connection to another node dies, you know nothing about the other 1143when a connection to another node dies, you know nothing about the other
752ports being the special case/exception, where transport errors cannot 1150ports being the special case/exception, where transport errors cannot
753occur. 1151occur.
754 1152
755=item * Erlang uses processes and a mailbox, AEMP does not queue. 1153=item * Erlang uses processes and a mailbox, AEMP does not queue.
756 1154
757Erlang uses processes that selectively receive messages, and therefore 1155Erlang uses processes that selectively receive messages out of order, and
758needs a queue. AEMP is event based, queuing messages would serve no 1156therefore needs a queue. AEMP is event based, queuing messages would serve
759useful purpose. For the same reason the pattern-matching abilities of 1157no useful purpose. For the same reason the pattern-matching abilities
760AnyEvent::MP are more limited, as there is little need to be able to 1158of AnyEvent::MP are more limited, as there is little need to be able to
761filter messages without dequeing them. 1159filter messages without dequeuing them.
762 1160
763(But see L<Coro::MP> for a more Erlang-like process model on top of AEMP). 1161This is not a philosophical difference, but simply stems from AnyEvent::MP
1162being event-based, while Erlang is process-based.
1163
1164You can have a look at L<Coro::MP> for a more Erlang-like process model on
1165top of AEMP and Coro threads.
764 1166
765=item * Erlang sends are synchronous, AEMP sends are asynchronous. 1167=item * Erlang sends are synchronous, AEMP sends are asynchronous.
766 1168
767Sending messages in Erlang is synchronous and blocks the process (and 1169Sending messages in Erlang is synchronous and blocks the process until
1170a connection has been established and the message sent (and so does not
768so does not need a queue that can overflow). AEMP sends are immediate, 1171need a queue that can overflow). AEMP sends return immediately, connection
769connection establishment is handled in the background. 1172establishment is handled in the background.
770 1173
771=item * Erlang suffers from silent message loss, AEMP does not. 1174=item * Erlang suffers from silent message loss, AEMP does not.
772 1175
773Erlang makes few guarantees on messages delivery - messages can get lost 1176Erlang implements few guarantees on messages delivery - messages can get
774without any of the processes realising it (i.e. you send messages a, b, 1177lost without any of the processes realising it (i.e. you send messages a,
775and c, and the other side only receives messages a and c). 1178b, and c, and the other side only receives messages a and c).
776 1179
777AEMP guarantees correct ordering, and the guarantee that there are no 1180AEMP guarantees (modulo hardware errors) correct ordering, and the
1181guarantee that after one message is lost, all following ones sent to the
1182same port are lost as well, until monitoring raises an error, so there are
778holes in the message sequence. 1183no silent "holes" in the message sequence.
779 1184
780=item * In Erlang, processes can be declared dead and later be found to be 1185If you want your software to be very reliable, you have to cope with
781alive. 1186corrupted and even out-of-order messages in both Erlang and AEMP. AEMP
782 1187simply tries to work better in common error cases, such as when a network
783In Erlang it can happen that a monitored process is declared dead and 1188link goes down.
784linked processes get killed, but later it turns out that the process is
785still alive - and can receive messages.
786
787In AEMP, when port monitoring detects a port as dead, then that port will
788eventually be killed - it cannot happen that a node detects a port as dead
789and then later sends messages to it, finding it is still alive.
790 1189
791=item * Erlang can send messages to the wrong port, AEMP does not. 1190=item * Erlang can send messages to the wrong port, AEMP does not.
792 1191
793In Erlang it is quite likely that a node that restarts reuses a process ID 1192In Erlang it is quite likely that a node that restarts reuses an Erlang
794known to other nodes for a completely different process, causing messages 1193process ID known to other nodes for a completely different process,
795destined for that process to end up in an unrelated process. 1194causing messages destined for that process to end up in an unrelated
1195process.
796 1196
797AEMP never reuses port IDs, so old messages or old port IDs floating 1197AEMP does not reuse port IDs, so old messages or old port IDs floating
798around in the network will not be sent to an unrelated port. 1198around in the network will not be sent to an unrelated port.
799 1199
800=item * Erlang uses unprotected connections, AEMP uses secure 1200=item * Erlang uses unprotected connections, AEMP uses secure
801authentication and can use TLS. 1201authentication and can use TLS.
802 1202
803AEMP can use a proven protocol - SSL/TLS - to protect connections and 1203AEMP can use a proven protocol - TLS - to protect connections and
804securely authenticate nodes. 1204securely authenticate nodes.
805 1205
806=item * The AEMP protocol is optimised for both text-based and binary 1206=item * The AEMP protocol is optimised for both text-based and binary
807communications. 1207communications.
808 1208
809The AEMP protocol, unlike the Erlang protocol, supports both 1209The AEMP protocol, unlike the Erlang protocol, supports both programming
810language-independent text-only protocols (good for debugging) and binary, 1210language independent text-only protocols (good for debugging), and binary,
811language-specific serialisers (e.g. Storable). 1211language-specific serialisers (e.g. Storable). By default, unless TLS is
1212used, the protocol is actually completely text-based.
812 1213
813It has also been carefully designed to be implementable in other languages 1214It has also been carefully designed to be implementable in other languages
814with a minimum of work while gracefully degrading fucntionality to make the 1215with a minimum of work while gracefully degrading functionality to make the
815protocol simple. 1216protocol simple.
816 1217
817=item * AEMP has more flexible monitoring options than Erlang. 1218=item * AEMP has more flexible monitoring options than Erlang.
818 1219
819In Erlang, you can chose to receive I<all> exit signals as messages 1220In Erlang, you can chose to receive I<all> exit signals as messages or
820or I<none>, there is no in-between, so monitoring single processes is 1221I<none>, there is no in-between, so monitoring single Erlang processes is
821difficult to implement. Monitoring in AEMP is more flexible than in 1222difficult to implement.
822Erlang, as one can choose between automatic kill, exit message or callback 1223
823on a per-process basis. 1224Monitoring in AEMP is more flexible than in Erlang, as one can choose
1225between automatic kill, exit message or callback on a per-port basis.
824 1226
825=item * Erlang tries to hide remote/local connections, AEMP does not. 1227=item * Erlang tries to hide remote/local connections, AEMP does not.
826 1228
827Monitoring in Erlang is not an indicator of process death/crashes, 1229Monitoring in Erlang is not an indicator of process death/crashes, in the
828as linking is (except linking is unreliable in Erlang). 1230same way as linking is (except linking is unreliable in Erlang).
829 1231
830In AEMP, you don't "look up" registered port names or send to named ports 1232In AEMP, you don't "look up" registered port names or send to named ports
831that might or might not be persistent. Instead, you normally spawn a port 1233that might or might not be persistent. Instead, you normally spawn a port
832on the remote node. The init function monitors the you, and you monitor 1234on the remote node. The init function monitors you, and you monitor the
833the remote port. Since both monitors are local to the node, they are much 1235remote port. Since both monitors are local to the node, they are much more
834more reliable. 1236reliable (no need for C<spawn_link>).
835 1237
836This also saves round-trips and avoids sending messages to the wrong port 1238This also saves round-trips and avoids sending messages to the wrong port
837(hard to do in Erlang). 1239(hard to do in Erlang).
838 1240
839=back 1241=back
840 1242
841=head1 RATIONALE 1243=head1 RATIONALE
842 1244
843=over 4 1245=over 4
844 1246
845=item Why strings for ports and noderefs, why not objects? 1247=item Why strings for port and node IDs, why not objects?
846 1248
847We considered "objects", but found that the actual number of methods 1249We considered "objects", but found that the actual number of methods
848thatc an be called are very low. Since port IDs and noderefs travel over 1250that can be called are quite low. Since port and node IDs travel over
849the network frequently, the serialising/deserialising would add lots of 1251the network frequently, the serialising/deserialising would add lots of
850overhead, as well as having to keep a proxy object. 1252overhead, as well as having to keep a proxy object everywhere.
851 1253
852Strings can easily be printed, easily serialised etc. and need no special 1254Strings can easily be printed, easily serialised etc. and need no special
853procedures to be "valid". 1255procedures to be "valid".
854 1256
855And a a miniport consists of a single closure stored in a global hash - it 1257And as a result, a port with just a default receiver consists of a single
856can't become much cheaper. 1258code reference stored in a global hash - it can't become much cheaper.
857 1259
858=item Why favour JSON, why not real serialising format such as Storable? 1260=item Why favour JSON, why not a real serialising format such as Storable?
859 1261
860In fact, any AnyEvent::MP node will happily accept Storable as framing 1262In fact, any AnyEvent::MP node will happily accept Storable as framing
861format, but currently there is no way to make a node use Storable by 1263format, but currently there is no way to make a node use Storable by
862default. 1264default (although all nodes will accept it).
863 1265
864The default framing protocol is JSON because a) JSON::XS is many times 1266The default framing protocol is JSON because a) JSON::XS is many times
865faster for small messages and b) most importantly, after years of 1267faster for small messages and b) most importantly, after years of
866experience we found that object serialisation is causing more problems 1268experience we found that object serialisation is causing more problems
867than it gains: Just like function calls, objects simply do not travel 1269than it solves: Just like function calls, objects simply do not travel
868easily over the network, mostly because they will always be a copy, so you 1270easily over the network, mostly because they will always be a copy, so you
869always have to re-think your design. 1271always have to re-think your design.
870 1272
871Keeping your messages simple, concentrating on data structures rather than 1273Keeping your messages simple, concentrating on data structures rather than
872objects, will keep your messages clean, tidy and efficient. 1274objects, will keep your messages clean, tidy and efficient.
873 1275
874=back 1276=back
875 1277
1278=head1 PORTING FROM AnyEvent::MP VERSION 1.X
1279
1280AEMP version 2 has a few major incompatible changes compared to version 1:
1281
1282=over 4
1283
1284=item AnyEvent::MP::Global no longer has group management functions.
1285
1286At least not officially - the grp_* functions are still exported and might
1287work, but they will be removed in some later release.
1288
1289AnyEvent::MP now comes with a distributed database that is more
1290powerful. Its database families map closely to port groups, but the API
1291has changed (the functions are also now exported by AnyEvent::MP). Here is
1292a rough porting guide:
1293
1294 grp_reg $group, $port # old
1295 db_reg $group, $port # new
1296
1297 $list = grp_get $group # old
1298 db_keys $group, sub { my $list = shift } # new
1299
1300 grp_mon $group, $cb->(\@ports, $add, $del) # old
1301 db_mon $group, $cb->(\%ports, $add, $change, $del) # new
1302
1303C<grp_reg> is a no-brainer (just replace by C<db_reg>), but C<grp_get> is
1304no longer instant, because the local node might not have a copy of the
1305group. You can either modify your code to allow for a callback, or use
1306C<db_mon> to keep an updated copy of the group:
1307
1308 my $local_group_copy;
1309 db_mon $group => sub { $local_group_copy = $_[0] };
1310
1311 # now "keys %$local_group_copy" always returns the most up-to-date
1312 # list of ports in the group.
1313
1314C<grp_mon> can be replaced by C<db_mon> with minor changes - C<db_mon>
1315passes a hash as first argument, and an extra C<$chg> argument that can be
1316ignored:
1317
1318 db_mon $group => sub {
1319 my ($ports, $add, $chg, $del) = @_;
1320 $ports = [keys %$ports];
1321
1322 # now $ports, $add and $del are the same as
1323 # were originally passed by grp_mon.
1324 ...
1325 };
1326
1327=item Nodes not longer connect to all other nodes.
1328
1329In AEMP 1.x, every node automatically loads the L<AnyEvent::MP::Global>
1330module, which in turn would create connections to all other nodes in the
1331network (helped by the seed nodes).
1332
1333In version 2.x, global nodes still connect to all other global nodes, but
1334other nodes don't - now every node either is a global node itself, or
1335attaches itself to another global node.
1336
1337If a node isn't a global node itself, then it attaches itself to one
1338of its seed nodes. If that seed node isn't a global node yet, it will
1339automatically be upgraded to a global node.
1340
1341So in many cases, nothing needs to be changed - one just has to make sure
1342that all seed nodes are meshed together with the other seed nodes (as with
1343AEMP 1.x), and other nodes specify them as seed nodes. This is most easily
1344achieved by specifying the same set of seed nodes for all nodes in the
1345network.
1346
1347Not opening a connection to every other node is usually an advantage,
1348except when you need the lower latency of an already established
1349connection. To ensure a node establishes a connection to another node,
1350you can monitor the node port (C<mon $node, ...>), which will attempt to
1351create the connection (and notify you when the connection fails).
1352
1353=item Listener-less nodes (nodes without binds) are gone.
1354
1355And are not coming back, at least not in their old form. If no C<binds>
1356are specified for a node, AnyEvent::MP assumes a default of C<*:*>.
1357
1358There are vague plans to implement some form of routing domains, which
1359might or might not bring back listener-less nodes, but don't count on it.
1360
1361The fact that most connections are now optional somewhat mitigates this,
1362as a node can be effectively unreachable from the outside without any
1363problems, as long as it isn't a global node and only reaches out to other
1364nodes (as opposed to being contacted from other nodes).
1365
1366=item $AnyEvent::MP::Kernel::WARN has gone.
1367
1368AnyEvent has acquired a logging framework (L<AnyEvent::Log>), and AEMP now
1369uses this, and so should your programs.
1370
1371Every module now documents what kinds of messages it generates, with
1372AnyEvent::MP acting as a catch all.
1373
1374On the positive side, this means that instead of setting
1375C<PERL_ANYEVENT_MP_WARNLEVEL>, you can get away by setting C<AE_VERBOSE> -
1376much less to type.
1377
1378=back
1379
1380=head1 LOGGING
1381
1382AnyEvent::MP does not normally log anything by itself, but since it is the
1383root of the contetx hierarchy for AnyEvent::MP modules, it will receive
1384all log messages by submodules.
1385
876=head1 SEE ALSO 1386=head1 SEE ALSO
1387
1388L<AnyEvent::MP::Intro> - a gentle introduction.
1389
1390L<AnyEvent::MP::Kernel> - more, lower-level, stuff.
1391
1392L<AnyEvent::MP::Global> - network maintenance and port groups, to find
1393your applications.
1394
1395L<AnyEvent::MP::DataConn> - establish data connections between nodes.
1396
1397L<AnyEvent::MP::LogCatcher> - simple service to display log messages from
1398all nodes.
877 1399
878L<AnyEvent>. 1400L<AnyEvent>.
879 1401
880=head1 AUTHOR 1402=head1 AUTHOR
881 1403

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines