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

Comparing AnyEvent-MP/MP.pm (file contents):
Revision 1.70 by root, Sun Aug 30 19:49:47 2009 UTC vs.
Revision 1.74 by root, Mon Aug 31 11:11:27 2009 UTC

… …
11 NODE $port # returns the noderef of the port 11 NODE $port # returns the noderef of the port
12 12
13 $SELF # receiving/own port id in rcv callbacks 13 $SELF # receiving/own port id in rcv callbacks
14 14
15 # initialise the node so it can send/receive messages 15 # initialise the node so it can send/receive messages
16 initialise_node; 16 configure;
17 17
18 # ports are message endpoints 18 # ports are message endpoints
19 19
20 # sending messages 20 # sending messages
21 snd $port, type => data...; 21 snd $port, type => data...;
22 snd $port, @msg; 22 snd $port, @msg;
23 snd @msg_with_first_element_being_a_port; 23 snd @msg_with_first_element_being_a_port;
24 24
25 # creating/using ports, the simple way 25 # creating/using ports, the simple way
26 my $simple_port = port { my @msg = @_; 0 }; 26 my $simple_port = port { my @msg = @_ };
27 27
28 # creating/using ports, tagged message matching 28 # creating/using ports, tagged message matching
29 my $port = port; 29 my $port = port;
30 rcv $port, ping => sub { snd $_[0], "pong"; 0 }; 30 rcv $port, ping => sub { snd $_[0], "pong" };
31 rcv $port, pong => sub { warn "pong received\n"; 0 }; 31 rcv $port, pong => sub { warn "pong received\n" };
32 32
33 # create a port on another node 33 # create a port on another node
34 my $port = spawn $node, $initfunc, @initdata; 34 my $port = spawn $node, $initfunc, @initdata;
35 35
36 # monitoring 36 # monitoring
… …
38 mon $port, $otherport # kill otherport on abnormal death 38 mon $port, $otherport # kill otherport on abnormal death
39 mon $port, $otherport, @msg # send message on death 39 mon $port, $otherport, @msg # send message on death
40 40
41=head1 CURRENT STATUS 41=head1 CURRENT STATUS
42 42
43 bin/aemp - stable.
43 AnyEvent::MP - stable API, should work 44 AnyEvent::MP - stable API, should work.
44 AnyEvent::MP::Intro - outdated 45 AnyEvent::MP::Intro - uptodate, but incomplete.
45 AnyEvent::MP::Kernel - mostly stable 46 AnyEvent::MP::Kernel - mostly stable.
46 AnyEvent::MP::Global - mostly stable 47 AnyEvent::MP::Global - stable API, protocol not yet final.
47 AnyEvent::MP::Node - mostly stable, but internal anyways
48 AnyEvent::MP::Transport - mostly stable, but internal anyways
49 48
50 stay tuned. 49 stay tuned.
51 50
52=head1 DESCRIPTION 51=head1 DESCRIPTION
53 52
… …
139 138
140our $VERSION = $AnyEvent::MP::Kernel::VERSION; 139our $VERSION = $AnyEvent::MP::Kernel::VERSION;
141 140
142our @EXPORT = qw( 141our @EXPORT = qw(
143 NODE $NODE *SELF node_of after 142 NODE $NODE *SELF node_of after
144 initialise_node 143 configure
145 snd rcv mon mon_guard kil reg psub spawn 144 snd rcv mon mon_guard kil reg psub spawn
146 port 145 port
147); 146);
148 147
149our $SELF; 148our $SELF;
… …
156 155
157=item $thisnode = NODE / $NODE 156=item $thisnode = NODE / $NODE
158 157
159The C<NODE> function returns, and the C<$NODE> variable contains, the node 158The C<NODE> function returns, and the C<$NODE> variable contains, the node
160ID of the node running in the current process. This value is initialised by 159ID of the node running in the current process. This value is initialised by
161a call to C<initialise_node>. 160a call to C<configure>.
162 161
163=item $nodeid = node_of $port 162=item $nodeid = node_of $port
164 163
165Extracts and returns the node ID from a port ID or a node ID. 164Extracts and returns the node ID from a port ID or a node ID.
166 165
167=item initialise_node $profile_name, key => value... 166=item configure key => value...
168 167
169Before a node can talk to other nodes on the network (i.e. enter 168Before a node can talk to other nodes on the network (i.e. enter
170"distributed mode") it has to initialise itself - the minimum a node needs 169"distributed mode") it has to configure itself - the minimum a node needs
171to know is its own name, and optionally it should know the addresses of 170to know is its own name, and optionally it should know the addresses of
172some other nodes in the network to discover other nodes. 171some other nodes in the network to discover other nodes.
173 172
174This function initialises a node - it must be called exactly once (or 173This function configures a node - it must be called exactly once (or
175never) before calling other AnyEvent::MP functions. 174never) before calling other AnyEvent::MP functions.
176 175
177The first argument is a profile name. If it is C<undef> or missing, then 176=over 4
178the current nodename will be used instead (i.e. F<uname -n>).
179 177
178=item step 1, gathering configuration from profiles
179
180The function first looks up the profile in the aemp configuration (see the 180The function first looks up a profile in the aemp configuration (see the
181L<aemp> commandline utility). the profile is calculated as follows: 181L<aemp> commandline utility). The profile name can be specified via the
182named C<profile> parameter. If it is missing, then the nodename (F<uname
183-n>) will be used as profile name.
184
185The profile data is then gathered as follows:
182 186
183First, all remaining key => value pairs (all of which are conviniently 187First, all remaining key => value pairs (all of which are conviniently
184undocumented at the moment) will be used. Then they will be overwritten by 188undocumented at the moment) will be interpreted as configuration
185any values specified in the global default configuration (see the F<aemp> 189data. Then they will be overwritten by any values specified in the global
186utility), then the chain of profiles selected, if any. That means that 190default configuration (see the F<aemp> utility), then the chain of
191profiles chosen by the profile name (and any C<parent> attributes).
192
187the values specified in the profile have highest priority and the values 193That means that the values specified in the profile have highest priority
188specified via C<initialise_node> have lowest priority. 194and the values specified directly via C<configure> have lowest priority,
195and can only be used to specify defaults.
189 196
190If the profile specifies a node ID, then this will become the node ID of 197If the profile specifies a node ID, then this will become the node ID of
191this process. If not, then the profile name will be used as node ID. The 198this process. If not, then the profile name will be used as node ID. The
192special node ID of C<anon/> will be replaced by a random node ID. 199special node ID of C<anon/> will be replaced by a random node ID.
200
201=item step 2, bind listener sockets
193 202
194The next step is to look up the binds in the profile, followed by binding 203The next step is to look up the binds in the profile, followed by binding
195aemp protocol listeners on all binds specified (it is possible and valid 204aemp protocol listeners on all binds specified (it is possible and valid
196to have no binds, meaning that the node cannot be contacted form the 205to have no binds, meaning that the node cannot be contacted form the
197outside. This means the node cannot talk to other nodes that also have no 206outside. This means the node cannot talk to other nodes that also have no
198binds, but it can still talk to all "normal" nodes). 207binds, but it can still talk to all "normal" nodes).
199 208
200If the profile does not specify a binds list, then a default of C<*> is 209If the profile does not specify a binds list, then a default of C<*> is
201used. 210used, meaning the node will bind on a dynamically-assigned port on every
211local IP address it finds.
202 212
213=item step 3, connect to seed nodes
214
203Lastly, the seeds list from the profile is passed to the 215As the last step, the seeds list from the profile is passed to the
204L<AnyEvent::MP::Global> module, which will then use it to keep 216L<AnyEvent::MP::Global> module, which will then use it to keep
205connectivity with at least on of those seed nodes at any point in time. 217connectivity with at least one node at any point in time.
206 218
207Example: become a distributed node listening on the guessed noderef, or 219=back
208the one specified via C<aemp> for the current node. This should be the 220
221Example: become a distributed node using the locla node name as profile.
209most common form of invocation for "daemon"-type nodes. 222This should be the most common form of invocation for "daemon"-type nodes.
210 223
211 initialise_node; 224 configure
212 225
213Example: become an anonymous node. This form is often used for commandline 226Example: become an anonymous node. This form is often used for commandline
214clients. 227clients.
215 228
216 initialise_node "anon/"; 229 configure nodeid => "anon/";
217 230
218Example: become a distributed node. If there is no profile of the given 231Example: configure a node using a profile called seed, which si suitable
219name, or no binds list was specified, resolve C<localhost:4044> and bind 232for a seed node as it binds on all local addresses on a fixed port (4040,
220on the resulting addresses. 233customary for aemp).
221 234
222 initialise_node "localhost:4044"; 235 # use the aemp commandline utility
236 # aemp profile seed nodeid anon/ binds '*:4040'
237
238 # then use it
239 configure profile => "seed";
240
241 # or simply use aemp from the shell again:
242 # aemp run profile seed
243
244 # or provide a nicer-to-remember nodeid
245 # aemp run profile seed nodeid "$(hostname)"
223 246
224=item $SELF 247=item $SELF
225 248
226Contains the current port id while executing C<rcv> callbacks or C<psub> 249Contains the current port id while executing C<rcv> callbacks or C<psub>
227blocks. 250blocks.

Diff Legend

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