[ViewVC] Diff of: cvs/EV/README

Comparing EV/README (file contents):
Revision 1.19 by root, Tue Dec 18 01:37:46 2007 UTC vs.
Revision 1.22 by root, Mon Jan 28 12:24:05 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
…		…
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", or just	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.	62	about in any case because it has much more detailed information.
63		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).
		99
64	BASIC INTERFACE	100	BASIC INTERFACE
65	$EV::DIED	101	$EV::DIED
66	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
67	callback throws an exception (with $@ containing the error). The	103	callback throws an exception (with $@ containing the error). The
68	default prints an informative message and continues.	104	default prints an informative message and continues.
69		105
70	If this callback throws an exception it will be silently ignored.	106	If this callback throws an exception it will be silently ignored.
71		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.
		118
72	$time = EV::time	119	$time = EV::time
73	Returns the current time in (fractional) seconds since the epoch.	120	Returns the current time in (fractional) seconds since the epoch.
74		121
75	$time = EV::now	122	$time = EV::now
		123	$time = $loop->now
76	Returns the time the last event loop iteration has been started.	124	Returns the time the last event loop iteration has been started.
77	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
78	to it is usually faster then calling EV::time.	126	to it is usually faster then calling EV::time.
79		127
80	$method = EV::method	128	$backend = EV::backend
		129	$backend = $loop->backend
81	Returns an integer describing the backend used by libev	130	Returns an integer describing the backend used by libev
82	(EV::METHOD_SELECT or EV::METHOD_EPOLL).	131	(EV::METHOD_SELECT or EV::METHOD_EPOLL).
83		132
84	EV::loop [$flags]	133	EV::loop [$flags]
		134	$loop->loop ([$flags])
85	Begin checking for events and calling callbacks. It returns when a	135	Begin checking for events and calling callbacks. It returns when a
86	callback calls EV::unloop.	136	callback calls EV::unloop.
87		137
88	The $flags argument can be one of the following:	138	The $flags argument can be one of the following:
89		139
90	0 as above	140	0 as above
91	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)
92	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)
93		143
94	EV::unloop [$how]	144	EV::unloop [$how]
		145	$loop->unloop ([$how])
95	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,
96	makes the innermost call to EV::loop return.	147	makes the innermost call to EV::loop return.
97		148
98	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
99	EV::loop will return as fast as possible.	150	EV::loop will return as fast as possible.
100		151
101	$count = EV::loop_count	152	$count = EV::loop_count
		153	$count = $loop->loop_count
102	Return the number of times the event loop has polled for new events.	154	Return the number of times the event loop has polled for new events.
103	Sometiems useful as a generation counter.	155	Sometiems useful as a generation counter.
104		156
105	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))
106	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
107	one-shot event without the need for managing a watcher object.	160	one-shot event without the need for managing a watcher object.
108		161
109	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
110	must be a bitset containing either "EV::READ", "EV::WRITE" or	163	must be a bitset containing either "EV::READ", "EV::WRITE" or
…		…
115	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.
116	Otherwise a EV::timer with this value will be started.	169	Otherwise a EV::timer with this value will be started.
117		170
118	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,
119	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
120	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",
121	"EV::READ", "EV::WRITE" and "EV::TIMEOUT").	174	"EV::READ", "EV::WRITE" and "EV::TIMEOUT").
122		175
123	EV::once doesn't return anything: the watchers stay active till	176	EV::once doesn't return anything: the watchers stay active till
124	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
125	the callback invoked.	178	the callback invoked.
126		179
127	EV::feed_fd_event ($fd, $revents)	180	EV::feed_fd_event ($fd, $revents)
		181	$loop->feed_fd_event ($fd, $revents)
