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

Comparing AnyEvent-MP/MP.pm (file contents):
Revision 1.119 by root, Sun Feb 26 10:29:59 2012 UTC vs.
Revision 1.127 by root, Sat Mar 3 20:35:10 2012 UTC

 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
 =cut
 package AnyEvent::MP;
+use AnyEvent::MP::Config ();
 use AnyEvent::MP::Kernel;
+use AnyEvent::MP::Kernel qw(%NODE %PORT %PORT_DATA $UNIQ $RUNIQ $ID);
 use common::sense;
 use Carp ();
 use AE ();
+use Guard ();
 use base "Exporter";
-our $VERSION = '1.30';
+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
 );
 our $SELF;
 sub _self_die() {
 Before a node can talk to other nodes on the network (i.e. enter
 "distributed mode") it has to configure itself - the minimum a node needs
 to know is its own name, and optionally it should know the addresses of
 some other nodes in the network to discover other nodes.
-The key/value pairs are basically the same ones as documented for the
-F<aemp> command line utility (sans the set/del prefix).
 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 these additions:
+=over 4
+=item norc => $boolean (default false)
+If true, then the rc file (e.g. F<~/.perl-anyevent-mp>) will I<not>
+be consulted - all configuraiton options must be specified in the
+C<configure> call.
+=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
 =item step 1, gathering configuration from profiles
 That means that the values specified in the profile have highest priority
 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. The
+this process. If not, then the profile name will be used as node ID, with
-special node ID of C<anon/> will be replaced by a random node ID.
+a unique randoms tring (C</%u>) appended.
+The node ID can contain some C<%> sequences that are expanded: C<%n>
+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 si suitable
+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).
    # use the aemp commandline utility
-   # aemp profile seed nodeid anon/ binds '*:4040'
+   # aemp profile seed binds '*:4040'
    # then use it
    configure profile => "seed";
    # or simply use aemp from the shell again:
 sub _kilme {
    die "received message on port without callback";
 }
 sub port(;&) {
-   my $id = "$UNIQ." . $ID++;
+   my $id = $UNIQ . ++$ID;
    my $port = "$NODE#$id";
    rcv $port, shift || \&_kilme;
    $port
    }
    $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
 }
 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, @_;
    "$nodeid#$id"
 }
 =item after $timeout, @msg
 =item after $timeout, $callback
    $port
 }
 =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
+the global nodes for their needs.
+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 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 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:
+   db_keys "my_image_scalers" => 60 => sub {
+   #d##TODO#
+=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 a key from the database.
+=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.
+=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 AnyEvent-MP/MP.pm (file contents): Revision 1.119 by root, Sun Feb 26 10:29:59 2012 UTC vs. Revision 1.127 by root, Sat Mar 3 20:35:10 2012 UTC

Diff Legend

Comparing AnyEvent-MP/MP.pm (file contents):
Revision 1.119 by root, Sun Feb 26 10:29:59 2012 UTC vs.
Revision 1.127 by root, Sat Mar 3 20:35:10 2012 UTC