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.128 by root, Sun Mar 4 14:28:44 2012 UTC vs.
Revision 1.130 by root, Fri Mar 9 17:05:26 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
… …
834 ref $action[0] 834 ref $action[0]
835 ? $action[0]() 835 ? $action[0]()
836 : snd @action; 836 : snd @action;
837 }; 837 };
838} 838}
839
840#=item $cb2 = timeout $seconds, $cb[, @args]
839 841
840=item cal $port, @msg, $callback[, $timeout] 842=item cal $port, @msg, $callback[, $timeout]
841 843
842A 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
843given contents (C<@msg>), but adds a reply port to the message. 845given contents (C<@msg>), but adds a reply port to the message.
… …
925pools. For example, a worker port for image scaling might do this: 927pools. For example, a worker port for image scaling might do this:
926 928
927 db_set my_image_scalers => $port; 929 db_set my_image_scalers => $port;
928 930
929And clients looking for an image scaler will want to get the 931And clients looking for an image scaler will want to get the
930C<my_image_scalers> keys: 932C<my_image_scalers> keys from time to time:
931 933
932 db_keys "my_image_scalers" => 60 => sub { 934 db_keys my_image_scalers => sub {
933 #d##TODO# 935 @ports = @{ $_[0] };
936 };
937
938Or better yet, they want to monitor the database family, so they always
939have a reasonable up-to-date copy:
940
941 db_mon my_image_scalers => sub {
942 @ports = keys %{ $_[0] };
943 };
944
945In general, you can set or delete single subkeys, but query and monitor
946whole families only.
947
948If you feel the need to monitor or query a single subkey, try giving it
949it's own family.
934 950
935=over 951=over
936 952
937=item db_set $family => $subkey [=> $value] 953=item db_set $family => $subkey [=> $value]
938 954
939Sets (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,
940C<undef> is used instead. 956C<undef> is used instead.
941 957
942=item db_del $family => $subkey 958=item db_del $family => $subkey...
943 959
944Deletes a key from the database. 960Deletes one or more subkeys from the database family.
945 961
946=item $guard = db_reg $family => $subkey [=> $value] 962=item $guard = db_reg $family => $subkey [=> $value]
947 963
948Sets 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
949destroyed, 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,
950then C<undef> is used. 966then C<undef> is used.
951 967
968=item db_family $family => $cb->(\%familyhash)
969
970Queries the named database C<$family> and call the callback with the
971family represented as a hash. You can keep and freely modify the hash.
972
973=item db_keys $family => $cb->(\@keys)
974
975Same as C<db_family>, except it only queries the family I<subkeys> and passes
976them as array reference to the callback.
977
978=item db_values $family => $cb->(\@values)
979
980Same as C<db_family>, except it only queries the family I<values> and passes them
981as array reference to the callback.
982
952=item $guard = db_mon $family => $cb->($familyhash, \@subkeys...) 983=item $guard = db_mon $family => $cb->($familyhash, \@added, \@changed, \@deleted)
953 984
954Creates 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
955or 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
956family 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.
957 990
958Specifically, if one of the passed subkeys exists in the $familyhash, then 991The family hash reference and the key arrays belong to AnyEvent::MP and
959it is currently set to the value in the $familyhash. Otherwise, it has 992B<must not be modified or stored> by the callback. When in doubt, make a
960been deleted. 993copy.
961 994
962The 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
963keys, 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.
964 999
965It 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
966the subkey is already present and the value has not changed. 1001the subkey is already present and the value has not changed.
967 1002
968The monitoring stops when the guard object is destroyed. 1003The monitoring stops when the guard object is destroyed.
969 1004
970Example: on every change to the family "mygroup", print out all keys. 1005Example: on every change to the family "mygroup", print out all keys.
971 1006
972 my $guard = db_mon mygroup => sub { 1007 my $guard = db_mon mygroup => sub {
973 my ($family, $keys) = @_; 1008 my ($family, $a, $c, $d) = @_;
974 print "mygroup members: ", (join " ", keys %$family), "\n"; 1009 print "mygroup members: ", (join " ", keys %$family), "\n";
975 }; 1010 };
976 1011
977Exmaple: wait until the family "My::Module::workers" is non-empty. 1012Exmaple: wait until the family "My::Module::workers" is non-empty.
978 1013
979 my $guard; $guard = db_mon My::Module::workers => sub { 1014 my $guard; $guard = db_mon My::Module::workers => sub {
980 my ($family, $keys) = @_; 1015 my ($family, $a, $c, $d) = @_;
981 return unless %$family; 1016 return unless %$family;
982 undef $guard; 1017 undef $guard;
983 print "My::Module::workers now nonempty\n"; 1018 print "My::Module::workers now nonempty\n";
984 }; 1019 };
985 1020
986Example: print all changes to the family "AnyRvent::Fantasy::Module". 1021Example: print all changes to the family "AnyRvent::Fantasy::Module".
987 1022
988 my $guard = db_mon AnyRvent::Fantasy::Module => sub { 1023 my $guard = db_mon AnyRvent::Fantasy::Module => sub {
989 my ($family, $keys) = @_; 1024 my ($family, $a, $c, $d) = @_;
990 1025
991 for (@$keys) { 1026 print "+$_=$family->{$_}\n" for @$a;
992 print "$_: ", 1027 print "*$_=$family->{$_}\n" for @$c;
993 (exists $family->{$_} 1028 print "-$_=$family->{$_}\n" for @$d;
994 ? $family->{$_}
995 : "(deleted)"),
996 "\n";
997 }
998 }; 1029 };
999 1030
1000=cut 1031=cut
1001 1032
1002=back 1033=back

Diff Legend

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