[ViewVC] Diff of: cvs/AnyEvent/README

Comparing AnyEvent/README (file contents):
Revision 1.24 by root, Thu May 29 03:46:04 2008 UTC vs.
Revision 1.30 by root, Mon Sep 29 02:08:57 2008 UTC

…		…
1	=> NAME	1	NAME
2	AnyEvent - provide framework for multiple event loops	2	AnyEvent - provide framework for multiple event loops
3		3
4	EV, Event, Glib, Tk, Perl, Event::Lib, Qt, POE - various supported event	4	EV, Event, Glib, Tk, Perl, Event::Lib, Qt, POE - various supported event
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 });
		30
		31	INTRODUCTION/TUTORIAL
		32	This manpage is mainly a reference manual. If you are interested in a
		33	tutorial or some gentle introduction, have a look at the AnyEvent::Intro
		34	manpage.
21		35
22	WHY YOU SHOULD USE THIS MODULE (OR NOT)	36	WHY YOU SHOULD USE THIS MODULE (OR NOT)
23	Glib, POE, IO::Async, Event... CPAN offers event models by the dozen	37	Glib, POE, IO::Async, Event... CPAN offers event models by the dozen
24	nowadays. So what is different about AnyEvent?	38	nowadays. So what is different about AnyEvent?
25		39
26	Executive Summary: AnyEvent is compatible, AnyEvent is *free of	40	Executive Summary: AnyEvent is compatible, AnyEvent is *free of
27	policy* and AnyEvent is small and efficient.	41	policy* and AnyEvent is small and efficient.
28		42
29	First and foremost, AnyEvent is not an event model itself, it only	43	First and foremost, AnyEvent is not an event model itself, it only
30	interfaces to whatever event model the main program happens to use in a	44	interfaces to whatever event model the main program happens to use, in a
31	pragmatic way. For event models and certain classes of immortals alike,	45	pragmatic way. For event models and certain classes of immortals alike,
32	the statement "there can only be one" is a bitter reality: In general,	46	the statement "there can only be one" is a bitter reality: In general,
33	only one event loop can be active at the same time in a process.	47	only one event loop can be active at the same time in a process.
34	AnyEvent helps hiding the differences between those event loops.	48	AnyEvent cannot change this, but it can hide the differences between
		49	those event loops.
