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.46 by root, Thu Aug 13 01:46:10 2009 UTC vs.
Revision 1.49 by root, Thu Aug 13 15:29:58 2009 UTC

… …
9 $NODE # contains this node's noderef 9 $NODE # contains this node's noderef
10 NODE # returns this node's noderef 10 NODE # returns this node's noderef
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
15 # initialise the node so it can send/receive messages
16 initialise_node; # -OR-
17 initialise_node "localhost:4040"; # -OR-
18 initialise_node "slave/", "localhost:4040"
14 19
15 # ports are message endpoints 20 # ports are message endpoints
16 21
17 # sending messages 22 # sending messages
18 snd $port, type => data...; 23 snd $port, type => data...;
19 snd $port, @msg; 24 snd $port, @msg;
20 snd @msg_with_first_element_being_a_port; 25 snd @msg_with_first_element_being_a_port;
21 26
22 # miniports 27 # creating/using miniports
23 my $miniport = port { my @msg = @_; 0 }; 28 my $miniport = port { my @msg = @_; 0 };
24 29
25 # full ports 30 # creating/using full ports
26 my $port = port; 31 my $port = port;
27 rcv $port, smartmatch => $cb->(@msg); 32 rcv $port, smartmatch => $cb->(@msg);
28 rcv $port, ping => sub { snd $_[0], "pong"; 0 }; 33 rcv $port, ping => sub { snd $_[0], "pong"; 0 };
29 rcv $port, pong => sub { warn "pong received\n"; 0 }; 34 rcv $port, pong => sub { warn "pong received\n"; 0 };
30 35
31 # remote ports
32 my $port = spawn $node, $initfunc, @initdata;
33
34 # more, smarter, matches (_any_ is exported by this module) 36 # more, smarter, matches (_any_ is exported by this module)
35 rcv $port, [child_died => $pid] => sub { ... 37 rcv $port, [child_died => $pid] => sub { ...
36 rcv $port, [_any_, _any_, 3] => sub { .. $_[2] is 3 38 rcv $port, [_any_, _any_, 3] => sub { .. $_[2] is 3
39
40 # create a port on another node
41 my $port = spawn $node, $initfunc, @initdata;
37 42
38 # monitoring 43 # monitoring
39 mon $port, $cb->(@msg) # callback is invoked on death 44 mon $port, $cb->(@msg) # callback is invoked on death
40 mon $port, $otherport # kill otherport on abnormal death 45 mon $port, $otherport # kill otherport on abnormal death
41 mon $port, $otherport, @msg # send message on death 46 mon $port, $otherport, @msg # send message on death
… …
163it should know the noderefs of some other nodes in the network. 168it should know the noderefs of some other nodes in the network.
164 169
165This function initialises a node - it must be called exactly once (or 170This function initialises a node - it must be called exactly once (or
166never) before calling other AnyEvent::MP functions. 171never) before calling other AnyEvent::MP functions.
167 172
168All arguments are noderefs, which can be either resolved or unresolved. 173All arguments (optionally except for the first) are noderefs, which can be
174either resolved or unresolved.
175
176The first argument will be looked up in the configuration database first
177(if it is C<undef> then the current nodename will be used instead) to find
178the relevant configuration profile (see L<aemp>). If none is found then
179the default configuration is used. The configuration supplies additional
180seed/master nodes and can override the actual noderef.
169 181
170There are two types of networked nodes, public nodes and slave nodes: 182There are two types of networked nodes, public nodes and slave nodes:
171 183
172=over 4 184=over 4
173 185
174=item public nodes 186=item public nodes
175 187
176For public nodes, C<$noderef> must either be a (possibly unresolved) 188For public nodes, C<$noderef> (supplied either directly to
177noderef, in which case it will be resolved, or C<undef> (or missing), in 189C<initialise_node> or indirectly via a profile or the nodename) must be a
178which case the noderef will be guessed. 190noderef (possibly unresolved, in which case it will be resolved).
179 191
180Afterwards, the node will bind itself on all endpoints and try to connect 192After resolving, the node will bind itself on all endpoints and try to
181to all additional C<$seednodes> that are specified. Seednodes are optional 193connect to all additional C<$seednodes> that are specified. Seednodes are
182and can be used to quickly bootstrap the node into an existing network. 194optional and can be used to quickly bootstrap the node into an existing
195network.
183 196
184=item slave nodes 197=item slave nodes
185 198
186When the C<$noderef> is the special string C<slave/>, then the node will 199When the C<$noderef> (either as given or overriden by the config file)
200is the special string C<slave/>, then the node will become a slave
187become a slave node. Slave nodes cannot be contacted from outside and will 201node. Slave nodes cannot be contacted from outside and will route most of
188route most of their traffic to the master node that they attach to. 202their traffic to the master node that they attach to.
189 203
190At least one additional noderef is required: The node will try to connect 204At least one additional noderef is required (either by specifying it
191to all of them and will become a slave attached to the first node it can 205directly or because it is part of the configuration profile): The node
192successfully connect to. 206will try to connect to all of them and will become a slave attached to the
207first node it can successfully connect to.
193 208
194=back 209=back
195 210
196This function will block until all nodes have been resolved and, for slave 211This function will block until all nodes have been resolved and, for slave
197nodes, until it has successfully established a connection to a master 212nodes, until it has successfully established a connection to a master
198server. 213server.
199 214
200Example: become a public node listening on the default node. 215Example: become a public node listening on the guessed noderef, or the one
216specified via C<aemp> for the current node. This should be the most common
217form of invocation for "daemon"-type nodes.
201 218
202 initialise_node; 219 initialise_node;
220
221Example: become a slave node to any of the the seednodes specified via
222C<aemp>. This form is often used for commandline clients.
223
224 initialise_node "slave/";
225
226Example: become a slave node to any of the specified master servers. This
227form is also often used for commandline clients.
228
229 initialise_node "slave/", "master1", "192.168.13.17", "mp.example.net";
203 230
204Example: become a public node, and try to contact some well-known master 231Example: become a public node, and try to contact some well-known master
205servers to become part of the network. 232servers to become part of the network.
206 233
207 initialise_node undef, "master1", "master2"; 234 initialise_node undef, "master1", "master2";
… …
210 237
211 initialise_node 4041; 238 initialise_node 4041;
212 239
213Example: become a public node, only visible on localhost port 4044. 240Example: become a public node, only visible on localhost port 4044.
214 241
215 initialise_node "locahost:4044"; 242 initialise_node "localhost:4044";
216
217Example: become a slave node to any of the specified master servers.
218
219 initialise_node "slave/", "master1", "192.168.13.17", "mp.example.net";
220 243
221=item $cv = resolve_node $noderef 244=item $cv = resolve_node $noderef
222 245
223Takes an unresolved node reference that may contain hostnames and 246Takes an unresolved node reference that may contain hostnames and
224abbreviated IDs, resolves all of them and returns a resolved node 247abbreviated IDs, resolves all of them and returns a resolved node
… …
869overhead, as well as having to keep a proxy object. 892overhead, as well as having to keep a proxy object.
870 893
871Strings can easily be printed, easily serialised etc. and need no special 894Strings can easily be printed, easily serialised etc. and need no special
872procedures to be "valid". 895procedures to be "valid".
873 896
897And a a miniport consists of a single closure stored in a global hash - it
898can't become much cheaper.
899
874=item Why favour JSON, why not real serialising format such as Storable? 900=item Why favour JSON, why not real serialising format such as Storable?
875 901
876In fact, any AnyEvent::MP node will happily accept Storable as framing 902In fact, any AnyEvent::MP node will happily accept Storable as framing
877format, but currently there is no way to make a node use Storable by 903format, but currently there is no way to make a node use Storable by
878default. 904default.

Diff Legend

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