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.67 by root, Fri Aug 28 22:21:53 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 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 then 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). 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:
186
187First, all remaining key => value pairs (all of which are conviniently
188undocumented at the moment) will be interpreted as configuration
189data. Then they will be overwritten by any values specified in the global
190default configuration (see the F<aemp> utility), then the chain of
191profiles chosen by the profile name (and any C<parent> attributes).
192
193That means that the values specified in the profile have highest priority
194and the values specified directly via C<configure> have lowest priority,
195and can only be used to specify defaults.
182 196
183If 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
184this 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
185special 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
186 202
187The 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
188aemp protocol listeners on all binds specified (it is possible and valid 204aemp protocol listeners on all binds specified (it is possible and valid
189to 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
190outside. 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
191binds, but it can still talk to all "normal" nodes). 207binds, but it can still talk to all "normal" nodes).
192 208
193If the profile does not specify a binds list, then the node ID will be 209If the profile does not specify a binds list, then a default of C<*> is
194treated as if it were of the form C<host:port>, which will be resolved and 210used, meaning the node will bind on a dynamically-assigned port on every
195used as binds list. 211local IP address it finds.
196 212
213=item step 3, connect to seed nodes
214
197Lastly, the seeds list from the profile is passed to the 215As the last step, the seeds list from the profile is passed to the
198L<AnyEvent::MP::Global> module, which will then use it to keep 216L<AnyEvent::MP::Global> module, which will then use it to keep
199connectivity with at least on of those seed nodes at any point in time. 217connectivity with at least one node at any point in time.
200 218
201Example: become a distributed node listening on the guessed noderef, or 219=back
202the 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.
203most common form of invocation for "daemon"-type nodes. 222This should be the most common form of invocation for "daemon"-type nodes.
204 223
205 initialise_node; 224 configure
206 225
207Example: become an anonymous node. This form is often used for commandline 226Example: become an anonymous node. This form is often used for commandline
208clients. 227clients.
209 228
210 initialise_node "anon/"; 229 configure nodeid => "anon/";
211 230
212Example: become a distributed node. If there is no profile of the given 231Example: configure a node using a profile called seed, which si suitable
213name, 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,
214on the resulting addresses. 233customary for aemp).
215 234
216 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)"
217 246
218=item $SELF 247=item $SELF
219 248
220Contains 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>
221blocks. 250blocks.
… …
811 840
812=back 841=back
813 842
814=head1 SEE ALSO 843=head1 SEE ALSO
815 844
845L<AnyEvent::MP::Intro> - a gentle introduction.
846
847L<AnyEvent::MP::Kernel> - more, lower-level, stuff.
848
849L<AnyEvent::MP::Global> - network maintainance and port groups, to find
850your applications.
851
816L<AnyEvent>. 852L<AnyEvent>.
817 853
818=head1 AUTHOR 854=head1 AUTHOR
819 855
820 Marc Lehmann <schmorp@schmorp.de> 856 Marc Lehmann <schmorp@schmorp.de>

Diff Legend

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