35		50
36	The goal of AnyEvent is to offer module authors the ability to do event	51	The goal of AnyEvent is to offer module authors the ability to do event
37	programming (waiting for I/O or timer events) without subscribing to a	52	programming (waiting for I/O or timer events) without subscribing to a
38	religion, a way of living, and most importantly: without forcing your	53	religion, a way of living, and most importantly: without forcing your
39	module users into the same thing by forcing them to use the same event	54	module users into the same thing by forcing them to use the same event
40	model you use.	55	model you use.
41		56
42	For modules like POE or IO::Async (which is a total misnomer as it is	57	For modules like POE or IO::Async (which is a total misnomer as it is
43	actually doing all I/O synchronously...), using them in your module is	58	actually doing all I/O synchronously...), using them in your module is
44	like joining a cult: After you joined, you are dependent on them and you	59	like joining a cult: After you joined, you are dependent on them and you
45	cannot use anything else, as it is simply incompatible to everything	60	cannot use anything else, as they are simply incompatible to everything
46	that isn't itself. What's worse, all the potential users of your module	61	that isn't them. What's worse, all the potential users of your module
47	are also forced to use the same event loop you use.	62	are also forced to use the same event loop you use.
48		63
49	AnyEvent is different: AnyEvent + POE works fine. AnyEvent + Glib works	64	AnyEvent is different: AnyEvent + POE works fine. AnyEvent + Glib works
50	fine. AnyEvent + Tk works fine etc. etc. but none of these work together	65	fine. AnyEvent + Tk works fine etc. etc. but none of these work together
51	with the rest: POE + IO::Async? No go. Tk + Event? No go. Again: if your	66	with the rest: POE + IO::Async? No go. Tk + Event? No go. Again: if your
52	module uses one of those, every user of your module has to use it, too.	67	module uses one of those, every user of your module has to use it, too.
53	But if your module uses AnyEvent, it works transparently with all event	68	But if your module uses AnyEvent, it works transparently with all event
54	models it supports (including stuff like POE and IO::Async, as long as	69	models it supports (including stuff like IO::Async, as long as those use
55	those use one of the supported event loops. It is trivial to add new	70	one of the supported event loops. It is trivial to add new event loops
56	event loops to AnyEvent, too, so it is future-proof).	71	to AnyEvent, too, so it is future-proof).
57		72
58	In addition to being free of having to use *the one and only true event	73	In addition to being free of having to use *the one and only true event
59	model*, AnyEvent also is free of bloat and policy: with POE or similar	74	model*, AnyEvent also is free of bloat and policy: with POE or similar
60	modules, you get an enormous amount of code and strict rules you have to	75	modules, you get an enormous amount of code and strict rules you have to
61	follow. AnyEvent, on the other hand, is lean and up to the point, by	76	follow. AnyEvent, on the other hand, is lean and up to the point, by
128	Many watchers either are used with "recursion" (repeating timers for	143	Many watchers either are used with "recursion" (repeating timers for
129	example), or need to refer to their watcher object in other ways.	144	example), or need to refer to their watcher object in other ways.
130		145
131	An any way to achieve that is this pattern:	146	An any way to achieve that is this pattern:
132		147
133	my $w; $w = AnyEvent->type (arg => value ..., cb => sub {	148	my $w; $w = AnyEvent->type (arg => value ..., cb => sub {
134	# you can use $w here, for example to undef it	149	# you can use $w here, for example to undef it
135	undef $w;	150	undef $w;
136	});	151	});
137		152
138	Note that "my $w; $w =" combination. This is necessary because in Perl,	153	Note that "my $w; $w =" combination. This is necessary because in Perl,
139	my variables are only visible after the statement in which they are	154	my variables are only visible after the statement in which they are
140	declared.	155	declared.
141		156
142	I/O WATCHERS	157	I/O WATCHERS
143	You can create an I/O watcher by calling the "AnyEvent->io" method with	158	You can create an I/O watcher by calling the "AnyEvent->io" method with
144	the following mandatory key-value pairs as arguments:	159	the following mandatory key-value pairs as arguments:
145		160
146	"fh" the Perl file handle (not file descriptor) to watch for events.	161	"fh" the Perl file handle (not file descriptor) to watch for events
		162	(AnyEvent might or might not keep a reference to this file handle).
147	"poll" must be a string that is either "r" or "w", which creates a	163	"poll" must be a string that is either "r" or "w", which creates a
148	watcher waiting for "r"eadable or "w"ritable events, respectively. "cb"	164	watcher waiting for "r"eadable or "w"ritable events, respectively. "cb"
149	is the callback to invoke each time the file handle becomes ready.	165	is the callback to invoke each time the file handle becomes ready.
150		166
151	Although the callback might get passed parameters, their value and	167	Although the callback might get passed parameters, their value and
…		…
158		174
159	Some event loops issue spurious readyness notifications, so you should	175	Some event loops issue spurious readyness notifications, so you should
160	always use non-blocking calls when reading/writing from/to your file	176	always use non-blocking calls when reading/writing from/to your file
161	handles.	177	handles.
162		178
163	Example:
164
165	# wait for readability of STDIN, then read a line and disable the watcher	179	Example: wait for readability of STDIN, then read a line and disable the
		180	watcher.
		181
