[ViewVC] Diff of: cvs/EV/README

Comparing EV/README (file contents):
Revision 1.8 by root, Thu Nov 8 17:02:10 2007 UTC vs.
Revision 1.21 by root, Sat Dec 22 16:48:33 2007 UTC

…		…
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, 1, sub {	14	my $w = EV::timer 2, 2, sub {
15	warn "is called roughly every 2s (repeat = 1)";	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 {
…		…
22	};	22	};
23		23
24	# IO	24	# IO
25		25
26	my $w = EV::io *STDIN, EV::READ, sub {	26	my $w = EV::io *STDIN, EV::READ, sub {
27	my ($w, $revents) = @_; # all callbacks get the watcher object 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	my $w = EV::signal 3, sub {
38	warn "sigquit received (this is GNU/Linux, right?)\n";
39	};
40
41	# CHILD/PID STATUS CHANGES	37	# CHILD/PID STATUS CHANGES
42		38
43	my $w = EV::child 666, sub {	39	my $w = EV::child 666, sub {
44	my ($w, $revents) = @_;	40	my ($w, $revents) = @_;
45	# my $pid = $w->rpid;
46	my $status = $w->rstatus;	41	my $status = $w->rstatus;
47	};	42	};
		43
		44	# STAT CHANGES
		45	my $w = EV::stat "/etc/passwd", 10, sub {
		46	my ($w, $revents) = @_;
		47	warn $w->path, " has changed somehow.\n";
		48	};
48		49
49	# MAINLOOP	50	# MAINLOOP
50	EV::loop; # loop until EV::loop_done is called	51	EV::loop; # loop until EV::unloop is called or all watchers stop
51	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
52	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
53		54
54	DESCRIPTION	55	DESCRIPTION
55	This module provides an interface to libev	56	This module provides an interface to libev
56	(<http://software.schmorp.de/pkg/libev.html>).	57	(<http://software.schmorp.de/pkg/libev.html>). While the documentation
		58	below is comprehensive, one might also consult the documentation of
		59	libev itself (<http://cvs.schmorp.de/libev/ev.html>) for more subtle
		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
		62	about in any case because it has much more detailed information.
		63
		64	EVENT LOOPS
		65	EV supports multiple event loops: There is a single "default event loop"
		66	that can handle everything including signals and child watchers, and any
		67	number of "dynamic event loops" that can use different backends (with
		68	various limitations), but no child and signal watchers.
		69
		70	You do not have to do anything to create the default event loop: When
		71	the module is loaded a suitable backend is selected on the premise of
		72	selecting a working backend (which for example rules out kqueue on most
		73	BSDs). Modules should, unless they have "special needs" always use the
		74	default loop as this is fastest (perl-wise), best supported by other
		75	modules (e.g. AnyEvent or Coro) and most portable event loop.
		76
		77	For specific programs you can create additional event loops dynamically.
		78
		79	$loop = new EV::loop [$flags]
		80	Create a new event loop as per the specified flags. Please refer to
		81	the "ev_loop_new ()" function description in the libev documentation
		82	(<http://pod.tst.eu/http://cvs.schmorp.de/libev/ev.pod#GLOBAL_FUNCTI
		83	ONS>) for more info.
		84
		85	The loop will automatically be destroyed when it is no longer
		86	referenced by any watcher and the loop object goes out of scope.
		87
		88	Using "EV::FLAG_FORKCHECK" is recommended, as only the default event
		89	loop is protected by this module.
		90
		91	$loop->loop_fork
		92	Must be called after a fork in the child, before entering or
		93	continuing the event loop. An alternative is to use
		94	"EV::FLAG_FORKCHECK" which calls this fucntion automatically, at
		95	some performance loss (refer to the libev documentation).
		96
		97	$loop = EV::default_loop [$flags]
		98	Return the default loop (which is a singleton object).
57		99
58	BASIC INTERFACE	100	BASIC INTERFACE
59	$EV::DIED	101	$EV::DIED
60	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
61	callback throws an exception (with $@ containing thr error). The	103	callback throws an exception (with $@ containing the error). The
62	default prints an informative message and continues.	104	default prints an informative message and continues.
63		105
64	If this callback throws an exception it will be silently ignored.	106	If this callback throws an exception it will be silently ignored.
		107
		108	$flags = EV::supported_backends
		109	$flags = EV::recommended_backends
		110	$flags = EV::embeddable_backends
		111	Returns the set (see "EV::BACKEND_*" flags) of backends supported by
		112	this instance of EV, the set of recommended backends (supposed to be
		113	good) for this platform and the set of embeddable backends (see
		114	EMBED WATCHERS).
		115
		116	EV::sleep $seconds
		117	Block the process for the given number of (fractional) seconds.
65		118
66	$time = EV::time	119	$time = EV::time
67	Returns the current time in (fractional) seconds since the epoch.	120	Returns the current time in (fractional) seconds since the epoch.
68		121
69	$time = EV::now	122	$time = EV::now
		123	$time = $loop->now
70	Returns the time the last event loop iteration has been started.	124	Returns the time the last event loop iteration has been started.
71	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
72	to it is usually faster then calling EV::time.	126	to it is usually faster then calling EV::time.
73		127
74	$method = EV::ev_method	128	$backend = EV::backend
		129	$backend = $loop->backend
75	Returns an integer describing the backend used by libev	130	Returns an integer describing the backend used by libev
76	(EV::METHOD_SELECT or EV::METHOD_EPOLL).	131	(EV::METHOD_SELECT or EV::METHOD_EPOLL).
77		132
78	EV::loop [$flags]	133	EV::loop [$flags]
		134	$loop->loop ([$flags])
79	Begin checking for events and calling callbacks. It returns when a	135	Begin checking for events and calling callbacks. It returns when a
80	callback calls EV::loop_done.	136	callback calls EV::unloop.
81		137
82	The $flags argument can be one of the following:	138	The $flags argument can be one of the following:
83		139
84	0 as above	140	0 as above
85	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)
86	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)
87		143
88	EV::loop_done [$how]	144	EV::unloop [$how]
		145	$loop->unloop ([$how])
89	When called with no arguments or an argument of 1, makes the	146	When called with no arguments or an argument of EV::UNLOOP_ONE,
90	innermost call to EV::loop return.	147	makes the innermost call to EV::loop return.
91		148
92	When called with an agrument of 2, all calls to EV::loop will return	149	When called with an argument of EV::UNLOOP_ALL, all calls to
93	as fast as possible.	150	EV::loop will return as fast as possible.
94		151
95	WATCHER	152	$count = EV::loop_count
		153	$count = $loop->loop_count
		154	Return the number of times the event loop has polled for new events.
		155	Sometiems useful as a generation counter.
		156
		157	EV::once $fh_or_undef, $events, $timeout, $cb->($revents)
		158	$loop->once ($fh_or_undef, $events, $timeout, $cb->($revents))
		159	This function rolls together an I/O and a timer watcher for a single
		160	one-shot event without the need for managing a watcher object.
		161
		162	If $fh_or_undef is a filehandle or file descriptor, then $events
		163	must be a bitset containing either "EV::READ", "EV::WRITE" or
		164	"EV::READ \| EV::WRITE", indicating the type of I/O event you want to
		165	wait for. If you do not want to wait for some I/O event, specify
		166	"undef" for $fh_or_undef and 0 for $events).
		167
		168	If timeout is "undef" or negative, then there will be no timeout.
		169	Otherwise a EV::timer with this value will be started.
		170
		171	When an error occurs or either the timeout or I/O watcher triggers,
		172	then the callback will be called with the received event set (in
		173	general you can expect it to be a combination of "EV::ERROR",
		174	"EV::READ", "EV::WRITE" and "EV::TIMEOUT").
		175
		176	EV::once doesn't return anything: the watchers stay active till
		177	either of them triggers, then they will be stopped and freed, and
		178	the callback invoked.
		179
		180	EV::feed_fd_event ($fd, $revents)
		181	$loop->feed_fd_event ($fd, $revents)
		182	Feed an event on a file descriptor into EV. EV will react to this
		183	call as if the readyness notifications specified by $revents (a
		184	combination of "EV::READ" and "EV::WRITE") happened on the file
		185	descriptor $fd.
		186
		187	EV::feed_signal_event ($signal)
		188	Feed a signal event into EV. EV will react to this call as if the
		189	signal specified by $signal had occured.
		190
		191	EV::set_io_collect_interval $time
		192	$loop->set_io_collect_interval ($time)
		193	EV::set_timeout_collect_interval $time
		194	$loop->set_timeout_collect_interval ($time)
		195	These advanced functions set the minimum block interval when polling
		196	for I/O events and the minimum wait interval for timer events. See
		197	the libev documentation at
		198	<http://pod.tst.eu/http://cvs.schmorp.de/libev/ev.pod#FUNCTIONS_CONT
		199	ROLLING_THE_EVENT_LOOP> for a more detailed discussion.
		200
		201	WATCHER OBJECTS
96	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
97	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,
98	you would create an EV::io watcher for that:	204	you would create an EV::io watcher for that:
99		205
100	my $watcher = EV::io *STDIN, EV::READ, sub {	206	my $watcher = EV::io *STDIN, EV::READ, sub {
101	my ($watcher, $revents) = @_;	207	my ($watcher, $revents) = @_;
102	warn "yeah, STDIN should not be readable without blocking!\n"	208	warn "yeah, STDIN should now be readable without blocking!\n"
103	};	209	};
104		210
105	All watchers can be active (waiting for events) or inactive (paused).	211	All watchers can be active (waiting for events) or inactive (paused).
106	Only active watchers will have their callbacks invoked. All callbacks	212	Only active watchers will have their callbacks invoked. All callbacks
107	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
108	received events.	214	received events.
109		215
110	Each watcher type has its associated bit in revents, so you can use the	216	Each watcher type has its associated bit in revents, so you can use the
111	same callback for multiple watchers. The event mask is named after the	217	same callback for multiple watchers. The event mask is named after the
112	type, i..e. EV::child sets EV::CHILD, EV::prepare sets EV::PREPARE,	218	type, i..e. EV::child sets EV::CHILD, EV::prepare sets EV::PREPARE,
113	EV::periodic sets EV::PERIODIC and so on, with the exception of IO	219	EV::periodic sets EV::PERIODIC and so on, with the exception of I/O
114	events (which can set both EV::READ and EV::WRITE bits), and EV::timer	220	events (which can set both EV::READ and EV::WRITE bits), and EV::timer
115	(which uses EV::TIMEOUT).	221	(which uses EV::TIMEOUT).
116		222
117	In the rare case where one wants to create a watcher but not start it at	223	In the rare case where one wants to create a watcher but not start it at
118	the same time, each constructor has a variant with a trailing "_ns" in	224	the same time, each constructor has a variant with a trailing "_ns" in
…		…
124		230
125	Also, all methods changing some aspect of a watcher (->set, ->priority,	231	Also, all methods changing some aspect of a watcher (->set, ->priority,
126	->fh and so on) automatically stop and start it again if it is active,	232	->fh and so on) automatically stop and start it again if it is active,
127	which means pending events get lost.	233	which means pending events get lost.
128		234
129	WATCHER TYPES	235	COMMON WATCHER METHODS
130	Now lets move to the existing watcher types and asociated methods.	236	This section lists methods common to all watchers.
131
132	The following methods are available for all watchers. Then followes a
133	description of each watcher constructor (EV::io, EV::timer,
134	EV::periodic, EV::signal, EV::child, EV::idle, EV::prepare and
135	EV::check), followed by any type-specific methods (if any).
136		237
137	$w->start	238	$w->start
138	Starts a watcher if it isn't active already. Does nothing to an	239	Starts a watcher if it isn't active already. Does nothing to an
139	already active watcher. By default, all watchers start out in the	240	already active watcher. By default, all watchers start out in the
140	active state (see the description of the "_ns" variants if you need	241	active state (see the description of the "_ns" variants if you need
141	stopped watchers).	242	stopped watchers).
142		243
143	$w->stop	244	$w->stop
144	Stop a watcher if it is active. Also clear any pending events	245	Stop a watcher if it is active. Also clear any pending events
145	(events that have been received but that didn't yet result in a	246	(events that have been received but that didn't yet result in a
146	callback invocation), regardless of wether the watcher was active or	247	callback invocation), regardless of whether the watcher was active
147	not.	248	or not.
148		249
149	$bool = $w->is_active	250	$bool = $w->is_active
150	Returns true if the watcher is active, false otherwise.	251	Returns true if the watcher is active, false otherwise.
151		252
152	$current_data = $w->data	253	$current_data = $w->data
…		…
170	Pending watchers with higher priority will be invoked first. The	271	Pending watchers with higher priority will be invoked first. The
171	valid range of priorities lies between EV::MAXPRI (default 2) and	272	valid range of priorities lies between EV::MAXPRI (default 2) and
172	EV::MINPRI (default -2). If the priority is outside this range it	273	EV::MINPRI (default -2). If the priority is outside this range it
173	will automatically be normalised to the nearest valid priority.	274	will automatically be normalised to the nearest valid priority.
174		275
175	The default priority of any newly-created weatcher is 0.	276	The default priority of any newly-created watcher is 0.
176		277
		278	Note that the priority semantics have not yet been fleshed out and
		279	are subject to almost certain change.
		280
