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.63 by root, Thu Aug 27 21:29:37 2009 UTC vs.
Revision 1.64 by root, Fri Aug 28 00:58:44 2009 UTC

… …
68=item port 68=item port
69 69
70A port is something you can send messages to (with the C<snd> function). 70A port is something you can send messages to (with the C<snd> function).
71 71
72Ports allow you to register C<rcv> handlers that can match all or just 72Ports allow you to register C<rcv> handlers that can match all or just
73some messages. Messages will not be queued. 73some messages. Messages send to ports will not be queued, regardless of
74anything was listening for them or not.
74 75
75=item port ID - C<noderef#portname> 76=item port ID - C<noderef#portname>
76 77
77A port ID is the concatenation of a noderef, a hash-mark (C<#>) as 78A port ID is the concatenation of a noderef, a hash-mark (C<#>) as
78separator, and a port name (a printable string of unspecified format). An 79separator, and a port name (a printable string of unspecified format). An
… …
89public nodes, but do not need an open port) or public nodes (connectable 90public nodes, but do not need an open port) or public nodes (connectable
90from any other node). 91from any other node).
91 92
92=item node ID - C<[a-za-Z0-9_\-.:]+> 93=item node ID - C<[a-za-Z0-9_\-.:]+>
93 94
94A node ID is a string that either simply identifies the node (for 95A node ID is a string that uniquely identifies the node within a
95private and slave nodes), or contains a recipe on how to reach a given 96network. Depending on the configuration used, node IDs can look like a
96node (for public nodes). 97hostname, a hostname and a port, or a random string. AnyEvent::MP itself
98doesn't interpret node IDs in any way.
97 99
98This recipe is simply a comma-separated list of C<address:port> pairs (for 100=item binds - C<ip:port>
99TCP/IP, other protocols might look different).
100 101
101Node references come in two flavours: resolved (containing only numerical 102Nodes can only talk to each other by creating some kind of connection to
102addresses) or unresolved (where hostnames are used instead of addresses). 103each other. To do this, nodes should listen on one or more local transport
104endpoints - binds. Currently, only standard C<ip:port> specifications can
105be used, which specify TCP ports to listen on.
103 106
104Before using an unresolved node reference in a message you first have to 107=item seeds - C<host:port>
105resolve it. 108
109When a node starts, it knows nothing about the network. To teach the node
110about the network it first has to contact some other node within the
111network. This node is called a seed.
112
113Seeds are transport endpoint(s) of as many nodes as one wants. Those nodes
114are expected to be long-running, and at least one of those should always
115be available. When nodes run out of connections (e.g. due to a network
116error), they try to re-establish connections to some seednodes again to
117join the network.
106 118
107=back 119=back
108 120
109=head1 VARIABLES/FUNCTIONS 121=head1 VARIABLES/FUNCTIONS
110 122
… …
141 kil $SELF, die => $msg; 153 kil $SELF, die => $msg;
142} 154}
143 155
144=item $thisnode = NODE / $NODE 156=item $thisnode = NODE / $NODE
145 157
146The C<NODE> function returns, and the C<$NODE> variable contains the 158The C<NODE> function returns, and the C<$NODE> variable contains the node
147node id of the local node. The value is initialised by a call to 159ID of the node running in the current process. This value is initialised by
148C<initialise_node>. 160a call to C<initialise_node>.
149 161
150=item $nodeid = node_of $port 162=item $nodeid = node_of $port
151 163
152Extracts and returns the noderef from a port ID or a node ID. 164Extracts and returns the node ID part from a port ID or a node ID.
153 165
154=item initialise_node $profile_name 166=item initialise_node $profile_name
155 167
156Before a node can talk to other nodes on the network it has to initialise 168Before a node can talk to other nodes on the network (i.e. enter
157itself - the minimum a node needs to know is it's own name, and optionally 169"distributed mode") it has to initialise itself - the minimum a node needs
158it should know the noderefs of some other nodes in the network. 170to know is its own name, and optionally it should know the addresses of
171some other nodes in the network to discover other nodes.
159 172
160This function initialises a node - it must be called exactly once (or 173This function initialises a node - it must be called exactly once (or
161never) before calling other AnyEvent::MP functions. 174never) before calling other AnyEvent::MP functions.
162 175
163All arguments (optionally except for the first) are noderefs, which can be 176The first argument is a profile name. If it is C<undef> or missing, then
164either resolved or unresolved. 177the current nodename will be used instead (i.e. F<uname -n>).
165 178
166The first argument will be looked up in the configuration database first 179The function then looks up the profile in the aemp configuration (see the
167(if it is C<undef> then the current nodename will be used instead) to find 180L<aemp> commandline utility).
168the relevant configuration profile (see L<aemp>). If none is found then
169the default configuration is used. The configuration supplies additional
170seed/master nodes and can override the actual noderef.
171 181
172There are two types of networked nodes, public nodes and slave nodes: 182If the profile specifies a node ID, then this will become the node ID of
183this process. If not, then the profile name will be used as node ID. The
184special node ID of C<anon/> will be replaced by a random node ID.
173 185
174=over 4 186The next step is to look up the binds in the profile, followed by binding
187aemp protocol listeners on all binds specified (it is possible and valid
188to have no binds, meaning that the node cannot be contacted form the
189outside. This means the node cannot talk to other nodes that also have no
190binds, but it can still talk to all "normal" nodes).
175 191
176=item public nodes 192If the profile does not specify a binds list, then the node ID will be
193treated as if it were of the form C<host:port>, which will be resolved and
194used as binds list.
177 195
178For public nodes, C<$noderef> (supplied either directly to 196Lastly, the seeds list from the profile is passed to the
179C<initialise_node> or indirectly via a profile or the nodename) must be a 197L<AnyEvent::MP::Global> module, which will then use it to keep
180noderef (possibly unresolved, in which case it will be resolved). 198connectivity with at least on of those seed nodes at any point in time.
181 199
182After resolving, the node will bind itself on all endpoints.
183
184=item slave nodes
185
186When the C<$noderef> (either as given or overriden by the config file)
187is the special string C<slave/>, then the node will become a slave
188node. Slave nodes cannot be contacted from outside, and cannot talk to
189each other (at least in this version of AnyEvent::MP).
190
191Slave nodes work by creating connections to all public nodes, using the
192L<AnyEvent::MP::Global> service.
193
194=back
195
196After initialising itself, the node will connect to all additional
197C<$seednodes> that are specified diretcly or via a profile. Seednodes are
198optional and can be used to quickly bootstrap the node into an existing
199network.
200
201All the seednodes will also be specially marked to automatically retry
202connecting to them indefinitely, so make sure that seednodes are really
203reliable and up (this might also change in the future).
204
205Example: become a public node listening on the guessed noderef, or the one 200Example: become a distributed node listening on the guessed noderef, or
206specified via C<aemp> for the current node. This should be the most common 201the one specified via C<aemp> for the current node. This should be the
207form of invocation for "daemon"-type nodes. 202most common form of invocation for "daemon"-type nodes.
208 203
209 initialise_node; 204 initialise_node;
210 205
211Example: become a slave node to any of the the seednodes specified via 206Example: become an anonymous node. This form is often used for commandline
212C<aemp>. This form is often used for commandline clients. 207clients.
213 208
214 initialise_node "slave/"; 209 initialise_node "anon/";
215 210
216Example: become a public node, and try to contact some well-known master 211Example: become a distributed node. If there is no profile of the given
217servers to become part of the network. 212name, or no binds list was specified, resolve C<localhost:4044> and bind
218 213on the resulting addresses.
219 initialise_node undef, "master1", "master2";
220
221Example: become a public node listening on port C<4041>.
222
223 initialise_node 4041;
224
225Example: become a public node, only visible on localhost port 4044.
226 214
227 initialise_node "localhost:4044"; 215 initialise_node "localhost:4044";
228
229=item $cv = resolve_node $noderef
230
231Takes an unresolved node reference that may contain hostnames and
232abbreviated IDs, resolves all of them and returns a resolved node
233reference.
234
235In addition to C<address:port> pairs allowed in resolved noderefs, the
236following forms are supported:
237
238=over 4
239
240=item the empty string
241
242An empty-string component gets resolved as if the default port (4040) was
243specified.
244
245=item naked port numbers (e.g. C<1234>)
246
247These are resolved by prepending the local nodename and a colon, to be
248further resolved.
249
250=item hostnames (e.g. C<localhost:1234>, C<localhost>)
251
252These are resolved by using AnyEvent::DNS to resolve them, optionally
253looking up SRV records for the C<aemp=4040> port, if no port was
254specified.
255
256=back
257 216
258=item $SELF 217=item $SELF
259 218
260Contains the current port id while executing C<rcv> callbacks or C<psub> 219Contains the current port id while executing C<rcv> callbacks or C<psub>
261blocks. 220blocks.

Diff Legend

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