166	my $w; $w = AnyEvent->io (fh => \*STDIN, poll => 'r', cb => sub {	182	my $w; $w = AnyEvent->io (fh => \*STDIN, poll => 'r', cb => sub {
167	chomp (my $input = <STDIN>);	183	chomp (my $input = <STDIN>);
168	warn "read: $input\n";	184	warn "read: $input\n";
169	undef $w;	185	undef $w;
170	});	186	});
…		…
179		195
180	Although the callback might get passed parameters, their value and	196	Although the callback might get passed parameters, their value and
181	presence is undefined and you cannot rely on them. Portable AnyEvent	197	presence is undefined and you cannot rely on them. Portable AnyEvent
182	callbacks cannot use arguments passed to time watcher callbacks.	198	callbacks cannot use arguments passed to time watcher callbacks.
183		199
184	The timer callback will be invoked at most once: if you want a repeating	200	The callback will normally be invoked once only. If you specify another
185	timer you have to create a new watcher (this is a limitation by both Tk	201	parameter, "interval", as a strictly positive number (> 0), then the
186	and Glib).	202	callback will be invoked regularly at that interval (in fractional
		203	seconds) after the first invocation. If "interval" is specified with a
		204	false value, then it is treated as if it were missing.
187		205
188	Example:	206	The callback will be rescheduled before invoking the callback, but no
		207	attempt is done to avoid timer drift in most backends, so the interval
		208	is only approximate.
189		209
190	# fire an event after 7.7 seconds	210	Example: fire an event after 7.7 seconds.
		211
191	my $w = AnyEvent->timer (after => 7.7, cb => sub {	212	my $w = AnyEvent->timer (after => 7.7, cb => sub {
192	warn "timeout\n";	213	warn "timeout\n";
193	});	214	});
194		215
195	# to cancel the timer:	216	# to cancel the timer:
196	undef $w;	217	undef $w;
197		218
198	Example 2:
199
200	# fire an event after 0.5 seconds, then roughly every second	219	Example 2: fire an event after 0.5 seconds, then roughly every second.
201	my $w;
202		220
203	my $cb = sub {
204	# cancel the old timer while creating a new one
205	$w = AnyEvent->timer (after => 1, cb => $cb);	221	my $w = AnyEvent->timer (after => 0.5, interval => 1, cb => sub {
		222	warn "timeout\n";
206	};	223	};
207
208	# start the "loop" by creating the first watcher
209	$w = AnyEvent->timer (after => 0.5, cb => $cb);
210		224
211	TIMING ISSUES	225	TIMING ISSUES
212	There are two ways to handle timers: based on real time (relative, "fire	226	There are two ways to handle timers: based on real time (relative, "fire
213	in 10 seconds") and based on wallclock time (absolute, "fire at 12	227	in 10 seconds") and based on wallclock time (absolute, "fire at 12
214	o'clock").	228	o'clock").
…		…
290	the difference between "AnyEvent->time" and "AnyEvent->now" into	304	the difference between "AnyEvent->time" and "AnyEvent->now" into
291	account.	305	account.
292		306
293	SIGNAL WATCHERS	307	SIGNAL WATCHERS
294	You can watch for signals using a signal watcher, "signal" is the signal	308	You can watch for signals using a signal watcher, "signal" is the signal
295	name without any "SIG" prefix, "cb" is the Perl callback to be invoked	309	name in uppercase and without any "SIG" prefix, "cb" is the Perl
296	whenever a signal occurs.	310	callback to be invoked whenever a signal occurs.
297		311
298	Although the callback might get passed parameters, their value and	312	Although the callback might get passed parameters, their value and
299	presence is undefined and you cannot rely on them. Portable AnyEvent	313	presence is undefined and you cannot rely on them. Portable AnyEvent
300	callbacks cannot use arguments passed to signal watcher callbacks.	314	callbacks cannot use arguments passed to signal watcher callbacks.
301		315
…		…
316		330
317	CHILD PROCESS WATCHERS	331	CHILD PROCESS WATCHERS
318	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.
319		333
320	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
321	watches for any child process exit). The watcher will trigger as often	335	watches for any child process exit). The watcher will triggered only
322	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
323	signal handler for "SIGCHLD". The callback will be called with the pid	337	on any trace events (stopped/continued).
324	and exit status (as returned by waitpid), so unlike other watcher types,	338
325	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).
326		347
327	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
328	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
329	could have exited already (and no SIGCHLD will be sent anymore).	350	could have exited already (and no SIGCHLD will be sent anymore).
330		351
…		…
337	an AnyEvent program, you have to create at least one watcher before	358	an AnyEvent program, you have to create at least one watcher before
338	you "fork" the child (alternatively, you can call "AnyEvent::detect").	359	you "fork" the child (alternatively, you can call "AnyEvent::detect").
339		360
340	Example: fork a process and wait for it	361	Example: fork a process and wait for it
341		362
342	my $done = AnyEvent->condvar;	363	my $done = AnyEvent->condvar;
343		364
344	my $pid = fork or exit 5;	365	my $pid = fork or exit 5;
345		366
346	my $w = AnyEvent->child (	367	my $w = AnyEvent->child (
347	pid => $pid,	368	pid => $pid,
348	cb => sub {	369	cb => sub {
349	my ($pid, $status) = @_;	370	my ($pid, $status) = @_;
350	warn "pid $pid exited with status $status";	371	warn "pid $pid exited with status $status";
351	$done->send;	372	$done->send;
352	},	373	},
353	);	374	);
354		375
355	# do something else, then wait for process exit	376	# do something else, then wait for process exit
356	$done->recv;	377	$done->recv;
357		378
358	CONDITION VARIABLES	379	CONDITION VARIABLES
359	If you are familiar with some event loops you will know that all of them	380	If you are familiar with some event loops you will know that all of them
360	require you to run some blocking "loop", "run" or similar function that	381	require you to run some blocking "loop", "run" or similar function that
361	will actively watch for new events and call your callbacks.	382	will actively watch for new events and call your callbacks.
…		…
366	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
367	because they represent a condition that must become true.	388	because they represent a condition that must become true.
368		389
369	Condition variables can be created by calling the "AnyEvent->condvar"	390	Condition variables can be created by calling the "AnyEvent->condvar"
370	method, usually without arguments. The only argument pair allowed is	391	method, usually without arguments. The only argument pair allowed is
		392
