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.124 by root, Sat Mar 3 11:38:43 2012 UTC vs.
Revision 1.131 by root, Fri Mar 9 19:07:53 2012 UTC

… …
35 # destroy a port again 35 # destroy a port again
36 kil $port; # "normal" kill 36 kil $port; # "normal" kill
37 kil $port, my_error => "everything is broken"; # error kill 37 kil $port, my_error => "everything is broken"; # error kill
38 38
39 # monitoring 39 # monitoring
40 mon $localport, $cb->(@msg) # callback is invoked on death 40 mon $port, $cb->(@msg) # callback is invoked on death
41 mon $localport, $otherport # kill otherport on abnormal death 41 mon $port, $localport # kill localport on abnormal death
42 mon $localport, $otherport, @msg # send message on death 42 mon $port, $localport, @msg # send message on death
43 43
44 # temporarily execute code in port context 44 # temporarily execute code in port context
45 peval $port, sub { die "kill the port!" }; 45 peval $port, sub { die "kill the port!" };
46 46
47 # execute callbacks in $SELF port context 47 # execute callbacks in $SELF port context
… …
197 NODE $NODE *SELF node_of after 197 NODE $NODE *SELF node_of after
198 configure 198 configure
199 snd rcv mon mon_guard kil psub peval spawn cal 199 snd rcv mon mon_guard kil psub peval spawn cal
200 port 200 port
201 db_set db_del db_reg 201 db_set db_del db_reg
202 db_mon db_family db_keys db_values
202); 203);
203 204
204our $SELF; 205our $SELF;
205 206
206sub _self_die() { 207sub _self_die() {
… …
230 231
231This function configures a node - it must be called exactly once (or 232This function configures a node - it must be called exactly once (or
232never) before calling other AnyEvent::MP functions. 233never) before calling other AnyEvent::MP functions.
233 234
234The key/value pairs are basically the same ones as documented for the 235The key/value pairs are basically the same ones as documented for the
235F<aemp> command line utility (sans the set/del prefix), with two additions: 236F<aemp> command line utility (sans the set/del prefix), with these additions:
236 237
237=over 4 238=over 4
238 239
239=item norc => $boolean (default false) 240=item norc => $boolean (default false)
240 241
… …
245=item force => $boolean (default false) 246=item force => $boolean (default false)
246 247
247IF true, then the values specified in the C<configure> will take 248IF true, then the values specified in the C<configure> will take
248precedence over any values configured via the rc file. The default is for 249precedence over any values configured via the rc file. The default is for
249the rc file to override any options specified in the program. 250the rc file to override any options specified in the program.
251
252=item secure => $pass->($nodeid)
253
254In addition to specifying a boolean, you can specify a code reference that
255is called for every remote execution attempt - the execution request is
256granted iff the callback returns a true value.
257
258See F<semp setsecure> for more info.
250 259
251=back 260=back
252 261
253=over 4 262=over 4
254 263
… …
271and the values specified directly via C<configure> have lowest priority, 280and the values specified directly via C<configure> have lowest priority,
272and can only be used to specify defaults. 281and can only be used to specify defaults.
273 282
274If the profile specifies a node ID, then this will become the node ID of 283If the profile specifies a node ID, then this will become the node ID of
275this process. If not, then the profile name will be used as node ID, with 284this process. If not, then the profile name will be used as node ID, with
276a slash (C</>) attached. 285a unique randoms tring (C</%u>) appended.
277 286
278If the node ID (or profile name) ends with a slash (C</>), then a random 287The node ID can contain some C<%> sequences that are expanded: C<%n>
279string is appended to make it unique. 288is expanded to the local nodename, C<%u> is replaced by a random
289strign to make the node unique. For example, the F<aemp> commandline
290utility uses C<aemp/%n/%u> as nodename, which might expand to
291C<aemp/cerebro/ZQDGSIkRhEZQDGSIkRhE>.
280 292
281=item step 2, bind listener sockets 293=item step 2, bind listener sockets
282 294
283The next step is to look up the binds in the profile, followed by binding 295The next step is to look up the binds in the profile, followed by binding
284aemp protocol listeners on all binds specified (it is possible and valid 296aemp protocol listeners on all binds specified (it is possible and valid
… …
301Example: become a distributed node using the local node name as profile. 313Example: become a distributed node using the local node name as profile.
302This should be the most common form of invocation for "daemon"-type nodes. 314This should be the most common form of invocation for "daemon"-type nodes.
303 315
304 configure 316 configure
305 317
306Example: become an anonymous node. This form is often used for commandline 318Example: become a semi-anonymous node. This form is often used for
307clients. 319commandline clients.
308 320
309 configure nodeid => "anon/"; 321 configure nodeid => "myscript/%n/%u";
310 322
311Example: configure a node using a profile called seed, which is suitable 323Example: configure a node using a profile called seed, which is suitable
312for a seed node as it binds on all local addresses on a fixed port (4040, 324for a seed node as it binds on all local addresses on a fixed port (4040,
313customary for aemp). 325customary for aemp).
314 326
… …
822 ref $action[0] 834 ref $action[0]
823 ? $action[0]() 835 ? $action[0]()
824 : snd @action; 836 : snd @action;
825 }; 837 };
826} 838}
839
840#=item $cb2 = timeout $seconds, $cb[, @args]
827 841
828=item cal $port, @msg, $callback[, $timeout] 842=item cal $port, @msg, $callback[, $timeout]
829 843
830A simple form of RPC - sends a message to the given C<$port> with the 844A simple form of RPC - sends a message to the given C<$port> with the
831given contents (C<@msg>), but adds a reply port to the message. 845given contents (C<@msg>), but adds a reply port to the message.
… …
880=back 894=back
881 895
882=head1 DISTRIBUTED DATABASE 896=head1 DISTRIBUTED DATABASE
883 897
884AnyEvent::MP comes with a simple distributed database. The database will 898AnyEvent::MP comes with a simple distributed database. The database will
885be mirrored asynchronously at all global nodes. Other nodes bind to one of 899be mirrored asynchronously on all global nodes. Other nodes bind to one
886the global nodes for their needs. 900of the global nodes for their needs. Every node has a "local database"
901which contains all the values that are set locally. All local databases
902are merged together to form the global database, which can be queried.
887 903
888The database consists of a two-level hash - a hash contains a hash which 904The database structure is that of a two-level hash - the database hash
889contains values. 905contains hashes which contain values, similarly to a perl hash of hashes,
906i.e.:
907
908 $DATABASE{$family}{$subkey} = $value
890 909
891The top level hash key is called "family", and the second-level hash key 910The top level hash key is called "family", and the second-level hash key
892is simply called "key". 911is called "subkey" or simply "key".
893 912
894The family and key must be alphanumeric ASCII strings, i.e. start 913The family must be alphanumeric, i.e. start with a letter and consist
895with a letter and consist of letters, digits, underscores and colons 914of letters, digits, underscores and colons (C<[A-Za-z][A-Za-z0-9_:]*>,
896(C<[A-Za-z][A-Za-z0-9_:]*>, pretty much like Perl module names. 915pretty much like Perl module names.
897 916
898As the family namespaceis global, it is recommended to prefix family names 917As the family namespace is global, it is recommended to prefix family names
899with the name of the application or module using it. 918with the name of the application or module using it.
900 919
920The subkeys must be non-empty strings, with no further restrictions.
921
901The values should preferably be strings, but other perl scalars should 922The values should preferably be strings, but other perl scalars should
902work as well (such as arrays and hashes). 923work as well (such as C<undef>, arrays and hashes).
903 924
904Every database entry is owned by one node - adding the same family/key 925Every database entry is owned by one node - adding the same family/subkey
905combination on multiple nodes will not cause discomfort for AnyEvent::MP, 926combination on multiple nodes will not cause discomfort for AnyEvent::MP,
906but the result might be nondeterministic, i.e. the key might have 927but the result might be nondeterministic, i.e. the key might have
907different values on different nodes. 928different values on different nodes.
908 929
930Different subkeys in the same family can be owned by different nodes
931without problems, and in fact, this is the common method to create worker
932pools. For example, a worker port for image scaling might do this:
933
934 db_set my_image_scalers => $port;
935
936And clients looking for an image scaler will want to get the
937C<my_image_scalers> keys from time to time:
938
939 db_keys my_image_scalers => sub {
940 @ports = @{ $_[0] };
941 };
942
943Or better yet, they want to monitor the database family, so they always
944have a reasonable up-to-date copy:
945
946 db_mon my_image_scalers => sub {
947 @ports = keys %{ $_[0] };
948 };
949
950In general, you can set or delete single subkeys, but query and monitor
951whole families only.
952
953If you feel the need to monitor or query a single subkey, try giving it
954it's own family.
955
956=over
957
909=item db_set $family => $key => $value 958=item db_set $family => $subkey [=> $value]
910 959
911Sets (or replaces) a key to the database. 960Sets (or replaces) a key to the database - if C<$value> is omitted,
961C<undef> is used instead.
912 962
913=item db_del $family => $key 963=item db_del $family => $subkey...
914 964
915Deletes a key from the database. 965Deletes one or more subkeys from the database family.
916 966
917=item $guard = db_reg $family => $key [=> $value] 967=item $guard = db_reg $family => $subkey [=> $value]
918 968
919Sets the key on the database and returns a guard. When the guard is 969Sets the key on the database and returns a guard. When the guard is
920destroyed, the key is deleted from the database. If C<$value> is missing, 970destroyed, the key is deleted from the database. If C<$value> is missing,
921then C<undef> is used. 971then C<undef> is used.
972
973=item db_family $family => $cb->(\%familyhash)
974
975Queries the named database C<$family> and call the callback with the
976family represented as a hash. You can keep and freely modify the hash.
977
978=item db_keys $family => $cb->(\@keys)
979
980Same as C<db_family>, except it only queries the family I<subkeys> and passes
981them as array reference to the callback.
982
983=item db_values $family => $cb->(\@values)
984
985Same as C<db_family>, except it only queries the family I<values> and passes them
986as array reference to the callback.
987
988=item $guard = db_mon $family => $cb->($familyhash, \@added, \@changed, \@deleted)
989
990Creates a monitor on the given database family. Each time a key is set
991or or is deleted the callback is called with a hash containing the
992database family and three lists of added, changed and deleted subkeys,
993respectively. If no keys have changed then the array reference might be
994C<undef> or even missing.
995
996The family hash reference and the key arrays belong to AnyEvent::MP and
997B<must not be modified or stored> by the callback. When in doubt, make a
998copy.
999
1000As soon as possible after the monitoring starts, the callback will be
1001called with the intiial contents of the family, even if it is empty,
1002i.e. there will always be a timely call to the callback with the current
1003contents.
1004
1005It is possible that the callback is called with a change event even though
1006the subkey is already present and the value has not changed.
1007
1008The monitoring stops when the guard object is destroyed.
1009
1010Example: on every change to the family "mygroup", print out all keys.
1011
1012 my $guard = db_mon mygroup => sub {
1013 my ($family, $a, $c, $d) = @_;
1014 print "mygroup members: ", (join " ", keys %$family), "\n";
1015 };
1016
1017Exmaple: wait until the family "My::Module::workers" is non-empty.
1018
1019 my $guard; $guard = db_mon My::Module::workers => sub {
1020 my ($family, $a, $c, $d) = @_;
1021 return unless %$family;
1022 undef $guard;
1023 print "My::Module::workers now nonempty\n";
1024 };
1025
1026Example: print all changes to the family "AnyRvent::Fantasy::Module".
1027
1028 my $guard = db_mon AnyRvent::Fantasy::Module => sub {
1029 my ($family, $a, $c, $d) = @_;
1030
1031 print "+$_=$family->{$_}\n" for @$a;
1032 print "*$_=$family->{$_}\n" for @$c;
1033 print "-$_=$family->{$_}\n" for @$d;
1034 };
922 1035
923=cut 1036=cut
924 1037
925=back 1038=back
926 1039

Diff Legend

– Removed lines
+ Added lines
< Changed lines
> Changed lines