128	Feed an event on a file descriptor into EV. EV will react to this	182	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	183	call as if the readyness notifications specified by $revents (a
130	combination of "EV::READ" and "EV::WRITE") happened on the file	184	combination of "EV::READ" and "EV::WRITE") happened on the file
131	descriptor $fd.	185	descriptor $fd.
132		186
133	EV::feed_signal_event ($signal)	187	EV::feed_signal_event ($signal)
134	Feed a signal event into EV. EV will react to this call as if the	188	Feed a signal event into EV. EV will react to this call as if the
135	signal specified by $signal had occured.	189	signal specified by $signal had occured.
136		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
137	WATCHER OBJECTS	201	WATCHER OBJECTS
138	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
139	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,
140	you would create an EV::io watcher for that:	204	you would create an EV::io watcher for that:
141		205
142	my $watcher = EV::io *STDIN, EV::READ, sub {	206	my $watcher = EV::io *STDIN, EV::READ, sub {
143	my ($watcher, $revents) = @_;	207	my ($watcher, $revents) = @_;
144	warn "yeah, STDIN should not be readable without blocking!\n"	208	warn "yeah, STDIN should now be readable without blocking!\n"
145	};	209	};
146		210
147	All watchers can be active (waiting for events) or inactive (paused).	211	All watchers can be active (waiting for events) or inactive (paused).
148	Only active watchers will have their callbacks invoked. All callbacks	212	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	213	will be called with at least two arguments: the watcher and a bitmask of
…		…
220	$w->feed_event ($revents)	284	$w->feed_event ($revents)
221	Feed some events on this watcher into EV. EV will react to this call	285	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.	286	as if the watcher had received the given $revents mask.
223		287
224	$revents = $w->clear_pending	288	$revents = $w->clear_pending
225	If the watcher is pending, this function returns clears its pending	289	If the watcher is pending, this function clears its pending status
226	status and returns its $revents bitset (as if its callback was	290	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	291	the watcher isn't pending it does nothing and returns 0.
228	0.
229		292
230	$previous_state = $w->keepalive ($bool)	293	$previous_state = $w->keepalive ($bool)
231	Normally, "EV::loop" will return when there are no active watchers	294	Normally, "EV::loop" will return when there are no active watchers
232	(which is a "deadlock" because no progress can be made anymore).	295	(which is a "deadlock" because no progress can be made anymore).
233	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
234	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
235	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
236	for their task :).	299	for their task :).
237		300
238	Sometimes, however, this gets in your way, for example when you the	301	Sometimes, however, this gets in your way, for example when the
239	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
240	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
241	module written by somebody else even). Then you might want any	304	module written by somebody else even). Then you might want any
242	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
243	"EV::loop" from returning just because you happen to have this	306	"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	316	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.	317	the event loop from running just because of that watcher.
255		318
256	my $udp_socket = ...	319	my $udp_socket = ...
257	my $udp_watcher = EV::io $udp_socket, EV::READ, sub { ... };	320	my $udp_watcher = EV::io $udp_socket, EV::READ, sub { ... };
258	$udp_watcher->keepalive (0);	321	$1000udp_watcher->keepalive (0);
259		322
		323	$loop = $w->loop
		324	Return the loop that this watcher is attached to.
		325
260	WATCHER TYPES	326	WATCHER TYPES
261	Each of the following subsections describes a single watcher type.	327	Each of the following subsections describes a single watcher type.
262		328
263	I/O WATCHERS - is this file descriptor readable or writable?	329	I/O WATCHERS - is this file descriptor readable or writable?
264	$w = EV::io $fileno_or_fh, $eventmask, $callback	330	$w = EV::io $fileno_or_fh, $eventmask, $callback
265	$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)
266	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
267	when at least one of events specified in $eventmask occurs.	335	when at least one of events specified in $eventmask occurs.
268		336
269	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:
270		338
…		…
287	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.
288		356
289	TIMER WATCHERS - relative and optionally repeating timeouts	357	TIMER WATCHERS - relative and optionally repeating timeouts
290	$w = EV::timer $after, $repeat, $callback	358	$w = EV::timer $after, $repeat, $callback
291	$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)
292	Calls the callback after $after seconds (which may be fractional).	362	Calls the callback after $after seconds (which may be fractional).
293	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
294	$repeat value as $after) after the callback returns.	364	$repeat value as $after) after the callback returns.
295		365
296	This means that the callback would be called roughly after $after	366	This means that the callback would be called roughly after $after
…		…
332	method on the timeout.	402	method on the timeout.
333		403
334	PERIODIC WATCHERS - to cron or not to cron?	404	PERIODIC WATCHERS - to cron or not to cron?
335	$w = EV::periodic $at, $interval, $reschedule_cb, $callback	405	$w = EV::periodic $at, $interval, $reschedule_cb, $callback
336	$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)
337	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
338	absolute times. Apart from creating "simple" timers that trigger	410	absolute times. Apart from creating "simple" timers that trigger
339	"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
340	absolute timers and more complex, cron-like, setups that are not	412	absolute timers and more complex, cron-like, setups that are not
341	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
342	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
343	the most complex watcher type in EV.	415	the most complex watcher type in EV.
344		416
345	It has three distinct "modes":	417	It has three distinct "modes":
346		418
347	* absolute timer ($interval = $reschedule_cb = 0)	419	* absolute timer ($interval = $reschedule_cb = 0)
		420
