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.129 by root, Thu Mar 8 21:37:51 2012 UTC vs.
Revision 1.130 by root, Fri Mar 9 17:05:26 2012 UTC

… …
953=item db_set $family => $subkey [=> $value] 953=item db_set $family => $subkey [=> $value]
954 954
955Sets (or replaces) a key to the database - if C<$value> is omitted, 955Sets (or replaces) a key to the database - if C<$value> is omitted,
956C<undef> is used instead. 956C<undef> is used instead.
957 957
958=item db_del $family => $subkey 958=item db_del $family => $subkey...
959 959
960Deletes a key from the database. 960Deletes one or more subkeys from the database family.
961 961
962=item $guard = db_reg $family => $subkey [=> $value] 962=item $guard = db_reg $family => $subkey [=> $value]
963 963
964Sets the key on the database and returns a guard. When the guard is 964Sets 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, 965destroyed, the key is deleted from the database. If C<$value> is missing,
… …
978=item db_values $family => $cb->(\@values) 978=item db_values $family => $cb->(\@values)
979 979
980Same as C<db_family>, except it only queries the family I<values> and passes them 980Same as C<db_family>, except it only queries the family I<values> and passes them
981as array reference to the callback. 981as array reference to the callback.
982 982
983=item $guard = db_mon $family => $cb->($familyhash, \@subkeys...) 983=item $guard = db_mon $family => $cb->($familyhash, \@added, \@changed, \@deleted)
984 984
985Creates a monitor on the given database family. Each time a key is set or 985Creates 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 986or or is deleted the callback is called with a hash containing the
987family and an arrayref with subkeys that have changed. 987database family and three lists of added, changed and deleted subkeys,
988respectively. If no keys have changed then the array reference might be
989C<undef> or even missing.
988 990
989Specifically, if one of the passed subkeys exists in the $familyhash, then
990it is currently set to the value in the $familyhash. Otherwise, it has
991been deleted.
992
993The family hash reference belongs to AnyEvent::MP and B<must not be 991The family hash reference and the key arrays belong to AnyEvent::MP and
994modified or stored> by the callback. When in doubt, make a copy. 992B<must not be modified or stored> by the callback. When in doubt, make a
993copy.
995 994
996The first call will be with the current contents of the family and all 995As soon as possible after the monitoring starts, the callback will be
997keys, as if they were just added. 996called with the intiial contents of the family, even if it is empty,
997i.e. there will always be a timely call to the callback with the current
998contents.
998 999
999It is possible that the callback is called with a change event even though 1000It is possible that the callback is called with a change event even though
1000the subkey is already present and the value has not changed. 1001the subkey is already present and the value has not changed.
1001 1002
1002The monitoring stops when the guard object is destroyed. 1003The monitoring stops when the guard object is destroyed.
1003 1004
1004Example: on every change to the family "mygroup", print out all keys. 1005Example: on every change to the family "mygroup", print out all keys.
1005 1006
1006 my $guard = db_mon mygroup => sub { 1007 my $guard = db_mon mygroup => sub {
1007 my ($family, $keys) = @_; 1008 my ($family, $a, $c, $d) = @_;
1008 print "mygroup members: ", (join " ", keys %$family), "\n"; 1009 print "mygroup members: ", (join " ", keys %$family), "\n";
1009 }; 1010 };
1010 1011
1011Exmaple: wait until the family "My::Module::workers" is non-empty. 1012Exmaple: wait until the family "My::Module::workers" is non-empty.
1012 1013
1013 my $guard; $guard = db_mon My::Module::workers => sub { 1014 my $guard; $guard = db_mon My::Module::workers => sub {
1014 my ($family, $keys) = @_; 1015 my ($family, $a, $c, $d) = @_;
1015 return unless %$family; 1016 return unless %$family;
1016 undef $guard; 1017 undef $guard;
1017 print "My::Module::workers now nonempty\n"; 1018 print "My::Module::workers now nonempty\n";
1018 }; 1019 };
1019 1020
1020Example: print all changes to the family "AnyRvent::Fantasy::Module". 1021Example: print all changes to the family "AnyRvent::Fantasy::Module".
1021 1022
1022 my $guard = db_mon AnyRvent::Fantasy::Module => sub { 1023 my $guard = db_mon AnyRvent::Fantasy::Module => sub {
1023 my ($family, $keys) = @_; 1024 my ($family, $a, $c, $d) = @_;
1024 1025
1025 for (@$keys) { 1026 print "+$_=$family->{$_}\n" for @$a;
1026 print "$_: ", 1027 print "*$_=$family->{$_}\n" for @$c;
1027 (exists $family->{$_} 1028 print "-$_=$family->{$_}\n" for @$d;
1028 ? $family->{$_}
1029 : "(deleted)"),
1030 "\n";
1031 }
1032 }; 1029 };
1033 1030
1034=cut 1031=cut
1035 1032
1036=back 1033=back

Diff Legend

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