[ViewVC] Diff of: cvs/AnyEvent-MP/MP.pm

Comparing AnyEvent-MP/MP.pm (file contents):
Revision 1.124 by root, Sat Mar 3 11:38:43 2012 UTC vs.
Revision 1.129 by root, Thu Mar 8 21:37:51 2012 UTC

    # destroy a port again
    kil $port;  # "normal" kill
    kil $port, my_error => "everything is broken"; # error kill
    # monitoring
-   mon $localport, $cb->(@msg)      # callback is invoked on death
+   mon $port, $cb->(@msg)      # callback is invoked on death
-   mon $localport, $otherport       # kill otherport on abnormal death
+   mon $port, $localport       # kill localport on abnormal death
-   mon $localport, $otherport, @msg # send message on death
+   mon $port, $localport, @msg # send message on death
    # temporarily execute code in port context
    peval $port, sub { die "kill the port!" };
    # execute callbacks in $SELF port context
    NODE $NODE *SELF node_of after
    configure
    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;
 sub _self_die() {
 This function configures a node - it must be called exactly once (or
 never) before calling other AnyEvent::MP functions.
 The key/value pairs are basically the same ones as documented for the
-F<aemp> command line utility (sans the set/del prefix), with two additions:
+F<aemp> command line utility (sans the set/del prefix), with these additions:
 =over 4
 =item norc => $boolean (default false)
 =item force => $boolean (default false)
 IF true, then the values specified in the C<configure> will take
 precedence over any values configured via the rc file. The default is for
 the rc file to override any options specified in the program.
+=item secure => $pass->($nodeid)
+In addition to specifying a boolean, you can specify a code reference that
+is called for every remote execution attempt - the execution request is
+granted iff the callback returns a true value.
+See F<semp setsecure> for more info.
 =back
 =over 4
 and the values specified directly via C<configure> have lowest priority,
 and can only be used to specify defaults.
 If the profile specifies a node ID, then this will become the node ID of
 this process. If not, then the profile name will be used as node ID, with
-a slash (C</>) attached.
+a unique randoms tring (C</%u>) appended.
-If the node ID (or profile name) ends with a slash (C</>), then a random
+The node ID can contain some C<%> sequences that are expanded: C<%n>
-string is appended to make it unique.
+is expanded to the local nodename, C<%u> is replaced by a random
+strign to make the node unique. For example, the F<aemp> commandline
+utility uses C<aemp/%n/%u> as nodename, which might expand to
+C<aemp/cerebro/ZQDGSIkRhEZQDGSIkRhE>.
 =item step 2, bind listener sockets
 The next step is to look up the binds in the profile, followed by binding
 aemp protocol listeners on all binds specified (it is possible and valid
 Example: become a distributed node using the local node name as profile.
 This should be the most common form of invocation for "daemon"-type nodes.
    configure
-Example: become an anonymous node. This form is often used for commandline
+Example: become a semi-anonymous node. This form is often used for
-clients.
+commandline clients.
-   configure nodeid => "anon/";
+   configure nodeid => "myscript/%n/%u";
 Example: configure a node using a profile called seed, which is suitable
 for a seed node as it binds on all local addresses on a fixed port (4040,
 customary for aemp).
       ref $action[0]
          ? $action[0]()
          : snd @action;
    };
 }
+#=item $cb2 = timeout $seconds, $cb[, @args]
 =item cal $port, @msg, $callback[, $timeout]
 A simple form of RPC - sends a message to the given C<$port> with the
 given contents (C<@msg>), but adds a reply port to the message.
 The database consists of a two-level hash - a hash contains a hash which
 contains values.
 The top level hash key is called "family", and the second-level hash key
-is simply called "key".
+is called "subkey" or simply "key".
-The family and key must be alphanumeric ASCII strings, i.e. start
+The family must be alphanumeric, i.e. start with a letter and consist
-with a letter and consist of letters, digits, underscores and colons
+of letters, digits, underscores and colons (C<[A-Za-z][A-Za-z0-9_:]*>,
-(C<[A-Za-z][A-Za-z0-9_:]*>, pretty much like Perl module names.
+pretty much like Perl module names.
-As the family namespaceis global, it is recommended to prefix family names
+As the family namespace is global, it is recommended to prefix family names
 with the name of the application or module using it.
+The subkeys must be non-empty strings, with no further restrictions.
 The values should preferably be strings, but other perl scalars should
-work as well (such as arrays and hashes).
+work as well (such as undef, arrays and hashes).
-Every database entry is owned by one node - adding the same family/key
+Every database entry is owned by one node - adding the same family/subkey
 combination on multiple nodes will not cause discomfort for AnyEvent::MP,
 but the result might be nondeterministic, i.e. the key might have
 different values on different nodes.
+Different subkeys in the same family can be owned by different nodes
+without problems, and in fact, this is the common method to create worker
+pools. For example, a worker port for image scaling might do this:
+   db_set my_image_scalers => $port;
+And clients looking for an image scaler will want to get the
+C<my_image_scalers> keys from time to time:
+   db_keys my_image_scalers => sub {
+      @ports = @{ $_[0] };
+   };
+Or better yet, they want to monitor the database family, so they always
+have a reasonable up-to-date copy:
+   db_mon my_image_scalers => sub {
+      @ports = keys %{ $_[0] };
+   };
+In general, you can set or delete single subkeys, but query and monitor
+whole families only.
+If you feel the need to monitor or query a single subkey, try giving it
+it's own family.
+=over
-=item db_set $family => $key => $value
+=item db_set $family => $subkey [=> $value]
-Sets (or replaces) a key to the database.
+Sets (or replaces) a key to the database - if C<$value> is omitted,
+C<undef> is used instead.
-=item db_del $family => $key
+=item db_del $family => $subkey
 Deletes a key from the database.
-=item $guard = db_reg $family => $key [=> $value]
+=item $guard = db_reg $family => $subkey [=> $value]
 Sets the key on the database and returns a guard. When the guard is
 destroyed, the key is deleted from the database. If C<$value> is missing,
 then C<undef> is used.
+=item db_family $family => $cb->(\%familyhash)
+Queries the named database C<$family> and call the callback with the
+family represented as a hash. You can keep and freely modify the hash.
+=item db_keys $family => $cb->(\@keys)
+Same as C<db_family>, except it only queries the family I<subkeys> and passes
+them as array reference to the callback.
+=item db_values $family => $cb->(\@values)
+Same as C<db_family>, except it only queries the family I<values> and passes them
+as array reference to the callback.
+=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 family hash reference belongs to AnyEvent::MP and B<must not be
+modified or stored> by the callback. When in doubt, make a copy.
+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

Diff Legend

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

Comparing AnyEvent-MP/MP.pm (file contents): Revision 1.124 by root, Sat Mar 3 11:38:43 2012 UTC vs. Revision 1.129 by root, Thu Mar 8 21:37:51 2012 UTC

Diff Legend

Comparing AnyEvent-MP/MP.pm (file contents):
Revision 1.124 by root, Sat Mar 3 11:38:43 2012 UTC vs.
Revision 1.129 by root, Thu Mar 8 21:37:51 2012 UTC