[ViewVC] Diff of: cvs/EV/README

Comparing EV/README (file contents):
Revision 1.14 by root, Wed Nov 28 19:22:16 2007 UTC vs.
Revision 1.24 by root, Wed Apr 16 17:08:29 2008 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
24	# IO	23
25		24	# IO
		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, 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		54
55	DESCRIPTION	55	DESCRIPTION
56	This module provides an interface to libev	56	This module provides an interface to libev
57	(<http://software.schmorp.de/pkg/libev.html>). While the documentation	57	(<http://software.schmorp.de/pkg/libev.html>). While the documentation
58	below is comprehensive, one might also consult the documentation of	58	below is comprehensive, one might also consult the documentation of
59	libev itself (<http://cvs.schmorp.de/libev/ev.html>) for more subtle	59	libev itself (<http://cvs.schmorp.de/libev/ev.html>) for more subtle
60	details on watcher semantics or some discussion on the available	60	details on watcher semantics or some discussion on the available
61	backends, or how to force a specific backend with "LIBEV_FLAGS".	61	backends, or how to force a specific backend with "LIBEV_FLAGS", or just
		62	about in any case because it has much more detailed information.
		63
		64	EVENT LOOPS
		65	EV supports multiple event loops: There is a single "default event loop"
		66	that can handle everything including signals and child watchers, and any
		67	number of "dynamic event loops" that can use different backends (with
		68	various limitations), but no child and signal watchers.
		69
		70	You do not have to do anything to create the default event loop: When
		71	the module is loaded a suitable backend is selected on the premise of
		72	selecting a working backend (which for example rules out kqueue on most
		73	BSDs). Modules should, unless they have "special needs" always use the
		74	default loop as this is fastest (perl-wise), best supported by other
		75	modules (e.g. AnyEvent or Coro) and most portable event loop.
		76
		77	For specific programs you can create additional event loops dynamically.
		78
		79	$loop = new EV::loop [$flags]
		80	Create a new event loop as per the specified flags. Please refer to
		81	the "ev_loop_new ()" function description in the libev documentation
		82	(<http://pod.tst.eu/http://cvs.schmorp.de/libev/ev.pod#GLOBAL_FUNCTI
		83	ONS>) for more info.
		84
		85	The loop will automatically be destroyed when it is no longer
		86	referenced by any watcher and the loop object goes out of scope.
		87
		88	Using "EV::FLAG_FORKCHECK" is recommended, as only the default event
		89	loop is protected by this module.
		90
		91	$loop->loop_fork
		92	Must be called after a fork in the child, before entering or
		93	continuing the event loop. An alternative is to use
		94	"EV::FLAG_FORKCHECK" which calls this fucntion automatically, at
		95	some performance loss (refer to the libev documentation).
		96
		97	$loop = EV::default_loop [$flags]
		98	Return the default loop (which is a singleton object).
62		99
63	BASIC INTERFACE	100	BASIC INTERFACE
64	$EV::DIED	101	$EV::DIED
65	Must contain a reference to a function that is called when a	102	Must contain a reference to a function that is called when a
66	callback throws an exception (with $@ containing thr error). The	103	callback throws an exception (with $@ containing the error). The
67	default prints an informative message and continues.	104	default prints an informative message and continues.
68		105
69	If this callback throws an exception it will be silently ignored.	106	If this callback throws an exception it will be silently ignored.
		107
		108	$flags = EV::supported_backends
		109	$flags = EV::recommended_backends
		110	$flags = EV::embeddable_backends
		111	Returns the set (see "EV::BACKEND_*" flags) of backends supported by
		112	this instance of EV, the set of recommended backends (supposed to be
		113	good) for this platform and the set of embeddable backends (see
		114	EMBED WATCHERS).
		115
		116	EV::sleep $seconds
		117	Block the process for the given number of (fractional) seconds.
70		118
71	$time = EV::time	119	$time = EV::time
72	Returns the current time in (fractional) seconds since the epoch.	120	Returns the current time in (fractional) seconds since the epoch.
73		121
74	$time = EV::now	122	$time = EV::now
		123	$time = $loop->now
75	Returns the time the last event loop iteration has been started.	124	Returns the time the last event loop iteration has been started.
76	This is the time that (relative) timers are based on, and refering	125	This is the time that (relative) timers are based on, and refering
77	to it is usually faster then calling EV::time.	126	to it is usually faster then calling EV::time.
78		127
79	$method = EV::method	128	$backend = EV::backend
		129	$backend = $loop->backend
80	Returns an integer describing the backend used by libev	130	Returns an integer describing the backend used by libev
81	(EV::METHOD_SELECT or EV::METHOD_EPOLL).	131	(EV::METHOD_SELECT or EV::METHOD_EPOLL).
82		132
83	EV::loop [$flags]	133	EV::loop [$flags]
		134	$loop->loop ([$flags])
84	Begin checking for events and calling callbacks. It returns when a	135	Begin checking for events and calling callbacks. It returns when a
85	callback calls EV::unloop.	136	callback calls EV::unloop.
86		137
87	The $flags argument can be one of the following:	138	The $flags argument can be one of the following:
88		139
89	0 as above	140	0 as above
90	EV::LOOP_ONESHOT block at most once (wait, but do not loop)	141	EV::LOOP_ONESHOT block at most once (wait, but do not loop)
91	EV::LOOP_NONBLOCK do not block at all (fetch/handle events but do not wait)	142	EV::LOOP_NONBLOCK do not block at all (fetch/handle events but do not wait)
92		143
93	EV::unloop [$how]	144	EV::unloop [$how]
		145	$loop->unloop ([$how])
94	When called with no arguments or an argument of EV::UNLOOP_ONE,	146	When called with no arguments or an argument of EV::UNLOOP_ONE,
95	makes the innermost call to EV::loop return.	147	makes the innermost call to EV::loop return.
96		148
97	When called with an argument of EV::UNLOOP_ALL, all calls to	149	When called with an argument of EV::UNLOOP_ALL, all calls to
98	EV::loop will return as fast as possible.	150	EV::loop will return as fast as possible.
99		151
		152	$count = EV::loop_count
		153	$count = $loop->loop_count
		154	Return the number of times the event loop has polled for new events.
		155	Sometiems useful as a generation counter.
		156
100	EV::once $fh_or_undef, $events, $timeout, $cb->($revents)	157	EV::once $fh_or_undef, $events, $timeout, $cb->($revents)
		158	$loop->once ($fh_or_undef, $events, $timeout, $cb->($revents))
101	This function rolls together an I/O and a timer watcher for a single	159	This function rolls together an I/O and a timer watcher for a single
102	one-shot event without the need for managing a watcher object.	160	one-shot event without the need for managing a watcher object.
103		161
104	If $fh_or_undef is a filehandle or file descriptor, then $events	162	If $fh_or_undef is a filehandle or file descriptor, then $events
105	must be a bitset containing either "EV::READ", "EV::WRITE" or	163	must be a bitset containing either "EV::READ", "EV::WRITE" or
…		…
110	If timeout is "undef" or negative, then there will be no timeout.	168	If timeout is "undef" or negative, then there will be no timeout.
111	Otherwise a EV::timer with this value will be started.	169	Otherwise a EV::timer with this value will be started.
112		170
113	When an error occurs or either the timeout or I/O watcher triggers,	171	When an error occurs or either the timeout or I/O watcher triggers,
114	then the callback will be called with the received event set (in	172	then the callback will be called with the received event set (in
115	general you can expect it to be a combination of "EV:ERROR",	173	general you can expect it to be a combination of "EV::ERROR",
116	"EV::READ", "EV::WRITE" and "EV::TIMEOUT").	174	"EV::READ", "EV::WRITE" and "EV::TIMEOUT").
117		175
118	EV::once doesn't return anything: the watchers stay active till	176	EV::once doesn't return anything: the watchers stay active till
119	either of them triggers, then they will be stopped and freed, and	177	either of them triggers, then they will be stopped and freed, and
120	the callback invoked.	178	the callback invoked.
121		179
		180	EV::feed_fd_event ($fd, $revents)
		181	$loop->feed_fd_event ($fd, $revents)
		182	Feed an event on a file descriptor into EV. EV will react to this
		183	call as if the readyness notifications specified by $revents (a
		184	combination of "EV::READ" and "EV::WRITE") happened on the file
		185	descriptor $fd.
		186
		187	EV::feed_signal_event ($signal)
		188	Feed a signal event into EV. EV will react to this call as if the
		189	signal specified by $signal had occured.
		190
		191	EV::set_io_collect_interval $time
		192	$loop->set_io_collect_interval ($time)
		193	EV::set_timeout_collect_interval $time
		194	$loop->set_timeout_collect_interval ($time)
		195	These advanced functions set the minimum block interval when polling
		196	for I/O events and the minimum wait interval for timer events. See
		197	the libev documentation at
		198	<http://pod.tst.eu/http://cvs.schmorp.de/libev/ev.pod#FUNCTIONS_CONT
		199	ROLLING_THE_EVENT_LOOP> for a more detailed discussion.
		200
122	WATCHER OBJECTS	201	WATCHER OBJECTS
123	A watcher is an object that gets created to record your interest in some	202	A watcher is an object that gets created to record your interest in some
124	event. For instance, if you want to wait for STDIN to become readable,	203	event. For instance, if you want to wait for STDIN to become readable,
125	you would create an EV::io watcher for that:	204	you would create an EV::io watcher for that:
126		205
127	my $watcher = EV::io *STDIN, EV::READ, sub {	206	my $watcher = EV::io *STDIN, EV::READ, sub {
128	my ($watcher, $revents) = @_;	207	my ($watcher, $revents) = @_;
129	warn "yeah, STDIN should not be readable without blocking!\n"	208	warn "yeah, STDIN should now be readable without blocking!\n"
130	};	209	};
131		210
132	All watchers can be active (waiting for events) or inactive (paused).	211	All watchers can be active (waiting for events) or inactive (paused).
133	Only active watchers will have their callbacks invoked. All callbacks	212	Only active watchers will have their callbacks invoked. All callbacks
134	will be called with at least two arguments: the watcher and a bitmask of	213	will be called with at least two arguments: the watcher and a bitmask of
135	received events.	214	received events.
136		215
137	Each watcher type has its associated bit in revents, so you can use the	216	Each watcher type has its associated bit in revents, so you can use the
138	same callback for multiple watchers. The event mask is named after the	217	same callback for multiple watchers. The event mask is named after the
139	type, i..e. EV::child sets EV::CHILD, EV::prepare sets EV::PREPARE,	218	type, i..e. EV::child sets EV::CHILD, EV::prepare sets EV::PREPARE,
140	EV::periodic sets EV::PERIODIC and so on, with the exception of IO	219	EV::periodic sets EV::PERIODIC and so on, with the exception of I/O
141	events (which can set both EV::READ and EV::WRITE bits), and EV::timer	220	events (which can set both EV::READ and EV::WRITE bits), and EV::timer
142	(which uses EV::TIMEOUT).	221	(which uses EV::TIMEOUT).
143		222
144	In the rare case where one wants to create a watcher but not start it at	223	In the rare case where one wants to create a watcher but not start it at
145	the same time, each constructor has a variant with a trailing "_ns" in	224	the same time, each constructor has a variant with a trailing "_ns" in
…		…
163	stopped watchers).	242	stopped watchers).
164		243
165	$w->stop	244	$w->stop
166	Stop a watcher if it is active. Also clear any pending events	245	Stop a watcher if it is active. Also clear any pending events
167	(events that have been received but that didn't yet result in a	246	(events that have been received but that didn't yet result in a
168	callback invocation), regardless of wether the watcher was active or	247	callback invocation), regardless of whether the watcher was active
169	not.	248	or not.
170		249
171	$bool = $w->is_active	250	$bool = $w->is_active
172	Returns true if the watcher is active, false otherwise.	251	Returns true if the watcher is active, false otherwise.
173		252
174	$current_data = $w->data	253	$current_data = $w->data
…		…
197	The default priority of any newly-created watcher is 0.	276	The default priority of any newly-created watcher is 0.
198		277
199	Note that the priority semantics have not yet been fleshed out and	278	Note that the priority semantics have not yet been fleshed out and
200	are subject to almost certain change.	279	are subject to almost certain change.
201		280
202	$w->trigger ($revents)	281	$w->invoke ($revents)
203	Call the callback now with the given event mask.	282	Call the callback now with the given event mask.
		283
		284	$w->feed_event ($revents)
		285	Feed some events on this watcher into EV. EV will react to this call
		286	as if the watcher had received the given $revents mask.
		287
		288	$revents = $w->clear_pending
		289	If the watcher is pending, this function clears its pending status
		290	and returns its $revents bitset (as if its callback was invoked). If
		291	the watcher isn't pending it does nothing and returns 0.
204		292
205	$previous_state = $w->keepalive ($bool)	293	$previous_state = $w->keepalive ($bool)
206	Normally, "EV::loop" will return when there are no active watchers	294	Normally, "EV::loop" will return when there are no active watchers
207	(which is a "deadlock" because no progress can be made anymore).	295	(which is a "deadlock" because no progress can be made anymore).
208	This is convinient because it allows you to start your watchers (and	296	This is convinient because it allows you to start your watchers (and
209	your jobs), call "EV::loop" once and when it returns you know that	297	your jobs), call "EV::loop" once and when it returns you know that
210	all your jobs are finished (or they forgot to register some watchers	298	all your jobs are finished (or they forgot to register some watchers
211	for their task :).	299	for their task :).
212		300
213	Sometimes, however, this gets in your way, for example when you the	301	Sometimes, however, this gets in your way, for example when the
214	module that calls "EV::loop" (usually the main program) is not the	302	module that calls "EV::loop" (usually the main program) is not the
215	same module as a long-living watcher (for example a DNS client	303	same module as a long-living watcher (for example a DNS client
216	module written by somebody else even). Then you might want any	304	module written by somebody else even). Then you might want any
217	outstanding requests to be handled, but you would not want to keep	305	outstanding requests to be handled, but you would not want to keep
218	"EV::loop" from returning just because you happen to have this	306	"EV::loop" from returning just because you happen to have this
…		…
223	returning.	311	returning.
224		312
225	The initial value for keepalive is true (enabled), and you cna	313	The initial value for keepalive is true (enabled), and you cna
226	change it any time.	314	change it any time.
227		315
228	Example: Register an IO watcher for some UDP socket but do not keep	316	Example: Register an I/O watcher for some UDP socket but do not keep
229	the event loop from running just because of that watcher.	317	the event loop from running just because of that watcher.
230		318
231	my $udp_socket = ...	319	my $udp_socket = ...
232	my $udp_watcher = EV::io $udp_socket, EV::READ, sub { ... };	320	my $udp_watcher = EV::io $udp_socket, EV::READ, sub { ... };
233	$udp_watcher->keepalive (0);	321	$1000udp_watcher->keepalive (0);
234		322
		323	$loop = $w->loop
		324	Return the loop that this watcher is attached to.
		325
