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.56 by root, Sat Aug 15 04:12:38 2009 UTC vs.
Revision 1.151 by root, Wed Aug 17 19:45:36 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
202Note that slave nodes cannot change their name, and consequently, their
203master, so if the master goes down, the slave node will not function well
204anymore until it can re-establish conenciton to its master. This makes
205slave nodes unsuitable for long-term nodes or fault-tolerant networks.
206 278
207=back 279=back
208 280
209This function will block until all nodes have been resolved and, for slave
210nodes, until it has successfully established a connection to a master
211server.
212
213All the seednodes will also be specially marked to automatically retry
214connecting to them infinitely.
215
216Example: become a public node listening on the guessed noderef, or the one
217specified via C<aemp> for the current node. This should be the most common
218form of invocation for "daemon"-type nodes.
219
220 initialise_node;
221
222Example: become a slave node to any of the the seednodes specified via
223C<aemp>. This form is often used for commandline clients.
224
225 initialise_node "slave/";
226
227Example: become a slave node to any of the specified master servers. This
228form is also often used for commandline clients.
229
230 initialise_node "slave/", "master1", "192.168.13.17", "mp.example.net";
231
232Example: become a public node, and try to contact some well-known master
233servers to become part of the network.
234
235 initialise_node undef, "master1", "master2";
236
237Example: become a public node listening on port C<4041>.
238
239 initialise_node 4041;
240
241Example: become a public node, only visible on localhost port 4044.
242
243 initialise_node "localhost:4044";
244
245=item $cv = resolve_node $noderef
246
247Takes an unresolved node reference that may contain hostnames and
248abbreviated IDs, resolves all of them and returns a resolved node
249reference.
250
251In addition to C<address:port> pairs allowed in resolved noderefs, the
252following forms are supported:
253
254=over 4 281=over 4
255 282
256=item the empty string 283=item step 1, gathering configuration from profiles
257 284
258An 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
259specified. 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.
260 289
261=item naked port numbers (e.g. C<1234>) 290The profile data is then gathered as follows:
262 291
263These are resolved by prepending the local nodename and a colon, to be 292First, all remaining key => value pairs (all of which are conveniently
264further 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).
265 297
266=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.
267 301
268These 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
269looking 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
270specified. 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.
271 329
272=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)"
273 357
274=item $SELF 358=item $SELF
275 359
276Contains 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>
277blocks. 361blocks.
278 362
279=item SELF, %SELF, @SELF... 363=item *SELF, SELF, %SELF, @SELF...
280 364
281Due 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
282just 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
283module, but only C<$SELF> is currently used. 367module, but only C<$SELF> is currently used.
284 368
285=item snd $port, type => @data 369=item snd $port, type => @data
286 370
287=item snd $port, @msg 371=item snd $port, @msg
288 372
289Send 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
290a local or a remote port, and must be a port ID. 374local or a remote port, and must be a port ID.
291 375
292While 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
293string 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
294type 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.
295 380
296The message data effectively becomes read-only after a call to this 381The message data logically becomes read-only after a call to this
297function: modifying any argument is not allowed and can cause many 382function: modifying any argument (or values referenced by them) is
298problems. 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.
299 387
300The 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
301JSON is used, then only strings, numbers and arrays and hashes consisting 389JSON is used, then only strings, numbers and arrays and hashes consisting
302of those are allowed (no objects). When Storable is used, then anything 390of those are allowed (no objects). When Storable is used, then anything
303that Storable can serialise and deserialise is allowed, and for the local 391that Storable can serialise and deserialise is allowed, and for the local
304node, anything can be passed. 392node, anything can be passed. Best rely only on the common denominator of
393these.
305 394
306=item $local_port = port 395=item $local_port = port
307 396
308Create 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
309no callbacks set and will throw an error when it receives messages. 398no callbacks set and will throw an error when it receives messages.
328 417
329=cut 418=cut
330 419
331sub rcv($@); 420sub rcv($@);
332 421
333sub _kilme { 422my $KILME = sub {
334 die "received message on port without callback"; 423 (my $tag = substr $_[0], 0, 30) =~ s/([^\x20-\x7e])/./g;
335} 424 kil $SELF, unhandled_message => "no callback found for message '$tag'";
425};
336 426
337sub port(;&) { 427sub port(;&) {
338 my $id = "$UNIQ." . $ID++; 428 my $id = $UNIQ . ++$ID;
339 my $port = "$NODE#$id"; 429 my $port = "$NODE#$id";
340 430
341 rcv $port, shift || \&_kilme; 431 rcv $port, shift || $KILME;
342 432
343 $port 433 $port
344} 434}
345 435
346=item rcv $local_port, $callback->(@msg) 436=item rcv $local_port, $callback->(@msg)
351 441
352The global C<$SELF> (exported by this module) contains C<$port> while 442The global C<$SELF> (exported by this module) contains C<$port> while
353executing the callback. Runtime errors during callback execution will 443executing the callback. Runtime errors during callback execution will
354result in the port being C<kil>ed. 444result in the port being C<kil>ed.
355 445
356The default callback received all messages not matched by a more specific 446The default callback receives all messages not matched by a more specific
357C<tag> match. 447C<tag> match.
358 448
359=item rcv $local_port, tag => $callback->(@msg_without_tag), ... 449=item rcv $local_port, tag => $callback->(@msg_without_tag), ...
360 450
361Register (or replace) callbacks to be called on messages starting with the 451Register (or replace) callbacks to be called on messages starting with the
382 msg1 => sub { ... }, 472 msg1 => sub { ... },
383 ... 473 ...
384 ; 474 ;
385 475
386Example: temporarily register a rcv callback for a tag matching some port 476Example: temporarily register a rcv callback for a tag matching some port
387(e.g. for a rpc reply) and unregister it after a message was received. 477(e.g. for an rpc reply) and unregister it after a message was received.
388 478
389 rcv $port, $otherport => sub { 479 rcv $port, $otherport => sub {
390 my @reply = @_; 480 my @reply = @_;
391 481
392 rcv $SELF, $otherport; 482 rcv $SELF, $otherport;
394 484
395=cut 485=cut
396 486
397sub rcv($@) { 487sub rcv($@) {
398 my $port = shift; 488 my $port = shift;
399 my ($noderef, $portid) = split /#/, $port, 2; 489 my ($nodeid, $portid) = split /#/, $port, 2;
400 490
401 ($NODE{$noderef} || add_node $noderef) == $NODE{""} 491 $nodeid eq $NODE
402 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";
403 493
404 while (@_) { 494 while (@_) {
405 if (ref $_[0]) { 495 if (ref $_[0]) {
406 if (my $self = $PORT_DATA{$portid}) { 496 if (my $self = $PORT_DATA{$portid}) {
407 "AnyEvent::MP::Port" eq ref $self 497 "AnyEvent::MP::Port" eq ref $self
408 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";
409 499
410 $self->[2] = shift; 500 $self->[0] = shift;
411 } else { 501 } else {
412 my $cb = shift; 502 my $cb = shift;
413 $PORT{$portid} = sub { 503 $PORT{$portid} = sub {
414 local $SELF = $port; 504 local $SELF = $port;
415 eval { &$cb }; _self_die if $@; 505 eval { &$cb }; _self_die if $@;
416 }; 506 };
417 } 507 }
418 } elsif (defined $_[0]) { 508 } elsif (defined $_[0]) {
419 my $self = $PORT_DATA{$portid} ||= do { 509 my $self = $PORT_DATA{$portid} ||= do {
420 my $self = bless [$PORT{$port} || sub { }, { }, $port], "AnyEvent::MP::Port"; 510 my $self = bless [$PORT{$portid} || sub { }, { }, $port], "AnyEvent::MP::Port";
421 511
422 $PORT{$portid} = sub { 512 $PORT{$portid} = sub {
423 local $SELF = $port; 513 local $SELF = $port;
424 514
425 if (my $cb = $self->[1]{$_[0]}) { 515 if (my $cb = $self->[1]{$_[0]}) {
447 } 537 }
448 538
449 $port 539 $port
450} 540}
451 541
542=item peval $port, $coderef[, @args]
543
544Evaluates the given C<$codref> within the context 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
452=item $closure = psub { BLOCK } 579=item $closure = psub { BLOCK }
453 580
454Remembers 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
455closure 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>
456callbacks, 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 }, @_ } >>.
457 587
458This is useful when you register callbacks from C<rcv> callbacks: 588This is useful when you register callbacks from C<rcv> callbacks:
459 589
460 rcv delayed_reply => sub { 590 rcv delayed_reply => sub {
461 my ($delay, @reply) = @_; 591 my ($delay, @reply) = @_;
485 $res 615 $res
486 } 616 }
487 } 617 }
488} 618}
489 619
490=item $guard = mon $port, $cb->(@reason) 620=item $guard = mon $port, $rcvport # kill $rcvport when $port dies
491 621
492=item $guard = mon $port, $rcvport 622=item $guard = mon $port # kill $SELF when $port dies
493 623
494=item $guard = mon $port 624=item $guard = mon $port, $cb->(@reason) # call $cb when $port dies
495 625
496=item $guard = mon $port, $rcvport, @msg 626=item $guard = mon $port, $rcvport, @msg # send a message when $port dies
497 627
498Monitor 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
499messages 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
500to stop monitoring again. 630to stop monitoring again.
501 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
502C<mon> effectively guarantees that, in the absence of hardware failures, 665C<mon> effectively guarantees that, in the absence of hardware failures,
503that after starting the monitor, either all messages sent to the port 666after starting the monitor, either all messages sent to the port will
504will arrive, or the monitoring action will be invoked after possible 667arrive, or the monitoring action will be invoked after possible message
505message loss has been detected. No messages will be lost "in between" 668loss has been detected. No messages will be lost "in between" (after
506(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
507port). After the monitoring action was invoked, further messages might get 670port). After the monitoring action was invoked, further messages might get
508delivered again. 671delivered again.
509 672
510In the first form (callback), the callback is simply called with any 673Inter-host-connection timeouts and monitoring depend on the transport
511number of C<@reason> elements (no @reason means that the port was deleted 674used. The only transport currently implemented is TCP, and AnyEvent::MP
512"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
513C<eval> if unsure. 676non-idle connection, and usually around two hours for idle connections).
514 677
515In the second form (another port given), the other port (C<$rcvport>) 678This means that monitoring is good for program errors and cleaning up
516will 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
517"normal" kils nothing happens, while under all other conditions, the other 680to ensure some maximum latency.
518port is killed with the same reason.
519
520The third form (kill self) is the same as the second form, except that
521C<$rvport> defaults to C<$SELF>.
522
523In the last form (message), a message of the form C<@msg, @reason> will be
524C<snd>.
525
526As a rule of thumb, monitoring requests should always monitor a port from
527a local port (or callback). The reason is that kill messages might get
528lost, just like any other message. Another less obvious reason is that
529even monitoring requests can get lost (for exmaple, when the connection
530to the other node goes down permanently). When monitoring a port locally
531these problems do not exist.
532 681
533Example: call a given callback when C<$port> is killed. 682Example: call a given callback when C<$port> is killed.
534 683
535 mon $port, sub { warn "port died because of <@_>\n" }; 684 mon $port, sub { warn "port died because of <@_>\n" };
536 685
543 mon $port, $self => "restart"; 692 mon $port, $self => "restart";
544 693
545=cut 694=cut
546 695
547sub mon { 696sub mon {
548 my ($noderef, $port) = split /#/, shift, 2; 697 my ($nodeid, $port) = split /#/, shift, 2;
549 698
550 my $node = $NODE{$noderef} || add_node $noderef; 699 my $node = $NODE{$nodeid} || add_node $nodeid;
551 700
552 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,';
553 702
554 unless (ref $cb) { 703 unless (ref $cb) {
555 if (@_) { 704 if (@_) {
564 } 713 }
565 714
566 $node->monitor ($port, $cb); 715 $node->monitor ($port, $cb);
567 716
568 defined wantarray 717 defined wantarray
569 and AnyEvent::Util::guard { $node->unmonitor ($port, $cb) } 718 and ($cb += 0, Guard::guard { $node->unmonitor ($port, $cb) })
570} 719}
571 720
572=item $guard = mon_guard $port, $ref, $ref... 721=item $guard = mon_guard $port, $ref, $ref...
573 722
574Monitors 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
575is killed, the references will be freed. 724is killed, the references will be freed.
576 725
577Optionally returns a guard that will stop the monitoring. 726Optionally returns a guard that will stop the monitoring.
578 727
579This 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
580want to free them when the port gets killed: 729want to free them when the port gets killed (note the use of C<psub>):
581 730
582 $port->rcv (start => sub { 731 $port->rcv (start => sub {
583 my $timer; $timer = mon_guard $port, AE::timer 1, 1, sub { 732 my $timer; $timer = mon_guard $port, AE::timer 1, 1, psub {
584 undef $timer if 0.9 < rand; 733 undef $timer if 0.9 < rand;
585 }); 734 });
586 }); 735 });
587 736
588=cut 737=cut
597 746
598=item kil $port[, @reason] 747=item kil $port[, @reason]
599 748
600Kill the specified port with the given C<@reason>. 749Kill the specified port with the given C<@reason>.
601 750
602If no C<@reason> is specified, then the port is killed "normally" (linked 751If no C<@reason> is specified, then the port is killed "normally" -
603ports 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.
604 754
605Otherwise, linked ports get killed with the same reason (second form of 755If a C<@reason> is specified, then linked ports (C<mon $mport, $lport>
606C<mon>, see below). 756form) get killed with the same reason.
607 757
608Runtime errors while evaluating C<rcv> callbacks or inside C<psub> blocks 758Runtime errors while evaluating C<rcv> callbacks or inside C<psub> blocks
609will be reported as reason C<< die => $@ >>. 759will be reported as reason C<< die => $@ >>.
610 760
611Transport/communication errors are reported as C<< transport_error => 761Transport/communication errors are reported as C<< transport_error =>
612$message >>. 762$message >>.
613 763
614=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: $!";
615 775
616=item $port = spawn $node, $initfunc[, @initdata] 776=item $port = spawn $node, $initfunc[, @initdata]
617 777
618Creates 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
619case it's the node where that port resides). 779case it's the node where that port resides).
620 780
621The 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
622permissible to immediately start sending messages or monitor the port. 782possible to immediately start sending messages or to monitor the port.
623 783
624After the port has been created, the init function is 784After the port has been created, the init function is called on the remote
625called. This function must be a fully-qualified function name 785node, in the same context as a C<rcv> callback. This function must be a
626(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
627program, use C<::name>. 787specify a function in the main program, use C<::name>.
628 788
629If 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>
630the 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.
631C<MyApp::Chat::Server>, C<MyApp::Chat>, C<MyApp>) until the function 791C<MyApp::Chat::Server>, C<MyApp::Chat>, C<MyApp>) until the function
632exists or it runs out of package names. 792exists or it runs out of package names.
633 793
634The 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
635object (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.
636 798
637A 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
638in the init function, monitor the original port. This two-way monitoring 800port, and in the remote init function, immediately monitor the passed
639ensures 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).
640 807
641Example: spawn a chat server port on C<$othernode>. 808Example: spawn a chat server port on C<$othernode>.
642 809
643 # this node, executed from within a port context: 810 # this node, executed from within a port context:
644 my $server = spawn $othernode, "MyApp::Chat::Server::connect", $SELF; 811 my $server = spawn $othernode, "MyApp::Chat::Server::connect", $SELF;
659 826
660sub _spawn { 827sub _spawn {
661 my $port = shift; 828 my $port = shift;
662 my $init = shift; 829 my $init = shift;
663 830
831 # rcv will create the actual port
664 local $SELF = "$NODE#$port"; 832 local $SELF = "$NODE#$port";
665 eval { 833 eval {
666 &{ load_func $init } 834 &{ load_func $init }
667 }; 835 };
668 _self_die if $@; 836 _self_die if $@;
669} 837}
670 838
671sub spawn(@) { 839sub spawn(@) {
672 my ($noderef, undef) = split /#/, shift, 2; 840 my ($nodeid, undef) = split /#/, shift, 2;
673 841
674 my $id = "$RUNIQ." . $ID++; 842 my $id = $RUNIQ . ++$ID;
675 843
676 $_[0] =~ /::/ 844 $_[0] =~ /::/
677 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";
678 846
679 snd_to_func $noderef, "AnyEvent::MP::_spawn" => $id, @_; 847 snd_to_func $nodeid, "AnyEvent::MP::_spawn" => $id, @_;
680 848
681 "$noderef#$id" 849 "$nodeid#$id"
682} 850}
683 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
684=back 931=back
685 932
686=head1 NODE MESSAGES 933=head1 DISTRIBUTED DATABASE
687 934
688Nodes understand the following messages sent to them. Many of them take 935AnyEvent::MP comes with a simple distributed database. The database will
689arguments called C<@reply>, which will simply be used to compose a reply 936be mirrored asynchronously on all global nodes. Other nodes bind to one
690message - 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"
691the 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.
692 940
693While 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.:
694 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
695=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.
696 1029
697=cut 1030=cut
698 1031
699=item lookup => $name, @reply 1032sub db_reg($$;$) {
1033 my $family = shift;
1034 my $port = @_ ? shift : $SELF;
700 1035
701Replies 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;
702 1038
703=item devnull => ... 1039 db_set $family => $port => $_[0];
704 1040
705Generic data sink/CPU heat conversion. 1041 defined wantarray
1042 and &Guard::guard ($clr)
1043}
706 1044
707=item relay => $port, @msg 1045=item db_family $family => $cb->(\%familyhash)
708 1046
709Simply 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.
710 1049
711=item eval => $string[ @reply] 1050=item db_keys $family => $cb->(\@keys)
712 1051
713Evaluates 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
714form C<@reply, $@, @evalres> is sent. 1053them as array reference to the callback.
715 1054
716Example: crash another node. 1055=item db_values $family => $cb->(\@values)
717 1056
718 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.
719 1059
720=item time => @reply 1060=item $guard = db_mon $family => $cb->(\%familyhash, \@added, \@changed, \@deleted)
721 1061
722Replies 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.
723 1067
724Example: 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
725C<timereply> message. 1069destroyed, stops the monitor.
726 1070
727 snd $NODE, time => $myport, timereply => 1, 2; 1071The family hash reference and the key arrays belong to AnyEvent::MP and
728 # => 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
729 1112
730=back 1113=back
731 1114
732=head1 AnyEvent::MP vs. Distributed Erlang 1115=head1 AnyEvent::MP vs. Distributed Erlang
733 1116
734AnyEvent::MP got lots of its ideas from distributed Erlang (Erlang node 1117AnyEvent::MP got lots of its ideas from distributed Erlang (Erlang node
735== 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
736programming techniques employed by Erlang apply to AnyEvent::MP. Here is a 1119programming techniques employed by Erlang apply to AnyEvent::MP. Here is a
737sample: 1120sample:
738 1121
739 http://www.Erlang.se/doc/programming_rules.shtml 1122 http://www.erlang.se/doc/programming_rules.shtml
740 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
741 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
742 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
743 1126
744Despite the similarities, there are also some important differences: 1127Despite the similarities, there are also some important differences:
745 1128
746=over 4 1129=over 4
747 1130
748=item * Node references contain the recipe on how to contact them. 1131=item * Node IDs are arbitrary strings in AEMP.
749 1132
750Erlang relies on special naming and DNS to work everywhere in the 1133Erlang relies on special naming and DNS to work everywhere in the same
751same 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
752convenience functionality. 1135configuration or DNS), and possibly the addresses of some seed nodes, but
753 1136will otherwise discover other nodes (and their IDs) itself.
754This means that AEMP requires a less tightly controlled environment at the
755cost of longer node references and a slightly higher management overhead.
756 1137
757=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
758uses "local ports are like remote ports". 1139uses "local ports are like remote ports".
759 1140
760The failure modes for local ports are quite different (runtime errors 1141The failure modes for local ports are quite different (runtime errors
769ports being the special case/exception, where transport errors cannot 1150ports being the special case/exception, where transport errors cannot
770occur. 1151occur.
771 1152
772=item * Erlang uses processes and a mailbox, AEMP does not queue. 1153=item * Erlang uses processes and a mailbox, AEMP does not queue.
773 1154
774Erlang uses processes that selectively receive messages, and therefore 1155Erlang uses processes that selectively receive messages out of order, and
775needs a queue. AEMP is event based, queuing messages would serve no 1156therefore needs a queue. AEMP is event based, queuing messages would serve
776useful purpose. For the same reason the pattern-matching abilities of 1157no useful purpose. For the same reason the pattern-matching abilities
777AnyEvent::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
778filter messages without dequeing them. 1159filter messages without dequeuing them.
779 1160
780(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.
781 1166
782=item * Erlang sends are synchronous, AEMP sends are asynchronous. 1167=item * Erlang sends are synchronous, AEMP sends are asynchronous.
783 1168
784Sending 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
785so does not need a queue that can overflow). AEMP sends are immediate, 1171need a queue that can overflow). AEMP sends return immediately, connection
786connection establishment is handled in the background. 1172establishment is handled in the background.
787 1173
788=item * Erlang suffers from silent message loss, AEMP does not. 1174=item * Erlang suffers from silent message loss, AEMP does not.
789 1175
790Erlang makes few guarantees on messages delivery - messages can get lost 1176Erlang implements few guarantees on messages delivery - messages can get
791without 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,
792and c, and the other side only receives messages a and c). 1178b, and c, and the other side only receives messages a and c).
793 1179
794AEMP 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
795holes in the message sequence. 1183no silent "holes" in the message sequence.
796 1184
797=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
798alive. 1186corrupted and even out-of-order messages in both Erlang and AEMP. AEMP
799 1187simply tries to work better in common error cases, such as when a network
800In Erlang it can happen that a monitored process is declared dead and 1188link goes down.
801linked processes get killed, but later it turns out that the process is
802still alive - and can receive messages.
803
804In AEMP, when port monitoring detects a port as dead, then that port will
805eventually be killed - it cannot happen that a node detects a port as dead
806and then later sends messages to it, finding it is still alive.
807 1189
808=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.
809 1191
810In 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
811known to other nodes for a completely different process, causing messages 1193process ID known to other nodes for a completely different process,
812destined for that process to end up in an unrelated process. 1194causing messages destined for that process to end up in an unrelated
1195process.
813 1196
814AEMP 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
815around in the network will not be sent to an unrelated port. 1198around in the network will not be sent to an unrelated port.
816 1199
817=item * Erlang uses unprotected connections, AEMP uses secure 1200=item * Erlang uses unprotected connections, AEMP uses secure
818authentication and can use TLS. 1201authentication and can use TLS.
819 1202
820AEMP can use a proven protocol - SSL/TLS - to protect connections and 1203AEMP can use a proven protocol - TLS - to protect connections and
821securely authenticate nodes. 1204securely authenticate nodes.
822 1205
823=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
824communications. 1207communications.
825 1208
826The AEMP protocol, unlike the Erlang protocol, supports both 1209The AEMP protocol, unlike the Erlang protocol, supports both programming
827language-independent text-only protocols (good for debugging) and binary, 1210language independent text-only protocols (good for debugging), and binary,
828language-specific serialisers (e.g. Storable). 1211language-specific serialisers (e.g. Storable). By default, unless TLS is
1212used, the protocol is actually completely text-based.
829 1213
830It has also been carefully designed to be implementable in other languages 1214It has also been carefully designed to be implementable in other languages
831with a minimum of work while gracefully degrading fucntionality to make the 1215with a minimum of work while gracefully degrading functionality to make the
832protocol simple. 1216protocol simple.
833 1217
834=item * AEMP has more flexible monitoring options than Erlang. 1218=item * AEMP has more flexible monitoring options than Erlang.
835 1219
836In 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
837or 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
838difficult to implement. Monitoring in AEMP is more flexible than in 1222difficult to implement.
839Erlang, as one can choose between automatic kill, exit message or callback 1223
840on 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.
841 1226
842=item * Erlang tries to hide remote/local connections, AEMP does not. 1227=item * Erlang tries to hide remote/local connections, AEMP does not.
843 1228
844Monitoring in Erlang is not an indicator of process death/crashes, 1229Monitoring in Erlang is not an indicator of process death/crashes, in the
845as linking is (except linking is unreliable in Erlang). 1230same way as linking is (except linking is unreliable in Erlang).
846 1231
847In 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
848that 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
849on 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
850the 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
851more reliable. 1236reliable (no need for C<spawn_link>).
852 1237
853This 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
854(hard to do in Erlang). 1239(hard to do in Erlang).
855 1240
856=back 1241=back
857 1242
858=head1 RATIONALE 1243=head1 RATIONALE
859 1244
860=over 4 1245=over 4
861 1246
862=item Why strings for ports and noderefs, why not objects? 1247=item Why strings for port and node IDs, why not objects?
863 1248
864We considered "objects", but found that the actual number of methods 1249We considered "objects", but found that the actual number of methods
865thatc 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
866the network frequently, the serialising/deserialising would add lots of 1251the network frequently, the serialising/deserialising would add lots of
867overhead, as well as having to keep a proxy object. 1252overhead, as well as having to keep a proxy object everywhere.
868 1253
869Strings can easily be printed, easily serialised etc. and need no special 1254Strings can easily be printed, easily serialised etc. and need no special
870procedures to be "valid". 1255procedures to be "valid".
871 1256
872And 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
873can't become much cheaper. 1258code reference stored in a global hash - it can't become much cheaper.
874 1259
875=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?
876 1261
877In fact, any AnyEvent::MP node will happily accept Storable as framing 1262In fact, any AnyEvent::MP node will happily accept Storable as framing
878format, 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
879default. 1264default (although all nodes will accept it).
880 1265
881The 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
882faster for small messages and b) most importantly, after years of 1267faster for small messages and b) most importantly, after years of
883experience we found that object serialisation is causing more problems 1268experience we found that object serialisation is causing more problems
884than it gains: Just like function calls, objects simply do not travel 1269than it solves: Just like function calls, objects simply do not travel
885easily 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
886always have to re-think your design. 1271always have to re-think your design.
887 1272
888Keeping your messages simple, concentrating on data structures rather than 1273Keeping your messages simple, concentrating on data structures rather than
889objects, will keep your messages clean, tidy and efficient. 1274objects, will keep your messages clean, tidy and efficient.
890 1275
891=back 1276=back
892 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 context hierarchy for AnyEvent::MP modules, it will receive
1384all log messages by submodules.
1385
893=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.
894 1399
895L<AnyEvent>. 1400L<AnyEvent>.
896 1401
897=head1 AUTHOR 1402=head1 AUTHOR
898 1403

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines