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

Comparing AnyEvent-MP/MP/Intro.pod (file contents):
Revision 1.3 by elmex, Mon Aug 3 08:40:29 2009 UTC vs.
Revision 1.4 by root, Mon Aug 3 09:19:21 2009 UTC

-=head1 Message Passing for the non-blocked Mind
+=head1 Message Passing for the Non-Blocked Mind
 =head2 Introduction and Terminology
-This is a Tutorial about how to get the swing of the new L<AnyEvent::MP>
+This is a tutorial about how to get the swing of the new L<AnyEvent::MP>
 module. Which allows us to transparently pass messages to our own process and
 to other process on other or the same host.
-What kind of messages? Well, basically a message here means a list of Perl
+What kind of messages? Well, basically a message here means a list of
-strings, numbers, hashes and arrays, mostly everything that can be expressed as
+Perl strings, numbers, hashes and arrays, mostly everything that can be
-L<JSON> string.
+expressed in a L<JSON> text (as JSON is used by default in the protocol).
-And next you might ask: between which entities are those messages "passed"?
+And next you might ask: between which entities are those messages being "passed"?
 Basically between C<nodes>, which are basically your applications (as in
 processes) that use L<AnyEvent::MP> that run either on the same or different
 hosts.
-In this Tutorial I'll show you how to write a simple chat server based on
+In this tutorial I'll show you how to write a simple chat server based on
 L<AnyEvent::MP>.
 =head2 The Chat Client
-Ok, lets start by implementing the "frontend" of the client. We will delay the
+OK, lets start by implementing the "frontend" of the client. We will delay the
 explanation and the code of the server until we finished the client, as the
 most complex things actually happen in the client.
 We will use L<AnyEvent::Handle> to do non-blocking IO read on standard input:
       }
    );
    $quit_cv->recv;
-This is now a very basic client. Explaining explicitly what L<AnyEvent::Handle>
+This is now a very basic client. Explaining explicitly what
-does or what a I<condvar> is all about is out of scope of this document, please
+L<AnyEvent::Handle> does or what a I<condvar> is all about is out of scope
-consult L<AnyEvent::Intro> or the manpages for L<AnyEvent> and
+of this document, please consult L<AnyEvent::Intro> or the manual pages
-L<AnyEvent::Handle>.
+for L<AnyEvent> and L<AnyEvent::Handle>.
 =head2 First Step Into Messaging
 Now we take a look at L<AnyEvent::MP>. We need to know what to do in
-C<send_message>. This is an example how it might look like:
+C<send_message>. This is an example of how it might look like:
    ... # the use lines from the above snippet
    use AnyEvent::MP;
 The C<snd> function is exported by L<AnyEvent::MP>, it stands for 'send a
 message'. The first argument is the I<port> (a I<port> is something that can
 receive messages) of the server which will receive the message . How we get it
 will be explained in the next step.  The next arguments of C<snd> are