177	$w->trigger ($revents)	281	$w->invoke ($revents)
178	Call the callback now with the given event mask.	282	Call the callback now with the given event mask.
179		283
		284	$w->feed_event ($revents)
		285	Feed some events on this watcher into EV. EV will react to this call
		286	as if the watcher had received the given $revents mask.
		287
		288	$revents = $w->clear_pending
		289	If the watcher is pending, this function clears its pending status
		290	and returns its $revents bitset (as if its callback was invoked). If
		291	the watcher isn't pending it does nothing and returns 0.
		292
		293	$previous_state = $w->keepalive ($bool)
		294	Normally, "EV::loop" will return when there are no active watchers
		295	(which is a "deadlock" because no progress can be made anymore).
		296	This is convinient because it allows you to start your watchers (and
		297	your jobs), call "EV::loop" once and when it returns you know that
		298	all your jobs are finished (or they forgot to register some watchers
		299	for their task :).
		300
		301	Sometimes, however, this gets in your way, for example when the
		302	module that calls "EV::loop" (usually the main program) is not the
		303	same module as a long-living watcher (for example a DNS client
		304	module written by somebody else even). Then you might want any
		305	outstanding requests to be handled, but you would not want to keep
		306	"EV::loop" from returning just because you happen to have this
		307	long-running UDP port watcher.
		308
		309	In this case you can clear the keepalive status, which means that
		310	even though your watcher is active, it won't keep "EV::loop" from
		311	returning.
		312
		313	The initial value for keepalive is true (enabled), and you cna
		314	change it any time.
		315
		316	Example: Register an I/O watcher for some UDP socket but do not keep
		317	the event loop from running just because of that watcher.
		318
		319	my $udp_socket = ...
		320	my $udp_watcher = EV::io $udp_socket, EV::READ, sub { ... };
		321	$1000udp_watcher->keepalive (0);
		322
		323	$loop = $w->loop
		324	Return the loop that this watcher is attached to.
		325
		326	WATCHER TYPES
		327	Each of the following subsections describes a single watcher type.
		328
		329	I/O WATCHERS - is this file descriptor readable or writable?