371	"cb", which specifies a callback to be called when the condition	393	"cb", which specifies a callback to be called when the condition
372	variable becomes true.	394	variable becomes true, with the condition variable as the first argument
		395	(but not the results).
373		396
374	After creation, the condition variable is "false" until it becomes	397	After creation, the condition variable is "false" until it becomes
375	"true" by calling the "send" method (or calling the condition variable	398	"true" by calling the "send" method (or calling the condition variable
376	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
377	the "->send" method).	400	the "->send" method).
…		…
433		456
434	my $done = AnyEvent->condvar;	457	my $done = AnyEvent->condvar;
435	my $delay = AnyEvent->timer (after => 5, cb => $done);	458	my $delay = AnyEvent->timer (after => 5, cb => $done);
436	$done->recv;	459	$done->recv;
437		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
438	METHODS FOR PRODUCERS	478	METHODS FOR PRODUCERS
439	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
440	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
441	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
442	uncommon for the consumer to create it as well.	482	uncommon for the consumer to create it as well.
…		…
562		602
563	$bool = $cv->ready	603	$bool = $cv->ready
564	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
565	"croak" have been called.	605	"croak" have been called.
566		606
567	$cb = $cv->cb ([new callback])	607	$cb = $cv->cb ($cb->($cv))
568	This is a mutator function that returns the callback set and	608	This is a mutator function that returns the callback set and
569	optionally replaces it before doing so.	609	optionally replaces it before doing so.
570		610
571	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.
572	when "send" or "croak" are called. Calling "recv" inside the	612	when "send" or "croak" are called, with the only argument being the
		613	condition variable itself. Calling "recv" inside the callback or at