235	WATCHER TYPES	326	WATCHER TYPES
236	Each of the following subsections describes a single watcher type.	327	Each of the following subsections describes a single watcher type.
237		328
238	IO WATCHERS - is this file descriptor readable or writable?	329	I/O WATCHERS - is this file descriptor readable or writable?
239	$w = EV::io $fileno_or_fh, $eventmask, $callback	330	$w = EV::io $fileno_or_fh, $eventmask, $callback
240	$w = EV::io_ns $fileno_or_fh, $eventmask, $callback	331	$w = EV::io_ns $fileno_or_fh, $eventmask, $callback
		332	$w = $loop->io ($fileno_or_fh, $eventmask, $callback)
		333	$w = $loop->io_ns ($fileno_or_fh, $eventmask, $callback)
241	As long as the returned watcher object is alive, call the $callback	334	As long as the returned watcher object is alive, call the $callback
242	when at least one of events specified in $eventmask occurs.	335	when at least one of events specified in $eventmask occurs.
243		336
244	The $eventmask can be one or more of these constants ORed together:	337	The $eventmask can be one or more of these constants ORed together:
245		338
…		…
262	Returns the previously set event mask and optionally set a new one.	355	Returns the previously set event mask and optionally set a new one.
263		356
264	TIMER WATCHERS - relative and optionally repeating timeouts	357	TIMER WATCHERS - relative and optionally repeating timeouts
265	$w = EV::timer $after, $repeat, $callback	358	$w = EV::timer $after, $repeat, $callback
266	$w = EV::timer_ns $after, $repeat, $callback	359	$w = EV::timer_ns $after, $repeat, $callback
		360	$w = $loop->timer ($after, $repeat, $callback)
		361	$w = $loop->timer_ns ($after, $repeat, $callback)
