[ViewVC] Diff of: cvs/libev/ev.3

Comparing libev/ev.3 (file contents):
Revision 1.5 by root, Fri Nov 23 04:36:03 2007 UTC vs.
Revision 1.13 by root, Sat Nov 24 09:48:38 2007 UTC

…		…
127	.\}	127	.\}
128	.rm #[ #] #H #V #F C	128	.rm #[ #] #H #V #F C
129	.\" ========================================================================	129	.\" ========================================================================
130	.\"	130	.\"
131	.IX Title ""<STANDARD INPUT>" 1"	131	.IX Title ""<STANDARD INPUT>" 1"
132	.TH "<STANDARD INPUT>" 1 "2007-11-23" "perl v5.8.8" "User Contributed Perl Documentation"	132	.TH "<STANDARD INPUT>" 1 "2007-11-24" "perl v5.8.8" "User Contributed Perl Documentation"
133	.SH "NAME"	133	.SH "NAME"
134	libev \- a high performance full\-featured event loop written in C	134	libev \- a high performance full\-featured event loop written in C
135	.SH "SYNOPSIS"	135	.SH "SYNOPSIS"
136	.IX Header "SYNOPSIS"	136	.IX Header "SYNOPSIS"
137	.Vb 1	137	.Vb 1
…		…
173	.IX Header "TIME REPRESENTATION"	173	.IX Header "TIME REPRESENTATION"
174	Libev represents time as a single floating point number, representing the	174	Libev represents time as a single floating point number, representing the
175	(fractional) number of seconds since the (\s-1POSIX\s0) epoch (somewhere near	175	(fractional) number of seconds since the (\s-1POSIX\s0) epoch (somewhere near
176	the beginning of 1970, details are complicated, don't ask). This type is	176	the beginning of 1970, details are complicated, don't ask). This type is
177	called \f(CW\(C`ev_tstamp\(C'\fR, which is what you should use too. It usually aliases	177	called \f(CW\(C`ev_tstamp\(C'\fR, which is what you should use too. It usually aliases
178	to the double type in C.	178	to the \f(CW\(C`double\(C'\fR type in C, and when you need to do any calculations on
		179	it, you should treat it as such.
179	.SH "GLOBAL FUNCTIONS"	180	.SH "GLOBAL FUNCTIONS"
180	.IX Header "GLOBAL FUNCTIONS"	181	.IX Header "GLOBAL FUNCTIONS"
181	These functions can be called anytime, even before initialising the	182	These functions can be called anytime, even before initialising the
182	library in any way.	183	library in any way.
183	.IP "ev_tstamp ev_time ()" 4	184	.IP "ev_tstamp ev_time ()" 4
…		…
199	.Sp	200	.Sp
200	Usually, it's a good idea to terminate if the major versions mismatch,	201	Usually, it's a good idea to terminate if the major versions mismatch,
201	as this indicates an incompatible change. Minor versions are usually	202	as this indicates an incompatible change. Minor versions are usually
202	compatible to older versions, so a larger minor version alone is usually	203	compatible to older versions, so a larger minor version alone is usually
203	not a problem.	204	not a problem.
		205	.Sp
		206	Example: make sure we haven't accidentally been linked against the wrong
		207	version:
		208	.Sp
		209	.Vb 3
		210	\& assert (("libev version mismatch",
		211	\& ev_version_major () == EV_VERSION_MAJOR
		212	\& && ev_version_minor () >= EV_VERSION_MINOR));
		213	.Ve
		214	.IP "unsigned int ev_supported_backends ()" 4
		215	.IX Item "unsigned int ev_supported_backends ()"
		216	Return the set of all backends (i.e. their corresponding \f(CW\(C`EV_BACKEND_\*(C'\fR
		217	value) compiled into this binary of libev (independent of their
		218	availability on the system you are running on). See \f(CW\(C`ev_default_loop\(C'\fR for
		219	a description of the set values.
		220	.Sp
		221	Example: make sure we have the epoll method, because yeah this is cool and
		222	a must have and can we have a torrent of it please!!!11
		223	.Sp
		224	.Vb 2
		225	\& assert (("sorry, no epoll, no sex",
		226	\& ev_supported_backends () & EVBACKEND_EPOLL));
		227	.Ve
		228	.IP "unsigned int ev_recommended_backends ()" 4
		229	.IX Item "unsigned int ev_recommended_backends ()"
		230	Return the set of all backends compiled into this binary of libev and also
		231	recommended for this platform. This set is often smaller than the one
		232	returned by \f(CW\(C`ev_supported_backends\(C'\fR, as for example kqueue is broken on
		233	most BSDs and will not be autodetected unless you explicitly request it
		234	(assuming you know what you are doing). This is the set of backends that
		235	libev will probe for if you specify no backends explicitly.
		236	.IP "unsigned int ev_embeddable_backends ()" 4
		237	.IX Item "unsigned int ev_embeddable_backends ()"
		238	Returns the set of backends that are embeddable in other event loops. This
		239	is the theoretical, all\-platform, value. To find which backends
		240	might be supported on the current system, you would need to look at
		241	\&\f(CW\(C`ev_embeddable_backends () & ev_supported_backends ()\(C'\fR, likewise for
		242	recommended ones.
		243	.Sp
		244	See the description of \f(CW\(C`ev_embed\(C'\fR watchers for more info.
204	.IP "ev_set_allocator (void (cb)(void *ptr, long size))" 4	245	.IP "ev_set_allocator (void (cb)(void *ptr, long size))" 4
205	.IX Item "ev_set_allocator (void (cb)(void *ptr, long size))"	246	.IX Item "ev_set_allocator (void (cb)(void *ptr, long size))"
206	Sets the allocation function to use (the prototype is similar to the	247	Sets the allocation function to use (the prototype is similar to the
207	realloc C function, the semantics are identical). It is used to allocate	248	realloc C function, the semantics are identical). It is used to allocate
208	and free memory (no surprises here). If it returns zero when memory	249	and free memory (no surprises here). If it returns zero when memory
…		…
210	destructive action. The default is your system realloc function.	251	destructive action. The default is your system realloc function.
211	.Sp	252	.Sp
212	You could override this function in high-availability programs to, say,	253	You could override this function in high-availability programs to, say,
213	free some memory if it cannot allocate memory, to use a special allocator,	254	free some memory if it cannot allocate memory, to use a special allocator,
214	or even to sleep a while and retry until some memory is available.	255	or even to sleep a while and retry until some memory is available.
		256	.Sp
		257	Example: replace the libev allocator with one that waits a bit and then
		258	retries: better than mine).
		259	.Sp
		260	.Vb 6
		261	\& static void *
		262	\& persistent_realloc (void *ptr, long size)
		263	\& {
		264	\& for (;;)
		265	\& {
		266	\& void *newptr = realloc (ptr, size);
		267	.Ve
		268	.Sp
		269	.Vb 2
		270	\& if (newptr)
		271	\& return newptr;
		272	.Ve
		273	.Sp
		274	.Vb 3
		275	\& sleep (60);
		276	\& }
		277	\& }
		278	.Ve
		279	.Sp
		280	.Vb 2
		281	\& ...
		282	\& ev_set_allocator (persistent_realloc);
		283	.Ve
215	.IP "ev_set_syserr_cb (void (cb)(const char msg));" 4	284	.IP "ev_set_syserr_cb (void (cb)(const char msg));" 4
216	.IX Item "ev_set_syserr_cb (void (cb)(const char msg));"	285	.IX Item "ev_set_syserr_cb (void (cb)(const char msg));"
217	Set the callback function to call on a retryable syscall error (such	286	Set the callback function to call on a retryable syscall error (such
218	as failed select, poll, epoll_wait). The message is a printable string	287	as failed select, poll, epoll_wait). The message is a printable string
219	indicating the system call or subsystem causing the problem. If this	288	indicating the system call or subsystem causing the problem. If this
220	callback is set, then libev will expect it to remedy the sitution, no	289	callback is set, then libev will expect it to remedy the sitution, no
221	matter what, when it returns. That is, libev will generally retry the	290	matter what, when it returns. That is, libev will generally retry the
222	requested operation, or, if the condition doesn't go away, do bad stuff	291	requested operation, or, if the condition doesn't go away, do bad stuff
223	(such as abort).	292	(such as abort).
		293	.Sp
		294	Example: do the same thing as libev does internally:
		295	.Sp
		296	.Vb 6
		297	\& static void
		298	\& fatal_error (const char *msg)
		299	\& {
		300	\& perror (msg);
		301	\& abort ();
		302	\& }
		303	.Ve
		304	.Sp
		305	.Vb 2
		306	\& ...
		307	\& ev_set_syserr_cb (fatal_error);
		308	.Ve
224	.SH "FUNCTIONS CONTROLLING THE EVENT LOOP"	309	.SH "FUNCTIONS CONTROLLING THE EVENT LOOP"
225	.IX Header "FUNCTIONS CONTROLLING THE EVENT LOOP"	310	.IX Header "FUNCTIONS CONTROLLING THE EVENT LOOP"
226	An event loop is described by a \f(CW\(C`struct ev_loop \*(C'\fR. The library knows two	311	An event loop is described by a \f(CW\(C`struct ev_loop \*(C'\fR. The library knows two
227	types of such loops, the \fIdefault\fR loop, which supports signals and child	312	types of such loops, the \fIdefault\fR loop, which supports signals and child
228	events, and dynamically created loops which do not.	313	events, and dynamically created loops which do not.
…		…
236	.IP "struct ev_loop *ev_default_loop (unsigned int flags)" 4	321	.IP "struct ev_loop *ev_default_loop (unsigned int flags)" 4
237	.IX Item "struct ev_loop *ev_default_loop (unsigned int flags)"	322	.IX Item "struct ev_loop *ev_default_loop (unsigned int flags)"
238	This will initialise the default event loop if it hasn't been initialised	323	This will initialise the default event loop if it hasn't been initialised
239	yet and return it. If the default loop could not be initialised, returns	324	yet and return it. If the default loop could not be initialised, returns
240	false. If it already was initialised it simply returns it (and ignores the	325	false. If it already was initialised it simply returns it (and ignores the
241	flags).	326	flags. If that is troubling you, check \f(CW\(C`ev_backend ()\(C'\fR afterwards).
242	.Sp	327	.Sp
243	If you don't know what event loop to use, use the one returned from this	328	If you don't know what event loop to use, use the one returned from this
244	function.	329	function.
245	.Sp	330	.Sp
246	The flags argument can be used to specify special behaviour or specific	331	The flags argument can be used to specify special behaviour or specific
247	backends to use, and is usually specified as 0 (or \s-1EVFLAG_AUTO\s0).	332	backends to use, and is usually specified as \f(CW0\fR (or \f(CW\(C`EVFLAG_AUTO\(C'\fR).
248	.Sp	333	.Sp
249	It supports the following flags:	334	The following flags are supported:
250	.RS 4	335	.RS 4
251	.ie n .IP """EVFLAG_AUTO""" 4	336	.ie n .IP """EVFLAG_AUTO""" 4
252	.el .IP "\f(CWEVFLAG_AUTO\fR" 4	337	.el .IP "\f(CWEVFLAG_AUTO\fR" 4
253	.IX Item "EVFLAG_AUTO"	338	.IX Item "EVFLAG_AUTO"
254	The default flags value. Use this if you have no clue (it's the right	339	The default flags value. Use this if you have no clue (it's the right
…		…
260	or setgid) then libev will \fInot\fR look at the environment variable	345	or setgid) then libev will \fInot\fR look at the environment variable
261	\&\f(CW\(C`LIBEV_FLAGS\(C'\fR. Otherwise (the default), this environment variable will	346	\&\f(CW\(C`LIBEV_FLAGS\(C'\fR. Otherwise (the default), this environment variable will
262	override the flags completely if it is found in the environment. This is	347	override the flags completely if it is found in the environment. This is
263	useful to try out specific backends to test their performance, or to work	348	useful to try out specific backends to test their performance, or to work
264	around bugs.	349	around bugs.
265	.ie n .IP """EVMETHOD_SELECT"" (value 1, portable select backend)" 4	350	.ie n .IP """EVBACKEND_SELECT"" (value 1, portable select backend)" 4
266	.el .IP "\f(CWEVMETHOD_SELECT\fR (value 1, portable select backend)" 4	351	.el .IP "\f(CWEVBACKEND_SELECT\fR (value 1, portable select backend)" 4
267	.IX Item "EVMETHOD_SELECT (value 1, portable select backend)"	352	.IX Item "EVBACKEND_SELECT (value 1, portable select backend)"
268	This is your standard \fIselect\fR\\|(2) backend. Not \fIcompletely\fR standard, as	353	This is your standard \fIselect\fR\\|(2) backend. Not \fIcompletely\fR standard, as
269	libev tries to roll its own fd_set with no limits on the number of fds,	354	libev tries to roll its own fd_set with no limits on the number of fds,
270	but if that fails, expect a fairly low limit on the number of fds when	355	but if that fails, expect a fairly low limit on the number of fds when
271	using this backend. It doesn't scale too well (O(highest_fd)), but its usually	356	using this backend. It doesn't scale too well (O(highest_fd)), but its usually
272	the fastest backend for a low number of fds.	357	the fastest backend for a low number of fds.
273	.ie n .IP """EVMETHOD_POLL"" (value 2, poll backend, available everywhere except on windows)" 4	358	.ie n .IP """EVBACKEND_POLL"" (value 2, poll backend, available everywhere except on windows)" 4
274	.el .IP "\f(CWEVMETHOD_POLL\fR (value 2, poll backend, available everywhere except on windows)" 4	359	.el .IP "\f(CWEVBACKEND_POLL\fR (value 2, poll backend, available everywhere except on windows)" 4
275	.IX Item "EVMETHOD_POLL (value 2, poll backend, available everywhere except on windows)"	360	.IX Item "EVBACKEND_POLL (value 2, poll backend, available everywhere except on windows)"
276	And this is your standard \fIpoll\fR\\|(2) backend. It's more complicated than	361	And this is your standard \fIpoll\fR\\|(2) backend. It's more complicated than
277	select, but handles sparse fds better and has no artificial limit on the	362	select, but handles sparse fds better and has no artificial limit on the
278	number of fds you can use (except it will slow down considerably with a	363	number of fds you can use (except it will slow down considerably with a
279	lot of inactive fds). It scales similarly to select, i.e. O(total_fds).	364	lot of inactive fds). It scales similarly to select, i.e. O(total_fds).
280	.ie n .IP """EVMETHOD_EPOLL"" (value 4, Linux)" 4	365	.ie n .IP """EVBACKEND_EPOLL"" (value 4, Linux)" 4
281	.el .IP "\f(CWEVMETHOD_EPOLL\fR (value 4, Linux)" 4	366	.el .IP "\f(CWEVBACKEND_EPOLL\fR (value 4, Linux)" 4
282	.IX Item "EVMETHOD_EPOLL (value 4, Linux)"	367	.IX Item "EVBACKEND_EPOLL (value 4, Linux)"
283	For few fds, this backend is a bit little slower than poll and select,	368	For few fds, this backend is a bit little slower than poll and select,
284	but it scales phenomenally better. While poll and select usually scale like	369	but it scales phenomenally better. While poll and select usually scale like
285	O(total_fds) where n is the total number of fds (or the highest fd), epoll scales	370	O(total_fds) where n is the total number of fds (or the highest fd), epoll scales
286	either O(1) or O(active_fds).	371	either O(1) or O(active_fds).
287	.Sp	372	.Sp
288	While stopping and starting an I/O watcher in the same iteration will	373	While stopping and starting an I/O watcher in the same iteration will
289	result in some caching, there is still a syscall per such incident	374	result in some caching, there is still a syscall per such incident
290	(because the fd could point to a different file description now), so its	375	(because the fd could point to a different file description now), so its
291	best to avoid that. Also, \fIdup()\fRed file descriptors might not work very	376	best to avoid that. Also, \fIdup()\fRed file descriptors might not work very
292	well if you register events for both fds.	377	well if you register events for both fds.
		378	.Sp
		379	Please note that epoll sometimes generates spurious notifications, so you
		380	need to use non-blocking I/O or other means to avoid blocking when no data
		381	(or space) is available.
293	.ie n .IP """EVMETHOD_KQUEUE"" (value 8, most \s-1BSD\s0 clones)" 4	382	.ie n .IP """EVBACKEND_KQUEUE"" (value 8, most \s-1BSD\s0 clones)" 4
294	.el .IP "\f(CWEVMETHOD_KQUEUE\fR (value 8, most \s-1BSD\s0 clones)" 4	383	.el .IP "\f(CWEVBACKEND_KQUEUE\fR (value 8, most \s-1BSD\s0 clones)" 4
295	.IX Item "EVMETHOD_KQUEUE (value 8, most BSD clones)"	384	.IX Item "EVBACKEND_KQUEUE (value 8, most BSD clones)"
296	Kqueue deserves special mention, as at the time of this writing, it	385	Kqueue deserves special mention, as at the time of this writing, it
297	was broken on all BSDs except NetBSD (usually it doesn't work with	386	was broken on all BSDs except NetBSD (usually it doesn't work with
298	anything but sockets and pipes, except on Darwin, where of course its	387	anything but sockets and pipes, except on Darwin, where of course its
299	completely useless). For this reason its not being \(L"autodetected\(R" unless	388	completely useless). For this reason its not being \(L"autodetected\(R"
300	you explicitly specify the flags (i.e. you don't use \s-1EVFLAG_AUTO\s0).	389	unless you explicitly specify it explicitly in the flags (i.e. using
		390	\&\f(CW\(C`EVBACKEND_KQUEUE\(C'\fR).
301	.Sp	391	.Sp
302	It scales in the same way as the epoll backend, but the interface to the	392	It scales in the same way as the epoll backend, but the interface to the
303	kernel is more efficient (which says nothing about its actual speed, of	393	kernel is more efficient (which says nothing about its actual speed, of
304	course). While starting and stopping an I/O watcher does not cause an	394	course). While starting and stopping an I/O watcher does not cause an
305	extra syscall as with epoll, it still adds up to four event changes per	395	extra syscall as with epoll, it still adds up to four event changes per
306	incident, so its best to avoid that.	396	incident, so its best to avoid that.
307	.ie n .IP """EVMETHOD_DEVPOLL"" (value 16, Solaris 8)" 4	397	.ie n .IP """EVBACKEND_DEVPOLL"" (value 16, Solaris 8)" 4
308	.el .IP "\f(CWEVMETHOD_DEVPOLL\fR (value 16, Solaris 8)" 4	398	.el .IP "\f(CWEVBACKEND_DEVPOLL\fR (value 16, Solaris 8)" 4
309	.IX Item "EVMETHOD_DEVPOLL (value 16, Solaris 8)"	399	.IX Item "EVBACKEND_DEVPOLL (value 16, Solaris 8)"
310	This is not implemented yet (and might never be).	400	This is not implemented yet (and might never be).
311	.ie n .IP """EVMETHOD_PORT"" (value 32, Solaris 10)" 4	401	.ie n .IP """EVBACKEND_PORT"" (value 32, Solaris 10)" 4
312	.el .IP "\f(CWEVMETHOD_PORT\fR (value 32, Solaris 10)" 4	402	.el .IP "\f(CWEVBACKEND_PORT\fR (value 32, Solaris 10)" 4
313	.IX Item "EVMETHOD_PORT (value 32, Solaris 10)"	403	.IX Item "EVBACKEND_PORT (value 32, Solaris 10)"
314	This uses the Solaris 10 port mechanism. As with everything on Solaris,	404	This uses the Solaris 10 port mechanism. As with everything on Solaris,
315	it's really slow, but it still scales very well (O(active_fds)).	405	it's really slow, but it still scales very well (O(active_fds)).
		406	.Sp
		407	Please note that solaris ports can result in a lot of spurious
		408	notifications, so you need to use non-blocking I/O or other means to avoid
		409	blocking when no data (or space) is available.
316	.ie n .IP """EVMETHOD_ALL""" 4	410	.ie n .IP """EVBACKEND_ALL""" 4
317	.el .IP "\f(CWEVMETHOD_ALL\fR" 4	411	.el .IP "\f(CWEVBACKEND_ALL\fR" 4
318	.IX Item "EVMETHOD_ALL"	412	.IX Item "EVBACKEND_ALL"
319	Try all backends (even potentially broken ones that wouldn't be tried	413	Try all backends (even potentially broken ones that wouldn't be tried
320	with \f(CW\(C`EVFLAG_AUTO\(C'\fR). Since this is a mask, you can do stuff such as	414	with \f(CW\(C`EVFLAG_AUTO\(C'\fR). Since this is a mask, you can do stuff such as
321	\&\f(CW\(C`EVMETHOD_ALL & ~EVMETHOD_KQUEUE\(C'\fR.	415	\&\f(CW\(C`EVBACKEND_ALL & ~EVBACKEND_KQUEUE\(C'\fR.
322	.RE	416	.RE
323	.RS 4	417	.RS 4
324	.Sp	418	.Sp
325	If one or more of these are ored into the flags value, then only these	419	If one or more of these are ored into the flags value, then only these
326	backends will be tried (in the reverse order as given here). If none are	420	backends will be tried (in the reverse order as given here). If none are
327	specified, most compiled-in backend will be tried, usually in reverse	421	specified, most compiled-in backend will be tried, usually in reverse
328	order of their flag values :)	422	order of their flag values :)
		423	.Sp
		424	The most typical usage is like this:
		425	.Sp
		426	.Vb 2
		427	\& if (!ev_default_loop (0))
		428	\& fatal ("could not initialise libev, bad $LIBEV_FLAGS in environment?");
		429	.Ve
		430	.Sp
		431	Restrict libev to the select and poll backends, and do not allow
		432	environment settings to be taken into account:
		433	.Sp
		434	.Vb 1
		435	\& ev_default_loop (EVBACKEND_POLL \| EVBACKEND_SELECT \| EVFLAG_NOENV);
		436	.Ve
		437	.Sp
		438	Use whatever libev has to offer, but make sure that kqueue is used if
		439	available (warning, breaks stuff, best use only with your own private
		440	event loop and only if you know the \s-1OS\s0 supports your types of fds):
		441	.Sp
		442	.Vb 1
		443	\& ev_default_loop (ev_recommended_backends () \| EVBACKEND_KQUEUE);
		444	.Ve
329	.RE	445	.RE
330	.IP "struct ev_loop *ev_loop_new (unsigned int flags)" 4	446	.IP "struct ev_loop *ev_loop_new (unsigned int flags)" 4
331	.IX Item "struct ev_loop *ev_loop_new (unsigned int flags)"	447	.IX Item "struct ev_loop *ev_loop_new (unsigned int flags)"
332	Similar to \f(CW\(C`ev_default_loop\(C'\fR, but always creates a new event loop that is	448	Similar to \f(CW\(C`ev_default_loop\(C'\fR, but always creates a new event loop that is
333	always distinct from the default loop. Unlike the default loop, it cannot	449	always distinct from the default loop. Unlike the default loop, it cannot
334	handle signal and child watchers, and attempts to do so will be greeted by	450	handle signal and child watchers, and attempts to do so will be greeted by
335	undefined behaviour (or a failed assertion if assertions are enabled).	451	undefined behaviour (or a failed assertion if assertions are enabled).
		452	.Sp
		453	Example: try to create a event loop that uses epoll and nothing else.
		454	.Sp
		455	.Vb 3
		456	\& struct ev_loop *epoller = ev_loop_new (EVBACKEND_EPOLL \| EVFLAG_NOENV);
		457	\& if (!epoller)
		458	\& fatal ("no epoll found here, maybe it hides under your chair");
		459	.Ve
336	.IP "ev_default_destroy ()" 4	460	.IP "ev_default_destroy ()" 4
337	.IX Item "ev_default_destroy ()"	461	.IX Item "ev_default_destroy ()"
338	Destroys the default loop again (frees all memory and kernel state	462	Destroys the default loop again (frees all memory and kernel state
339	etc.). This stops all registered event watchers (by not touching them in	463	etc.). None of the active event watchers will be stopped in the normal
340	any way whatsoever, although you cannot rely on this :).	464	sense, so e.g. \f(CW\(C`ev_is_active\(C'\fR might still return true. It is your
		465	responsibility to either stop all watchers cleanly yoursef \fIbefore\fR
		466	calling this function, or cope with the fact afterwards (which is usually
		467	the easiest thing, youc na just ignore the watchers and/or \f(CW\(C`free ()\(C'\fR them
		468	for example).
341	.IP "ev_loop_destroy (loop)" 4	469	.IP "ev_loop_destroy (loop)" 4
342	.IX Item "ev_loop_destroy (loop)"	470	.IX Item "ev_loop_destroy (loop)"
343	Like \f(CW\(C`ev_default_destroy\(C'\fR, but destroys an event loop created by an	471	Like \f(CW\(C`ev_default_destroy\(C'\fR, but destroys an event loop created by an
344	earlier call to \f(CW\(C`ev_loop_new\(C'\fR.	472	earlier call to \f(CW\(C`ev_loop_new\(C'\fR.
345	.IP "ev_default_fork ()" 4	473	.IP "ev_default_fork ()" 4
…		…
358	quite nicely into a call to \f(CW\(C`pthread_atfork\(C'\fR:	486	quite nicely into a call to \f(CW\(C`pthread_atfork\(C'\fR:
359	.Sp	487	.Sp
360	.Vb 1	488	.Vb 1
361	\& pthread_atfork (0, 0, ev_default_fork);	489	\& pthread_atfork (0, 0, ev_default_fork);
362	.Ve	490	.Ve
		491	.Sp
		492	At the moment, \f(CW\(C`EVBACKEND_SELECT\(C'\fR and \f(CW\(C`EVBACKEND_POLL\(C'\fR are safe to use
		493	without calling this function, so if you force one of those backends you
		494	do not need to care.
363	.IP "ev_loop_fork (loop)" 4	495	.IP "ev_loop_fork (loop)" 4
364	.IX Item "ev_loop_fork (loop)"	496	.IX Item "ev_loop_fork (loop)"
365	Like \f(CW\(C`ev_default_fork\(C'\fR, but acts on an event loop created by	497	Like \f(CW\(C`ev_default_fork\(C'\fR, but acts on an event loop created by
366	\&\f(CW\(C`ev_loop_new\(C'\fR. Yes, you have to call this on every allocated event loop	498	\&\f(CW\(C`ev_loop_new\(C'\fR. Yes, you have to call this on every allocated event loop
367	after fork, and how you do this is entirely your own problem.	499	after fork, and how you do this is entirely your own problem.
368	.IP "unsigned int ev_method (loop)" 4	500	.IP "unsigned int ev_backend (loop)" 4
369	.IX Item "unsigned int ev_method (loop)"	501	.IX Item "unsigned int ev_backend (loop)"
370	Returns one of the \f(CW\(C`EVMETHOD_\*(C'\fR flags indicating the event backend in	502	Returns one of the \f(CW\(C`EVBACKEND_\*(C'\fR flags indicating the event backend in
371	use.	503	use.
372	.IP "ev_tstamp ev_now (loop)" 4	504	.IP "ev_tstamp ev_now (loop)" 4
373	.IX Item "ev_tstamp ev_now (loop)"	505	.IX Item "ev_tstamp ev_now (loop)"
374	Returns the current \(L"event loop time\(R", which is the time the event loop	506	Returns the current \(L"event loop time\(R", which is the time the event loop
375	got events and started processing them. This timestamp does not change	507	received events and started processing them. This timestamp does not
376	as long as callbacks are being processed, and this is also the base time	508	change as long as callbacks are being processed, and this is also the base
377	used for relative timers. You can treat it as the timestamp of the event	509	time used for relative timers. You can treat it as the timestamp of the
378	occuring (or more correctly, the mainloop finding out about it).	510	event occuring (or more correctly, libev finding out about it).
379	.IP "ev_loop (loop, int flags)" 4	511	.IP "ev_loop (loop, int flags)" 4
380	.IX Item "ev_loop (loop, int flags)"	512	.IX Item "ev_loop (loop, int flags)"
381	Finally, this is it, the event handler. This function usually is called	513	Finally, this is it, the event handler. This function usually is called
382	after you initialised all your watchers and you want to start handling	514	after you initialised all your watchers and you want to start handling
383	events.	515	events.
384	.Sp	516	.Sp
385	If the flags argument is specified as 0, it will not return until either	517	If the flags argument is specified as \f(CW0\fR, it will not return until
386	no event watchers are active anymore or \f(CW\(C`ev_unloop\(C'\fR was called.	518	either no event watchers are active anymore or \f(CW\(C`ev_unloop\(C'\fR was called.
		519	.Sp
		520	Please note that an explicit \f(CW\(C`ev_unloop\(C'\fR is usually better than
		521	relying on all watchers to be stopped when deciding when a program has
		522	finished (especially in interactive programs), but having a program that
		523	automatically loops as long as it has to and no longer by virtue of
		524	relying on its watchers stopping correctly is a thing of beauty.
387	.Sp	525	.Sp
388	A flags value of \f(CW\(C`EVLOOP_NONBLOCK\(C'\fR will look for new events, will handle	526	A flags value of \f(CW\(C`EVLOOP_NONBLOCK\(C'\fR will look for new events, will handle
389	those events and any outstanding ones, but will not block your process in	527	those events and any outstanding ones, but will not block your process in
390	case there are no events and will return after one iteration of the loop.	528	case there are no events and will return after one iteration of the loop.
391	.Sp	529	.Sp
392	A flags value of \f(CW\(C`EVLOOP_ONESHOT\(C'\fR will look for new events (waiting if	530	A flags value of \f(CW\(C`EVLOOP_ONESHOT\(C'\fR will look for new events (waiting if
393	neccessary) and will handle those and any outstanding ones. It will block	531	neccessary) and will handle those and any outstanding ones. It will block
394	your process until at least one new event arrives, and will return after	532	your process until at least one new event arrives, and will return after
395	one iteration of the loop.	533	one iteration of the loop. This is useful if you are waiting for some
		534	external event in conjunction with something not expressible using other
		535	libev watchers. However, a pair of \f(CW\(C`ev_prepare\(C'\fR/\f(CW\(C`ev_check\(C'\fR watchers is
		536	usually a better approach for this kind of thing.
396	.Sp	537	.Sp
397	This flags value could be used to implement alternative looping
398	constructs, but the \f(CW\(C`prepare\(C'\fR and \f(CW\(C`check\(C'\fR watchers provide a better and
399	more generic mechanism.
400	.Sp
401	Here are the gory details of what ev_loop does:	538	Here are the gory details of what \f(CW\(C`ev_loop\(C'\fR does:
402	.Sp	539	.Sp
403	.Vb 15	540	.Vb 18
404	\& 1. If there are no active watchers (reference count is zero), return.	541	\& * If there are no active watchers (reference count is zero), return.
405	\& 2. Queue and immediately call all prepare watchers.	542	\& - Queue prepare watchers and then call all outstanding watchers.
406	\& 3. If we have been forked, recreate the kernel state.	543	\& - If we have been forked, recreate the kernel state.
407	\& 4. Update the kernel state with all outstanding changes.	544	\& - Update the kernel state with all outstanding changes.
408	\& 5. Update the "event loop time".	545	\& - Update the "event loop time".
409	\& 6. Calculate for how long to block.	546	\& - Calculate for how long to block.
410	\& 7. Block the process, waiting for events.	547	\& - Block the process, waiting for any events.
		548	\& - Queue all outstanding I/O (fd) events.
411	\& 8. Update the "event loop time" and do time jump handling.	549	\& - Update the "event loop time" and do time jump handling.
412	\& 9. Queue all outstanding timers.	550	\& - Queue all outstanding timers.
413	\& 10. Queue all outstanding periodics.	551	\& - Queue all outstanding periodics.
414	\& 11. If no events are pending now, queue all idle watchers.	552	\& - If no events are pending now, queue all idle watchers.
415	\& 12. Queue all check watchers.	553	\& - Queue all check watchers.
416	\& 13. Call all queued watchers in reverse order (i.e. check watchers first).	554	\& - Call all queued watchers in reverse order (i.e. check watchers first).
		555	\& Signals and child watchers are implemented as I/O watchers, and will
		556	\& be handled here by queueing them when their watcher gets executed.
417	\& 14. If ev_unloop has been called or EVLOOP_ONESHOT or EVLOOP_NONBLOCK	557	\& - If ev_unloop has been called or EVLOOP_ONESHOT or EVLOOP_NONBLOCK
418	\& was used, return, otherwise continue with step #1.	558	\& were used, return, otherwise continue with step *.
		559	.Ve
		560	.Sp
		561	Example: queue some jobs and then loop until no events are outsanding
		562	anymore.
		563	.Sp
		564	.Vb 4
		565	\& ... queue jobs here, make sure they register event watchers as long
		566	\& ... as they still have work to do (even an idle watcher will do..)
		567	\& ev_loop (my_loop, 0);
		568	\& ... jobs done. yeah!
419	.Ve	569	.Ve
420	.IP "ev_unloop (loop, how)" 4	570	.IP "ev_unloop (loop, how)" 4
421	.IX Item "ev_unloop (loop, how)"	571	.IX Item "ev_unloop (loop, how)"
422	Can be used to make a call to \f(CW\(C`ev_loop\(C'\fR return early (but only after it	572	Can be used to make a call to \f(CW\(C`ev_loop\(C'\fR return early (but only after it
423	has processed all outstanding events). The \f(CW\(C`how\(C'\fR argument must be either	573	has processed all outstanding events). The \f(CW\(C`how\(C'\fR argument must be either
…		…
437	example, libev itself uses this for its internal signal pipe: It is not	587	example, libev itself uses this for its internal signal pipe: It is not
438	visible to the libev user and should not keep \f(CW\(C`ev_loop\(C'\fR from exiting if	588	visible to the libev user and should not keep \f(CW\(C`ev_loop\(C'\fR from exiting if
439	no event watchers registered by it are active. It is also an excellent	589	no event watchers registered by it are active. It is also an excellent
440	way to do this for generic recurring timers or from within third-party	590	way to do this for generic recurring timers or from within third-party
441	libraries. Just remember to \fIunref after start\fR and \fIref before stop\fR.	591	libraries. Just remember to \fIunref after start\fR and \fIref before stop\fR.
		592	.Sp
		593	Example: create a signal watcher, but keep it from keeping \f(CW\(C`ev_loop\(C'\fR
		594	running when nothing else is active.
		595	.Sp
		596	.Vb 4
		597	\& struct dv_signal exitsig;
		598	\& ev_signal_init (&exitsig, sig_cb, SIGINT);
		599	\& ev_signal_start (myloop, &exitsig);
		600	\& evf_unref (myloop);
		601	.Ve
		602	.Sp
		603	Example: for some weird reason, unregister the above signal handler again.
		604	.Sp
		605	.Vb 2
		606	\& ev_ref (myloop);
		607	\& ev_signal_stop (myloop, &exitsig);
		608	.Ve
442	.SH "ANATOMY OF A WATCHER"	609	.SH "ANATOMY OF A WATCHER"
443	.IX Header "ANATOMY OF A WATCHER"	610	.IX Header "ANATOMY OF A WATCHER"
444	A watcher is a structure that you create and register to record your	611	A watcher is a structure that you create and register to record your
445	interest in some event. For instance, if you want to wait for \s-1STDIN\s0 to	612	interest in some event. For instance, if you want to wait for \s-1STDIN\s0 to
446	become readable, you would create an \f(CW\(C`ev_io\(C'\fR watcher for that:	613	become readable, you would create an \f(CW\(C`ev_io\(C'\fR watcher for that:
…		…
482	)\(C'\fR), and you can stop watching for events at any time by calling the	649	)\(C'\fR), and you can stop watching for events at any time by calling the
483	corresponding stop function (\f(CW\(C`ev_<type>_stop (loop, watcher )\*(C'\fR.	650	corresponding stop function (\f(CW\(C`ev_<type>_stop (loop, watcher )\*(C'\fR.
484	.PP	651	.PP
485	As long as your watcher is active (has been started but not stopped) you	652	As long as your watcher is active (has been started but not stopped) you
486	must not touch the values stored in it. Most specifically you must never	653	must not touch the values stored in it. Most specifically you must never
487	reinitialise it or call its set method.	654	reinitialise it or call its \f(CW\(C`set\(C'\fR macro.
488	.PP
489	You can check whether an event is active by calling the \f(CW\*(C`ev_is_active
490	(watcher )\(C'\fR macro. To see whether an event is outstanding (but the
491	callback for it has not been called yet) you can use the \f(CW\*(C`ev_is_pending
492	(watcher )\(C'\fR macro.
493	.PP	655	.PP
494	Each and every callback receives the event loop pointer as first, the	656	Each and every callback receives the event loop pointer as first, the
495	registered watcher structure as second, and a bitset of received events as	657	registered watcher structure as second, and a bitset of received events as
496	third argument.	658	third argument.
497	.PP	659	.PP
…		…
555	Libev will usually signal a few \(L"dummy\(R" events together with an error,	717	Libev will usually signal a few \(L"dummy\(R" events together with an error,
556	for example it might indicate that a fd is readable or writable, and if	718	for example it might indicate that a fd is readable or writable, and if
557	your callbacks is well-written it can just attempt the operation and cope	719	your callbacks is well-written it can just attempt the operation and cope
558	with the error from \fIread()\fR or \fIwrite()\fR. This will not work in multithreaded	720	with the error from \fIread()\fR or \fIwrite()\fR. This will not work in multithreaded
559	programs, though, so beware.	721	programs, though, so beware.
		722	.Sh "\s-1SUMMARY\s0 \s-1OF\s0 \s-1GENERIC\s0 \s-1WATCHER\s0 \s-1FUNCTIONS\s0"
		723	.IX Subsection "SUMMARY OF GENERIC WATCHER FUNCTIONS"
		724	In the following description, \f(CW\(C`TYPE\(C'\fR stands for the watcher type,
		725	e.g. \f(CW\(C`timer\(C'\fR for \f(CW\(C`ev_timer\(C'\fR watchers and \f(CW\(C`io\(C'\fR for \f(CW\(C`ev_io\(C'\fR watchers.
		726	.ie n .IP """ev_init"" (ev_TYPE *watcher, callback)" 4
		727	.el .IP "\f(CWev_init\fR (ev_TYPE *watcher, callback)" 4
		728	.IX Item "ev_init (ev_TYPE *watcher, callback)"
		729	This macro initialises the generic portion of a watcher. The contents
		730	of the watcher object can be arbitrary (so \f(CW\(C`malloc\(C'\fR will do). Only
		731	the generic parts of the watcher are initialised, you \fIneed\fR to call
		732	the type-specific \f(CW\(C`ev_TYPE_set\(C'\fR macro afterwards to initialise the
		733	type-specific parts. For each type there is also a \f(CW\(C`ev_TYPE_init\(C'\fR macro
		734	which rolls both calls into one.
		735	.Sp
		736	You can reinitialise a watcher at any time as long as it has been stopped
		737	(or never started) and there are no pending events outstanding.
		738	.Sp
		739	The callbakc is always of type \f(CW\(C`void ()(ev_loop loop, ev_TYPE watcher,
		740	int revents)\*(C'\fR.
		741	.ie n .IP """ev_TYPE_set"" (ev_TYPE *, [args])" 4
		742	.el .IP "\f(CWev_TYPE_set\fR (ev_TYPE *, [args])" 4
		743	.IX Item "ev_TYPE_set (ev_TYPE *, [args])"
		744	This macro initialises the type-specific parts of a watcher. You need to
		745	call \f(CW\(C`ev_init\(C'\fR at least once before you call this macro, but you can
		746	call \f(CW\(C`ev_TYPE_set\(C'\fR any number of times. You must not, however, call this
		747	macro on a watcher that is active (it can be pending, however, which is a
		748	difference to the \f(CW\(C`ev_init\(C'\fR macro).
		749	.Sp
		750	Although some watcher types do not have type-specific arguments
		751	(e.g. \f(CW\(C`ev_prepare\(C'\fR) you still need to call its \f(CW\(C`set\(C'\fR macro.
		752	.ie n .IP """ev_TYPE_init"" (ev_TYPE *watcher, callback, [args])" 4
		753	.el .IP "\f(CWev_TYPE_init\fR (ev_TYPE *watcher, callback, [args])" 4
		754	.IX Item "ev_TYPE_init (ev_TYPE *watcher, callback, [args])"
		755	This convinience macro rolls both \f(CW\(C`ev_init\(C'\fR and \f(CW\(C`ev_TYPE_set\(C'\fR macro
		756	calls into a single call. This is the most convinient method to initialise
		757	a watcher. The same limitations apply, of course.
		758	.ie n .IP """ev_TYPE_start"" (loop , ev_TYPE watcher)" 4
		759	.el .IP "\f(CWev_TYPE_start\fR (loop , ev_TYPE watcher)" 4
		760	.IX Item "ev_TYPE_start (loop , ev_TYPE watcher)"
		761	Starts (activates) the given watcher. Only active watchers will receive
		762	events. If the watcher is already active nothing will happen.
		763	.ie n .IP """ev_TYPE_stop"" (loop , ev_TYPE watcher)" 4
		764	.el .IP "\f(CWev_TYPE_stop\fR (loop , ev_TYPE watcher)" 4
		765	.IX Item "ev_TYPE_stop (loop , ev_TYPE watcher)"
		766	Stops the given watcher again (if active) and clears the pending
		767	status. It is possible that stopped watchers are pending (for example,
		768	non-repeating timers are being stopped when they become pending), but
		769	\&\f(CW\(C`ev_TYPE_stop\(C'\fR ensures that the watcher is neither active nor pending. If
		770	you want to free or reuse the memory used by the watcher it is therefore a
		771	good idea to always call its \f(CW\(C`ev_TYPE_stop\(C'\fR function.
		772	.IP "bool ev_is_active (ev_TYPE *watcher)" 4
		773	.IX Item "bool ev_is_active (ev_TYPE *watcher)"
		774	Returns a true value iff the watcher is active (i.e. it has been started
		775	and not yet been stopped). As long as a watcher is active you must not modify
		776	it.
		777	.IP "bool ev_is_pending (ev_TYPE *watcher)" 4
		778	.IX Item "bool ev_is_pending (ev_TYPE *watcher)"
		779	Returns a true value iff the watcher is pending, (i.e. it has outstanding
		780	events but its callback has not yet been invoked). As long as a watcher
		781	is pending (but not active) you must not call an init function on it (but
		782	\&\f(CW\(C`ev_TYPE_set\(C'\fR is safe) and you must make sure the watcher is available to
		783	libev (e.g. you cnanot \f(CW\(C`free ()\(C'\fR it).
		784	.IP "callback = ev_cb (ev_TYPE *watcher)" 4
		785	.IX Item "callback = ev_cb (ev_TYPE *watcher)"
		786	Returns the callback currently set on the watcher.
		787	.IP "ev_cb_set (ev_TYPE *watcher, callback)" 4
		788	.IX Item "ev_cb_set (ev_TYPE *watcher, callback)"
		789	Change the callback. You can change the callback at virtually any time
		790	(modulo threads).
560	.Sh "\s-1ASSOCIATING\s0 \s-1CUSTOM\s0 \s-1DATA\s0 \s-1WITH\s0 A \s-1WATCHER\s0"	791	.Sh "\s-1ASSOCIATING\s0 \s-1CUSTOM\s0 \s-1DATA\s0 \s-1WITH\s0 A \s-1WATCHER\s0"
561	.IX Subsection "ASSOCIATING CUSTOM DATA WITH A WATCHER"	792	.IX Subsection "ASSOCIATING CUSTOM DATA WITH A WATCHER"
562	Each watcher has, by default, a member \f(CW\(C`void data\*(C'\fR that you can change	793	Each watcher has, by default, a member \f(CW\(C`void data\*(C'\fR that you can change
563	and read at any time, libev will completely ignore it. This can be used	794	and read at any time, libev will completely ignore it. This can be used
564	to associate arbitrary data with your watcher. If you need more data and	795	to associate arbitrary data with your watcher. If you need more data and
…		…
612	descriptors correctly if you register interest in two or more fds pointing	843	descriptors correctly if you register interest in two or more fds pointing
613	to the same underlying file/socket etc. description (that is, they share	844	to the same underlying file/socket etc. description (that is, they share
614	the same underlying \(L"file open\(R").	845	the same underlying \(L"file open\(R").
615	.PP	846	.PP
616	If you must do this, then force the use of a known-to-be-good backend	847	If you must do this, then force the use of a known-to-be-good backend
617	(at the time of this writing, this includes only \s-1EVMETHOD_SELECT\s0 and	848	(at the time of this writing, this includes only \f(CW\(C`EVBACKEND_SELECT\(C'\fR and
618	\&\s-1EVMETHOD_POLL\s0).	849	\&\f(CW\(C`EVBACKEND_POLL\(C'\fR).
619	.IP "ev_io_init (ev_io *, callback, int fd, int events)" 4	850	.IP "ev_io_init (ev_io *, callback, int fd, int events)" 4
620	.IX Item "ev_io_init (ev_io *, callback, int fd, int events)"	851	.IX Item "ev_io_init (ev_io *, callback, int fd, int events)"
621	.PD 0	852	.PD 0
622	.IP "ev_io_set (ev_io *, int fd, int events)" 4	853	.IP "ev_io_set (ev_io *, int fd, int events)" 4
623	.IX Item "ev_io_set (ev_io *, int fd, int events)"	854	.IX Item "ev_io_set (ev_io *, int fd, int events)"
624	.PD	855	.PD
625	Configures an \f(CW\(C`ev_io\(C'\fR watcher. The fd is the file descriptor to rceeive	856	Configures an \f(CW\(C`ev_io\(C'\fR watcher. The fd is the file descriptor to rceeive
626	events for and events is either \f(CW\(C`EV_READ\(C'\fR, \f(CW\(C`EV_WRITE\(C'\fR or \f(CW\*(C`EV_READ \|	857	events for and events is either \f(CW\(C`EV_READ\(C'\fR, \f(CW\(C`EV_WRITE\(C'\fR or \f(CW\*(C`EV_READ \|
627	EV_WRITE\*(C'\fR to receive the given events.	858	EV_WRITE\*(C'\fR to receive the given events.
		859	.Sp
		860	Please note that most of the more scalable backend mechanisms (for example
		861	epoll and solaris ports) can result in spurious readyness notifications
		862	for file descriptors, so you practically need to use non-blocking I/O (and
		863	treat callback invocation as hint only), or retest separately with a safe
		864	interface before doing I/O (XLib can do this), or force the use of either
		865	\&\f(CW\(C`EVBACKEND_SELECT\(C'\fR or \f(CW\(C`EVBACKEND_POLL\(C'\fR, which don't suffer from this
		866	problem. Also note that it is quite easy to have your callback invoked
		867	when the readyness condition is no longer valid even when employing
		868	typical ways of handling events, so its a good idea to use non-blocking
		869	I/O unconditionally.
		870	.PP
		871	Example: call \f(CW\(C`stdin_readable_cb\(C'\fR when \s-1STDIN_FILENO\s0 has become, well
		872	readable, but only once. Since it is likely line\-buffered, you could
		873	attempt to read a whole line in the callback:
		874	.PP
		875	.Vb 6
		876	\& static void
		877	\& stdin_readable_cb (struct ev_loop loop, struct ev_io w, int revents)
		878	\& {
		879	\& ev_io_stop (loop, w);
		880	\& .. read from stdin here (or from w->fd) and haqndle any I/O errors
		881	\& }
		882	.Ve
		883	.PP
		884	.Vb 6
		885	\& ...
		886	\& struct ev_loop *loop = ev_default_init (0);
		887	\& struct ev_io stdin_readable;
		888	\& ev_io_init (&stdin_readable, stdin_readable_cb, STDIN_FILENO, EV_READ);
		889	\& ev_io_start (loop, &stdin_readable);
		890	\& ev_loop (loop, 0);
		891	.Ve
628	.ie n .Sh """ev_timer"" \- relative and optionally recurring timeouts"	892	.ie n .Sh """ev_timer"" \- relative and optionally recurring timeouts"
629	.el .Sh "\f(CWev_timer\fP \- relative and optionally recurring timeouts"	893	.el .Sh "\f(CWev_timer\fP \- relative and optionally recurring timeouts"
630	.IX Subsection "ev_timer - relative and optionally recurring timeouts"	894	.IX Subsection "ev_timer - relative and optionally recurring timeouts"
631	Timer watchers are simple relative timers that generate an event after a	895	Timer watchers are simple relative timers that generate an event after a
632	given time, and optionally repeating in regular intervals after that.	896	given time, and optionally repeating in regular intervals after that.
…		…
682	seconds of inactivity on the socket. The easiest way to do this is to	946	seconds of inactivity on the socket. The easiest way to do this is to
683	configure an \f(CW\(C`ev_timer\(C'\fR with after=repeat=60 and calling ev_timer_again each	947	configure an \f(CW\(C`ev_timer\(C'\fR with after=repeat=60 and calling ev_timer_again each
684	time you successfully read or write some data. If you go into an idle	948	time you successfully read or write some data. If you go into an idle
685	state where you do not expect data to travel on the socket, you can stop	949	state where you do not expect data to travel on the socket, you can stop
686	the timer, and again will automatically restart it if need be.	950	the timer, and again will automatically restart it if need be.
		951	.PP
		952	Example: create a timer that fires after 60 seconds.
		953	.PP
		954	.Vb 5
		955	\& static void
		956	\& one_minute_cb (struct ev_loop loop, struct ev_timer w, int revents)
		957	\& {
		958	\& .. one minute over, w is actually stopped right here
		959	\& }
		960	.Ve
		961	.PP
		962	.Vb 3
		963	\& struct ev_timer mytimer;
		964	\& ev_timer_init (&mytimer, one_minute_cb, 60., 0.);
		965	\& ev_timer_start (loop, &mytimer);
		966	.Ve
		967	.PP
		968	Example: create a timeout timer that times out after 10 seconds of
		969	inactivity.
		970	.PP
		971	.Vb 5
		972	\& static void
		973	\& timeout_cb (struct ev_loop loop, struct ev_timer w, int revents)
		974	\& {
		975	\& .. ten seconds without any activity
		976	\& }
		977	.Ve
		978	.PP
		979	.Vb 4
		980	\& struct ev_timer mytimer;
		981	\& ev_timer_init (&mytimer, timeout_cb, 0., 10.); /* note, only repeat used */
		982	\& ev_timer_again (&mytimer); /* start timer */
		983	\& ev_loop (loop, 0);
		984	.Ve
		985	.PP
		986	.Vb 3
		987	\& // and in some piece of code that gets executed on any "activity":
		988	\& // reset the timeout to start ticking again at 10 seconds
		989	\& ev_timer_again (&mytimer);
		990	.Ve
687	.ie n .Sh """ev_periodic"" \- to cron or not to cron"	991	.ie n .Sh """ev_periodic"" \- to cron or not to cron"
688	.el .Sh "\f(CWev_periodic\fP \- to cron or not to cron"	992	.el .Sh "\f(CWev_periodic\fP \- to cron or not to cron"
689	.IX Subsection "ev_periodic - to cron or not to cron"	993	.IX Subsection "ev_periodic - to cron or not to cron"
690	Periodic watchers are also timers of a kind, but they are very versatile	994	Periodic watchers are also timers of a kind, but they are very versatile
691	(and unfortunately a bit complex).	995	(and unfortunately a bit complex).
692	.PP	996	.PP
693	Unlike \f(CW\(C`ev_timer\(C'\fR's, they are not based on real time (or relative time)	997	Unlike \f(CW\(C`ev_timer\(C'\fR's, they are not based on real time (or relative time)
694	but on wallclock time (absolute time). You can tell a periodic watcher	998	but on wallclock time (absolute time). You can tell a periodic watcher
695	to trigger \(L"at\(R" some specific point in time. For example, if you tell a	999	to trigger \(L"at\(R" some specific point in time. For example, if you tell a
696	periodic watcher to trigger in 10 seconds (by specifiying e.g. c<ev_now ()	1000	periodic watcher to trigger in 10 seconds (by specifiying e.g. \f(CW\*(C`ev_now ()
697	+ 10.>) and then reset your system clock to the last year, then it will	1001	+ 10.\*(C'\fR) and then reset your system clock to the last year, then it will
698	take a year to trigger the event (unlike an \f(CW\(C`ev_timer\(C'\fR, which would trigger	1002	take a year to trigger the event (unlike an \f(CW\(C`ev_timer\(C'\fR, which would trigger
699	roughly 10 seconds later and of course not if you reset your system time	1003	roughly 10 seconds later and of course not if you reset your system time
700	again).	1004	again).
701	.PP	1005	.PP
702	They can also be used to implement vastly more complex timers, such as	1006	They can also be used to implement vastly more complex timers, such as
…		…
783	.IX Item "ev_periodic_again (loop, ev_periodic *)"	1087	.IX Item "ev_periodic_again (loop, ev_periodic *)"
784	Simply stops and restarts the periodic watcher again. This is only useful	1088	Simply stops and restarts the periodic watcher again. This is only useful
785	when you changed some parameters or the reschedule callback would return	1089	when you changed some parameters or the reschedule callback would return
786	a different time than the last time it was called (e.g. in a crond like	1090	a different time than the last time it was called (e.g. in a crond like
787	program when the crontabs have changed).	1091	program when the crontabs have changed).
		1092	.PP
		1093	Example: call a callback every hour, or, more precisely, whenever the
		1094	system clock is divisible by 3600. The callback invocation times have
		1095	potentially a lot of jittering, but good long-term stability.
		1096	.PP
		1097	.Vb 5
		1098	\& static void
		1099	\& clock_cb (struct ev_loop loop, struct ev_io w, int revents)
		1100	\& {
		1101	\& ... its now a full hour (UTC, or TAI or whatever your clock follows)
		1102	\& }
		1103	.Ve
		1104	.PP
		1105	.Vb 3
		1106	\& struct ev_periodic hourly_tick;
		1107	\& ev_periodic_init (&hourly_tick, clock_cb, 0., 3600., 0);
		1108	\& ev_periodic_start (loop, &hourly_tick);
		1109	.Ve
		1110	.PP
		1111	Example: the same as above, but use a reschedule callback to do it:
		1112	.PP
		1113	.Vb 1
		1114	\& #include <math.h>
		1115	.Ve
		1116	.PP
		1117	.Vb 5
		1118	\& static ev_tstamp
		1119	\& my_scheduler_cb (struct ev_periodic *w, ev_tstamp now)
		1120	\& {
		1121	\& return fmod (now, 3600.) + 3600.;
		1122	\& }
		1123	.Ve
		1124	.PP
		1125	.Vb 1
		1126	\& ev_periodic_init (&hourly_tick, clock_cb, 0., 0., my_scheduler_cb);
		1127	.Ve
		1128	.PP
		1129	Example: call a callback every hour, starting now:
		1130	.PP
		1131	.Vb 4
		1132	\& struct ev_periodic hourly_tick;
		1133	\& ev_periodic_init (&hourly_tick, clock_cb,
		1134	\& fmod (ev_now (loop), 3600.), 3600., 0);
		1135	\& ev_periodic_start (loop, &hourly_tick);
		1136	.Ve
788	.ie n .Sh """ev_signal"" \- signal me when a signal gets signalled"	1137	.ie n .Sh """ev_signal"" \- signal me when a signal gets signalled"
789	.el .Sh "\f(CWev_signal\fP \- signal me when a signal gets signalled"	1138	.el .Sh "\f(CWev_signal\fP \- signal me when a signal gets signalled"
790	.IX Subsection "ev_signal - signal me when a signal gets signalled"	1139	.IX Subsection "ev_signal - signal me when a signal gets signalled"
791	Signal watchers will trigger an event when the process receives a specific	1140	Signal watchers will trigger an event when the process receives a specific
792	signal one or more times. Even though signals are very asynchronous, libev	1141	signal one or more times. Even though signals are very asynchronous, libev
…		…
822	\&\fIany\fR process if \f(CW\(C`pid\(C'\fR is specified as \f(CW0\fR). The callback can look	1171	\&\fIany\fR process if \f(CW\(C`pid\(C'\fR is specified as \f(CW0\fR). The callback can look
823	at the \f(CW\(C`rstatus\(C'\fR member of the \f(CW\(C`ev_child\(C'\fR watcher structure to see	1172	at the \f(CW\(C`rstatus\(C'\fR member of the \f(CW\(C`ev_child\(C'\fR watcher structure to see
824	the status word (use the macros from \f(CW\(C`sys/wait.h\(C'\fR and see your systems	1173	the status word (use the macros from \f(CW\(C`sys/wait.h\(C'\fR and see your systems
825	\&\f(CW\(C`waitpid\(C'\fR documentation). The \f(CW\(C`rpid\(C'\fR member contains the pid of the	1174	\&\f(CW\(C`waitpid\(C'\fR documentation). The \f(CW\(C`rpid\(C'\fR member contains the pid of the
826	process causing the status change.	1175	process causing the status change.
		1176	.PP
		1177	Example: try to exit cleanly on \s-1SIGINT\s0 and \s-1SIGTERM\s0.
		1178	.PP
		1179	.Vb 5
		1180	\& static void
		1181	\& sigint_cb (struct ev_loop loop, struct ev_signal w, int revents)
		1182	\& {
		1183	\& ev_unloop (loop, EVUNLOOP_ALL);
		1184	\& }
		1185	.Ve
		1186	.PP
		1187	.Vb 3
		1188	\& struct ev_signal signal_watcher;
		1189	\& ev_signal_init (&signal_watcher, sigint_cb, SIGINT);
		1190	\& ev_signal_start (loop, &sigint_cb);
		1191	.Ve
827	.ie n .Sh """ev_idle"" \- when you've got nothing better to do"	1192	.ie n .Sh """ev_idle"" \- when you've got nothing better to do"
828	.el .Sh "\f(CWev_idle\fP \- when you've got nothing better to do"	1193	.el .Sh "\f(CWev_idle\fP \- when you've got nothing better to do"
829	.IX Subsection "ev_idle - when you've got nothing better to do"	1194	.IX Subsection "ev_idle - when you've got nothing better to do"
830	Idle watchers trigger events when there are no other events are pending	1195	Idle watchers trigger events when there are no other events are pending
831	(prepare, check and other idle watchers do not count). That is, as long	1196	(prepare, check and other idle watchers do not count). That is, as long
…		…
845	.IP "ev_idle_init (ev_signal *, callback)" 4	1210	.IP "ev_idle_init (ev_signal *, callback)" 4
846	.IX Item "ev_idle_init (ev_signal *, callback)"	1211	.IX Item "ev_idle_init (ev_signal *, callback)"
847	Initialises and configures the idle watcher \- it has no parameters of any	1212	Initialises and configures the idle watcher \- it has no parameters of any
848	kind. There is a \f(CW\(C`ev_idle_set\(C'\fR macro, but using it is utterly pointless,	1213	kind. There is a \f(CW\(C`ev_idle_set\(C'\fR macro, but using it is utterly pointless,
849	believe me.	1214	believe me.
		1215	.PP
		1216	Example: dynamically allocate an \f(CW\(C`ev_idle\(C'\fR, start it, and in the
		1217	callback, free it. Alos, use no error checking, as usual.
		1218	.PP
		1219	.Vb 7
		1220	\& static void
		1221	\& idle_cb (struct ev_loop loop, struct ev_idle w, int revents)
		1222	\& {
		1223	\& free (w);
		1224	\& // now do something you wanted to do when the program has
		1225	\& // no longer asnything immediate to do.
		1226	\& }
		1227	.Ve
		1228	.PP
		1229	.Vb 3
		1230	\& struct ev_idle *idle_watcher = malloc (sizeof (struct ev_idle));
		1231	\& ev_idle_init (idle_watcher, idle_cb);
		1232	\& ev_idle_start (loop, idle_cb);
		1233	.Ve
850	.ie n .Sh """ev_prepare""\fP and \f(CW""ev_check"" \- customise your event loop"	1234	.ie n .Sh """ev_prepare""\fP and \f(CW""ev_check"" \- customise your event loop"
851	.el .Sh "\f(CWev_prepare\fP and \f(CWev_check\fP \- customise your event loop"	1235	.el .Sh "\f(CWev_prepare\fP and \f(CWev_check\fP \- customise your event loop"
852	.IX Subsection "ev_prepare and ev_check - customise your event loop"	1236	.IX Subsection "ev_prepare and ev_check - customise your event loop"
853	Prepare and check watchers are usually (but not always) used in tandem:	1237	Prepare and check watchers are usually (but not always) used in tandem:
854	prepare watchers get invoked before the process blocks and check watchers	1238	prepare watchers get invoked before the process blocks and check watchers
855	afterwards.	1239	afterwards.
856	.PP	1240	.PP
857	Their main purpose is to integrate other event mechanisms into libev. This	1241	Their main purpose is to integrate other event mechanisms into libev and
858	could be used, for example, to track variable changes, implement your own	1242	their use is somewhat advanced. This could be used, for example, to track
859	watchers, integrate net-snmp or a coroutine library and lots more.	1243	variable changes, implement your own watchers, integrate net-snmp or a
		1244	coroutine library and lots more.
860	.PP	1245	.PP
861	This is done by examining in each prepare call which file descriptors need	1246	This is done by examining in each prepare call which file descriptors need
862	to be watched by the other library, registering \f(CW\(C`ev_io\(C'\fR watchers for	1247	to be watched by the other library, registering \f(CW\(C`ev_io\(C'\fR watchers for
863	them and starting an \f(CW\(C`ev_timer\(C'\fR watcher for any timeouts (many libraries	1248	them and starting an \f(CW\(C`ev_timer\(C'\fR watcher for any timeouts (many libraries
864	provide just this functionality). Then, in the check watcher you check for	1249	provide just this functionality). Then, in the check watcher you check for
…		…
882	.IX Item "ev_check_init (ev_check *, callback)"	1267	.IX Item "ev_check_init (ev_check *, callback)"
883	.PD	1268	.PD
884	Initialises and configures the prepare or check watcher \- they have no	1269	Initialises and configures the prepare or check watcher \- they have no
885	parameters of any kind. There are \f(CW\(C`ev_prepare_set\(C'\fR and \f(CW\(C`ev_check_set\(C'\fR	1270	parameters of any kind. There are \f(CW\(C`ev_prepare_set\(C'\fR and \f(CW\(C`ev_check_set\(C'\fR
886	macros, but using them is utterly, utterly and completely pointless.	1271	macros, but using them is utterly, utterly and completely pointless.
		1272	.PP
		1273	Example: TODO.
		1274	.ie n .Sh """ev_embed"" \- when one backend isn't enough"
		1275	.el .Sh "\f(CWev_embed\fP \- when one backend isn't enough"
		1276	.IX Subsection "ev_embed - when one backend isn't enough"
		1277	This is a rather advanced watcher type that lets you embed one event loop
		1278	into another (currently only \f(CW\(C`ev_io\(C'\fR events are supported in the embedded
		1279	loop, other types of watchers might be handled in a delayed or incorrect
		1280	fashion and must not be used).
		1281	.PP
		1282	There are primarily two reasons you would want that: work around bugs and
		1283	prioritise I/O.
		1284	.PP
		1285	As an example for a bug workaround, the kqueue backend might only support
		1286	sockets on some platform, so it is unusable as generic backend, but you
		1287	still want to make use of it because you have many sockets and it scales
		1288	so nicely. In this case, you would create a kqueue-based loop and embed it
		1289	into your default loop (which might use e.g. poll). Overall operation will
		1290	be a bit slower because first libev has to poll and then call kevent, but
		1291	at least you can use both at what they are best.
		1292	.PP
		1293	As for prioritising I/O: rarely you have the case where some fds have
		1294	to be watched and handled very quickly (with low latency), and even
		1295	priorities and idle watchers might have too much overhead. In this case
		1296	you would put all the high priority stuff in one loop and all the rest in
		1297	a second one, and embed the second one in the first.
		1298	.PP
		1299	As long as the watcher is active, the callback will be invoked every time
		1300	there might be events pending in the embedded loop. The callback must then
		1301	call \f(CW\(C`ev_embed_sweep (mainloop, watcher)\(C'\fR to make a single sweep and invoke
		1302	their callbacks (you could also start an idle watcher to give the embedded
		1303	loop strictly lower priority for example). You can also set the callback
		1304	to \f(CW0\fR, in which case the embed watcher will automatically execute the
		1305	embedded loop sweep.
		1306	.PP
		1307	As long as the watcher is started it will automatically handle events. The
		1308	callback will be invoked whenever some events have been handled. You can
		1309	set the callback to \f(CW0\fR to avoid having to specify one if you are not
		1310	interested in that.
		1311	.PP
		1312	Also, there have not currently been made special provisions for forking:
		1313	when you fork, you not only have to call \f(CW\(C`ev_loop_fork\(C'\fR on both loops,
		1314	but you will also have to stop and restart any \f(CW\(C`ev_embed\(C'\fR watchers
		1315	yourself.
		1316	.PP
		1317	Unfortunately, not all backends are embeddable, only the ones returned by
		1318	\&\f(CW\(C`ev_embeddable_backends\(C'\fR are, which, unfortunately, does not include any
		1319	portable one.
		1320	.PP
		1321	So when you want to use this feature you will always have to be prepared
		1322	that you cannot get an embeddable loop. The recommended way to get around
		1323	this is to have a separate variables for your embeddable loop, try to
		1324	create it, and if that fails, use the normal loop for everything:
		1325	.PP
		1326	.Vb 3
		1327	\& struct ev_loop *loop_hi = ev_default_init (0);
		1328	\& struct ev_loop *loop_lo = 0;
		1329	\& struct ev_embed embed;
		1330	.Ve
		1331	.PP
		1332	.Vb 5
		1333	\& // see if there is a chance of getting one that works
		1334	\& // (remember that a flags value of 0 means autodetection)
		1335	\& loop_lo = ev_embeddable_backends () & ev_recommended_backends ()
		1336	\& ? ev_loop_new (ev_embeddable_backends () & ev_recommended_backends ())
		1337	\& : 0;
		1338	.Ve
		1339	.PP
		1340	.Vb 8
		1341	\& // if we got one, then embed it, otherwise default to loop_hi
		1342	\& if (loop_lo)
		1343	\& {
		1344	\& ev_embed_init (&embed, 0, loop_lo);
		1345	\& ev_embed_start (loop_hi, &embed);
		1346	\& }
		1347	\& else
		1348	\& loop_lo = loop_hi;
		1349	.Ve
		1350	.IP "ev_embed_init (ev_embed , callback, struct ev_loop embedded_loop)" 4
		1351	.IX Item "ev_embed_init (ev_embed , callback, struct ev_loop embedded_loop)"
		1352	.PD 0
		1353	.IP "ev_embed_set (ev_embed , callback, struct ev_loop embedded_loop)" 4
		1354	.IX Item "ev_embed_set (ev_embed , callback, struct ev_loop embedded_loop)"
		1355	.PD
		1356	Configures the watcher to embed the given loop, which must be
		1357	embeddable. If the callback is \f(CW0\fR, then \f(CW\(C`ev_embed_sweep\(C'\fR will be
		1358	invoked automatically, otherwise it is the responsibility of the callback
		1359	to invoke it (it will continue to be called until the sweep has been done,
		1360	if you do not want thta, you need to temporarily stop the embed watcher).
		1361	.IP "ev_embed_sweep (loop, ev_embed *)" 4
		1362	.IX Item "ev_embed_sweep (loop, ev_embed *)"
		1363	Make a single, non-blocking sweep over the embedded loop. This works
		1364	similarly to \f(CW\(C`ev_loop (embedded_loop, EVLOOP_NONBLOCK)\(C'\fR, but in the most
		1365	apropriate way for embedded loops.
887	.SH "OTHER FUNCTIONS"	1366	.SH "OTHER FUNCTIONS"
888	.IX Header "OTHER FUNCTIONS"	1367	.IX Header "OTHER FUNCTIONS"
889	There are some other functions of possible interest. Described. Here. Now.	1368	There are some other functions of possible interest. Described. Here. Now.
890	.IP "ev_once (loop, int fd, int events, ev_tstamp timeout, callback)" 4	1369	.IP "ev_once (loop, int fd, int events, ev_tstamp timeout, callback)" 4
891	.IX Item "ev_once (loop, int fd, int events, ev_tstamp timeout, callback)"	1370	.IX Item "ev_once (loop, int fd, int events, ev_tstamp timeout, callback)"
…		…
920	.Ve	1399	.Ve
921	.Sp	1400	.Sp
922	.Vb 1	1401	.Vb 1
923	\& ev_once (STDIN_FILENO, EV_READ, 10., stdin_ready, 0);	1402	\& ev_once (STDIN_FILENO, EV_READ, 10., stdin_ready, 0);
924	.Ve	1403	.Ve
925	.IP "ev_feed_event (loop, watcher, int events)" 4	1404	.IP "ev_feed_event (ev_loop , watcher , int revents)" 4
926	.IX Item "ev_feed_event (loop, watcher, int events)"	1405	.IX Item "ev_feed_event (ev_loop , watcher , int revents)"
927	Feeds the given event set into the event loop, as if the specified event	1406	Feeds the given event set into the event loop, as if the specified event
928	had happened for the specified watcher (which must be a pointer to an	1407	had happened for the specified watcher (which must be a pointer to an
929	initialised but not necessarily started event watcher).	1408	initialised but not necessarily started event watcher).
930	.IP "ev_feed_fd_event (loop, int fd, int revents)" 4	1409	.IP "ev_feed_fd_event (ev_loop *, int fd, int revents)" 4
931	.IX Item "ev_feed_fd_event (loop, int fd, int revents)"	1410	.IX Item "ev_feed_fd_event (ev_loop *, int fd, int revents)"
932	Feed an event on the given fd, as if a file descriptor backend detected	1411	Feed an event on the given fd, as if a file descriptor backend detected
933	the given events it.	1412	the given events it.
934	.IP "ev_feed_signal_event (loop, int signum)" 4	1413	.IP "ev_feed_signal_event (ev_loop *loop, int signum)" 4
935	.IX Item "ev_feed_signal_event (loop, int signum)"	1414	.IX Item "ev_feed_signal_event (ev_loop *loop, int signum)"
936	Feed an event as if the given signal occured (loop must be the default loop!).	1415	Feed an event as if the given signal occured (\f(CW\(C`loop\(C'\fR must be the default
		1416	loop!).
937	.SH "LIBEVENT EMULATION"	1417	.SH "LIBEVENT EMULATION"
938	.IX Header "LIBEVENT EMULATION"	1418	.IX Header "LIBEVENT EMULATION"
939	Libev offers a compatibility emulation layer for libevent. It cannot	1419	Libev offers a compatibility emulation layer for libevent. It cannot
940	emulate the internals of libevent, so here are some usage hints:	1420	emulate the internals of libevent, so here are some usage hints:
941	.IP "* Use it by including <event.h>, as usual." 4	1421	.IP "* Use it by including <event.h>, as usual." 4
…		…
952	.IP "* The libev emulation is \fInot\fR \s-1ABI\s0 compatible to libevent, you need to use the libev header file and library." 4	1432	.IP "* The libev emulation is \fInot\fR \s-1ABI\s0 compatible to libevent, you need to use the libev header file and library." 4
953	.IX Item "The libev emulation is not ABI compatible to libevent, you need to use the libev header file and library."	1433	.IX Item "The libev emulation is not ABI compatible to libevent, you need to use the libev header file and library."
954	.PD	1434	.PD
955	.SH "\*(C+ SUPPORT"	1435	.SH "\*(C+ SUPPORT"
956	.IX Header " SUPPORT"	1436	.IX Header " SUPPORT"
957	\&\s-1TBD\s0.	1437	Libev comes with some simplistic wrapper classes for \*(C+ that mainly allow
		1438	you to use some convinience methods to start/stop watchers and also change
		1439	the callback model to a model using method callbacks on objects.
		1440	.PP
		1441	To use it,
		1442	.PP
		1443	.Vb 1
		1444	\& #include <ev++.h>
		1445	.Ve
		1446	.PP
		1447	(it is not installed by default). This automatically includes \fIev.h\fR
		1448	and puts all of its definitions (many of them macros) into the global
		1449	namespace. All \(C+ specific things are put into the \f(CW\(C`ev\*(C'\fR namespace.
		1450	.PP
		1451	It should support all the same embedding options as \fIev.h\fR, most notably
		1452	\&\f(CW\(C`EV_MULTIPLICITY\(C'\fR.
		1453	.PP
		1454	Here is a list of things available in the \f(CW\(C`ev\(C'\fR namespace:
		1455	.ie n .IP """ev::READ""\fR, \f(CW""ev::WRITE"" etc." 4
		1456	.el .IP "\f(CWev::READ\fR, \f(CWev::WRITE\fR etc." 4
		1457	.IX Item "ev::READ, ev::WRITE etc."
		1458	These are just enum values with the same values as the \f(CW\(C`EV_READ\(C'\fR etc.
		1459	macros from \fIev.h\fR.
		1460	.ie n .IP """ev::tstamp""\fR, \f(CW""ev::now""" 4
		1461	.el .IP "\f(CWev::tstamp\fR, \f(CWev::now\fR" 4
		1462	.IX Item "ev::tstamp, ev::now"
		1463	Aliases to the same types/functions as with the \f(CW\(C`ev_\(C'\fR prefix.
		1464	.ie n .IP """ev::io""\fR, \f(CW""ev::timer""\fR, \f(CW""ev::periodic""\fR, \f(CW""ev::idle""\fR, \f(CW""ev::sig"" etc." 4
		1465	.el .IP "\f(CWev::io\fR, \f(CWev::timer\fR, \f(CWev::periodic\fR, \f(CWev::idle\fR, \f(CWev::sig\fR etc." 4
		1466	.IX Item "ev::io, ev::timer, ev::periodic, ev::idle, ev::sig etc."
		1467	For each \f(CW\(C`ev_TYPE\(C'\fR watcher in \fIev.h\fR there is a corresponding class of
		1468	the same name in the \f(CW\(C`ev\(C'\fR namespace, with the exception of \f(CW\(C`ev_signal\(C'\fR
		1469	which is called \f(CW\(C`ev::sig\(C'\fR to avoid clashes with the \f(CW\(C`signal\(C'\fR macro
		1470	defines by many implementations.
		1471	.Sp
		1472	All of those classes have these methods:
		1473	.RS 4
		1474	.IP "ev::TYPE::TYPE (object , object::method )" 4
		1475	.IX Item "ev::TYPE::TYPE (object , object::method )"
		1476	.PD 0
		1477	.IP "ev::TYPE::TYPE (object , object::method , struct ev_loop *)" 4
		1478	.IX Item "ev::TYPE::TYPE (object , object::method , struct ev_loop *)"
		1479	.IP "ev::TYPE::~TYPE" 4
		1480	.IX Item "ev::TYPE::~TYPE"
		1481	.PD
		1482	The constructor takes a pointer to an object and a method pointer to
		1483	the event handler callback to call in this class. The constructor calls
		1484	\&\f(CW\(C`ev_init\(C'\fR for you, which means you have to call the \f(CW\(C`set\(C'\fR method
		1485	before starting it. If you do not specify a loop then the constructor
		1486	automatically associates the default loop with this watcher.
		1487	.Sp
		1488	The destructor automatically stops the watcher if it is active.
		1489	.IP "w\->set (struct ev_loop *)" 4
		1490	.IX Item "w->set (struct ev_loop *)"
		1491	Associates a different \f(CW\(C`struct ev_loop\(C'\fR with this watcher. You can only
		1492	do this when the watcher is inactive (and not pending either).
		1493	.IP "w\->set ([args])" 4
		1494	.IX Item "w->set ([args])"
		1495	Basically the same as \f(CW\(C`ev_TYPE_set\(C'\fR, with the same args. Must be
		1496	called at least once. Unlike the C counterpart, an active watcher gets
		1497	automatically stopped and restarted.
		1498	.IP "w\->start ()" 4
		1499	.IX Item "w->start ()"
		1500	Starts the watcher. Note that there is no \f(CW\(C`loop\(C'\fR argument as the
		1501	constructor already takes the loop.
		1502	.IP "w\->stop ()" 4
		1503	.IX Item "w->stop ()"
		1504	Stops the watcher if it is active. Again, no \f(CW\(C`loop\(C'\fR argument.
		1505	.ie n .IP "w\->again () ""ev::timer""\fR, \f(CW""ev::periodic"" only" 4
		1506	.el .IP "w\->again () \f(CWev::timer\fR, \f(CWev::periodic\fR only" 4
		1507	.IX Item "w->again () ev::timer, ev::periodic only"
		1508	For \f(CW\(C`ev::timer\(C'\fR and \f(CW\(C`ev::periodic\(C'\fR, this invokes the corresponding
		1509	\&\f(CW\(C`ev_TYPE_again\(C'\fR function.
		1510	.ie n .IP "w\->sweep () ""ev::embed"" only" 4
		1511	.el .IP "w\->sweep () \f(CWev::embed\fR only" 4
		1512	.IX Item "w->sweep () ev::embed only"
		1513	Invokes \f(CW\(C`ev_embed_sweep\(C'\fR.
		1514	.RE
		1515	.RS 4
		1516	.RE
		1517	.PP
		1518	Example: Define a class with an \s-1IO\s0 and idle watcher, start one of them in
		1519	the constructor.
		1520	.PP
		1521	.Vb 4
		1522	\& class myclass
		1523	\& {
		1524	\& ev_io io; void io_cb (ev::io &w, int revents);
		1525	\& ev_idle idle void idle_cb (ev::idle &w, int revents);
		1526	.Ve
		1527	.PP
		1528	.Vb 2
		1529	\& myclass ();
		1530	\& }
		1531	.Ve
		1532	.PP
		1533	.Vb 6
		1534	\& myclass::myclass (int fd)
		1535	\& : io (this, &myclass::io_cb),
		1536	\& idle (this, &myclass::idle_cb)
		1537	\& {
		1538	\& io.start (fd, ev::READ);
		1539	\& }
		1540	.Ve
958	.SH "AUTHOR"	1541	.SH "AUTHOR"
959	.IX Header "AUTHOR"	1542	.IX Header "AUTHOR"
960	Marc Lehmann <libev@schmorp.de>.	1543	Marc Lehmann <libev@schmorp.de>.

Diff Legend

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

Comparing libev/ev.3 (file contents): Revision 1.5 by root, Fri Nov 23 04:36:03 2007 UTC vs. Revision 1.13 by root, Sat Nov 24 09:48:38 2007 UTC

Diff Legend

Comparing libev/ev.3 (file contents):
Revision 1.5 by root, Fri Nov 23 04:36:03 2007 UTC vs.
Revision 1.13 by root, Sat Nov 24 09:48:38 2007 UTC