348	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
349	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
350	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
351	system time reaches or surpasses this time.	424	system time reaches or surpasses this time.
352		425
353	* non-repeating interval timer ($interval > 0, $reschedule_cb = 0)	426	* non-repeating interval timer ($interval > 0, $reschedule_cb = 0)
		427
354	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
355	the next "$at + N * $interval" time (for some integer N) and	429	the next "$at + N * $interval" time (for some integer N) and
356	then repeat, regardless of any time jumps.	430	then repeat, regardless of any time jumps.
357		431
358	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
…		…
367	Another way to think about it (for the mathematically inclined)	441	Another way to think about it (for the mathematically inclined)
368	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
369	at the next possible time where "$time = $at (mod $interval)",	443	at the next possible time where "$time = $at (mod $interval)",
370	regardless of any time jumps.	444	regardless of any time jumps.
371		445
372	* manual reschedule mode ($reschedule_cb = coderef)	446	* manual reschedule mode ($reschedule_cb = coderef)
		447
373	In this mode $interval and $at are both being ignored. Instead,	448	In this mode $interval and $at are both being ignored. Instead,
374	each time the periodic watcher gets scheduled, the reschedule	449	each time the periodic watcher gets scheduled, the reschedule
375	callback ($reschedule_cb) will be called with the watcher as	450	callback ($reschedule_cb) will be called with the watcher as
376	first, and the current time as second argument.	451	first, and the current time as second argument.
377		452
…		…
438	$old_signum = $w->signal ($new_signal)	513	$old_signum = $w->signal ($new_signal)
439	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
440	optionally set a new one.	515	optionally set a new one.
441		516
442	CHILD WATCHERS - watch out for process status changes	517	CHILD WATCHERS - watch out for process status changes
443	$w = EV::child $pid, $callback	518	$w = EV::child $pid, $trace, $callback
444	$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)
445	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
446	$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
447	receives a "SIGCHLD", EV will fetch the outstanding exit/wait status	526	the process receives a "SIGCHLD", EV will fetch the outstanding
448	for all changed/zombie children and call the callback.	527	exit/wait status for all changed/zombie children and call the
		528	callback.
449		529
450	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
451	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
452	iteration (for example, first you "fork", then the new child process	532	iteration (for example, first you "fork", then the new child process
453	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
…		…
460	be called.	540	be called.
461		541
462	The "child_ns" variant doesn't start (activate) the newly created	542	The "child_ns" variant doesn't start (activate) the newly created
463	watcher.	543	watcher.
464		544
465	$w->set ($pid)	545	$w->set ($pid, $trace)
466	Reconfigures the watcher, see the constructor above for details. Can	546	Reconfigures the watcher, see the constructor above for details. Can
467	be called at any time.	547	be called at any time.
468		548
469	$current_pid = $w->pid	549	$current_pid = $w->pid
470	$old_pid = $w->pid ($new_pid)
471	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.
472		551
473	$exit_status = $w->rstatus	552	$exit_status = $w->rstatus
474	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
475	entry in perlfunc).	554	entry in perlfunc).
…		…
479	a watcher for all pids).	558	a watcher for all pids).
480		559
481	STAT WATCHERS - did the file attributes just change?	560	STAT WATCHERS - did the file attributes just change?
482	$w = EV::stat $path, $interval, $callback	561	$w = EV::stat $path, $interval, $callback
483	$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)
484	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
485	$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"
486	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.
487		568
488	The $interval is a recommended polling interval for systems where	569	The $interval is a recommended polling interval for systems where
…		…
548	Can be used to query the actual interval used.	629	Can be used to query the actual interval used.
549		630
550	IDLE WATCHERS - when you've got nothing better to do...	631	IDLE WATCHERS - when you've got nothing better to do...
551	$w = EV::idle $callback	632	$w = EV::idle $callback
552	$w = EV::idle_ns $callback	633	$w = EV::idle_ns $callback
		634	$w = $loop->idle ($callback)
		635	$w = $loop->idle_ns ($callback)
