[ViewVC] Diff of: cvs/AnyEvent/README

Comparing AnyEvent/README (file contents):
Revision 1.46 by root, Sat Jul 18 05:19:09 2009 UTC vs.
Revision 1.50 by root, Sat Aug 1 09:14:54 2009 UTC

…		…
1	NAME	1	NAME
2	AnyEvent - provide framework for multiple event loops	2	AnyEvent - the DBI of event loop programming
3		3
4	EV, Event, Glib, Tk, Perl, Event::Lib, Qt and POE are various supported	4	EV, Event, Glib, Tk, Perl, Event::Lib, Irssi, rxvt-unicode, IO::Async,
5	event loops.	5	Qt and POE are various supported event loops/environments.
6		6
7	SYNOPSIS	7	SYNOPSIS
8	use AnyEvent;	8	use AnyEvent;
9		9
10	# file descriptor readable	10	# file descriptor readable
37		37
38	INTRODUCTION/TUTORIAL	38	INTRODUCTION/TUTORIAL
39	This manpage is mainly a reference manual. If you are interested in a	39	This manpage is mainly a reference manual. If you are interested in a
40	tutorial or some gentle introduction, have a look at the AnyEvent::Intro	40	tutorial or some gentle introduction, have a look at the AnyEvent::Intro
41	manpage.	41	manpage.
		42
		43	SUPPORT
		44	There is a mailinglist for discussing all things AnyEvent, and an IRC
		45	channel, too.
		46
		47	See the AnyEvent project page at the Schmorpforge Ta-Sa Software
		48	Repository, at <http://anyevent.schmorp.de>, for more info.
42		49
43	WHY YOU SHOULD USE THIS MODULE (OR NOT)	50	WHY YOU SHOULD USE THIS MODULE (OR NOT)
44	Glib, POE, IO::Async, Event... CPAN offers event models by the dozen	51	Glib, POE, IO::Async, Event... CPAN offers event models by the dozen
45	nowadays. So what is different about AnyEvent?	52	nowadays. So what is different about AnyEvent?
46		53
…		…
166	Note that "my $w; $w =" combination. This is necessary because in Perl,	173	Note that "my $w; $w =" combination. This is necessary because in Perl,
167	my variables are only visible after the statement in which they are	174	my variables are only visible after the statement in which they are
168	declared.	175	declared.
169		176
170	I/O WATCHERS	177	I/O WATCHERS
		178	$w = AnyEvent->io (
		179	fh => <filehandle_or_fileno>,
		180	poll => <"r" or "w">,
		181	cb => <callback>,
		182	);
		183
171	You can create an I/O watcher by calling the "AnyEvent->io" method with	184	You can create an I/O watcher by calling the "AnyEvent->io" method with
172	the following mandatory key-value pairs as arguments:	185	the following mandatory key-value pairs as arguments:
173		186
174	"fh" is the Perl file handle (or a naked file descriptor) to watch for	187	"fh" is the Perl file handle (or a naked file descriptor) to watch for
175	events (AnyEvent might or might not keep a reference to this file	188	events (AnyEvent might or might not keep a reference to this file
…		…
203	warn "read: $input\n";	216	warn "read: $input\n";
204	undef $w;	217	undef $w;
205	});	218	});
206		219
207	TIME WATCHERS	220	TIME WATCHERS
		221	$w = AnyEvent->timer (after => <seconds>, cb => <callback>);
		222
		223	$w = AnyEvent->timer (
		224	after => <fractional_seconds>,
		225	interval => <fractional_seconds>,
		226	cb => <callback>,
		227	);
		228
