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

Comparing AnyEvent-MP/MP/Intro.pod (file contents):
Revision 1.50 by root, Fri Mar 9 19:07:53 2012 UTC vs.
Revision 1.51 by root, Wed Mar 21 00:14:25 2012 UTC

       print "Received data: " . $data . "\n";
    };
    AnyEvent->condvar->recv;
-=head3 AnyEvent::MP::Global
-Now, that wasn't too bad, was it? OK, let's step through the new functions
+Now, that wasn't too bad, was it? OK, let's go through the new functions
 that have been used.
 =head3 C<configure> and Joining and Maintaining the Network
 First let's have a look at C<configure>:
    my $port = port;
    db_set eg_receivers => $port;
 The C<port> function has already been discussed. It simply creates a new
-I<port> and returns the I<port ID>. The C<db_reg> function, however, is
+I<port> and returns the I<port ID>. The C<db_set> function, however, is
 new: The first argument is the name of a I<database family> and the second
 argument is the name of a I<subkey> within that family. The third argument
 would be the I<value> to be associated with the family and subkey, but,
 since it is missing, it will simply be C<undef>.
-OK, what's this weird talk about families you wonder - AnyEvent::MP comes
+What is a "family" you wonder? Well, AnyEvent::MP comes with a distributed
-with a distributed database. This database runs on so-called "global"
+database. This database runs on so-called "global" nodes, which usually
-nodes, which usually are the seed nodes of your network. The database
+are the seed nodes of your network. The database structure is "simply" a
-structure is "simply" a hash of hashes of values.
+hash of hashes of values.
-In other words, if the database were stored in C<%DB>, then the C<db_set>
+To illustrate this with Perl syntax, assume the database was stored in
-function more or less would do this:
+C<%DB>, then the C<db_set> function more or less would do this:
    $DB{eg_receivers}{$port} = undef;
 So the ominous "family" selects a hash in the database, and the "subkey"
-is simply the key in this hash. And C<db_set> very much works like an
+is simply the key in this hash - C<db_set> very much works like this
 assignment.
 The family namespace is shared by all nodes in a network, so the names
 should be reasonably unique, for example, they could start with the name
 of your module, or the name of the program, using your port name or node
 different computers.
 Each time you start the sender, it will send a message to all receivers it
 finds (you have to interrupt it manually afterwards).
-Additional things you could try include using C<PERL_ANYEVENT_MP_TRACE=1>
+Additional experiments you could try include using
-to see which messages are exchanged, or starting the sender first and see
+C<PERL_ANYEVENT_MP_TRACE=1> to see which messages are exchanged, or
-how long it takes it to find the receiver.
+starting the sender before the receiver and see how long it then takes to
+find the receiver.
 =head3 Splitting Network Configuration and Application Code
 OK, so far, this works reasonably. In the real world, however, the person
 configuring your application to run on a specific network (the end user
 We bind the seed node to port 4040 on all interfaces:
    aemp profile seed binds "*:4040"
 And we configure all nodes to use this as seed node (this only works when
-running on the same host, for multiple machines you would provide the IP
+running on the same host, for multiple machines you would replace the C<*>
-address or hostname of the node running the seed), by changing the global
+by the IP address or hostname of the node running the seed), by changing
-settings shared between all profiles:
+the global settings shared between all profiles:
    aemp seeds "*:4040"
 Then we run the seed node:
      warn "$port was killed (with reason @_)";
   };
   AnyEvent->condvar->recv;
