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

Comparing AnyEvent/lib/AnyEvent.pm (file contents):
Revision 1.246 by root, Sat Jul 18 15:51:52 2009 UTC vs.
Revision 1.253 by root, Tue Jul 21 06:00:47 2009 UTC

…		…
1	=head1 NAME	1	=head1 NAME
2		2
3	AnyEvent - provide framework for multiple event loops	3	AnyEvent - events independent of event loop implementation
4		4
5	EV, Event, Glib, Tk, Perl, Event::Lib, Qt and POE are various supported	5	EV, Event, Glib, Tk, Perl, Event::Lib, Qt and POE are various supported
6	event loops.	6	event loops.
7		7
8	=head1 SYNOPSIS	8	=head1 SYNOPSIS
40	=head1 INTRODUCTION/TUTORIAL	40	=head1 INTRODUCTION/TUTORIAL
41		41
42	This manpage is mainly a reference manual. If you are interested	42	This manpage is mainly a reference manual. If you are interested
43	in a tutorial or some gentle introduction, have a look at the	43	in a tutorial or some gentle introduction, have a look at the
44	L<AnyEvent::Intro> manpage.	44	L<AnyEvent::Intro> manpage.
		45
		46	=head1 SUPPORT
		47
		48	There is a mailinglist for discussing all things AnyEvent, and an IRC
		49	channel, too.
		50
		51	See the AnyEvent project page at the B<Schmorpforge Ta-Sa Software
		52	Respository>, at L<http://anyevent.schmorp.de>, for more info.
45		53
46	=head1 WHY YOU SHOULD USE THIS MODULE (OR NOT)	54	=head1 WHY YOU SHOULD USE THIS MODULE (OR NOT)
47		55
48	Glib, POE, IO::Async, Event... CPAN offers event models by the dozen	56	Glib, POE, IO::Async, Event... CPAN offers event models by the dozen
49	nowadays. So what is different about AnyEvent?	57	nowadays. So what is different about AnyEvent?
…		…
368		376
369	This watcher might use C<%SIG> (depending on the event loop used),	377	This watcher might use C<%SIG> (depending on the event loop used),
370	so programs overwriting those signals directly will likely not work	378	so programs overwriting those signals directly will likely not work
371	correctly.	379	correctly.
372		380
		381	Example: exit on SIGINT
		382
		383	my $w = AnyEvent->signal (signal => "INT", cb => sub { exit 1 });
		384
		385	=head3 Signal Races, Delays and Workarounds
		386