267	Calls the callback after $after seconds (which may be fractional).	362	Calls the callback after $after seconds (which may be fractional).
268	If $repeat is non-zero, the timer will be restarted (with the	363	If $repeat is non-zero, the timer will be restarted (with the
269	$repeat value as $after) after the callback returns.	364	$repeat value as $after) after the callback returns.
270		365
271	This means that the callback would be called roughly after $after	366	This means that the callback would be called roughly after $after
…		…
307	method on the timeout.	402	method on the timeout.
308		403
309	PERIODIC WATCHERS - to cron or not to cron?	404	PERIODIC WATCHERS - to cron or not to cron?
310	$w = EV::periodic $at, $interval, $reschedule_cb, $callback	405	$w = EV::periodic $at, $interval, $reschedule_cb, $callback
311	$w = EV::periodic_ns $at, $interval, $reschedule_cb, $callback	406	$w = EV::periodic_ns $at, $interval, $reschedule_cb, $callback
		407	$w = $loop->periodic ($at, $interval, $reschedule_cb, $callback)
		408	$w = $loop->periodic_ns ($at, $interval, $reschedule_cb, $callback)
312	Similar to EV::timer, but is not based on relative timeouts but on	409	Similar to EV::timer, but is not based on relative timeouts but on
313	absolute times. Apart from creating "simple" timers that trigger	410	absolute times. Apart from creating "simple" timers that trigger
314	"at" the specified time, it can also be used for non-drifting	411	"at" the specified time, it can also be used for non-drifting
315	absolute timers and more complex, cron-like, setups that are not	412	absolute timers and more complex, cron-like, setups that are not
316	adversely affected by time jumps (i.e. when the system clock is	413	adversely affected by time jumps (i.e. when the system clock is
317	changed by explicit date -s or other means such as ntpd). It is also	414	changed by explicit date -s or other means such as ntpd). It is also
318	the most complex watcher type in EV.	415	the most complex watcher type in EV.
319		416
320	It has three distinct "modes":	417	It has three distinct "modes":
321		418
322	* absolute timer ($interval = $reschedule_cb = 0)	419	* absolute timer ($interval = $reschedule_cb = 0)
		420