573	callback or at any later time is guaranteed not to block.	614	any later time is guaranteed not to block.
574		615
575	GLOBAL VARIABLES AND FUNCTIONS	616	GLOBAL VARIABLES AND FUNCTIONS
576	$AnyEvent::MODEL	617	$AnyEvent::MODEL
577	Contains "undef" until the first watcher is being created. Then it	618	Contains "undef" until the first watcher is being created. Then it
578	contains the event model that is being used, which is the name of	619	contains the event model that is being used, which is the name of
…		…
692	AnyEvent::Util	733	AnyEvent::Util
693	Contains various utility functions that replace often-used but	734	Contains various utility functions that replace often-used but
694	blocking functions such as "inet_aton" by event-/callback-based	735	blocking functions such as "inet_aton" by event-/callback-based
695	versions.	736	versions.
696		737
697	AnyEvent::Handle
698	Provide read and write buffers and manages watchers for reads and
699	writes.
700
701	AnyEvent::Socket	738	AnyEvent::Socket
702	Provides various utility functions for (internet protocol) sockets,	739	Provides various utility functions for (internet protocol) sockets,
703	addresses and name resolution. Also functions to create non-blocking	740	addresses and name resolution. Also functions to create non-blocking
704	tcp connections or tcp servers, with IPv6 and SRV record support and	741	tcp connections or tcp servers, with IPv6 and SRV record support and
705	more.	742	more.
706		743
		744	AnyEvent::Handle
		745	Provide read and write buffers, manages watchers for reads and
		746	writes, supports raw and formatted I/O, I/O queued and fully
		747	transparent and non-blocking SSL/TLS.
		748
707	AnyEvent::DNS	749	AnyEvent::DNS
708	Provides rich asynchronous DNS resolver capabilities.	750	Provides rich asynchronous DNS resolver capabilities.
709		751
		752	AnyEvent::HTTP
		753	A simple-to-use HTTP library that is capable of making a lot of
		754	concurrent HTTP requests.
		755
710	AnyEvent::HTTPD	756	AnyEvent::HTTPD
711	Provides a simple web application server framework.	757	Provides a simple web application server framework.
712		758
713	AnyEvent::FastPing	759	AnyEvent::FastPing
714	The fastest ping in the west.	760	The fastest ping in the west.
		761
		762	AnyEvent::DBI
		763	Executes DBI requests asynchronously in a proxy process.
		764
		765	AnyEvent::AIO
		766	Truly asynchronous I/O, should be in the toolbox of every event
		767	programmer. AnyEvent::AIO transparently fuses IO::AIO and AnyEvent
		768	together.
		769
		770	AnyEvent::BDB
		771	Truly asynchronous Berkeley DB access. AnyEvent::BDB transparently
		772	fuses BDB and AnyEvent together.
		773
		774	AnyEvent::GPSD
		775	A non-blocking interface to gpsd, a daemon delivering GPS
		776	information.
		777
		778	AnyEvent::IGS
		779	A non-blocking interface to the Internet Go Server protocol (used by
		780	App::IGS).
715		781
716	Net::IRC3	782	Net::IRC3
717	AnyEvent based IRC client module family.	783	AnyEvent based IRC client module family.
718		784
719	Net::XMPP2	785	Net::XMPP2
…		…
727	High level API for event-based execution flow control.	793	High level API for event-based execution flow control.
728		794
729	Coro	795	Coro
730	Has special support for AnyEvent via Coro::AnyEvent.	796	Has special support for AnyEvent via Coro::AnyEvent.
731		797
732	AnyEvent::AIO, IO::AIO
733	Truly asynchronous I/O, should be in the toolbox of every event
734	programmer. AnyEvent::AIO transparently fuses IO::AIO and AnyEvent
735	together.
736
737	AnyEvent::BDB, BDB
738	Truly asynchronous Berkeley DB access. AnyEvent::AIO transparently
739	fuses IO::AIO and AnyEvent together.
740
741	IO::Lambda	798	IO::Lambda
742	The lambda approach to I/O - don't ask, look there. Can use	799	The lambda approach to I/O - don't ask, look there. Can use
743	AnyEvent.	800	AnyEvent.
744		801
745	SUPPLYING YOUR OWN EVENT MODEL INTERFACE	802	ERROR AND EXCEPTION HANDLING
746	This is an advanced topic that you do not normally need to use AnyEvent	803	In general, AnyEvent does not do any error handling - it relies on the
747	in a module. This section is only of use to event loop authors who want	804	caller to do that if required. The AnyEvent::Strict module (see also the
748	to provide AnyEvent compatibility.	805	"PERL_ANYEVENT_STRICT" environment variable, below) provides strict
		806	checking of all AnyEvent methods, however, which is highly useful during
		807	development.
