[ViewVC] Diff of: cvs/EV/README

Comparing EV/README (file contents):
Revision 1.31 by root, Wed Nov 19 10:33:32 2008 UTC vs.
Revision 1.36 by root, Thu Oct 21 02:46:59 2010 UTC

…		…
2	EV - perl interface to libev, a high performance full-featured event	2	EV - perl interface to libev, a high performance full-featured event
3	loop	3	loop
4		4
5	SYNOPSIS	5	SYNOPSIS
6	use EV;	6	use EV;
7		7
8	# TIMERS	8	# TIMERS
9		9
10	my $w = EV::timer 2, 0, sub {	10	my $w = EV::timer 2, 0, sub {
11	warn "is called after 2s";	11	warn "is called after 2s";
12	};	12	};
13		13
14	my $w = EV::timer 2, 2, sub {	14	my $w = EV::timer 2, 2, sub {
15	warn "is called roughly every 2s (repeat = 2)";	15	warn "is called roughly every 2s (repeat = 2)";
16	};	16	};
17		17
18	undef $w; # destroy event watcher again	18	undef $w; # destroy event watcher again
19		19
20	my $w = EV::periodic 0, 60, 0, sub {	20	my $w = EV::periodic 0, 60, 0, sub {
21	warn "is called every minute, on the minute, exactly";	21	warn "is called every minute, on the minute, exactly";
22	};	22	};
		23
23		24	# IO
24	# IO	25
25
26	my $w = EV::io *STDIN, EV::READ, sub {	26	my $w = EV::io *STDIN, EV::READ, sub {
27	my ($w, $revents) = @_; # all callbacks receive the watcher and event mask	27	my ($w, $revents) = @_; # all callbacks receive the watcher and event mask
28	warn "stdin is readable, you entered: ", <STDIN>;	28	warn "stdin is readable, you entered: ", <STDIN>;
29	};	29	};
30		30
31	# SIGNALS	31	# SIGNALS
32		32
33	my $w = EV::signal 'QUIT', sub {	33	my $w = EV::signal 'QUIT', sub {
34	warn "sigquit received\n";	34	warn "sigquit received\n";
35	};	35	};
36		36
37	# CHILD/PID STATUS CHANGES	37	# CHILD/PID STATUS CHANGES
38		38
39	my $w = EV::child 666, 0, sub {	39	my $w = EV::child 666, 0, sub {
40	my ($w, $revents) = @_;	40	my ($w, $revents) = @_;
41	my $status = $w->rstatus;	41	my $status = $w->rstatus;
42	};	42	};
43		43
44	# STAT CHANGES	44	# STAT CHANGES
45	my $w = EV::stat "/etc/passwd", 10, sub {	45	my $w = EV::stat "/etc/passwd", 10, sub {
46	my ($w, $revents) = @_;	46	my ($w, $revents) = @_;
47	warn $w->path, " has changed somehow.\n";	47	warn $w->path, " has changed somehow.\n";
48	};	48	};
49		49
50	# MAINLOOP	50	# MAINLOOP
51	EV::loop; # loop until EV::unloop is called or all watchers stop	51	EV::loop; # loop until EV::unloop is called or all watchers stop
52	EV::loop EV::LOOP_ONESHOT; # block until at least one event could be handled	52	EV::loop EV::LOOP_ONESHOT; # block until at least one event could be handled
53	EV::loop EV::LOOP_NONBLOCK; # try to handle same events, but do not block	53	EV::loop EV::LOOP_NONBLOCK; # try to handle same events, but do not block
		54
		55	BEFORE YOU START USING THIS MODULE
		56	If you only need timer, I/O, signal, child and idle watchers and not the
		57	advanced functionality of this module, consider using AnyEvent instead,
		58	specifically the simplified API described in AE.
		59
		60	When used with EV as backend, the AE API is as fast as the native EV
		61	API, but your programs/modules will still run with many other event
		62	loops.
