[ViewVC] Diff of: cvs/AnyEvent/README

Comparing AnyEvent/README (file contents):
Revision 1.22 by root, Sat May 24 17:58:33 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
62	only offering the functionality that is necessary, in as thin as a	77	only offering the functionality that is necessary, in as thin as a
63	wrapper as technically possible.	78	wrapper as technically possible.
64		79
		80	Of course, AnyEvent comes with a big (and fully optional!) toolbox of
		81	useful functionality, such as an asynchronous DNS resolver, 100%
		82	non-blocking connects (even with TLS/SSL, IPv6 and on broken platforms
		83	such as Windows) and lots of real-world knowledge and workarounds for
		84	platform bugs and differences.
		85
65	Of course, if you want lots of policy (this can arguably be somewhat	86	Now, if you do want lots of policy (this can arguably be somewhat
66	useful) and you want to force your users to use the one and only event	87	useful) and you want to force your users to use the one and only event
67	model, you should not use this module.	88	model, you should not use this module.
68		89
69	DESCRIPTION	90	DESCRIPTION
70	AnyEvent provides an identical interface to multiple event loops. This	91	AnyEvent provides an identical interface to multiple event loops. This
99	starts using it, all bets are off. Maybe you should tell their authors	120	starts using it, all bets are off. Maybe you should tell their authors
100	to use AnyEvent so their modules work together with others seamlessly...	121	to use AnyEvent so their modules work together with others seamlessly...
101		122
102	The pure-perl implementation of AnyEvent is called	123	The pure-perl implementation of AnyEvent is called
103	"AnyEvent::Impl::Perl". Like other event modules you can load it	124	"AnyEvent::Impl::Perl". Like other event modules you can load it
104	explicitly.	125	explicitly and enjoy the high availability of that event loop :)
105		126
106	WATCHERS	127	WATCHERS
107	AnyEvent has the central concept of a watcher, which is an object that	128	AnyEvent has the central concept of a watcher, which is an object that
108	stores relevant data for each kind of event you are waiting for, such as	129	stores relevant data for each kind of event you are waiting for, such as
109	the callback to call, the file handle to watch, etc.	130	the callback to call, the file handle to watch, etc.
…		…
122	Many watchers either are used with "recursion" (repeating timers for	143	Many watchers either are used with "recursion" (repeating timers for
123	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.
124		145
125	An any way to achieve that is this pattern:	146	An any way to achieve that is this pattern:
126		147
127	my $w; $w = AnyEvent->type (arg => value ..., cb => sub {	148	my $w; $w = AnyEvent->type (arg => value ..., cb => sub {
128	# you can use $w here, for example to undef it	149	# you can use $w here, for example to undef it
129	undef $w;	150	undef $w;
130	});	151	});
131		152
132	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,
133	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
134	declared.	155	declared.
135		156
136	I/O WATCHERS	157	I/O WATCHERS
137	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
138	the following mandatory key-value pairs as arguments:	159	the following mandatory key-value pairs as arguments:
139		160
140	"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).
141	"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
142	watcher waiting for "r"eadable or "w"ritable events, respectively. "cb"	164	watcher waiting for "r"eadable or "w"ritable events, respectively. "cb"
143	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.
144		166
145	Although the callback might get passed parameters, their value and	167	Although the callback might get passed parameters, their value and
…		…
152		174
153	Some event loops issue spurious readyness notifications, so you should	175	Some event loops issue spurious readyness notifications, so you should
154	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
155	handles.	177	handles.
156		178
157	Example:
158
159	# 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
160	my $w; $w = AnyEvent->io (fh => \*STDIN, poll => 'r', cb => sub {	182	my $w; $w = AnyEvent->io (fh => \*STDIN, poll => 'r', cb => sub {
161	chomp (my $input = <STDIN>);	183	chomp (my $input = <STDIN>);
162	warn "read: $input\n";	184	warn "read: $input\n";
163	undef $w;	185	undef $w;
164	});	186	});
…		…
173		195
174	Although the callback might get passed parameters, their value and	196	Although the callback might get passed parameters, their value and
175	presence is undefined and you cannot rely on them. Portable AnyEvent	197	presence is undefined and you cannot rely on them. Portable AnyEvent
176	callbacks cannot use arguments passed to time watcher callbacks.	198	callbacks cannot use arguments passed to time watcher callbacks.
177		199
178	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
179	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
180	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.
181		205
182	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.
183		209
184	# fire an event after 7.7 seconds	210	Example: fire an event after 7.7 seconds.
		211
185	my $w = AnyEvent->timer (after => 7.7, cb => sub {	212	my $w = AnyEvent->timer (after => 7.7, cb => sub {
186	warn "timeout\n";	213	warn "timeout\n";
187	});	214	});
188		215
189	# to cancel the timer:	216	# to cancel the timer:
190	undef $w;	217	undef $w;
191		218
192	Example 2:
193
194	# 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.
195	my $w;
196		220
197	my $cb = sub {
198	# cancel the old timer while creating a new one
199	$w = AnyEvent->timer (after => 1, cb => $cb);	221	my $w = AnyEvent->timer (after => 0.5, interval => 1, cb => sub {
		222	warn "timeout\n";
200	};	223	};
201
202	# start the "loop" by creating the first watcher
203	$w = AnyEvent->timer (after => 0.5, cb => $cb);
204		224
205	TIMING ISSUES	225	TIMING ISSUES
206	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
207	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
208	o'clock").	228	o'clock").
…		…
220	on wallclock time) timers.	240	on wallclock time) timers.
221		241
222	AnyEvent always prefers relative timers, if available, matching the	242	AnyEvent always prefers relative timers, if available, matching the
223	AnyEvent API.	243	AnyEvent API.
224		244
		245	AnyEvent has two additional methods that return the "current time":
		246
		247	AnyEvent->time
		248	This returns the "current wallclock time" as a fractional number of
		249	seconds since the Epoch (the same thing as "time" or
		250	"Time::HiRes::time" return, and the result is guaranteed to be
		251	compatible with those).
		252
		253	It progresses independently of any event loop processing, i.e. each
		254	call will check the system clock, which usually gets updated
		255	frequently.
		256
		257	AnyEvent->now
		258	This also returns the "current wallclock time", but unlike "time",
		259	above, this value might change only once per event loop iteration,
		260	depending on the event loop (most return the same time as "time",
		261	above). This is the time that AnyEvent's timers get scheduled
		262	against.
		263
		264	*In almost all cases (in all cases if you don't care), this is the
		265	function to call when you want to know the current time.*
		266
		267	This function is also often faster then "AnyEvent->time", and thus
		268	the preferred method if you want some timestamp (for example,
		269	AnyEvent::Handle uses this to update it's activity timeouts).
		270
		271	The rest of this section is only of relevance if you try to be very
		272	exact with your timing, you can skip it without bad conscience.
		273
		274	For a practical example of when these times differ, consider
		275	Event::Lib and EV and the following set-up:
		276
		277	The event loop is running and has just invoked one of your callback
		278	at time=500 (assume no other callbacks delay processing). In your
		279	callback, you wait a second by executing "sleep 1" (blocking the
		280	process for a second) and then (at time=501) you create a relative
		281	timer that fires after three seconds.
		282
		283	With Event::Lib, "AnyEvent->time" and "AnyEvent->now" will both
		284	return 501, because that is the current time, and the timer will be
		285	scheduled to fire at time=504 (501 + 3).
		286
		287	With EV, "AnyEvent->time" returns 501 (as that is the current time),
		288	but "AnyEvent->now" returns 500, as that is the time the last event
		289	processing phase started. With EV, your timer gets scheduled to run
		290	at time=503 (500 + 3).
		291
		292	In one sense, Event::Lib is more exact, as it uses the current time
		293	regardless of any delays introduced by event processing. However,
		294	most callbacks do not expect large delays in processing, so this
		295	causes a higher drift (and a lot more system calls to get the
		296	current time).
		297
		298	In another sense, EV is more exact, as your timer will be scheduled
		299	at the same time, regardless of how long event processing actually
		300	took.
		301
		302	In either case, if you care (and in most cases, you don't), then you
		303	can get whatever behaviour you want with any event loop, by taking
		304	the difference between "AnyEvent->time" and "AnyEvent->now" into
		305	account.
		306
225	SIGNAL WATCHERS	307	SIGNAL WATCHERS
226	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
227	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
228	whenever a signal occurs.	310	callback to be invoked whenever a signal occurs.
229		311
230	Although the callback might get passed parameters, their value and	312	Although the callback might get passed parameters, their value and
231	presence is undefined and you cannot rely on them. Portable AnyEvent	313	presence is undefined and you cannot rely on them. Portable AnyEvent
232	callbacks cannot use arguments passed to signal watcher callbacks.	314	callbacks cannot use arguments passed to signal watcher callbacks.
233		315
…		…
248		330
249	CHILD PROCESS WATCHERS	331	CHILD PROCESS WATCHERS
250	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.
251		333
252	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
253	watches for any child process exit). The watcher will trigger as often	335	watches for any child process exit). The watcher will triggered only
254	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
255	signal handler for "SIGCHLD". The callback will be called with the pid	337	on any trace events (stopped/continued).
256	and exit status (as returned by waitpid), so unlike other watcher types,	338
257	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).
258		347
259	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
260	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
261	could have exited already (and no SIGCHLD will be sent anymore).	350	could have exited already (and no SIGCHLD will be sent anymore).
262		351
…		…
269	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
270	you "fork" the child (alternatively, you can call "AnyEvent::detect").	359	you "fork" the child (alternatively, you can call "AnyEvent::detect").
271		360
272	Example: fork a process and wait for it	361	Example: fork a process and wait for it
273		362
274	my $done = AnyEvent->condvar;	363	my $done = AnyEvent->condvar;
275		364
276	my $pid = fork or exit 5;	365	my $pid = fork or exit 5;
277		366
278	my $w = AnyEvent->child (	367	my $w = AnyEvent->child (
279	pid => $pid,	368	pid => $pid,
280	cb => sub {	369	cb => sub {
281	my ($pid, $status) = @_;	370	my ($pid, $status) = @_;
282	warn "pid $pid exited with status $status";	371	warn "pid $pid exited with status $status";
283	$done->send;	372	$done->send;
284	},	373	},
285	);	374	);
286		375
287	# do something else, then wait for process exit	376	# do something else, then wait for process exit
288	$done->recv;	377	$done->recv;
289		378
290	CONDITION VARIABLES	379	CONDITION VARIABLES
291	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
292	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
293	will actively watch for new events and call your callbacks.	382	will actively watch for new events and call your callbacks.
…		…
298	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
299	because they represent a condition that must become true.	388	because they represent a condition that must become true.
300		389
301	Condition variables can be created by calling the "AnyEvent->condvar"	390	Condition variables can be created by calling the "AnyEvent->condvar"
302	method, usually without arguments. The only argument pair allowed is	391	method, usually without arguments. The only argument pair allowed is
		392
303	"cb", which specifies a callback to be called when the condition	393	"cb", which specifies a callback to be called when the condition
304	variable becomes true.	394	variable becomes true, with the condition variable as the first argument
		395	(but not the results).
305		396
306	After creation, the condition variable is "false" until it becomes	397	After creation, the condition variable is "false" until it becomes
307	"true" by calling the "send" method (or calling the condition variable	398	"true" by calling the "send" method (or calling the condition variable
308	as if it were a callback).	399	as if it were a callback, read about the caveats in the description for
		400	the "->send" method).
309		401
310	Condition variables are similar to callbacks, except that you can	402	Condition variables are similar to callbacks, except that you can
311	optionally wait for them. They can also be called merge points - points	403	optionally wait for them. They can also be called merge points - points
312	in time where multiple outstanding events have been processed. And yet	404	in time where multiple outstanding events have been processed. And yet
313	another way to call them is transactions - each condition variable can	405	another way to call them is transactions - each condition variable can
…		…
364		456
365	my $done = AnyEvent->condvar;	457	my $done = AnyEvent->condvar;
366	my $delay = AnyEvent->timer (after => 5, cb => $done);	458	my $delay = AnyEvent->timer (after => 5, cb => $done);
367	$done->recv;	459	$done->recv;
368		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
369	METHODS FOR PRODUCERS	478	METHODS FOR PRODUCERS
370	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
371	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
372	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
373	uncommon for the consumer to create it as well.	482	uncommon for the consumer to create it as well.
…		…
383	Any arguments passed to the "send" call will be returned by all	492	Any arguments passed to the "send" call will be returned by all
384	future "->recv" calls.	493	future "->recv" calls.
385		494
386	Condition variables are overloaded so one can call them directly (as	495	Condition variables are overloaded so one can call them directly (as
387	a code reference). Calling them directly is the same as calling	496	a code reference). Calling them directly is the same as calling
388	"send".	497	"send". Note, however, that many C-based event loops do not handle
		498	overloading, so as tempting as it may be, passing a condition
		499	variable instead of a callback does not work. Both the pure perl and
		500	EV loops support overloading, however, as well as all functions that
		501	use perl to invoke a callback (as in AnyEvent::Socket and
		502	AnyEvent::DNS for example).
389		503
390	$cv->croak ($error)	504	$cv->croak ($error)
391	Similar to send, but causes all call's to "->recv" to invoke	505	Similar to send, but causes all call's to "->recv" to invoke
392	"Carp::croak" with the given error message/object/scalar.	506	"Carp::croak" with the given error message/object/scalar.
393		507
…		…
488		602
489	$bool = $cv->ready	603	$bool = $cv->ready
490	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
491	"croak" have been called.	605	"croak" have been called.
492		606
493	$cb = $cv->cb ([new callback])	607	$cb = $cv->cb ($cb->($cv))
494	This is a mutator function that returns the callback set and	608	This is a mutator function that returns the callback set and
495	optionally replaces it before doing so.	609	optionally replaces it before doing so.
496		610
497	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.
498	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
499	callback or at any later time is guaranteed not to block.	614	any later time is guaranteed not to block.
500		615
501	GLOBAL VARIABLES AND FUNCTIONS	616	GLOBAL VARIABLES AND FUNCTIONS
502	$AnyEvent::MODEL	617	$AnyEvent::MODEL
503	Contains "undef" until the first watcher is being created. Then it	618	Contains "undef" until the first watcher is being created. Then it
504	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
…		…
578	If it doesn't care, it can just "use AnyEvent" and use it itself, or not	693	If it doesn't care, it can just "use AnyEvent" and use it itself, or not
579	do anything special (it does not need to be event-based) and let	694	do anything special (it does not need to be event-based) and let
580	AnyEvent decide which implementation to chose if some module relies on	695	AnyEvent decide which implementation to chose if some module relies on
581	it.	696	it.
582		697
583	If the main program relies on a specific event model. For example, in	698	If the main program relies on a specific event model - for example, in
584	Gtk2 programs you have to rely on the Glib module. You should load the	699	Gtk2 programs you have to rely on the Glib module - you should load the
585	event module before loading AnyEvent or any module that uses it:	700	event module before loading AnyEvent or any module that uses it:
586	generally speaking, you should load it as early as possible. The reason	701	generally speaking, you should load it as early as possible. The reason
587	is that modules might create watchers when they are loaded, and AnyEvent	702	is that modules might create watchers when they are loaded, and AnyEvent
588	will decide on the event model to use as soon as it creates watchers,	703	will decide on the event model to use as soon as it creates watchers,
589	and it might chose the wrong one unless you load the correct one	704	and it might chose the wrong one unless you load the correct one
590	yourself.	705	yourself.
591		706
592	You can chose to use a rather inefficient pure-perl implementation by	707	You can chose to use a pure-perl implementation by loading the
593	loading the "AnyEvent::Impl::Perl" module, which gives you similar	708	"AnyEvent::Impl::Perl" module, which gives you similar behaviour
594	behaviour everywhere, but letting AnyEvent chose is generally better.	709	everywhere, but letting AnyEvent chose the model is generally better.
		710
		711	MAINLOOP EMULATION
		712	Sometimes (often for short test scripts, or even standalone programs who
		713	only want to use AnyEvent), you do not want to run a specific event
		714	loop.
		715
		716	In that case, you can use a condition variable like this:
		717
		718	AnyEvent->condvar->recv;
		719
		720	This has the effect of entering the event loop and looping forever.
		721
		722	Note that usually your program has some exit condition, in which case it
		723	is better to use the "traditional" approach of storing a condition
		724	variable somewhere, waiting for it, and sending it when the program
		725	should exit cleanly.
595		726
596	OTHER MODULES	727	OTHER MODULES
597	The following is a non-exhaustive list of additional modules that use	728	The following is a non-exhaustive list of additional modules that use
598	AnyEvent and can therefore be mixed easily with other AnyEvent modules	729	AnyEvent and can therefore be mixed easily with other AnyEvent modules
599	in the same program. Some of the modules come with AnyEvent, some are	730	in the same program. Some of the modules come with AnyEvent, some are
…		…
602	AnyEvent::Util	733	AnyEvent::Util
603	Contains various utility functions that replace often-used but	734	Contains various utility functions that replace often-used but
604	blocking functions such as "inet_aton" by event-/callback-based	735	blocking functions such as "inet_aton" by event-/callback-based
605	versions.	736	versions.
606		737
607	AnyEvent::Handle
608	Provide read and write buffers and manages watchers for reads and
609	writes.
610
611	AnyEvent::Socket	738	AnyEvent::Socket
612	Provides various utility functions for (internet protocol) sockets,	739	Provides various utility functions for (internet protocol) sockets,
613	addresses and name resolution. Also functions to create non-blocking	740	addresses and name resolution. Also functions to create non-blocking
614	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
615	more.	742	more.
616		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
		749	AnyEvent::DNS
		750	Provides rich asynchronous DNS resolver capabilities.
		751
		752	AnyEvent::HTTP
		753	A simple-to-use HTTP library that is capable of making a lot of
		754	concurrent HTTP requests.
		755
617	AnyEvent::HTTPD	756	AnyEvent::HTTPD
618	Provides a simple web application server framework.	757	Provides a simple web application server framework.
619		758
620	AnyEvent::DNS
621	Provides rich asynchronous DNS resolver capabilities.
622
623	AnyEvent::FastPing	759	AnyEvent::FastPing
624	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).
625		781
626	Net::IRC3	782	Net::IRC3
627	AnyEvent based IRC client module family.	783	AnyEvent based IRC client module family.
628		784
629	Net::XMPP2	785	Net::XMPP2
…		…
637	High level API for event-based execution flow control.	793	High level API for event-based execution flow control.
638		794
639	Coro	795	Coro
640	Has special support for AnyEvent via Coro::AnyEvent.	796	Has special support for AnyEvent via Coro::AnyEvent.
641		797
642	AnyEvent::AIO, IO::AIO
643	Truly asynchronous I/O, should be in the toolbox of every event
644	programmer. AnyEvent::AIO transparently fuses IO::AIO and AnyEvent
645	together.
646
647	AnyEvent::BDB, BDB
648	Truly asynchronous Berkeley DB access. AnyEvent::AIO transparently
649	fuses IO::AIO and AnyEvent together.
650
651	IO::Lambda	798	IO::Lambda
652	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
653	AnyEvent.	800	AnyEvent.
654		801
655	SUPPLYING YOUR OWN EVENT MODEL INTERFACE	802	ERROR AND EXCEPTION HANDLING
656	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
657	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
658	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.
659		808
660	If you need to support another event library which isn't directly	809	As for exception handling (i.e. runtime errors and exceptions thrown
661	supported by AnyEvent, you can supply your own interface to it by	810	while executing a callback), this is not only highly event-loop
662	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
663	event module and the package name of the interface to use onto	812	job of the main program.
664	@AnyEvent::REGISTRY. You can do that before and even without loading
665	AnyEvent, so it is reasonably cheap.
666		813
667	Example:	814	The pure perl event loop simply re-throws the exception (usually within
668		815	"condvar->recv"), the Event and EV modules call "$Event/EV::DIED->()",
669	push @AnyEvent::REGISTRY, [urxvt => urxvt::anyevent::];	816	Glib uses "install_exception_handler" and so on.
670
671	This tells AnyEvent to (literally) use the "urxvt::anyevent::"
672	package/class when it finds the "urxvt" package/module is already
673	loaded.
674
675	When AnyEvent is loaded and asked to find a suitable event model, it
676	will first check for the presence of urxvt by trying to "use" the
677	"urxvt::anyevent" module.
678
679	The class should provide implementations for all watcher types. See
680	AnyEvent::Impl::EV (source code), AnyEvent::Impl::Glib (Source code) and
681	so on for actual examples. Use "perldoc -m AnyEvent::Impl::Glib" to see
682	the sources.
683
684	If you don't provide "signal" and "child" watchers than AnyEvent will
685	provide suitable (hopefully) replacements.
686
687	The above example isn't fictitious, the rxvt-unicode (a.k.a. urxvt)
688	terminal emulator uses the above line as-is. An interface isn't included
689	in AnyEvent because it doesn't make sense outside the embedded
690	interpreter inside rxvt-unicode, and it is updated and maintained as
691	part of the rxvt-unicode distribution.
692
693	rxvt-unicode also cheats a bit by not providing blocking access to
694	condition variables: code blocking while waiting for a condition will
695	"die". This still works with most modules/usages, and blocking calls
696	must not be done in an interactive application, so it makes sense.
697		817
698	ENVIRONMENT VARIABLES	818	ENVIRONMENT VARIABLES
699	The following environment variables are used by this module:	819	The following environment variables are used by this module or its
		820	submodules:
700		821
701	"PERL_ANYEVENT_VERBOSE"	822	"PERL_ANYEVENT_VERBOSE"
702	By default, AnyEvent will be completely silent except in fatal	823	By default, AnyEvent will be completely silent except in fatal
703	conditions. You can set this environment variable to make AnyEvent	824	conditions. You can set this environment variable to make AnyEvent
704	more talkative.	825	more talkative.
…		…
707	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
708	by "PERL_ANYEVENT_MODEL".	829	by "PERL_ANYEVENT_MODEL".
709		830
710	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
711	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.
712		846
713	"PERL_ANYEVENT_MODEL"	847	"PERL_ANYEVENT_MODEL"
714	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,
715	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
716	consisting entirely of ASCII letters. The string "AnyEvent::Impl::"	850	consisting entirely of ASCII letters. The string "AnyEvent::Impl::"
…		…
721	This functionality might change in future versions.	855	This functionality might change in future versions.
722		856
723	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
724	could start your program like this:	858	could start your program like this:
725		859
726	PERL_ANYEVENT_MODEL=Perl perl ...	860	PERL_ANYEVENT_MODEL=Perl perl ...
727		861
728	"PERL_ANYEVENT_PROTOCOLS"	862	"PERL_ANYEVENT_PROTOCOLS"
729	Used by both AnyEvent::DNS and AnyEvent::Socket to determine	863	Used by both AnyEvent::DNS and AnyEvent::Socket to determine
730	preferences for IPv4 or IPv6. The default is unspecified (and might	864	preferences for IPv4 or IPv6. The default is unspecified (and might
731	change, or be the result of auto probing).	865	change, or be the result of auto probing).
…		…
753	but some (broken) firewalls drop such DNS packets, which is why it	887	but some (broken) firewalls drop such DNS packets, which is why it
754	is off by default.	888	is off by default.
755		889
756	Setting this variable to 1 will cause AnyEvent::DNS to announce	890	Setting this variable to 1 will cause AnyEvent::DNS to announce
757	EDNS0 in its DNS requests.	891	EDNS0 in its DNS requests.
		892
		893	"PERL_ANYEVENT_MAX_FORKS"
		894	The maximum number of child processes that
		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.