749		808
750	If you need to support another event library which isn't directly	809	As for exception handling (i.e. runtime errors and exceptions thrown
751	supported by AnyEvent, you can supply your own interface to it by	810	while executing a callback), this is not only highly event-loop
752	pushing, before the first watcher gets created, the package name of the	811	specific, but also not in any way wrapped by this module, as this is the
753	event module and the package name of the interface to use onto	812	job of the main program.
754	@AnyEvent::REGISTRY. You can do that before and even without loading
755	AnyEvent, so it is reasonably cheap.
756		813
757	Example:	814	The pure perl event loop simply re-throws the exception (usually within
758		815	"condvar->recv"), the Event and EV modules call "$Event/EV::DIED->()",
759	push @AnyEvent::REGISTRY, [urxvt => urxvt::anyevent::];	816	Glib uses "install_exception_handler" and so on.
760
761	This tells AnyEvent to (literally) use the "urxvt::anyevent::"
762	package/class when it finds the "urxvt" package/module is already
763	loaded.
764
765	When AnyEvent is loaded and asked to find a suitable event model, it
766	will first check for the presence of urxvt by trying to "use" the
767	"urxvt::anyevent" module.
768
769	The class should provide implementations for all watcher types. See
770	AnyEvent::Impl::EV (source code), AnyEvent::Impl::Glib (Source code) and
771	so on for actual examples. Use "perldoc -m AnyEvent::Impl::Glib" to see
772	the sources.
773
774	If you don't provide "signal" and "child" watchers than AnyEvent will
775	provide suitable (hopefully) replacements.
776
777	The above example isn't fictitious, the rxvt-unicode (a.k.a. urxvt)
778	terminal emulator uses the above line as-is. An interface isn't included
779	in AnyEvent because it doesn't make sense outside the embedded
780	interpreter inside rxvt-unicode, and it is updated and maintained as
781	part of the rxvt-unicode distribution.
782
783	rxvt-unicode also cheats a bit by not providing blocking access to
784	condition variables: code blocking while waiting for a condition will
785	"die". This still works with most modules/usages, and blocking calls
786	must not be done in an interactive application, so it makes sense.
787		817
788	ENVIRONMENT VARIABLES	818	ENVIRONMENT VARIABLES
789	The following environment variables are used by this module:	819	The following environment variables are used by this module or its
		820	submodules:
790		821
791	"PERL_ANYEVENT_VERBOSE"	822	"PERL_ANYEVENT_VERBOSE"
792	By default, AnyEvent will be completely silent except in fatal	823	By default, AnyEvent will be completely silent except in fatal
793	conditions. You can set this environment variable to make AnyEvent	824	conditions. You can set this environment variable to make AnyEvent
794	more talkative.	825	more talkative.
…		…
797	conditions, such as not being able to load the event model specified	828	conditions, such as not being able to load the event model specified
798	by "PERL_ANYEVENT_MODEL".	829	by "PERL_ANYEVENT_MODEL".
799		830
800	When set to 2 or higher, cause AnyEvent to report to STDERR which	831	When set to 2 or higher, cause AnyEvent to report to STDERR which
801	event model it chooses.	832	event model it chooses.
		833
		834	"PERL_ANYEVENT_STRICT"
		835	AnyEvent does not do much argument checking by default, as thorough
		836	argument checking is very costly. Setting this variable to a true
		837	value will cause AnyEvent to load "AnyEvent::Strict" and then to
		838	thoroughly check the arguments passed to most method calls. If it
		839	finds any problems it will croak.
		840
		841	In other words, enables "strict" mode.
		842
		843	Unlike "use strict", it is definitely recommended ot keep it off in
		844	production. Keeping "PERL_ANYEVENT_STRICT=1" in your environment
		845	while developing programs can be very useful, however.