-C<'message'> and C<$msg> are the first two elements of the I<message> (a
+C<message> and C<$msg> are the first two elements of the I<message> (a
 I<message> in L<AnyEvent::MP> is a be a simple list of values, which can be
 sent to I<ports>).
 Thats all fine so far, but how do we get the C<$server_port>? Well, we will
 need to get the unique I<port id> of the server's port where he wants to
 receive all the incoming chat messages. A I<port id> is unfortunately a very
 unique string, which we are unable to know in advance. But L<AnyEvent::MP>
 supports the concept of 'well known ports', which is basically a port on the
 server side registered under a well known name. For example, the server has a
 port for receiving chat messages with a unique I<port id> and registered it
-under the name C<"chatter">.
+under the name C<chatter>.
+BTW, these "well known port names" should follow similar rules as Perl
+identifiers, so you should prefix them with your package/module name to
+make them unique, unless you use them in the main program.
 As I<messages> can only be sent to a I<port id> and not just to a name we have
 to ask the server I<node> what I<port id> has the well known port with the
-name C<"chatter">
+name C<chatter>.
 Another new term, what is a I<node>: The messaging network that can be created with
 L<AnyEvent::MP> consists of I<nodes>. A I<node> handles all the connection and
-low level message sending logic for it's application. The application in this
+low level message sending logic for its application. The application in this
 case is the server. Also every client has/is a I<node>.
 =head2 Getting The Chatter Port
 Ok, lots of talk, now some code. Now we will actually get the C<$server_port>
 Next thing is the C<$server_node>. In order to refer to another node we need
 some kind of string to reference it. The I<noderef> is basically a comma
 seperated list of C<host:port> pairs. We assume in this tutorial that the
 server runs on your localhost at port 1299, this gives us the noderef
-C<"localhost:1299">.
+C<localhost:1299>.
-Now you might ask what the C<"#"> at the end in C<$server_node> the above
+Now you might ask what the C<#> at the end in C<$server_node> the above
 example is about. Well, what I didn't tell you yet is that each I<node> has a
 default I<port> to receive messages. The default port is the empty string
 C<"">. The I<default port> of a I<node> also provides some special services for
 us, for example resolving a well known port to a I<port id>.
 Now to this line:
    snd $server_node, wkp => "chatter", "$client_port", "resolved";
-We send a message with first element being C<'wkp'> (standing for 'well known
+We send a message with first element being C<wkp> (standing for 'well known
 port'). Then the well known port name that we want to resolve to a I<port id>:
-C<"chatter">.  And in order for the server node to be able to send us back the
+C<chatter>. And in order for the server node to be able to send us back the
 resolved I<port id> we have to tell it where to send the result message: The
-result message will have as it's first argument the string C<"resolved"> and
+result message will have as it's first argument the string C<resolved> and
-will be sent to C<"$client_port"> (the I<port id> of our own just created
+will be sent to C<$client_port> (the I<port id> of our own just created
 port).
-Next this is this:
+Next comes the receiver for this C<wkp> request.
    $client_port->rcv (resolved => sub {
       my ($client_port, $type, $chatter_port_id) = @_;
       ...
       1
    });
 This sets up a receiver on our own port for the result message with the first
-argument being the string C<"resolved">. Receivers can match the contents of
+argument being the string C<resolved>. Receivers can match the contents of
 the messages before actually 'sending' it to the given callback.
 B<Please note> that the given callback has to return either a true or a false
 value for indicating whether it is B<done> (true value) or still wants to
 B<continue> (false value) receiving messages.
 In this case we tell the C<$client_port> to look into the received messages and
-look for the string C<"resolved"> in the first element of the message. If it is
+look for the string C<resolved> in the first element of the message. If it is
 found, the given callback will be called with the C<$client_port> as first
 argument, and the message as the remaining arguments.
 We name the first element of the message C<$type> in this case. It's a common
 idiom to code the 'type' of a message into it's first element, this allows for
 simple matching.
-The result message will contain the I<port id> of the well known port C<"chatter">
+The result message will contain the I<port id> of the well known port C<chatter>
 as next element, and will be put in C<$chatter_port_id>.
 Next we just assign C<$server_port> and return a 1 (a true value)
 from the callback. It indicates that we are done and don't want to receive
-further C<'resolved'> messages with this callback.
+further C<resolved> messages with this callback.
 Now we continue to the rest of the client by calling C<send> on
 C<$resolved_cv>.
 First new step after this is setting up the chat message receiver callback.
       print "chat> $msg\n";
       0
    });
-We assume that all messages that are broadcasted to all clients by the server
+We assume that all messages that are broadcast to all clients by the server
-will contain as first element the string C<"message"> and the actual message as
+will contain the string C<message> as first element, and the actual message as
 second element. The callback returns a false value this time, to indicate that
 it wants to continue receiving messages.
 Last but not least we actually tell the server to send us
 the new chat messages from other clients. We do so by sending the
-message type C<'join'> followed by our own I<port id>.
+message type C<join> followed by our own I<port id>.
    # send the server a 'join' message:
    snd $server_port, join => "$client_port";
 Then the server knows where to send all the new messages to.
 =head2 The Finished Client
 This is the complete client script:
    #!perl
    use AnyEvent;
    use AnyEvent::Handle;
    use AnyEvent::MP;
    my $resolved_cv = AnyEvent->condvar;
    $quit_cv->recv;
 =head2 The Server
 Ok, now finally to the server. What do we need? Well, we need to setup
-the well known port C<"chatter"> where all clients send their messages to.
+the well known port C<chatter> where all clients send their messages to.
 Up and into code right now:
    #!perl
    use AnyEvent;
    use AnyEvent::MP;
    become_public "localhost:1299";
 L<AnyEvent::MP>
 =head1 AUTHOR
   Robin Redeker <elmex@ta-sa.org>

Diff Legend

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

Comparing AnyEvent-MP/MP/Intro.pod (file contents): Revision 1.3 by elmex, Mon Aug 3 08:40:29 2009 UTC vs. Revision 1.4 by root, Mon Aug 3 09:19:21 2009 UTC

Diff Legend

Comparing AnyEvent-MP/MP/Intro.pod (file contents):
Revision 1.3 by elmex, Mon Aug 3 08:40:29 2009 UTC vs.
Revision 1.4 by root, Mon Aug 3 09:19:21 2009 UTC