54		63
55	DESCRIPTION	64	DESCRIPTION
56	This module provides an interface to libev	65	This module provides an interface to libev
57	(<http://software.schmorp.de/pkg/libev.html>). While the documentation	66	(<http://software.schmorp.de/pkg/libev.html>). While the documentation
58	below is comprehensive, one might also consult the documentation of	67	below is comprehensive, one might also consult the documentation of
…		…
91	embed a kqueue loop into the default loop: running the default loop	100	embed a kqueue loop into the default loop: running the default loop
92	will then also service the kqueue loop to some extent. See the example	101	will then also service the kqueue loop to some extent. See the example
93	in the section about embed watchers for an example on how to achieve	102	in the section about embed watchers for an example on how to achieve
94	that.	103	that.
95		104
96	$loop = new EV::loop [$flags]	105	$loop = new EV::Loop [$flags]
97	Create a new event loop as per the specified flags. Please refer to	106	Create a new event loop as per the specified flags. Please refer to
98	the "ev_loop_new ()" function description in the libev documentation	107	the "ev_loop_new ()" function description in the libev documentation
99	(<http://pod.tst.eu/http://cvs.schmorp.de/libev/ev.pod#GLOBAL_FUNCTI	108	(<http://pod.tst.eu/http://cvs.schmorp.de/libev/ev.pod#GLOBAL_FUNCTI
100	ONS>, or locally-installed as EV::libev manpage) for more info.	109	ONS>, or locally-installed as EV::libev manpage) for more info.
101		110
…		…
152	$time = $loop->now	161	$time = $loop->now
153	Returns the time the last event loop iteration has been started.	162	Returns the time the last event loop iteration has been started.
154	This is the time that (relative) timers are based on, and referring	163	This is the time that (relative) timers are based on, and referring
155	to it is usually faster then calling EV::time.	164	to it is usually faster then calling EV::time.
156		165
		166	EV::now_update
		167	$loop->now_update
		168	Establishes the current time by querying the kernel, updating the
		169	time returned by "EV::now" in the progress. This is a costly
		170	operation and is usually done automatically within "EV::loop".
		171
		172	This function is rarely useful, but when some event callback runs
		173	for a very long time without entering the event loop, updating
		174	libev's idea of the current time is a good idea.
		175
		176	EV::suspend
		177	$loop->suspend
		178	EV::resume
		179	$loop->resume
		180	These two functions suspend and resume a loop, for use when the loop
		181	is not used for a while and timeouts should not be processed.
		182
		183	A typical use case would be an interactive program such as a game:
		184	When the user presses "^Z" to suspend the game and resumes it an
		185	hour later it would be best to handle timeouts as if no time had
		186	actually passed while the program was suspended. This can be
		187	achieved by calling "suspend" in your "SIGTSTP" handler, sending
		188	yourself a "SIGSTOP" and calling "resume" directly afterwards to
		189	resume timer processing.
		190
		191	Effectively, all "timer" watchers will be delayed by the time spend
		192	between "suspend" and "resume", and all "periodic" watchers will be
		193	rescheduled (that is, they will lose any events that would have
		194	occured while suspended).
		195
		196	After calling "suspend" you must not call any function on the
		197	given loop other than "resume", and you must not call "resume"
		198	without a previous call to "suspend".
		199
		200	Calling "suspend"/"resume" has the side effect of updating the event
		201	loop time (see "now_update").
		202
157	$backend = EV::backend	203	$backend = EV::backend
158	$backend = $loop->backend	204	$backend = $loop->backend
159	Returns an integer describing the backend used by libev	205	Returns an integer describing the backend used by libev
160	(EV::BACKEND_SELECT or EV::BACKEND_EPOLL).	206	(EV::BACKEND_SELECT or EV::BACKEND_EPOLL).
161		207
…		…
198	Otherwise a EV::timer with this value will be started.	244	Otherwise a EV::timer with this value will be started.
199		245
200	When an error occurs or either the timeout or I/O watcher triggers,	246	When an error occurs or either the timeout or I/O watcher triggers,
201	then the callback will be called with the received event set (in	247	then the callback will be called with the received event set (in
202	general you can expect it to be a combination of "EV::ERROR",	248	general you can expect it to be a combination of "EV::ERROR",
203	"EV::READ", "EV::WRITE" and "EV::TIMEOUT").	249	"EV::READ", "EV::WRITE" and "EV::TIMER").
204		250
205	EV::once doesn't return anything: the watchers stay active till	251	EV::once doesn't return anything: the watchers stay active till
206	either of them triggers, then they will be stopped and freed, and	252	either of them triggers, then they will be stopped and freed, and
207	the callback invoked.	253	the callback invoked.
208		254
…		…
226	the libev documentation at	272	the libev documentation at
227	<http://pod.tst.eu/http://cvs.schmorp.de/libev/ev.pod#FUNCTIONS_CONT	273	<http://pod.tst.eu/http://cvs.schmorp.de/libev/ev.pod#FUNCTIONS_CONT
228	ROLLING_THE_EVENT_LOOP> (locally installed as EV::libev) for a more	274	ROLLING_THE_EVENT_LOOP> (locally installed as EV::libev) for a more
229	detailed discussion.	275	detailed discussion.
230		276
		277	$count = EV::pending_count
		278	$count = $loop->pending_count
		279	Returns the number of currently pending watchers.
		280
		281	EV::invoke_pending
		282	$loop->invoke_pending
		283	Invoke all currently pending watchers.
		284
