… | |
… | |
953 | =item db_set $family => $subkey [=> $value] |
953 | =item db_set $family => $subkey [=> $value] |
954 | |
954 | |
955 | Sets (or replaces) a key to the database - if C<$value> is omitted, |
955 | Sets (or replaces) a key to the database - if C<$value> is omitted, |
956 | C<undef> is used instead. |
956 | C<undef> is used instead. |
957 | |
957 | |
958 | =item db_del $family => $subkey |
958 | =item db_del $family => $subkey... |
959 | |
959 | |
960 | Deletes a key from the database. |
960 | Deletes 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 | |
964 | Sets the key on the database and returns a guard. When the guard is |
964 | Sets the key on the database and returns a guard. When the guard is |
965 | destroyed, the key is deleted from the database. If C<$value> is missing, |
965 | destroyed, 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 | |
980 | Same as C<db_family>, except it only queries the family I<values> and passes them |
980 | Same as C<db_family>, except it only queries the family I<values> and passes them |
981 | as array reference to the callback. |
981 | as 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 | |
985 | Creates a monitor on the given database family. Each time a key is set or |
985 | Creates a monitor on the given database family. Each time a key is set |
986 | or is deleted the callback is called with a hash containing the database |
986 | or or is deleted the callback is called with a hash containing the |
987 | family and an arrayref with subkeys that have changed. |
987 | database family and three lists of added, changed and deleted subkeys, |
|
|
988 | respectively. If no keys have changed then the array reference might be |
|
|
989 | C<undef> or even missing. |
988 | |
990 | |
989 | Specifically, if one of the passed subkeys exists in the $familyhash, then |
|
|
990 | it is currently set to the value in the $familyhash. Otherwise, it has |
|
|
991 | been deleted. |
|
|
992 | |
|
|
993 | The family hash reference belongs to AnyEvent::MP and B<must not be |
991 | The family hash reference and the key arrays belong to AnyEvent::MP and |
994 | modified or stored> by the callback. When in doubt, make a copy. |
992 | B<must not be modified or stored> by the callback. When in doubt, make a |
|
|
993 | copy. |
995 | |
994 | |
996 | The first call will be with the current contents of the family and all |
995 | As soon as possible after the monitoring starts, the callback will be |
997 | keys, as if they were just added. |
996 | called with the intiial contents of the family, even if it is empty, |
|
|
997 | i.e. there will always be a timely call to the callback with the current |
|
|
998 | contents. |
998 | |
999 | |
999 | It is possible that the callback is called with a change event even though |
1000 | It is possible that the callback is called with a change event even though |
1000 | the subkey is already present and the value has not changed. |
1001 | the subkey is already present and the value has not changed. |
1001 | |
1002 | |
1002 | The monitoring stops when the guard object is destroyed. |
1003 | The monitoring stops when the guard object is destroyed. |
1003 | |
1004 | |
1004 | Example: on every change to the family "mygroup", print out all keys. |
1005 | Example: 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 | |
1011 | Exmaple: wait until the family "My::Module::workers" is non-empty. |
1012 | Exmaple: 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 | |
1020 | Example: print all changes to the family "AnyRvent::Fantasy::Module". |
1021 | Example: 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 |