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

Comparing cvsroot/AnyEvent-MP/MP.pm (file contents):
Revision 1.124 by root, Sat Mar 3 11:38:43 2012 UTC vs.
Revision 1.136 by root, Wed Mar 21 15:22:16 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->(@msg)
+In addition to specifying a boolean, you can specify a code reference that
+is called for every code execution attempt - the execution request is
+granted iff the callback returns a true value.
+Most of the time the callback should look only at
+C<$AnyEvent::MP::Kernel::SRCNODE> to make a decision, and not at the
+actual message (which can be about anything, and is mostly provided for
+diagnostic purposes).
+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).
 =cut
 sub rcv($@);
-sub _kilme {
+my $KILME = sub {
-   die "received message on port without callback";
+   (my $tag = substr $_[0], 0, 30) =~ s/([\x20-\x7e])/./g;
-}
+   kil $SELF, unhandled_message => "no callback found for message '$tag'";
+};
 sub port(;&) {
    my $id = $UNIQ . ++$ID;
    my $port = "$NODE#$id";
-   rcv $port, shift || \&_kilme;
+   rcv $port, shift || $KILME;
    $port
 }
 =item rcv $local_port, $callback->(@msg)
 The global C<$SELF> (exported by this module) contains C<$port> while
 executing the callback. Runtime errors during callback execution will
 result in the port being C<kil>ed.
-The default callback received all messages not matched by a more specific
+The default callback receives all messages not matched by a more specific
 C<tag> match.
 =item rcv $local_port, tag => $callback->(@msg_without_tag), ...
 Register (or replace) callbacks to be called on messages starting with the
 will be reported as reason C<< die => $@ >>.
 Transport/communication errors are reported as C<< transport_error =>
 $message >>.
-=cut
+Common idioms:
+   # silently remove yourself, do not kill linked ports
+   kil $SELF;
+   # report a failure in some detail
+   kil $SELF, failure_mode_1 => "it failed with too high temperature";
+   # do not waste much time with killing, just die when something goes wrong
+   open my $fh, "<file"
+      or die "file: $!";
 =item $port = spawn $node, $initfunc[, @initdata]
 Creates a port on the node C<$node> (which can also be a port ID, in which
 case it's the node where that port resides).
       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.
 =back
 =head1 DISTRIBUTED DATABASE
 AnyEvent::MP comes with a simple distributed database. The database will
-be mirrored asynchronously at all global nodes. Other nodes bind to one of
+be mirrored asynchronously on all global nodes. Other nodes bind to one
-the global nodes for their needs.
+of the global nodes for their needs. Every node has a "local database"
+which contains all the values that are set locally. All local databases
+are merged together to form the global database, which can be queried.
-The database consists of a two-level hash - a hash contains a hash which
+The database structure is that of a two-level hash - the database hash
-contains values.
+contains hashes which contain values, similarly to a perl hash of hashes,
+i.e.:
+  $DATABASE{$family}{$subkey} = $value
 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 C<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.
+Deletes one or more subkeys from the database family.
-=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, \@added, \@changed, \@deleted)
+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 three lists of added, changed and deleted subkeys,
+respectively. If no keys have changed then the array reference might be
+C<undef> or even missing.
+If not called in void context, a guard object is returned that, when
+destroyed, stops the monitor.
+The family hash reference and the key arrays belong to AnyEvent::MP and
+B<must not be modified or stored> by the callback. When in doubt, make a
+copy.
+As soon as possible after the monitoring starts, the callback will be
+called with the intiial contents of the family, even if it is empty,
+i.e. there will always be a timely call to the callback with the current
+contents.
+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, $a, $c, $d) = @_;
+      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, $a, $c, $d) = @_;
+      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, $a, $c, $d) = @_;
+      print "+$_=$family->{$_}\n" for @$a;
+      print "*$_=$family->{$_}\n" for @$c;
+      print "-$_=$family->{$_}\n" for @$d;
+   };
 =cut
 =back

Diff Legend

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

Comparing cvsroot/AnyEvent-MP/MP.pm (file contents): Revision 1.124 by root, Sat Mar 3 11:38:43 2012 UTC vs. Revision 1.136 by root, Wed Mar 21 15:22:16 2012 UTC

Diff Legend

Comparing cvsroot/AnyEvent-MP/MP.pm (file contents):
Revision 1.124 by root, Sat Mar 3 11:38:43 2012 UTC vs.
Revision 1.136 by root, Wed Mar 21 15:22:16 2012 UTC