[ViewVC] Diff of: cvs/EV/README

Comparing EV/README (file contents):
Revision 1.17 by root, Sat Dec 8 14:44:21 2007 UTC vs.
Revision 1.26 by root, Wed May 21 23:40:08 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://pod.tst.eu/http://cvs.schmorp.de/libev/ev.pod>)
60	details on watcher semantics or some discussion on the available	60	for more subtle details on watcher semantics or some discussion on the
61	backends, or how to force a specific backend with "LIBEV_FLAGS", or just	61	available backends, or how to force a specific backend with
62	about in any case because it has much more detailed information.	62	"LIBEV_FLAGS", or just about in any case because it has much more
		63	detailed information.
		64
		65	This module is very fast and scalable. It is actually so fast that you
		66	can use it through the AnyEvent module, stay portable to other event
		67	loops (if you don't rely on any watcher types not available through it)
		68	and still be faster than with any other event loop currently supported
		69	in Perl.
		70
		71	EVENT LOOPS
		72	EV supports multiple event loops: There is a single "default event loop"
		73	that can handle everything including signals and child watchers, and any
		74	number of "dynamic event loops" that can use different backends (with
		75	various limitations), but no child and signal watchers.
		76
		77	You do not have to do anything to create the default event loop: When
		78	the module is loaded a suitable backend is selected on the premise of
		79	selecting a working backend (which for example rules out kqueue on most
		80	BSDs). Modules should, unless they have "special needs" always use the
		81	default loop as this is fastest (perl-wise), best supported by other
		82	modules (e.g. AnyEvent or Coro) and most portable event loop.
		83
		84	For specific programs you can create additional event loops dynamically.
		85
		86	$loop = new EV::loop [$flags]
		87	Create a new event loop as per the specified flags. Please refer to
		88	the "ev_loop_new ()" function description in the libev documentation
		89	(<http://pod.tst.eu/http://cvs.schmorp.de/libev/ev.pod#GLOBAL_FUNCTI
		90	ONS>) for more info.
		91
		92	The loop will automatically be destroyed when it is no longer
		93	referenced by any watcher and the loop object goes out of scope.
		94
		95	Using "EV::FLAG_FORKCHECK" is recommended, as only the default event
		96	loop is protected by this module.
		97
		98	$loop->loop_fork
		99	Must be called after a fork in the child, before entering or
		100	continuing the event loop. An alternative is to use
		101	"EV::FLAG_FORKCHECK" which calls this fucntion automatically, at
		102	some performance loss (refer to the libev documentation).
		103
		104	$loop = EV::default_loop [$flags]
		105	Return the default loop (which is a singleton object).
63		106
64	BASIC INTERFACE	107	BASIC INTERFACE
65	$EV::DIED	108	$EV::DIED
66	Must contain a reference to a function that is called when a	109	Must contain a reference to a function that is called when a
67	callback throws an exception (with $@ containing thr error). The	110	callback throws an exception (with $@ containing the error). The
68	default prints an informative message and continues.	111	default prints an informative message and continues.
69		112
70	If this callback throws an exception it will be silently ignored.	113	If this callback throws an exception it will be silently ignored.
		114
		115	$flags = EV::supported_backends
		116	$flags = EV::recommended_backends
		117	$flags = EV::embeddable_backends
		118	Returns the set (see "EV::BACKEND_*" flags) of backends supported by
		119	this instance of EV, the set of recommended backends (supposed to be
		120	good) for this platform and the set of embeddable backends (see
		121	EMBED WATCHERS).
		122
		123	EV::sleep $seconds
		124	Block the process for the given number of (fractional) seconds.
71		125
72	$time = EV::time	126	$time = EV::time
73	Returns the current time in (fractional) seconds since the epoch.	127	Returns the current time in (fractional) seconds since the epoch.
74		128
75	$time = EV::now	129	$time = EV::now
		130	$time = $loop->now
76	Returns the time the last event loop iteration has been started.	131	Returns the time the last event loop iteration has been started.
77	This is the time that (relative) timers are based on, and refering	132	This is the time that (relative) timers are based on, and refering
78	to it is usually faster then calling EV::time.	133	to it is usually faster then calling EV::time.
79		134
80	$method = EV::method	135	$backend = EV::backend
		136	$backend = $loop->backend
81	Returns an integer describing the backend used by libev	137	Returns an integer describing the backend used by libev
82	(EV::METHOD_SELECT or EV::METHOD_EPOLL).	138	(EV::METHOD_SELECT or EV::METHOD_EPOLL).
83		139
84	EV::loop [$flags]	140	EV::loop [$flags]
		141	$loop->loop ([$flags])
85	Begin checking for events and calling callbacks. It returns when a	142	Begin checking for events and calling callbacks. It returns when a
86	callback calls EV::unloop.	143	callback calls EV::unloop.
87		144
88	The $flags argument can be one of the following:	145	The $flags argument can be one of the following:
89		146
90	0 as above	147	0 as above
91	EV::LOOP_ONESHOT block at most once (wait, but do not loop)	148	EV::LOOP_ONESHOT block at most once (wait, but do not loop)
92	EV::LOOP_NONBLOCK do not block at all (fetch/handle events but do not wait)	149	EV::LOOP_NONBLOCK do not block at all (fetch/handle events but do not wait)
93		150
94	EV::unloop [$how]	151	EV::unloop [$how]
		152	$loop->unloop ([$how])
95	When called with no arguments or an argument of EV::UNLOOP_ONE,	153	When called with no arguments or an argument of EV::UNLOOP_ONE,
96	makes the innermost call to EV::loop return.	154	makes the innermost call to EV::loop return.
97		155
98	When called with an argument of EV::UNLOOP_ALL, all calls to	156	When called with an argument of EV::UNLOOP_ALL, all calls to
99	EV::loop will return as fast as possible.	157	EV::loop will return as fast as possible.
100		158
101	$count = EV::loop_count	159	$count = EV::loop_count
		160	$count = $loop->loop_count
102	Return the number of times the event loop has polled for new events.	161	Return the number of times the event loop has polled for new events.
103	Sometiems useful as a generation counter.	162	Sometiems useful as a generation counter.
104		163
105	EV::once $fh_or_undef, $events, $timeout, $cb->($revents)	164	EV::once $fh_or_undef, $events, $timeout, $cb->($revents)
		165	$loop->once ($fh_or_undef, $events, $timeout, $cb->($revents))
106	This function rolls together an I/O and a timer watcher for a single	166	This function rolls together an I/O and a timer watcher for a single
107	one-shot event without the need for managing a watcher object.	167	one-shot event without the need for managing a watcher object.
108		168
109	If $fh_or_undef is a filehandle or file descriptor, then $events	169	If $fh_or_undef is a filehandle or file descriptor, then $events
110	must be a bitset containing either "EV::READ", "EV::WRITE" or	170	must be a bitset containing either "EV::READ", "EV::WRITE" or
…		…
115	If timeout is "undef" or negative, then there will be no timeout.	175	If timeout is "undef" or negative, then there will be no timeout.
116	Otherwise a EV::timer with this value will be started.	176	Otherwise a EV::timer with this value will be started.
117		177
118	When an error occurs or either the timeout or I/O watcher triggers,	178	When an error occurs or either the timeout or I/O watcher triggers,
119	then the callback will be called with the received event set (in	179	then the callback will be called with the received event set (in
120	general you can expect it to be a combination of "EV:ERROR",	180	general you can expect it to be a combination of "EV::ERROR",
121	"EV::READ", "EV::WRITE" and "EV::TIMEOUT").	181	"EV::READ", "EV::WRITE" and "EV::TIMEOUT").
122		182
123	EV::once doesn't return anything: the watchers stay active till	183	EV::once doesn't return anything: the watchers stay active till
124	either of them triggers, then they will be stopped and freed, and	184	either of them triggers, then they will be stopped and freed, and
125	the callback invoked.	185	the callback invoked.
126		186
127	EV::feed_fd_event ($fd, $revents)	187	EV::feed_fd_event ($fd, $revents)
		188	$loop->feed_fd_event ($fd, $revents)
128	Feed an event on a file descriptor into EV. EV will react to this	189	Feed an event on a file descriptor into EV. EV will react to this
129	call as if the readyness notifications specified by $revents (a	190	call as if the readyness notifications specified by $revents (a
130	combination of "EV::READ" and "EV::WRITE") happened on the file	191	combination of "EV::READ" and "EV::WRITE") happened on the file
131	descriptor $fd.	192	descriptor $fd.
132		193
133	EV::feed_signal_event ($signal)	194	EV::feed_signal_event ($signal)
134	Feed a signal event into EV. EV will react to this call as if the	195	Feed a signal event into EV. EV will react to this call as if the
135	signal specified by $signal had occured.	196	signal specified by $signal had occured.
136		197
		198	EV::set_io_collect_interval $time
		199	$loop->set_io_collect_interval ($time)
		200	EV::set_timeout_collect_interval $time
		201	$loop->set_timeout_collect_interval ($time)
		202	These advanced functions set the minimum block interval when polling
		203	for I/O events and the minimum wait interval for timer events. See
		204	the libev documentation at
		205	<http://pod.tst.eu/http://cvs.schmorp.de/libev/ev.pod#FUNCTIONS_CONT
		206	ROLLING_THE_EVENT_LOOP> for a more detailed discussion.
		207
137	WATCHER OBJECTS	208	WATCHER OBJECTS
138	A watcher is an object that gets created to record your interest in some	209	A watcher is an object that gets created to record your interest in some
139	event. For instance, if you want to wait for STDIN to become readable,	210	event. For instance, if you want to wait for STDIN to become readable,
140	you would create an EV::io watcher for that:	211	you would create an EV::io watcher for that:
141		212
142	my $watcher = EV::io *STDIN, EV::READ, sub {	213	my $watcher = EV::io *STDIN, EV::READ, sub {
143	my ($watcher, $revents) = @_;	214	my ($watcher, $revents) = @_;
144	warn "yeah, STDIN should not be readable without blocking!\n"	215	warn "yeah, STDIN should now be readable without blocking!\n"
145	};	216	};
146		217
147	All watchers can be active (waiting for events) or inactive (paused).	218	All watchers can be active (waiting for events) or inactive (paused).
148	Only active watchers will have their callbacks invoked. All callbacks	219	Only active watchers will have their callbacks invoked. All callbacks
149	will be called with at least two arguments: the watcher and a bitmask of	220	will be called with at least two arguments: the watcher and a bitmask of
…		…
220	$w->feed_event ($revents)	291	$w->feed_event ($revents)
221	Feed some events on this watcher into EV. EV will react to this call	292	Feed some events on this watcher into EV. EV will react to this call
222	as if the watcher had received the given $revents mask.	293	as if the watcher had received the given $revents mask.
223		294
224	$revents = $w->clear_pending	295	$revents = $w->clear_pending
225	If the watcher is pending, this function returns clears its pending	296	If the watcher is pending, this function clears its pending status
226	status and returns its $revents bitset (as if its callback was	297	and returns its $revents bitset (as if its callback was invoked). If
227	invoked). If the watcher isn't pending it does nothing and returns	298	the watcher isn't pending it does nothing and returns 0.
228	0.
229		299
230	$previous_state = $w->keepalive ($bool)	300	$previous_state = $w->keepalive ($bool)
231	Normally, "EV::loop" will return when there are no active watchers	301	Normally, "EV::loop" will return when there are no active watchers
232	(which is a "deadlock" because no progress can be made anymore).	302	(which is a "deadlock" because no progress can be made anymore).
233	This is convinient because it allows you to start your watchers (and	303	This is convinient because it allows you to start your watchers (and
234	your jobs), call "EV::loop" once and when it returns you know that	304	your jobs), call "EV::loop" once and when it returns you know that
235	all your jobs are finished (or they forgot to register some watchers	305	all your jobs are finished (or they forgot to register some watchers
236	for their task :).	306	for their task :).
237		307
238	Sometimes, however, this gets in your way, for example when you the	308	Sometimes, however, this gets in your way, for example when the
239	module that calls "EV::loop" (usually the main program) is not the	309	module that calls "EV::loop" (usually the main program) is not the
240	same module as a long-living watcher (for example a DNS client	310	same module as a long-living watcher (for example a DNS client
241	module written by somebody else even). Then you might want any	311	module written by somebody else even). Then you might want any
242	outstanding requests to be handled, but you would not want to keep	312	outstanding requests to be handled, but you would not want to keep
243	"EV::loop" from returning just because you happen to have this	313	"EV::loop" from returning just because you happen to have this
…		…
253	Example: Register an I/O watcher for some UDP socket but do not keep	323	Example: Register an I/O watcher for some UDP socket but do not keep
254	the event loop from running just because of that watcher.	324	the event loop from running just because of that watcher.
255		325
256	my $udp_socket = ...	326	my $udp_socket = ...
257	my $udp_watcher = EV::io $udp_socket, EV::READ, sub { ... };	327	my $udp_watcher = EV::io $udp_socket, EV::READ, sub { ... };
258	$udp_watcher->keepalive (0);	328	$1000udp_watcher->keepalive (0);
259		329
		330	$loop = $w->loop
		331	Return the loop that this watcher is attached to.
		332
260	WATCHER TYPES	333	WATCHER TYPES
261	Each of the following subsections describes a single watcher type.	334	Each of the following subsections describes a single watcher type.
262		335
263	I/O WATCHERS - is this file descriptor readable or writable?	336	I/O WATCHERS - is this file descriptor readable or writable?
264	$w = EV::io $fileno_or_fh, $eventmask, $callback	337	$w = EV::io $fileno_or_fh, $eventmask, $callback
265	$w = EV::io_ns $fileno_or_fh, $eventmask, $callback	338	$w = EV::io_ns $fileno_or_fh, $eventmask, $callback
		339	$w = $loop->io ($fileno_or_fh, $eventmask, $callback)
		340	$w = $loop->io_ns ($fileno_or_fh, $eventmask, $callback)
266	As long as the returned watcher object is alive, call the $callback	341	As long as the returned watcher object is alive, call the $callback
267	when at least one of events specified in $eventmask occurs.	342	when at least one of events specified in $eventmask occurs.
268		343
269	The $eventmask can be one or more of these constants ORed together:	344	The $eventmask can be one or more of these constants ORed together:
270		345
…		…
287	Returns the previously set event mask and optionally set a new one.	362	Returns the previously set event mask and optionally set a new one.
288		363
289	TIMER WATCHERS - relative and optionally repeating timeouts	364	TIMER WATCHERS - relative and optionally repeating timeouts
290	$w = EV::timer $after, $repeat, $callback	365	$w = EV::timer $after, $repeat, $callback
291	$w = EV::timer_ns $after, $repeat, $callback	366	$w = EV::timer_ns $after, $repeat, $callback
		367	$w = $loop->timer ($after, $repeat, $callback)
		368	$w = $loop->timer_ns ($after, $repeat, $callback)
292	Calls the callback after $after seconds (which may be fractional).	369	Calls the callback after $after seconds (which may be fractional).
293	If $repeat is non-zero, the timer will be restarted (with the	370	If $repeat is non-zero, the timer will be restarted (with the
294	$repeat value as $after) after the callback returns.	371	$repeat value as $after) after the callback returns.
295		372
296	This means that the callback would be called roughly after $after	373	This means that the callback would be called roughly after $after
…		…
332	method on the timeout.	409	method on the timeout.
333		410
334	PERIODIC WATCHERS - to cron or not to cron?	411	PERIODIC WATCHERS - to cron or not to cron?
335	$w = EV::periodic $at, $interval, $reschedule_cb, $callback	412	$w = EV::periodic $at, $interval, $reschedule_cb, $callback
336	$w = EV::periodic_ns $at, $interval, $reschedule_cb, $callback	413	$w = EV::periodic_ns $at, $interval, $reschedule_cb, $callback
		414	$w = $loop->periodic ($at, $interval, $reschedule_cb, $callback)
		415	$w = $loop->periodic_ns ($at, $interval, $reschedule_cb, $callback)
337	Similar to EV::timer, but is not based on relative timeouts but on	416	Similar to EV::timer, but is not based on relative timeouts but on
338	absolute times. Apart from creating "simple" timers that trigger	417	absolute times. Apart from creating "simple" timers that trigger
339	"at" the specified time, it can also be used for non-drifting	418	"at" the specified time, it can also be used for non-drifting
340	absolute timers and more complex, cron-like, setups that are not	419	absolute timers and more complex, cron-like, setups that are not
341	adversely affected by time jumps (i.e. when the system clock is	420	adversely affected by time jumps (i.e. when the system clock is
342	changed by explicit date -s or other means such as ntpd). It is also	421	changed by explicit date -s or other means such as ntpd). It is also
343	the most complex watcher type in EV.	422	the most complex watcher type in EV.
344		423
345	It has three distinct "modes":	424	It has three distinct "modes":
346		425
347	* absolute timer ($interval = $reschedule_cb = 0)	426	* absolute timer ($interval = $reschedule_cb = 0)
		427
348	This time simply fires at the wallclock time $at and doesn't	428	This time simply fires at the wallclock time $at and doesn't
349	repeat. It will not adjust when a time jump occurs, that is, if	429	repeat. It will not adjust when a time jump occurs, that is, if
350	it is to be run at January 1st 2011 then it will run when the	430	it is to be run at January 1st 2011 then it will run when the
351	system time reaches or surpasses this time.	431	system time reaches or surpasses this time.
352		432
353	* non-repeating interval timer ($interval > 0, $reschedule_cb = 0)	433	* repeating interval timer ($interval > 0, $reschedule_cb = 0)
		434
354	In this mode the watcher will always be scheduled to time out at	435	In this mode the watcher will always be scheduled to time out at
355	the next "$at + N * $interval" time (for some integer N) and	436	the next "$at + N * $interval" time (for some integer N) and
356	then repeat, regardless of any time jumps.	437	then repeat, regardless of any time jumps.
357		438
358	This can be used to create timers that do not drift with respect	439	This can be used to create timers that do not drift with respect
…		…
367	Another way to think about it (for the mathematically inclined)	448	Another way to think about it (for the mathematically inclined)
368	is that EV::periodic will try to run the callback in this mode	449	is that EV::periodic will try to run the callback in this mode
369	at the next possible time where "$time = $at (mod $interval)",	450	at the next possible time where "$time = $at (mod $interval)",
370	regardless of any time jumps.	451	regardless of any time jumps.
371		452
372	* manual reschedule mode ($reschedule_cb = coderef)	453	* manual reschedule mode ($reschedule_cb = coderef)
		454
373	In this mode $interval and $at are both being ignored. Instead,	455	In this mode $interval and $at are both being ignored. Instead,
374	each time the periodic watcher gets scheduled, the reschedule	456	each time the periodic watcher gets scheduled, the reschedule
375	callback ($reschedule_cb) will be called with the watcher as	457	callback ($reschedule_cb) will be called with the watcher as
376	first, and the current time as second argument.	458	first, and the current time as second argument.
377		459
378	*This callback MUST NOT stop or destroy this or any other	460	*This callback MUST NOT stop or destroy this or any other
		461	periodic watcher, ever, and MUST NOT call any event loop
379	periodic watcher, ever*. If you need to stop it, return 1e30 and	462	functions or methods*. If you need to stop it, return 1e30 and
380	stop it afterwards.	463	stop it afterwards. You may create and start a "EV::prepare"
		464	watcher for this task.
381		465
382	It must return the next time to trigger, based on the passed	466	It must return the next time to trigger, based on the passed
383	time value (that is, the lowest time value larger than to the	467	time value (that is, the lowest time value larger than or equal
384	second argument). It will usually be called just before the	468	to to the second argument). It will usually be called just
385	callback will be triggered, but might be called at other times,	469	before the callback will be triggered, but might be called at
386	too.	470	other times, too.
387		471
388	This can be used to create very complex timers, such as a timer	472	This can be used to create very complex timers, such as a timer
389	that triggers on each midnight, local time (actually 24 hours	473	that triggers on each midnight, local time (actually 24 hours
390	after the last midnight, to keep the example simple. If you know	474	after the last midnight, to keep the example simple. If you know
391	a way to do it correctly in about the same space (without	475	a way to do it correctly in about the same space (without
…		…
409	be called at any time.	493	be called at any time.
410		494
411	$w->again	495	$w->again
412	Simply stops and starts the watcher again.	496	Simply stops and starts the watcher again.
413		497
		498	$time = $w->at
		499	Return the time that the watcher is expected to trigger next.
		500
414	SIGNAL WATCHERS - signal me when a signal gets signalled!	501	SIGNAL WATCHERS - signal me when a signal gets signalled!
415	$w = EV::signal $signal, $callback	502	$w = EV::signal $signal, $callback
416	$w = EV::signal_ns $signal, $callback	503	$w = EV::signal_ns $signal, $callback
417	Call the callback when $signal is received (the signal can be	504	Call the callback when $signal is received (the signal can be
418	specified by number or by name, just as with "kill" or %SIG).	505	specified by number or by name, just as with "kill" or %SIG).
…		…
435	$old_signum = $w->signal ($new_signal)	522	$old_signum = $w->signal ($new_signal)
436	Returns the previously set signal (always as a number not name) and	523	Returns the previously set signal (always as a number not name) and
437	optionally set a new one.	524	optionally set a new one.
438		525
439	CHILD WATCHERS - watch out for process status changes	526	CHILD WATCHERS - watch out for process status changes
440	$w = EV::child $pid, $callback	527	$w = EV::child $pid, $trace, $callback
441	$w = EV::child_ns $pid, $callback	528	$w = EV::child_ns $pid, $trace, $callback
		529	$w = $loop->child ($pid, $trace, $callback)
		530	$w = $loop->child_ns ($pid, $trace, $callback)
442	Call the callback when a status change for pid $pid (or any pid if	531	Call the callback when a status change for pid $pid (or any pid if
443	$pid is 0) has been received. More precisely: when the process	532	$pid is 0) has been received (a status change happens when the
		533	process terminates or is killed, or, when trace is true,
		534	additionally when it is stopped or continued). More precisely: when
444	receives a "SIGCHLD", EV will fetch the outstanding exit/wait status	535	the process receives a "SIGCHLD", EV will fetch the outstanding
445	for all changed/zombie children and call the callback.	536	exit/wait status for all changed/zombie children and call the
		537	callback.
446		538
447	It is valid (and fully supported) to install a child watcher after a	539	It is valid (and fully supported) to install a child watcher after a
448	child has exited but before the event loop has started its next	540	child has exited but before the event loop has started its next
449	iteration (for example, first you "fork", then the new child process	541	iteration (for example, first you "fork", then the new child process
450	might exit, and only then do you install a child watcher in the	542	might exit, and only then do you install a child watcher in the
…		…
457	be called.	549	be called.
458		550
459	The "child_ns" variant doesn't start (activate) the newly created	551	The "child_ns" variant doesn't start (activate) the newly created
460	watcher.	552	watcher.
461		553
462	$w->set ($pid)	554	$w->set ($pid, $trace)
463	Reconfigures the watcher, see the constructor above for details. Can	555	Reconfigures the watcher, see the constructor above for details. Can
464	be called at any time.	556	be called at any time.
465		557
466	$current_pid = $w->pid	558	$current_pid = $w->pid
467	$old_pid = $w->pid ($new_pid)
468	Returns the previously set process id and optionally set a new one.	559	Returns the previously set process id and optionally set a new one.
469		560
470	$exit_status = $w->rstatus	561	$exit_status = $w->rstatus
471	Return the exit/wait status (as returned by waitpid, see the waitpid	562	Return the exit/wait status (as returned by waitpid, see the waitpid
472	entry in perlfunc).	563	entry in perlfunc).
…		…
476	a watcher for all pids).	567	a watcher for all pids).
477		568
478	STAT WATCHERS - did the file attributes just change?	569	STAT WATCHERS - did the file attributes just change?
479	$w = EV::stat $path, $interval, $callback	570	$w = EV::stat $path, $interval, $callback
480	$w = EV::stat_ns $path, $interval, $callback	571	$w = EV::stat_ns $path, $interval, $callback
		572	$w = $loop->stat ($path, $interval, $callback)
		573	$w = $loop->stat_ns ($path, $interval, $callback)
481	Call the callback when a file status change has been detected on	574	Call the callback when a file status change has been detected on
482	$path. The $path does not need to exist, changing from "path exists"	575	$path. The $path does not need to exist, changing from "path exists"
483	to "path does not exist" is a status change like any other.	576	to "path does not exist" is a status change like any other.
484		577
485	The $interval is a recommended polling interval for systems where	578	The $interval is a recommended polling interval for systems where
…		…
545	Can be used to query the actual interval used.	638	Can be used to query the actual interval used.
546		639
547	IDLE WATCHERS - when you've got nothing better to do...	640	IDLE WATCHERS - when you've got nothing better to do...
548	$w = EV::idle $callback	641	$w = EV::idle $callback
549	$w = EV::idle_ns $callback	642	$w = EV::idle_ns $callback
		643	$w = $loop->idle ($callback)
		644	$w = $loop->idle_ns ($callback)
550	Call the callback when there are no other pending watchers of the	645	Call the callback when there are no other pending watchers of the
551	same or higher priority (excluding check, prepare and other idle	646	same or higher priority (excluding check, prepare and other idle
552	watchers of the same or lower priority, of course). They are called	647	watchers of the same or lower priority, of course). They are called
553	idle watchers because when the watcher is the highest priority	648	idle watchers because when the watcher is the highest priority
554	pending event in the process, the process is considered to be idle	649	pending event in the process, the process is considered to be idle
…		…
570	watcher.	665	watcher.
571		666
572	PREPARE WATCHERS - customise your event loop!	667	PREPARE WATCHERS - customise your event loop!
573	$w = EV::prepare $callback	668	$w = EV::prepare $callback
574	$w = EV::prepare_ns $callback	669	$w = EV::prepare_ns $callback
		670	$w = $loop->prepare ($callback)
		671	$w = $loop->prepare_ns ($callback)
575	Call the callback just before the process would block. You can still	672	Call the callback just before the process would block. You can still
576	create/modify any watchers at this point.	673	create/modify any watchers at this point.
577		674
578	See the EV::check watcher, below, for explanations and an example.	675	See the EV::check watcher, below, for explanations and an example.
579		676
…		…
581	watcher.	678	watcher.
582		679
583	CHECK WATCHERS - customise your event loop even more!	680	CHECK WATCHERS - customise your event loop even more!
584	$w = EV::check $callback	681	$w = EV::check $callback
585	$w = EV::check_ns $callback	682	$w = EV::check_ns $callback
		683	$w = $loop->check ($callback)
		684	$w = $loop->check_ns ($callback)
586	Call the callback just after the process wakes up again (after it	685	Call the callback just after the process wakes up again (after it
587	has gathered events), but before any other callbacks have been	686	has gathered events), but before any other callbacks have been
588	invoked.	687	invoked.
589		688
590	This is used to integrate other event-based software into the EV	689	This is used to integrate other event-based software into the EV
…		…
639	is done before the event loop blocks next and before "check" watchers	738	is done before the event loop blocks next and before "check" watchers
640	are being called, and only in the child after the fork.	739	are being called, and only in the child after the fork.
641		740
642	$w = EV::fork $callback	741	$w = EV::fork $callback
643	$w = EV::fork_ns $callback	742	$w = EV::fork_ns $callback
		743	$w = $loop->fork ($callback)
		744	$w = $loop->fork_ns ($callback)
644	Call the callback before the event loop is resumed in the child	745	Call the callback before the event loop is resumed in the child
645	process after a fork.	746	process after a fork.
646		747
647	The "fork_ns" variant doesn't start (activate) the newly created	748	The "fork_ns" variant doesn't start (activate) the newly created
648	watcher.	749	watcher.
		750
		751	EMBED WATCHERS - when one backend isn't enough...
		752	This is a rather advanced watcher type that lets you embed one event
		753	loop into another (currently only IO events are supported in the
		754	embedded loop, other types of watchers might be handled in a delayed or
		755	incorrect fashion and must not be used).
		756
		757	See the libev documentation at
		758	<http://pod.tst.eu/http://cvs.schmorp.de/libev/ev.pod#code_ev_embed_code
		759	_when_one_backend_> for more details.
		760
		761	In short, this watcher is most useful on BSD systems without working
		762	kqueue to still be able to handle a large number of sockets:
		763
		764	my $socket_loop;
		765
		766	# check wether we use SELECT or POLL _and_ KQUEUE is supported
		767	if (
		768	(EV::backend & (EV::BACKEND_POLL \| EV::BACKEND_SELECT))
		769	&& (EV::supported_backends & EV::embeddable_backends & EV::BACKEND_KQUEUE)
		770	) {
		771	# use kqueue for sockets
		772	$socket_loop = new EV::Loop EV::BACKEND_KQUEUE \| EV::FLAG_NOENV;
		773	}
		774
		775	# use the default loop otherwise
		776	$socket_loop \|\|= EV::default_loop;
		777
		778	$w = EV::embed $otherloop, $callback
		779	$w = EV::embed_ns $otherloop, $callback
		780	$w = $loop->embed ($otherloop, $callback)
		781	$w = $loop->embed_ns ($otherloop, $callback)
		782	Call the callback when the embedded event loop ($otherloop) has any
		783	I/O activity. The $callback should alwas be specified as "undef" in
		784	this version of EV, which means the embedded event loop will be
		785	managed automatically.
		786
		787	The "embed_ns" variant doesn't start (activate) the newly created
		788	watcher.
		789
		790	ASYNC WATCHERS - how to wake up another event loop
		791	Async watchers are provided by EV, but have little use in perl directly,
		792	as perl neither supports threads nor direct access to signal handlers or
		793	other contexts where they could be of value.
		794
		795	It is, however, possible to use them from the XS level.
		796
		797	Please see the libev documentation for further details.
		798
		799	$w = EV::async $callback
		800	$w = EV::async_ns $callback
		801	$w->send
		802	$bool = $w->async_pending
649		803
650	PERL SIGNALS	804	PERL SIGNALS
651	While Perl signal handling (%SIG) is not affected by EV, the behaviour	805	While Perl signal handling (%SIG) is not affected by EV, the behaviour
652	with EV is as the same as any other C library: Perl-signals will only be	806	with EV is as the same as any other C library: Perl-signals will only be
653	handled when Perl runs, which means your signal handler might be invoked	807	handled when Perl runs, which means your signal handler might be invoked
…		…
660	to be called on every event loop iteration by installing a "EV::check"	814	to be called on every event loop iteration by installing a "EV::check"
661	watcher:	815	watcher:
662		816
663	my $async_check = EV::check sub { };	817	my $async_check = EV::check sub { };
664		818
665	This ensures that perl shortly gets into control for a short time, and	819	This ensures that perl gets into control for a short time to handle any
666	also ensures slower overall operation.	820	pending signals, and also ensures (slightly) slower overall operation.
667		821
668	THREADS	822	THREADS
669	Threads are not supported by this module in any way. Perl pseudo-threads	823	Threads are not supported by this module in any way. Perl pseudo-threads
670	is evil stuff and must die. As soon as Perl gains real threads I will	824	is evil stuff and must die. As soon as Perl gains real threads I will
671	work on thread support for it.	825	work on thread support for it.
…		…
686		840
687	On win32, there is no notion of fork so all this doesn't apply, of	841	On win32, there is no notion of fork so all this doesn't apply, of
688	course.	842	course.
689		843
690	SEE ALSO	844	SEE ALSO
691	EV::ADNS (asynchronous dns), Glib::EV (makes Glib/Gtk2 use EV as event	845	EV::ADNS (asynchronous DNS), Glib::EV (makes Glib/Gtk2 use EV as event
692	loop), Coro::EV (efficient coroutines with EV).	846	loop), EV::Glib (embed Glib into EV), Coro::EV (efficient coroutines
		847	with EV), Net::SNMP::EV (asynchronous SNMP), AnyEvent for event-loop
		848	agnostic and portable event driven programming.
693		849
694	AUTHOR	850	AUTHOR
695	Marc Lehmann <schmorp@schmorp.de>	851	Marc Lehmann <schmorp@schmorp.de>
696	http://home.schmorp.de/	852	http://home.schmorp.de/
697		853

Diff Legend

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

Comparing EV/README (file contents): Revision 1.17 by root, Sat Dec 8 14:44:21 2007 UTC vs. Revision 1.26 by root, Wed May 21 23:40:08 2008 UTC

Diff Legend

Comparing EV/README (file contents):
Revision 1.17 by root, Sat Dec 8 14:44:21 2007 UTC vs.
Revision 1.26 by root, Wed May 21 23:40:08 2008 UTC