231	WATCHER OBJECTS	285	WATCHER OBJECTS
232	A watcher is an object that gets created to record your interest in some	286	A watcher is an object that gets created to record your interest in some
233	event. For instance, if you want to wait for STDIN to become readable,	287	event. For instance, if you want to wait for STDIN to become readable,
234	you would create an EV::io watcher for that:	288	you would create an EV::io watcher for that:
235		289
…		…
245		299
246	Each watcher type has its associated bit in revents, so you can use the	300	Each watcher type has its associated bit in revents, so you can use the
247	same callback for multiple watchers. The event mask is named after the	301	same callback for multiple watchers. The event mask is named after the
248	type, i.e. EV::child sets EV::CHILD, EV::prepare sets EV::PREPARE,	302	type, i.e. EV::child sets EV::CHILD, EV::prepare sets EV::PREPARE,
249	EV::periodic sets EV::PERIODIC and so on, with the exception of I/O	303	EV::periodic sets EV::PERIODIC and so on, with the exception of I/O
250	events (which can set both EV::READ and EV::WRITE bits), and EV::timer	304	events (which can set both EV::READ and EV::WRITE bits).
251	(which uses EV::TIMEOUT).
252		305
253	In the rare case where one wants to create a watcher but not start it at	306	In the rare case where one wants to create a watcher but not start it at
254	the same time, each constructor has a variant with a trailing "_ns" in	307	the same time, each constructor has a variant with a trailing "_ns" in
255	its name, e.g. EV::io has a non-starting variant EV::io_ns and so on.	308	its name, e.g. EV::io has a non-starting variant EV::io_ns and so on.
256		309
…		…
321	the watcher isn't pending it does nothing and returns 0.	374	the watcher isn't pending it does nothing and returns 0.
322		375
323	$previous_state = $w->keepalive ($bool)	376	$previous_state = $w->keepalive ($bool)
324	Normally, "EV::loop" will return when there are no active watchers	377	Normally, "EV::loop" will return when there are no active watchers
325	(which is a "deadlock" because no progress can be made anymore).	378	(which is a "deadlock" because no progress can be made anymore).
326	This is convinient because it allows you to start your watchers (and	379	This is convenient because it allows you to start your watchers (and
327	your jobs), call "EV::loop" once and when it returns you know that	380	your jobs), call "EV::loop" once and when it returns you know that
328	all your jobs are finished (or they forgot to register some watchers	381	all your jobs are finished (or they forgot to register some watchers
329	for their task :).	382	for their task :).
330		383
331	Sometimes, however, this gets in your way, for example when the	384	Sometimes, however, this gets in your way, for example when the
…		…
522	Return the time that the watcher is expected to trigger next.	575	Return the time that the watcher is expected to trigger next.
523		576
524	SIGNAL WATCHERS - signal me when a signal gets signalled!	577	SIGNAL WATCHERS - signal me when a signal gets signalled!
525	$w = EV::signal $signal, $callback	578	$w = EV::signal $signal, $callback
526	$w = EV::signal_ns $signal, $callback	579	$w = EV::signal_ns $signal, $callback
		580	$w = $loop->signal ($signal, $callback)
		581	$w = $loop->signal_ns ($signal, $callback)
527	Call the callback when $signal is received (the signal can be	582	Call the callback when $signal is received (the signal can be
528	specified by number or by name, just as with "kill" or %SIG).	583	specified by number or by name, just as with "kill" or %SIG).
		584
		585	Only one event loop can grab a given signal - attempting to grab the
		586	same signal from two EV loops will crash the program immediately or
		587	cause data corruption.