373	Also note that many event loops (e.g. Glib, Tk, Qt, IO::Async) do not	387	Many event loops (e.g. Glib, Tk, Qt, IO::Async) do not support attaching
374	support attaching callbacks to signals, which is a pity, as you cannot do	388	callbacks to signals in a generic way, which is a pity, as you cannot do
375	race-free signal handling in perl. AnyEvent will try to do it's best, but	389	race-free signal handling in perl. AnyEvent will try to do it's best, but
376	in some cases, signals will be delayed. The maximum time a signal might	390	in some cases, signals will be delayed. The maximum time a signal might
377	be delayed is specified in C<$AnyEvent::MAX_SIGNAL_LATENCY> (default: 10	391	be delayed is specified in C<$AnyEvent::MAX_SIGNAL_LATENCY> (default: 10
378	seconds). This variable can be changed only before the first signal	392	seconds). This variable can be changed only before the first signal
379	watcher is created, and should be left alone otherwise. Higher values	393	watcher is created, and should be left alone otherwise. Higher values
380	will cause fewer spurious wake-ups, which is better for power and CPU	394	will cause fewer spurious wake-ups, which is better for power and CPU
381	saving. All these problems can be avoided by installing the optional	395	saving. All these problems can be avoided by installing the optional
382	L<Async::Interrupt> module.	396	L<Async::Interrupt> module. This will not work with inherently broken
383		397	event loops such as L<Event> or L<Event::Lib> (and not with L<POE>
384	Example: exit on SIGINT	398	currently, as POE does it's own workaround with one-second latency). With
385		399	those, you just have to suffer the delays.
386	my $w = AnyEvent->signal (signal => "INT", cb => sub { exit 1 });
387		400
388	=head2 CHILD PROCESS WATCHERS	401	=head2 CHILD PROCESS WATCHERS
389		402
390	You can also watch on a child process exit and catch its exit status.	403	You can also watch on a child process exit and catch its exit status.
391		404
…		…
504	Condition variables are similar to callbacks, except that you can	517	Condition variables are similar to callbacks, except that you can
505	optionally wait for them. They can also be called merge points - points	518	optionally wait for them. They can also be called merge points - points
506	in time where multiple outstanding events have been processed. And yet	519	in time where multiple outstanding events have been processed. And yet
507	another way to call them is transactions - each condition variable can be	520	another way to call them is transactions - each condition variable can be
508	used to represent a transaction, which finishes at some point and delivers	521	used to represent a transaction, which finishes at some point and delivers
509	a result.	522	a result. And yet some people know them as "futures" - a promise to
		523	compute/deliver something that you can wait for.
510		524
511	Condition variables are very useful to signal that something has finished,	525	Condition variables are very useful to signal that something has finished,
512	for example, if you write a module that does asynchronous http requests,	526	for example, if you write a module that does asynchronous http requests,
513	then a condition variable would be the ideal candidate to signal the	527	then a condition variable would be the ideal candidate to signal the
514	availability of results. The user can either act when the callback is	528	availability of results. The user can either act when the callback is
…		…
865	event module detection too early, for example, L<AnyEvent::AIO> creates	879	event module detection too early, for example, L<AnyEvent::AIO> creates
866	and installs the global L<IO::AIO> watcher in a C<post_detect> block to	880	and installs the global L<IO::AIO> watcher in a C<post_detect> block to
867	avoid autodetecting the event module at load time.	881	avoid autodetecting the event module at load time.
868		882
869	If called in scalar or list context, then it creates and returns an object	883	If called in scalar or list context, then it creates and returns an object
870	that automatically removes the callback again when it is destroyed. See	884	that automatically removes the callback again when it is destroyed (or
		885	C<undef> when the hook was immediately executed). See L<AnyEvent::AIO> for
871	L<Coro::BDB> for a case where this is useful.	886	a case where this is useful.
		887
		888	Example: Create a watcher for the IO::AIO module and store it in
		889	C<$WATCHER>. Only do so after the event loop is initialised, though.
		890
		891	our WATCHER;
		892
		893	my $guard = AnyEvent::post_detect {
		894	$WATCHER = AnyEvent->io (fh => IO::AIO::poll_fileno, poll => 'r', cb => \&IO::AIO::poll_cb);
		895	};
		896
		897	# the \|\|= is important in case post_detect immediately runs the block,
		898	# as to not clobber the newly-created watcher. assigning both watcher and
		899	# post_detect guard to the same variable has the advantage of users being
		900	# able to just C<undef $WATCHER> if the watcher causes them grief.
		901
		902	$WATCHER \|\|= $guard;
872		903
873	=item @AnyEvent::post_detect	904	=item @AnyEvent::post_detect
874		905
875	If there are any code references in this array (you can C<push> to it	906	If there are any code references in this array (you can C<push> to it
876	before or after loading AnyEvent), then they will called directly after	907	before or after loading AnyEvent), then they will called directly after
…		…
1053		1084
1054	BEGIN { AnyEvent::common_sense }	1085	BEGIN { AnyEvent::common_sense }
1055		1086
1056	use Carp ();	1087	use Carp ();
1057		1088
1058	our $VERSION = 4.85;	1089	our $VERSION = 4.86;
1059	our $MODEL;	1090	our $MODEL;
1060		1091
1061	our $AUTOLOAD;	1092	our $AUTOLOAD;
1062	our @ISA;	1093	our @ISA;
1063		1094
…		…
1121	my ($cb) = @_;	1152	my ($cb) = @_;
1122		1153
1123	if ($MODEL) {	1154	if ($MODEL) {
1124	$cb->();	1155	$cb->();
1125		1156
1126	1	1157	undef
1127	} else {	1158	} else {
1128	push @post_detect, $cb;	1159	push @post_detect, $cb;
1129		1160
1130	defined wantarray	1161	defined wantarray
1131	? bless \$cb, "AnyEvent::Util::postdetect"	1162	? bless \$cb, "AnyEvent::Util::postdetect"
…		…
2270		2301
2271	This slightly arcane module is used to implement fast signal handling: To	2302	This slightly arcane module is used to implement fast signal handling: To
2272	my knowledge, there is no way to do completely race-free and quick	2303	my knowledge, there is no way to do completely race-free and quick
2273	signal handling in pure perl. To ensure that signals still get	2304	signal handling in pure perl. To ensure that signals still get
2274	delivered, AnyEvent will start an interval timer to wake up perl (and	2305	delivered, AnyEvent will start an interval timer to wake up perl (and
2275	catch the signals) with soemd elay (default is 10 seconds, look for	2306	catch the signals) with some delay (default is 10 seconds, look for
2276	C<$AnyEvent::MAX_SIGNAL_LATENCY>).	2307	C<$AnyEvent::MAX_SIGNAL_LATENCY>).
2277		2308
2278	If this module is available, then it will be used to implement signal	2309	If this module is available, then it will be used to implement signal
2279	catching, which means that signals will not be delayed, and the event loop	2310	catching, which means that signals will not be delayed, and the event loop
2280	will not be interrupted regularly, which is more efficient (And good for	2311	will not be interrupted regularly, which is more efficient (And good for
2281	battery life on laptops).	2312	battery life on laptops).
2282		2313
2283	This affects not just the pure-perl event loop, but also other event loops	2314	This affects not just the pure-perl event loop, but also other event loops
2284	that have no signal handling on their own (e.g. Glib, Tk, Qt).	2315	that have no signal handling on their own (e.g. Glib, Tk, Qt).
		2316
		2317	Some event loops (POE, Event, Event::Lib) offer signal watchers natively,
		2318	and either employ their own workarounds (POE) or use AnyEvent's workaround
		2319	(using C<$AnyEvent::MAX_SIGNAL_LATENCY>). Installing L<Async::Interrupt>
		2320	does nothing for those backends.
2285		2321
2286	=item L<EV>	2322	=item L<EV>
2287		2323
2288	This module isn't really "optional", as it is simply one of the backend	2324	This module isn't really "optional", as it is simply one of the backend
2289	event loops that AnyEvent can use. However, it is simply the best event	2325	event loops that AnyEvent can use. However, it is simply the best event
…		…
2303		2339
2304	=item L<JSON> and L<JSON::XS>	2340	=item L<JSON> and L<JSON::XS>
2305		2341
2306	This module is required when you want to read or write JSON data via	2342	This module is required when you want to read or write JSON data via
2307	L<AnyEvent::Handle>. It is also written in pure-perl, but can take	2343	L<AnyEvent::Handle>. It is also written in pure-perl, but can take
2308	advantage of the ulta-high-speed L<JSON::XS> module when it is installed.	2344	advantage of the ultra-high-speed L<JSON::XS> module when it is installed.
2309		2345
2310	In fact, L<AnyEvent::Handle> will use L<JSON::XS> by default if it is	2346	In fact, L<AnyEvent::Handle> will use L<JSON::XS> by default if it is
2311	installed.	2347	installed.
2312		2348
2313	=item L<Net::SSLeay>	2349	=item L<Net::SSLeay>

Diff Legend

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

Comparing AnyEvent/lib/AnyEvent.pm (file contents): Revision 1.246 by root, Sat Jul 18 15:51:52 2009 UTC vs. Revision 1.253 by root, Tue Jul 21 06:00:47 2009 UTC

Diff Legend

Comparing AnyEvent/lib/AnyEvent.pm (file contents):
Revision 1.246 by root, Sat Jul 18 15:51:52 2009 UTC vs.
Revision 1.253 by root, Tue Jul 21 06:00:47 2009 UTC