ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/AnyEvent-MP/MP/Intro.pod
(Generate patch)

Comparing AnyEvent-MP/MP/Intro.pod (file contents):
Revision 1.13 by root, Thu Aug 13 20:47:54 2009 UTC vs.
Revision 1.14 by root, Fri Aug 14 03:27:59 2009 UTC

1=head1 Message Passing for the Non-Blocked Mind 1=head1 Message Passing for the Non-Blocked Mind
2 2
3=head1 Introduction and Terminology 3=head1 Introduction and Terminology
4 4
5This is a tutorial about how to get the swing of the new L<AnyEvent::MP> 5This is a tutorial about how to get the swing of the new L<AnyEvent::MP>
6module. Which allows us to transparently pass messages to our own process 6module, which allows us to transparently pass messages to our own process
7and to other processes on another or the same host. 7and to other processes on another or the same host.
8 8
9What kind of messages? Well, basically a message here means a list of 9What kind of messages? Well, basically a message here means a list of
10Perl strings, numbers, hashes and arrays, mostly everything that can be 10Perl strings, numbers, hashes and arrays, anythin everything that can be
11expressed as a L<JSON> text (as JSON is used by default in the protocol). 11expressed as a L<JSON> text (as JSON is used by default in the protocol).
12 12
13And next you might ask: between which entities are those messages 13And next you might ask: between which entities are those messages
14being "passed"? Effectively between I<nodes>: a nodes is basically a 14being "passed"? Effectively between I<nodes>: a nodes is basically a
15process/program that use L<AnyEvent::MP> and can run either on the same or 15process/program that use L<AnyEvent::MP> and can run either on the same or
16different hosts. 16different hosts.
17 17
18To make this more managable, every node can contain any number of 18To make this more managable, every node can contain any number of
19I<ports>: Ports are ultimately the receivers of your messages. 19I<ports>: Ports are ultimately the receivers of your messages.
20 20
21In this tutorial I'll show you how to write a simple chat server based on 21In this tutorial I'll show you how to write a simple chat server based
22L<AnyEvent::MP>. 22on L<AnyEvent::MP>. This example is used because it nicely shows how to
23organise a simple application, but keep in mind that every node trusts any
24other, so this chat cannot be used to implement a real chat server and
25client system, but it can be used to implement a distributed chat system
26for example.
23 27
24=head1 System Requirements and System Setup 28=head1 System Requirements and System Setup
25 29
26Before we can start we have to make sure some things work on your 30Before we can start we have to make sure some things work on your
27system. 31system.
28 32
29You should of course also make sure that L<AnyEvent> and L<AnyEvent::MP> 33You should of course first make sure that L<AnyEvent> and L<AnyEvent::MP>
30are installed. But how to do that is out of scope of this tutorial. 34are installed. But how to do that is out of scope of this tutorial.
31 35
32Then we have to setup a I<shared secret>: for two L<AnyEvent::MP> nodes to 36Then we have to setup a I<shared secret>: for two L<AnyEvent::MP> nodes to
33be able to communicate with each other and authenticate each other it is 37be able to communicate with each other and authenticate each other it is
34necessary to setup the same I<shared secret> for both of them. 38necessary to setup the same I<shared secret> for both of them (use use TLS
39certificates).
35 40
36The easiest way is to use the F<aemp> utility: 41The easiest way is to set this up is to use the F<aemp> utility:
37 42
38 aemp gensecret 43 aemp gensecret
39 44
40This creates the F<$HOME/.perl-anyevent-mp> config file and generates a 45This creates a F<$HOME/.perl-anyevent-mp> config file and generates a
41random shared secret. You can copy this file to any other system and then 46random shared secret. You can copy this file to any other system and then
42communicate with it. You can also select your own shared secret (F<aemp 47communicate with it. You can also select your own shared secret (F<aemp
43setsecret>) and for increased security requirements you can even create 48setsecret>) and for increased security requirements you can even create
44a TLS certificate (F<aemp gencert>), causing conenctions to not just be 49a TLS certificate (F<aemp gencert>), causing connections to not just be
45authenticated, but also to be encrypted. 50authenticated, but also to be encrypted.
46 51
47Connections will only be successful when the nodes that want to connect to 52Connections will only be successful when the nodes that want to connect to
48each other have the same I<shared secret> (or successfully verify the TLS 53each other have the same I<shared secret> (or successfully verify the TLS
49certificate). 54certificate of the other side).
50 55
51B<If something does not work as expected, and for example tcpdump shows 56B<If something does not work as expected, and for example tcpdump shows
52that the connections are closed almost immediatly, you should make sure 57that the connections are closed almost immediatly, you should make sure
53that F<~/.perl-anyevent-mp> is the same on all hosts/user accounts that 58that F<~/.perl-anyevent-mp> is the same on all hosts/user accounts that
54you try to connect with each other!> 59you try to connect with each other!>
… …
452 457
453Now, for the interested parties, let me explain some details about the protocol 458Now, for the interested parties, let me explain some details about the protocol
454that L<AnyEvent::MP> nodes use to communicate to each other. If you are not 459that L<AnyEvent::MP> nodes use to communicate to each other. If you are not
455interested you can skip this section. 460interested you can skip this section.
456 461
457Usually TCP is used for communication. Each I<node>, if configured to be a 462Usually TCP is used for communication. Each I<node>, if configured to be
458I<public> node with the C<become_public> function will listen on the configured 463a I<public> node with the C<initialise_node> function will listen on the
459TCP port (default is 4040). 464configured TCP port (default is 4040).
460 465
461If then one I<node> wants to send a message to another I<node> it will 466If then one I<node> wants to send a message to another I<node> it will
462connect to the host and port given in the I<port ID>. 467connect to the host and port given in the I<port ID>.
463 468
464Then some handshaking occurs to check whether both I<nodes> know the 469Then some handshaking occurs to check whether both I<nodes> know the

Diff Legend

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