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

Comparing AnyEvent-MP/MP.pm (file contents):
Revision 1.130 by root, Fri Mar 9 17:05:26 2012 UTC vs.
Revision 1.139 by root, Thu Mar 22 20:07:31 2012 UTC

…		…
247		247
248	IF true, then the values specified in the C<configure> will take	248	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	249	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.	250	the rc file to override any options specified in the program.
251		251
252	=item secure => $pass->($nodeid)	252	=item secure => $pass->(@msg)
253		253
254	In addition to specifying a boolean, you can specify a code reference that	254	In addition to specifying a boolean, you can specify a code reference that
255	is called for every remote execution attempt - the execution request is	255	is called for every code execution attempt - the execution request is
256	granted iff the callback returns a true value.	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).
257		262
258	See F<semp setsecure> for more info.	263	See F<semp setsecure> for more info.
259		264
260	=back	265	=back
261		266
…		…
398		403
399	=cut	404	=cut
400		405
401	sub rcv($@);	406	sub rcv($@);
402		407
403	sub _kilme {	408	my $KILME = sub {
404	die "received message on port without callback";	409	(my $tag = substr $_[0], 0, 30) =~ s/([\x20-\x7e])/./g;
405	}	410	kil $SELF, unhandled_message => "no callback found for message '$tag'";
		411	};
406		412
407	sub port(;&) {	413	sub port(;&) {
408	my $id = $UNIQ . ++$ID;	414	my $id = $UNIQ . ++$ID;
409	my $port = "$NODE#$id";	415	my $port = "$NODE#$id";
410		416
411	rcv $port, shift \|\| \&_kilme;	417	rcv $port, shift \|\| $KILME;
412		418
413	$port	419	$port
414	}	420	}
415		421
416	=item rcv $local_port, $callback->(@msg)	422	=item rcv $local_port, $callback->(@msg)
…		…
421		427
422	The global C<$SELF> (exported by this module) contains C<$port> while	428	The global C<$SELF> (exported by this module) contains C<$port> while
423	executing the callback. Runtime errors during callback execution will	429	executing the callback. Runtime errors during callback execution will
424	result in the port being C<kil>ed.	430	result in the port being C<kil>ed.
425		431
426	The default callback received all messages not matched by a more specific	432	The default callback receives all messages not matched by a more specific
427	C<tag> match.	433	C<tag> match.
428		434
429	=item rcv $local_port, tag => $callback->(@msg_without_tag), ...	435	=item rcv $local_port, tag => $callback->(@msg_without_tag), ...
430		436
431	Register (or replace) callbacks to be called on messages starting with the	437	Register (or replace) callbacks to be called on messages starting with the
…		…
595	$res	601	$res
596	}	602	}
597	}	603	}
598	}	604	}
599		605
		606	=item $guard = mon $port, $rcvport # kill $rcvport when $port dies
		607
		608	=item $guard = mon $port # kill $SELF when $port dies
		609
600	=item $guard = mon $port, $cb->(@reason) # call $cb when $port dies	610	=item $guard = mon $port, $cb->(@reason) # call $cb when $port dies
601
602	=item $guard = mon $port, $rcvport # kill $rcvport when $port dies
603
604	=item $guard = mon $port # kill $SELF when $port dies
605		611
606	=item $guard = mon $port, $rcvport, @msg # send a message when $port dies	612	=item $guard = mon $port, $rcvport, @msg # send a message when $port dies
607		613
608	Monitor the given port and do something when the port is killed or	614	Monitor the given port and do something when the port is killed or
609	messages to it were lost, and optionally return a guard that can be used	615	messages to it were lost, and optionally return a guard that can be used
610	to stop monitoring again.	616	to stop monitoring again.
611		617
		618	The first two forms distinguish between "normal" and "abnormal" kil's:
		619
		620	In the first form (another port given), if the C<$port> is C<kil>'ed with
		621	a non-empty reason, the other port (C<$rcvport>) will be kil'ed with the
		622	same reason. That is, on "normal" kil's nothing happens, while under all
		623	other conditions, the other port is killed with the same reason.
		624
		625	The second form (kill self) is the same as the first form, except that
		626	C<$rvport> defaults to C<$SELF>.
		627
		628	The remaining forms don't distinguish between "normal" and "abnormal" kil's
		629	- it's up to the callback or receiver to check whether the C<@reason> is
		630	empty and act accordingly.
		631
