[ViewVC] Diff of: cvs/EV/README

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

Diff Legend

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

Comparing EV/README (file contents): Revision 1.15 by root, Wed Dec 5 14:06:50 2007 UTC vs. Revision 1.27 by root, Mon May 26 05:37:18 2008 UTC

Diff Legend

Comparing EV/README (file contents):
Revision 1.15 by root, Wed Dec 5 14:06:50 2007 UTC vs.
Revision 1.27 by root, Mon May 26 05:37:18 2008 UTC