802		846
803	"PERL_ANYEVENT_MODEL"	847	"PERL_ANYEVENT_MODEL"
804	This can be used to specify the event model to be used by AnyEvent,	848	This can be used to specify the event model to be used by AnyEvent,
805	before auto detection and -probing kicks in. It must be a string	849	before auto detection and -probing kicks in. It must be a string
806	consisting entirely of ASCII letters. The string "AnyEvent::Impl::"	850	consisting entirely of ASCII letters. The string "AnyEvent::Impl::"
…		…
811	This functionality might change in future versions.	855	This functionality might change in future versions.
812		856
813	For example, to force the pure perl model (AnyEvent::Impl::Perl) you	857	For example, to force the pure perl model (AnyEvent::Impl::Perl) you
814	could start your program like this:	858	could start your program like this:
815		859
816	PERL_ANYEVENT_MODEL=Perl perl ...	860	PERL_ANYEVENT_MODEL=Perl perl ...
817		861
818	"PERL_ANYEVENT_PROTOCOLS"	862	"PERL_ANYEVENT_PROTOCOLS"
819	Used by both AnyEvent::DNS and AnyEvent::Socket to determine	863	Used by both AnyEvent::DNS and AnyEvent::Socket to determine
820	preferences for IPv4 or IPv6. The default is unspecified (and might	864	preferences for IPv4 or IPv6. The default is unspecified (and might
821	change, or be the result of auto probing).	865	change, or be the result of auto probing).
…		…
847	EDNS0 in its DNS requests.	891	EDNS0 in its DNS requests.
848		892
849	"PERL_ANYEVENT_MAX_FORKS"	893	"PERL_ANYEVENT_MAX_FORKS"
850	The maximum number of child processes that	894	The maximum number of child processes that
851	"AnyEvent::Util::fork_call" will create in parallel.	895	"AnyEvent::Util::fork_call" will create in parallel.
		896
		897	SUPPLYING YOUR OWN EVENT MODEL INTERFACE
		898	This is an advanced topic that you do not normally need to use AnyEvent
		899	in a module. This section is only of use to event loop authors who want
		900	to provide AnyEvent compatibility.
		901
		902	If you need to support another event library which isn't directly
		903	supported by AnyEvent, you can supply your own interface to it by
		904	pushing, before the first watcher gets created, the package name of the
		905	event module and the package name of the interface to use onto
		906	@AnyEvent::REGISTRY. You can do that before and even without loading
		907	AnyEvent, so it is reasonably cheap.
		908
		909	Example:
		910
		911	push @AnyEvent::REGISTRY, [urxvt => urxvt::anyevent::];
		912
		913	This tells AnyEvent to (literally) use the "urxvt::anyevent::"
		914	package/class when it finds the "urxvt" package/module is already
		915	loaded.
		916
		917	When AnyEvent is loaded and asked to find a suitable event model, it
		918	will first check for the presence of urxvt by trying to "use" the
		919	"urxvt::anyevent" module.
		920
		921	The class should provide implementations for all watcher types. See
		922	AnyEvent::Impl::EV (source code), AnyEvent::Impl::Glib (Source code) and
		923	so on for actual examples. Use "perldoc -m AnyEvent::Impl::Glib" to see
		924	the sources.
		925
		926	If you don't provide "signal" and "child" watchers than AnyEvent will
		927	provide suitable (hopefully) replacements.
		928
		929	The above example isn't fictitious, the rxvt-unicode (a.k.a. urxvt)
		930	terminal emulator uses the above line as-is. An interface isn't included
		931	in AnyEvent because it doesn't make sense outside the embedded
		932	interpreter inside rxvt-unicode, and it is updated and maintained as
		933	part of the rxvt-unicode distribution.
		934
		935	rxvt-unicode also cheats a bit by not providing blocking access to
		936	condition variables: code blocking while waiting for a condition will
		937	"die". This still works with most modules/usages, and blocking calls
		938	must not be done in an interactive application, so it makes sense.