323	This time simply fires at the wallclock time $at and doesn't	421	This time simply fires at the wallclock time $at and doesn't
324	repeat. It will not adjust when a time jump occurs, that is, if	422	repeat. It will not adjust when a time jump occurs, that is, if
325	it is to be run at January 1st 2011 then it will run when the	423	it is to be run at January 1st 2011 then it will run when the
326	system time reaches or surpasses this time.	424	system time reaches or surpasses this time.
327		425
328	* non-repeating interval timer ($interval > 0, $reschedule_cb = 0)	426	* repeating interval timer ($interval > 0, $reschedule_cb = 0)
		427
329	In this mode the watcher will always be scheduled to time out at	428	In this mode the watcher will always be scheduled to time out at
330	the next "$at + N * $interval" time (for some integer N) and	429	the next "$at + N * $interval" time (for some integer N) and
331	then repeat, regardless of any time jumps.	430	then repeat, regardless of any time jumps.
332		431
333	This can be used to create timers that do not drift with respect	432	This can be used to create timers that do not drift with respect
…		…
342	Another way to think about it (for the mathematically inclined)	441	Another way to think about it (for the mathematically inclined)
343	is that EV::periodic will try to run the callback in this mode	442	is that EV::periodic will try to run the callback in this mode
344	at the next possible time where "$time = $at (mod $interval)",	443	at the next possible time where "$time = $at (mod $interval)",
345	regardless of any time jumps.	444	regardless of any time jumps.
346		445
347	* manual reschedule mode ($reschedule_cb = coderef)	446	* manual reschedule mode ($reschedule_cb = coderef)
		447
348	In this mode $interval and $at are both being ignored. Instead,	448	In this mode $interval and $at are both being ignored. Instead,
349	each time the periodic watcher gets scheduled, the reschedule	449	each time the periodic watcher gets scheduled, the reschedule
350	callback ($reschedule_cb) will be called with the watcher as	450	callback ($reschedule_cb) will be called with the watcher as
351	first, and the current time as second argument.	451	first, and the current time as second argument.
352		452
…		…
384	be called at any time.	484	be called at any time.
385		485
386	$w->again	486	$w->again
387	Simply stops and starts the watcher again.	487	Simply stops and starts the watcher again.
388		488
		489	$time = $w->at
		490	Return the time that the watcher is expected to trigger next.
		491
