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.71 by root, Sun Aug 30 19:52:56 2009 UTC vs.
Revision 1.72 by root, Mon Aug 31 10:07:04 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...;
… …
138 138
139our $VERSION = $AnyEvent::MP::Kernel::VERSION; 139our $VERSION = $AnyEvent::MP::Kernel::VERSION;
140 140
141our @EXPORT = qw( 141our @EXPORT = qw(
142 NODE $NODE *SELF node_of after 142 NODE $NODE *SELF node_of after
143 initialise_node 143 configure
144 snd rcv mon mon_guard kil reg psub spawn 144 snd rcv mon mon_guard kil reg psub spawn
145 port 145 port
146); 146);
147 147
148our $SELF; 148our $SELF;
… …
155 155
156=item $thisnode = NODE / $NODE 156=item $thisnode = NODE / $NODE
157 157
158The 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
159ID 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
160a call to C<initialise_node>. 160a call to C<configure>.
161 161
162=item $nodeid = node_of $port 162=item $nodeid = node_of $port
163 163
164Extracts 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.
165 165
166=item initialise_node $profile_name, key => value... 166=item configure key => value...
167 167
168Before 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
169"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
170to 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
171some other nodes in the network to discover other nodes. 171some other nodes in the network to discover other nodes.
172 172
173This function initialises a node - it must be called exactly once (or 173This function configures a node - it must be called exactly once (or
174never) before calling other AnyEvent::MP functions. 174never) before calling other AnyEvent::MP functions.
175 175
176The first argument is a profile name. If it is C<undef> or missing, then 176=over 4
177the current nodename will be used instead (i.e. F<uname -n>).
178 177
178=item step 1, gathering configuration from profiles
179
179The 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
180L<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:
181 186
182First, all remaining key => value pairs (all of which are conviniently 187First, all remaining key => value pairs (all of which are conviniently
183undocumented at the moment) will be used. Then they will be overwritten by 188undocumented at the moment) will be interpreted as configuration
184any values specified in the global default configuration (see the F<aemp> 189data. Then they will be overwritten by any values specified in the global
185utility), 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
186the values specified in the profile have highest priority and the values 193That means that the values specified in the profile have highest priority
187specified 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.
188 196
189If 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
190this 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
191special 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
192 202
193The 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
194aemp protocol listeners on all binds specified (it is possible and valid 204aemp protocol listeners on all binds specified (it is possible and valid
195to 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
196outside. 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
197binds, but it can still talk to all "normal" nodes). 207binds, but it can still talk to all "normal" nodes).
198 208
199If 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
200used. 210used, meaning the node will bind on a dynamically-assigned port on every
211local IP address it finds.
201 212
213=item step 3, connect to seed nodes
214
202Lastly, the seeds list from the profile is passed to the 215As the last step, the seeds list from the profile is passed to the
203L<AnyEvent::MP::Global> module, which will then use it to keep 216L<AnyEvent::MP::Global> module, which will then use it to keep
204connectivity with at least on of those seed nodes at any point in time. 217connectivity with at least one node at any point in time.
205 218
206Example: become a distributed node listening on the guessed noderef, or 219=back
207the 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.
208most common form of invocation for "daemon"-type nodes. 222This should be the most common form of invocation for "daemon"-type nodes.
209 223
210 initialise_node; 224 configure
211 225
212Example: become an anonymous node. This form is often used for commandline 226Example: become an anonymous node. This form is often used for commandline
213clients. 227clients.
214 228
215 initialise_node "anon/"; 229 configure nodeid => "anon/";
216 230
217Example: become a distributed node. If there is no profile of the given 231Example: configure a node using a profile called seed, which si suitable
218name, 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,
219on the resulting addresses. 233customary for aemp).
220 234
221 initialise_node "localhost:4044"; 235 # use the aemp commandline utility
236 # aemp profile seed setnodeid anon/ setbinds '*: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)"
222 246
223=item $SELF 247=item $SELF
224 248
225Contains 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>
226blocks. 250blocks.

Diff Legend

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