[ViewVC] Diff of: cvs/AnyEvent/README

Comparing AnyEvent/README (file contents):
Revision 1.28 by root, Sat Jul 12 20:45:27 2008 UTC vs.
Revision 1.34 by root, Fri Nov 21 01:36:22 2008 UTC

…		…
5	loops	5	loops
6		6
7	SYNOPSIS	7	SYNOPSIS
8	use AnyEvent;	8	use AnyEvent;
9		9
10	my $w = AnyEvent->io (fh => $fh, poll => "r\|w", cb => sub {	10	my $w = AnyEvent->io (fh => $fh, poll => "r\|w", cb => sub { ... });
11	...
12	});
13		11
14	my $w = AnyEvent->timer (after => $seconds, cb => sub {	12	my $w = AnyEvent->timer (after => $seconds, cb => sub { ... });
		13	my $w = AnyEvent->timer (after => $seconds, interval => $seconds, cb => ...
		14
		15	print AnyEvent->now; # prints current event loop time
		16	print AnyEvent->time; # think Time::HiRes::time or simply CORE::time.
		17
		18	my $w = AnyEvent->signal (signal => "TERM", cb => sub { ... });
		19
		20	my $w = AnyEvent->child (pid => $pid, cb => sub {
		21	my ($pid, $status) = @_;
15	...	22	...
16	});	23	});
17		24
18	my $w = AnyEvent->condvar; # stores whether a condition was flagged	25	my $w = AnyEvent->condvar; # stores whether a condition was flagged
19	$w->send; # wake up current and all future recv's	26	$w->send; # wake up current and all future recv's
20	$w->recv; # enters "main loop" till $condvar gets ->send	27	$w->recv; # enters "main loop" till $condvar gets ->send
		28	# use a condvar in callback mode:
		29	$w->cb (sub { $_[0]->recv });
21		30
22	INTRODUCTION/TUTORIAL	31	INTRODUCTION/TUTORIAL
23	This manpage is mainly a reference manual. If you are interested in a	32	This manpage is mainly a reference manual. If you are interested in a
24	tutorial or some gentle introduction, have a look at the AnyEvent::Intro	33	tutorial or some gentle introduction, have a look at the AnyEvent::Intro
25	manpage.	34	manpage.
…		…
321		330
322	CHILD PROCESS WATCHERS	331	CHILD PROCESS WATCHERS
323	You can also watch on a child process exit and catch its exit status.	332	You can also watch on a child process exit and catch its exit status.
324		333
325	The child process is specified by the "pid" argument (if set to 0, it	334	The child process is specified by the "pid" argument (if set to 0, it
326	watches for any child process exit). The watcher will trigger as often	335	watches for any child process exit). The watcher will triggered only
327	as status change for the child are received. This works by installing a	336	when the child process has finished and an exit status is available, not
328	signal handler for "SIGCHLD". The callback will be called with the pid	337	on any trace events (stopped/continued).
329	and exit status (as returned by waitpid), so unlike other watcher types,	338
330	you can rely on child watcher callback arguments.	339	The callback will be called with the pid and exit status (as returned by
		340	waitpid), so unlike other watcher types, you can rely on child watcher
		341	callback arguments.
		342
		343	This watcher type works by installing a signal handler for "SIGCHLD",
		344	and since it cannot be shared, nothing else should use SIGCHLD or reap
		345	random child processes (waiting for specific child processes, e.g.
		346	inside "system", is just fine).
331		347
332	There is a slight catch to child watchers, however: you usually start	348	There is a slight catch to child watchers, however: you usually start
333	them after the child process was created, and this means the process	349	them after the child process was created, and this means the process
334	could have exited already (and no SIGCHLD will be sent anymore).	350	could have exited already (and no SIGCHLD will be sent anymore).
335		351
…		…
371	The instrument to do that is called a "condition variable", so called	387	The instrument to do that is called a "condition variable", so called
372	because they represent a condition that must become true.	388	because they represent a condition that must become true.
373		389
374	Condition variables can be created by calling the "AnyEvent->condvar"	390	Condition variables can be created by calling the "AnyEvent->condvar"
375	method, usually without arguments. The only argument pair allowed is	391	method, usually without arguments. The only argument pair allowed is
		392
376	"cb", which specifies a callback to be called when the condition	393	"cb", which specifies a callback to be called when the condition
377	variable becomes true.	394	variable becomes true, with the condition variable as the first argument
		395	(but not the results).
378		396
379	After creation, the condition variable is "false" until it becomes	397	After creation, the condition variable is "false" until it becomes
380	"true" by calling the "send" method (or calling the condition variable	398	"true" by calling the "send" method (or calling the condition variable
381	as if it were a callback, read about the caveats in the description for	399	as if it were a callback, read about the caveats in the description for
382	the "->send" method).	400	the "->send" method).
…		…
438		456
439	my $done = AnyEvent->condvar;	457	my $done = AnyEvent->condvar;
440	my $delay = AnyEvent->timer (after => 5, cb => $done);	458	my $delay = AnyEvent->timer (after => 5, cb => $done);
441	$done->recv;	459	$done->recv;
442		460
		461	Example: Imagine an API that returns a condvar and doesn't support
		462	callbacks. This is how you make a synchronous call, for example from the
		463	main program:
		464
		465	use AnyEvent::CouchDB;
		466
		467	...
		468
		469	my @info = $couchdb->info->recv;
		470
		471	And this is how you would just ste a callback to be called whenever the
		472	results are available:
		473
		474	$couchdb->info->cb (sub {
		475	my @info = $_[0]->recv;
		476	});
		477
443	METHODS FOR PRODUCERS	478	METHODS FOR PRODUCERS
444	These methods should only be used by the producing side, i.e. the	479	These methods should only be used by the producing side, i.e. the
445	code/module that eventually sends the signal. Note that it is also the	480	code/module that eventually sends the signal. Note that it is also the
446	producer side which creates the condvar in most cases, but it isn't	481	producer side which creates the condvar in most cases, but it isn't
447	uncommon for the consumer to create it as well.	482	uncommon for the consumer to create it as well.
…		…
567		602
568	$bool = $cv->ready	603	$bool = $cv->ready
569	Returns true when the condition is "true", i.e. whether "send" or	604	Returns true when the condition is "true", i.e. whether "send" or
570	"croak" have been called.	605	"croak" have been called.
571		606
572	$cb = $cv->cb ([new callback])	607	$cb = $cv->cb ($cb->($cv))
573	This is a mutator function that returns the callback set and	608	This is a mutator function that returns the callback set and
574	optionally replaces it before doing so.	609	optionally replaces it before doing so.
575		610
576	The callback will be called when the condition becomes "true", i.e.	611	The callback will be called when the condition becomes "true", i.e.
577	when "send" or "croak" are called, with the only argument being the	612	when "send" or "croak" are called, with the only argument being the
…		…
742		777
743	AnyEvent::IGS	778	AnyEvent::IGS
744	A non-blocking interface to the Internet Go Server protocol (used by	779	A non-blocking interface to the Internet Go Server protocol (used by
745	App::IGS).	780	App::IGS).
746		781
		782	AnyEvent::IRC
		783	AnyEvent based IRC client module family (replacing the older
747	Net::IRC3	784	Net::IRC3).
748	AnyEvent based IRC client module family.
749		785
750	Net::XMPP2	786	Net::XMPP2
751	AnyEvent based XMPP (Jabber protocol) module family.	787	AnyEvent based XMPP (Jabber protocol) module family.
752		788
753	Net::FCP	789	Net::FCP
…		…
762		798
763	IO::Lambda	799	IO::Lambda
764	The lambda approach to I/O - don't ask, look there. Can use	800	The lambda approach to I/O - don't ask, look there. Can use
765	AnyEvent.	801	AnyEvent.
766		802
767	SUPPLYING YOUR OWN EVENT MODEL INTERFACE	803	ERROR AND EXCEPTION HANDLING
768	This is an advanced topic that you do not normally need to use AnyEvent	804	In general, AnyEvent does not do any error handling - it relies on the
769	in a module. This section is only of use to event loop authors who want	805	caller to do that if required. The AnyEvent::Strict module (see also the
770	to provide AnyEvent compatibility.	806	"PERL_ANYEVENT_STRICT" environment variable, below) provides strict
		807	checking of all AnyEvent methods, however, which is highly useful during
		808	development.
771		809
772	If you need to support another event library which isn't directly	810	As for exception handling (i.e. runtime errors and exceptions thrown
773	supported by AnyEvent, you can supply your own interface to it by	811	while executing a callback), this is not only highly event-loop
774	pushing, before the first watcher gets created, the package name of the	812	specific, but also not in any way wrapped by this module, as this is the
775	event module and the package name of the interface to use onto	813	job of the main program.
776	@AnyEvent::REGISTRY. You can do that before and even without loading
777	AnyEvent, so it is reasonably cheap.
778		814
779	Example:	815	The pure perl event loop simply re-throws the exception (usually within
780		816	"condvar->recv"), the Event and EV modules call "$Event/EV::DIED->()",
781	push @AnyEvent::REGISTRY, [urxvt => urxvt::anyevent::];	817	Glib uses "install_exception_handler" and so on.
782
783	This tells AnyEvent to (literally) use the "urxvt::anyevent::"
784	package/class when it finds the "urxvt" package/module is already
785	loaded.
786
787	When AnyEvent is loaded and asked to find a suitable event model, it
788	will first check for the presence of urxvt by trying to "use" the
789	"urxvt::anyevent" module.
790
791	The class should provide implementations for all watcher types. See
792	AnyEvent::Impl::EV (source code), AnyEvent::Impl::Glib (Source code) and
793	so on for actual examples. Use "perldoc -m AnyEvent::Impl::Glib" to see
794	the sources.
795
796	If you don't provide "signal" and "child" watchers than AnyEvent will
797	provide suitable (hopefully) replacements.
798
799	The above example isn't fictitious, the rxvt-unicode (a.k.a. urxvt)
800	terminal emulator uses the above line as-is. An interface isn't included
801	in AnyEvent because it doesn't make sense outside the embedded
802	interpreter inside rxvt-unicode, and it is updated and maintained as
803	part of the rxvt-unicode distribution.
804
805	rxvt-unicode also cheats a bit by not providing blocking access to
806	condition variables: code blocking while waiting for a condition will
807	"die". This still works with most modules/usages, and blocking calls
808	must not be done in an interactive application, so it makes sense.
809		818
810	ENVIRONMENT VARIABLES	819	ENVIRONMENT VARIABLES
811	The following environment variables are used by this module:	820	The following environment variables are used by this module or its
		821	submodules:
