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

Comparing AnyEvent-MP/MP.pm (file contents):
Revision 1.120 by root, Sun Feb 26 11:12:54 2012 UTC vs.
Revision 1.125 by root, Sat Mar 3 13:07:19 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 two 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.
+=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 slash (C</>) attached.
+If the node ID (or profile name) ends with a slash (C</>), then a random
+string is appended to make it unique.
 =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: 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 simply called "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 keys must be strings, with no other limitations.
+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/key
+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.
+=item db_set $family => $key => $value
+Sets (or replaces) a key to the database.
+=item db_del $family => $key
+Deletes a key from the database.
+=item $guard = db_reg $family => $key [=> $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.120 by root, Sun Feb 26 11:12:54 2012 UTC vs. Revision 1.125 by root, Sat Mar 3 13:07:19 2012 UTC

Diff Legend

Comparing AnyEvent-MP/MP.pm (file contents):
Revision 1.120 by root, Sun Feb 26 11:12:54 2012 UTC vs.
Revision 1.125 by root, Sat Mar 3 13:07:19 2012 UTC