ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/cvsroot/AnyEvent-MP/MP.pm
(Generate patch)

Comparing cvsroot/AnyEvent-MP/MP.pm (file contents):
Revision 1.129 by root, Thu Mar 8 21:37:51 2012 UTC vs.
Revision 1.132 by root, Sat Mar 10 20:34:11 2012 UTC

… …
398 398
399=cut 399=cut
400 400
401sub rcv($@); 401sub rcv($@);
402 402
403sub _kilme { 403my $KILME = sub {
404 die "received message on port without callback"; 404 die "received message on port without callback";
405} 405};
406 406
407sub port(;&) { 407sub port(;&) {
408 my $id = $UNIQ . ++$ID; 408 my $id = $UNIQ . ++$ID;
409 my $port = "$NODE#$id"; 409 my $port = "$NODE#$id";
410 410
411 rcv $port, shift || \&_kilme; 411 rcv $port, shift || $KILME;
412 412
413 $port 413 $port
414} 414}
415 415
416=item rcv $local_port, $callback->(@msg) 416=item rcv $local_port, $callback->(@msg)
… …
894=back 894=back
895 895
896=head1 DISTRIBUTED DATABASE 896=head1 DISTRIBUTED DATABASE
897 897
898AnyEvent::MP comes with a simple distributed database. The database will 898AnyEvent::MP comes with a simple distributed database. The database will
899be mirrored asynchronously at all global nodes. Other nodes bind to one of 899be mirrored asynchronously on all global nodes. Other nodes bind to one
900the 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.
901 903
902The 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
903contains values. 905contains hashes which contain values, similarly to a perl hash of hashes,
906i.e.:
907
908 $DATABASE{$family}{$subkey} = $value
904 909
905The 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
906is called "subkey" or simply "key". 911is called "subkey" or simply "key".
907 912
908The family must be alphanumeric, i.e. start with a letter and consist 913The family must be alphanumeric, i.e. start with a letter and consist
… …
913with the name of the application or module using it. 918with the name of the application or module using it.
914 919
915The subkeys must be non-empty strings, with no further restrictions. 920The subkeys must be non-empty strings, with no further restrictions.
916 921
917The values should preferably be strings, but other perl scalars should 922The values should preferably be strings, but other perl scalars should
918work as well (such as undef, arrays and hashes). 923work as well (such as C<undef>, arrays and hashes).
919 924
920Every database entry is owned by one node - adding the same family/subkey 925Every database entry is owned by one node - adding the same family/subkey
921combination on multiple nodes will not cause discomfort for AnyEvent::MP, 926combination on multiple nodes will not cause discomfort for AnyEvent::MP,
922but the result might be nondeterministic, i.e. the key might have 927but the result might be nondeterministic, i.e. the key might have
923different values on different nodes. 928different values on different nodes.
… …
953=item db_set $family => $subkey [=> $value] 958=item db_set $family => $subkey [=> $value]
954 959
955Sets (or replaces) a key to the database - if C<$value> is omitted, 960Sets (or replaces) a key to the database - if C<$value> is omitted,
956C<undef> is used instead. 961C<undef> is used instead.
957 962
958=item db_del $family => $subkey 963=item db_del $family => $subkey...
959 964
960Deletes a key from the database. 965Deletes one or more subkeys from the database family.
961 966
962=item $guard = db_reg $family => $subkey [=> $value] 967=item $guard = db_reg $family => $subkey [=> $value]
963 968
964Sets 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
965destroyed, 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,
… …
978=item db_values $family => $cb->(\@values) 983=item db_values $family => $cb->(\@values)
979 984
980Same as C<db_family>, except it only queries the family I<values> and passes them 985Same as C<db_family>, except it only queries the family I<values> and passes them
981as array reference to the callback. 986as array reference to the callback.
982 987
983=item $guard = db_mon $family => $cb->($familyhash, \@subkeys...) 988=item $guard = db_mon $family => $cb->($familyhash, \@added, \@changed, \@deleted)
984 989
985Creates a monitor on the given database family. Each time a key is set or 990Creates a monitor on the given database family. Each time a key is set
986or is deleted the callback is called with a hash containing the database 991or or is deleted the callback is called with a hash containing the
987family and an arrayref with subkeys that have changed. 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.
988 995
989Specifically, if one of the passed subkeys exists in the $familyhash, then 996If not called in void context, a guard object is returned that, when
990it is currently set to the value in the $familyhash. Otherwise, it has 997destroyed, stops the monitor.
991been deleted.
992 998
993The family hash reference belongs to AnyEvent::MP and B<must not be 999The family hash reference and the key arrays belong to AnyEvent::MP and
994modified or stored> by the callback. When in doubt, make a copy. 1000B<must not be modified or stored> by the callback. When in doubt, make a
1001copy.
995 1002
996The first call will be with the current contents of the family and all 1003As soon as possible after the monitoring starts, the callback will be
997keys, as if they were just added. 1004called with the intiial contents of the family, even if it is empty,
1005i.e. there will always be a timely call to the callback with the current
1006contents.
998 1007
999It is possible that the callback is called with a change event even though 1008It is possible that the callback is called with a change event even though
1000the subkey is already present and the value has not changed. 1009the subkey is already present and the value has not changed.
1001 1010
1002The monitoring stops when the guard object is destroyed. 1011The monitoring stops when the guard object is destroyed.
1003 1012
1004Example: on every change to the family "mygroup", print out all keys. 1013Example: on every change to the family "mygroup", print out all keys.
1005 1014
1006 my $guard = db_mon mygroup => sub { 1015 my $guard = db_mon mygroup => sub {
1007 my ($family, $keys) = @_; 1016 my ($family, $a, $c, $d) = @_;
1008 print "mygroup members: ", (join " ", keys %$family), "\n"; 1017 print "mygroup members: ", (join " ", keys %$family), "\n";
1009 }; 1018 };
1010 1019
1011Exmaple: wait until the family "My::Module::workers" is non-empty. 1020Exmaple: wait until the family "My::Module::workers" is non-empty.
1012 1021
1013 my $guard; $guard = db_mon My::Module::workers => sub { 1022 my $guard; $guard = db_mon My::Module::workers => sub {
1014 my ($family, $keys) = @_; 1023 my ($family, $a, $c, $d) = @_;
1015 return unless %$family; 1024 return unless %$family;
1016 undef $guard; 1025 undef $guard;
1017 print "My::Module::workers now nonempty\n"; 1026 print "My::Module::workers now nonempty\n";
1018 }; 1027 };
1019 1028
1020Example: print all changes to the family "AnyRvent::Fantasy::Module". 1029Example: print all changes to the family "AnyRvent::Fantasy::Module".
1021 1030
1022 my $guard = db_mon AnyRvent::Fantasy::Module => sub { 1031 my $guard = db_mon AnyRvent::Fantasy::Module => sub {
1023 my ($family, $keys) = @_; 1032 my ($family, $a, $c, $d) = @_;
1024 1033
1025 for (@$keys) { 1034 print "+$_=$family->{$_}\n" for @$a;
1026 print "$_: ", 1035 print "*$_=$family->{$_}\n" for @$c;
1027 (exists $family->{$_} 1036 print "-$_=$family->{$_}\n" for @$d;
1028 ? $family->{$_}
1029 : "(deleted)"),
1030 "\n";
1031 }
1032 }; 1037 };
1033 1038
1034=cut 1039=cut
1035 1040
1036=back 1041=back

Diff Legend

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