812		822
813	"PERL_ANYEVENT_VERBOSE"	823	"PERL_ANYEVENT_VERBOSE"
814	By default, AnyEvent will be completely silent except in fatal	824	By default, AnyEvent will be completely silent except in fatal
815	conditions. You can set this environment variable to make AnyEvent	825	conditions. You can set this environment variable to make AnyEvent
816	more talkative.	826	more talkative.
…		…
829	thoroughly check the arguments passed to most method calls. If it	839	thoroughly check the arguments passed to most method calls. If it
830	finds any problems it will croak.	840	finds any problems it will croak.
831		841
832	In other words, enables "strict" mode.	842	In other words, enables "strict" mode.
833		843
834	Unlike "use strict" it is definitely recommended ot keep it off in	844	Unlike "use strict", it is definitely recommended ot keep it off in
835	production.	845	production. Keeping "PERL_ANYEVENT_STRICT=1" in your environment
		846	while developing programs can be very useful, however.
836		847
837	"PERL_ANYEVENT_MODEL"	848	"PERL_ANYEVENT_MODEL"
838	This can be used to specify the event model to be used by AnyEvent,	849	This can be used to specify the event model to be used by AnyEvent,
839	before auto detection and -probing kicks in. It must be a string	850	before auto detection and -probing kicks in. It must be a string
840	consisting entirely of ASCII letters. The string "AnyEvent::Impl::"	851	consisting entirely of ASCII letters. The string "AnyEvent::Impl::"
…		…
881	EDNS0 in its DNS requests.	892	EDNS0 in its DNS requests.
882		893
883	"PERL_ANYEVENT_MAX_FORKS"	894	"PERL_ANYEVENT_MAX_FORKS"
884	The maximum number of child processes that	895	The maximum number of child processes that
885	"AnyEvent::Util::fork_call" will create in parallel.	896	"AnyEvent::Util::fork_call" will create in parallel.
		897
		898	SUPPLYING YOUR OWN EVENT MODEL INTERFACE
		899	This is an advanced topic that you do not normally need to use AnyEvent
		900	in a module. This section is only of use to event loop authors who want
		901	to provide AnyEvent compatibility.
		902
		903	If you need to support another event library which isn't directly
		904	supported by AnyEvent, you can supply your own interface to it by
		905	pushing, before the first watcher gets created, the package name of the
		906	event module and the package name of the interface to use onto
		907	@AnyEvent::REGISTRY. You can do that before and even without loading
		908	AnyEvent, so it is reasonably cheap.
		909
		910	Example:
		911
		912	push @AnyEvent::REGISTRY, [urxvt => urxvt::anyevent::];
		913
		914	This tells AnyEvent to (literally) use the "urxvt::anyevent::"
		915	package/class when it finds the "urxvt" package/module is already
		916	loaded.
		917
		918	When AnyEvent is loaded and asked to find a suitable event model, it
		919	will first check for the presence of urxvt by trying to "use" the
		920	"urxvt::anyevent" module.
		921
		922	The class should provide implementations for all watcher types. See
		923	AnyEvent::Impl::EV (source code), AnyEvent::Impl::Glib (Source code) and
		924	so on for actual examples. Use "perldoc -m AnyEvent::Impl::Glib" to see
		925	the sources.
		926
		927	If you don't provide "signal" and "child" watchers than AnyEvent will
		928	provide suitable (hopefully) replacements.
		929
		930	The above example isn't fictitious, the rxvt-unicode (a.k.a. urxvt)
		931	terminal emulator uses the above line as-is. An interface isn't included
		932	in AnyEvent because it doesn't make sense outside the embedded
		933	interpreter inside rxvt-unicode, and it is updated and maintained as
		934	part of the rxvt-unicode distribution.
		935
		936	rxvt-unicode also cheats a bit by not providing blocking access to
		937	condition variables: code blocking while waiting for a condition will
		938	"die". This still works with most modules/usages, and blocking calls
		939	must not be done in an interactive application, so it makes sense.