852		939
853	EXAMPLE PROGRAM	940	EXAMPLE PROGRAM
854	The following program uses an I/O watcher to read data from STDIN, a	941	The following program uses an I/O watcher to read data from STDIN, a
855	timer to display a message once per second, and a condition variable to	942	timer to display a message once per second, and a condition variable to
856	quit the program when the user enters quit:	943	quit the program when the user enters quit:
…		…
1262	model than specified in the variable.	1349	model than specified in the variable.
1263		1350
1264	You can make AnyEvent completely ignore this variable by deleting it	1351	You can make AnyEvent completely ignore this variable by deleting it
1265	before the first watcher gets created, e.g. with a "BEGIN" block:	1352	before the first watcher gets created, e.g. with a "BEGIN" block:
1266		1353
1267	BEGIN { delete $ENV{PERL_ANYEVENT_MODEL} }	1354	BEGIN { delete $ENV{PERL_ANYEVENT_MODEL} }
1268		1355
1269	use AnyEvent;	1356	use AnyEvent;
1270		1357
1271	Similar considerations apply to $ENV{PERL_ANYEVENT_VERBOSE}, as that can	1358	Similar considerations apply to $ENV{PERL_ANYEVENT_VERBOSE}, as that can
1272	be used to probe what backend is used and gain other information (which	1359	be used to probe what backend is used and gain other information (which
1273	is probably even less useful to an attacker than PERL_ANYEVENT_MODEL).	1360	is probably even less useful to an attacker than PERL_ANYEVENT_MODEL),
		1361	and $ENV{PERL_ANYEGENT_STRICT}.
		1362
		1363	BUGS
		1364	Perl 5.8 has numerous memleaks that sometimes hit this module and are
		1365	hard to work around. If you suffer from memleaks, first upgrade to Perl
		1366	5.10 and check wether the leaks still show up. (Perl 5.10.0 has other
		1367	annoying mamleaks, such as leaking on "map" and "grep" but it is usually
		1368	not as pronounced).
1274		1369
1275	SEE ALSO	1370	SEE ALSO
1276	Utility functions: AnyEvent::Util.	1371	Utility functions: AnyEvent::Util.
1277		1372
1278	Event modules: EV, EV::Glib, Glib::EV, Event, Glib::Event, Glib, Tk,	1373	Event modules: EV, EV::Glib, Glib::EV, Event, Glib::Event, Glib, Tk,
…		…
1290	Coroutine support: Coro, Coro::AnyEvent, Coro::EV, Coro::Event,	1385	Coroutine support: Coro, Coro::AnyEvent, Coro::EV, Coro::Event,
1291		1386
1292	Nontrivial usage examples: Net::FCP, Net::XMPP2, AnyEvent::DNS.	1387	Nontrivial usage examples: Net::FCP, Net::XMPP2, AnyEvent::DNS.
1293		1388
1294	AUTHOR	1389	AUTHOR
1295	Marc Lehmann <schmorp@schmorp.de>	1390	Marc Lehmann <schmorp@schmorp.de>
1296	http://home.schmorp.de/	1391	http://home.schmorp.de/
1297		1392

Diff Legend

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

Comparing AnyEvent/README (file contents): Revision 1.24 by root, Thu May 29 03:46:04 2008 UTC vs. Revision 1.30 by root, Mon Sep 29 02:08:57 2008 UTC

Diff Legend

Comparing AnyEvent/README (file contents):
Revision 1.24 by root, Thu May 29 03:46:04 2008 UTC vs.
Revision 1.30 by root, Mon Sep 29 02:08:57 2008 UTC