389	SIGNAL WATCHERS - signal me when a signal gets signalled!	492	SIGNAL WATCHERS - signal me when a signal gets signalled!
390	$w = EV::signal $signal, $callback	493	$w = EV::signal $signal, $callback
391	$w = EV::signal_ns $signal, $callback	494	$w = EV::signal_ns $signal, $callback
392	Call the callback when $signal is received (the signal can be	495	Call the callback when $signal is received (the signal can be
393	specified by number or by name, just as with "kill" or %SIG).	496	specified by number or by name, just as with "kill" or %SIG).
…		…
410	$old_signum = $w->signal ($new_signal)	513	$old_signum = $w->signal ($new_signal)
411	Returns the previously set signal (always as a number not name) and	514	Returns the previously set signal (always as a number not name) and
412	optionally set a new one.	515	optionally set a new one.
413		516
414	CHILD WATCHERS - watch out for process status changes	517	CHILD WATCHERS - watch out for process status changes
415	$w = EV::child $pid, $callback	518	$w = EV::child $pid, $trace, $callback
416	$w = EV::child_ns $pid, $callback	519	$w = EV::child_ns $pid, $trace, $callback
		520	$w = $loop->child ($pid, $trace, $callback)
		521	$w = $loop->child_ns ($pid, $trace, $callback)
417	Call the callback when a status change for pid $pid (or any pid if	522	Call the callback when a status change for pid $pid (or any pid if
418	$pid is 0) has been received. More precisely: when the process	523	$pid is 0) has been received (a status change happens when the
		524	process terminates or is killed, or, when trace is true,
		525	additionally when it is stopped or continued). More precisely: when
419	receives a "SIGCHLD", EV will fetch the outstanding exit/wait status	526	the process receives a "SIGCHLD", EV will fetch the outstanding
420	for all changed/zombie children and call the callback.	527	exit/wait status for all changed/zombie children and call the
		528	callback.
421		529
422	It is valid (and fully supported) to install a child watcher after a	530	It is valid (and fully supported) to install a child watcher after a
423	child has exited but before the event loop has started its next	531	child has exited but before the event loop has started its next
424	iteration (for example, first you "fork", then the new child process	532	iteration (for example, first you "fork", then the new child process
425	might exit, and only then do you install a child watcher in the	533	might exit, and only then do you install a child watcher in the
…		…
432	be called.	540	be called.
433		541
434	The "child_ns" variant doesn't start (activate) the newly created	542	The "child_ns" variant doesn't start (activate) the newly created
435	watcher.	543	watcher.
436		544
437	$w->set ($pid)	545	$w->set ($pid, $trace)
438	Reconfigures the watcher, see the constructor above for details. Can	546	Reconfigures the watcher, see the constructor above for details. Can
439	be called at any time.	547	be called at any time.
440		548
441	$current_pid = $w->pid	549	$current_pid = $w->pid
442	$old_pid = $w->pid ($new_pid)
443	Returns the previously set process id and optionally set a new one.	550	Returns the previously set process id and optionally set a new one.
444		551
445	$exit_status = $w->rstatus	552	$exit_status = $w->rstatus
446	Return the exit/wait status (as returned by waitpid, see the waitpid	553	Return the exit/wait status (as returned by waitpid, see the waitpid
447	entry in perlfunc).	554	entry in perlfunc).
…		…
451	a watcher for all pids).	558	a watcher for all pids).
452		559
453	STAT WATCHERS - did the file attributes just change?	560	STAT WATCHERS - did the file attributes just change?
454	$w = EV::stat $path, $interval, $callback	561	$w = EV::stat $path, $interval, $callback
455	$w = EV::stat_ns $path, $interval, $callback	562	$w = EV::stat_ns $path, $interval, $callback
		563	$w = $loop->stat ($path, $interval, $callback)
		564	$w = $loop->stat_ns ($path, $interval, $callback)
456	Call the callback when a file status change has been detected on	565	Call the callback when a file status change has been detected on
457	$path. The $path does not need to exist, changing from "path exists"	566	$path. The $path does not need to exist, changing from "path exists"
458	to "path does not exist" is a status change like any other.	567	to "path does not exist" is a status change like any other.
459		568
460	The $interval is a recommended polling interval for systems where	569	The $interval is a recommended polling interval for systems where
…		…
520	Can be used to query the actual interval used.	629	Can be used to query the actual interval used.
521		630
522	IDLE WATCHERS - when you've got nothing better to do...	631	IDLE WATCHERS - when you've got nothing better to do...
523	$w = EV::idle $callback	632	$w = EV::idle $callback
524	$w = EV::idle_ns $callback	633	$w = EV::idle_ns $callback
		634	$w = $loop->idle ($callback)
		635	$w = $loop->idle_ns ($callback)
