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

Comparing AnyEvent-MP/MP.pm (file contents):
Revision 1.136 by root, Wed Mar 21 15:22:16 2012 UTC vs.
Revision 1.139 by root, Thu Mar 22 20:07:31 2012 UTC

…		…
601	$res	601	$res
602	}	602	}
603	}	603	}
604	}	604	}
605		605
		606	=item $guard = mon $port, $rcvport # kill $rcvport when $port dies
		607
		608	=item $guard = mon $port # kill $SELF when $port dies
		609
606	=item $guard = mon $port, $cb->(@reason) # call $cb when $port dies	610	=item $guard = mon $port, $cb->(@reason) # call $cb when $port dies
607
608	=item $guard = mon $port, $rcvport # kill $rcvport when $port dies
609
610	=item $guard = mon $port # kill $SELF when $port dies
611		611
612	=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
613		613
614	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
615	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
616	to stop monitoring again.	616	to stop monitoring again.
617		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
618	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
619	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
620	"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
621	C<eval> if unsure.	635	C<eval> if unsure.
622		636
623	In the second form (another port given), the other port (C<$rcvport>)
624	will be C<kil>'ed with C<@reason>, if a @reason was specified, i.e. on
625	"normal" kils nothing happens, while under all other conditions, the other
626	port is killed with the same reason.
627
628	The third form (kill self) is the same as the second form, except that
629	C<$rvport> defaults to C<$SELF>.
630
631	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,
632	C<snd>.	638	@reason> will be C<snd>.
633		639
634	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
635	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.
636		643
637	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
638	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
639	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
640	even monitoring requests can get lost (for example, when the connection	647	obvious reason is that even monitoring requests can get lost (for example,
641	to the other node goes down permanently). When monitoring a port locally	648	when the connection to the other node goes down permanently). When
642	these problems do not exist.	649	monitoring a port locally these problems do not exist.
643		650
644	C<mon> effectively guarantees that, in the absence of hardware failures,	651	C<mon> effectively guarantees that, in the absence of hardware failures,
645	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
646	arrive, or the monitoring action will be invoked after possible message	653	arrive, or the monitoring action will be invoked after possible message
647	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
…		…
969	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
970	it's own family.	977	it's own family.
971		978
972	=over	979	=over
973		980
974	=item db_set $family => $subkey [=> $value]	981	=item $guard = db_set $family => $subkey [=> $value]
975		982
976	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,
977	C<undef> is used instead.	984	C<undef> is used instead.
978		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
979	=item db_del $family => $subkey...	989	=item db_del $family => $subkey...
980		990
981	Deletes one or more subkeys from the database family.	991	Deletes one or more subkeys from the database family.
982		992
983	=item $guard = db_reg $family => $subkey [=> $value]	993	=item $guard = db_reg $family => $port => $value
984		994
985	Sets the key on the database and returns a guard. When the guard is	995	=item $guard = db_reg $family => $port
986	destroyed, the key is deleted from the database. If C<$value> is missing,	996
987	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	}
988		1030
989	=item db_family $family => $cb->(\%familyhash)	1031	=item db_family $family => $cb->(\%familyhash)
990		1032
991	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
992	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.
…		…
1217	Keeping your messages simple, concentrating on data structures rather than	1259	Keeping your messages simple, concentrating on data structures rather than
1218	objects, will keep your messages clean, tidy and efficient.	1260	objects, will keep your messages clean, tidy and efficient.
1219		1261
1220	=back	1262	=back
1221		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
1222	=head1 SEE ALSO	1369	=head1 SEE ALSO
1223		1370
1224	L<AnyEvent::MP::Intro> - a gentle introduction.	1371	L<AnyEvent::MP::Intro> - a gentle introduction.
1225		1372
1226	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.136 by root, Wed Mar 21 15:22:16 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.136 by root, Wed Mar 21 15:22:16 2012 UTC vs.
Revision 1.139 by root, Thu Mar 22 20:07:31 2012 UTC