[ViewVC] Diff of: cvs/AnyEvent/lib/AnyEvent.pm

Comparing AnyEvent/lib/AnyEvent.pm (file contents):
Revision 1.305 by root, Sun Dec 13 05:13:15 2009 UTC vs.
Revision 1.327 by root, Sun Jun 6 10:13:57 2010 UTC

…		…
7		7
8	=head1 SYNOPSIS	8	=head1 SYNOPSIS
9		9
10	use AnyEvent;	10	use AnyEvent;
11		11
		12	# if you prefer function calls, look at the AE manpage for
		13	# an alternative API.
		14
12	# file descriptor readable	15	# file handle or descriptor readable
13	my $w = AnyEvent->io (fh => $fh, poll => "r", cb => sub { ... });	16	my $w = AnyEvent->io (fh => $fh, poll => "r", cb => sub { ... });
14		17
15	# one-shot or repeating timers	18	# one-shot or repeating timers
16	my $w = AnyEvent->timer (after => $seconds, cb => sub { ... });	19	my $w = AnyEvent->timer (after => $seconds, cb => sub { ... });
17	my $w = AnyEvent->timer (after => $seconds, interval => $seconds, cb => ...	20	my $w = AnyEvent->timer (after => $seconds, interval => $seconds, cb => ...
…		…
503		506
504	=head2 IDLE WATCHERS	507	=head2 IDLE WATCHERS
505		508
506	$w = AnyEvent->idle (cb => <callback>);	509	$w = AnyEvent->idle (cb => <callback>);
507		510
508	Sometimes there is a need to do something, but it is not so important	511	Repeatedly invoke the callback after the process becomes idle, until
509	to do it instantly, but only when there is nothing better to do. This	512	either the watcher is destroyed or new events have been detected.
510	"nothing better to do" is usually defined to be "no other events need
511	attention by the event loop".
512		513
513	Idle watchers ideally get invoked when the event loop has nothing	514	Idle watchers are useful when there is a need to do something, but it
514	better to do, just before it would block the process to wait for new	515	is not so important (or wise) to do it instantly. The callback will be
515	events. Instead of blocking, the idle watcher is invoked.	516	invoked only when there is "nothing better to do", which is usually
		517	defined as "all outstanding events have been handled and no new events
		518	have been detected". That means that idle watchers ideally get invoked
		519	when the event loop has just polled for new events but none have been
		520	detected. Instead of blocking to wait for more events, the idle watchers
		521	will be invoked.
516		522
517	Most event loops unfortunately do not really support idle watchers (only	523	Unfortunately, most event loops do not really support idle watchers (only
518	EV, Event and Glib do it in a usable fashion) - for the rest, AnyEvent	524	EV, Event and Glib do it in a usable fashion) - for the rest, AnyEvent
519	will simply call the callback "from time to time".	525	will simply call the callback "from time to time".
520		526
521	Example: read lines from STDIN, but only process them when the	527	Example: read lines from STDIN, but only process them when the
522	program is otherwise idle:	528	program is otherwise idle:
…		…
550	will actively watch for new events and call your callbacks.	556	will actively watch for new events and call your callbacks.
551		557
552	AnyEvent is slightly different: it expects somebody else to run the event	558	AnyEvent is slightly different: it expects somebody else to run the event
553	loop and will only block when necessary (usually when told by the user).	559	loop and will only block when necessary (usually when told by the user).
554		560
555	The instrument to do that is called a "condition variable", so called	561	The tool to do that is called a "condition variable", so called because
556	because they represent a condition that must become true.	562	they represent a condition that must become true.
557		563
558	Now is probably a good time to look at the examples further below.	564	Now is probably a good time to look at the examples further below.
559		565
560	Condition variables can be created by calling the C<< AnyEvent->condvar	566	Condition variables can be created by calling the C<< AnyEvent->condvar
561	>> method, usually without arguments. The only argument pair allowed is	567	>> method, usually without arguments. The only argument pair allowed is
…		…
566	After creation, the condition variable is "false" until it becomes "true"	572	After creation, the condition variable is "false" until it becomes "true"
567	by calling the C<send> method (or calling the condition variable as if it	573	by calling the C<send> method (or calling the condition variable as if it
568	were a callback, read about the caveats in the description for the C<<	574	were a callback, read about the caveats in the description for the C<<
569	->send >> method).	575	->send >> method).
570		576
571	Condition variables are similar to callbacks, except that you can	577	Since condition variables are the most complex part of the AnyEvent API, here are
572	optionally wait for them. They can also be called merge points - points	578	some different mental models of what they are - pick the ones you can connect to:
573	in time where multiple outstanding events have been processed. And yet	579
574	another way to call them is transactions - each condition variable can be	580	=over 4
575	used to represent a transaction, which finishes at some point and delivers	581
576	a result. And yet some people know them as "futures" - a promise to	582	=item * Condition variables are like callbacks - you can call them (and pass them instead
577	compute/deliver something that you can wait for.	583	of callbacks). Unlike callbacks however, you can also wait for them to be called.
		584
		585	=item * Condition variables are signals - one side can emit or send them,
		586	the other side can wait for them, or install a handler that is called when
		587	the signal fires.
		588
		589	=item * Condition variables are like "Merge Points" - points in your program
		590	where you merge multiple independent results/control flows into one.
		591
		592	=item * Condition variables represent a transaction - function that start
		593	some kind of transaction can return them, leaving the caller the choice
		594	between waiting in a blocking fashion, or setting a callback.
		595
		596	=item * Condition variables represent future values, or promises to deliver
		597	some result, long before the result is available.
		598
		599	=back
578		600
579	Condition variables are very useful to signal that something has finished,	601	Condition variables are very useful to signal that something has finished,
580	for example, if you write a module that does asynchronous http requests,	602	for example, if you write a module that does asynchronous http requests,
581	then a condition variable would be the ideal candidate to signal the	603	then a condition variable would be the ideal candidate to signal the
582	availability of results. The user can either act when the callback is	604	availability of results. The user can either act when the callback is
…		…
603	eventually calls C<< -> send >>, and the "consumer side", which waits	625	eventually calls C<< -> send >>, and the "consumer side", which waits
604	for the send to occur.	626	for the send to occur.
605		627
606	Example: wait for a timer.	628	Example: wait for a timer.
607		629
608	# wait till the result is ready	630	# condition: "wait till the timer is fired"
609	my $result_ready = AnyEvent->condvar;	631	my $timer_fired = AnyEvent->condvar;
610		632
611	# do something such as adding a timer	633	# create the timer - we could wait for, say
612	# or socket watcher the calls $result_ready->send	634	# a handle becomign ready, or even an
613	# when the "result" is ready.	635	# AnyEvent::HTTP request to finish, but
614	# in this case, we simply use a timer:	636	# in this case, we simply use a timer:
615	my $w = AnyEvent->timer (	637	my $w = AnyEvent->timer (
616	after => 1,	638	after => 1,
617	cb => sub { $result_ready->send },	639	cb => sub { $timer_fired->send },
618	);	640	);
619		641
620	# this "blocks" (while handling events) till the callback	642	# this "blocks" (while handling events) till the callback
621	# calls ->send	643	# calls ->send
622	$result_ready->recv;	644	$timer_fired->recv;
623		645
624	Example: wait for a timer, but take advantage of the fact that condition	646	Example: wait for a timer, but take advantage of the fact that condition
625	variables are also callable directly.	647	variables are also callable directly.
626		648
627	my $done = AnyEvent->condvar;	649	my $done = AnyEvent->condvar;
…		…
1051	=head1 OTHER MODULES	1073	=head1 OTHER MODULES
1052		1074
1053	The following is a non-exhaustive list of additional modules that use	1075	The following is a non-exhaustive list of additional modules that use
1054	AnyEvent as a client and can therefore be mixed easily with other AnyEvent	1076	AnyEvent as a client and can therefore be mixed easily with other AnyEvent
1055	modules and other event loops in the same program. Some of the modules	1077	modules and other event loops in the same program. Some of the modules
1056	come with AnyEvent, most are available via CPAN.	1078	come as part of AnyEvent, the others are available via CPAN.
1057		1079
1058	=over 4	1080	=over 4
1059		1081
1060	=item L<AnyEvent::Util>	1082	=item L<AnyEvent::Util>
1061		1083
…		…
1076		1098
1077	=item L<AnyEvent::DNS>	1099	=item L<AnyEvent::DNS>
1078		1100
1079	Provides rich asynchronous DNS resolver capabilities.	1101	Provides rich asynchronous DNS resolver capabilities.
1080		1102
		1103	=item L<AnyEvent::HTTP>, L<AnyEvent::IRC>, L<AnyEvent::XMPP>, L<AnyEvent::GPSD>, L<AnyEvent::IGS>, L<AnyEvent::FCP>
		1104
		1105	Implement event-based interfaces to the protocols of the same name (for
		1106	the curious, IGS is the International Go Server and FCP is the Freenet
		1107	Client Protocol).
		1108
		1109	=item L<AnyEvent::Handle::UDP>
		1110
		1111	Here be danger!
		1112
		1113	As Pauli would put it, "Not only is it not right, it's not even wrong!" -
		1114	there are so many things wrong with AnyEvent::Handle::UDP, most notably
		1115	it's use of a stream-based API with a protocol that isn't streamable, that
		1116	the only way to improve it is to delete it.
		1117
		1118	It features data corruption (but typically only under load) and general
		1119	confusion. On top, the author is not only clueless about UDP but also
		1120	fact-resistant - some gems of his understanding: "connect doesn't work
		1121	with UDP", "UDP packets are not IP packets", "UDP only has datagrams, not
		1122	packets", "I don't need to implement proper error checking as UDP doesn't
		1123	support error checking" and so on - he doesn't even understand what's
		1124	wrong with his module when it is explained to him.
		1125
1081	=item L<AnyEvent::HTTP>	1126	=item L<AnyEvent::DBI>
1082		1127
1083	A simple-to-use HTTP library that is capable of making a lot of concurrent	1128	Executes L<DBI> requests asynchronously in a proxy process for you,
1084	HTTP requests.	1129	notifying you in an event-bnased way when the operation is finished.
		1130
		1131	=item L<AnyEvent::AIO>
		1132
		1133	Truly asynchronous (as opposed to non-blocking) I/O, should be in the
		1134	toolbox of every event programmer. AnyEvent::AIO transparently fuses
		1135	L<IO::AIO> and AnyEvent together, giving AnyEvent access to event-based
		1136	file I/O, and much more.
1085		1137
1086	=item L<AnyEvent::HTTPD>	1138	=item L<AnyEvent::HTTPD>
1087		1139
1088	Provides a simple web application server framework.	1140	A simple embedded webserver.
1089		1141
1090	=item L<AnyEvent::FastPing>	1142	=item L<AnyEvent::FastPing>
1091		1143
1092	The fastest ping in the west.	1144	The fastest ping in the west.
1093
1094	=item L<AnyEvent::DBI>
1095
1096	Executes L<DBI> requests asynchronously in a proxy process.
1097
1098	=item L<AnyEvent::AIO>
1099
1100	Truly asynchronous I/O, should be in the toolbox of every event
1101	programmer. AnyEvent::AIO transparently fuses L<IO::AIO> and AnyEvent
1102	together.
1103
1104	=item L<AnyEvent::BDB>
1105
1106	Truly asynchronous Berkeley DB access. AnyEvent::BDB transparently fuses
1107	L<BDB> and AnyEvent together.
1108
1109	=item L<AnyEvent::GPSD>
1110
1111	A non-blocking interface to gpsd, a daemon delivering GPS information.
1112
1113	=item L<AnyEvent::IRC>
1114
1115	AnyEvent based IRC client module family (replacing the older Net::IRC3).
1116
1117	=item L<AnyEvent::XMPP>
1118
1119	AnyEvent based XMPP (Jabber protocol) module family (replacing the older
1120	Net::XMPP2>.
1121
1122	=item L<AnyEvent::IGS>
1123
1124	A non-blocking interface to the Internet Go Server protocol (used by
1125	L<App::IGS>).
1126
1127	=item L<Net::FCP>
1128
1129	AnyEvent-based implementation of the Freenet Client Protocol, birthplace
1130	of AnyEvent.
1131
1132	=item L<Event::ExecFlow>
1133
1134	High level API for event-based execution flow control.
1135		1145
1136	=item L<Coro>	1146	=item L<Coro>
1137		1147
1138	Has special support for AnyEvent via L<Coro::AnyEvent>.	1148	Has special support for AnyEvent via L<Coro::AnyEvent>.
1139		1149
…		…
1145		1155
1146	# basically a tuned-down version of common::sense	1156	# basically a tuned-down version of common::sense
1147	sub common_sense {	1157	sub common_sense {
1148	# from common:.sense 1.0	1158	# from common:.sense 1.0
1149	${^WARNING_BITS} = "\xfc\x3f\x33\x00\x0f\xf3\xcf\xc0\xf3\xfc\x33\x00";	1159	${^WARNING_BITS} = "\xfc\x3f\x33\x00\x0f\xf3\xcf\xc0\xf3\xfc\x33\x00";
1150	# use strict vars subs	1160	# use strict vars subs - NO UTF-8, as Util.pm doesn't like this atm. (uts46data.pl)
1151	$^H \|= 0x00000600;	1161	$^H \|= 0x00000600;
1152	}	1162	}
1153		1163
1154	BEGIN { AnyEvent::common_sense }	1164	BEGIN { AnyEvent::common_sense }
1155		1165
1156	use Carp ();	1166	use Carp ();
1157		1167
1158	our $VERSION = '5.22';	1168	our $VERSION = '5.27';
1159	our $MODEL;	1169	our $MODEL;
1160		1170
1161	our $AUTOLOAD;	1171	our $AUTOLOAD;
1162	our @ISA;	1172	our @ISA;
1163		1173
1164	our @REGISTRY;	1174	our @REGISTRY;
1165		1175
1166	our $VERBOSE;	1176	our $VERBOSE;
1167		1177
1168	BEGIN {	1178	BEGIN {
1169	eval "sub WIN32(){ " . (($^O =~ /mswin32/i)*1) ." }";	1179	require "AnyEvent/constants.pl";
		1180
1170	eval "sub TAINT(){ " . (${^TAINT}*1) . " }";	1181	eval "sub TAINT (){" . (${^TAINT}*1) . "}";
1171		1182
1172	delete @ENV{grep /^PERL_ANYEVENT_/, keys %ENV}	1183	delete @ENV{grep /^PERL_ANYEVENT_/, keys %ENV}
1173	if ${^TAINT};	1184	if ${^TAINT};
1174		1185
1175	$VERBOSE = $ENV{PERL_ANYEVENT_VERBOSE}*1;	1186	$VERBOSE = $ENV{PERL_ANYEVENT_VERBOSE}*1;
…		…
1218	our @post_detect;	1229	our @post_detect;
1219		1230
1220	sub post_detect(&) {	1231	sub post_detect(&) {
1221	my ($cb) = @_;	1232	my ($cb) = @_;
1222		1233
1223	if ($MODEL) {
1224	$cb->();
1225
1226	undef
1227	} else {
1228	push @post_detect, $cb;	1234	push @post_detect, $cb;
1229		1235
1230	defined wantarray	1236	defined wantarray
1231	? bless \$cb, "AnyEvent::Util::postdetect"	1237	? bless \$cb, "AnyEvent::Util::postdetect"
1232	: ()	1238	: ()
1233	}
1234	}	1239	}
1235		1240
1236	sub AnyEvent::Util::postdetect::DESTROY {	1241	sub AnyEvent::Util::postdetect::DESTROY {
1237	@post_detect = grep $_ != ${$_[0]}, @post_detect;	1242	@post_detect = grep $_ != ${$_[0]}, @post_detect;
1238	}	1243	}
1239		1244
1240	sub detect() {	1245	sub detect() {
		1246	# free some memory
		1247	*detect = sub () { $MODEL };
		1248
		1249	local $!; # for good measure
		1250	local $SIG{__DIE__};
		1251
		1252	if ($ENV{PERL_ANYEVENT_MODEL} =~ /^([a-zA-Z]+)$/) {
		1253	my $model = "AnyEvent::Impl::$1";
		1254	if (eval "require $model") {
		1255	$MODEL = $model;
		1256	warn "AnyEvent: loaded model '$model' (forced by \$ENV{PERL_ANYEVENT_MODEL}), using it.\n" if $VERBOSE >= 2;
		1257	} else {
		1258	warn "AnyEvent: unable to load model '$model' (from \$ENV{PERL_ANYEVENT_MODEL}):\n$@" if $VERBOSE;
		1259	}
		1260	}
		1261
		1262	# check for already loaded models
1241	unless ($MODEL) {	1263	unless ($MODEL) {
1242	local $SIG{__DIE__};	1264	for (@REGISTRY, @models) {
1243		1265	my ($package, $model) = @$_;
1244	if ($ENV{PERL_ANYEVENT_MODEL} =~ /^([a-zA-Z]+)$/) {	1266	if (${"$package\::VERSION"} > 0) {
1245	my $model = "AnyEvent::Impl::$1";
1246	if (eval "require $model") {	1267	if (eval "require $model") {
1247	$MODEL = $model;	1268	$MODEL = $model;
1248	warn "AnyEvent: loaded model '$model' (forced by \$ENV{PERL_ANYEVENT_MODEL}), using it.\n" if $VERBOSE >= 2;	1269	warn "AnyEvent: autodetected model '$model', using it.\n" if $VERBOSE >= 2;
1249	} else {	1270	last;
1250	warn "AnyEvent: unable to load model '$model' (from \$ENV{PERL_ANYEVENT_MODEL}):\n$@" if $VERBOSE;	1271	}
1251	}	1272	}
1252	}	1273	}
1253		1274
1254	# check for already loaded models
1255	unless ($MODEL) {	1275	unless ($MODEL) {
		1276	# try to autoload a model
1256	for (@REGISTRY, @models) {	1277	for (@REGISTRY, @models) {
1257	my ($package, $model) = @$_;	1278	my ($package, $model, $autoload) = @$_;
		1279	if (
		1280	$autoload
		1281	and eval "require $package"
1258	if (${"$package\::VERSION"} > 0) {	1282	and ${"$package\::VERSION"} > 0
1259	if (eval "require $model") {	1283	and eval "require $model"
		1284	) {
1260	$MODEL = $model;	1285	$MODEL = $model;
1261	warn "AnyEvent: autodetected model '$model', using it.\n" if $VERBOSE >= 2;	1286	warn "AnyEvent: autoloaded model '$model', using it.\n" if $VERBOSE >= 2;
1262	last;	1287	last;
1263	}
1264	}	1288	}
1265	}	1289	}
1266		1290
1267	unless ($MODEL) {
1268	# try to autoload a model
1269	for (@REGISTRY, @models) {
1270	my ($package, $model, $autoload) = @$_;
1271	if (
1272	$autoload
1273	and eval "require $package"
1274	and ${"$package\::VERSION"} > 0
1275	and eval "require $model"
1276	) {
1277	$MODEL = $model;
1278	warn "AnyEvent: autoloaded model '$model', using it.\n" if $VERBOSE >= 2;
1279	last;
1280	}
1281	}
1282
1283	$MODEL	1291	$MODEL
1284	or die "No event module selected for AnyEvent and autodetect failed. Install any one of these modules: EV, Event or Glib.\n";	1292	or die "No event module selected for AnyEvent and autodetect failed. Install any one of these modules: EV, Event or Glib.\n";
1285	}
1286	}	1293	}
1287
1288	push @{"$MODEL\::ISA"}, "AnyEvent::Base";
1289
1290	unshift @ISA, $MODEL;
1291
1292	require AnyEvent::Strict if $ENV{PERL_ANYEVENT_STRICT};
1293
1294	(shift @post_detect)->() while @post_detect;
1295	}	1294	}
		1295
		1296	@models = (); # free probe data
		1297
		1298	push @{"$MODEL\::ISA"}, "AnyEvent::Base";
		1299	unshift @ISA, $MODEL;
		1300
		1301	# now nuke some methods that are overriden by the backend.
		1302	# SUPER is not allowed.
		1303	for (qw(time signal child idle)) {
		1304	undef &{"AnyEvent::Base::$_"}
		1305	if defined &{"$MODEL\::$_"};
		1306	}
		1307
		1308	require AnyEvent::Strict if $ENV{PERL_ANYEVENT_STRICT};
		1309
		1310	(shift @post_detect)->() while @post_detect;
		1311
		1312	*post_detect = sub(&) {
		1313	shift->();
		1314
		1315	undef
		1316	};
1296		1317
1297	$MODEL	1318	$MODEL
1298	}	1319	}
1299		1320
1300	sub AUTOLOAD {	1321	sub AUTOLOAD {
1301	(my $func = $AUTOLOAD) =~ s/.*://;	1322	(my $func = $AUTOLOAD) =~ s/.*://;
1302		1323
1303	$method{$func}	1324	$method{$func}
1304	or Carp::croak "$func: not a valid method for AnyEvent objects";	1325	or Carp::croak "$func: not a valid AnyEvent class method";
1305		1326
1306	detect unless $MODEL;	1327	detect;
1307		1328
1308	my $class = shift;	1329	my $class = shift;
1309	$class->$func (@_);	1330	$class->$func (@_);
1310	}	1331	}
1311		1332
…		…
1328		1349
1329	=head1 SIMPLIFIED AE API	1350	=head1 SIMPLIFIED AE API
1330		1351
1331	Starting with version 5.0, AnyEvent officially supports a second, much	1352	Starting with version 5.0, AnyEvent officially supports a second, much
1332	simpler, API that is designed to reduce the calling, typing and memory	1353	simpler, API that is designed to reduce the calling, typing and memory
1333	overhead.	1354	overhead by using function call syntax and a fixed number of parameters.
1334		1355
1335	See the L<AE> manpage for details.	1356	See the L<AE> manpage for details.
1336		1357
1337	=cut	1358	=cut
1338		1359
1339	package AE;	1360	package AE;
1340		1361
1341	our $VERSION = $AnyEvent::VERSION;	1362	our $VERSION = $AnyEvent::VERSION;
		1363
		1364	# fall back to the main API by default - backends and AnyEvent::Base
		1365	# implementations can overwrite these.
1342		1366
1343	sub io($$$) {	1367	sub io($$$) {
1344	AnyEvent->io (fh => $_[0], poll => $_[1] ? "w" : "r", cb => $_[2])	1368	AnyEvent->io (fh => $_[0], poll => $_[1] ? "w" : "r", cb => $_[2])
1345	}	1369	}
1346		1370
…		…
1378		1402
1379	package AnyEvent::Base;	1403	package AnyEvent::Base;
1380		1404
1381	# default implementations for many methods	1405	# default implementations for many methods
1382		1406
1383	sub _time() {	1407	sub time {
		1408	eval q{ # poor man's autoloading {}
1384	# probe for availability of Time::HiRes	1409	# probe for availability of Time::HiRes
1385	if (eval "use Time::HiRes (); Time::HiRes::time (); 1") {	1410	if (eval "use Time::HiRes (); Time::HiRes::time (); 1") {
1386	warn "AnyEvent: using Time::HiRes for sub-second timing accuracy.\n" if $VERBOSE >= 8;	1411	warn "AnyEvent: using Time::HiRes for sub-second timing accuracy.\n" if $VERBOSE >= 8;
1387	*_time = \&Time::HiRes::time;	1412	*AE::time = \&Time::HiRes::time;
1388	# if (eval "use POSIX (); (POSIX::times())...	1413	# if (eval "use POSIX (); (POSIX::times())...
1389	} else {	1414	} else {
1390	warn "AnyEvent: using built-in time(), WARNING, no sub-second resolution!\n" if $VERBOSE;	1415	warn "AnyEvent: using built-in time(), WARNING, no sub-second resolution!\n" if $VERBOSE;
1391	*_time = sub { time }; # epic fail	1416	*AE::time = sub (){ time }; # epic fail
		1417	}
		1418
		1419	*time = sub { AE::time }; # different prototypes
1392	}	1420	};
		1421	die if $@;
1393		1422
1394	&_time	1423	&time
1395	}	1424	}
1396		1425
1397	sub time { _time }	1426	*now = \&time;
1398	sub now { _time }	1427
1399	sub now_update { }	1428	sub now_update { }
1400		1429
1401	# default implementation for ->condvar	1430	# default implementation for ->condvar
1402		1431
1403	sub condvar {	1432	sub condvar {
		1433	eval q{ # poor man's autoloading {}
		1434	*condvar = sub {
1404	bless { @_ == 3 ? (_ae_cb => $_[2]) : () }, "AnyEvent::CondVar"	1435	bless { @_ == 3 ? (_ae_cb => $_[2]) : () }, "AnyEvent::CondVar"
		1436	};
		1437
		1438	*AE::cv = sub (;&) {
		1439	bless { @_ ? (_ae_cb => shift) : () }, "AnyEvent::CondVar"
		1440	};
		1441	};
		1442	die if $@;
		1443
		1444	&condvar
1405	}	1445	}
1406		1446
1407	# default implementation for ->signal	1447	# default implementation for ->signal
1408		1448
1409	our $HAVE_ASYNC_INTERRUPT;	1449	our $HAVE_ASYNC_INTERRUPT;
…		…
1418		1458
1419	our ($SIGPIPE_R, $SIGPIPE_W, %SIG_CB, %SIG_EV, $SIG_IO);	1459	our ($SIGPIPE_R, $SIGPIPE_W, %SIG_CB, %SIG_EV, $SIG_IO);
1420	our (%SIG_ASY, %SIG_ASY_W);	1460	our (%SIG_ASY, %SIG_ASY_W);
1421	our ($SIG_COUNT, $SIG_TW);	1461	our ($SIG_COUNT, $SIG_TW);
1422		1462
1423	sub _signal_exec {
1424	$HAVE_ASYNC_INTERRUPT
1425	? $SIGPIPE_R->drain
1426	: sysread $SIGPIPE_R, (my $dummy), 9;
1427
1428	while (%SIG_EV) {
1429	for (keys %SIG_EV) {
1430	delete $SIG_EV{$_};
1431	$_->() for values %{ $SIG_CB{$_} \|\| {} };
1432	}
1433	}
1434	}
1435
1436	# install a dummy wakeup watcher to reduce signal catching latency	1463	# install a dummy wakeup watcher to reduce signal catching latency
		1464	# used by Impls
1437	sub _sig_add() {	1465	sub _sig_add() {
1438	unless ($SIG_COUNT++) {	1466	unless ($SIG_COUNT++) {
1439	# try to align timer on a full-second boundary, if possible	1467	# try to align timer on a full-second boundary, if possible
1440	my $NOW = AE::now;	1468	my $NOW = AE::now;
1441		1469
…		…
1451	undef $SIG_TW	1479	undef $SIG_TW
1452	unless --$SIG_COUNT;	1480	unless --$SIG_COUNT;
1453	}	1481	}
1454		1482
1455	our $_sig_name_init; $_sig_name_init = sub {	1483	our $_sig_name_init; $_sig_name_init = sub {
1456	eval q{ # poor man's autoloading	1484	eval q{ # poor man's autoloading {}
1457	undef $_sig_name_init;	1485	undef $_sig_name_init;
1458		1486
1459	if (_have_async_interrupt) {	1487	if (_have_async_interrupt) {
1460	*sig2num = \&Async::Interrupt::sig2num;	1488	*sig2num = \&Async::Interrupt::sig2num;
1461	*sig2name = \&Async::Interrupt::sig2name;	1489	*sig2name = \&Async::Interrupt::sig2name;
…		…
1493	$SIG_IO = AE::io $SIGPIPE_R->fileno, 0, \&_signal_exec;	1521	$SIG_IO = AE::io $SIGPIPE_R->fileno, 0, \&_signal_exec;
1494		1522
1495	} else {	1523	} else {
1496	warn "AnyEvent: using emulated perl signal handling with latency timer.\n" if $VERBOSE >= 8;	1524	warn "AnyEvent: using emulated perl signal handling with latency timer.\n" if $VERBOSE >= 8;
1497		1525
1498	require Fcntl;
1499
1500	if (AnyEvent::WIN32) {	1526	if (AnyEvent::WIN32) {
1501	require AnyEvent::Util;	1527	require AnyEvent::Util;
1502		1528
1503	($SIGPIPE_R, $SIGPIPE_W) = AnyEvent::Util::portable_pipe ();	1529	($SIGPIPE_R, $SIGPIPE_W) = AnyEvent::Util::portable_pipe ();
1504	AnyEvent::Util::fh_nonblocking ($SIGPIPE_R, 1) if $SIGPIPE_R;	1530	AnyEvent::Util::fh_nonblocking ($SIGPIPE_R, 1) if $SIGPIPE_R;
1505	AnyEvent::Util::fh_nonblocking ($SIGPIPE_W, 1) if $SIGPIPE_W; # just in case	1531	AnyEvent::Util::fh_nonblocking ($SIGPIPE_W, 1) if $SIGPIPE_W; # just in case
1506	} else {	1532	} else {
1507	pipe $SIGPIPE_R, $SIGPIPE_W;	1533	pipe $SIGPIPE_R, $SIGPIPE_W;
1508	fcntl $SIGPIPE_R, &Fcntl::F_SETFL, &Fcntl::O_NONBLOCK if $SIGPIPE_R;	1534	fcntl $SIGPIPE_R, AnyEvent::F_SETFL, AnyEvent::O_NONBLOCK if $SIGPIPE_R;
1509	fcntl $SIGPIPE_W, &Fcntl::F_SETFL, &Fcntl::O_NONBLOCK if $SIGPIPE_W; # just in case	1535	fcntl $SIGPIPE_W, AnyEvent::F_SETFL, AnyEvent::O_NONBLOCK if $SIGPIPE_W; # just in case
1510		1536
1511	# not strictly required, as $^F is normally 2, but let's make sure...	1537	# not strictly required, as $^F is normally 2, but let's make sure...
1512	fcntl $SIGPIPE_R, &Fcntl::F_SETFD, &Fcntl::FD_CLOEXEC;	1538	fcntl $SIGPIPE_R, AnyEvent::F_SETFD, AnyEvent::FD_CLOEXEC;
1513	fcntl $SIGPIPE_W, &Fcntl::F_SETFD, &Fcntl::FD_CLOEXEC;	1539	fcntl $SIGPIPE_W, AnyEvent::F_SETFD, AnyEvent::FD_CLOEXEC;
1514	}	1540	}
1515		1541
1516	$SIGPIPE_R	1542	$SIGPIPE_R
1517	or Carp::croak "AnyEvent: unable to create a signal reporting pipe: $!\n";	1543	or Carp::croak "AnyEvent: unable to create a signal reporting pipe: $!\n";
1518		1544
1519	$SIG_IO = AE::io $SIGPIPE_R, 0, \&_signal_exec;	1545	$SIG_IO = AE::io $SIGPIPE_R, 0, \&_signal_exec;
1520	}	1546	}
1521		1547
1522	*signal = sub {	1548	*signal = $HAVE_ASYNC_INTERRUPT
		1549	? sub {
1523	my (undef, %arg) = @_;	1550	my (undef, %arg) = @_;
1524		1551
1525	my $signal = uc $arg{signal}
1526	or Carp::croak "required option 'signal' is missing";
1527
1528	if ($HAVE_ASYNC_INTERRUPT) {
1529	# async::interrupt	1552	# async::interrupt
1530
1531	$signal = sig2num $signal;	1553	my $signal = sig2num $arg{signal};
1532	$SIG_CB{$signal}{$arg{cb}} = $arg{cb};	1554	$SIG_CB{$signal}{$arg{cb}} = $arg{cb};
1533		1555
1534	$SIG_ASY{$signal} \|\|= new Async::Interrupt	1556	$SIG_ASY{$signal} \|\|= new Async::Interrupt
1535	cb => sub { undef $SIG_EV{$signal} },	1557	cb => sub { undef $SIG_EV{$signal} },
1536	signal => $signal,	1558	signal => $signal,
1537	pipe => [$SIGPIPE_R->filenos],	1559	pipe => [$SIGPIPE_R->filenos],
1538	pipe_autodrain => 0,	1560	pipe_autodrain => 0,
1539	;	1561	;
1540		1562
1541	} else {	1563	bless [$signal, $arg{cb}], "AnyEvent::Base::signal"
		1564	}
		1565	: sub {
		1566	my (undef, %arg) = @_;
		1567
1542	# pure perl	1568	# pure perl
1543
1544	# AE::Util has been loaded in signal
1545	$signal = sig2name $signal;	1569	my $signal = sig2name $arg{signal};
1546	$SIG_CB{$signal}{$arg{cb}} = $arg{cb};	1570	$SIG_CB{$signal}{$arg{cb}} = $arg{cb};
1547		1571
1548	$SIG{$signal} \|\|= sub {	1572	$SIG{$signal} \|\|= sub {
1549	local $!;	1573	local $!;
1550	syswrite $SIGPIPE_W, "\x00", 1 unless %SIG_EV;	1574	syswrite $SIGPIPE_W, "\x00", 1 unless %SIG_EV;
1551	undef $SIG_EV{$signal};	1575	undef $SIG_EV{$signal};
1552	};	1576	};
1553		1577
1554	# can't do signal processing without introducing races in pure perl,	1578	# can't do signal processing without introducing races in pure perl,
1555	# so limit the signal latency.	1579	# so limit the signal latency.
1556	_sig_add;	1580	_sig_add;
1557	}
1558		1581
1559	bless [$signal, $arg{cb}], "AnyEvent::Base::signal"	1582	bless [$signal, $arg{cb}], "AnyEvent::Base::signal"
		1583	}
1560	};	1584	;
1561		1585
1562	*AnyEvent::Base::signal::DESTROY = sub {	1586	*AnyEvent::Base::signal::DESTROY = sub {
1563	my ($signal, $cb) = @{$_[0]};	1587	my ($signal, $cb) = @{$_[0]};
1564		1588
1565	_sig_del;	1589	_sig_del;
…		…
1572	# print weird messages, or just unconditionally exit	1596	# print weird messages, or just unconditionally exit
1573	# instead of getting the default action.	1597	# instead of getting the default action.
1574	undef $SIG{$signal}	1598	undef $SIG{$signal}
1575	unless keys %{ $SIG_CB{$signal} };	1599	unless keys %{ $SIG_CB{$signal} };
1576	};	1600	};
		1601
		1602	*_signal_exec = sub {
		1603	$HAVE_ASYNC_INTERRUPT
		1604	? $SIGPIPE_R->drain
		1605	: sysread $SIGPIPE_R, (my $dummy), 9;
		1606
		1607	while (%SIG_EV) {
		1608	for (keys %SIG_EV) {
		1609	delete $SIG_EV{$_};
		1610	$_->() for values %{ $SIG_CB{$_} \|\| {} };
		1611	}
		1612	}
		1613	};
1577	};	1614	};
1578	die if $@;	1615	die if $@;
		1616
1579	&signal	1617	&signal
1580	}	1618	}
1581		1619
1582	# default implementation for ->child	1620	# default implementation for ->child
1583		1621
1584	our %PID_CB;	1622	our %PID_CB;
1585	our $CHLD_W;	1623	our $CHLD_W;
1586	our $CHLD_DELAY_W;	1624	our $CHLD_DELAY_W;
1587	our $WNOHANG;	1625	our $WNOHANG;
1588		1626
		1627	# used by many Impl's
1589	sub _emit_childstatus($$) {	1628	sub _emit_childstatus($$) {
1590	my (undef, $rpid, $rstatus) = @_;	1629	my (undef, $rpid, $rstatus) = @_;
1591		1630
1592	$_->($rpid, $rstatus)	1631	$_->($rpid, $rstatus)
1593	for values %{ $PID_CB{$rpid} \|\| {} },	1632	for values %{ $PID_CB{$rpid} \|\| {} },
1594	values %{ $PID_CB{0} \|\| {} };	1633	values %{ $PID_CB{0} \|\| {} };
1595	}	1634	}
1596		1635
1597	sub _sigchld {
1598	my $pid;
1599
1600	AnyEvent->_emit_childstatus ($pid, $?)
1601	while ($pid = waitpid -1, $WNOHANG) > 0;
1602	}
1603
1604	sub child {	1636	sub child {
		1637	eval q{ # poor man's autoloading {}
		1638	*_sigchld = sub {
		1639	my $pid;
		1640
		1641	AnyEvent->_emit_childstatus ($pid, $?)
		1642	while ($pid = waitpid -1, $WNOHANG) > 0;
		1643	};
		1644
		1645	*child = sub {
1605	my (undef, %arg) = @_;	1646	my (undef, %arg) = @_;
1606		1647
1607	defined (my $pid = $arg{pid} + 0)	1648	defined (my $pid = $arg{pid} + 0)
1608	or Carp::croak "required option 'pid' is missing";	1649	or Carp::croak "required option 'pid' is missing";
1609		1650
1610	$PID_CB{$pid}{$arg{cb}} = $arg{cb};	1651	$PID_CB{$pid}{$arg{cb}} = $arg{cb};
1611		1652
1612	# WNOHANG is almost cetrainly 1 everywhere	1653	# WNOHANG is almost cetrainly 1 everywhere
1613	$WNOHANG \|\|= $^O =~ /^(?:openbsd\|netbsd\|linux\|freebsd\|cygwin\|MSWin32)$/	1654	$WNOHANG \|\|= $^O =~ /^(?:openbsd\|netbsd\|linux\|freebsd\|cygwin\|MSWin32)$/
1614	? 1	1655	? 1
1615	: eval { local $SIG{__DIE__}; require POSIX; &POSIX::WNOHANG } \|\| 1;	1656	: eval { local $SIG{__DIE__}; require POSIX; &POSIX::WNOHANG } \|\| 1;
1616		1657
1617	unless ($CHLD_W) {	1658	unless ($CHLD_W) {
1618	$CHLD_W = AE::signal CHLD => \&_sigchld;	1659	$CHLD_W = AE::signal CHLD => \&_sigchld;
1619	# child could be a zombie already, so make at least one round	1660	# child could be a zombie already, so make at least one round
1620	&_sigchld;	1661	&_sigchld;
1621	}	1662	}
1622		1663
1623	bless [$pid, $arg{cb}], "AnyEvent::Base::child"	1664	bless [$pid, $arg{cb}], "AnyEvent::Base::child"
1624	}	1665	};
1625		1666
1626	sub AnyEvent::Base::child::DESTROY {	1667	*AnyEvent::Base::child::DESTROY = sub {
1627	my ($pid, $cb) = @{$_[0]};	1668	my ($pid, $cb) = @{$_[0]};
1628		1669
1629	delete $PID_CB{$pid}{$cb};	1670	delete $PID_CB{$pid}{$cb};
1630	delete $PID_CB{$pid} unless keys %{ $PID_CB{$pid} };	1671	delete $PID_CB{$pid} unless keys %{ $PID_CB{$pid} };
1631		1672
1632	undef $CHLD_W unless keys %PID_CB;	1673	undef $CHLD_W unless keys %PID_CB;
		1674	};
		1675	};
		1676	die if $@;
		1677
		1678	&child
1633	}	1679	}
1634		1680
1635	# idle emulation is done by simply using a timer, regardless	1681	# idle emulation is done by simply using a timer, regardless
1636	# of whether the process is idle or not, and not letting	1682	# of whether the process is idle or not, and not letting
1637	# the callback use more than 50% of the time.	1683	# the callback use more than 50% of the time.
1638	sub idle {	1684	sub idle {
		1685	eval q{ # poor man's autoloading {}
		1686	*idle = sub {
1639	my (undef, %arg) = @_;	1687	my (undef, %arg) = @_;
1640		1688
1641	my ($cb, $w, $rcb) = $arg{cb};	1689	my ($cb, $w, $rcb) = $arg{cb};
1642		1690
1643	$rcb = sub {	1691	$rcb = sub {
1644	if ($cb) {	1692	if ($cb) {
1645	$w = _time;	1693	$w = _time;
1646	&$cb;	1694	&$cb;
1647	$w = _time - $w;	1695	$w = _time - $w;
1648		1696
1649	# never use more then 50% of the time for the idle watcher,	1697	# never use more then 50% of the time for the idle watcher,
1650	# within some limits	1698	# within some limits
1651	$w = 0.0001 if $w < 0.0001;	1699	$w = 0.0001 if $w < 0.0001;
1652	$w = 5 if $w > 5;	1700	$w = 5 if $w > 5;
1653		1701
1654	$w = AE::timer $w, 0, $rcb;	1702	$w = AE::timer $w, 0, $rcb;
1655	} else {	1703	} else {
1656	# clean up...	1704	# clean up...
1657	undef $w;	1705	undef $w;
1658	undef $rcb;	1706	undef $rcb;
		1707	}
		1708	};
		1709
		1710	$w = AE::timer 0.05, 0, $rcb;
		1711
		1712	bless \\$cb, "AnyEvent::Base::idle"
1659	}	1713	};
		1714
		1715	*AnyEvent::Base::idle::DESTROY = sub {
		1716	undef $${$_[0]};
		1717	};
1660	};	1718	};
		1719	die if $@;
1661		1720
1662	$w = AE::timer 0.05, 0, $rcb;	1721	&idle
1663
1664	bless \\$cb, "AnyEvent::Base::idle"
1665	}
1666
1667	sub AnyEvent::Base::idle::DESTROY {
1668	undef $${$_[0]};
1669	}	1722	}
1670		1723
1671	package AnyEvent::CondVar;	1724	package AnyEvent::CondVar;
1672		1725
1673	our @ISA = AnyEvent::CondVar::Base::;	1726	our @ISA = AnyEvent::CondVar::Base::;
…		…
2032		2085
2033	The actual code goes further and collects all errors (C<die>s, exceptions)	2086	The actual code goes further and collects all errors (C<die>s, exceptions)
2034	that occurred during request processing. The C<result> method detects	2087	that occurred during request processing. The C<result> method detects
2035	whether an exception as thrown (it is stored inside the $txn object)	2088	whether an exception as thrown (it is stored inside the $txn object)
2036	and just throws the exception, which means connection errors and other	2089	and just throws the exception, which means connection errors and other
2037	problems get reported tot he code that tries to use the result, not in a	2090	problems get reported to the code that tries to use the result, not in a
2038	random callback.	2091	random callback.
2039		2092
2040	All of this enables the following usage styles:	2093	All of this enables the following usage styles:
2041		2094
2042	1. Blocking:	2095	1. Blocking:
…		…
2499	automatic timer adjustments even when no monotonic clock is available,	2552	automatic timer adjustments even when no monotonic clock is available,
2500	can take avdantage of advanced kernel interfaces such as C<epoll> and	2553	can take avdantage of advanced kernel interfaces such as C<epoll> and
2501	C<kqueue>, and is the fastest backend I<by far>. You can even embed	2554	C<kqueue>, and is the fastest backend I<by far>. You can even embed
2502	L<Glib>/L<Gtk2> in it (or vice versa, see L<EV::Glib> and L<Glib::EV>).	2555	L<Glib>/L<Gtk2> in it (or vice versa, see L<EV::Glib> and L<Glib::EV>).
2503		2556
		2557	If you only use backends that rely on another event loop (e.g. C<Tk>),
		2558	then this module will do nothing for you.
		2559
2504	=item L<Guard>	2560	=item L<Guard>
2505		2561
2506	The guard module, when used, will be used to implement	2562	The guard module, when used, will be used to implement
2507	C<AnyEvent::Util::guard>. This speeds up guards considerably (and uses a	2563	C<AnyEvent::Util::guard>. This speeds up guards considerably (and uses a
2508	lot less memory), but otherwise doesn't affect guard operation much. It is	2564	lot less memory), but otherwise doesn't affect guard operation much. It is
2509	purely used for performance.	2565	purely used for performance.
2510		2566
2511	=item L<JSON> and L<JSON::XS>	2567	=item L<JSON> and L<JSON::XS>
2512		2568
2513	One of these modules is required when you want to read or write JSON data	2569	One of these modules is required when you want to read or write JSON data
2514	via L<AnyEvent::Handle>. It is also written in pure-perl, but can take	2570	via L<AnyEvent::Handle>. L<JSON> is also written in pure-perl, but can take
2515	advantage of the ultra-high-speed L<JSON::XS> module when it is installed.	2571	advantage of the ultra-high-speed L<JSON::XS> module when it is installed.
2516
2517	In fact, L<AnyEvent::Handle> will use L<JSON::XS> by default if it is
2518	installed.
2519		2572
2520	=item L<Net::SSLeay>	2573	=item L<Net::SSLeay>
2521		2574
2522	Implementing TLS/SSL in Perl is certainly interesting, but not very	2575	Implementing TLS/SSL in Perl is certainly interesting, but not very
2523	worthwhile: If this module is installed, then L<AnyEvent::Handle> (with	2576	worthwhile: If this module is installed, then L<AnyEvent::Handle> (with
…		…
2534		2587
2535		2588
2536	=head1 FORK	2589	=head1 FORK
2537		2590
2538	Most event libraries are not fork-safe. The ones who are usually are	2591	Most event libraries are not fork-safe. The ones who are usually are
2539	because they rely on inefficient but fork-safe C<select> or C<poll>	2592	because they rely on inefficient but fork-safe C<select> or C<poll> calls
2540	calls. Only L<EV> is fully fork-aware.	2593	- higher performance APIs such as BSD's kqueue or the dreaded Linux epoll
		2594	are usually badly thought-out hacks that are incompatible with fork in
		2595	one way or another. Only L<EV> is fully fork-aware and ensures that you
		2596	continue event-processing in both parent and child (or both, if you know
		2597	what you are doing).
2541		2598
2542	This means that, in general, you cannot fork and do event processing	2599	This means that, in general, you cannot fork and do event processing in
2543	in the child if a watcher was created before the fork (which in turn	2600	the child if the event library was initialised before the fork (which
2544	initialises the event library).	2601	usually happens when the first AnyEvent watcher is created, or the library
		2602	is loaded).
2545		2603
2546	If you have to fork, you must either do so I<before> creating your first	2604	If you have to fork, you must either do so I<before> creating your first
2547	watcher OR you must not use AnyEvent at all in the child OR you must do	2605	watcher OR you must not use AnyEvent at all in the child OR you must do
2548	something completely out of the scope of AnyEvent.	2606	something completely out of the scope of AnyEvent.
2549		2607
2550	The problem of doing event processing in the parent I<and> the child	2608	The problem of doing event processing in the parent I<and> the child
2551	is much more complicated: even for backends that I<are> fork-aware or	2609	is much more complicated: even for backends that I<are> fork-aware or
2552	fork-safe, their behaviour is not usually what you want: fork clones all	2610	fork-safe, their behaviour is not usually what you want: fork clones all
2553	watchers, that means all timers, I/O watchers etc. are active in both	2611	watchers, that means all timers, I/O watchers etc. are active in both
2554	parent and child, which is almost never what you want.	2612	parent and child, which is almost never what you want. USing C<exec>
		2613	to start worker children from some kind of manage rprocess is usually
		2614	preferred, because it is much easier and cleaner, at the expense of having
		2615	to have another binary.
2555		2616
2556		2617
2557	=head1 SECURITY CONSIDERATIONS	2618	=head1 SECURITY CONSIDERATIONS
2558		2619
2559	AnyEvent can be forced to load any event model via	2620	AnyEvent can be forced to load any event model via

Diff Legend

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

Comparing AnyEvent/lib/AnyEvent.pm (file contents): Revision 1.305 by root, Sun Dec 13 05:13:15 2009 UTC vs. Revision 1.327 by root, Sun Jun 6 10:13:57 2010 UTC

Diff Legend

Comparing AnyEvent/lib/AnyEvent.pm (file contents):
Revision 1.305 by root, Sun Dec 13 05:13:15 2009 UTC vs.
Revision 1.327 by root, Sun Jun 6 10:13:57 2010 UTC