612	In the first form (callback), the callback is simply called with any	632	In the third form (callback), the callback is simply called with any
613	number of C<@reason> elements (no @reason means that the port was deleted	633	number of C<@reason> elements (empty @reason means that the port was deleted
614	"normally"). Note also that I<< the callback B<must> never die >>, so use	634	"normally"). Note also that I<< the callback B<must> never die >>, so use
615	C<eval> if unsure.	635	C<eval> if unsure.
616		636
617	In the second form (another port given), the other port (C<$rcvport>)
618	will be C<kil>'ed with C<@reason>, if a @reason was specified, i.e. on
619	"normal" kils nothing happens, while under all other conditions, the other
620	port is killed with the same reason.
621
622	The third form (kill self) is the same as the second form, except that
623	C<$rvport> defaults to C<$SELF>.
624
625	In the last form (message), a message of the form C<@msg, @reason> will be	637	In the last form (message), a message of the form C<$rcvport, @msg,
626	C<snd>.	638	@reason> will be C<snd>.
627		639
628	Monitoring-actions are one-shot: once messages are lost (and a monitoring	640	Monitoring-actions are one-shot: once messages are lost (and a monitoring
629	alert was raised), they are removed and will not trigger again.	641	alert was raised), they are removed and will not trigger again, even if it
		642	turns out that the port is still alive.