208	You can create a time watcher by calling the "AnyEvent->timer" method	229	You can create a time watcher by calling the "AnyEvent->timer" method
209	with the following mandatory arguments:	230	with the following mandatory arguments:
210		231
211	"after" specifies after how many seconds (fractional values are	232	"after" specifies after how many seconds (fractional values are
212	supported) the callback should be invoked. "cb" is the callback to	233	supported) the callback should be invoked. "cb" is the callback to
…		…
336	the event loop's idea of "current time".	357	the event loop's idea of "current time".
337		358
338	Note that updating the time might cause some events to be handled.	359	Note that updating the time might cause some events to be handled.
339		360
340	SIGNAL WATCHERS	361	SIGNAL WATCHERS
		362	$w = AnyEvent->signal (signal => <uppercase_signal_name>, cb => <callback>);
		363
341	You can watch for signals using a signal watcher, "signal" is the signal	364	You can watch for signals using a signal watcher, "signal" is the signal
342	name in uppercase and without any "SIG" prefix, "cb" is the Perl	365	name in uppercase and without any "SIG" prefix, "cb" is the Perl
343	callback to be invoked whenever a signal occurs.	366	callback to be invoked whenever a signal occurs.
344		367
345	Although the callback might get passed parameters, their value and	368	Although the callback might get passed parameters, their value and
…		…
357		380
358	This watcher might use %SIG (depending on the event loop used), so	381	This watcher might use %SIG (depending on the event loop used), so
359	programs overwriting those signals directly will likely not work	382	programs overwriting those signals directly will likely not work
360	correctly.	383	correctly.
361		384
		385	Example: exit on SIGINT
		386
		387	my $w = AnyEvent->signal (signal => "INT", cb => sub { exit 1 });
		388
		389	Signal Races, Delays and Workarounds
362	Also note that many event loops (e.g. Glib, Tk, Qt, IO::Async) do not	390	Many event loops (e.g. Glib, Tk, Qt, IO::Async) do not support attaching
363	support attaching callbacks to signals, which is a pity, as you cannot	391	callbacks to signals in a generic way, which is a pity, as you cannot do
364	do race-free signal handling in perl. AnyEvent will try to do it's best,	392	race-free signal handling in perl, requiring C libraries for this.
365	but in some cases, signals will be delayed. The maximum time a signal	393	AnyEvent will try to do it's best, which means in some cases, signals
366	might be delayed is specified in $AnyEvent::MAX_SIGNAL_LATENCY (default:	394	will be delayed. The maximum time a signal might be delayed is specified
367	10 seconds). This variable can be changed only before the first signal	395	in $AnyEvent::MAX_SIGNAL_LATENCY (default: 10 seconds). This variable
368	watcher is created, and should be left alone otherwise. Higher values	396	can be changed only before the first signal watcher is created, and
		397	should be left alone otherwise. This variable determines how often
		398	AnyEvent polls for signals (in case a wake-up was missed). Higher values
369	will cause fewer spurious wake-ups, which is better for power and CPU	399	will cause fewer spurious wake-ups, which is better for power and CPU
		400	saving.
		401
370	saving. All these problems can be avoided by installing the optional	402	All these problems can be avoided by installing the optional
371	Async::Interrupt module.	403	Async::Interrupt module, which works with most event loops. It will not
372		404	work with inherently broken event loops such as Event or Event::Lib (and
373	Example: exit on SIGINT	405	not with POE currently, as POE does it's own workaround with one-second
374		406	latency). For those, you just have to suffer the delays.
375	my $w = AnyEvent->signal (signal => "INT", cb => sub { exit 1 });
376		407
377	CHILD PROCESS WATCHERS	408	CHILD PROCESS WATCHERS
		409	$w = AnyEvent->child (pid => <process id>, cb => <callback>);
		410
378	You can also watch on a child process exit and catch its exit status.	411	You can also watch on a child process exit and catch its exit status.
379		412
380	The child process is specified by the "pid" argument (if set to 0, it	413	The child process is specified by the "pid" argument (one some backends,
381	watches for any child process exit). The watcher will triggered only	414	using 0 watches for any child process exit, on others this will croak).
382	when the child process has finished and an exit status is available, not	415	The watcher will be triggered only when the child process has finished
383	on any trace events (stopped/continued).	416	and an exit status is available, not on any trace events
		417	(stopped/continued).
