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

Comparing cvsroot/AnyEvent-MP/MP.pm (file contents):
Revision 1.122 by root, Wed Feb 29 18:44:59 2012 UTC vs.
Revision 1.133 by root, Mon Mar 12 10:34:06 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
 Ports are represented by (printable) strings called "port IDs".
 =item port ID - C<nodeid#portname>
-A port ID is the concatenation of a node ID, a hash-mark (C<#>) as
+A port ID is the concatenation of a node ID, a hash-mark (C<#>)
-separator, and a port name (a printable string of unspecified format).
+as separator, and a port name (a printable string of unspecified
+format created by AnyEvent::MP).
 =item node
 A node is a single process containing at least one port - the node port,
 which enables nodes to manage each other remotely, and to create new
 use common::sense;
 use Carp ();
 use AE ();
+use Guard ();
 use base "Exporter";
 our $VERSION = $AnyEvent::MP::Config::VERSION;
 our @EXPORT = qw(
    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).
 =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 set for message (first element $tag)";
+};
 sub port(;&) {
-   my $id = "$UNIQ." . ++$ID;
+   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
    }
    $node->monitor ($port, $cb);
    defined wantarray
-      and ($cb += 0, AnyEvent::Util::guard { $node->unmonitor ($port, $cb) })
+      and ($cb += 0, Guard::guard { $node->unmonitor ($port, $cb) })
 }
 =item $guard = mon_guard $port, $ref, $ref...
 Monitors the given C<$port> and keeps the passed references. When the port
 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).
 }
 sub spawn(@) {
    my ($nodeid, undef) = split /#/, shift, 2;
-   my $id = "$RUNIQ." . ++$ID;
+   my $id = $RUNIQ . ++$ID;
    $_[0] =~ /::/
       or Carp::croak "spawn init function must be a fully-qualified name, caught";
    snd_to_func $nodeid, "AnyEvent::MP::_spawn" => $id, @_;
       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.
    $port
 }
 =back
+=head1 DISTRIBUTED DATABASE
+AnyEvent::MP comes with a simple distributed database. The database will
+be mirrored asynchronously on all global nodes. Other nodes bind to one
+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 structure is that of a two-level hash - the database hash
+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 called "subkey" or simply "key".
+The family must be alphanumeric, i.e. start with a letter and consist
+of letters, digits, underscores and colons (C<[A-Za-z][A-Za-z0-9_:]*>,
+pretty much like Perl module 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 C<undef>, arrays and hashes).
+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 => $subkey [=> $value]
+Sets (or replaces) a key to the database - if C<$value> is omitted,
+C<undef> is used instead.
+=item db_del $family => $subkey...
+Deletes one or more subkeys from the database family.
+=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
 =head1 AnyEvent::MP vs. Distributed Erlang
 AnyEvent::MP got lots of its ideas from distributed Erlang (Erlang node
 == aemp node, Erlang process == aemp port), so many of the documents and
 programming techniques employed by Erlang apply to AnyEvent::MP. Here is a

Diff Legend

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

Comparing cvsroot/AnyEvent-MP/MP.pm (file contents): Revision 1.122 by root, Wed Feb 29 18:44:59 2012 UTC vs. Revision 1.133 by root, Mon Mar 12 10:34:06 2012 UTC

Diff Legend

Comparing cvsroot/AnyEvent-MP/MP.pm (file contents):
Revision 1.122 by root, Wed Feb 29 18:44:59 2012 UTC vs.
Revision 1.133 by root, Mon Mar 12 10:34:06 2012 UTC