--- AnyEvent-MP/MP.pm	2012/03/03 20:35:10	1.127
+++ AnyEvent-MP/MP.pm	2012/03/04 14:28:44	1.128
@@ -199,6 +199,7 @@
    snd rcv mon mon_guard kil psub peval spawn cal
    port
    db_set db_del db_reg
+   db_mon db_family db_keys db_values
 );
 
 our $SELF;
@@ -948,6 +949,54 @@
 destroyed, the key is deleted from the database. If C<$value> is missing,
 then C<undef> is used.
 
+=item $guard = db_mon $family => $cb->($familyhash, \@subkeys...)
+
+Creates a monitor on the given database family. Each time a key is set or
+or is deleted the callback is called with a hash containing the database
+family and an arrayref with subkeys that have changed.
+
+Specifically, if one of the passed subkeys exists in the $familyhash, then
+it is currently set to the value in the $familyhash. Otherwise, it has
+been deleted.
+
+The first call will be with the current contents of the family and all
+keys, as if they were just added.
+
+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, $keys) = @_;
+      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, $keys) = @_;
+      return unless %$family;
+      undef $guard;
+      print "My::Module::workers now nonempty\n";
+   };
+
+Example: print all changes to the family "AnyRvent::Fantasy::Module".
+
+   my $guard = db_mon AnyRvent::Fantasy::Module => sub {
+      my ($family, $keys) = @_;
+
+      for (@$keys) {
+         print "$_: ",
+               (exists $family->{$_}
+                  ? $family->{$_}
+                  : "(deleted)"),
+               "\n";
+      }
+   };
+
 =cut
 
 =back