384		418
385	The callback will be called with the pid and exit status (as returned by	419	The callback will be called with the pid and exit status (as returned by
386	waitpid), so unlike other watcher types, you can rely on child watcher	420	waitpid), so unlike other watcher types, you can rely on child watcher
387	callback arguments.	421	callback arguments.
388		422
…		…
427		461
428	# do something else, then wait for process exit	462	# do something else, then wait for process exit
429	$done->recv;	463	$done->recv;
430		464
431	IDLE WATCHERS	465	IDLE WATCHERS
		466	$w = AnyEvent->idle (cb => <callback>);
		467
432	Sometimes there is a need to do something, but it is not so important to	468	Sometimes there is a need to do something, but it is not so important to
433	do it instantly, but only when there is nothing better to do. This	469	do it instantly, but only when there is nothing better to do. This
434	"nothing better to do" is usually defined to be "no other events need	470	"nothing better to do" is usually defined to be "no other events need
435	attention by the event loop".	471	attention by the event loop".
436		472
…		…
461	}	497	}
462	});	498	});
463	});	499	});
464		500
465	CONDITION VARIABLES	501	CONDITION VARIABLES
		502	$cv = AnyEvent->condvar;
		503
		504	$cv->send (<list>);
		505	my @res = $cv->recv;
		506
466	If you are familiar with some event loops you will know that all of them	507	If you are familiar with some event loops you will know that all of them
467	require you to run some blocking "loop", "run" or similar function that	508	require you to run some blocking "loop", "run" or similar function that
468	will actively watch for new events and call your callbacks.	509	will actively watch for new events and call your callbacks.
469		510
470	AnyEvent is slightly different: it expects somebody else to run the	511	AnyEvent is slightly different: it expects somebody else to run the
…		…
490	Condition variables are similar to callbacks, except that you can	531	Condition variables are similar to callbacks, except that you can
491	optionally wait for them. They can also be called merge points - points	532	optionally wait for them. They can also be called merge points - points
492	in time where multiple outstanding events have been processed. And yet	533	in time where multiple outstanding events have been processed. And yet
493	another way to call them is transactions - each condition variable can	534	another way to call them is transactions - each condition variable can
494	be used to represent a transaction, which finishes at some point and	535	be used to represent a transaction, which finishes at some point and
495	delivers a result.	536	delivers a result. And yet some people know them as "futures" - a
		537	promise to compute/deliver something that you can wait for.
496		538
497	Condition variables are very useful to signal that something has	539	Condition variables are very useful to signal that something has
498	finished, for example, if you write a module that does asynchronous http	540	finished, for example, if you write a module that does asynchronous http
499	requests, then a condition variable would be the ideal candidate to	541	requests, then a condition variable would be the ideal candidate to
500	signal the availability of results. The user can either act when the	542	signal the availability of results. The user can either act when the
…		…
718		760
719	$cb = $cv->cb ($cb->($cv))	761	$cb = $cv->cb ($cb->($cv))
720	This is a mutator function that returns the callback set and	762	This is a mutator function that returns the callback set and
721	optionally replaces it before doing so.	763	optionally replaces it before doing so.
722		764
723	The callback will be called when the condition becomes "true", i.e.	765	The callback will be called when the condition becomes (or already
724	when "send" or "croak" are called, with the only argument being the	766	was) "true", i.e. when "send" or "croak" are called (or were
725	condition variable itself. Calling "recv" inside the callback or at	767	called), with the only argument being the condition variable itself.
		768	Calling "recv" inside the callback or at any later time is
726	any later time is guaranteed not to block.	769	guaranteed not to block.
727		770
728	SUPPORTED EVENT LOOPS/BACKENDS	771	SUPPORTED EVENT LOOPS/BACKENDS
729	The available backend classes are (every class has its own manpage):	772	The available backend classes are (every class has its own manpage):
730		773
731	Backends that are autoprobed when no other event loop can be found.	774	Backends that are autoprobed when no other event loop can be found.
…		…
748		791
749	AnyEvent::Impl::Glib based on Glib, slow but very stable.	792	AnyEvent::Impl::Glib based on Glib, slow but very stable.
750	AnyEvent::Impl::Tk based on Tk, very broken.	793	AnyEvent::Impl::Tk based on Tk, very broken.
751	AnyEvent::Impl::EventLib based on Event::Lib, leaks memory and worse.	794	AnyEvent::Impl::EventLib based on Event::Lib, leaks memory and worse.
752	AnyEvent::Impl::POE based on POE, very slow, some limitations.	795	AnyEvent::Impl::POE based on POE, very slow, some limitations.
		796	AnyEvent::Impl::Irssi used when running within irssi.
753		797
754	Backends with special needs.	798	Backends with special needs.
755	Qt requires the Qt::Application to be instantiated first, but will	799	Qt requires the Qt::Application to be instantiated first, but will
756	otherwise be picked up automatically. As long as the main program	800	otherwise be picked up automatically. As long as the main program
757	instantiates the application before any AnyEvent watchers are	801	instantiates the application before any AnyEvent watchers are
…		…
822	creates and installs the global IO::AIO watcher in a "post_detect"	866	creates and installs the global IO::AIO watcher in a "post_detect"
823	block to avoid autodetecting the event module at load time.	867	block to avoid autodetecting the event module at load time.
824		868
825	If called in scalar or list context, then it creates and returns an	869	If called in scalar or list context, then it creates and returns an
826	object that automatically removes the callback again when it is	870	object that automatically removes the callback again when it is
		871	destroyed (or "undef" when the hook was immediately executed). See
827	destroyed. See Coro::BDB for a case where this is useful.	872	AnyEvent::AIO for a case where this is useful.
		873
		874	Example: Create a watcher for the IO::AIO module and store it in
		875	$WATCHER. Only do so after the event loop is initialised, though.
		876
		877	our WATCHER;
		878
		879	my $guard = AnyEvent::post_detect {
		880	$WATCHER = AnyEvent->io (fh => IO::AIO::poll_fileno, poll => 'r', cb => \&IO::AIO::poll_cb);
		881	};
		882
		883	# the \|\|= is important in case post_detect immediately runs the block,
		884	# as to not clobber the newly-created watcher. assigning both watcher and
		885	# post_detect guard to the same variable has the advantage of users being
		886	# able to just C<undef $WATCHER> if the watcher causes them grief.
		887
		888	$WATCHER \|\|= $guard;
828		889
829	@AnyEvent::post_detect	890	@AnyEvent::post_detect
830	If there are any code references in this array (you can "push" to it	891	If there are any code references in this array (you can "push" to it
831	before or after loading AnyEvent), then they will called directly	892	before or after loading AnyEvent), then they will called directly
832	after the event loop has been chosen.	893	after the event loop has been chosen.
…		…
1644	Async::Interrupt	1705	Async::Interrupt
1645	This slightly arcane module is used to implement fast signal	1706	This slightly arcane module is used to implement fast signal
1646	handling: To my knowledge, there is no way to do completely	1707	handling: To my knowledge, there is no way to do completely
1647	race-free and quick signal handling in pure perl. To ensure that	1708	race-free and quick signal handling in pure perl. To ensure that
1648	signals still get delivered, AnyEvent will start an interval timer	1709	signals still get delivered, AnyEvent will start an interval timer
1649	to wake up perl (and catch the signals) with soemd elay (default is	1710	to wake up perl (and catch the signals) with some delay (default is
1650	10 seconds, look for $AnyEvent::MAX_SIGNAL_LATENCY).	1711	10 seconds, look for $AnyEvent::MAX_SIGNAL_LATENCY).
1651		1712
1652	If this module is available, then it will be used to implement	1713	If this module is available, then it will be used to implement
1653	signal catching, which means that signals will not be delayed, and	1714	signal catching, which means that signals will not be delayed, and
1654	the event loop will not be interrupted regularly, which is more	1715	the event loop will not be interrupted regularly, which is more
1655	efficient (And good for battery life on laptops).	1716	efficient (And good for battery life on laptops).
1656		1717
1657	This affects not just the pure-perl event loop, but also other event	1718	This affects not just the pure-perl event loop, but also other event
1658	loops that have no signal handling on their own (e.g. Glib, Tk, Qt).	1719	loops that have no signal handling on their own (e.g. Glib, Tk, Qt).
		1720
		1721	Some event loops (POE, Event, Event::Lib) offer signal watchers
		1722	natively, and either employ their own workarounds (POE) or use
		1723	AnyEvent's workaround (using $AnyEvent::MAX_SIGNAL_LATENCY).
		1724	Installing Async::Interrupt does nothing for those backends.