525	Call the callback when there are no pending io, timer/periodic,	636	Call the callback when there are no other pending watchers of the
526	signal or child events, i.e. when the process is idle.	637	same or higher priority (excluding check, prepare and other idle
		638	watchers of the same or lower priority, of course). They are called
		639	idle watchers because when the watcher is the highest priority
		640	pending event in the process, the process is considered to be idle
		641	at that priority.
		642
		643	If you want a watcher that is only ever called when no other
		644	events are outstanding you have to set the priority to "EV::MINPRI".
527		645
528	The process will not block as long as any idle watchers are active,	646	The process will not block as long as any idle watchers are active,
529	and they will be called repeatedly until stopped.	647	and they will be called repeatedly until stopped.
		648
		649	For example, if you have idle watchers at priority 0 and 1, and an
		650	I/O watcher at priority 0, then the idle watcher at priority 1 and
		651	the I/O watcher will always run when ready. Only when the idle
		652	watcher at priority 1 is stopped and the I/O watcher at priority 0
		653	is not pending with the 0-priority idle watcher be invoked.
530		654
531	The "idle_ns" variant doesn't start (activate) the newly created	655	The "idle_ns" variant doesn't start (activate) the newly created
532	watcher.	656	watcher.
533		657
534	PREPARE WATCHERS - customise your event loop!	658	PREPARE WATCHERS - customise your event loop!
535	$w = EV::prepare $callback	659	$w = EV::prepare $callback
536	$w = EV::prepare_ns $callback	660	$w = EV::prepare_ns $callback
		661	$w = $loop->prepare ($callback)
		662	$w = $loop->prepare_ns ($callback)
537	Call the callback just before the process would block. You can still	663	Call the callback just before the process would block. You can still
538	create/modify any watchers at this point.	664	create/modify any watchers at this point.
539		665
540	See the EV::check watcher, below, for explanations and an example.	666	See the EV::check watcher, below, for explanations and an example.
541		667
…		…
543	watcher.	669	watcher.
544		670
545	CHECK WATCHERS - customise your event loop even more!	671	CHECK WATCHERS - customise your event loop even more!
546	$w = EV::check $callback	672	$w = EV::check $callback
547	$w = EV::check_ns $callback	673	$w = EV::check_ns $callback
		674	$w = $loop->check ($callback)
		675	$w = $loop->check_ns ($callback)