180	$w = EV::io $fileno_or_fh, $eventmask, $callback	330	$w = EV::io $fileno_or_fh, $eventmask, $callback
181	$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)
182	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
183	when the events specified in $eventmask.	335	when at least one of events specified in $eventmask occurs.
184		336
185	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:
186		338
187	EV::READ wait until read() wouldn't block anymore	339	EV::READ wait until read() wouldn't block anymore
188	EV::WRITE wait until write() wouldn't block anymore	340	EV::WRITE wait until write() wouldn't block anymore
…		…
200		352
201	$current_eventmask = $w->events	353	$current_eventmask = $w->events
202	$old_eventmask = $w->events ($new_eventmask)	354	$old_eventmask = $w->events ($new_eventmask)
203	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.
204		356
		357	TIMER WATCHERS - relative and optionally repeating timeouts
205	$w = EV::timer $after, $repeat, $callback	358	$w = EV::timer $after, $repeat, $callback
206	$w = EV::timer_ns $after, $repeat, $callback	359	$w = EV::timer_ns $after, $repeat, $callback
207	Calls the callback after $after seconds. If $repeat is non-zero, the	360	$w = $loop->timer ($after, $repeat, $callback)
208	timer will be restarted (with the $repeat value as $after) after the	361	$w = $loop->timer_ns ($after, $repeat, $callback)
209	callback returns.	362	Calls the callback after $after seconds (which may be fractional).
		363	If $repeat is non-zero, the timer will be restarted (with the
		364	$repeat value as $after) after the callback returns.
210		365
211	This means that the callback would be called roughly after $after	366	This means that the callback would be called roughly after $after
212	seconds, and then every $repeat seconds. "Roughly" because the time	367	seconds, and then every $repeat seconds. The timer does his best not
213	of callback processing is not taken into account, so the timer will	368	to drift, but it will not invoke the timer more often then once per
214	slowly drift. If that isn't acceptable, look at EV::periodic.	369	event loop iteration, and might drift in other cases. If that isn't
		370	acceptable, look at EV::periodic, which can provide long-term stable
		371	timers.
215		372
216	The timer is based on a monotonic clock, that is if somebody is	373	The timer is based on a monotonic clock, that is, if somebody is
217	sitting in front of the machine while the timer is running and	374	sitting in front of the machine while the timer is running and
218	changes the system clock, the timer will nevertheless run (roughly)	375	changes the system clock, the timer will nevertheless run (roughly)
219	the same time.	376	the same time.
220		377
221	The "timer_ns" variant doesn't start (activate) the newly created	378	The "timer_ns" variant doesn't start (activate) the newly created
222	watcher.	379	watcher.
223		380
224	$w->set ($after, $repeat)	381	$w->set ($after, $repeat)
225	Reconfigures the watcher, see the constructor above for details. Can	382	Reconfigures the watcher, see the constructor above for details. Can
226	be at any time.	383	be called at any time.
227		384
228	$w->again	385	$w->again
229	Similar to the "start" method, but has special semantics for	386	Similar to the "start" method, but has special semantics for
230	repeating timers:	387	repeating timers:
231		388
		389	If the timer is active and non-repeating, it will be stopped.
		390
232	If the timer is active and repeating, reset the timeout to occur	391	If the timer is active and repeating, reset the timeout to occur
233	$repeat seconds after now.	392	$repeat seconds after now.
234		393
235	If the timer is active and non-repeating, it will be stopped.
236
237	If the timer is in active and repeating, start it.	394	If the timer is inactive and repeating, start it using the repeat
		395	value.
238		396
239	Otherwise do nothing.	397	Otherwise do nothing.
240		398
241	This behaviour is useful when you have a timeout for some IO	399	This behaviour is useful when you have a timeout for some IO
242	operation. You create a timer object with the same value for $after	400	operation. You create a timer object with the same value for $after
243	and $repeat, and then, in the read/write watcher, run the "again"	401	and $repeat, and then, in the read/write watcher, run the "again"
244	method on the timeout.	402	method on the timeout.
245		403
		404	PERIODIC WATCHERS - to cron or not to cron?
246	$w = EV::periodic $at, $interval, $reschedule_cb, $callback	405	$w = EV::periodic $at, $interval, $reschedule_cb, $callback
247	$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)
248	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
249	absolute times. Apart from creating "simple" timers that trigger	410	absolute times. Apart from creating "simple" timers that trigger
250	"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
251	absolute timers and more complex, cron-like, setups that are not	412	absolute timers and more complex, cron-like, setups that are not
252	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
…		…
280	at the next possible time where "$time = $at (mod $interval)",	441	at the next possible time where "$time = $at (mod $interval)",
281	regardless of any time jumps.	442	regardless of any time jumps.
282		443
283	* manual reschedule mode ($reschedule_cb = coderef)	444	* manual reschedule mode ($reschedule_cb = coderef)
284	In this mode $interval and $at are both being ignored. Instead,	445	In this mode $interval and $at are both being ignored. Instead,
285	each time the periodic watcher gets scheduled, the first	446	each time the periodic watcher gets scheduled, the reschedule
286	callback ($reschedule_cb) will be called with the watcher as	447	callback ($reschedule_cb) will be called with the watcher as
287	first, and the current time as second argument.	448	first, and the current time as second argument.
288		449
289	*This callback MUST NOT stop or destroy this or any other	450	*This callback MUST NOT stop or destroy this or any other
290	periodic watcher, ever*. If you need to stop it, return 1e30 and	451	periodic watcher, ever*. If you need to stop it, return 1e30 and
…		…
315	The "periodic_ns" variant doesn't start (activate) the newly created	476	The "periodic_ns" variant doesn't start (activate) the newly created
316	watcher.	477	watcher.
317		478
318	$w->set ($at, $interval, $reschedule_cb)	479	$w->set ($at, $interval, $reschedule_cb)
319	Reconfigures the watcher, see the constructor above for details. Can	480	Reconfigures the watcher, see the constructor above for details. Can
320	be at any time.	481	be called at any time.
321		482
322	$w->again	483	$w->again
323	Simply stops and starts the watcher again.	484	Simply stops and starts the watcher again.
324		485
		486	$time = $w->at
		487	Return the time that the watcher is expected to trigger next.
		488
		489	SIGNAL WATCHERS - signal me when a signal gets signalled!
325	$w = EV::signal $signal, $callback	490	$w = EV::signal $signal, $callback
326	$w = EV::signal_ns $signal, $callback	491	$w = EV::signal_ns $signal, $callback
327	Call the callback when $signal is received (the signal can be	492	Call the callback when $signal is received (the signal can be
328	specified by number or by name, just as with kill or %SIG).	493	specified by number or by name, just as with "kill" or %SIG).
329		494
330	EV will grab the signal for the process (the kernel only allows one	495	EV will grab the signal for the process (the kernel only allows one
331	component to receive a signal at a time) when you start a signal	496	component to receive a signal at a time) when you start a signal
332	watcher, and removes it again when you stop it. Perl does the same	497	watcher, and removes it again when you stop it. Perl does the same
333	when you add/remove callbacks to %SIG, so watch out.	498	when you add/remove callbacks to %SIG, so watch out.
…		…
337	The "signal_ns" variant doesn't start (activate) the newly created	502	The "signal_ns" variant doesn't start (activate) the newly created
338	watcher.	503	watcher.
339		504
340	$w->set ($signal)	505	$w->set ($signal)
341	Reconfigures the watcher, see the constructor above for details. Can	506	Reconfigures the watcher, see the constructor above for details. Can
342	be at any time.	507	be called at any time.
343		508
344	$current_signum = $w->signal	509	$current_signum = $w->signal
345	$old_signum = $w->signal ($new_signal)	510	$old_signum = $w->signal ($new_signal)
346	Returns the previously set signal (always as a number not name) and	511	Returns the previously set signal (always as a number not name) and
347	optionally set a new one.	512	optionally set a new one.
348		513
		514	CHILD WATCHERS - watch out for process status changes
349	$w = EV::child $pid, $callback	515	$w = EV::child $pid, $callback
350	$w = EV::child_ns $pid, $callback	516	$w = EV::child_ns $pid, $callback
		517	$w = $loop->child ($pid, $callback)
		518	$w = $loop->child_ns ($pid, $callback)
351	Call the callback when a status change for pid $pid (or any pid if	519	Call the callback when a status change for pid $pid (or any pid if
352	$pid is 0) has been received. More precisely: when the process	520	$pid is 0) has been received. More precisely: when the process
353	receives a SIGCHLD, EV will fetch the outstanding exit/wait status	521	receives a "SIGCHLD", EV will fetch the outstanding exit/wait status
354	for all changed/zombie children and call the callback.	522	for all changed/zombie children and call the callback.
355		523
356	You can access both status and pid by using the "rstatus" and "rpid"	524	It is valid (and fully supported) to install a child watcher after a
		525	child has exited but before the event loop has started its next
		526	iteration (for example, first you "fork", then the new child process
		527	might exit, and only then do you install a child watcher in the
		528	parent for the new pid).
		529
		530	You can access both exit (or tracing) status and pid by using the
357	methods on the watcher object.	531	"rstatus" and "rpid" methods on the watcher object.
358		532
359	You can have as many pid watchers per pid as you want.	533	You can have as many pid watchers per pid as you want, they will all
		534	be called.
360		535
361	The "child_ns" variant doesn't start (activate) the newly created	536	The "child_ns" variant doesn't start (activate) the newly created
362	watcher.	537	watcher.
363		538
364	$w->set ($pid)	539	$w->set ($pid)
365	Reconfigures the watcher, see the constructor above for details. Can	540	Reconfigures the watcher, see the constructor above for details. Can
366	be at any time.	541	be called at any time.
367		542
368	$current_pid = $w->pid	543	$current_pid = $w->pid
369	$old_pid = $w->pid ($new_pid)	544	$old_pid = $w->pid ($new_pid)
370	Returns the previously set process id and optionally set a new one.	545	Returns the previously set process id and optionally set a new one.
371		546
…		…
375		550
376	$pid = $w->rpid	551	$pid = $w->rpid
377	Return the pid of the awaited child (useful when you have installed	552	Return the pid of the awaited child (useful when you have installed
378	a watcher for all pids).	553	a watcher for all pids).
379		554
		555	STAT WATCHERS - did the file attributes just change?
		556	$w = EV::stat $path, $interval, $callback
		557	$w = EV::stat_ns $path, $interval, $callback
		558	$w = $loop->stat ($path, $interval, $callback)
		559	$w = $loop->stat_ns ($path, $interval, $callback)
		560	Call the callback when a file status change has been detected on
		561	$path. The $path does not need to exist, changing from "path exists"
		562	to "path does not exist" is a status change like any other.
		563
		564	The $interval is a recommended polling interval for systems where
		565	OS-supported change notifications don't exist or are not supported.
		566	If you use 0 then an unspecified default is used (which is highly
		567	recommended!), which is to be expected to be around five seconds
		568	usually.
		569
		570	This watcher type is not meant for massive numbers of stat watchers,
		571	as even with OS-supported change notifications, this can be
		572	resource-intensive.
		573
		574	The "stat_ns" variant doesn't start (activate) the newly created
		575	watcher.
		576
		577	... = $w->stat
		578	This call is very similar to the perl "stat" built-in: It stats
		579	(using "lstat") the path specified in the watcher and sets perls
		580	stat cache (as well as EV's idea of the current stat values) to the
		581	values found.
		582
		583	In scalar context, a boolean is return indicating success or failure
		584	of the stat. In list context, the same 13-value list as with stat is
		585	returned (except that the blksize and blocks fields are not
		586	reliable).
		587
		588	In the case of an error, errno is set to "ENOENT" (regardless of the
		589	actual error value) and the "nlink" value is forced to zero (if the
		590	stat was successful then nlink is guaranteed to be non-zero).
		591
		592	See also the next two entries for more info.
		593
		594	... = $w->attr
		595	Just like "$w->stat", but without the initial stat'ing: this returns
		596	the values most recently detected by EV. See the next entry for more
		597	info.
		598
		599	... = $w->prev
		600	Just like "$w->stat", but without the initial stat'ing: this returns
		601	the previous set of values, before the change.
		602
		603	That is, when the watcher callback is invoked, "$w->prev" will be
		604	set to the values found before a change was detected, while
		605	"$w->attr" returns the values found leading to the change detection.
		606	The difference (if any) between "prev" and "attr" is what triggered
		607	the callback.
		608
		609	If you did something to the filesystem object and do not want to
		610	trigger yet another change, you can call "stat" to update EV's idea
		611	of what the current attributes are.
		612
		613	$w->set ($path, $interval)
		614	Reconfigures the watcher, see the constructor above for details. Can
		615	be called at any time.
		616
		617	$current_path = $w->path
		618	$old_path = $w->path ($new_path)
		619	Returns the previously set path and optionally set a new one.
		620
		621	$current_interval = $w->interval
		622	$old_interval = $w->interval ($new_interval)
		623	Returns the previously set interval and optionally set a new one.
		624	Can be used to query the actual interval used.
		625
		626	IDLE WATCHERS - when you've got nothing better to do...
380	$w = EV::idle $callback	627	$w = EV::idle $callback
381	$w = EV::idle_ns $callback	628	$w = EV::idle_ns $callback
		629	$w = $loop->idle ($callback)
		630	$w = $loop->idle_ns ($callback)
382	Call the callback when there are no pending io, timer/periodic,	631	Call the callback when there are no other pending watchers of the
383	signal or child events, i.e. when the process is idle.	632	same or higher priority (excluding check, prepare and other idle
		633	watchers of the same or lower priority, of course). They are called
		634	idle watchers because when the watcher is the highest priority
		635	pending event in the process, the process is considered to be idle
		636	at that priority.
		637
		638	If you want a watcher that is only ever called when no other
		639	events are outstanding you have to set the priority to "EV::MINPRI".
384		640
385	The process will not block as long as any idle watchers are active,	641	The process will not block as long as any idle watchers are active,
386	and they will be called repeatedly until stopped.	642	and they will be called repeatedly until stopped.
387		643
		644	For example, if you have idle watchers at priority 0 and 1, and an
		645	I/O watcher at priority 0, then the idle watcher at priority 1 and
		646	the I/O watcher will always run when ready. Only when the idle
		647	watcher at priority 1 is stopped and the I/O watcher at priority 0
		648	is not pending with the 0-priority idle watcher be invoked.
		649
388	The "idle_ns" variant doesn't start (activate) the newly created	650	The "idle_ns" variant doesn't start (activate) the newly created
389	watcher.	651	watcher.
390		652
		653	PREPARE WATCHERS - customise your event loop!
391	$w = EV::prepare $callback	654	$w = EV::prepare $callback
392	$w = EV::prepare_ns $callback	655	$w = EV::prepare_ns $callback
		656	$w = $loop->prepare ($callback)
		657	$w = $loop->prepare_ns ($callback)
393	Call the callback just before the process would block. You can still	658	Call the callback just before the process would block. You can still
394	create/modify any watchers at this point.	659	create/modify any watchers at this point.
395		660
396	See the EV::check watcher, below, for explanations and an example.	661	See the EV::check watcher, below, for explanations and an example.
397		662
398	The "prepare_ns" variant doesn't start (activate) the newly created	663	The "prepare_ns" variant doesn't start (activate) the newly created
399	watcher.	664	watcher.
400		665
		666	CHECK WATCHERS - customise your event loop even more!
401	$w = EV::check $callback	667	$w = EV::check $callback
402	$w = EV::check_ns $callback	668	$w = EV::check_ns $callback
		669	$w = $loop->check ($callback)
		670	$w = $loop->check_ns ($callback)
403	Call the callback just after the process wakes up again (after it	671	Call the callback just after the process wakes up again (after it
404	has gathered events), but before any other callbacks have been	672	has gathered events), but before any other callbacks have been
405	invoked.	673	invoked.
406		674
407	This is used to integrate other event-based software into the EV	675	This is used to integrate other event-based software into the EV
…		…
416	# do nothing unless active	684	# do nothing unless active
417	$dispatcher->{_event_queue_h}	685	$dispatcher->{_event_queue_h}
418	or return;	686	or return;
419		687
420	# make the dispatcher handle any outstanding stuff	688	# make the dispatcher handle any outstanding stuff
		689	... not shown
421		690
422	# create an IO watcher for each and every socket	691	# create an I/O watcher for each and every socket
423	@snmp_watcher = (	692	@snmp_watcher = (
424	(map { EV::io $_, EV::READ, sub { } }	693	(map { EV::io $_, EV::READ, sub { } }
425	keys %{ $dispatcher->{_descriptors} }),	694	keys %{ $dispatcher->{_descriptors} }),
		695
		696	EV::timer +($event->[Net::SNMP::Dispatcher::_ACTIVE]
		697	? $event->[Net::SNMP::Dispatcher::_TIME] - EV::now : 0),
		698	0, sub { },
426	);	699	);
427
428	# if there are any timeouts, also create a timer
429	push @snmp_watcher, EV::timer $event->[Net::SNMP::Dispatcher::_TIME] - EV::now, 0, sub { }
430	if $event->[Net::SNMP::Dispatcher::_ACTIVE];
431	};	700	};
432		701
433	The callbacks are irrelevant, the only purpose of those watchers is	702	The callbacks are irrelevant (and are not even being called), the
434	to wake up the process as soon as one of those events occurs (socket	703	only purpose of those watchers is to wake up the process as soon as
435	readable, or timer timed out). The corresponding EV::check watcher	704	one of those events occurs (socket readable, or timer timed out).
436	will then clean up:	705	The corresponding EV::check watcher will then clean up:
437		706
438	our $snmp_check = EV::check sub {	707	our $snmp_check = EV::check sub {
439	# destroy all watchers	708	# destroy all watchers
440	@snmp_watcher = ();	709	@snmp_watcher = ();
441		710
442	# make the dispatcher handle any new stuff	711	# make the dispatcher handle any new stuff
		712	... not shown
443	};	713	};
444		714
445	The callbacks of the created watchers will not be called as the	715	The callbacks of the created watchers will not be called as the
446	watchers are destroyed before this cna happen (remember EV::check	716	watchers are destroyed before this cna happen (remember EV::check
447	gets called first).	717	gets called first).
448		718
449	The "check_ns" variant doesn't start (activate) the newly created	719	The "check_ns" variant doesn't start (activate) the newly created
450	watcher.	720	watcher.
451		721
		722	FORK WATCHERS - the audacity to resume the event loop after a fork
		723	Fork watchers are called when a "fork ()" was detected. The invocation
		724	is done before the event loop blocks next and before "check" watchers
		725	are being called, and only in the child after the fork.
		726
		727	$w = EV::fork $callback
		728	$w = EV::fork_ns $callback
		729	$w = $loop->fork ($callback)
		730	$w = $loop->fork_ns ($callback)
		731	Call the callback before the event loop is resumed in the child
		732	process after a fork.
		733
		734	The "fork_ns" variant doesn't start (activate) the newly created
		735	watcher.
		736
		737	EMBED WATCHERS - when one backend isn't enough...
		738	This is a rather advanced watcher type that lets you embed one event
		739	loop into another (currently only IO events are supported in the
		740	embedded loop, other types of watchers might be handled in a delayed or
		741	incorrect fashion and must not be used).
		742
		743	See the libev documentation at
		744	<http://pod.tst.eu/http://cvs.schmorp.de/libev/ev.pod#code_ev_embed_code
		745	_when_one_backend_> for more details.
		746
		747	In short, this watcher is most useful on BSD systems without working
		748	kqueue to still be able to handle a large number of sockets:
		749
		750	my $socket_loop;
		751
		752	# check wether we use SELECT or POLL _and_ KQUEUE is supported
		753	if (
		754	(EV::backend & (EV::BACKEND_POLL \| EV::BACKEND_SELECT))
		755	&& (EV::supported_backends & EV::embeddable_backends & EV::BACKEND_KQUEUE)
		756	) {
		757	# use kqueue for sockets
		758	$socket_loop = new EV::Loop EV::BACKEND_KQUEUE \| EV::FLAG_NOENV;
		759	}
		760
		761	# use the default loop otherwise
		762	$socket_loop \|\|= EV::default_loop;
		763
		764	$w = EV::embed $otherloop, $callback
		765	$w = EV::embed_ns $otherloop, $callback
		766	$w = $loop->embed ($otherloop, $callback)
		767	$w = $loop->embed_ns ($otherloop, $callback)
		768	Call the callback when the embedded event loop ($otherloop) has any
		769	I/O activity. The $callback should alwas be specified as "undef" in
		770	this version of EV, which means the embedded event loop will be
		771	managed automatically.
		772
		773	The "embed_ns" variant doesn't start (activate) the newly created
		774	watcher.
		775
		776	PERL SIGNALS
		777	While Perl signal handling (%SIG) is not affected by EV, the behaviour
		778	with EV is as the same as any other C library: Perl-signals will only be
		779	handled when Perl runs, which means your signal handler might be invoked
		780	only the next time an event callback is invoked.
		781
		782	The solution is to use EV signal watchers (see "EV::signal"), which will
		783	ensure proper operations with regards to other event watchers.
		784
		785	If you cannot do this for whatever reason, you can also force a watcher
		786	to be called on every event loop iteration by installing a "EV::check"
		787	watcher:
		788
		789	my $async_check = EV::check sub { };
		790
		791	This ensures that perl gets into control for a short time to handle any
		792	pending signals, and also ensures (slightly) slower overall operation.
		793