-This time we will get something like:
+This time we will get something else:
+   2012-03-21 00:50:36 <2> unmonitored local port fADb died with reason: die oops at - line 3.
-   anon/zpX.a was killed (with reason no_such_port cannot monitor nonexistent port)
+   anon/fADb was killed (with reason no_such_port cannot monitor nonexistent port)
-Since the port was already gone, the kill reason is now C<no_such_port>
+The first line is a warning that is printed when a port dies that isn't
-with some descriptive (we hope) error message.
+being monitored, because that is normally a bug. When later a C<mon> is
+attempted, it is immediately killed, because the port is already gone. The
+kill reason is now C<no_such_port> with some descriptive (we hope) error
+message.
-In fact, the kill reason is usually some identifier as first argument
+As you probably suspect from these examples, the kill reason is usually
-and a human-readable error message as second argument, but can be about
+some identifier as first argument and a human-readable error message as
-anything (it is simply a list of values you cna choose yourself) or even
+second argument - all kill reasons by AnyEvent::MP itself follow this
+pattern. But the kill reason can be anything: it is simply a list of
+values you can choose yourself. It can even be nothing (an empty list) -
-nothing - which is called a "normal" kill.
+this is called a "normal" kill.
-You can kill ports manually using the C<kil> function, which will be
+Apart from die'ing, you can kill ports manually using the C<kil>
-treated like an error when any reason is specified:
+function. Using the C<kil> function will be treated like an error when a
+non-empty reason is specified:
    kil $port, custom_error => "don't like your steenking face";
-And a clean kill without any reason arguments:
+And a I<normal> kill without any reason arguments:
    kil $port;
 By now you probably wonder what this "normal" kill business is: A common
 idiom is to not specify a callback to C<mon>, but another port, such as
 C<$SELF>:
    mon $port, $SELF;
-This basically means "monitor $port and kill me when it crashes". And a
+This basically means "monitor $port and kill me when it crashes" - and
-"normal" kill does not count as a crash. This way you can easily link
+the thing is, a "normal" kill does not count as a crash. This way you can
-ports together and make them crash together on errors, while allowing you
+easily link ports together and make them crash together on errors, while
-to remove a port silently.
+allowing you to remove a port silently when it has done it's job properly.
 =head3 Port Context
-When code runs in a port context, that means C<$SELF> contains its own
+Code runs in the so-called "port context". That means C<$SELF> contains
-port ID and exceptions that the code throws will be caught.
+its own port ID and exceptions that the code throws will be caught.
 Since AnyEvent::MP is event-based, it is not uncommon to register
-callbacks from C<rcv> handlers. As example, assume that the port receive
+callbacks from within C<rcv> handlers. As example, assume that the
-handler wants to C<die> a second later, using C<after>:
+following port receive handler wants to C<die> a second later, using
+C<after>:
   my $port = port {
      after 1, sub { die "oops" };
   };
-Then you will find it does not work - when the after callback is executed,
+If you try this out, you would find it does not work - when the C<after>
-it does not run in port context anymore, so exceptions will not be caught.
+callback is executed, it does not run in the port context anymore, so
+exceptions will not be caught.
 For these cases, AnyEvent::MP exports a special "closure constructor"
-called C<psub>, which works just like perls built-in C<sub>:
+called C<psub>, which works mostly like perl's built-in C<sub>:
   my $port = port {
      after 1, psub { die "oops" };
   };
-C<psub> stores C<$SELF> and returns a code reference. When the code
+C<psub> remembers the port context and returns a code reference. When the
-reference is invoked, it will run the code block within the context of
+code reference is invoked, it will run the code block within the context
-that port, so exception handling once more works as expected.
+that it was created in, so exception handling once more works as expected.
 There is even a way to temporarily execute code in the context of some
 port, namely C<peval>:
   peval $port, sub {

Diff Legend

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

Comparing AnyEvent-MP/MP/Intro.pod (file contents): Revision 1.50 by root, Fri Mar 9 19:07:53 2012 UTC vs. Revision 1.51 by root, Wed Mar 21 00:14:25 2012 UTC

Diff Legend

Comparing AnyEvent-MP/MP/Intro.pod (file contents):
Revision 1.50 by root, Fri Mar 9 19:07:53 2012 UTC vs.
Revision 1.51 by root, Wed Mar 21 00:14:25 2012 UTC