548	Call the callback just after the process wakes up again (after it	676	Call the callback just after the process wakes up again (after it
549	has gathered events), but before any other callbacks have been	677	has gathered events), but before any other callbacks have been
550	invoked.	678	invoked.
551		679
552	This is used to integrate other event-based software into the EV	680	This is used to integrate other event-based software into the EV
…		…
563	or return;	691	or return;
564		692
565	# make the dispatcher handle any outstanding stuff	693	# make the dispatcher handle any outstanding stuff
566	... not shown	694	... not shown
567		695
568	# create an IO watcher for each and every socket	696	# create an I/O watcher for each and every socket
569	@snmp_watcher = (	697	@snmp_watcher = (
570	(map { EV::io $_, EV::READ, sub { } }	698	(map { EV::io $_, EV::READ, sub { } }
571	keys %{ $dispatcher->{_descriptors} }),	699	keys %{ $dispatcher->{_descriptors} }),
572		700
573	EV::timer +($event->[Net::SNMP::Dispatcher::_ACTIVE]	701	EV::timer +($event->[Net::SNMP::Dispatcher::_ACTIVE]
…		…
601	is done before the event loop blocks next and before "check" watchers	729	is done before the event loop blocks next and before "check" watchers
602	are being called, and only in the child after the fork.	730	are being called, and only in the child after the fork.
603		731
604	$w = EV::fork $callback	732	$w = EV::fork $callback
605	$w = EV::fork_ns $callback	733	$w = EV::fork_ns $callback
		734	$w = $loop->fork ($callback)
		735	$w = $loop->fork_ns ($callback)
606	Call the callback before the event loop is resumed in the child	736	Call the callback before the event loop is resumed in the child
607	process after a fork.	737	process after a fork.
608		738
609	The "fork_ns" variant doesn't start (activate) the newly created	739	The "fork_ns" variant doesn't start (activate) the newly created
610	watcher.	740	watcher.
		741
		742	EMBED WATCHERS - when one backend isn't enough...
		743	This is a rather advanced watcher type that lets you embed one event
		744	loop into another (currently only IO events are supported in the
		745	embedded loop, other types of watchers might be handled in a delayed or
		746	incorrect fashion and must not be used).
		747
		748	See the libev documentation at
		749	<http://pod.tst.eu/http://cvs.schmorp.de/libev/ev.pod#code_ev_embed_code
		750	_when_one_backend_> for more details.
		751
		752	In short, this watcher is most useful on BSD systems without working
		753	kqueue to still be able to handle a large number of sockets:
		754
		755	my $socket_loop;
		756
		757	# check wether we use SELECT or POLL _and_ KQUEUE is supported
		758	if (
		759	(EV::backend & (EV::BACKEND_POLL \| EV::BACKEND_SELECT))
		760	&& (EV::supported_backends & EV::embeddable_backends & EV::BACKEND_KQUEUE)
		761	) {
		762	# use kqueue for sockets
		763	$socket_loop = new EV::Loop EV::BACKEND_KQUEUE \| EV::FLAG_NOENV;
		764	}
		765
		766	# use the default loop otherwise
		767	$socket_loop \|\|= EV::default_loop;
		768
		769	$w = EV::embed $otherloop, $callback
		770	$w = EV::embed_ns $otherloop, $callback
		771	$w = $loop->embed ($otherloop, $callback)
		772	$w = $loop->embed_ns ($otherloop, $callback)
		773	Call the callback when the embedded event loop ($otherloop) has any
		774	I/O activity. The $callback should alwas be specified as "undef" in
		775	this version of EV, which means the embedded event loop will be
		776	managed automatically.
		777
		778	The "embed_ns" variant doesn't start (activate) the newly created
		779	watcher.
		780
		781	ASYNC WATCHERS - how to wake up another event loop
		782	Async watchers are provided by EV, but have little use in perl directly,
		783	as perl neither supports threads nor direct access to signal handlers or
		784	other contexts where they could be of value.
		785
		786	It is, however, possible to use them from the XS level.
		787
		788	Please see the libev documentation for further details.
		789
		790	$w = EV::async $callback
		791	$w = EV::async_ns $callback
		792	$w->send
		793	$bool = $w->async_pending
		794
		795	PERL SIGNALS
		796	While Perl signal handling (%SIG) is not affected by EV, the behaviour
		797	with EV is as the same as any other C library: Perl-signals will only be
		798	handled when Perl runs, which means your signal handler might be invoked
		799	only the next time an event callback is invoked.
		800
		801	The solution is to use EV signal watchers (see "EV::signal"), which will
		802	ensure proper operations with regards to other event watchers.
		803
		804	If you cannot do this for whatever reason, you can also force a watcher
		805	to be called on every event loop iteration by installing a "EV::check"
		806	watcher:
		807
		808	my $async_check = EV::check sub { };
		809
		810	This ensures that perl gets into control for a short time to handle any
		811	pending signals, and also ensures (slightly) slower overall operation.
611		812
612	THREADS	813	THREADS
613	Threads are not supported by this module in any way. Perl pseudo-threads	814	Threads are not supported by this module in any way. Perl pseudo-threads
614	is evil stuff and must die. As soon as Perl gains real threads I will	815	is evil stuff and must die. As soon as Perl gains real threads I will
615	work on thread support for it.	816	work on thread support for it.
…		…
630		831
631	On win32, there is no notion of fork so all this doesn't apply, of	832	On win32, there is no notion of fork so all this doesn't apply, of
632	course.	833	course.
633		834
634	SEE ALSO	835	SEE ALSO
635	EV::DNS.	836	EV::ADNS (asynchronous DNS), Glib::EV (makes Glib/Gtk2 use EV as event
		837	loop), EV::Glib (embed Glib into EV), Coro::EV (efficient coroutines
		838	with EV), Net::SNMP::EV (asynchronous SNMP).
636		839
637	AUTHOR	840	AUTHOR
638	Marc Lehmann <schmorp@schmorp.de>	841	Marc Lehmann <schmorp@schmorp.de>
639	http://home.schmorp.de/	842	http://home.schmorp.de/
640		843

Diff Legend

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

Comparing EV/README (file contents): Revision 1.14 by root, Wed Nov 28 19:22:16 2007 UTC vs. Revision 1.24 by root, Wed Apr 16 17:08:29 2008 UTC

Diff Legend

Comparing EV/README (file contents):
Revision 1.14 by root, Wed Nov 28 19:22:16 2007 UTC vs.
Revision 1.24 by root, Wed Apr 16 17:08:29 2008 UTC