630		643
631	As a rule of thumb, monitoring requests should always monitor a port from	644	As a rule of thumb, monitoring requests should always monitor a remote
632	a local port (or callback). The reason is that kill messages might get	645	port locally (using a local C<$rcvport> or a callback). The reason is that
633	lost, just like any other message. Another less obvious reason is that	646	kill messages might get lost, just like any other message. Another less
634	even monitoring requests can get lost (for example, when the connection	647	obvious reason is that even monitoring requests can get lost (for example,
635	to the other node goes down permanently). When monitoring a port locally	648	when the connection to the other node goes down permanently). When
636	these problems do not exist.	649	monitoring a port locally these problems do not exist.
637		650
638	C<mon> effectively guarantees that, in the absence of hardware failures,	651	C<mon> effectively guarantees that, in the absence of hardware failures,
639	after starting the monitor, either all messages sent to the port will	652	after starting the monitor, either all messages sent to the port will
640	arrive, or the monitoring action will be invoked after possible message	653	arrive, or the monitoring action will be invoked after possible message
641	loss has been detected. No messages will be lost "in between" (after	654	loss has been detected. No messages will be lost "in between" (after
…		…
732	will be reported as reason C<< die => $@ >>.	745	will be reported as reason C<< die => $@ >>.
733		746
734	Transport/communication errors are reported as C<< transport_error =>	747	Transport/communication errors are reported as C<< transport_error =>
735	$message >>.	748	$message >>.
736		749
737	=cut	750	Common idioms:
		751
		752	# silently remove yourself, do not kill linked ports
		753	kil $SELF;
		754
		755	# report a failure in some detail
		756	kil $SELF, failure_mode_1 => "it failed with too high temperature";
		757
		758	# do not waste much time with killing, just die when something goes wrong
		759	open my $fh, "<file"
		760	or die "file: $!";
738		761
739	=item $port = spawn $node, $initfunc[, @initdata]	762	=item $port = spawn $node, $initfunc[, @initdata]
740		763
741	Creates a port on the node C<$node> (which can also be a port ID, in which	764	Creates a port on the node C<$node> (which can also be a port ID, in which
742	case it's the node where that port resides).	765	case it's the node where that port resides).
…		…
894	=back	917	=back
895		918
896	=head1 DISTRIBUTED DATABASE	919	=head1 DISTRIBUTED DATABASE
897		920
898	AnyEvent::MP comes with a simple distributed database. The database will	921	AnyEvent::MP comes with a simple distributed database. The database will
899	be mirrored asynchronously at all global nodes. Other nodes bind to one of	922	be mirrored asynchronously on all global nodes. Other nodes bind to one
900	the global nodes for their needs.	923	of the global nodes for their needs. Every node has a "local database"
		924	which contains all the values that are set locally. All local databases
		925	are merged together to form the global database, which can be queried.
901		926
902	The database consists of a two-level hash - a hash contains a hash which	927	The database structure is that of a two-level hash - the database hash
903	contains values.	928	contains hashes which contain values, similarly to a perl hash of hashes,
		929	i.e.:
		930
		931	$DATABASE{$family}{$subkey} = $value
904		932
905	The top level hash key is called "family", and the second-level hash key	933	The top level hash key is called "family", and the second-level hash key
906	is called "subkey" or simply "key".	934	is called "subkey" or simply "key".
907		935
908	The family must be alphanumeric, i.e. start with a letter and consist	936	The family must be alphanumeric, i.e. start with a letter and consist
…		…
913	with the name of the application or module using it.	941	with the name of the application or module using it.
914		942
915	The subkeys must be non-empty strings, with no further restrictions.	943	The subkeys must be non-empty strings, with no further restrictions.
916		944
917	The values should preferably be strings, but other perl scalars should	945	The values should preferably be strings, but other perl scalars should
918	work as well (such as undef, arrays and hashes).	946	work as well (such as C<undef>, arrays and hashes).
919		947
920	Every database entry is owned by one node - adding the same family/subkey	948	Every database entry is owned by one node - adding the same family/subkey
921	combination on multiple nodes will not cause discomfort for AnyEvent::MP,	949	combination on multiple nodes will not cause discomfort for AnyEvent::MP,
922	but the result might be nondeterministic, i.e. the key might have	950	but the result might be nondeterministic, i.e. the key might have
923	different values on different nodes.	951	different values on different nodes.
…		…
948	If you feel the need to monitor or query a single subkey, try giving it	976	If you feel the need to monitor or query a single subkey, try giving it
949	it's own family.	977	it's own family.
950		978
951	=over	979	=over
952		980
953	=item db_set $family => $subkey [=> $value]	981	=item $guard = db_set $family => $subkey [=> $value]
954		982
955	Sets (or replaces) a key to the database - if C<$value> is omitted,	983	Sets (or replaces) a key to the database - if C<$value> is omitted,
956	C<undef> is used instead.	984	C<undef> is used instead.
957		985
		986	When called in non-void context, C<db_set> returns a guard that
		987	automatically calls C<db_del> when it is destroyed.
		988
958	=item db_del $family => $subkey...	989	=item db_del $family => $subkey...
959		990
960	Deletes one or more subkeys from the database family.	991	Deletes one or more subkeys from the database family.
961		992
962	=item $guard = db_reg $family => $subkey [=> $value]	993	=item $guard = db_reg $family => $port => $value
963		994
964	Sets the key on the database and returns a guard. When the guard is	995	=item $guard = db_reg $family => $port
965	destroyed, the key is deleted from the database. If C<$value> is missing,	996
966	then C<undef> is used.	997	=item $guard = db_reg $family
		998
		999	Registers a port in the given family and optionally returns a guard to
		1000	remove it.
		1001
		1002	This function basically does the same as:
		1003
		1004	db_set $family => $port => $value
		1005
		1006	Except that the port is monitored and automatically removed from the
		1007	database family when it is kil'ed.
		1008
		1009	If C<$value> is missing, C<undef> is used. If C<$port> is missing, then
		1010	C<$SELF> is used.
		1011
		1012	This function is most useful to register a port in some port group (which
		1013	is just another name for a database family), and have it removed when the
		1014	port is gone. This works best when the port is a local port.
		1015
		1016	=cut
		1017
		1018	sub db_reg($$;$) {
		1019	my $family = shift;
		1020	my $port = @_ ? shift : $SELF;
		1021
		1022	my $clr = sub { db_del $family => $port };
		1023	mon $port, $clr;
		1024
		1025	db_set $family => $port => $_[0];
		1026
		1027	defined wantarray
		1028	and &Guard::guard ($clr)
		1029	}
967		1030
968	=item db_family $family => $cb->(\%familyhash)	1031	=item db_family $family => $cb->(\%familyhash)
969		1032
970	Queries the named database C<$family> and call the callback with the	1033	Queries the named database C<$family> and call the callback with the
971	family represented as a hash. You can keep and freely modify the hash.	1034	family represented as a hash. You can keep and freely modify the hash.
…		…
985	Creates a monitor on the given database family. Each time a key is set	1048	Creates a monitor on the given database family. Each time a key is set
986	or or is deleted the callback is called with a hash containing the	1049	or or is deleted the callback is called with a hash containing the
987	database family and three lists of added, changed and deleted subkeys,	1050	database family and three lists of added, changed and deleted subkeys,
988	respectively. If no keys have changed then the array reference might be	1051	respectively. If no keys have changed then the array reference might be
989	C<undef> or even missing.	1052	C<undef> or even missing.
		1053
		1054	If not called in void context, a guard object is returned that, when
		1055	destroyed, stops the monitor.
990		1056
991	The family hash reference and the key arrays belong to AnyEvent::MP and	1057	The family hash reference and the key arrays belong to AnyEvent::MP and
992	B<must not be modified or stored> by the callback. When in doubt, make a	1058	B<must not be modified or stored> by the callback. When in doubt, make a
993	copy.	1059	copy.
994		1060
…		…
1193	Keeping your messages simple, concentrating on data structures rather than	1259	Keeping your messages simple, concentrating on data structures rather than
1194	objects, will keep your messages clean, tidy and efficient.	1260	objects, will keep your messages clean, tidy and efficient.
1195		1261
1196	=back	1262	=back
1197		1263
		1264	=head1 PORTING FROM AnyEvent::MP VERSION 1.X
		1265
		1266	AEMP version 2 has a few major incompatible changes compared to version 1:
		1267
		1268	=over 4
		1269
		1270	=item AnyEvent::MP::Global no longer has group management functions.
		1271
		1272	AnyEvent::MP now comes with a distributed database that is more
		1273	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
		1275	a rough porting guide:
		1276
		1277	grp_reg $group, $port # old
		1278	db_reg $group, $port # new
		1279
		1280	$list = grp_get $group # old
		1281	db_keys $group, sub { my $list = shift } # new
		1282
		1283	grp_mon $group, $cb->(\@ports, $add, $del) # old
		1284	db_mon $group, $cb->(\%ports, $add, $change, $del) # new
		1285
		1286	C<grp_reg> is a no-brainer (just replace by C<db_reg>), but C<grp_get> is
		1287	no longer instant, because the local node might not have a copy of the
		1288	group. You can either modify your code to allow for a callback, or use
		1289	C<db_mon> to keep an updated copy of the group:
		1290
		1291	my $local_group_copy;
		1292	db_mon $group => sub { $local_group_copy = $_[0] };
		1293
		1294	# now "keys %$local_group_copy" always returns the most up-to-date
		1295	# list of ports in the group.
		1296
		1297	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
		1299	ignored:
		1300
		1301	db_mon $group => sub {
		1302	my ($ports, $add, $chg, $lde) = @_;
		1303	$ports = [keys %$ports];
		1304
		1305	# now $ports, $add and $del are the same as
		1306	# were originally passed by grp_mon.
		1307	...
		1308	};
		1309
		1310	=item Nodes not longer connect to all other nodes.
		1311
		1312	In AEMP 1.x, every node automatically loads the L<AnyEvent::MP::Global>
		1313	module, which in turn would create connections to all other nodes in the
		1314	network (helped by the seed nodes).
		1315
		1316	In version 2.x, global nodes still connect to all other global nodes, but
		1317	other nodes don't - now every node either is a global node itself, or
		1318	attaches itself to another global node.
		1319
		1320	If a node isn't a global node itself, then it attaches itself to one
		1321	of its seed nodes. If that seed node isn't a global node yet, it will
		1322	automatically be upgraded to a global node.
		1323
		1324	So in many cases, nothing needs to be changed - one just has to make sure
		1325	that all seed nodes are meshed together with the other seed nodes (as with
		1326	AEMP 1.x), and other nodes specify them as seed nodes. This is most easily
		1327	achieved by specifying the same set of seed nodes for all nodes in the
		1328	network.
		1329
		1330	Not opening a connection to every other node is usually an advantage,
		1331	except when you need the lower latency of an already established
		1332	connection. To ensure a node establishes a connection to another node,
		1333	you can monitor the node port (C<mon $node, ...>), which will attempt to
		1334	create the connection (and notify you when the connection fails).
		1335
		1336	=item Listener-less nodes (nodes without binds) are gone.
		1337
		1338	And are not coming back, at least not in their old form. If no C<binds>
		1339	are specified for a node, AnyEvent::MP assumes a default of C<:>.
		1340
		1341	There are vague plans to implement some form of routing domains, which
		1342	might or might not bring back listener-less nodes, but don't count on it.
		1343
		1344	The fact that most connections are now optional somewhat mitigates this,
		1345	as a node can be effectively unreachable from the outside without any
		1346	problems, as long as it isn't a global node and only reaches out to other
		1347	nodes (as opposed to being contacted from other nodes).
		1348
		1349	=item $AnyEvent::MP::Kernel::WARN has gone.
		1350
		1351	AnyEvent has acquired a logging framework (L<AnyEvent::Log>), and AEMP now
		1352	uses this, and so should your programs.
		1353
		1354	Every module now documents what kinds of messages it generates, with
		1355	AnyEvent::MP acting as a catch all.
		1356
		1357	On the positive side, this means that instead of setting
		1358	C<PERL_ANYEVENT_MP_WARNLEVEL>, you can get away by setting C<AE_VERBOSE> -
		1359	much less to type.
		1360
		1361	=back
		1362
		1363	=head1 LOGGING
		1364
		1365	AnyEvent::MP does not normally log anything by itself, but sinc eit is the
		1366	root of the contetx hierarchy for AnyEvent::MP modules, it will receive
		1367	all log messages by submodules.
		1368
1198	=head1 SEE ALSO	1369	=head1 SEE ALSO
1199		1370
1200	L<AnyEvent::MP::Intro> - a gentle introduction.	1371	L<AnyEvent::MP::Intro> - a gentle introduction.
1201		1372
1202	L<AnyEvent::MP::Kernel> - more, lower-level, stuff.	1373	L<AnyEvent::MP::Kernel> - more, lower-level, stuff.

Diff Legend

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

Comparing AnyEvent-MP/MP.pm (file contents): Revision 1.130 by root, Fri Mar 9 17:05:26 2012 UTC vs. Revision 1.139 by root, Thu Mar 22 20:07:31 2012 UTC

Diff Legend

Comparing AnyEvent-MP/MP.pm (file contents):
Revision 1.130 by root, Fri Mar 9 17:05:26 2012 UTC vs.
Revision 1.139 by root, Thu Mar 22 20:07:31 2012 UTC