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.142 by root, Fri Mar 23 13:44:01 2012 UTC vs.
Revision 1.147 by root, Mon Jun 20 16:58:15 2016 UTC

… …
47 # execute callbacks in $SELF port context 47 # execute callbacks in $SELF port context
48 my $timer = AE::timer 1, 0, psub { 48 my $timer = AE::timer 1, 0, psub {
49 die "kill the port, delayed"; 49 die "kill the port, delayed";
50 }; 50 };
51 51
52 # distributed database - modification
53 db_set $family => $subkey [=> $value] # add a subkey
54 db_del $family => $subkey... # delete one or more subkeys
55 db_reg $family => $port [=> $value] # register a port
56
57 # distributed database - queries
58 db_family $family => $cb->(\%familyhash)
59 db_keys $family => $cb->(\@keys)
60 db_values $family => $cb->(\@values)
61
62 # distributed database - monitoring a family
63 db_mon $family => $cb->(\%familyhash, \@added, \@changed, \@deleted)
64
52=head1 DESCRIPTION 65=head1 DESCRIPTION
53 66
54This module (-family) implements a simple message passing framework. 67This module (-family) implements a simple message passing framework.
55 68
56Despite its simplicity, you can securely message other processes running 69Despite its simplicity, you can securely message other processes running
… …
105each other. To do this, nodes should listen on one or more local transport 118each other. To do this, nodes should listen on one or more local transport
106endpoints - binds. 119endpoints - binds.
107 120
108Currently, only standard C<ip:port> specifications can be used, which 121Currently, only standard C<ip:port> specifications can be used, which
109specify TCP ports to listen on. So a bind is basically just a tcp socket 122specify TCP ports to listen on. So a bind is basically just a tcp socket
110in listening mode thta accepts conenctions form other nodes. 123in listening mode that accepts connections from other nodes.
111 124
112=item seed nodes 125=item seed nodes
113 126
114When a node starts, it knows nothing about the network it is in - it 127When a node starts, it knows nothing about the network it is in - it
115needs to connect to at least one other node that is already in the 128needs to connect to at least one other node that is already in the
116network. These other nodes are called "seed nodes". 129network. These other nodes are called "seed nodes".
117 130
118Seed nodes themselves are not special - they are seed nodes only because 131Seed nodes themselves are not special - they are seed nodes only because
119some other node I<uses> them as such, but any node can be used as seed 132some other node I<uses> them as such, but any node can be used as seed
120node for other nodes, and eahc node cna use a different set of seed nodes. 133node for other nodes, and eahc node can use a different set of seed nodes.
121 134
122In addition to discovering the network, seed nodes are also used to 135In addition to discovering the network, seed nodes are also used to
123maintain the network - all nodes using the same seed node form are part of 136maintain the network - all nodes using the same seed node are part of the
124the same network. If a network is split into multiple subnets because e.g. 137same network. If a network is split into multiple subnets because e.g. the
125the network link between the parts goes down, then using the same seed 138network link between the parts goes down, then using the same seed nodes
126nodes for all nodes ensures that eventually the subnets get merged again. 139for all nodes ensures that eventually the subnets get merged again.
127 140
128Seed nodes are expected to be long-running, and at least one seed node 141Seed nodes are expected to be long-running, and at least one seed node
129should always be available. They should also be relatively responsive - a 142should always be available. They should also be relatively responsive - a
130seed node that blocks for long periods will slow down everybody else. 143seed node that blocks for long periods will slow down everybody else.
131 144
… …
155 168
156Any node that loads the L<AnyEvent::MP::Global> module becomes a global 169Any node that loads the L<AnyEvent::MP::Global> module becomes a global
157node and tries to keep connections to all other nodes. So while it can 170node and tries to keep connections to all other nodes. So while it can
158make sense to make every node "global" in small networks, it usually makes 171make sense to make every node "global" in small networks, it usually makes
159sense to only make seed nodes into global nodes in large networks (nodes 172sense to only make seed nodes into global nodes in large networks (nodes
160keep connections to seed nodes and global nodes, so makign them the same 173keep connections to seed nodes and global nodes, so making them the same
161reduces overhead). 174reduces overhead).
162 175
163=back 176=back
164 177
165=head1 VARIABLES/FUNCTIONS 178=head1 VARIABLES/FUNCTIONS
… …
170 183
171package AnyEvent::MP; 184package AnyEvent::MP;
172 185
173use AnyEvent::MP::Config (); 186use AnyEvent::MP::Config ();
174use AnyEvent::MP::Kernel; 187use AnyEvent::MP::Kernel;
175use AnyEvent::MP::Kernel qw(%NODE %PORT %PORT_DATA $UNIQ $RUNIQ $ID); 188use AnyEvent::MP::Kernel qw(
189 %NODE %PORT %PORT_DATA $UNIQ $RUNIQ $ID
190 add_node load_func
191
192 NODE $NODE
193 configure
194 node_of port_is_local
195 snd kil
196 db_set db_del
197 db_mon db_family db_keys db_values
198);
176 199
177use common::sense; 200use common::sense;
178 201
179use Carp (); 202use Carp ();
180 203
… …
184use base "Exporter"; 207use base "Exporter";
185 208
186our $VERSION = $AnyEvent::MP::Config::VERSION; 209our $VERSION = $AnyEvent::MP::Config::VERSION;
187 210
188our @EXPORT = qw( 211our @EXPORT = qw(
189 NODE $NODE *SELF node_of after 212 NODE $NODE
190 configure 213 configure
214 node_of port_is_local
215 snd kil
216 db_set db_del
217 db_mon db_family db_keys db_values
218
219 *SELF
220
191 snd rcv mon mon_guard kil psub peval spawn cal 221 port rcv mon mon_guard psub peval spawn cal
192 port
193 db_set db_del db_reg 222 db_set db_del db_reg
194 db_mon db_family db_keys db_values 223 db_mon db_family db_keys db_values
224
225 after
195); 226);
196 227
197our $SELF; 228our $SELF;
198 229
199sub _self_die() { 230sub _self_die() {
… …
210 241
211=item $nodeid = node_of $port 242=item $nodeid = node_of $port
212 243
213Extracts and returns the node ID from a port ID or a node ID. 244Extracts and returns the node ID from a port ID or a node ID.
214 245
246=item $is_local = port_is_local $port
247
248Returns true iff the port is a local port.
249
215=item configure $profile, key => value... 250=item configure $profile, key => value...
216 251
217=item configure key => value... 252=item configure key => value...
218 253
219Before a node can talk to other nodes on the network (i.e. enter 254Before a node can talk to other nodes on the network (i.e. enter
… …
230=over 4 265=over 4
231 266
232=item norc => $boolean (default false) 267=item norc => $boolean (default false)
233 268
234If true, then the rc file (e.g. F<~/.perl-anyevent-mp>) will I<not> 269If true, then the rc file (e.g. F<~/.perl-anyevent-mp>) will I<not>
235be consulted - all configuraiton options must be specified in the 270be consulted - all configuration options must be specified in the
236C<configure> call. 271C<configure> call.
237 272
238=item force => $boolean (default false) 273=item force => $boolean (default false)
239 274
240IF true, then the values specified in the C<configure> will take 275IF true, then the values specified in the C<configure> will take
… …
451 486
452sub rcv($@) { 487sub rcv($@) {
453 my $port = shift; 488 my $port = shift;
454 my ($nodeid, $portid) = split /#/, $port, 2; 489 my ($nodeid, $portid) = split /#/, $port, 2;
455 490
456 $NODE{$nodeid} == $NODE{""} 491 $nodeid eq $NODE
457 or Carp::croak "$port: rcv can only be called on local ports, caught"; 492 or Carp::croak "$port: rcv can only be called on local ports, caught";
458 493
459 while (@_) { 494 while (@_) {
460 if (ref $_[0]) { 495 if (ref $_[0]) {
461 if (my $self = $PORT_DATA{$portid}) { 496 if (my $self = $PORT_DATA{$portid}) {
… …
505} 540}
506 541
507=item peval $port, $coderef[, @args] 542=item peval $port, $coderef[, @args]
508 543
509Evaluates the given C<$codref> within the contetx of C<$port>, that is, 544Evaluates the given C<$codref> within the contetx of C<$port>, that is,
510when the code throews an exception the C<$port> will be killed. 545when the code throws an exception the C<$port> will be killed.
511 546
512Any remaining args will be passed to the callback. Any return values will 547Any remaining args will be passed to the callback. Any return values will
513be returned to the caller. 548be returned to the caller.
514 549
515This is useful when you temporarily want to execute code in the context of 550This is useful when you temporarily want to execute code in the context of
… …
1020=item db_values $family => $cb->(\@values) 1055=item db_values $family => $cb->(\@values)
1021 1056
1022Same as C<db_family>, except it only queries the family I<values> and passes them 1057Same as C<db_family>, except it only queries the family I<values> and passes them
1023as array reference to the callback. 1058as array reference to the callback.
1024 1059
1025=item $guard = db_mon $family => $cb->($familyhash, \@added, \@changed, \@deleted) 1060=item $guard = db_mon $family => $cb->(\%familyhash, \@added, \@changed, \@deleted)
1026 1061
1027Creates a monitor on the given database family. Each time a key is set 1062Creates a monitor on the given database family. Each time a key is
1028or or is deleted the callback is called with a hash containing the 1063set or is deleted the callback is called with a hash containing the
1029database family and three lists of added, changed and deleted subkeys, 1064database family and three lists of added, changed and deleted subkeys,
1030respectively. If no keys have changed then the array reference might be 1065respectively. If no keys have changed then the array reference might be
1031C<undef> or even missing. 1066C<undef> or even missing.
1032 1067
1033If not called in void context, a guard object is returned that, when 1068If not called in void context, a guard object is returned that, when
… …
1061 return unless %$family; 1096 return unless %$family;
1062 undef $guard; 1097 undef $guard;
1063 print "My::Module::workers now nonempty\n"; 1098 print "My::Module::workers now nonempty\n";
1064 }; 1099 };
1065 1100
1066Example: print all changes to the family "AnyRvent::Fantasy::Module". 1101Example: print all changes to the family "AnyEvent::Fantasy::Module".
1067 1102
1068 my $guard = db_mon AnyRvent::Fantasy::Module => sub { 1103 my $guard = db_mon AnyEvent::Fantasy::Module => sub {
1069 my ($family, $a, $c, $d) = @_; 1104 my ($family, $a, $c, $d) = @_;
1070 1105
1071 print "+$_=$family->{$_}\n" for @$a; 1106 print "+$_=$family->{$_}\n" for @$a;
1072 print "*$_=$family->{$_}\n" for @$c; 1107 print "*$_=$family->{$_}\n" for @$c;
1073 print "-$_=$family->{$_}\n" for @$d; 1108 print "-$_=$family->{$_}\n" for @$d;
… …
1124filter messages without dequeuing them. 1159filter messages without dequeuing them.
1125 1160
1126This is not a philosophical difference, but simply stems from AnyEvent::MP 1161This is not a philosophical difference, but simply stems from AnyEvent::MP
1127being event-based, while Erlang is process-based. 1162being event-based, while Erlang is process-based.
1128 1163
1129You cna have a look at L<Coro::MP> for a more Erlang-like process model on 1164You can have a look at L<Coro::MP> for a more Erlang-like process model on
1130top of AEMP and Coro threads. 1165top of AEMP and Coro threads.
1131 1166
1132=item * Erlang sends are synchronous, AEMP sends are asynchronous. 1167=item * Erlang sends are synchronous, AEMP sends are asynchronous.
1133 1168
1134Sending messages in Erlang is synchronous and blocks the process until 1169Sending messages in Erlang is synchronous and blocks the process until
1135a conenction has been established and the message sent (and so does not 1170a connection has been established and the message sent (and so does not
1136need a queue that can overflow). AEMP sends return immediately, connection 1171need a queue that can overflow). AEMP sends return immediately, connection
1137establishment is handled in the background. 1172establishment is handled in the background.
1138 1173
1139=item * Erlang suffers from silent message loss, AEMP does not. 1174=item * Erlang suffers from silent message loss, AEMP does not.
1140 1175
… …
1342 1377
1343=back 1378=back
1344 1379
1345=head1 LOGGING 1380=head1 LOGGING
1346 1381
1347AnyEvent::MP does not normally log anything by itself, but sinc eit is the 1382AnyEvent::MP does not normally log anything by itself, but since it is the
1348root of the contetx hierarchy for AnyEvent::MP modules, it will receive 1383root of the contetx hierarchy for AnyEvent::MP modules, it will receive
1349all log messages by submodules. 1384all log messages by submodules.
1350 1385
1351=head1 SEE ALSO 1386=head1 SEE ALSO
1352 1387

Diff Legend

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