529		588
530	EV will grab the signal for the process (the kernel only allows one	589	EV will grab the signal for the process (the kernel only allows one
531	component to receive a signal at a time) when you start a signal	590	component to receive a signal at a time) when you start a signal
532	watcher, and removes it again when you stop it. Perl does the same	591	watcher, and removes it again when you stop it. Perl does the same
533	when you add/remove callbacks to %SIG, so watch out.	592	when you add/remove callbacks to %SIG, so watch out.
…		…
783		842
784	In short, this watcher is most useful on BSD systems without working	843	In short, this watcher is most useful on BSD systems without working
785	kqueue to still be able to handle a large number of sockets:	844	kqueue to still be able to handle a large number of sockets:
786		845
787	my $socket_loop;	846	my $socket_loop;
788		847
789	# check wether we use SELECT or POLL _and_ KQUEUE is supported	848	# check wether we use SELECT or POLL _and_ KQUEUE is supported
790	if (	849	if (
791	(EV::backend & (EV::BACKEND_POLL \| EV::BACKEND_SELECT))	850	(EV::backend & (EV::BACKEND_POLL \| EV::BACKEND_SELECT))
792	&& (EV::supported_backends & EV::embeddable_backends & EV::BACKEND_KQUEUE)	851	&& (EV::supported_backends & EV::embeddable_backends & EV::BACKEND_KQUEUE)
793	) {	852	) {
794	# use kqueue for sockets	853	# use kqueue for sockets
795	$socket_loop = new EV::Loop EV::BACKEND_KQUEUE \| EV::FLAG_NOENV;	854	$socket_loop = new EV::Loop EV::BACKEND_KQUEUE \| EV::FLAG_NOENV;
796	}	855	}
797		856
798	# use the default loop otherwise	857	# use the default loop otherwise
799	$socket_loop \|\|= EV::default_loop;	858	$socket_loop \|\|= EV::default_loop;
800		859
801	$w = EV::embed $otherloop[, $callback]	860	$w = EV::embed $otherloop[, $callback]
802	$w = EV::embed_ns $otherloop[, $callback]	861	$w = EV::embed_ns $otherloop[, $callback]
803	$w = $loop->embed ($otherloop[, $callback])	862	$w = $loop->embed ($otherloop[, $callback])
…		…
810	The "embed_ns" variant doesn't start (activate) the newly created	869	The "embed_ns" variant doesn't start (activate) the newly created
811	watcher.	870	watcher.
812		871
813	ASYNC WATCHERS - how to wake up another event loop	872	ASYNC WATCHERS - how to wake up another event loop
814	Async watchers are provided by EV, but have little use in perl directly,	873	Async watchers are provided by EV, but have little use in perl directly,
815	as perl neither supports threads nor direct access to signal handlers or	874	as perl neither supports threads running in parallel nor direct access
816	other contexts where they could be of value.	875	to signal handlers or other contexts where they could be of value.
817		876
818	It is, however, possible to use them from the XS level.	877	It is, however, possible to use them from the XS level.
819		878
820	Please see the libev documentation for further details.	879	Please see the libev documentation for further details.
821		880
…		…
840	my $async_check = EV::check sub { };	899	my $async_check = EV::check sub { };
841		900
842	This ensures that perl gets into control for a short time to handle any	901	This ensures that perl gets into control for a short time to handle any
843	pending signals, and also ensures (slightly) slower overall operation.	902	pending signals, and also ensures (slightly) slower overall operation.
844		903
845	THREADS	904	ITHREADS
846	Threads are not supported by this module in any way. Perl pseudo-threads	905	Ithreads are not supported by this module in any way. Perl
847	is evil stuff and must die. As soon as Perl gains real threads I will	906	pseudo-threads is evil stuff and must die. Real threads as provided by
848	work on thread support for it.	907	Coro are fully supported (and enhanced support is available via
		908	Coro::EV).
849		909
850	FORK	910	FORK
851	Most of the "improved" event delivering mechanisms of modern operating	911	Most of the "improved" event delivering mechanisms of modern operating
852	systems have quite a few problems with fork(2) (to put it bluntly: it is	912	systems have quite a few problems with fork(2) (to put it bluntly: it is
853	not supported and usually destructive). Libev makes it possible to work	913	not supported and usually destructive). Libev makes it possible to work

Diff Legend

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

Comparing EV/README (file contents): Revision 1.31 by root, Wed Nov 19 10:33:32 2008 UTC vs. Revision 1.36 by root, Thu Oct 21 02:46:59 2010 UTC

Diff Legend

Comparing EV/README (file contents):
Revision 1.31 by root, Wed Nov 19 10:33:32 2008 UTC vs.
Revision 1.36 by root, Thu Oct 21 02:46:59 2010 UTC