--- AnyEvent-MP/MP.pm 2012/02/29 18:44:59 1.122 +++ AnyEvent-MP/MP.pm 2021/10/23 03:35:49 1.156 @@ -37,9 +37,9 @@ kil $port, my_error => "everything is broken"; # error kill # monitoring - mon $localport, $cb->(@msg) # callback is invoked on death - mon $localport, $otherport # kill otherport on abnormal death - mon $localport, $otherport, @msg # send message on death + mon $port, $cb->(@msg) # callback is invoked on death + mon $port, $localport # kill localport on abnormal death + mon $port, $localport, @msg # send message on death # temporarily execute code in port context peval $port, sub { die "kill the port!" }; @@ -49,13 +49,18 @@ die "kill the port, delayed"; }; -=head1 CURRENT STATUS + # distributed database - modification + db_set $family => $subkey [=> $value] # add a subkey + db_del $family => $subkey... # delete one or more subkeys + db_reg $family => $port [=> $value] # register a port + + # distributed database - queries + db_family $family => $cb->(\%familyhash) + db_keys $family => $cb->(\@keys) + db_values $family => $cb->(\@values) - bin/aemp - stable. - AnyEvent::MP - stable API, should work. - AnyEvent::MP::Intro - explains most concepts. - AnyEvent::MP::Kernel - mostly stable API. - AnyEvent::MP::Global - stable API. + # distributed database - monitoring a family + db_mon $family => $cb->(\%familyhash, \@added, \@changed, \@deleted) =head1 DESCRIPTION @@ -73,19 +78,20 @@ =item port -Not to be confused with a TCP port, a "port" is something you can send +Not to be confused with TCP ports, a "port" is something you can send messages to (with the C function). Ports allow you to register C handlers that can match all or just some messages. Messages send to ports will not be queued, regardless of -anything was listening for them or not. +whether anything was listening for them or not. Ports are represented by (printable) strings called "port IDs". =item port ID - C -A port ID is the concatenation of a node ID, a hash-mark (C<#>) as -separator, and a port name (a printable string of unspecified format). +A port ID is the concatenation of a node ID, a hash-mark (C<#>) +as separator, and a port name (a printable string of unspecified +format created by AnyEvent::MP). =item node @@ -114,7 +120,7 @@ Currently, only standard C specifications can be used, which specify TCP ports to listen on. So a bind is basically just a tcp socket -in listening mode thta accepts conenctions form other nodes. +in listening mode that accepts connections from other nodes. =item seed nodes @@ -124,13 +130,13 @@ Seed nodes themselves are not special - they are seed nodes only because some other node I them as such, but any node can be used as seed -node for other nodes, and eahc node cna use a different set of seed nodes. +node for other nodes, and eahc node can use a different set of seed nodes. In addition to discovering the network, seed nodes are also used to -maintain the network - all nodes using the same seed node form are part of -the same network. If a network is split into multiple subnets because e.g. -the network link between the parts goes down, then using the same seed -nodes for all nodes ensures that eventually the subnets get merged again. +maintain the network - all nodes using the same seed node are part of the +same network. If a network is split into multiple subnets because e.g. the +network link between the parts goes down, then using the same seed nodes +for all nodes ensures that eventually the subnets get merged again. Seed nodes are expected to be long-running, and at least one seed node should always be available. They should also be relatively responsive - a @@ -164,7 +170,7 @@ node and tries to keep connections to all other nodes. So while it can make sense to make every node "global" in small networks, it usually makes sense to only make seed nodes into global nodes in large networks (nodes -keep connections to seed nodes and global nodes, so makign them the same +keep connections to seed nodes and global nodes, so making them the same reduces overhead). =back @@ -179,23 +185,43 @@ use AnyEvent::MP::Config (); use AnyEvent::MP::Kernel; -use AnyEvent::MP::Kernel qw(%NODE %PORT %PORT_DATA $UNIQ $RUNIQ $ID); +use AnyEvent::MP::Kernel qw( + %NODE %PORT %PORT_DATA $UNIQ $RUNIQ $ID + add_node load_func + + NODE $NODE + configure + node_of port_is_local + snd kil + db_set db_del + db_mon db_family db_keys db_values +); use common::sense; use Carp (); -use AE (); +use AnyEvent (); +use Guard (); use base "Exporter"; -our $VERSION = $AnyEvent::MP::Config::VERSION; +our $VERSION = '2.02'; # also in MP/Config.pm our @EXPORT = qw( - NODE $NODE *SELF node_of after configure - snd rcv mon mon_guard kil psub peval spawn cal - port + + NODE $NODE + *SELF + + node_of port_is_local + + snd kil + port rcv mon mon_guard psub peval spawn cal + db_set db_del db_reg + db_mon db_family db_keys db_values + + after ); our $SELF; @@ -216,6 +242,10 @@ Extracts and returns the node ID from a port ID or a node ID. +=item $is_local = port_is_local $port + +Returns true iff the port is a local port. + =item configure $profile, key => value... =item configure key => value... @@ -229,14 +259,14 @@ never) before calling other AnyEvent::MP functions. The key/value pairs are basically the same ones as documented for the -F command line utility (sans the set/del prefix), with two additions: +F command line utility (sans the set/del prefix), with these additions: =over 4 =item norc => $boolean (default false) If true, then the rc file (e.g. F<~/.perl-anyevent-mp>) will I -be consulted - all configuraiton options must be specified in the +be consulted - all configuration options must be specified in the C call. =item force => $boolean (default false) @@ -270,16 +300,19 @@ If the profile specifies a node ID, then this will become the node ID of this process. If not, then the profile name will be used as node ID, with -a slash (C) attached. +a unique randoms tring (C) appended. -If the node ID (or profile name) ends with a slash (C), then a random -string is appended to make it unique. +The node ID can contain some C<%> sequences that are expanded: C<%n> +is expanded to the local nodename, C<%u> is replaced by a random +string to make the node unique. For example, the F commandline +utility uses C as nodename, which might expand to +C. =item step 2, bind listener sockets The next step is to look up the binds in the profile, followed by binding aemp protocol listeners on all binds specified (it is possible and valid -to have no binds, meaning that the node cannot be contacted form the +to have no binds, meaning that the node cannot be contacted from the outside. This means the node cannot talk to other nodes that also have no binds, but it can still talk to all "normal" nodes). @@ -300,10 +333,10 @@ configure -Example: become an anonymous node. This form is often used for commandline -clients. +Example: become a semi-anonymous node. This form is often used for +commandline clients. - configure nodeid => "anon/"; + configure nodeid => "myscript/%n/%u"; Example: configure a node using a profile called seed, which is suitable for a seed node as it binds on all local addresses on a fixed port (4040, @@ -385,15 +418,16 @@ sub rcv($@); -sub _kilme { - die "received message on port without callback"; -} +my $KILME = sub { + (my $tag = substr $_[0], 0, 30) =~ s/([^\x20-\x7e])/./g; + kil $SELF, unhandled_message => "no callback found for message '$tag'"; +}; sub port(;&) { - my $id = "$UNIQ." . ++$ID; + my $id = $UNIQ . ++$ID; my $port = "$NODE#$id"; - rcv $port, shift || \&_kilme; + rcv $port, shift || $KILME; $port } @@ -408,7 +442,7 @@ executing the callback. Runtime errors during callback execution will result in the port being Ced. -The default callback received all messages not matched by a more specific +The default callback receives all messages not matched by a more specific C match. =item rcv $local_port, tag => $callback->(@msg_without_tag), ... @@ -453,7 +487,7 @@ my $port = shift; my ($nodeid, $portid) = split /#/, $port, 2; - $NODE{$nodeid} == $NODE{""} + $nodeid eq $NODE or Carp::croak "$port: rcv can only be called on local ports, caught"; while (@_) { @@ -506,8 +540,8 @@ =item peval $port, $coderef[, @args] -Evaluates the given C<$codref> within the contetx of C<$port>, that is, -when the code throews an exception the C<$port> will be killed. +Evaluates the given C<$codref> within the context of C<$port>, that is, +when the code throws an exception the C<$port> will be killed. Any remaining args will be passed to the callback. Any return values will be returned to the caller. @@ -582,43 +616,51 @@ } } -=item $guard = mon $port, $cb->(@reason) # call $cb when $port dies - =item $guard = mon $port, $rcvport # kill $rcvport when $port dies =item $guard = mon $port # kill $SELF when $port dies +=item $guard = mon $port, $cb->(@reason) # call $cb when $port dies + =item $guard = mon $port, $rcvport, @msg # send a message when $port dies Monitor the given port and do something when the port is killed or messages to it were lost, and optionally return a guard that can be used to stop monitoring again. -In the first form (callback), the callback is simply called with any -number of C<@reason> elements (no @reason means that the port was deleted -"normally"). Note also that I<< the callback B never die >>, so use -C if unsure. +The first two forms distinguish between "normal" and "abnormal" kil's: -In the second form (another port given), the other port (C<$rcvport>) -will be C'ed with C<@reason>, if a @reason was specified, i.e. on -"normal" kils nothing happens, while under all other conditions, the other -port is killed with the same reason. +In the first form (another port given), if the C<$port> is C'ed with +a non-empty reason, the other port (C<$rcvport>) will be kil'ed with the +same reason. That is, on "normal" kil's nothing happens, while under all +other conditions, the other port is killed with the same reason. -The third form (kill self) is the same as the second form, except that +The second form (kill self) is the same as the first form, except that C<$rvport> defaults to C<$SELF>. -In the last form (message), a message of the form C<@msg, @reason> will be -C. +The remaining forms don't distinguish between "normal" and "abnormal" kil's +- it's up to the callback or receiver to check whether the C<@reason> is +empty and act accordingly. -Monitoring-actions are one-shot: once messages are lost (and a monitoring -alert was raised), they are removed and will not trigger again. +In the third form (callback), the callback is simply called with any +number of C<@reason> elements (empty @reason means that the port was deleted +"normally"). Note also that I<< the callback B never die >>, so use +C if unsure. -As a rule of thumb, monitoring requests should always monitor a port from -a local port (or callback). The reason is that kill messages might get -lost, just like any other message. Another less obvious reason is that -even monitoring requests can get lost (for example, when the connection -to the other node goes down permanently). When monitoring a port locally -these problems do not exist. +In the last form (message), a message of the form C<$rcvport, @msg, +@reason> will be C. + +Monitoring-actions are one-shot: once messages are lost (and a monitoring +alert was raised), they are removed and will not trigger again, even if it +turns out that the port is still alive (but monitoring actions added after +that will again trigger). + +As a rule of thumb, monitoring requests should always monitor a remote +port locally (using a local C<$rcvport> or a callback). The reason is that +kill messages might get lost, just like any other message. Another less +obvious reason is that even monitoring requests can get lost (for example, +when the connection to the other node goes down permanently). When +monitoring a port locally these problems do not exist. C effectively guarantees that, in the absence of hardware failures, after starting the monitor, either all messages sent to the port will @@ -673,7 +715,7 @@ $node->monitor ($port, $cb); defined wantarray - and ($cb += 0, AnyEvent::Util::guard { $node->unmonitor ($port, $cb) }) + and ($cb += 0, Guard::guard { $node->unmonitor ($port, $cb) }) } =item $guard = mon_guard $port, $ref, $ref... @@ -719,7 +761,17 @@ Transport/communication errors are reported as C<< transport_error => $message >>. -=cut +Common idioms: + + # silently remove yourself, do not kill linked ports + kil $SELF; + + # report a failure in some detail + kil $SELF, failure_mode_1 => "it failed with too high temperature"; + + # do not waste much time with killing, just die when something goes wrong + open my $fh, " with the -given contents (C<@msg>), but adds a reply port to the message. +given contents (C<@msg>), but appends a reply port to the message. The reply port is created temporarily just for the purpose of receiving the reply, and will be Ced when no longer needed. @@ -876,6 +930,188 @@ =back +=head1 DISTRIBUTED DATABASE + +AnyEvent::MP comes with a simple distributed database. The database will +be mirrored asynchronously on all global nodes. Other nodes bind to one +of the global nodes for their needs. Every node has a "local database" +which contains all the values that are set locally. All local databases +are merged together to form the global database, which can be queried. + +The database structure is that of a two-level hash - the database hash +contains hashes which contain values, similarly to a perl hash of hashes, +i.e.: + + $DATABASE{$family}{$subkey} = $value + +The top level hash key is called "family", and the second-level hash key +is called "subkey" or simply "key". + +The family must be alphanumeric, i.e. start with a letter and consist +of letters, digits, underscores and colons (C<[A-Za-z][A-Za-z0-9_:]*>, +pretty much like Perl module names. + +As the family namespace is global, it is recommended to prefix family names +with the name of the application or module using it. + +The subkeys must be non-empty strings, with no further restrictions. + +The values should preferably be strings, but other perl scalars should +work as well (such as C, arrays and hashes). + +Every database entry is owned by one node - adding the same family/subkey +combination on multiple nodes will not cause discomfort for AnyEvent::MP, +but the result might be nondeterministic, i.e. the key might have +different values on different nodes. + +Different subkeys in the same family can be owned by different nodes +without problems, and in fact, this is the common method to create worker +pools. For example, a worker port for image scaling might do this: + + db_set my_image_scalers => $port; # value not used + +And clients looking for an image scaler will want to get the +C keys from time to time: + + db_keys my_image_scalers => sub { + @ports = @{ $_[0] }; + }; + +Or better yet, they want to monitor the database family, so they always +have a reasonable up-to-date copy: + + db_mon my_image_scalers => sub { + @ports = keys %{ $_[0] }; + }; + +In general, you can set or delete single subkeys, but query and monitor +whole families only. + +If you feel the need to monitor or query a single subkey, try giving it +it's own family. + +=over + +=item $guard = db_set $family => $subkey [=> $value] + +Sets (or replaces) a key to the database - if C<$value> is omitted, +C is used instead. + +When called in non-void context, C returns a guard that +automatically calls C when it is destroyed. + +=item db_del $family => $subkey... + +Deletes one or more subkeys from the database family. + +=item $guard = db_reg $family => $port => $value + +=item $guard = db_reg $family => $port + +=item $guard = db_reg $family + +Registers a port in the given family and optionally returns a guard to +remove it. + +This function basically does the same as: + + db_set $family => $port => $value + +Except that the port is monitored and automatically removed from the +database family when it is kil'ed. + +If C<$value> is missing, C is used. If C<$port> is missing, then +C<$SELF> is used. + +This function is most useful to register a port in some port group (which +is just another name for a database family), and have it removed when the +port is gone. This works best when the port is a local port. + +=cut + +sub db_reg($$;$) { + my $family = shift; + my $port = @_ ? shift : $SELF; + + my $clr = sub { db_del $family => $port }; + mon $port, $clr; + + db_set $family => $port => $_[0]; + + defined wantarray + and &Guard::guard ($clr) +} + +=item db_family $family => $cb->(\%familyhash) + +Queries the named database C<$family> and call the callback with the +family represented as a hash. You can keep and freely modify the hash. + +=item db_keys $family => $cb->(\@keys) + +Same as C, except it only queries the family I and passes +them as array reference to the callback. + +=item db_values $family => $cb->(\@values) + +Same as C, except it only queries the family I and passes them +as array reference to the callback. + +=item $guard = db_mon $family => $cb->(\%familyhash, \@added, \@changed, \@deleted) + +Creates a monitor on the given database family. Each time a key is +set or is deleted the callback is called with a hash containing the +database family and three lists of added, changed and deleted subkeys, +respectively. If no keys have changed then the array reference might be +C or even missing. + +If not called in void context, a guard object is returned that, when +destroyed, stops the monitor. + +The family hash reference and the key arrays belong to AnyEvent::MP and +B by the callback. When in doubt, make a +copy. + +As soon as possible after the monitoring starts, the callback will be +called with the intiial contents of the family, even if it is empty, +i.e. there will always be a timely call to the callback with the current +contents. + +It is possible that the callback is called with a change event even though +the subkey is already present and the value has not changed. + +The monitoring stops when the guard object is destroyed. + +Example: on every change to the family "mygroup", print out all keys. + + my $guard = db_mon mygroup => sub { + my ($family, $a, $c, $d) = @_; + print "mygroup members: ", (join " ", keys %$family), "\n"; + }; + +Exmaple: wait until the family "My::Module::workers" is non-empty. + + my $guard; $guard = db_mon My::Module::workers => sub { + my ($family, $a, $c, $d) = @_; + return unless %$family; + undef $guard; + print "My::Module::workers now nonempty\n"; + }; + +Example: print all changes to the family "AnyEvent::Fantasy::Module". + + my $guard = db_mon AnyEvent::Fantasy::Module => sub { + my ($family, $a, $c, $d) = @_; + + print "+$_=$family->{$_}\n" for @$a; + print "*$_=$family->{$_}\n" for @$c; + print "-$_=$family->{$_}\n" for @$d; + }; + +=cut + +=back + =head1 AnyEvent::MP vs. Distributed Erlang AnyEvent::MP got lots of its ideas from distributed Erlang (Erlang node @@ -925,13 +1161,13 @@ This is not a philosophical difference, but simply stems from AnyEvent::MP being event-based, while Erlang is process-based. -You cna have a look at L for a more Erlang-like process model on +You can have a look at L for a more Erlang-like process model on top of AEMP and Coro threads. =item * Erlang sends are synchronous, AEMP sends are asynchronous. Sending messages in Erlang is synchronous and blocks the process until -a conenction has been established and the message sent (and so does not +a connection has been established and the message sent (and so does not need a queue that can overflow). AEMP sends return immediately, connection establishment is handled in the background. @@ -1039,6 +1275,114 @@ =back +=head1 PORTING FROM AnyEvent::MP VERSION 1.X + +AEMP version 2 has a few major incompatible changes compared to version 1: + +=over 4 + +=item AnyEvent::MP::Global no longer has group management functions. + +At least not officially - the grp_* functions are still exported and might +work, but they will be removed in some later release. + +AnyEvent::MP now comes with a distributed database that is more +powerful. Its database families map closely to port groups, but the API +has changed (the functions are also now exported by AnyEvent::MP). Here is +a rough porting guide: + + grp_reg $group, $port # old + db_reg $group, $port # new + + $list = grp_get $group # old + db_keys $group, sub { my $list = shift } # new + + grp_mon $group, $cb->(\@ports, $add, $del) # old + db_mon $group, $cb->(\%ports, $add, $change, $del) # new + +C is a no-brainer (just replace by C), but C is +no longer instant, because the local node might not have a copy of the +group. You can either modify your code to allow for a callback, or use +C to keep an updated copy of the group: + + my $local_group_copy; + db_mon $group => sub { $local_group_copy = $_[0] }; + + # now "keys %$local_group_copy" always returns the most up-to-date + # list of ports in the group. + +C can be replaced by C with minor changes - C +passes a hash as first argument, and an extra C<$chg> argument that can be +ignored: + + db_mon $group => sub { + my ($ports, $add, $chg, $del) = @_; + $ports = [keys %$ports]; + + # now $ports, $add and $del are the same as + # were originally passed by grp_mon. + ... + }; + +=item Nodes not longer connect to all other nodes. + +In AEMP 1.x, every node automatically loads the L +module, which in turn would create connections to all other nodes in the +network (helped by the seed nodes). + +In version 2.x, global nodes still connect to all other global nodes, but +other nodes don't - now every node either is a global node itself, or +attaches itself to another global node. + +If a node isn't a global node itself, then it attaches itself to one +of its seed nodes. If that seed node isn't a global node yet, it will +automatically be upgraded to a global node. + +So in many cases, nothing needs to be changed - one just has to make sure +that all seed nodes are meshed together with the other seed nodes (as with +AEMP 1.x), and other nodes specify them as seed nodes. This is most easily +achieved by specifying the same set of seed nodes for all nodes in the +network. + +Not opening a connection to every other node is usually an advantage, +except when you need the lower latency of an already established +connection. To ensure a node establishes a connection to another node, +you can monitor the node port (C), which will attempt to +create the connection (and notify you when the connection fails). + +=item Listener-less nodes (nodes without binds) are gone. + +And are not coming back, at least not in their old form. If no C +are specified for a node, AnyEvent::MP assumes a default of C<*:*>. + +There are vague plans to implement some form of routing domains, which +might or might not bring back listener-less nodes, but don't count on it. + +The fact that most connections are now optional somewhat mitigates this, +as a node can be effectively unreachable from the outside without any +problems, as long as it isn't a global node and only reaches out to other +nodes (as opposed to being contacted from other nodes). + +=item $AnyEvent::MP::Kernel::WARN has gone. + +AnyEvent has acquired a logging framework (L), and AEMP now +uses this, and so should your programs. + +Every module now documents what kinds of messages it generates, with +AnyEvent::MP acting as a catch all. + +On the positive side, this means that instead of setting +C, you can get away by setting C - +much less to type. + +=back + +=head1 LOGGING + +AnyEvent::MP does not normally log anything by itself, but since it is the +root of the context hierarchy for AnyEvent::MP modules, it will receive +all log messages by submodules. + =head1 SEE ALSO L - a gentle introduction.