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

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines