[ViewVC] Diff of: cvs/AnyEvent-MP/MP.pm

Comparing AnyEvent-MP/MP.pm (file contents):
Revision 1.139 by root, Thu Mar 22 20:07:31 2012 UTC vs.
Revision 1.153 by root, Sat Nov 2 01:30:49 2019 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	=head1 CURRENT STATUS	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
53		56
54	bin/aemp - stable.	57	# distributed database - queries
55	AnyEvent::MP - stable API, should work.	58	db_family $family => $cb->(\%familyhash)
56	AnyEvent::MP::Intro - explains most concepts.	59	db_keys $family => $cb->(\@keys)
57	AnyEvent::MP::Kernel - mostly stable API.	60	db_values $family => $cb->(\@values)
58	AnyEvent::MP::Global - stable API.	61
		62	# distributed database - monitoring a family
		63	db_mon $family => $cb->(\%familyhash, \@added, \@changed, \@deleted)
59		64
60	=head1 DESCRIPTION	65	=head1 DESCRIPTION
61		66
62	This module (-family) implements a simple message passing framework.	67	This module (-family) implements a simple message passing framework.
63		68
…		…
113	each other. To do this, nodes should listen on one or more local transport	118	each other. To do this, nodes should listen on one or more local transport
114	endpoints - binds.	119	endpoints - binds.
115		120
116	Currently, only standard C<ip:port> specifications can be used, which	121	Currently, only standard C<ip:port> specifications can be used, which
117	specify TCP ports to listen on. So a bind is basically just a tcp socket	122	specify TCP ports to listen on. So a bind is basically just a tcp socket
118	in listening mode thta accepts conenctions form other nodes.	123	in listening mode that accepts connections from other nodes.
119		124
120	=item seed nodes	125	=item seed nodes
121		126
122	When a node starts, it knows nothing about the network it is in - it	127	When a node starts, it knows nothing about the network it is in - it
123	needs to connect to at least one other node that is already in the	128	needs to connect to at least one other node that is already in the
124	network. These other nodes are called "seed nodes".	129	network. These other nodes are called "seed nodes".
125		130
126	Seed nodes themselves are not special - they are seed nodes only because	131	Seed nodes themselves are not special - they are seed nodes only because
127	some other node I<uses> them as such, but any node can be used as seed	132	some other node I<uses> them as such, but any node can be used as seed
128	node for other nodes, and eahc node cna use a different set of seed nodes.	133	node for other nodes, and eahc node can use a different set of seed nodes.
129		134
130	In addition to discovering the network, seed nodes are also used to	135	In addition to discovering the network, seed nodes are also used to
131	maintain the network - all nodes using the same seed node form are part of	136	maintain the network - all nodes using the same seed node are part of the
132	the same network. If a network is split into multiple subnets because e.g.	137	same network. If a network is split into multiple subnets because e.g. the
133	the network link between the parts goes down, then using the same seed	138	network link between the parts goes down, then using the same seed nodes
134	nodes for all nodes ensures that eventually the subnets get merged again.	139	for all nodes ensures that eventually the subnets get merged again.
135		140
136	Seed nodes are expected to be long-running, and at least one seed node	141	Seed nodes are expected to be long-running, and at least one seed node
137	should always be available. They should also be relatively responsive - a	142	should always be available. They should also be relatively responsive - a
138	seed node that blocks for long periods will slow down everybody else.	143	seed node that blocks for long periods will slow down everybody else.
139		144
…		…
163		168
164	Any node that loads the L<AnyEvent::MP::Global> module becomes a global	169	Any node that loads the L<AnyEvent::MP::Global> module becomes a global
165	node and tries to keep connections to all other nodes. So while it can	170	node and tries to keep connections to all other nodes. So while it can
166	make sense to make every node "global" in small networks, it usually makes	171	make sense to make every node "global" in small networks, it usually makes
167	sense to only make seed nodes into global nodes in large networks (nodes	172	sense to only make seed nodes into global nodes in large networks (nodes
168	keep connections to seed nodes and global nodes, so makign them the same	173	keep connections to seed nodes and global nodes, so making them the same
169	reduces overhead).	174	reduces overhead).
170		175
171	=back	176	=back
172		177
173	=head1 VARIABLES/FUNCTIONS	178	=head1 VARIABLES/FUNCTIONS
…		…
178		183
179	package AnyEvent::MP;	184	package AnyEvent::MP;
180		185
181	use AnyEvent::MP::Config ();	186	use AnyEvent::MP::Config ();
182	use AnyEvent::MP::Kernel;	187	use AnyEvent::MP::Kernel;
183	use AnyEvent::MP::Kernel qw(%NODE %PORT %PORT_DATA $UNIQ $RUNIQ $ID);	188	use 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	);
184		199
185	use common::sense;	200	use common::sense;
186		201
187	use Carp ();	202	use Carp ();
188		203
189	use AE ();	204	use AnyEvent ();
190	use Guard ();	205	use Guard ();
191		206
192	use base "Exporter";	207	use base "Exporter";
193		208
194	our $VERSION = $AnyEvent::MP::Config::VERSION;	209	our $VERSION = '2.02'; # also in MP/Config.pm
195		210
196	our @EXPORT = qw(	211	our @EXPORT = qw(
197	NODE $NODE *SELF node_of after
198	configure	212	configure
		213
		214	NODE $NODE
		215	*SELF
		216
		217	node_of port_is_local
		218
		219	snd kil
199	snd rcv mon mon_guard kil psub peval spawn cal	220	port rcv mon mon_guard psub peval spawn cal
200	port
201	db_set db_del db_reg	221	db_set db_del db_reg
202	db_mon db_family db_keys db_values	222	db_mon db_family db_keys db_values
		223
		224	after
203	);	225	);
204		226
205	our $SELF;	227	our $SELF;
206		228
207	sub _self_die() {	229	sub _self_die() {
…		…
218		240
219	=item $nodeid = node_of $port	241	=item $nodeid = node_of $port
220		242
221	Extracts and returns the node ID from a port ID or a node ID.	243	Extracts and returns the node ID from a port ID or a node ID.
222		244
		245	=item $is_local = port_is_local $port
		246
		247	Returns true iff the port is a local port.
		248
223	=item configure $profile, key => value...	249	=item configure $profile, key => value...
224		250
225	=item configure key => value...	251	=item configure key => value...
226		252
227	Before a node can talk to other nodes on the network (i.e. enter	253	Before a node can talk to other nodes on the network (i.e. enter
…		…
238	=over 4	264	=over 4
239		265
240	=item norc => $boolean (default false)	266	=item norc => $boolean (default false)
241		267
242	If true, then the rc file (e.g. F<~/.perl-anyevent-mp>) will I<not>	268	If true, then the rc file (e.g. F<~/.perl-anyevent-mp>) will I<not>
243	be consulted - all configuraiton options must be specified in the	269	be consulted - all configuration options must be specified in the
244	C<configure> call.	270	C<configure> call.
245		271
246	=item force => $boolean (default false)	272	=item force => $boolean (default false)
247		273
248	IF true, then the values specified in the C<configure> will take	274	IF true, then the values specified in the C<configure> will take
249	precedence over any values configured via the rc file. The default is for	275	precedence over any values configured via the rc file. The default is for
250	the rc file to override any options specified in the program.	276	the rc file to override any options specified in the program.
251
252	=item secure => $pass->(@msg)
253
254	In addition to specifying a boolean, you can specify a code reference that
255	is called for every code execution attempt - the execution request is
256	granted iff the callback returns a true value.
257
258	Most of the time the callback should look only at
259	C<$AnyEvent::MP::Kernel::SRCNODE> to make a decision, and not at the
260	actual message (which can be about anything, and is mostly provided for
261	diagnostic purposes).
262
263	See F<semp setsecure> for more info.
264		277
265	=back	278	=back
266		279
267	=over 4	280	=over 4
268		281
…		…
297		310
298	=item step 2, bind listener sockets	311	=item step 2, bind listener sockets
299		312
300	The next step is to look up the binds in the profile, followed by binding	313	The next step is to look up the binds in the profile, followed by binding
301	aemp protocol listeners on all binds specified (it is possible and valid	314	aemp protocol listeners on all binds specified (it is possible and valid
302	to have no binds, meaning that the node cannot be contacted form the	315	to have no binds, meaning that the node cannot be contacted from the
303	outside. This means the node cannot talk to other nodes that also have no	316	outside. This means the node cannot talk to other nodes that also have no
304	binds, but it can still talk to all "normal" nodes).	317	binds, but it can still talk to all "normal" nodes).
305		318
306	If the profile does not specify a binds list, then a default of C<*> is	319	If the profile does not specify a binds list, then a default of C<*> is
307	used, meaning the node will bind on a dynamically-assigned port on every	320	used, meaning the node will bind on a dynamically-assigned port on every
…		…
404	=cut	417	=cut
405		418
406	sub rcv($@);	419	sub rcv($@);
407		420
408	my $KILME = sub {	421	my $KILME = sub {
409	(my $tag = substr $_[0], 0, 30) =~ s/([\x20-\x7e])/./g;	422	(my $tag = substr $_[0], 0, 30) =~ s/([^\x20-\x7e])/./g;
410	kil $SELF, unhandled_message => "no callback found for message '$tag'";	423	kil $SELF, unhandled_message => "no callback found for message '$tag'";
411	};	424	};
412		425
413	sub port(;&) {	426	sub port(;&) {
414	my $id = $UNIQ . ++$ID;	427	my $id = $UNIQ . ++$ID;
…		…
472		485
473	sub rcv($@) {	486	sub rcv($@) {
474	my $port = shift;	487	my $port = shift;
475	my ($nodeid, $portid) = split /#/, $port, 2;	488	my ($nodeid, $portid) = split /#/, $port, 2;
476		489
477	$NODE{$nodeid} == $NODE{""}	490	$nodeid eq $NODE
478	or Carp::croak "$port: rcv can only be called on local ports, caught";	491	or Carp::croak "$port: rcv can only be called on local ports, caught";
479		492
480	while (@_) {	493	while (@_) {
481	if (ref $_[0]) {	494	if (ref $_[0]) {
482	if (my $self = $PORT_DATA{$portid}) {	495	if (my $self = $PORT_DATA{$portid}) {
…		…
525	$port	538	$port
526	}	539	}
527		540
528	=item peval $port, $coderef[, @args]	541	=item peval $port, $coderef[, @args]
529		542
530	Evaluates the given C<$codref> within the contetx of C<$port>, that is,	543	Evaluates the given C<$codref> within the context of C<$port>, that is,
531	when the code throews an exception the C<$port> will be killed.	544	when the code throws an exception the C<$port> will be killed.
532		545
533	Any remaining args will be passed to the callback. Any return values will	546	Any remaining args will be passed to the callback. Any return values will
534	be returned to the caller.	547	be returned to the caller.
535		548
536	This is useful when you temporarily want to execute code in the context of	549	This is useful when you temporarily want to execute code in the context of
…		…
1041	=item db_values $family => $cb->(\@values)	1054	=item db_values $family => $cb->(\@values)
1042		1055
1043	Same as C<db_family>, except it only queries the family I<values> and passes them	1056	Same as C<db_family>, except it only queries the family I<values> and passes them
1044	as array reference to the callback.	1057	as array reference to the callback.
1045		1058
1046	=item $guard = db_mon $family => $cb->($familyhash, \@added, \@changed, \@deleted)	1059	=item $guard = db_mon $family => $cb->(\%familyhash, \@added, \@changed, \@deleted)
1047		1060
1048	Creates a monitor on the given database family. Each time a key is set	1061	Creates a monitor on the given database family. Each time a key is
1049	or or is deleted the callback is called with a hash containing the	1062	set or is deleted the callback is called with a hash containing the
1050	database family and three lists of added, changed and deleted subkeys,	1063	database family and three lists of added, changed and deleted subkeys,
1051	respectively. If no keys have changed then the array reference might be	1064	respectively. If no keys have changed then the array reference might be
1052	C<undef> or even missing.	1065	C<undef> or even missing.
1053		1066
1054	If not called in void context, a guard object is returned that, when	1067	If not called in void context, a guard object is returned that, when
…		…
1082	return unless %$family;	1095	return unless %$family;
1083	undef $guard;	1096	undef $guard;
1084	print "My::Module::workers now nonempty\n";	1097	print "My::Module::workers now nonempty\n";
1085	};	1098	};
1086		1099
1087	Example: print all changes to the family "AnyRvent::Fantasy::Module".	1100	Example: print all changes to the family "AnyEvent::Fantasy::Module".
1088		1101
1089	my $guard = db_mon AnyRvent::Fantasy::Module => sub {	1102	my $guard = db_mon AnyEvent::Fantasy::Module => sub {
1090	my ($family, $a, $c, $d) = @_;	1103	my ($family, $a, $c, $d) = @_;
1091		1104
1092	print "+$_=$family->{$_}\n" for @$a;	1105	print "+$_=$family->{$_}\n" for @$a;
1093	print "*$_=$family->{$_}\n" for @$c;	1106	print "*$_=$family->{$_}\n" for @$c;
1094	print "-$_=$family->{$_}\n" for @$d;	1107	print "-$_=$family->{$_}\n" for @$d;
…		…
1145	filter messages without dequeuing them.	1158	filter messages without dequeuing them.
1146		1159
1147	This is not a philosophical difference, but simply stems from AnyEvent::MP	1160	This is not a philosophical difference, but simply stems from AnyEvent::MP
1148	being event-based, while Erlang is process-based.	1161	being event-based, while Erlang is process-based.
1149		1162
1150	You cna have a look at L<Coro::MP> for a more Erlang-like process model on	1163	You can have a look at L<Coro::MP> for a more Erlang-like process model on
1151	top of AEMP and Coro threads.	1164	top of AEMP and Coro threads.
1152		1165
1153	=item * Erlang sends are synchronous, AEMP sends are asynchronous.	1166	=item * Erlang sends are synchronous, AEMP sends are asynchronous.
1154		1167
1155	Sending messages in Erlang is synchronous and blocks the process until	1168	Sending messages in Erlang is synchronous and blocks the process until
1156	a conenction has been established and the message sent (and so does not	1169	a connection has been established and the message sent (and so does not
1157	need a queue that can overflow). AEMP sends return immediately, connection	1170	need a queue that can overflow). AEMP sends return immediately, connection
1158	establishment is handled in the background.	1171	establishment is handled in the background.
1159		1172
1160	=item * Erlang suffers from silent message loss, AEMP does not.	1173	=item * Erlang suffers from silent message loss, AEMP does not.
1161		1174
…		…
1267		1280
1268	=over 4	1281	=over 4
1269		1282
1270	=item AnyEvent::MP::Global no longer has group management functions.	1283	=item AnyEvent::MP::Global no longer has group management functions.
1271		1284
		1285	At least not officially - the grp_* functions are still exported and might
		1286	work, but they will be removed in some later release.
		1287
1272	AnyEvent::MP now comes with a distributed database that is more	1288	AnyEvent::MP now comes with a distributed database that is more
1273	powerful. Its database families map closely to port groups, but the API	1289	powerful. Its database families map closely to port groups, but the API
1274	has changed (the functions are also now exported by AnyEvent::MP). Here is	1290	has changed (the functions are also now exported by AnyEvent::MP). Here is
1275	a rough porting guide:	1291	a rough porting guide:
1276		1292
…		…
1297	C<grp_mon> can be replaced by C<db_mon> with minor changes - C<db_mon>	1313	C<grp_mon> can be replaced by C<db_mon> with minor changes - C<db_mon>
1298	passes a hash as first argument, and an extra C<$chg> argument that can be	1314	passes a hash as first argument, and an extra C<$chg> argument that can be
1299	ignored:	1315	ignored:
1300		1316
1301	db_mon $group => sub {	1317	db_mon $group => sub {
1302	my ($ports, $add, $chg, $lde) = @_;	1318	my ($ports, $add, $chg, $del) = @_;
1303	$ports = [keys %$ports];	1319	$ports = [keys %$ports];
1304		1320
1305	# now $ports, $add and $del are the same as	1321	# now $ports, $add and $del are the same as
1306	# were originally passed by grp_mon.	1322	# were originally passed by grp_mon.
1307	...	1323	...
…		…
1360		1376
1361	=back	1377	=back
1362		1378
1363	=head1 LOGGING	1379	=head1 LOGGING
1364		1380
1365	AnyEvent::MP does not normally log anything by itself, but sinc eit is the	1381	AnyEvent::MP does not normally log anything by itself, but since it is the
1366	root of the contetx hierarchy for AnyEvent::MP modules, it will receive	1382	root of the context hierarchy for AnyEvent::MP modules, it will receive
1367	all log messages by submodules.	1383	all log messages by submodules.
1368		1384
1369	=head1 SEE ALSO	1385	=head1 SEE ALSO
1370		1386
1371	L<AnyEvent::MP::Intro> - a gentle introduction.	1387	L<AnyEvent::MP::Intro> - a gentle introduction.

Diff Legend

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

Comparing AnyEvent-MP/MP.pm (file contents): Revision 1.139 by root, Thu Mar 22 20:07:31 2012 UTC vs. Revision 1.153 by root, Sat Nov 2 01:30:49 2019 UTC

Diff Legend

Comparing AnyEvent-MP/MP.pm (file contents):
Revision 1.139 by root, Thu Mar 22 20:07:31 2012 UTC vs.
Revision 1.153 by root, Sat Nov 2 01:30:49 2019 UTC