452	THREADS	794	THREADS
453	Threads are not supported by this in any way. Perl pseudo-threads is	795	Threads are not supported by this module in any way. Perl pseudo-threads
454	evil stuff and must die.	796	is evil stuff and must die. As soon as Perl gains real threads I will
		797	work on thread support for it.
		798
		799	FORK
		800	Most of the "improved" event delivering mechanisms of modern operating
		801	systems have quite a few problems with fork(2) (to put it bluntly: it is
		802	not supported and usually destructive). Libev makes it possible to work
		803	around this by having a function that recreates the kernel state after
		804	fork in the child.
		805
		806	On non-win32 platforms, this module requires the pthread_atfork
		807	functionality to do this automatically for you. This function is quite
		808	buggy on most BSDs, though, so YMMV. The overhead for this is quite
		809	negligible, because everything the function currently does is set a flag
		810	that is checked only when the event loop gets used the next time, so
		811	when you do fork but not use EV, the overhead is minimal.
		812
		813	On win32, there is no notion of fork so all this doesn't apply, of
		814	course.
455		815
456	SEE ALSO	816	SEE ALSO
457	L<EV::DNS>, L<EV::AnyEvent>.	817	EV::ADNS (asynchronous DNS), Glib::EV (makes Glib/Gtk2 use EV as event
		818	loop), EV::Glib (embed Glib into EV), Coro::EV (efficient coroutines
		819	with EV), Net::SNMP::EV (asynchronous SNMP).
458		820
459	AUTHOR	821	AUTHOR
460	Marc Lehmann <schmorp@schmorp.de>	822	Marc Lehmann <schmorp@schmorp.de>
461	http://home.schmorp.de/	823	http://home.schmorp.de/
462		824

Diff Legend

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

Comparing EV/README (file contents): Revision 1.8 by root, Thu Nov 8 17:02:10 2007 UTC vs. Revision 1.21 by root, Sat Dec 22 16:48:33 2007 UTC

Diff Legend

Comparing EV/README (file contents):
Revision 1.8 by root, Thu Nov 8 17:02:10 2007 UTC vs.
Revision 1.21 by root, Sat Dec 22 16:48:33 2007 UTC