553	Call the callback when there are no other pending watchers of the	636	Call the callback when there are no other pending watchers of the
554	same or higher priority (excluding check, prepare and other idle	637	same or higher priority (excluding check, prepare and other idle
555	watchers of the same or lower priority, of course). They are called	638	watchers of the same or lower priority, of course). They are called
556	idle watchers because when the watcher is the highest priority	639	idle watchers because when the watcher is the highest priority
557	pending event in the process, the process is considered to be idle	640	pending event in the process, the process is considered to be idle
…		…
573	watcher.	656	watcher.
574		657
575	PREPARE WATCHERS - customise your event loop!	658	PREPARE WATCHERS - customise your event loop!
576	$w = EV::prepare $callback	659	$w = EV::prepare $callback
577	$w = EV::prepare_ns $callback	660	$w = EV::prepare_ns $callback
		661	$w = $loop->prepare ($callback)
		662	$w = $loop->prepare_ns ($callback)
578	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
579	create/modify any watchers at this point.	664	create/modify any watchers at this point.
580		665
581	See the EV::check watcher, below, for explanations and an example.	666	See the EV::check watcher, below, for explanations and an example.
582		667
…		…
584	watcher.	669	watcher.
585		670
586	CHECK WATCHERS - customise your event loop even more!	671	CHECK WATCHERS - customise your event loop even more!
587	$w = EV::check $callback	672	$w = EV::check $callback
588	$w = EV::check_ns $callback	673	$w = EV::check_ns $callback
		674	$w = $loop->check ($callback)
		675	$w = $loop->check_ns ($callback)
589	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
590	has gathered events), but before any other callbacks have been	677	has gathered events), but before any other callbacks have been
591	invoked.	678	invoked.
592		679
593	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
…		…
642	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
643	are being called, and only in the child after the fork.	730	are being called, and only in the child after the fork.
644		731
645	$w = EV::fork $callback	732	$w = EV::fork $callback
646	$w = EV::fork_ns $callback	733	$w = EV::fork_ns $callback
		734	$w = $loop->fork ($callback)
		735	$w = $loop->fork_ns ($callback)
647	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
648	process after a fork.	737	process after a fork.
649		738
650	The "fork_ns" variant doesn't start (activate) the newly created	739	The "fork_ns" variant doesn't start (activate) the newly created
		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
651	watcher.	779	watcher.
652		780
653	PERL SIGNALS	781	PERL SIGNALS
654	While Perl signal handling (%SIG) is not affected by EV, the behaviour	782	While Perl signal handling (%SIG) is not affected by EV, the behaviour
655	with EV is as the same as any other C library: Perl-signals will only be	783	with EV is as the same as any other C library: Perl-signals will only be
…		…
663	to be called on every event loop iteration by installing a "EV::check"	791	to be called on every event loop iteration by installing a "EV::check"
664	watcher:	792	watcher:
665		793
666	my $async_check = EV::check sub { };	794	my $async_check = EV::check sub { };
667		795
668	This ensures that perl shortly gets into control for a short time, and	796	This ensures that perl gets into control for a short time to handle any
669	also ensures slower overall operation.	797	pending signals, and also ensures (slightly) slower overall operation.
670		798
671	THREADS	799	THREADS
672	Threads are not supported by this module in any way. Perl pseudo-threads	800	Threads are not supported by this module in any way. Perl pseudo-threads
673	is evil stuff and must die. As soon as Perl gains real threads I will	801	is evil stuff and must die. As soon as Perl gains real threads I will
674	work on thread support for it.	802	work on thread support for it.
…		…
689		817
690	On win32, there is no notion of fork so all this doesn't apply, of	818	On win32, there is no notion of fork so all this doesn't apply, of
691	course.	819	course.
692		820
693	SEE ALSO	821	SEE ALSO
694	EV::ADNS (asynchronous dns), Glib::EV (makes Glib/Gtk2 use EV as event	822	EV::ADNS (asynchronous DNS), Glib::EV (makes Glib/Gtk2 use EV as event
695	loop), Coro::EV (efficient coroutines with EV).	823	loop), EV::Glib (embed Glib into EV), Coro::EV (efficient coroutines
		824	with EV), Net::SNMP::EV (asynchronous SNMP).
696		825
697	AUTHOR	826	AUTHOR
698	Marc Lehmann <schmorp@schmorp.de>	827	Marc Lehmann <schmorp@schmorp.de>
699	http://home.schmorp.de/	828	http://home.schmorp.de/
700		829

Diff Legend

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

Comparing EV/README (file contents): Revision 1.19 by root, Tue Dec 18 01:37:46 2007 UTC vs. Revision 1.22 by root, Mon Jan 28 12:24:05 2008 UTC

Diff Legend

Comparing EV/README (file contents):
Revision 1.19 by root, Tue Dec 18 01:37:46 2007 UTC vs.
Revision 1.22 by root, Mon Jan 28 12:24:05 2008 UTC