1659		1725
1660	EV This module isn't really "optional", as it is simply one of the	1726	EV This module isn't really "optional", as it is simply one of the
1661	backend event loops that AnyEvent can use. However, it is simply the	1727	backend event loops that AnyEvent can use. However, it is simply the
1662	best event loop available in terms of features, speed and stability:	1728	best event loop available in terms of features, speed and stability:
1663	It supports the AnyEvent API optimally, implements all the watcher	1729	It supports the AnyEvent API optimally, implements all the watcher
…		…
1674	operation much. It is purely used for performance.	1740	operation much. It is purely used for performance.
1675		1741
1676	JSON and JSON::XS	1742	JSON and JSON::XS
1677	This module is required when you want to read or write JSON data via	1743	This module is required when you want to read or write JSON data via
1678	AnyEvent::Handle. It is also written in pure-perl, but can take	1744	AnyEvent::Handle. It is also written in pure-perl, but can take
1679	advantage of the ulta-high-speed JSON::XS module when it is	1745	advantage of the ultra-high-speed JSON::XS module when it is
1680	installed.	1746	installed.
1681		1747
1682	In fact, AnyEvent::Handle will use JSON::XS by default if it is	1748	In fact, AnyEvent::Handle will use JSON::XS by default if it is
1683	installed.	1749	installed.
1684		1750
…		…
1741	Event::Lib, Qt, POE.	1807	Event::Lib, Qt, POE.
1742		1808
1743	Implementations: AnyEvent::Impl::EV, AnyEvent::Impl::Event,	1809	Implementations: AnyEvent::Impl::EV, AnyEvent::Impl::Event,
1744	AnyEvent::Impl::Glib, AnyEvent::Impl::Tk, AnyEvent::Impl::Perl,	1810	AnyEvent::Impl::Glib, AnyEvent::Impl::Tk, AnyEvent::Impl::Perl,
1745	AnyEvent::Impl::EventLib, AnyEvent::Impl::Qt, AnyEvent::Impl::POE,	1811	AnyEvent::Impl::EventLib, AnyEvent::Impl::Qt, AnyEvent::Impl::POE,
1746	AnyEvent::Impl::IOAsync.	1812	AnyEvent::Impl::IOAsync, Anyevent::Impl::Irssi.
1747		1813
1748	Non-blocking file handles, sockets, TCP clients and servers:	1814	Non-blocking file handles, sockets, TCP clients and servers:
1749	AnyEvent::Handle, AnyEvent::Socket, AnyEvent::TLS.	1815	AnyEvent::Handle, AnyEvent::Socket, AnyEvent::TLS.
1750		1816
1751	Asynchronous DNS: AnyEvent::DNS.	1817	Asynchronous DNS: AnyEvent::DNS.

Diff Legend

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

Comparing AnyEvent/README (file contents): Revision 1.46 by root, Sat Jul 18 05:19:09 2009 UTC vs. Revision 1.50 by root, Sat Aug 1 09:14:54 2009 UTC

Diff Legend

Comparing AnyEvent/README (file contents):
Revision 1.46 by root, Sat Jul 18 05:19:09 2009 UTC vs.
Revision 1.50 by root, Sat Aug 1 09:14:54 2009 UTC