886		940
887	EXAMPLE PROGRAM	941	EXAMPLE PROGRAM
888	The following program uses an I/O watcher to read data from STDIN, a	942	The following program uses an I/O watcher to read data from STDIN, a
889	timer to display a message once per second, and a condition variable to	943	timer to display a message once per second, and a condition variable to
890	quit the program when the user enters quit:	944	quit the program when the user enters quit:
…		…
1077	destroy is the time, in microseconds, that it takes to destroy a	1131	destroy is the time, in microseconds, that it takes to destroy a
1078	single watcher.	1132	single watcher.
1079		1133
1080	Results	1134	Results
1081	name watchers bytes create invoke destroy comment	1135	name watchers bytes create invoke destroy comment
1082	EV/EV 400000 244 0.56 0.46 0.31 EV native interface	1136	EV/EV 400000 224 0.47 0.35 0.27 EV native interface
1083	EV/Any 100000 244 2.50 0.46 0.29 EV + AnyEvent watchers	1137	EV/Any 100000 224 2.88 0.34 0.27 EV + AnyEvent watchers
1084	CoroEV/Any 100000 244 2.49 0.44 0.29 coroutines + Coro::Signal	1138	CoroEV/Any 100000 224 2.85 0.35 0.28 coroutines + Coro::Signal
1085	Perl/Any 100000 513 4.92 0.87 1.12 pure perl implementation	1139	Perl/Any 100000 452 4.13 0.73 0.95 pure perl implementation
1086	Event/Event 16000 516 31.88 31.30 0.85 Event native interface	1140	Event/Event 16000 517 32.20 31.80 0.81 Event native interface
1087	Event/Any 16000 590 35.75 31.42 1.08 Event + AnyEvent watchers	1141	Event/Any 16000 590 35.85 31.55 1.06 Event + AnyEvent watchers
1088	Glib/Any 16000 1357 98.22 12.41 54.00 quadratic behaviour	1142	Glib/Any 16000 1357 102.33 12.31 51.00 quadratic behaviour
1089	Tk/Any 2000 1860 26.97 67.98 14.00 SEGV with >> 2000 watchers	1143	Tk/Any 2000 1860 27.20 66.31 14.00 SEGV with >> 2000 watchers
1090	POE/Event 2000 6644 108.64 736.02 14.73 via POE::Loop::Event	1144	POE/Event 2000 6328 109.99 751.67 14.02 via POE::Loop::Event
1091	POE/Select 2000 6343 94.13 809.12 565.96 via POE::Loop::Select	1145	POE/Select 2000 6027 94.54 809.13 579.80 via POE::Loop::Select
1092		1146
1093	Discussion	1147	Discussion
1094	The benchmark does not measure scalability of the event loop very	1148	The benchmark does not measure scalability of the event loop very
1095	well. For example, a select-based event loop (such as the pure perl one)	1149	well. For example, a select-based event loop (such as the pure perl one)
1096	can never compete with an event loop that uses epoll when the number of	1150	can never compete with an event loop that uses epoll when the number of
…		…
1277		1331
1278	Summary	1332	Summary
1279	* C-based event loops perform very well with small number of watchers,	1333	* C-based event loops perform very well with small number of watchers,
1280	as the management overhead dominates.	1334	as the management overhead dominates.
1281		1335
		1336	SIGNALS
		1337	AnyEvent currently installs handlers for these signals:
		1338
		1339	SIGCHLD
		1340	A handler for "SIGCHLD" is installed by AnyEvent's child watcher
		1341	emulation for event loops that do not support them natively. Also,
		1342	some event loops install a similar handler.
		1343
		1344	SIGPIPE
		1345	A no-op handler is installed for "SIGPIPE" when $SIG{PIPE} is
		1346	"undef" when AnyEvent gets loaded.
		1347
		1348	The rationale for this is that AnyEvent users usually do not really
		1349	depend on SIGPIPE delivery (which is purely an optimisation for
		1350	shell use, or badly-written programs), but "SIGPIPE" can cause
		1351	spurious and rare program exits as a lot of people do not expect
		1352	"SIGPIPE" when writing to some random socket.
		1353
		1354	The rationale for installing a no-op handler as opposed to ignoring
		1355	it is that this way, the handler will be restored to defaults on
		1356	exec.
		1357
		1358	Feel free to install your own handler, or reset it to defaults.
		1359
1282	FORK	1360	FORK
1283	Most event libraries are not fork-safe. The ones who are usually are	1361	Most event libraries are not fork-safe. The ones who are usually are
1284	because they rely on inefficient but fork-safe "select" or "poll" calls.	1362	because they rely on inefficient but fork-safe "select" or "poll" calls.
1285	Only EV is fully fork-aware.	1363	Only EV is fully fork-aware.
1286		1364

Diff Legend

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

Comparing AnyEvent/README (file contents): Revision 1.28 by root, Sat Jul 12 20:45:27 2008 UTC vs. Revision 1.34 by root, Fri Nov 21 01:36:22 2008 UTC

Diff Legend

Comparing AnyEvent/README (file contents):
Revision 1.28 by root, Sat Jul 12 20:45:27 2008 UTC vs.
Revision 1.34 by root, Fri Nov 21 01:36:22 2008 UTC