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.22 by elmex, Fri Aug 28 17:03:02 2009 UTC vs.
Revision 1.23 by root, Sat Aug 29 14:36:10 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 programs to transparently pass messages within the
7and to other processes on another or the same host. 7process and to other processes on the same or a different host.
8 8
9What kind of messages? Well, basically a message here means a list of Perl 9What kind of messages? Basically a message here means a list of Perl
10strings, numbers, hashes and arrays, anything that can be expressed as a 10strings, numbers, hashes and arrays, anything that can be expressed as a
11L<JSON> text (as JSON is used by default in the protocol). Here is an example: 11L<JSON> text (as JSON is used by default in the protocol). Here are two
12examples:
12 13
14 write_log => 1251555874, "action was successful.\n"
13 [123, ["a", "b", "c"], { foo => 'bar' }] 15 123, ["a", "b", "c"], { foo => "bar" }
14 16
15When using L<AnyEvent::MP> you should usually use a string as first element 17When using L<AnyEvent::MP> it is customary to use a descriptive string as
16of a message, which describes the type of the 18first element of a message, that indictes the type of the message. This
17message. That element is called a I<tag> in L<AnyEvent::MP>, as some 19element is called a I<tag> in L<AnyEvent::MP>, as some API functions
18API functions (C<rcv>) support matching it directly. So supposedly you want to 20(C<rcv>) support matching it directly.
19send a ping message with your current time to something, this is how such a
20message might look like (in Perl syntax):
21 21
22Supposedly you want to send a ping message with your current time to
23somewhere, this is how such a message might look like (in Perl syntax):
24
22 ['ping', 1251381636] 25 ping => 1251381636
23 26
24The next interesting question is: Between which entities are those messages 27Now that we know what a message is, to which entities are those
25being I<passed>? They are I<passed> between I<ports>. I<ports> are just sources 28messages being I<passed>? They are I<passed> to I<ports>. A I<port> is
26and destinations for messages. How do these ports relate to things you know? 29a destination for messages but also a context to execute code: when
27Well, each I<port> belongs to a I<node>, and a I<node> is just the UNIX process 30a runtime error occurs while executing code belonging to a port, the
31exception will be raised on the port and can even travel to interested
32parties on other nodes, which makes supervision of distributed processes
33easy.
34
35How do these ports relate to things you know? Each I<port> belongs
36to a I<node>, and a I<node> is just the UNIX process that runs your
28that runs your L<AnyEvent::MP> application. 37L<AnyEvent::MP> application.
29 38
30Each I<node> is distinguished from other I<nodes>, that run on the same host or 39Each I<node> is distinguished from other I<nodes> running on the same or
31multiple hosts in a network, by it's I<node ID>. A I<node ID> can be manually 40another host in a network by its I<node ID>. A I<node ID> is simply a
32assigned or L<AnyEvent::MP> will assign one it self for you. 41unique string chosen manually or assigned by L<AnyEvent::MP> in some way
42(UNIX nodename, random string...).
33 43
34Here is a visualisation about how I<nodes>, I<ports> and UNIX processes 44Here is a diagram about how I<nodes>, I<ports> and UNIX processes relate
35relate to each other. The setup consists of two nodes (more are of 45to each other. The setup consists of two nodes (more are of course
36course possible): Node C<A> (in UNIX process 7066) with the ports C<ABC> and C<DEF>. 46possible): Node C<A> (in UNIX process 7066) with the ports C<ABC> and
37And the node C<B> (in UNIX process 8321) with the ports C<FOO> and C<BAR>. 47C<DEF>. And the node C<B> (in UNIX process 8321) with the ports C<FOO> and
48C<BAR>.
38 49
39 50
40 |- PID: 7066 -| |- PID: 8321 -| 51 |- PID: 7066 -| |- PID: 8321 -|
41 | | | | 52 | | | |
42 | Node ID: A | | Node ID: B | 53 | Node ID: A | | Node ID: B |
… …
45 | | X | | 56 | | X | |
46 | Port DEF =|= <----/ \-----> =|= Port BAR | 57 | Port DEF =|= <----/ \-----> =|= Port BAR |
47 | | | | 58 | | | |
48 |-------------| |-------------| 59 |-------------| |-------------|
49 60
50The strings for the I<port ids> here are just for illustrative purposes. Even 61The strings for the I<port IDs> here are just for illustrative
51if in reality I<ports> in L<AnyEvent::MP> are also identified by strings they 62purposes: Even though I<ports> in L<AnyEvent::MP> are also identified by
52can't be choosen manually and are assigned randomly. These I<port ids> should 63strings, they can't be choosen manually and are assigned by the system
53also not be used directly for other purposes than referring to an endpoint for 64dynamically. These I<port IDs> are unique within a network and can also be
54messages. 65used to identify senders or as message tags for instance.
55 66
56The next sections will explain the API of L<AnyEvent::MP> by going through a 67The next sections will explain the API of L<AnyEvent::MP> by going through
57few simple examples. Later some more complex idioms are introduced, which are 68a few simple examples. Later some more complex idioms are introduced,
58maybe useful to solve some real world problems. 69which are hopefully useful to solve some real world problems.
59 70
60=head1 Passing Your First Message 71=head1 Passing Your First Message
61 72
62As start lets have a look at the messaging API. The next example is just a 73As start lets have a look at the messaging API. The next example is just a
63demo to show the basic elements of message passing with L<AnyEvent::MP>. 74demo to show the basic elements of message passing with L<AnyEvent::MP>.

Diff Legend

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