758		939
759	EXAMPLE PROGRAM	940	EXAMPLE PROGRAM
760	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
761	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
762	quit the program when the user enters quit:	943	quit the program when the user enters quit:
…		…
1168	model than specified in the variable.	1349	model than specified in the variable.
1169		1350
1170	You can make AnyEvent completely ignore this variable by deleting it	1351	You can make AnyEvent completely ignore this variable by deleting it
1171	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:
1172		1353
1173	BEGIN { delete $ENV{PERL_ANYEVENT_MODEL} }	1354	BEGIN { delete $ENV{PERL_ANYEVENT_MODEL} }
1174		1355
1175	use AnyEvent;	1356	use AnyEvent;
1176		1357
1177	Similar considerations apply to $ENV{PERL_ANYEVENT_VERBOSE}, as that can	1358	Similar considerations apply to $ENV{PERL_ANYEVENT_VERBOSE}, as that can
1178	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
1179	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).
1180		1369
1181	SEE ALSO	1370	SEE ALSO
1182	Utility functions: AnyEvent::Util.	1371	Utility functions: AnyEvent::Util.
1183		1372
1184	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,
…		…
1196	Coroutine support: Coro, Coro::AnyEvent, Coro::EV, Coro::Event,	1385	Coroutine support: Coro, Coro::AnyEvent, Coro::EV, Coro::Event,
1197		1386
1198	Nontrivial usage examples: Net::FCP, Net::XMPP2, AnyEvent::DNS.	1387	Nontrivial usage examples: Net::FCP, Net::XMPP2, AnyEvent::DNS.
1199		1388
1200	AUTHOR	1389	AUTHOR
1201	Marc Lehmann <schmorp@schmorp.de>	1390	Marc Lehmann <schmorp@schmorp.de>
1202	http://home.schmorp.de/	1391	http://home.schmorp.de/
1203		1392

Diff Legend

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

Comparing AnyEvent/README (file contents): Revision 1.22 by root, Sat May 24 17:58:33 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.22 by root, Sat May 24 17:58:33 2008 UTC vs.
Revision 1.30 by root, Mon Sep 29 02:08:57 2008 UTC