ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/libev/ev.3
Revision: 1.69
Committed: Sat Jul 5 02:25:40 2008 UTC (15 years, 10 months ago) by root
Branch: MAIN
Changes since 1.68: +12 -6 lines
Log Message:
*** empty log message ***

File Contents

# User Rev Content
1 root 1.60 .\" Automatically generated by Pod::Man 2.16 (Pod::Simple 3.05)
2 root 1.1 .\"
3     .\" Standard preamble:
4     .\" ========================================================================
5     .de Sh \" Subsection heading
6     .br
7     .if t .Sp
8     .ne 5
9     .PP
10     \fB\\$1\fR
11     .PP
12     ..
13     .de Sp \" Vertical space (when we can't use .PP)
14     .if t .sp .5v
15     .if n .sp
16     ..
17     .de Vb \" Begin verbatim text
18     .ft CW
19     .nf
20     .ne \\$1
21     ..
22     .de Ve \" End verbatim text
23     .ft R
24     .fi
25     ..
26     .\" Set up some character translations and predefined strings. \*(-- will
27     .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
28 root 1.60 .\" double quote, and \*(R" will give a right double quote. \*(C+ will
29     .\" give a nicer C++. Capital omega is used to do unbreakable dashes and
30     .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
31     .\" nothing in troff, for use with C<>.
32     .tr \(*W-
33 root 1.1 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
34     .ie n \{\
35     . ds -- \(*W-
36     . ds PI pi
37     . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
38     . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
39     . ds L" ""
40     . ds R" ""
41     . ds C` ""
42     . ds C' ""
43     'br\}
44     .el\{\
45     . ds -- \|\(em\|
46     . ds PI \(*p
47     . ds L" ``
48     . ds R" ''
49     'br\}
50     .\"
51 root 1.60 .\" Escape single quotes in literal strings from groff's Unicode transform.
52     .ie \n(.g .ds Aq \(aq
53     .el .ds Aq '
54     .\"
55 root 1.1 .\" If the F register is turned on, we'll generate index entries on stderr for
56     .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
57     .\" entries marked with X<> in POD. Of course, you'll have to process the
58     .\" output yourself in some meaningful fashion.
59 root 1.60 .ie \nF \{\
60 root 1.1 . de IX
61     . tm Index:\\$1\t\\n%\t"\\$2"
62     ..
63     . nr % 0
64     . rr F
65     .\}
66 root 1.60 .el \{\
67     . de IX
68     ..
69     .\}
70 root 1.1 .\"
71     .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
72     .\" Fear. Run. Save yourself. No user-serviceable parts.
73     . \" fudge factors for nroff and troff
74     .if n \{\
75     . ds #H 0
76     . ds #V .8m
77     . ds #F .3m
78     . ds #[ \f1
79     . ds #] \fP
80     .\}
81     .if t \{\
82     . ds #H ((1u-(\\\\n(.fu%2u))*.13m)
83     . ds #V .6m
84     . ds #F 0
85     . ds #[ \&
86     . ds #] \&
87     .\}
88     . \" simple accents for nroff and troff
89     .if n \{\
90     . ds ' \&
91     . ds ` \&
92     . ds ^ \&
93     . ds , \&
94     . ds ~ ~
95     . ds /
96     .\}
97     .if t \{\
98     . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
99     . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
100     . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
101     . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
102     . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
103     . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
104     .\}
105     . \" troff and (daisy-wheel) nroff accents
106     .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
107     .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
108     .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
109     .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
110     .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
111     .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
112     .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
113     .ds ae a\h'-(\w'a'u*4/10)'e
114     .ds Ae A\h'-(\w'A'u*4/10)'E
115     . \" corrections for vroff
116     .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
117     .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
118     . \" for low resolution devices (crt and lpr)
119     .if \n(.H>23 .if \n(.V>19 \
120     \{\
121     . ds : e
122     . ds 8 ss
123     . ds o a
124     . ds d- d\h'-1'\(ga
125     . ds D- D\h'-1'\(hy
126     . ds th \o'bp'
127     . ds Th \o'LP'
128     . ds ae ae
129     . ds Ae AE
130     .\}
131     .rm #[ #] #H #V #F C
132     .\" ========================================================================
133     .\"
134 root 1.65 .IX Title "LIBEV 3"
135 root 1.69 .TH LIBEV 3 "2008-06-19" "libev-3.43" "libev - high performance full featured event loop"
136 root 1.60 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
137     .\" way too many mistakes in technical documents.
138     .if n .ad l
139     .nh
140 root 1.1 .SH "NAME"
141     libev \- a high performance full\-featured event loop written in C
142     .SH "SYNOPSIS"
143     .IX Header "SYNOPSIS"
144 root 1.28 .Vb 1
145 root 1.68 \& #include <ev.h>
146 root 1.28 .Ve
147 root 1.59 .Sh "\s-1EXAMPLE\s0 \s-1PROGRAM\s0"
148     .IX Subsection "EXAMPLE PROGRAM"
149 root 1.61 .Vb 2
150 root 1.68 \& // a single header file is required
151     \& #include <ev.h>
152 root 1.60 \&
153 root 1.68 \& // every watcher type has its own typedef\*(Aqd struct
154     \& // with the name ev_<type>
155     \& ev_io stdin_watcher;
156     \& ev_timer timeout_watcher;
157     \&
158     \& // all watcher callbacks have a similar signature
159     \& // this callback is called when data is readable on stdin
160     \& static void
161     \& stdin_cb (EV_P_ struct ev_io *w, int revents)
162     \& {
163     \& puts ("stdin ready");
164     \& // for one\-shot events, one must manually stop the watcher
165     \& // with its corresponding stop function.
166     \& ev_io_stop (EV_A_ w);
167     \&
168     \& // this causes all nested ev_loop\*(Aqs to stop iterating
169     \& ev_unloop (EV_A_ EVUNLOOP_ALL);
170     \& }
171     \&
172     \& // another callback, this time for a time\-out
173     \& static void
174     \& timeout_cb (EV_P_ struct ev_timer *w, int revents)
175     \& {
176     \& puts ("timeout");
177     \& // this causes the innermost ev_loop to stop iterating
178     \& ev_unloop (EV_A_ EVUNLOOP_ONE);
179     \& }
180     \&
181     \& int
182     \& main (void)
183     \& {
184     \& // use the default event loop unless you have special needs
185     \& struct ev_loop *loop = ev_default_loop (0);
186     \&
187     \& // initialise an io watcher, then start it
188     \& // this one will watch for stdin to become readable
189     \& ev_io_init (&stdin_watcher, stdin_cb, /*STDIN_FILENO*/ 0, EV_READ);
190     \& ev_io_start (loop, &stdin_watcher);
191     \&
192     \& // initialise a timer watcher, then start it
193     \& // simple non\-repeating 5.5 second timeout
194     \& ev_timer_init (&timeout_watcher, timeout_cb, 5.5, 0.);
195     \& ev_timer_start (loop, &timeout_watcher);
196     \&
197     \& // now wait for events to arrive
198     \& ev_loop (loop, 0);
199     \&
200     \& // unloop was called, so exit
201     \& return 0;
202     \& }
203 root 1.27 .Ve
204 root 1.1 .SH "DESCRIPTION"
205     .IX Header "DESCRIPTION"
206 root 1.61 The newest version of this document is also available as an html-formatted
207 root 1.39 web page you might find easier to navigate when reading it for the first
208 root 1.66 time: <http://pod.tst.eu/http://cvs.schmorp.de/libev/ev.pod>.
209 root 1.39 .PP
210 root 1.1 Libev is an event loop: you register interest in certain events (such as a
211 root 1.54 file descriptor being readable or a timeout occurring), and it will manage
212 root 1.1 these event sources and provide your program with events.
213     .PP
214     To do this, it must take more or less complete control over your process
215     (or thread) by executing the \fIevent loop\fR handler, and will then
216     communicate events via a callback mechanism.
217     .PP
218     You register interest in certain events by registering so-called \fIevent
219     watchers\fR, which are relatively small C structures you initialise with the
220     details of the event, and then hand it over to libev by \fIstarting\fR the
221     watcher.
222 root 1.59 .Sh "\s-1FEATURES\s0"
223     .IX Subsection "FEATURES"
224 root 1.31 Libev supports \f(CW\*(C`select\*(C'\fR, \f(CW\*(C`poll\*(C'\fR, the Linux-specific \f(CW\*(C`epoll\*(C'\fR, the
225     BSD-specific \f(CW\*(C`kqueue\*(C'\fR and the Solaris-specific event port mechanisms
226     for file descriptor events (\f(CW\*(C`ev_io\*(C'\fR), the Linux \f(CW\*(C`inotify\*(C'\fR interface
227     (for \f(CW\*(C`ev_stat\*(C'\fR), relative timers (\f(CW\*(C`ev_timer\*(C'\fR), absolute timers
228     with customised rescheduling (\f(CW\*(C`ev_periodic\*(C'\fR), synchronous signals
229     (\f(CW\*(C`ev_signal\*(C'\fR), process status change events (\f(CW\*(C`ev_child\*(C'\fR), and event
230     watchers dealing with the event loop mechanism itself (\f(CW\*(C`ev_idle\*(C'\fR,
231 root 1.28 \&\f(CW\*(C`ev_embed\*(C'\fR, \f(CW\*(C`ev_prepare\*(C'\fR and \f(CW\*(C`ev_check\*(C'\fR watchers) as well as
232     file watchers (\f(CW\*(C`ev_stat\*(C'\fR) and even limited support for fork events
233     (\f(CW\*(C`ev_fork\*(C'\fR).
234     .PP
235     It also is quite fast (see this
236     benchmark comparing it to libevent
237     for example).
238 root 1.59 .Sh "\s-1CONVENTIONS\s0"
239     .IX Subsection "CONVENTIONS"
240 root 1.61 Libev is very configurable. In this manual the default (and most common)
241     configuration will be described, which supports multiple event loops. For
242     more info about various configuration options please have a look at
243     \&\fB\s-1EMBED\s0\fR section in this manual. If libev was configured without support
244     for multiple event loops, then all functions taking an initial argument of
245     name \f(CW\*(C`loop\*(C'\fR (which is always of type \f(CW\*(C`struct ev_loop *\*(C'\fR) will not have
246     this argument.
247 root 1.59 .Sh "\s-1TIME\s0 \s-1REPRESENTATION\s0"
248     .IX Subsection "TIME REPRESENTATION"
249 root 1.1 Libev represents time as a single floating point number, representing the
250     (fractional) number of seconds since the (\s-1POSIX\s0) epoch (somewhere near
251     the beginning of 1970, details are complicated, don't ask). This type is
252     called \f(CW\*(C`ev_tstamp\*(C'\fR, which is what you should use too. It usually aliases
253 root 1.9 to the \f(CW\*(C`double\*(C'\fR type in C, and when you need to do any calculations on
254 root 1.68 it, you should treat it as some floating point value. Unlike the name
255 root 1.52 component \f(CW\*(C`stamp\*(C'\fR might indicate, it is also used for time differences
256     throughout libev.
257 root 1.67 .SH "ERROR HANDLING"
258     .IX Header "ERROR HANDLING"
259     Libev knows three classes of errors: operating system errors, usage errors
260     and internal errors (bugs).
261     .PP
262     When libev catches an operating system error it cannot handle (for example
263 root 1.68 a system call indicating a condition libev cannot fix), it calls the callback
264 root 1.67 set via \f(CW\*(C`ev_set_syserr_cb\*(C'\fR, which is supposed to fix the problem or
265     abort. The default is to print a diagnostic message and to call \f(CW\*(C`abort
266     ()\*(C'\fR.
267     .PP
268     When libev detects a usage error such as a negative timer interval, then
269     it will print a diagnostic message and abort (via the \f(CW\*(C`assert\*(C'\fR mechanism,
270     so \f(CW\*(C`NDEBUG\*(C'\fR will disable this checking): these are programming errors in
271     the libev caller and need to be fixed there.
272     .PP
273     Libev also has a few internal error-checking \f(CW\*(C`assert\*(C'\fRions, and also has
274     extensive consistency checking code. These do not trigger under normal
275     circumstances, as they indicate either a bug in libev or worse.
276 root 1.1 .SH "GLOBAL FUNCTIONS"
277     .IX Header "GLOBAL FUNCTIONS"
278     These functions can be called anytime, even before initialising the
279     library in any way.
280     .IP "ev_tstamp ev_time ()" 4
281     .IX Item "ev_tstamp ev_time ()"
282 root 1.2 Returns the current time as libev would use it. Please note that the
283     \&\f(CW\*(C`ev_now\*(C'\fR function is usually faster and also often returns the timestamp
284     you actually want to know.
285 root 1.57 .IP "ev_sleep (ev_tstamp interval)" 4
286     .IX Item "ev_sleep (ev_tstamp interval)"
287 root 1.56 Sleep for the given interval: The current thread will be blocked until
288     either it is interrupted or the given time interval has passed. Basically
289 root 1.68 this is a sub-second-resolution \f(CW\*(C`sleep ()\*(C'\fR.
290 root 1.1 .IP "int ev_version_major ()" 4
291     .IX Item "int ev_version_major ()"
292     .PD 0
293     .IP "int ev_version_minor ()" 4
294     .IX Item "int ev_version_minor ()"
295     .PD
296 root 1.48 You can find out the major and minor \s-1ABI\s0 version numbers of the library
297 root 1.1 you linked against by calling the functions \f(CW\*(C`ev_version_major\*(C'\fR and
298     \&\f(CW\*(C`ev_version_minor\*(C'\fR. If you want, you can compare against the global
299     symbols \f(CW\*(C`EV_VERSION_MAJOR\*(C'\fR and \f(CW\*(C`EV_VERSION_MINOR\*(C'\fR, which specify the
300     version of the library your program was compiled against.
301     .Sp
302 root 1.48 These version numbers refer to the \s-1ABI\s0 version of the library, not the
303     release version.
304 root 1.47 .Sp
305 root 1.1 Usually, it's a good idea to terminate if the major versions mismatch,
306 root 1.47 as this indicates an incompatible change. Minor versions are usually
307 root 1.1 compatible to older versions, so a larger minor version alone is usually
308     not a problem.
309 root 1.9 .Sp
310 root 1.28 Example: Make sure we haven't accidentally been linked against the wrong
311     version.
312 root 1.9 .Sp
313     .Vb 3
314 root 1.68 \& assert (("libev version mismatch",
315     \& ev_version_major () == EV_VERSION_MAJOR
316     \& && ev_version_minor () >= EV_VERSION_MINOR));
317 root 1.9 .Ve
318 root 1.6 .IP "unsigned int ev_supported_backends ()" 4
319     .IX Item "unsigned int ev_supported_backends ()"
320     Return the set of all backends (i.e. their corresponding \f(CW\*(C`EV_BACKEND_*\*(C'\fR
321     value) compiled into this binary of libev (independent of their
322     availability on the system you are running on). See \f(CW\*(C`ev_default_loop\*(C'\fR for
323     a description of the set values.
324 root 1.9 .Sp
325     Example: make sure we have the epoll method, because yeah this is cool and
326     a must have and can we have a torrent of it please!!!11
327     .Sp
328     .Vb 2
329 root 1.68 \& assert (("sorry, no epoll, no sex",
330     \& ev_supported_backends () & EVBACKEND_EPOLL));
331 root 1.9 .Ve
332 root 1.6 .IP "unsigned int ev_recommended_backends ()" 4
333     .IX Item "unsigned int ev_recommended_backends ()"
334     Return the set of all backends compiled into this binary of libev and also
335     recommended for this platform. This set is often smaller than the one
336     returned by \f(CW\*(C`ev_supported_backends\*(C'\fR, as for example kqueue is broken on
337 root 1.68 most BSDs and will not be auto-detected unless you explicitly request it
338 root 1.6 (assuming you know what you are doing). This is the set of backends that
339 root 1.8 libev will probe for if you specify no backends explicitly.
340 root 1.10 .IP "unsigned int ev_embeddable_backends ()" 4
341     .IX Item "unsigned int ev_embeddable_backends ()"
342     Returns the set of backends that are embeddable in other event loops. This
343 root 1.60 is the theoretical, all-platform, value. To find which backends
344 root 1.10 might be supported on the current system, you would need to look at
345     \&\f(CW\*(C`ev_embeddable_backends () & ev_supported_backends ()\*(C'\fR, likewise for
346     recommended ones.
347     .Sp
348     See the description of \f(CW\*(C`ev_embed\*(C'\fR watchers for more info.
349 root 1.32 .IP "ev_set_allocator (void *(*cb)(void *ptr, long size))" 4
350     .IX Item "ev_set_allocator (void *(*cb)(void *ptr, long size))"
351     Sets the allocation function to use (the prototype is similar \- the
352 root 1.64 semantics are identical to the \f(CW\*(C`realloc\*(C'\fR C89/SuS/POSIX function). It is
353     used to allocate and free memory (no surprises here). If it returns zero
354     when memory needs to be allocated (\f(CW\*(C`size != 0\*(C'\fR), the library might abort
355     or take some potentially destructive action.
356     .Sp
357     Since some systems (at least OpenBSD and Darwin) fail to implement
358     correct \f(CW\*(C`realloc\*(C'\fR semantics, libev will use a wrapper around the system
359     \&\f(CW\*(C`realloc\*(C'\fR and \f(CW\*(C`free\*(C'\fR functions by default.
360 root 1.1 .Sp
361     You could override this function in high-availability programs to, say,
362     free some memory if it cannot allocate memory, to use a special allocator,
363     or even to sleep a while and retry until some memory is available.
364 root 1.9 .Sp
365 root 1.28 Example: Replace the libev allocator with one that waits a bit and then
366 root 1.64 retries (example requires a standards-compliant \f(CW\*(C`realloc\*(C'\fR).
367 root 1.9 .Sp
368     .Vb 6
369     \& static void *
370 root 1.26 \& persistent_realloc (void *ptr, size_t size)
371 root 1.9 \& {
372     \& for (;;)
373     \& {
374     \& void *newptr = realloc (ptr, size);
375 root 1.60 \&
376 root 1.9 \& if (newptr)
377     \& return newptr;
378 root 1.60 \&
379 root 1.9 \& sleep (60);
380     \& }
381     \& }
382 root 1.60 \&
383 root 1.9 \& ...
384     \& ev_set_allocator (persistent_realloc);
385     .Ve
386 root 1.1 .IP "ev_set_syserr_cb (void (*cb)(const char *msg));" 4
387     .IX Item "ev_set_syserr_cb (void (*cb)(const char *msg));"
388 root 1.68 Set the callback function to call on a retryable system call error (such
389 root 1.1 as failed select, poll, epoll_wait). The message is a printable string
390     indicating the system call or subsystem causing the problem. If this
391 root 1.68 callback is set, then libev will expect it to remedy the situation, no
392 root 1.1 matter what, when it returns. That is, libev will generally retry the
393     requested operation, or, if the condition doesn't go away, do bad stuff
394     (such as abort).
395 root 1.9 .Sp
396 root 1.28 Example: This is basically the same thing that libev does internally, too.
397 root 1.9 .Sp
398     .Vb 6
399     \& static void
400     \& fatal_error (const char *msg)
401     \& {
402     \& perror (msg);
403     \& abort ();
404     \& }
405 root 1.60 \&
406 root 1.9 \& ...
407     \& ev_set_syserr_cb (fatal_error);
408     .Ve
409 root 1.1 .SH "FUNCTIONS CONTROLLING THE EVENT LOOP"
410     .IX Header "FUNCTIONS CONTROLLING THE EVENT LOOP"
411     An event loop is described by a \f(CW\*(C`struct ev_loop *\*(C'\fR. The library knows two
412     types of such loops, the \fIdefault\fR loop, which supports signals and child
413     events, and dynamically created loops which do not.
414     .IP "struct ev_loop *ev_default_loop (unsigned int flags)" 4
415     .IX Item "struct ev_loop *ev_default_loop (unsigned int flags)"
416     This will initialise the default event loop if it hasn't been initialised
417     yet and return it. If the default loop could not be initialised, returns
418     false. If it already was initialised it simply returns it (and ignores the
419 root 1.6 flags. If that is troubling you, check \f(CW\*(C`ev_backend ()\*(C'\fR afterwards).
420 root 1.1 .Sp
421     If you don't know what event loop to use, use the one returned from this
422     function.
423     .Sp
424 root 1.63 Note that this function is \fInot\fR thread-safe, so if you want to use it
425     from multiple threads, you have to lock (note also that this is unlikely,
426     as loops cannot bes hared easily between threads anyway).
427     .Sp
428 root 1.60 The default loop is the only loop that can handle \f(CW\*(C`ev_signal\*(C'\fR and
429     \&\f(CW\*(C`ev_child\*(C'\fR watchers, and to do this, it always registers a handler
430 root 1.68 for \f(CW\*(C`SIGCHLD\*(C'\fR. If this is a problem for your application you can either
431 root 1.60 create a dynamic loop with \f(CW\*(C`ev_loop_new\*(C'\fR that doesn't do that, or you
432     can simply overwrite the \f(CW\*(C`SIGCHLD\*(C'\fR signal handler \fIafter\fR calling
433     \&\f(CW\*(C`ev_default_init\*(C'\fR.
434     .Sp
435 root 1.1 The flags argument can be used to specify special behaviour or specific
436 root 1.8 backends to use, and is usually specified as \f(CW0\fR (or \f(CW\*(C`EVFLAG_AUTO\*(C'\fR).
437 root 1.1 .Sp
438 root 1.8 The following flags are supported:
439 root 1.1 .RS 4
440     .ie n .IP """EVFLAG_AUTO""" 4
441     .el .IP "\f(CWEVFLAG_AUTO\fR" 4
442     .IX Item "EVFLAG_AUTO"
443     The default flags value. Use this if you have no clue (it's the right
444     thing, believe me).
445     .ie n .IP """EVFLAG_NOENV""" 4
446     .el .IP "\f(CWEVFLAG_NOENV\fR" 4
447     .IX Item "EVFLAG_NOENV"
448 root 1.68 If this flag bit is or'ed into the flag value (or the program runs setuid
449 root 1.1 or setgid) then libev will \fInot\fR look at the environment variable
450     \&\f(CW\*(C`LIBEV_FLAGS\*(C'\fR. Otherwise (the default), this environment variable will
451     override the flags completely if it is found in the environment. This is
452     useful to try out specific backends to test their performance, or to work
453     around bugs.
454 root 1.35 .ie n .IP """EVFLAG_FORKCHECK""" 4
455     .el .IP "\f(CWEVFLAG_FORKCHECK\fR" 4
456     .IX Item "EVFLAG_FORKCHECK"
457     Instead of calling \f(CW\*(C`ev_default_fork\*(C'\fR or \f(CW\*(C`ev_loop_fork\*(C'\fR manually after
458     a fork, you can also make libev check for a fork in each iteration by
459     enabling this flag.
460     .Sp
461     This works by calling \f(CW\*(C`getpid ()\*(C'\fR on every iteration of the loop,
462     and thus this might slow down your event loop if you do a lot of loop
463 root 1.37 iterations and little real work, but is usually not noticeable (on my
464 root 1.61 GNU/Linux system for example, \f(CW\*(C`getpid\*(C'\fR is actually a simple 5\-insn sequence
465 root 1.68 without a system call and thus \fIvery\fR fast, but my GNU/Linux system also has
466 root 1.35 \&\f(CW\*(C`pthread_atfork\*(C'\fR which is even faster).
467     .Sp
468     The big advantage of this flag is that you can forget about fork (and
469     forget about forgetting to tell libev about forking) when you use this
470     flag.
471     .Sp
472 root 1.68 This flag setting cannot be overridden or specified in the \f(CW\*(C`LIBEV_FLAGS\*(C'\fR
473 root 1.35 environment variable.
474 root 1.6 .ie n .IP """EVBACKEND_SELECT"" (value 1, portable select backend)" 4
475     .el .IP "\f(CWEVBACKEND_SELECT\fR (value 1, portable select backend)" 4
476     .IX Item "EVBACKEND_SELECT (value 1, portable select backend)"
477 root 1.3 This is your standard \fIselect\fR\|(2) backend. Not \fIcompletely\fR standard, as
478     libev tries to roll its own fd_set with no limits on the number of fds,
479     but if that fails, expect a fairly low limit on the number of fds when
480 root 1.58 using this backend. It doesn't scale too well (O(highest_fd)), but its
481 root 1.60 usually the fastest backend for a low number of (low-numbered :) fds.
482 root 1.58 .Sp
483     To get good performance out of this backend you need a high amount of
484 root 1.68 parallelism (most of the file descriptors should be busy). If you are
485 root 1.58 writing a server, you should \f(CW\*(C`accept ()\*(C'\fR in a loop to accept as many
486     connections as possible during one iteration. You might also want to have
487     a look at \f(CW\*(C`ev_set_io_collect_interval ()\*(C'\fR to increase the amount of
488 root 1.67 readiness notifications you get per iteration.
489 root 1.6 .ie n .IP """EVBACKEND_POLL"" (value 2, poll backend, available everywhere except on windows)" 4
490     .el .IP "\f(CWEVBACKEND_POLL\fR (value 2, poll backend, available everywhere except on windows)" 4
491     .IX Item "EVBACKEND_POLL (value 2, poll backend, available everywhere except on windows)"
492 root 1.58 And this is your standard \fIpoll\fR\|(2) backend. It's more complicated
493     than select, but handles sparse fds better and has no artificial
494     limit on the number of fds you can use (except it will slow down
495     considerably with a lot of inactive fds). It scales similarly to select,
496     i.e. O(total_fds). See the entry for \f(CW\*(C`EVBACKEND_SELECT\*(C'\fR, above, for
497     performance tips.
498 root 1.6 .ie n .IP """EVBACKEND_EPOLL"" (value 4, Linux)" 4
499     .el .IP "\f(CWEVBACKEND_EPOLL\fR (value 4, Linux)" 4
500     .IX Item "EVBACKEND_EPOLL (value 4, Linux)"
501 root 1.3 For few fds, this backend is a bit little slower than poll and select,
502 root 1.54 but it scales phenomenally better. While poll and select usually scale
503     like O(total_fds) where n is the total number of fds (or the highest fd),
504     epoll scales either O(1) or O(active_fds). The epoll design has a number
505     of shortcomings, such as silently dropping events in some hard-to-detect
506 root 1.68 cases and requiring a system call per fd change, no fork support and bad
507 root 1.58 support for dup.
508 root 1.3 .Sp
509 root 1.54 While stopping, setting and starting an I/O watcher in the same iteration
510 root 1.68 will result in some caching, there is still a system call per such incident
511 root 1.3 (because the fd could point to a different file description now), so its
512 root 1.54 best to avoid that. Also, \f(CW\*(C`dup ()\*(C'\fR'ed file descriptors might not work
513     very well if you register events for both fds.
514 root 1.7 .Sp
515     Please note that epoll sometimes generates spurious notifications, so you
516     need to use non-blocking I/O or other means to avoid blocking when no data
517     (or space) is available.
518 root 1.58 .Sp
519     Best performance from this backend is achieved by not unregistering all
520     watchers for a file descriptor until it has been closed, if possible, i.e.
521     keep at least one watcher active per fd at all times.
522     .Sp
523 root 1.68 While nominally embeddable in other event loops, this feature is broken in
524 root 1.58 all kernel versions tested so far.
525 root 1.6 .ie n .IP """EVBACKEND_KQUEUE"" (value 8, most \s-1BSD\s0 clones)" 4
526     .el .IP "\f(CWEVBACKEND_KQUEUE\fR (value 8, most \s-1BSD\s0 clones)" 4
527     .IX Item "EVBACKEND_KQUEUE (value 8, most BSD clones)"
528 root 1.3 Kqueue deserves special mention, as at the time of this writing, it
529 root 1.57 was broken on all BSDs except NetBSD (usually it doesn't work reliably
530     with anything but sockets and pipes, except on Darwin, where of course
531 root 1.68 it's completely useless). For this reason it's not being \*(L"auto-detected\*(R"
532 root 1.8 unless you explicitly specify it explicitly in the flags (i.e. using
533 root 1.54 \&\f(CW\*(C`EVBACKEND_KQUEUE\*(C'\fR) or libev was compiled on a known-to-be-good (\-enough)
534     system like NetBSD.
535 root 1.3 .Sp
536 root 1.57 You still can embed kqueue into a normal poll or select backend and use it
537     only for sockets (after having made sure that sockets work with kqueue on
538     the target platform). See \f(CW\*(C`ev_embed\*(C'\fR watchers for more info.
539     .Sp
540 root 1.3 It scales in the same way as the epoll backend, but the interface to the
541 root 1.57 kernel is more efficient (which says nothing about its actual speed, of
542     course). While stopping, setting and starting an I/O watcher does never
543 root 1.68 cause an extra system call as with \f(CW\*(C`EVBACKEND_EPOLL\*(C'\fR, it still adds up to
544 root 1.57 two event changes per incident, support for \f(CW\*(C`fork ()\*(C'\fR is very bad and it
545     drops fds silently in similarly hard-to-detect cases.
546 root 1.58 .Sp
547     This backend usually performs well under most conditions.
548     .Sp
549     While nominally embeddable in other event loops, this doesn't work
550     everywhere, so you might need to test for this. And since it is broken
551     almost everywhere, you should only use it when you have a lot of sockets
552     (for which it usually works), by embedding it into another event loop
553     (e.g. \f(CW\*(C`EVBACKEND_SELECT\*(C'\fR or \f(CW\*(C`EVBACKEND_POLL\*(C'\fR) and using it only for
554     sockets.
555 root 1.6 .ie n .IP """EVBACKEND_DEVPOLL"" (value 16, Solaris 8)" 4
556     .el .IP "\f(CWEVBACKEND_DEVPOLL\fR (value 16, Solaris 8)" 4
557     .IX Item "EVBACKEND_DEVPOLL (value 16, Solaris 8)"
558 root 1.58 This is not implemented yet (and might never be, unless you send me an
559     implementation). According to reports, \f(CW\*(C`/dev/poll\*(C'\fR only supports sockets
560     and is not embeddable, which would limit the usefulness of this backend
561     immensely.
562 root 1.6 .ie n .IP """EVBACKEND_PORT"" (value 32, Solaris 10)" 4
563     .el .IP "\f(CWEVBACKEND_PORT\fR (value 32, Solaris 10)" 4
564     .IX Item "EVBACKEND_PORT (value 32, Solaris 10)"
565 root 1.54 This uses the Solaris 10 event port mechanism. As with everything on Solaris,
566 root 1.3 it's really slow, but it still scales very well (O(active_fds)).
567 root 1.7 .Sp
568 root 1.68 Please note that Solaris event ports can deliver a lot of spurious
569 root 1.7 notifications, so you need to use non-blocking I/O or other means to avoid
570     blocking when no data (or space) is available.
571 root 1.58 .Sp
572     While this backend scales well, it requires one system call per active
573     file descriptor per loop iteration. For small and medium numbers of file
574     descriptors a \*(L"slow\*(R" \f(CW\*(C`EVBACKEND_SELECT\*(C'\fR or \f(CW\*(C`EVBACKEND_POLL\*(C'\fR backend
575     might perform better.
576 root 1.60 .Sp
577 root 1.67 On the positive side, ignoring the spurious readiness notifications, this
578 root 1.60 backend actually performed to specification in all tests and is fully
579     embeddable, which is a rare feat among the OS-specific backends.
580 root 1.6 .ie n .IP """EVBACKEND_ALL""" 4
581     .el .IP "\f(CWEVBACKEND_ALL\fR" 4
582     .IX Item "EVBACKEND_ALL"
583 root 1.4 Try all backends (even potentially broken ones that wouldn't be tried
584     with \f(CW\*(C`EVFLAG_AUTO\*(C'\fR). Since this is a mask, you can do stuff such as
585 root 1.6 \&\f(CW\*(C`EVBACKEND_ALL & ~EVBACKEND_KQUEUE\*(C'\fR.
586 root 1.58 .Sp
587     It is definitely not recommended to use this flag.
588 root 1.1 .RE
589     .RS 4
590 root 1.3 .Sp
591 root 1.68 If one or more of these are or'ed into the flags value, then only these
592 root 1.60 backends will be tried (in the reverse order as listed here). If none are
593     specified, all backends in \f(CW\*(C`ev_recommended_backends ()\*(C'\fR will be tried.
594 root 1.8 .Sp
595     The most typical usage is like this:
596     .Sp
597     .Vb 2
598 root 1.68 \& if (!ev_default_loop (0))
599     \& fatal ("could not initialise libev, bad $LIBEV_FLAGS in environment?");
600 root 1.8 .Ve
601     .Sp
602     Restrict libev to the select and poll backends, and do not allow
603     environment settings to be taken into account:
604     .Sp
605     .Vb 1
606 root 1.68 \& ev_default_loop (EVBACKEND_POLL | EVBACKEND_SELECT | EVFLAG_NOENV);
607 root 1.8 .Ve
608     .Sp
609     Use whatever libev has to offer, but make sure that kqueue is used if
610     available (warning, breaks stuff, best use only with your own private
611     event loop and only if you know the \s-1OS\s0 supports your types of fds):
612     .Sp
613     .Vb 1
614 root 1.68 \& ev_default_loop (ev_recommended_backends () | EVBACKEND_KQUEUE);
615 root 1.8 .Ve
616 root 1.1 .RE
617     .IP "struct ev_loop *ev_loop_new (unsigned int flags)" 4
618     .IX Item "struct ev_loop *ev_loop_new (unsigned int flags)"
619     Similar to \f(CW\*(C`ev_default_loop\*(C'\fR, but always creates a new event loop that is
620     always distinct from the default loop. Unlike the default loop, it cannot
621     handle signal and child watchers, and attempts to do so will be greeted by
622     undefined behaviour (or a failed assertion if assertions are enabled).
623 root 1.9 .Sp
624 root 1.63 Note that this function \fIis\fR thread-safe, and the recommended way to use
625     libev with threads is indeed to create one loop per thread, and using the
626     default loop in the \*(L"main\*(R" or \*(L"initial\*(R" thread.
627     .Sp
628 root 1.28 Example: Try to create a event loop that uses epoll and nothing else.
629 root 1.9 .Sp
630     .Vb 3
631 root 1.68 \& struct ev_loop *epoller = ev_loop_new (EVBACKEND_EPOLL | EVFLAG_NOENV);
632     \& if (!epoller)
633     \& fatal ("no epoll found here, maybe it hides under your chair");
634 root 1.9 .Ve
635 root 1.1 .IP "ev_default_destroy ()" 4
636     .IX Item "ev_default_destroy ()"
637     Destroys the default loop again (frees all memory and kernel state
638 root 1.12 etc.). None of the active event watchers will be stopped in the normal
639     sense, so e.g. \f(CW\*(C`ev_is_active\*(C'\fR might still return true. It is your
640 root 1.68 responsibility to either stop all watchers cleanly yourself \fIbefore\fR
641 root 1.12 calling this function, or cope with the fact afterwards (which is usually
642 root 1.52 the easiest thing, you can just ignore the watchers and/or \f(CW\*(C`free ()\*(C'\fR them
643 root 1.12 for example).
644 root 1.52 .Sp
645 root 1.54 Note that certain global state, such as signal state, will not be freed by
646 root 1.52 this function, and related watchers (such as signal and child watchers)
647     would need to be stopped manually.
648     .Sp
649     In general it is not advisable to call this function except in the
650     rare occasion where you really need to free e.g. the signal handling
651     pipe fds. If you need dynamically allocated loops it is better to use
652     \&\f(CW\*(C`ev_loop_new\*(C'\fR and \f(CW\*(C`ev_loop_destroy\*(C'\fR).
653 root 1.1 .IP "ev_loop_destroy (loop)" 4
654     .IX Item "ev_loop_destroy (loop)"
655     Like \f(CW\*(C`ev_default_destroy\*(C'\fR, but destroys an event loop created by an
656     earlier call to \f(CW\*(C`ev_loop_new\*(C'\fR.
657     .IP "ev_default_fork ()" 4
658     .IX Item "ev_default_fork ()"
659 root 1.60 This function sets a flag that causes subsequent \f(CW\*(C`ev_loop\*(C'\fR iterations
660     to reinitialise the kernel state for backends that have one. Despite the
661     name, you can call it anytime, but it makes most sense after forking, in
662     the child process (or both child and parent, but that again makes little
663     sense). You \fImust\fR call it in the child before using any of the libev
664     functions, and it will only take effect at the next \f(CW\*(C`ev_loop\*(C'\fR iteration.
665     .Sp
666     On the other hand, you only need to call this function in the child
667     process if and only if you want to use the event library in the child. If
668     you just fork+exec, you don't have to call it at all.
669 root 1.1 .Sp
670     The function itself is quite fast and it's usually not a problem to call
671     it just in case after a fork. To make this easy, the function will fit in
672     quite nicely into a call to \f(CW\*(C`pthread_atfork\*(C'\fR:
673     .Sp
674     .Vb 1
675     \& pthread_atfork (0, 0, ev_default_fork);
676     .Ve
677     .IP "ev_loop_fork (loop)" 4
678     .IX Item "ev_loop_fork (loop)"
679     Like \f(CW\*(C`ev_default_fork\*(C'\fR, but acts on an event loop created by
680     \&\f(CW\*(C`ev_loop_new\*(C'\fR. Yes, you have to call this on every allocated event loop
681     after fork, and how you do this is entirely your own problem.
682 root 1.61 .IP "int ev_is_default_loop (loop)" 4
683     .IX Item "int ev_is_default_loop (loop)"
684     Returns true when the given loop actually is the default loop, false otherwise.
685 root 1.37 .IP "unsigned int ev_loop_count (loop)" 4
686     .IX Item "unsigned int ev_loop_count (loop)"
687     Returns the count of loop iterations for the loop, which is identical to
688     the number of times libev did poll for new events. It starts at \f(CW0\fR and
689     happily wraps around with enough iterations.
690     .Sp
691     This value can sometimes be useful as a generation counter of sorts (it
692     \&\*(L"ticks\*(R" the number of loop iterations), as it roughly corresponds with
693     \&\f(CW\*(C`ev_prepare\*(C'\fR and \f(CW\*(C`ev_check\*(C'\fR calls.
694 root 1.6 .IP "unsigned int ev_backend (loop)" 4
695     .IX Item "unsigned int ev_backend (loop)"
696     Returns one of the \f(CW\*(C`EVBACKEND_*\*(C'\fR flags indicating the event backend in
697 root 1.1 use.
698     .IP "ev_tstamp ev_now (loop)" 4
699     .IX Item "ev_tstamp ev_now (loop)"
700     Returns the current \*(L"event loop time\*(R", which is the time the event loop
701 root 1.9 received events and started processing them. This timestamp does not
702     change as long as callbacks are being processed, and this is also the base
703     time used for relative timers. You can treat it as the timestamp of the
704 root 1.54 event occurring (or more correctly, libev finding out about it).
705 root 1.1 .IP "ev_loop (loop, int flags)" 4
706     .IX Item "ev_loop (loop, int flags)"
707     Finally, this is it, the event handler. This function usually is called
708     after you initialised all your watchers and you want to start handling
709     events.
710     .Sp
711 root 1.8 If the flags argument is specified as \f(CW0\fR, it will not return until
712     either no event watchers are active anymore or \f(CW\*(C`ev_unloop\*(C'\fR was called.
713 root 1.1 .Sp
714 root 1.9 Please note that an explicit \f(CW\*(C`ev_unloop\*(C'\fR is usually better than
715     relying on all watchers to be stopped when deciding when a program has
716     finished (especially in interactive programs), but having a program that
717     automatically loops as long as it has to and no longer by virtue of
718     relying on its watchers stopping correctly is a thing of beauty.
719     .Sp
720 root 1.1 A flags value of \f(CW\*(C`EVLOOP_NONBLOCK\*(C'\fR will look for new events, will handle
721     those events and any outstanding ones, but will not block your process in
722     case there are no events and will return after one iteration of the loop.
723     .Sp
724     A flags value of \f(CW\*(C`EVLOOP_ONESHOT\*(C'\fR will look for new events (waiting if
725 root 1.68 necessary) and will handle those and any outstanding ones. It will block
726 root 1.1 your process until at least one new event arrives, and will return after
727 root 1.8 one iteration of the loop. This is useful if you are waiting for some
728     external event in conjunction with something not expressible using other
729     libev watchers. However, a pair of \f(CW\*(C`ev_prepare\*(C'\fR/\f(CW\*(C`ev_check\*(C'\fR watchers is
730     usually a better approach for this kind of thing.
731     .Sp
732     Here are the gory details of what \f(CW\*(C`ev_loop\*(C'\fR does:
733     .Sp
734 root 1.60 .Vb 10
735     \& \- Before the first iteration, call any pending watchers.
736     \& * If EVFLAG_FORKCHECK was used, check for a fork.
737     \& \- If a fork was detected, queue and call all fork watchers.
738     \& \- Queue and call all prepare watchers.
739     \& \- If we have been forked, recreate the kernel state.
740     \& \- Update the kernel state with all outstanding changes.
741     \& \- Update the "event loop time".
742     \& \- Calculate for how long to sleep or block, if at all
743     \& (active idle watchers, EVLOOP_NONBLOCK or not having
744     \& any active watchers at all will result in not sleeping).
745     \& \- Sleep if the I/O and timer collect interval say so.
746     \& \- Block the process, waiting for any events.
747     \& \- Queue all outstanding I/O (fd) events.
748     \& \- Update the "event loop time" and do time jump handling.
749     \& \- Queue all outstanding timers.
750     \& \- Queue all outstanding periodics.
751     \& \- If no events are pending now, queue all idle watchers.
752     \& \- Queue all check watchers.
753     \& \- Call all queued watchers in reverse order (i.e. check watchers first).
754 root 1.8 \& Signals and child watchers are implemented as I/O watchers, and will
755     \& be handled here by queueing them when their watcher gets executed.
756 root 1.60 \& \- If ev_unloop has been called, or EVLOOP_ONESHOT or EVLOOP_NONBLOCK
757     \& were used, or there are no active watchers, return, otherwise
758     \& continue with step *.
759 root 1.2 .Ve
760 root 1.9 .Sp
761 root 1.60 Example: Queue some jobs and then loop until no events are outstanding
762 root 1.9 anymore.
763     .Sp
764     .Vb 4
765     \& ... queue jobs here, make sure they register event watchers as long
766     \& ... as they still have work to do (even an idle watcher will do..)
767     \& ev_loop (my_loop, 0);
768     \& ... jobs done. yeah!
769     .Ve
770 root 1.1 .IP "ev_unloop (loop, how)" 4
771     .IX Item "ev_unloop (loop, how)"
772     Can be used to make a call to \f(CW\*(C`ev_loop\*(C'\fR return early (but only after it
773     has processed all outstanding events). The \f(CW\*(C`how\*(C'\fR argument must be either
774     \&\f(CW\*(C`EVUNLOOP_ONE\*(C'\fR, which will make the innermost \f(CW\*(C`ev_loop\*(C'\fR call return, or
775     \&\f(CW\*(C`EVUNLOOP_ALL\*(C'\fR, which will make all nested \f(CW\*(C`ev_loop\*(C'\fR calls return.
776 root 1.60 .Sp
777     This \*(L"unloop state\*(R" will be cleared when entering \f(CW\*(C`ev_loop\*(C'\fR again.
778 root 1.1 .IP "ev_ref (loop)" 4
779     .IX Item "ev_ref (loop)"
780     .PD 0
781     .IP "ev_unref (loop)" 4
782     .IX Item "ev_unref (loop)"
783     .PD
784     Ref/unref can be used to add or remove a reference count on the event
785     loop: Every watcher keeps one reference, and as long as the reference
786     count is nonzero, \f(CW\*(C`ev_loop\*(C'\fR will not return on its own. If you have
787     a watcher you never unregister that should not keep \f(CW\*(C`ev_loop\*(C'\fR from
788     returning, \fIev_unref()\fR after starting, and \fIev_ref()\fR before stopping it. For
789     example, libev itself uses this for its internal signal pipe: It is not
790     visible to the libev user and should not keep \f(CW\*(C`ev_loop\*(C'\fR from exiting if
791     no event watchers registered by it are active. It is also an excellent
792     way to do this for generic recurring timers or from within third-party
793 root 1.60 libraries. Just remember to \fIunref after start\fR and \fIref before stop\fR
794     (but only if the watcher wasn't active before, or was active before,
795     respectively).
796 root 1.9 .Sp
797 root 1.28 Example: Create a signal watcher, but keep it from keeping \f(CW\*(C`ev_loop\*(C'\fR
798 root 1.9 running when nothing else is active.
799     .Sp
800     .Vb 4
801 root 1.68 \& struct ev_signal exitsig;
802     \& ev_signal_init (&exitsig, sig_cb, SIGINT);
803     \& ev_signal_start (loop, &exitsig);
804     \& evf_unref (loop);
805 root 1.9 .Ve
806     .Sp
807 root 1.28 Example: For some weird reason, unregister the above signal handler again.
808 root 1.9 .Sp
809     .Vb 2
810 root 1.68 \& ev_ref (loop);
811     \& ev_signal_stop (loop, &exitsig);
812 root 1.9 .Ve
813 root 1.57 .IP "ev_set_io_collect_interval (loop, ev_tstamp interval)" 4
814     .IX Item "ev_set_io_collect_interval (loop, ev_tstamp interval)"
815 root 1.56 .PD 0
816 root 1.57 .IP "ev_set_timeout_collect_interval (loop, ev_tstamp interval)" 4
817     .IX Item "ev_set_timeout_collect_interval (loop, ev_tstamp interval)"
818 root 1.56 .PD
819     These advanced functions influence the time that libev will spend waiting
820     for events. Both are by default \f(CW0\fR, meaning that libev will try to
821     invoke timer/periodic callbacks and I/O callbacks with minimum latency.
822     .Sp
823     Setting these to a higher value (the \f(CW\*(C`interval\*(C'\fR \fImust\fR be >= \f(CW0\fR)
824     allows libev to delay invocation of I/O and timer/periodic callbacks to
825     increase efficiency of loop iterations.
826     .Sp
827     The background is that sometimes your program runs just fast enough to
828     handle one (or very few) event(s) per loop iteration. While this makes
829     the program responsive, it also wastes a lot of \s-1CPU\s0 time to poll for new
830     events, especially with backends like \f(CW\*(C`select ()\*(C'\fR which have a high
831     overhead for the actual polling but can deliver many events at once.
832     .Sp
833     By setting a higher \fIio collect interval\fR you allow libev to spend more
834     time collecting I/O events, so you can handle more events per iteration,
835     at the cost of increasing latency. Timeouts (both \f(CW\*(C`ev_periodic\*(C'\fR and
836 root 1.58 \&\f(CW\*(C`ev_timer\*(C'\fR) will be not affected. Setting this to a non-null value will
837 root 1.57 introduce an additional \f(CW\*(C`ev_sleep ()\*(C'\fR call into most loop iterations.
838 root 1.56 .Sp
839     Likewise, by setting a higher \fItimeout collect interval\fR you allow libev
840     to spend more time collecting timeouts, at the expense of increased
841     latency (the watcher callback will be called later). \f(CW\*(C`ev_io\*(C'\fR watchers
842 root 1.57 will not be affected. Setting this to a non-null value will not introduce
843     any overhead in libev.
844 root 1.56 .Sp
845 root 1.68 Many (busy) programs can usually benefit by setting the I/O collect
846 root 1.57 interval to a value near \f(CW0.1\fR or so, which is often enough for
847     interactive servers (of course not for games), likewise for timeouts. It
848     usually doesn't make much sense to set it to a lower value than \f(CW0.01\fR,
849 root 1.68 as this approaches the timing granularity of most systems.
850 root 1.67 .IP "ev_loop_verify (loop)" 4
851     .IX Item "ev_loop_verify (loop)"
852     This function only does something when \f(CW\*(C`EV_VERIFY\*(C'\fR support has been
853     compiled in. It tries to go through all internal structures and checks
854     them for validity. If anything is found to be inconsistent, it will print
855     an error message to standard error and call \f(CW\*(C`abort ()\*(C'\fR.
856     .Sp
857     This can be used to catch bugs inside libev itself: under normal
858     circumstances, this function will never abort as of course libev keeps its
859     data structures consistent.
860 root 1.1 .SH "ANATOMY OF A WATCHER"
861     .IX Header "ANATOMY OF A WATCHER"
862     A watcher is a structure that you create and register to record your
863     interest in some event. For instance, if you want to wait for \s-1STDIN\s0 to
864     become readable, you would create an \f(CW\*(C`ev_io\*(C'\fR watcher for that:
865     .PP
866     .Vb 5
867 root 1.68 \& static void my_cb (struct ev_loop *loop, struct ev_io *w, int revents)
868     \& {
869     \& ev_io_stop (w);
870     \& ev_unloop (loop, EVUNLOOP_ALL);
871     \& }
872     \&
873     \& struct ev_loop *loop = ev_default_loop (0);
874     \& struct ev_io stdin_watcher;
875     \& ev_init (&stdin_watcher, my_cb);
876     \& ev_io_set (&stdin_watcher, STDIN_FILENO, EV_READ);
877     \& ev_io_start (loop, &stdin_watcher);
878     \& ev_loop (loop, 0);
879 root 1.1 .Ve
880     .PP
881     As you can see, you are responsible for allocating the memory for your
882     watcher structures (and it is usually a bad idea to do this on the stack,
883     although this can sometimes be quite valid).
884     .PP
885     Each watcher structure must be initialised by a call to \f(CW\*(C`ev_init
886     (watcher *, callback)\*(C'\fR, which expects a callback to be provided. This
887 root 1.68 callback gets invoked each time the event occurs (or, in the case of I/O
888 root 1.1 watchers, each time the event loop detects that the file descriptor given
889     is readable and/or writable).
890     .PP
891     Each watcher type has its own \f(CW\*(C`ev_<type>_set (watcher *, ...)\*(C'\fR macro
892     with arguments specific to this watcher type. There is also a macro
893     to combine initialisation and setting in one call: \f(CW\*(C`ev_<type>_init
894     (watcher *, callback, ...)\*(C'\fR.
895     .PP
896     To make the watcher actually watch out for events, you have to start it
897     with a watcher-specific start function (\f(CW\*(C`ev_<type>_start (loop, watcher
898     *)\*(C'\fR), and you can stop watching for events at any time by calling the
899     corresponding stop function (\f(CW\*(C`ev_<type>_stop (loop, watcher *)\*(C'\fR.
900     .PP
901     As long as your watcher is active (has been started but not stopped) you
902     must not touch the values stored in it. Most specifically you must never
903 root 1.11 reinitialise it or call its \f(CW\*(C`set\*(C'\fR macro.
904 root 1.1 .PP
905     Each and every callback receives the event loop pointer as first, the
906     registered watcher structure as second, and a bitset of received events as
907     third argument.
908     .PP
909     The received events usually include a single bit per event type received
910     (you can receive multiple events at the same time). The possible bit masks
911     are:
912     .ie n .IP """EV_READ""" 4
913     .el .IP "\f(CWEV_READ\fR" 4
914     .IX Item "EV_READ"
915     .PD 0
916     .ie n .IP """EV_WRITE""" 4
917     .el .IP "\f(CWEV_WRITE\fR" 4
918     .IX Item "EV_WRITE"
919     .PD
920     The file descriptor in the \f(CW\*(C`ev_io\*(C'\fR watcher has become readable and/or
921     writable.
922     .ie n .IP """EV_TIMEOUT""" 4
923     .el .IP "\f(CWEV_TIMEOUT\fR" 4
924     .IX Item "EV_TIMEOUT"
925     The \f(CW\*(C`ev_timer\*(C'\fR watcher has timed out.
926     .ie n .IP """EV_PERIODIC""" 4
927     .el .IP "\f(CWEV_PERIODIC\fR" 4
928     .IX Item "EV_PERIODIC"
929     The \f(CW\*(C`ev_periodic\*(C'\fR watcher has timed out.
930     .ie n .IP """EV_SIGNAL""" 4
931     .el .IP "\f(CWEV_SIGNAL\fR" 4
932     .IX Item "EV_SIGNAL"
933     The signal specified in the \f(CW\*(C`ev_signal\*(C'\fR watcher has been received by a thread.
934     .ie n .IP """EV_CHILD""" 4
935     .el .IP "\f(CWEV_CHILD\fR" 4
936     .IX Item "EV_CHILD"
937     The pid specified in the \f(CW\*(C`ev_child\*(C'\fR watcher has received a status change.
938 root 1.22 .ie n .IP """EV_STAT""" 4
939     .el .IP "\f(CWEV_STAT\fR" 4
940     .IX Item "EV_STAT"
941     The path specified in the \f(CW\*(C`ev_stat\*(C'\fR watcher changed its attributes somehow.
942 root 1.1 .ie n .IP """EV_IDLE""" 4
943     .el .IP "\f(CWEV_IDLE\fR" 4
944     .IX Item "EV_IDLE"
945     The \f(CW\*(C`ev_idle\*(C'\fR watcher has determined that you have nothing better to do.
946     .ie n .IP """EV_PREPARE""" 4
947     .el .IP "\f(CWEV_PREPARE\fR" 4
948     .IX Item "EV_PREPARE"
949     .PD 0
950     .ie n .IP """EV_CHECK""" 4
951     .el .IP "\f(CWEV_CHECK\fR" 4
952     .IX Item "EV_CHECK"
953     .PD
954     All \f(CW\*(C`ev_prepare\*(C'\fR watchers are invoked just \fIbefore\fR \f(CW\*(C`ev_loop\*(C'\fR starts
955     to gather new events, and all \f(CW\*(C`ev_check\*(C'\fR watchers are invoked just after
956     \&\f(CW\*(C`ev_loop\*(C'\fR has gathered them, but before it invokes any callbacks for any
957     received events. Callbacks of both watcher types can start and stop as
958     many watchers as they want, and all of them will be taken into account
959     (for example, a \f(CW\*(C`ev_prepare\*(C'\fR watcher might start an idle watcher to keep
960     \&\f(CW\*(C`ev_loop\*(C'\fR from blocking).
961 root 1.24 .ie n .IP """EV_EMBED""" 4
962     .el .IP "\f(CWEV_EMBED\fR" 4
963     .IX Item "EV_EMBED"
964     The embedded event loop specified in the \f(CW\*(C`ev_embed\*(C'\fR watcher needs attention.
965     .ie n .IP """EV_FORK""" 4
966     .el .IP "\f(CWEV_FORK\fR" 4
967     .IX Item "EV_FORK"
968     The event loop has been resumed in the child process after fork (see
969     \&\f(CW\*(C`ev_fork\*(C'\fR).
970 root 1.61 .ie n .IP """EV_ASYNC""" 4
971     .el .IP "\f(CWEV_ASYNC\fR" 4
972     .IX Item "EV_ASYNC"
973     The given async watcher has been asynchronously notified (see \f(CW\*(C`ev_async\*(C'\fR).
974 root 1.1 .ie n .IP """EV_ERROR""" 4
975     .el .IP "\f(CWEV_ERROR\fR" 4
976     .IX Item "EV_ERROR"
977 root 1.68 An unspecified error has occurred, the watcher has been stopped. This might
978 root 1.1 happen because the watcher could not be properly started because libev
979     ran out of memory, a file descriptor was found to be closed or any other
980     problem. You best act on it by reporting the problem and somehow coping
981     with the watcher being stopped.
982     .Sp
983     Libev will usually signal a few \*(L"dummy\*(R" events together with an error,
984     for example it might indicate that a fd is readable or writable, and if
985     your callbacks is well-written it can just attempt the operation and cope
986 root 1.68 with the error from \fIread()\fR or \fIwrite()\fR. This will not work in multi-threaded
987 root 1.1 programs, though, so beware.
988 root 1.17 .Sh "\s-1GENERIC\s0 \s-1WATCHER\s0 \s-1FUNCTIONS\s0"
989     .IX Subsection "GENERIC WATCHER FUNCTIONS"
990 root 1.11 In the following description, \f(CW\*(C`TYPE\*(C'\fR stands for the watcher type,
991     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.
992     .ie n .IP """ev_init"" (ev_TYPE *watcher, callback)" 4
993     .el .IP "\f(CWev_init\fR (ev_TYPE *watcher, callback)" 4
994     .IX Item "ev_init (ev_TYPE *watcher, callback)"
995     This macro initialises the generic portion of a watcher. The contents
996     of the watcher object can be arbitrary (so \f(CW\*(C`malloc\*(C'\fR will do). Only
997     the generic parts of the watcher are initialised, you \fIneed\fR to call
998     the type-specific \f(CW\*(C`ev_TYPE_set\*(C'\fR macro afterwards to initialise the
999     type-specific parts. For each type there is also a \f(CW\*(C`ev_TYPE_init\*(C'\fR macro
1000     which rolls both calls into one.
1001     .Sp
1002     You can reinitialise a watcher at any time as long as it has been stopped
1003     (or never started) and there are no pending events outstanding.
1004     .Sp
1005 root 1.17 The callback is always of type \f(CW\*(C`void (*)(ev_loop *loop, ev_TYPE *watcher,
1006 root 1.11 int revents)\*(C'\fR.
1007     .ie n .IP """ev_TYPE_set"" (ev_TYPE *, [args])" 4
1008     .el .IP "\f(CWev_TYPE_set\fR (ev_TYPE *, [args])" 4
1009     .IX Item "ev_TYPE_set (ev_TYPE *, [args])"
1010     This macro initialises the type-specific parts of a watcher. You need to
1011     call \f(CW\*(C`ev_init\*(C'\fR at least once before you call this macro, but you can
1012     call \f(CW\*(C`ev_TYPE_set\*(C'\fR any number of times. You must not, however, call this
1013     macro on a watcher that is active (it can be pending, however, which is a
1014     difference to the \f(CW\*(C`ev_init\*(C'\fR macro).
1015     .Sp
1016     Although some watcher types do not have type-specific arguments
1017     (e.g. \f(CW\*(C`ev_prepare\*(C'\fR) you still need to call its \f(CW\*(C`set\*(C'\fR macro.
1018     .ie n .IP """ev_TYPE_init"" (ev_TYPE *watcher, callback, [args])" 4
1019     .el .IP "\f(CWev_TYPE_init\fR (ev_TYPE *watcher, callback, [args])" 4
1020     .IX Item "ev_TYPE_init (ev_TYPE *watcher, callback, [args])"
1021 root 1.68 This convenience macro rolls both \f(CW\*(C`ev_init\*(C'\fR and \f(CW\*(C`ev_TYPE_set\*(C'\fR macro
1022     calls into a single call. This is the most convenient method to initialise
1023 root 1.11 a watcher. The same limitations apply, of course.
1024     .ie n .IP """ev_TYPE_start"" (loop *, ev_TYPE *watcher)" 4
1025     .el .IP "\f(CWev_TYPE_start\fR (loop *, ev_TYPE *watcher)" 4
1026     .IX Item "ev_TYPE_start (loop *, ev_TYPE *watcher)"
1027     Starts (activates) the given watcher. Only active watchers will receive
1028     events. If the watcher is already active nothing will happen.
1029     .ie n .IP """ev_TYPE_stop"" (loop *, ev_TYPE *watcher)" 4
1030     .el .IP "\f(CWev_TYPE_stop\fR (loop *, ev_TYPE *watcher)" 4
1031     .IX Item "ev_TYPE_stop (loop *, ev_TYPE *watcher)"
1032     Stops the given watcher again (if active) and clears the pending
1033     status. It is possible that stopped watchers are pending (for example,
1034     non-repeating timers are being stopped when they become pending), but
1035     \&\f(CW\*(C`ev_TYPE_stop\*(C'\fR ensures that the watcher is neither active nor pending. If
1036     you want to free or reuse the memory used by the watcher it is therefore a
1037     good idea to always call its \f(CW\*(C`ev_TYPE_stop\*(C'\fR function.
1038     .IP "bool ev_is_active (ev_TYPE *watcher)" 4
1039     .IX Item "bool ev_is_active (ev_TYPE *watcher)"
1040     Returns a true value iff the watcher is active (i.e. it has been started
1041     and not yet been stopped). As long as a watcher is active you must not modify
1042     it.
1043     .IP "bool ev_is_pending (ev_TYPE *watcher)" 4
1044     .IX Item "bool ev_is_pending (ev_TYPE *watcher)"
1045     Returns a true value iff the watcher is pending, (i.e. it has outstanding
1046     events but its callback has not yet been invoked). As long as a watcher
1047     is pending (but not active) you must not call an init function on it (but
1048 root 1.43 \&\f(CW\*(C`ev_TYPE_set\*(C'\fR is safe), you must not change its priority, and you must
1049     make sure the watcher is available to libev (e.g. you cannot \f(CW\*(C`free ()\*(C'\fR
1050     it).
1051 root 1.29 .IP "callback ev_cb (ev_TYPE *watcher)" 4
1052     .IX Item "callback ev_cb (ev_TYPE *watcher)"
1053 root 1.11 Returns the callback currently set on the watcher.
1054     .IP "ev_cb_set (ev_TYPE *watcher, callback)" 4
1055     .IX Item "ev_cb_set (ev_TYPE *watcher, callback)"
1056     Change the callback. You can change the callback at virtually any time
1057     (modulo threads).
1058 root 1.37 .IP "ev_set_priority (ev_TYPE *watcher, priority)" 4
1059     .IX Item "ev_set_priority (ev_TYPE *watcher, priority)"
1060     .PD 0
1061     .IP "int ev_priority (ev_TYPE *watcher)" 4
1062     .IX Item "int ev_priority (ev_TYPE *watcher)"
1063     .PD
1064     Set and query the priority of the watcher. The priority is a small
1065     integer between \f(CW\*(C`EV_MAXPRI\*(C'\fR (default: \f(CW2\fR) and \f(CW\*(C`EV_MINPRI\*(C'\fR
1066     (default: \f(CW\*(C`\-2\*(C'\fR). Pending watchers with higher priority will be invoked
1067     before watchers with lower priority, but priority will not keep watchers
1068     from being executed (except for \f(CW\*(C`ev_idle\*(C'\fR watchers).
1069     .Sp
1070     This means that priorities are \fIonly\fR used for ordering callback
1071     invocation after new events have been received. This is useful, for
1072     example, to reduce latency after idling, or more often, to bind two
1073     watchers on the same event and make sure one is called first.
1074     .Sp
1075     If you need to suppress invocation when higher priority events are pending
1076     you need to look at \f(CW\*(C`ev_idle\*(C'\fR watchers, which provide this functionality.
1077     .Sp
1078 root 1.43 You \fImust not\fR change the priority of a watcher as long as it is active or
1079     pending.
1080     .Sp
1081 root 1.37 The default priority used by watchers when no priority has been set is
1082     always \f(CW0\fR, which is supposed to not be too high and not be too low :).
1083     .Sp
1084     Setting a priority outside the range of \f(CW\*(C`EV_MINPRI\*(C'\fR to \f(CW\*(C`EV_MAXPRI\*(C'\fR is
1085     fine, as long as you do not mind that the priority value you query might
1086     or might not have been adjusted to be within valid range.
1087 root 1.43 .IP "ev_invoke (loop, ev_TYPE *watcher, int revents)" 4
1088     .IX Item "ev_invoke (loop, ev_TYPE *watcher, int revents)"
1089     Invoke the \f(CW\*(C`watcher\*(C'\fR with the given \f(CW\*(C`loop\*(C'\fR and \f(CW\*(C`revents\*(C'\fR. Neither
1090     \&\f(CW\*(C`loop\*(C'\fR nor \f(CW\*(C`revents\*(C'\fR need to be valid as long as the watcher callback
1091     can deal with that fact.
1092     .IP "int ev_clear_pending (loop, ev_TYPE *watcher)" 4
1093     .IX Item "int ev_clear_pending (loop, ev_TYPE *watcher)"
1094     If the watcher is pending, this function returns clears its pending status
1095     and returns its \f(CW\*(C`revents\*(C'\fR bitset (as if its callback was invoked). If the
1096     watcher isn't pending it does nothing and returns \f(CW0\fR.
1097 root 1.1 .Sh "\s-1ASSOCIATING\s0 \s-1CUSTOM\s0 \s-1DATA\s0 \s-1WITH\s0 A \s-1WATCHER\s0"
1098     .IX Subsection "ASSOCIATING CUSTOM DATA WITH A WATCHER"
1099     Each watcher has, by default, a member \f(CW\*(C`void *data\*(C'\fR that you can change
1100     and read at any time, libev will completely ignore it. This can be used
1101     to associate arbitrary data with your watcher. If you need more data and
1102     don't want to allocate memory and store a pointer to it in that data
1103     member, you can also \*(L"subclass\*(R" the watcher type and provide your own
1104     data:
1105     .PP
1106     .Vb 7
1107 root 1.68 \& struct my_io
1108     \& {
1109     \& struct ev_io io;
1110     \& int otherfd;
1111     \& void *somedata;
1112     \& struct whatever *mostinteresting;
1113     \& }
1114 root 1.1 .Ve
1115     .PP
1116     And since your callback will be called with a pointer to the watcher, you
1117     can cast it back to your own type:
1118     .PP
1119     .Vb 5
1120 root 1.68 \& static void my_cb (struct ev_loop *loop, struct ev_io *w_, int revents)
1121     \& {
1122     \& struct my_io *w = (struct my_io *)w_;
1123     \& ...
1124     \& }
1125 root 1.1 .Ve
1126     .PP
1127 root 1.29 More interesting and less C\-conformant ways of casting your callback type
1128     instead have been omitted.
1129     .PP
1130     Another common scenario is having some data structure with multiple
1131     watchers:
1132     .PP
1133     .Vb 6
1134 root 1.68 \& struct my_biggy
1135     \& {
1136     \& int some_data;
1137     \& ev_timer t1;
1138     \& ev_timer t2;
1139     \& }
1140 root 1.29 .Ve
1141     .PP
1142     In this case getting the pointer to \f(CW\*(C`my_biggy\*(C'\fR is a bit more complicated,
1143     you need to use \f(CW\*(C`offsetof\*(C'\fR:
1144     .PP
1145     .Vb 1
1146 root 1.68 \& #include <stddef.h>
1147 root 1.60 \&
1148 root 1.68 \& static void
1149     \& t1_cb (EV_P_ struct ev_timer *w, int revents)
1150     \& {
1151     \& struct my_biggy big = (struct my_biggy *
1152     \& (((char *)w) \- offsetof (struct my_biggy, t1));
1153     \& }
1154     \&
1155     \& static void
1156     \& t2_cb (EV_P_ struct ev_timer *w, int revents)
1157     \& {
1158     \& struct my_biggy big = (struct my_biggy *
1159     \& (((char *)w) \- offsetof (struct my_biggy, t2));
1160     \& }
1161 root 1.29 .Ve
1162 root 1.1 .SH "WATCHER TYPES"
1163     .IX Header "WATCHER TYPES"
1164     This section describes each watcher in detail, but will not repeat
1165 root 1.22 information given in the last section. Any initialisation/set macros,
1166     functions and members specific to the watcher type are explained.
1167     .PP
1168     Members are additionally marked with either \fI[read\-only]\fR, meaning that,
1169     while the watcher is active, you can look at the member and expect some
1170     sensible content, but you must not modify it (you can modify it while the
1171     watcher is stopped to your hearts content), or \fI[read\-write]\fR, which
1172     means you can expect it to have some sensible content while the watcher
1173     is active, but you can also modify it. Modifying it may not do something
1174     sensible or take immediate effect (or do anything at all), but libev will
1175     not crash or malfunction in any way.
1176 root 1.17 .ie n .Sh """ev_io"" \- is this file descriptor readable or writable?"
1177     .el .Sh "\f(CWev_io\fP \- is this file descriptor readable or writable?"
1178     .IX Subsection "ev_io - is this file descriptor readable or writable?"
1179 root 1.1 I/O watchers check whether a file descriptor is readable or writable
1180 root 1.17 in each iteration of the event loop, or, more precisely, when reading
1181     would not block the process and writing would at least be able to write
1182     some data. This behaviour is called level-triggering because you keep
1183     receiving events as long as the condition persists. Remember you can stop
1184     the watcher if you don't want to act on the event and neither want to
1185     receive future events.
1186 root 1.1 .PP
1187     In general you can register as many read and/or write event watchers per
1188     fd as you want (as long as you don't confuse yourself). Setting all file
1189     descriptors to non-blocking mode is also usually a good idea (but not
1190     required if you know what you are doing).
1191     .PP
1192     If you must do this, then force the use of a known-to-be-good backend
1193 root 1.6 (at the time of this writing, this includes only \f(CW\*(C`EVBACKEND_SELECT\*(C'\fR and
1194     \&\f(CW\*(C`EVBACKEND_POLL\*(C'\fR).
1195 root 1.17 .PP
1196     Another thing you have to watch out for is that it is quite easy to
1197 root 1.67 receive \*(L"spurious\*(R" readiness notifications, that is your callback might
1198 root 1.17 be called with \f(CW\*(C`EV_READ\*(C'\fR but a subsequent \f(CW\*(C`read\*(C'\fR(2) will actually block
1199     because there is no data. Not only are some backends known to create a
1200 root 1.68 lot of those (for example Solaris ports), it is very easy to get into
1201 root 1.17 this situation even with a relatively standard program structure. Thus
1202     it is best to always use non-blocking I/O: An extra \f(CW\*(C`read\*(C'\fR(2) returning
1203     \&\f(CW\*(C`EAGAIN\*(C'\fR is far preferable to a program hanging until some data arrives.
1204     .PP
1205     If you cannot run the fd in non-blocking mode (for example you should not
1206 root 1.68 play around with an Xlib connection), then you have to separately re-test
1207 root 1.38 whether a file descriptor is really ready with a known-to-be good interface
1208 root 1.17 such as poll (fortunately in our Xlib example, Xlib already does this on
1209     its own, so its quite safe to use).
1210 root 1.49 .PP
1211     \fIThe special problem of disappearing file descriptors\fR
1212     .IX Subsection "The special problem of disappearing file descriptors"
1213     .PP
1214 root 1.54 Some backends (e.g. kqueue, epoll) need to be told about closing a file
1215 root 1.49 descriptor (either by calling \f(CW\*(C`close\*(C'\fR explicitly or by any other means,
1216     such as \f(CW\*(C`dup\*(C'\fR). The reason is that you register interest in some file
1217     descriptor, but when it goes away, the operating system will silently drop
1218     this interest. If another file descriptor with the same number then is
1219     registered with libev, there is no efficient way to see that this is, in
1220     fact, a different file descriptor.
1221     .PP
1222     To avoid having to explicitly tell libev about such cases, libev follows
1223     the following policy: Each time \f(CW\*(C`ev_io_set\*(C'\fR is being called, libev
1224     will assume that this is potentially a new file descriptor, otherwise
1225     it is assumed that the file descriptor stays the same. That means that
1226     you \fIhave\fR to call \f(CW\*(C`ev_io_set\*(C'\fR (or \f(CW\*(C`ev_io_init\*(C'\fR) when you change the
1227     descriptor even if the file descriptor number itself did not change.
1228     .PP
1229     This is how one would do it normally anyway, the important point is that
1230     the libev application should not optimise around libev but should leave
1231     optimisations to libev.
1232 root 1.50 .PP
1233 root 1.55 \fIThe special problem of dup'ed file descriptors\fR
1234     .IX Subsection "The special problem of dup'ed file descriptors"
1235 root 1.54 .PP
1236     Some backends (e.g. epoll), cannot register events for file descriptors,
1237 root 1.59 but only events for the underlying file descriptions. That means when you
1238     have \f(CW\*(C`dup ()\*(C'\fR'ed file descriptors or weirder constellations, and register
1239     events for them, only one file descriptor might actually receive events.
1240 root 1.54 .PP
1241 root 1.59 There is no workaround possible except not registering events
1242     for potentially \f(CW\*(C`dup ()\*(C'\fR'ed file descriptors, or to resort to
1243 root 1.54 \&\f(CW\*(C`EVBACKEND_SELECT\*(C'\fR or \f(CW\*(C`EVBACKEND_POLL\*(C'\fR.
1244     .PP
1245     \fIThe special problem of fork\fR
1246     .IX Subsection "The special problem of fork"
1247     .PP
1248     Some backends (epoll, kqueue) do not support \f(CW\*(C`fork ()\*(C'\fR at all or exhibit
1249     useless behaviour. Libev fully supports fork, but needs to be told about
1250     it in the child.
1251     .PP
1252     To support fork in your programs, you either have to call
1253     \&\f(CW\*(C`ev_default_fork ()\*(C'\fR or \f(CW\*(C`ev_loop_fork ()\*(C'\fR after a fork in the child,
1254     enable \f(CW\*(C`EVFLAG_FORKCHECK\*(C'\fR, or resort to \f(CW\*(C`EVBACKEND_SELECT\*(C'\fR or
1255     \&\f(CW\*(C`EVBACKEND_POLL\*(C'\fR.
1256     .PP
1257 root 1.63 \fIThe special problem of \s-1SIGPIPE\s0\fR
1258     .IX Subsection "The special problem of SIGPIPE"
1259     .PP
1260     While not really specific to libev, it is easy to forget about \s-1SIGPIPE:\s0
1261     when reading from a pipe whose other end has been closed, your program
1262     gets send a \s-1SIGPIPE\s0, which, by default, aborts your program. For most
1263     programs this is sensible behaviour, for daemons, this is usually
1264     undesirable.
1265     .PP
1266     So when you encounter spurious, unexplained daemon exits, make sure you
1267     ignore \s-1SIGPIPE\s0 (and maybe make sure you log the exit status of your daemon
1268     somewhere, as that would have given you a big clue).
1269     .PP
1270 root 1.50 \fIWatcher-Specific Functions\fR
1271     .IX Subsection "Watcher-Specific Functions"
1272 root 1.1 .IP "ev_io_init (ev_io *, callback, int fd, int events)" 4
1273     .IX Item "ev_io_init (ev_io *, callback, int fd, int events)"
1274     .PD 0
1275     .IP "ev_io_set (ev_io *, int fd, int events)" 4
1276     .IX Item "ev_io_set (ev_io *, int fd, int events)"
1277     .PD
1278 root 1.17 Configures an \f(CW\*(C`ev_io\*(C'\fR watcher. The \f(CW\*(C`fd\*(C'\fR is the file descriptor to
1279 root 1.68 receive events for and events is either \f(CW\*(C`EV_READ\*(C'\fR, \f(CW\*(C`EV_WRITE\*(C'\fR or
1280 root 1.17 \&\f(CW\*(C`EV_READ | EV_WRITE\*(C'\fR to receive the given events.
1281 root 1.22 .IP "int fd [read\-only]" 4
1282     .IX Item "int fd [read-only]"
1283     The file descriptor being watched.
1284     .IP "int events [read\-only]" 4
1285     .IX Item "int events [read-only]"
1286     The events being watched.
1287 root 1.9 .PP
1288 root 1.60 \fIExamples\fR
1289     .IX Subsection "Examples"
1290     .PP
1291 root 1.28 Example: Call \f(CW\*(C`stdin_readable_cb\*(C'\fR when \s-1STDIN_FILENO\s0 has become, well
1292 root 1.60 readable, but only once. Since it is likely line-buffered, you could
1293 root 1.28 attempt to read a whole line in the callback.
1294 root 1.9 .PP
1295     .Vb 6
1296 root 1.68 \& static void
1297     \& stdin_readable_cb (struct ev_loop *loop, struct ev_io *w, int revents)
1298     \& {
1299     \& ev_io_stop (loop, w);
1300     \& .. read from stdin here (or from w\->fd) and haqndle any I/O errors
1301     \& }
1302     \&
1303     \& ...
1304     \& struct ev_loop *loop = ev_default_init (0);
1305     \& struct ev_io stdin_readable;
1306     \& ev_io_init (&stdin_readable, stdin_readable_cb, STDIN_FILENO, EV_READ);
1307     \& ev_io_start (loop, &stdin_readable);
1308     \& ev_loop (loop, 0);
1309 root 1.9 .Ve
1310 root 1.17 .ie n .Sh """ev_timer"" \- relative and optionally repeating timeouts"
1311     .el .Sh "\f(CWev_timer\fP \- relative and optionally repeating timeouts"
1312     .IX Subsection "ev_timer - relative and optionally repeating timeouts"
1313 root 1.1 Timer watchers are simple relative timers that generate an event after a
1314     given time, and optionally repeating in regular intervals after that.
1315     .PP
1316     The timers are based on real time, that is, if you register an event that
1317 root 1.68 times out after an hour and you reset your system clock to January last
1318 root 1.67 year, it will still time out after (roughly) and hour. \*(L"Roughly\*(R" because
1319 root 1.2 detecting time jumps is hard, and some inaccuracies are unavoidable (the
1320 root 1.1 monotonic clock option helps a lot here).
1321     .PP
1322     The relative timeouts are calculated relative to the \f(CW\*(C`ev_now ()\*(C'\fR
1323     time. This is usually the right thing as this timestamp refers to the time
1324 root 1.2 of the event triggering whatever timeout you are modifying/starting. If
1325     you suspect event processing to be delayed and you \fIneed\fR to base the timeout
1326 root 1.1 on the current time, use something like this to adjust for this:
1327     .PP
1328     .Vb 1
1329 root 1.60 \& ev_timer_set (&timer, after + ev_now () \- ev_time (), 0.);
1330 root 1.1 .Ve
1331 root 1.2 .PP
1332 root 1.68 The callback is guaranteed to be invoked only after its timeout has passed,
1333 root 1.2 but if multiple timers become ready during the same loop iteration then
1334     order of execution is undefined.
1335 root 1.50 .PP
1336     \fIWatcher-Specific Functions and Data Members\fR
1337     .IX Subsection "Watcher-Specific Functions and Data Members"
1338 root 1.1 .IP "ev_timer_init (ev_timer *, callback, ev_tstamp after, ev_tstamp repeat)" 4
1339     .IX Item "ev_timer_init (ev_timer *, callback, ev_tstamp after, ev_tstamp repeat)"
1340     .PD 0
1341     .IP "ev_timer_set (ev_timer *, ev_tstamp after, ev_tstamp repeat)" 4
1342     .IX Item "ev_timer_set (ev_timer *, ev_tstamp after, ev_tstamp repeat)"
1343     .PD
1344 root 1.67 Configure the timer to trigger after \f(CW\*(C`after\*(C'\fR seconds. If \f(CW\*(C`repeat\*(C'\fR
1345     is \f(CW0.\fR, then it will automatically be stopped once the timeout is
1346     reached. If it is positive, then the timer will automatically be
1347     configured to trigger again \f(CW\*(C`repeat\*(C'\fR seconds later, again, and again,
1348     until stopped manually.
1349     .Sp
1350     The timer itself will do a best-effort at avoiding drift, that is, if
1351     you configure a timer to trigger every 10 seconds, then it will normally
1352     trigger at exactly 10 second intervals. If, however, your program cannot
1353     keep up with the timer (because it takes longer than those 10 seconds to
1354     do stuff) the timer will not fire more than once per event loop iteration.
1355 root 1.61 .IP "ev_timer_again (loop, ev_timer *)" 4
1356     .IX Item "ev_timer_again (loop, ev_timer *)"
1357 root 1.1 This will act as if the timer timed out and restart it again if it is
1358     repeating. The exact semantics are:
1359     .Sp
1360 root 1.34 If the timer is pending, its pending status is cleared.
1361 root 1.1 .Sp
1362 root 1.68 If the timer is started but non-repeating, stop it (as if it timed out).
1363 root 1.34 .Sp
1364     If the timer is repeating, either start it if necessary (with the
1365     \&\f(CW\*(C`repeat\*(C'\fR value), or reset the running timer to the \f(CW\*(C`repeat\*(C'\fR value.
1366 root 1.1 .Sp
1367     This sounds a bit complicated, but here is a useful and typical
1368 root 1.68 example: Imagine you have a \s-1TCP\s0 connection and you want a so-called idle
1369 root 1.34 timeout, that is, you want to be called when there have been, say, 60
1370     seconds of inactivity on the socket. The easiest way to do this is to
1371     configure an \f(CW\*(C`ev_timer\*(C'\fR with a \f(CW\*(C`repeat\*(C'\fR value of \f(CW60\fR and then call
1372 root 1.22 \&\f(CW\*(C`ev_timer_again\*(C'\fR each time you successfully read or write some data. If
1373     you go into an idle state where you do not expect data to travel on the
1374 root 1.34 socket, you can \f(CW\*(C`ev_timer_stop\*(C'\fR the timer, and \f(CW\*(C`ev_timer_again\*(C'\fR will
1375     automatically restart it if need be.
1376 root 1.22 .Sp
1377 root 1.34 That means you can ignore the \f(CW\*(C`after\*(C'\fR value and \f(CW\*(C`ev_timer_start\*(C'\fR
1378     altogether and only ever use the \f(CW\*(C`repeat\*(C'\fR value and \f(CW\*(C`ev_timer_again\*(C'\fR:
1379 root 1.22 .Sp
1380     .Vb 8
1381     \& ev_timer_init (timer, callback, 0., 5.);
1382     \& ev_timer_again (loop, timer);
1383     \& ...
1384 root 1.60 \& timer\->again = 17.;
1385 root 1.22 \& ev_timer_again (loop, timer);
1386     \& ...
1387 root 1.60 \& timer\->again = 10.;
1388 root 1.22 \& ev_timer_again (loop, timer);
1389     .Ve
1390     .Sp
1391 root 1.34 This is more slightly efficient then stopping/starting the timer each time
1392     you want to modify its timeout value.
1393 root 1.22 .IP "ev_tstamp repeat [read\-write]" 4
1394     .IX Item "ev_tstamp repeat [read-write]"
1395     The current \f(CW\*(C`repeat\*(C'\fR value. Will be used each time the watcher times out
1396     or \f(CW\*(C`ev_timer_again\*(C'\fR is called and determines the next timeout (if any),
1397     which is also when any modifications are taken into account.
1398 root 1.9 .PP
1399 root 1.60 \fIExamples\fR
1400     .IX Subsection "Examples"
1401     .PP
1402 root 1.28 Example: Create a timer that fires after 60 seconds.
1403 root 1.9 .PP
1404     .Vb 5
1405 root 1.68 \& static void
1406     \& one_minute_cb (struct ev_loop *loop, struct ev_timer *w, int revents)
1407     \& {
1408     \& .. one minute over, w is actually stopped right here
1409     \& }
1410     \&
1411     \& struct ev_timer mytimer;
1412     \& ev_timer_init (&mytimer, one_minute_cb, 60., 0.);
1413     \& ev_timer_start (loop, &mytimer);
1414 root 1.9 .Ve
1415     .PP
1416 root 1.28 Example: Create a timeout timer that times out after 10 seconds of
1417 root 1.9 inactivity.
1418     .PP
1419     .Vb 5
1420 root 1.68 \& static void
1421     \& timeout_cb (struct ev_loop *loop, struct ev_timer *w, int revents)
1422     \& {
1423     \& .. ten seconds without any activity
1424     \& }
1425     \&
1426     \& struct ev_timer mytimer;
1427     \& ev_timer_init (&mytimer, timeout_cb, 0., 10.); /* note, only repeat used */
1428     \& ev_timer_again (&mytimer); /* start timer */
1429     \& ev_loop (loop, 0);
1430     \&
1431     \& // and in some piece of code that gets executed on any "activity":
1432     \& // reset the timeout to start ticking again at 10 seconds
1433     \& ev_timer_again (&mytimer);
1434 root 1.9 .Ve
1435 root 1.17 .ie n .Sh """ev_periodic"" \- to cron or not to cron?"
1436     .el .Sh "\f(CWev_periodic\fP \- to cron or not to cron?"
1437     .IX Subsection "ev_periodic - to cron or not to cron?"
1438 root 1.1 Periodic watchers are also timers of a kind, but they are very versatile
1439     (and unfortunately a bit complex).
1440     .PP
1441     Unlike \f(CW\*(C`ev_timer\*(C'\fR's, they are not based on real time (or relative time)
1442 root 1.68 but on wall clock time (absolute time). You can tell a periodic watcher
1443 root 1.67 to trigger after some specific point in time. For example, if you tell a
1444 root 1.68 periodic watcher to trigger in 10 seconds (by specifying e.g. \f(CW\*(C`ev_now ()
1445 root 1.67 + 10.\*(C'\fR, that is, an absolute time not a delay) and then reset your system
1446 root 1.68 clock to January of the previous year, then it will take more than year
1447 root 1.67 to trigger the event (unlike an \f(CW\*(C`ev_timer\*(C'\fR, which would still trigger
1448     roughly 10 seconds later as it uses a relative timeout).
1449     .PP
1450     \&\f(CW\*(C`ev_periodic\*(C'\fRs can also be used to implement vastly more complex timers,
1451     such as triggering an event on each \*(L"midnight, local time\*(R", or other
1452     complicated, rules.
1453 root 1.2 .PP
1454 root 1.68 As with timers, the callback is guaranteed to be invoked only when the
1455 root 1.67 time (\f(CW\*(C`at\*(C'\fR) has passed, but if multiple periodic timers become ready
1456 root 1.2 during the same loop iteration then order of execution is undefined.
1457 root 1.50 .PP
1458     \fIWatcher-Specific Functions and Data Members\fR
1459     .IX Subsection "Watcher-Specific Functions and Data Members"
1460 root 1.1 .IP "ev_periodic_init (ev_periodic *, callback, ev_tstamp at, ev_tstamp interval, reschedule_cb)" 4
1461     .IX Item "ev_periodic_init (ev_periodic *, callback, ev_tstamp at, ev_tstamp interval, reschedule_cb)"
1462     .PD 0
1463     .IP "ev_periodic_set (ev_periodic *, ev_tstamp after, ev_tstamp repeat, reschedule_cb)" 4
1464     .IX Item "ev_periodic_set (ev_periodic *, ev_tstamp after, ev_tstamp repeat, reschedule_cb)"
1465     .PD
1466     Lots of arguments, lets sort it out... There are basically three modes of
1467     operation, and we will explain them from simplest to complex:
1468     .RS 4
1469 root 1.60 .IP "\(bu" 4
1470     absolute timer (at = time, interval = reschedule_cb = 0)
1471     .Sp
1472 root 1.68 In this configuration the watcher triggers an event after the wall clock
1473 root 1.67 time \f(CW\*(C`at\*(C'\fR has passed and doesn't repeat. It will not adjust when a time
1474     jump occurs, that is, if it is to be run at January 1st 2011 then it will
1475     run when the system time reaches or surpasses this time.
1476 root 1.60 .IP "\(bu" 4
1477 root 1.61 repeating interval timer (at = offset, interval > 0, reschedule_cb = 0)
1478 root 1.60 .Sp
1479 root 1.1 In this mode the watcher will always be scheduled to time out at the next
1480 root 1.46 \&\f(CW\*(C`at + N * interval\*(C'\fR time (for some integer N, which can also be negative)
1481     and then repeat, regardless of any time jumps.
1482 root 1.1 .Sp
1483     This can be used to create timers that do not drift with respect to system
1484 root 1.67 time, for example, here is a \f(CW\*(C`ev_periodic\*(C'\fR that triggers each hour, on
1485     the hour:
1486 root 1.1 .Sp
1487     .Vb 1
1488     \& ev_periodic_set (&periodic, 0., 3600., 0);
1489     .Ve
1490     .Sp
1491     This doesn't mean there will always be 3600 seconds in between triggers,
1492 root 1.68 but only that the callback will be called when the system time shows a
1493 root 1.1 full hour (\s-1UTC\s0), or more correctly, when the system time is evenly divisible
1494     by 3600.
1495     .Sp
1496     Another way to think about it (for the mathematically inclined) is that
1497     \&\f(CW\*(C`ev_periodic\*(C'\fR will try to run the callback in this mode at the next possible
1498     time where \f(CW\*(C`time = at (mod interval)\*(C'\fR, regardless of any time jumps.
1499 root 1.46 .Sp
1500     For numerical stability it is preferable that the \f(CW\*(C`at\*(C'\fR value is near
1501     \&\f(CW\*(C`ev_now ()\*(C'\fR (the current time), but there is no range requirement for
1502 root 1.67 this value, and in fact is often specified as zero.
1503     .Sp
1504 root 1.68 Note also that there is an upper limit to how often a timer can fire (\s-1CPU\s0
1505 root 1.67 speed for example), so if \f(CW\*(C`interval\*(C'\fR is very small then timing stability
1506 root 1.68 will of course deteriorate. Libev itself tries to be exact to be about one
1507 root 1.67 millisecond (if the \s-1OS\s0 supports it and the machine is fast enough).
1508 root 1.60 .IP "\(bu" 4
1509     manual reschedule mode (at and interval ignored, reschedule_cb = callback)
1510     .Sp
1511 root 1.1 In this mode the values for \f(CW\*(C`interval\*(C'\fR and \f(CW\*(C`at\*(C'\fR are both being
1512     ignored. Instead, each time the periodic watcher gets scheduled, the
1513     reschedule callback will be called with the watcher as first, and the
1514     current time as second argument.
1515     .Sp
1516     \&\s-1NOTE:\s0 \fIThis callback \s-1MUST\s0 \s-1NOT\s0 stop or destroy any periodic watcher,
1517 root 1.67 ever, or make \s-1ANY\s0 event loop modifications whatsoever\fR.
1518     .Sp
1519     If you need to stop it, return \f(CW\*(C`now + 1e30\*(C'\fR (or so, fudge fudge) and stop
1520     it afterwards (e.g. by starting an \f(CW\*(C`ev_prepare\*(C'\fR watcher, which is the
1521     only event loop modification you are allowed to do).
1522 root 1.1 .Sp
1523 root 1.67 The callback prototype is \f(CW\*(C`ev_tstamp (*reschedule_cb)(struct ev_periodic
1524     *w, ev_tstamp now)\*(C'\fR, e.g.:
1525 root 1.1 .Sp
1526     .Vb 4
1527     \& static ev_tstamp my_rescheduler (struct ev_periodic *w, ev_tstamp now)
1528     \& {
1529     \& return now + 60.;
1530     \& }
1531     .Ve
1532     .Sp
1533     It must return the next time to trigger, based on the passed time value
1534     (that is, the lowest time value larger than to the second argument). It
1535     will usually be called just before the callback will be triggered, but
1536     might be called at other times, too.
1537     .Sp
1538 root 1.67 \&\s-1NOTE:\s0 \fIThis callback must always return a time that is higher than or
1539     equal to the passed \f(CI\*(C`now\*(C'\fI value\fR.
1540 root 1.1 .Sp
1541     This can be used to create very complex timers, such as a timer that
1542 root 1.67 triggers on \*(L"next midnight, local time\*(R". To do this, you would calculate the
1543 root 1.1 next midnight after \f(CW\*(C`now\*(C'\fR and return the timestamp value for this. How
1544     you do this is, again, up to you (but it is not trivial, which is the main
1545     reason I omitted it as an example).
1546     .RE
1547     .RS 4
1548     .RE
1549     .IP "ev_periodic_again (loop, ev_periodic *)" 4
1550     .IX Item "ev_periodic_again (loop, ev_periodic *)"
1551     Simply stops and restarts the periodic watcher again. This is only useful
1552     when you changed some parameters or the reschedule callback would return
1553     a different time than the last time it was called (e.g. in a crond like
1554     program when the crontabs have changed).
1555 root 1.65 .IP "ev_tstamp ev_periodic_at (ev_periodic *)" 4
1556     .IX Item "ev_tstamp ev_periodic_at (ev_periodic *)"
1557     When active, returns the absolute time that the watcher is supposed to
1558     trigger next.
1559 root 1.46 .IP "ev_tstamp offset [read\-write]" 4
1560     .IX Item "ev_tstamp offset [read-write]"
1561     When repeating, this contains the offset value, otherwise this is the
1562     absolute point in time (the \f(CW\*(C`at\*(C'\fR value passed to \f(CW\*(C`ev_periodic_set\*(C'\fR).
1563     .Sp
1564     Can be modified any time, but changes only take effect when the periodic
1565     timer fires or \f(CW\*(C`ev_periodic_again\*(C'\fR is being called.
1566 root 1.22 .IP "ev_tstamp interval [read\-write]" 4
1567     .IX Item "ev_tstamp interval [read-write]"
1568     The current interval value. Can be modified any time, but changes only
1569     take effect when the periodic timer fires or \f(CW\*(C`ev_periodic_again\*(C'\fR is being
1570     called.
1571     .IP "ev_tstamp (*reschedule_cb)(struct ev_periodic *w, ev_tstamp now) [read\-write]" 4
1572     .IX Item "ev_tstamp (*reschedule_cb)(struct ev_periodic *w, ev_tstamp now) [read-write]"
1573     The current reschedule callback, or \f(CW0\fR, if this functionality is
1574     switched off. Can be changed any time, but changes only take effect when
1575     the periodic timer fires or \f(CW\*(C`ev_periodic_again\*(C'\fR is being called.
1576 root 1.9 .PP
1577 root 1.60 \fIExamples\fR
1578     .IX Subsection "Examples"
1579     .PP
1580 root 1.28 Example: Call a callback every hour, or, more precisely, whenever the
1581 root 1.9 system clock is divisible by 3600. The callback invocation times have
1582 root 1.68 potentially a lot of jitter, but good long-term stability.
1583 root 1.9 .PP
1584     .Vb 5
1585 root 1.68 \& static void
1586     \& clock_cb (struct ev_loop *loop, struct ev_io *w, int revents)
1587     \& {
1588     \& ... its now a full hour (UTC, or TAI or whatever your clock follows)
1589     \& }
1590     \&
1591     \& struct ev_periodic hourly_tick;
1592     \& ev_periodic_init (&hourly_tick, clock_cb, 0., 3600., 0);
1593     \& ev_periodic_start (loop, &hourly_tick);
1594 root 1.9 .Ve
1595     .PP
1596 root 1.28 Example: The same as above, but use a reschedule callback to do it:
1597 root 1.9 .PP
1598     .Vb 1
1599 root 1.68 \& #include <math.h>
1600 root 1.60 \&
1601 root 1.68 \& static ev_tstamp
1602     \& my_scheduler_cb (struct ev_periodic *w, ev_tstamp now)
1603     \& {
1604     \& return fmod (now, 3600.) + 3600.;
1605     \& }
1606 root 1.60 \&
1607 root 1.68 \& ev_periodic_init (&hourly_tick, clock_cb, 0., 0., my_scheduler_cb);
1608 root 1.9 .Ve
1609     .PP
1610 root 1.28 Example: Call a callback every hour, starting now:
1611 root 1.9 .PP
1612     .Vb 4
1613 root 1.68 \& struct ev_periodic hourly_tick;
1614     \& ev_periodic_init (&hourly_tick, clock_cb,
1615     \& fmod (ev_now (loop), 3600.), 3600., 0);
1616     \& ev_periodic_start (loop, &hourly_tick);
1617 root 1.9 .Ve
1618 root 1.17 .ie n .Sh """ev_signal"" \- signal me when a signal gets signalled!"
1619     .el .Sh "\f(CWev_signal\fP \- signal me when a signal gets signalled!"
1620     .IX Subsection "ev_signal - signal me when a signal gets signalled!"
1621 root 1.1 Signal watchers will trigger an event when the process receives a specific
1622     signal one or more times. Even though signals are very asynchronous, libev
1623     will try it's best to deliver signals synchronously, i.e. as part of the
1624     normal event processing, like any other event.
1625     .PP
1626     You can configure as many watchers as you like per signal. Only when the
1627     first watcher gets started will libev actually register a signal watcher
1628     with the kernel (thus it coexists with your own signal handlers as long
1629     as you don't register any with libev). Similarly, when the last signal
1630     watcher for a signal is stopped libev will reset the signal handler to
1631     \&\s-1SIG_DFL\s0 (regardless of what it was set to before).
1632 root 1.50 .PP
1633 root 1.61 If possible and supported, libev will install its handlers with
1634 root 1.68 \&\f(CW\*(C`SA_RESTART\*(C'\fR behaviour enabled, so system calls should not be unduly
1635     interrupted. If you have a problem with system calls getting interrupted by
1636 root 1.61 signals you can block all signals in an \f(CW\*(C`ev_check\*(C'\fR watcher and unblock
1637     them in an \f(CW\*(C`ev_prepare\*(C'\fR watcher.
1638     .PP
1639 root 1.50 \fIWatcher-Specific Functions and Data Members\fR
1640     .IX Subsection "Watcher-Specific Functions and Data Members"
1641 root 1.1 .IP "ev_signal_init (ev_signal *, callback, int signum)" 4
1642     .IX Item "ev_signal_init (ev_signal *, callback, int signum)"
1643     .PD 0
1644     .IP "ev_signal_set (ev_signal *, int signum)" 4
1645     .IX Item "ev_signal_set (ev_signal *, int signum)"
1646     .PD
1647     Configures the watcher to trigger on the given signal number (usually one
1648     of the \f(CW\*(C`SIGxxx\*(C'\fR constants).
1649 root 1.22 .IP "int signum [read\-only]" 4
1650     .IX Item "int signum [read-only]"
1651     The signal the watcher watches out for.
1652 root 1.61 .PP
1653     \fIExamples\fR
1654     .IX Subsection "Examples"
1655     .PP
1656     Example: Try to exit cleanly on \s-1SIGINT\s0 and \s-1SIGTERM\s0.
1657     .PP
1658     .Vb 5
1659 root 1.68 \& static void
1660     \& sigint_cb (struct ev_loop *loop, struct ev_signal *w, int revents)
1661     \& {
1662     \& ev_unloop (loop, EVUNLOOP_ALL);
1663     \& }
1664     \&
1665     \& struct ev_signal signal_watcher;
1666     \& ev_signal_init (&signal_watcher, sigint_cb, SIGINT);
1667     \& ev_signal_start (loop, &sigint_cb);
1668 root 1.61 .Ve
1669 root 1.17 .ie n .Sh """ev_child"" \- watch out for process status changes"
1670     .el .Sh "\f(CWev_child\fP \- watch out for process status changes"
1671     .IX Subsection "ev_child - watch out for process status changes"
1672 root 1.1 Child watchers trigger when your process receives a \s-1SIGCHLD\s0 in response to
1673 root 1.61 some child status changes (most typically when a child of yours dies). It
1674     is permissible to install a child watcher \fIafter\fR the child has been
1675     forked (which implies it might have already exited), as long as the event
1676     loop isn't entered (or is continued from a watcher).
1677     .PP
1678     Only the default event loop is capable of handling signals, and therefore
1679 root 1.68 you can only register child watchers in the default event loop.
1680 root 1.61 .PP
1681     \fIProcess Interaction\fR
1682     .IX Subsection "Process Interaction"
1683     .PP
1684     Libev grabs \f(CW\*(C`SIGCHLD\*(C'\fR as soon as the default event loop is
1685     initialised. This is necessary to guarantee proper behaviour even if
1686 root 1.68 the first child watcher is started after the child exits. The occurrence
1687 root 1.61 of \f(CW\*(C`SIGCHLD\*(C'\fR is recorded asynchronously, but child reaping is done
1688     synchronously as part of the event loop processing. Libev always reaps all
1689     children, even ones not watched.
1690     .PP
1691     \fIOverriding the Built-In Processing\fR
1692     .IX Subsection "Overriding the Built-In Processing"
1693     .PP
1694     Libev offers no special support for overriding the built-in child
1695     processing, but if your application collides with libev's default child
1696     handler, you can override it easily by installing your own handler for
1697     \&\f(CW\*(C`SIGCHLD\*(C'\fR after initialising the default loop, and making sure the
1698     default loop never gets destroyed. You are encouraged, however, to use an
1699     event-based approach to child reaping and thus use libev's support for
1700     that, so other libev users can use \f(CW\*(C`ev_child\*(C'\fR watchers freely.
1701 root 1.50 .PP
1702     \fIWatcher-Specific Functions and Data Members\fR
1703     .IX Subsection "Watcher-Specific Functions and Data Members"
1704 root 1.60 .IP "ev_child_init (ev_child *, callback, int pid, int trace)" 4
1705     .IX Item "ev_child_init (ev_child *, callback, int pid, int trace)"
1706 root 1.1 .PD 0
1707 root 1.60 .IP "ev_child_set (ev_child *, int pid, int trace)" 4
1708     .IX Item "ev_child_set (ev_child *, int pid, int trace)"
1709 root 1.1 .PD
1710     Configures the watcher to wait for status changes of process \f(CW\*(C`pid\*(C'\fR (or
1711     \&\fIany\fR process if \f(CW\*(C`pid\*(C'\fR is specified as \f(CW0\fR). The callback can look
1712     at the \f(CW\*(C`rstatus\*(C'\fR member of the \f(CW\*(C`ev_child\*(C'\fR watcher structure to see
1713     the status word (use the macros from \f(CW\*(C`sys/wait.h\*(C'\fR and see your systems
1714     \&\f(CW\*(C`waitpid\*(C'\fR documentation). The \f(CW\*(C`rpid\*(C'\fR member contains the pid of the
1715 root 1.60 process causing the status change. \f(CW\*(C`trace\*(C'\fR must be either \f(CW0\fR (only
1716     activate the watcher when the process terminates) or \f(CW1\fR (additionally
1717     activate the watcher when the process is stopped or continued).
1718 root 1.22 .IP "int pid [read\-only]" 4
1719     .IX Item "int pid [read-only]"
1720     The process id this watcher watches out for, or \f(CW0\fR, meaning any process id.
1721     .IP "int rpid [read\-write]" 4
1722     .IX Item "int rpid [read-write]"
1723     The process id that detected a status change.
1724     .IP "int rstatus [read\-write]" 4
1725     .IX Item "int rstatus [read-write]"
1726     The process exit/trace status caused by \f(CW\*(C`rpid\*(C'\fR (see your systems
1727     \&\f(CW\*(C`waitpid\*(C'\fR and \f(CW\*(C`sys/wait.h\*(C'\fR documentation for details).
1728 root 1.9 .PP
1729 root 1.60 \fIExamples\fR
1730     .IX Subsection "Examples"
1731     .PP
1732 root 1.61 Example: \f(CW\*(C`fork()\*(C'\fR a new process and install a child handler to wait for
1733     its completion.
1734 root 1.9 .PP
1735 root 1.61 .Vb 1
1736 root 1.68 \& ev_child cw;
1737 root 1.61 \&
1738 root 1.68 \& static void
1739     \& child_cb (EV_P_ struct ev_child *w, int revents)
1740     \& {
1741     \& ev_child_stop (EV_A_ w);
1742     \& printf ("process %d exited with status %x\en", w\->rpid, w\->rstatus);
1743     \& }
1744     \&
1745     \& pid_t pid = fork ();
1746     \&
1747     \& if (pid < 0)
1748     \& // error
1749     \& else if (pid == 0)
1750     \& {
1751     \& // the forked child executes here
1752     \& exit (1);
1753     \& }
1754     \& else
1755     \& {
1756     \& ev_child_init (&cw, child_cb, pid, 0);
1757     \& ev_child_start (EV_DEFAULT_ &cw);
1758     \& }
1759 root 1.9 .Ve
1760 root 1.22 .ie n .Sh """ev_stat"" \- did the file attributes just change?"
1761     .el .Sh "\f(CWev_stat\fP \- did the file attributes just change?"
1762     .IX Subsection "ev_stat - did the file attributes just change?"
1763 root 1.68 This watches a file system path for attribute changes. That is, it calls
1764 root 1.22 \&\f(CW\*(C`stat\*(C'\fR regularly (or when the \s-1OS\s0 says it changed) and sees if it changed
1765     compared to the last time, invoking the callback if it did.
1766     .PP
1767     The path does not need to exist: changing from \*(L"path exists\*(R" to \*(L"path does
1768     not exist\*(R" is a status change like any other. The condition \*(L"path does
1769     not exist\*(R" is signified by the \f(CW\*(C`st_nlink\*(C'\fR field being zero (which is
1770     otherwise always forced to be at least one) and all the other fields of
1771     the stat buffer having unspecified contents.
1772     .PP
1773 root 1.33 The path \fIshould\fR be absolute and \fImust not\fR end in a slash. If it is
1774     relative and your working directory changes, the behaviour is undefined.
1775     .PP
1776 root 1.22 Since there is no standard to do this, the portable implementation simply
1777 root 1.30 calls \f(CW\*(C`stat (2)\*(C'\fR regularly on the path to see if it changed somehow. You
1778 root 1.22 can specify a recommended polling interval for this case. If you specify
1779     a polling interval of \f(CW0\fR (highly recommended!) then a \fIsuitable,
1780     unspecified default\fR value will be used (which you can expect to be around
1781     five seconds, although this might change dynamically). Libev will also
1782     impose a minimum interval which is currently around \f(CW0.1\fR, but thats
1783     usually overkill.
1784     .PP
1785     This watcher type is not meant for massive numbers of stat watchers,
1786     as even with OS-supported change notifications, this can be
1787 root 1.60 resource-intensive.
1788 root 1.22 .PP
1789 root 1.30 At the time of this writing, only the Linux inotify interface is
1790     implemented (implementing kqueue support is left as an exercise for the
1791 root 1.65 reader, note, however, that the author sees no way of implementing ev_stat
1792     semantics with kqueue). Inotify will be used to give hints only and should
1793     not change the semantics of \f(CW\*(C`ev_stat\*(C'\fR watchers, which means that libev
1794     sometimes needs to fall back to regular polling again even with inotify,
1795     but changes are usually detected immediately, and if the file exists there
1796     will be no polling.
1797 root 1.50 .PP
1798 root 1.63 \fI\s-1ABI\s0 Issues (Largefile Support)\fR
1799     .IX Subsection "ABI Issues (Largefile Support)"
1800     .PP
1801     Libev by default (unless the user overrides this) uses the default
1802 root 1.69 compilation environment, which means that on systems with large file
1803     support disabled by default, you get the 32 bit version of the stat
1804 root 1.63 structure. When using the library from programs that change the \s-1ABI\s0 to
1805     use 64 bit file offsets the programs will fail. In that case you have to
1806     compile libev with the same flags to get binary compatibility. This is
1807     obviously the case with any flags that change the \s-1ABI\s0, but the problem is
1808 root 1.69 most noticeably disabled with ev_stat and large file support.
1809     .PP
1810     The solution for this is to lobby your distribution maker to make large
1811     file interfaces available by default (as e.g. FreeBSD does) and not
1812     optional. Libev cannot simply switch on large file support because it has
1813     to exchange stat structures with application programs compiled using the
1814     default compilation environment.
1815 root 1.63 .PP
1816 root 1.59 \fIInotify\fR
1817     .IX Subsection "Inotify"
1818     .PP
1819     When \f(CW\*(C`inotify (7)\*(C'\fR support has been compiled into libev (generally only
1820     available on Linux) and present at runtime, it will be used to speed up
1821     change detection where possible. The inotify descriptor will be created lazily
1822     when the first \f(CW\*(C`ev_stat\*(C'\fR watcher is being started.
1823     .PP
1824 root 1.65 Inotify presence does not change the semantics of \f(CW\*(C`ev_stat\*(C'\fR watchers
1825 root 1.59 except that changes might be detected earlier, and in some cases, to avoid
1826 root 1.65 making regular \f(CW\*(C`stat\*(C'\fR calls. Even in the presence of inotify support
1827 root 1.59 there are many cases where libev has to resort to regular \f(CW\*(C`stat\*(C'\fR polling.
1828     .PP
1829     (There is no support for kqueue, as apparently it cannot be used to
1830     implement this functionality, due to the requirement of having a file
1831     descriptor open on the object at all times).
1832     .PP
1833     \fIThe special problem of stat time resolution\fR
1834     .IX Subsection "The special problem of stat time resolution"
1835     .PP
1836 root 1.68 The \f(CW\*(C`stat ()\*(C'\fR system call only supports full-second resolution portably, and
1837     even on systems where the resolution is higher, many file systems still
1838 root 1.59 only support whole seconds.
1839     .PP
1840 root 1.65 That means that, if the time is the only thing that changes, you can
1841     easily miss updates: on the first update, \f(CW\*(C`ev_stat\*(C'\fR detects a change and
1842     calls your callback, which does something. When there is another update
1843     within the same second, \f(CW\*(C`ev_stat\*(C'\fR will be unable to detect it as the stat
1844     data does not change.
1845     .PP
1846     The solution to this is to delay acting on a change for slightly more
1847 root 1.67 than a second (or till slightly after the next full second boundary), using
1848 root 1.65 a roughly one-second-delay \f(CW\*(C`ev_timer\*(C'\fR (e.g. \f(CW\*(C`ev_timer_set (w, 0., 1.02);
1849     ev_timer_again (loop, w)\*(C'\fR).
1850     .PP
1851     The \f(CW.02\fR offset is added to work around small timing inconsistencies
1852     of some operating systems (where the second counter of the current time
1853     might be be delayed. One such system is the Linux kernel, where a call to
1854     \&\f(CW\*(C`gettimeofday\*(C'\fR might return a timestamp with a full second later than
1855     a subsequent \f(CW\*(C`time\*(C'\fR call \- if the equivalent of \f(CW\*(C`time ()\*(C'\fR is used to
1856     update file times then there will be a small window where the kernel uses
1857     the previous second to update file times but libev might already execute
1858     the timer callback).
1859 root 1.59 .PP
1860 root 1.50 \fIWatcher-Specific Functions and Data Members\fR
1861     .IX Subsection "Watcher-Specific Functions and Data Members"
1862 root 1.22 .IP "ev_stat_init (ev_stat *, callback, const char *path, ev_tstamp interval)" 4
1863     .IX Item "ev_stat_init (ev_stat *, callback, const char *path, ev_tstamp interval)"
1864     .PD 0
1865     .IP "ev_stat_set (ev_stat *, const char *path, ev_tstamp interval)" 4
1866     .IX Item "ev_stat_set (ev_stat *, const char *path, ev_tstamp interval)"
1867     .PD
1868     Configures the watcher to wait for status changes of the given
1869     \&\f(CW\*(C`path\*(C'\fR. The \f(CW\*(C`interval\*(C'\fR is a hint on how quickly a change is expected to
1870     be detected and should normally be specified as \f(CW0\fR to let libev choose
1871     a suitable value. The memory pointed to by \f(CW\*(C`path\*(C'\fR must point to the same
1872     path for as long as the watcher is active.
1873     .Sp
1874 root 1.65 The callback will receive \f(CW\*(C`EV_STAT\*(C'\fR when a change was detected, relative
1875     to the attributes at the time the watcher was started (or the last change
1876     was detected).
1877 root 1.61 .IP "ev_stat_stat (loop, ev_stat *)" 4
1878     .IX Item "ev_stat_stat (loop, ev_stat *)"
1879 root 1.22 Updates the stat buffer immediately with new values. If you change the
1880 root 1.65 watched path in your callback, you could call this function to avoid
1881     detecting this change (while introducing a race condition if you are not
1882     the only one changing the path). Can also be useful simply to find out the
1883     new values.
1884 root 1.22 .IP "ev_statdata attr [read\-only]" 4
1885     .IX Item "ev_statdata attr [read-only]"
1886 root 1.65 The most-recently detected attributes of the file. Although the type is
1887 root 1.22 \&\f(CW\*(C`ev_statdata\*(C'\fR, this is usually the (or one of the) \f(CW\*(C`struct stat\*(C'\fR types
1888 root 1.65 suitable for your system, but you can only rely on the POSIX-standardised
1889     members to be present. If the \f(CW\*(C`st_nlink\*(C'\fR member is \f(CW0\fR, then there was
1890     some error while \f(CW\*(C`stat\*(C'\fRing the file.
1891 root 1.22 .IP "ev_statdata prev [read\-only]" 4
1892     .IX Item "ev_statdata prev [read-only]"
1893     The previous attributes of the file. The callback gets invoked whenever
1894 root 1.65 \&\f(CW\*(C`prev\*(C'\fR != \f(CW\*(C`attr\*(C'\fR, or, more precisely, one or more of these members
1895     differ: \f(CW\*(C`st_dev\*(C'\fR, \f(CW\*(C`st_ino\*(C'\fR, \f(CW\*(C`st_mode\*(C'\fR, \f(CW\*(C`st_nlink\*(C'\fR, \f(CW\*(C`st_uid\*(C'\fR,
1896     \&\f(CW\*(C`st_gid\*(C'\fR, \f(CW\*(C`st_rdev\*(C'\fR, \f(CW\*(C`st_size\*(C'\fR, \f(CW\*(C`st_atime\*(C'\fR, \f(CW\*(C`st_mtime\*(C'\fR, \f(CW\*(C`st_ctime\*(C'\fR.
1897 root 1.22 .IP "ev_tstamp interval [read\-only]" 4
1898     .IX Item "ev_tstamp interval [read-only]"
1899     The specified interval.
1900     .IP "const char *path [read\-only]" 4
1901     .IX Item "const char *path [read-only]"
1902 root 1.68 The file system path that is being watched.
1903 root 1.22 .PP
1904 root 1.59 \fIExamples\fR
1905     .IX Subsection "Examples"
1906     .PP
1907 root 1.22 Example: Watch \f(CW\*(C`/etc/passwd\*(C'\fR for attribute changes.
1908     .PP
1909 root 1.60 .Vb 10
1910 root 1.68 \& static void
1911     \& passwd_cb (struct ev_loop *loop, ev_stat *w, int revents)
1912     \& {
1913     \& /* /etc/passwd changed in some way */
1914     \& if (w\->attr.st_nlink)
1915     \& {
1916     \& printf ("passwd current size %ld\en", (long)w\->attr.st_size);
1917     \& printf ("passwd current atime %ld\en", (long)w\->attr.st_mtime);
1918     \& printf ("passwd current mtime %ld\en", (long)w\->attr.st_mtime);
1919     \& }
1920     \& else
1921     \& /* you shalt not abuse printf for puts */
1922     \& puts ("wow, /etc/passwd is not there, expect problems. "
1923     \& "if this is windows, they already arrived\en");
1924     \& }
1925 root 1.60 \&
1926 root 1.68 \& ...
1927     \& ev_stat passwd;
1928 root 1.60 \&
1929 root 1.68 \& ev_stat_init (&passwd, passwd_cb, "/etc/passwd", 0.);
1930     \& ev_stat_start (loop, &passwd);
1931 root 1.22 .Ve
1932 root 1.59 .PP
1933     Example: Like above, but additionally use a one-second delay so we do not
1934     miss updates (however, frequent updates will delay processing, too, so
1935     one might do the work both on \f(CW\*(C`ev_stat\*(C'\fR callback invocation \fIand\fR on
1936     \&\f(CW\*(C`ev_timer\*(C'\fR callback invocation).
1937     .PP
1938     .Vb 2
1939 root 1.68 \& static ev_stat passwd;
1940     \& static ev_timer timer;
1941 root 1.60 \&
1942 root 1.68 \& static void
1943     \& timer_cb (EV_P_ ev_timer *w, int revents)
1944     \& {
1945     \& ev_timer_stop (EV_A_ w);
1946     \&
1947     \& /* now it\*(Aqs one second after the most recent passwd change */
1948     \& }
1949     \&
1950     \& static void
1951     \& stat_cb (EV_P_ ev_stat *w, int revents)
1952     \& {
1953     \& /* reset the one\-second timer */
1954     \& ev_timer_again (EV_A_ &timer);
1955     \& }
1956     \&
1957     \& ...
1958     \& ev_stat_init (&passwd, stat_cb, "/etc/passwd", 0.);
1959     \& ev_stat_start (loop, &passwd);
1960     \& ev_timer_init (&timer, timer_cb, 0., 1.02);
1961 root 1.59 .Ve
1962 root 1.17 .ie n .Sh """ev_idle"" \- when you've got nothing better to do..."
1963     .el .Sh "\f(CWev_idle\fP \- when you've got nothing better to do..."
1964     .IX Subsection "ev_idle - when you've got nothing better to do..."
1965 root 1.37 Idle watchers trigger events when no other events of the same or higher
1966     priority are pending (prepare, check and other idle watchers do not
1967     count).
1968     .PP
1969     That is, as long as your process is busy handling sockets or timeouts
1970     (or even signals, imagine) of the same or higher priority it will not be
1971     triggered. But when your process is idle (or only lower-priority watchers
1972     are pending), the idle watchers are being called once per event loop
1973     iteration \- until stopped, that is, or your process receives more events
1974     and becomes busy again with higher priority stuff.
1975 root 1.1 .PP
1976     The most noteworthy effect is that as long as any idle watchers are
1977     active, the process will not block when waiting for new events.
1978     .PP
1979     Apart from keeping your process non-blocking (which is a useful
1980     effect on its own sometimes), idle watchers are a good place to do
1981 root 1.60 \&\*(L"pseudo-background processing\*(R", or delay processing stuff to after the
1982 root 1.1 event loop has handled all outstanding events.
1983 root 1.50 .PP
1984     \fIWatcher-Specific Functions and Data Members\fR
1985     .IX Subsection "Watcher-Specific Functions and Data Members"
1986 root 1.1 .IP "ev_idle_init (ev_signal *, callback)" 4
1987     .IX Item "ev_idle_init (ev_signal *, callback)"
1988     Initialises and configures the idle watcher \- it has no parameters of any
1989     kind. There is a \f(CW\*(C`ev_idle_set\*(C'\fR macro, but using it is utterly pointless,
1990     believe me.
1991 root 1.9 .PP
1992 root 1.60 \fIExamples\fR
1993     .IX Subsection "Examples"
1994     .PP
1995 root 1.28 Example: Dynamically allocate an \f(CW\*(C`ev_idle\*(C'\fR watcher, start it, and in the
1996     callback, free it. Also, use no error checking, as usual.
1997 root 1.9 .PP
1998     .Vb 7
1999 root 1.68 \& static void
2000     \& idle_cb (struct ev_loop *loop, struct ev_idle *w, int revents)
2001     \& {
2002     \& free (w);
2003     \& // now do something you wanted to do when the program has
2004     \& // no longer anything immediate to do.
2005     \& }
2006     \&
2007     \& struct ev_idle *idle_watcher = malloc (sizeof (struct ev_idle));
2008     \& ev_idle_init (idle_watcher, idle_cb);
2009     \& ev_idle_start (loop, idle_cb);
2010 root 1.9 .Ve
2011 root 1.17 .ie n .Sh """ev_prepare""\fP and \f(CW""ev_check"" \- customise your event loop!"
2012     .el .Sh "\f(CWev_prepare\fP and \f(CWev_check\fP \- customise your event loop!"
2013     .IX Subsection "ev_prepare and ev_check - customise your event loop!"
2014 root 1.1 Prepare and check watchers are usually (but not always) used in tandem:
2015     prepare watchers get invoked before the process blocks and check watchers
2016     afterwards.
2017     .PP
2018 root 1.20 You \fImust not\fR call \f(CW\*(C`ev_loop\*(C'\fR or similar functions that enter
2019     the current event loop from either \f(CW\*(C`ev_prepare\*(C'\fR or \f(CW\*(C`ev_check\*(C'\fR
2020     watchers. Other loops than the current one are fine, however. The
2021     rationale behind this is that you do not need to check for recursion in
2022     those watchers, i.e. the sequence will always be \f(CW\*(C`ev_prepare\*(C'\fR, blocking,
2023     \&\f(CW\*(C`ev_check\*(C'\fR so if you have one watcher of each kind they will always be
2024     called in pairs bracketing the blocking call.
2025     .PP
2026 root 1.10 Their main purpose is to integrate other event mechanisms into libev and
2027     their use is somewhat advanced. This could be used, for example, to track
2028     variable changes, implement your own watchers, integrate net-snmp or a
2029 root 1.20 coroutine library and lots more. They are also occasionally useful if
2030     you cache some data and want to flush it before blocking (for example,
2031     in X programs you might want to do an \f(CW\*(C`XFlush ()\*(C'\fR in an \f(CW\*(C`ev_prepare\*(C'\fR
2032     watcher).
2033 root 1.1 .PP
2034     This is done by examining in each prepare call which file descriptors need
2035     to be watched by the other library, registering \f(CW\*(C`ev_io\*(C'\fR watchers for
2036     them and starting an \f(CW\*(C`ev_timer\*(C'\fR watcher for any timeouts (many libraries
2037     provide just this functionality). Then, in the check watcher you check for
2038 root 1.68 any events that occurred (by checking the pending status of all watchers
2039 root 1.1 and stopping them) and call back into the library. The I/O and timer
2040     callbacks will never actually be called (but must be valid nevertheless,
2041     because you never know, you know?).
2042     .PP
2043     As another example, the Perl Coro module uses these hooks to integrate
2044     coroutines into libev programs, by yielding to other active coroutines
2045     during each prepare and only letting the process block if no coroutines
2046     are ready to run (it's actually more complicated: it only runs coroutines
2047     with priority higher than or equal to the event loop and one coroutine
2048     of lower priority, but only once, using idle watchers to keep the event
2049     loop from blocking if lower-priority coroutines are active, thus mapping
2050     low-priority coroutines to idle/background tasks).
2051 root 1.45 .PP
2052     It is recommended to give \f(CW\*(C`ev_check\*(C'\fR watchers highest (\f(CW\*(C`EV_MAXPRI\*(C'\fR)
2053     priority, to ensure that they are being run before any other watchers
2054     after the poll. Also, \f(CW\*(C`ev_check\*(C'\fR watchers (and \f(CW\*(C`ev_prepare\*(C'\fR watchers,
2055     too) should not activate (\*(L"feed\*(R") events into libev. While libev fully
2056 root 1.65 supports this, they might get executed before other \f(CW\*(C`ev_check\*(C'\fR watchers
2057 root 1.57 did their job. As \f(CW\*(C`ev_check\*(C'\fR watchers are often used to embed other
2058 root 1.60 (non-libev) event loops those other event loops might be in an unusable
2059 root 1.57 state until their \f(CW\*(C`ev_check\*(C'\fR watcher ran (always remind yourself to
2060     coexist peacefully with others).
2061 root 1.50 .PP
2062     \fIWatcher-Specific Functions and Data Members\fR
2063     .IX Subsection "Watcher-Specific Functions and Data Members"
2064 root 1.1 .IP "ev_prepare_init (ev_prepare *, callback)" 4
2065     .IX Item "ev_prepare_init (ev_prepare *, callback)"
2066     .PD 0
2067     .IP "ev_check_init (ev_check *, callback)" 4
2068     .IX Item "ev_check_init (ev_check *, callback)"
2069     .PD
2070     Initialises and configures the prepare or check watcher \- they have no
2071     parameters of any kind. There are \f(CW\*(C`ev_prepare_set\*(C'\fR and \f(CW\*(C`ev_check_set\*(C'\fR
2072     macros, but using them is utterly, utterly and completely pointless.
2073 root 1.9 .PP
2074 root 1.60 \fIExamples\fR
2075     .IX Subsection "Examples"
2076     .PP
2077 root 1.44 There are a number of principal ways to embed other event loops or modules
2078     into libev. Here are some ideas on how to include libadns into libev
2079     (there is a Perl module named \f(CW\*(C`EV::ADNS\*(C'\fR that does this, which you could
2080 root 1.65 use as a working example. Another Perl module named \f(CW\*(C`EV::Glib\*(C'\fR embeds a
2081     Glib main context into libev, and finally, \f(CW\*(C`Glib::EV\*(C'\fR embeds \s-1EV\s0 into the
2082     Glib event loop).
2083 root 1.44 .PP
2084     Method 1: Add \s-1IO\s0 watchers and a timeout watcher in a prepare handler,
2085     and in a check watcher, destroy them and call into libadns. What follows
2086     is pseudo-code only of course. This requires you to either use a low
2087     priority for the check watcher or use \f(CW\*(C`ev_clear_pending\*(C'\fR explicitly, as
2088     the callbacks for the IO/timeout watchers might not have been called yet.
2089 root 1.20 .PP
2090     .Vb 2
2091 root 1.68 \& static ev_io iow [nfd];
2092     \& static ev_timer tw;
2093     \&
2094     \& static void
2095     \& io_cb (ev_loop *loop, ev_io *w, int revents)
2096     \& {
2097     \& }
2098     \&
2099     \& // create io watchers for each fd and a timer before blocking
2100     \& static void
2101     \& adns_prepare_cb (ev_loop *loop, ev_prepare *w, int revents)
2102     \& {
2103     \& int timeout = 3600000;
2104     \& struct pollfd fds [nfd];
2105     \& // actual code will need to loop here and realloc etc.
2106     \& adns_beforepoll (ads, fds, &nfd, &timeout, timeval_from (ev_time ()));
2107     \&
2108     \& /* the callback is illegal, but won\*(Aqt be called as we stop during check */
2109     \& ev_timer_init (&tw, 0, timeout * 1e\-3);
2110     \& ev_timer_start (loop, &tw);
2111 root 1.60 \&
2112 root 1.68 \& // create one ev_io per pollfd
2113     \& for (int i = 0; i < nfd; ++i)
2114     \& {
2115     \& ev_io_init (iow + i, io_cb, fds [i].fd,
2116     \& ((fds [i].events & POLLIN ? EV_READ : 0)
2117     \& | (fds [i].events & POLLOUT ? EV_WRITE : 0)));
2118     \&
2119     \& fds [i].revents = 0;
2120     \& ev_io_start (loop, iow + i);
2121     \& }
2122     \& }
2123     \&
2124     \& // stop all watchers after blocking
2125     \& static void
2126     \& adns_check_cb (ev_loop *loop, ev_check *w, int revents)
2127     \& {
2128     \& ev_timer_stop (loop, &tw);
2129     \&
2130     \& for (int i = 0; i < nfd; ++i)
2131     \& {
2132     \& // set the relevant poll flags
2133     \& // could also call adns_processreadable etc. here
2134     \& struct pollfd *fd = fds + i;
2135     \& int revents = ev_clear_pending (iow + i);
2136     \& if (revents & EV_READ ) fd\->revents |= fd\->events & POLLIN;
2137     \& if (revents & EV_WRITE) fd\->revents |= fd\->events & POLLOUT;
2138 root 1.60 \&
2139 root 1.68 \& // now stop the watcher
2140     \& ev_io_stop (loop, iow + i);
2141     \& }
2142     \&
2143     \& adns_afterpoll (adns, fds, nfd, timeval_from (ev_now (loop));
2144     \& }
2145 root 1.20 .Ve
2146 root 1.44 .PP
2147     Method 2: This would be just like method 1, but you run \f(CW\*(C`adns_afterpoll\*(C'\fR
2148     in the prepare watcher and would dispose of the check watcher.
2149     .PP
2150     Method 3: If the module to be embedded supports explicit event
2151 root 1.68 notification (libadns does), you can also make use of the actual watcher
2152 root 1.44 callbacks, and only destroy/create the watchers in the prepare watcher.
2153     .PP
2154     .Vb 5
2155 root 1.68 \& static void
2156     \& timer_cb (EV_P_ ev_timer *w, int revents)
2157     \& {
2158     \& adns_state ads = (adns_state)w\->data;
2159     \& update_now (EV_A);
2160     \&
2161     \& adns_processtimeouts (ads, &tv_now);
2162     \& }
2163     \&
2164     \& static void
2165     \& io_cb (EV_P_ ev_io *w, int revents)
2166     \& {
2167     \& adns_state ads = (adns_state)w\->data;
2168     \& update_now (EV_A);
2169 root 1.60 \&
2170 root 1.68 \& if (revents & EV_READ ) adns_processreadable (ads, w\->fd, &tv_now);
2171     \& if (revents & EV_WRITE) adns_processwriteable (ads, w\->fd, &tv_now);
2172     \& }
2173     \&
2174     \& // do not ever call adns_afterpoll
2175 root 1.44 .Ve
2176     .PP
2177     Method 4: Do not use a prepare or check watcher because the module you
2178 root 1.68 want to embed is too inflexible to support it. Instead, you can override
2179 root 1.44 their poll function. The drawback with this solution is that the main
2180     loop is now no longer controllable by \s-1EV\s0. The \f(CW\*(C`Glib::EV\*(C'\fR module does
2181     this.
2182     .PP
2183     .Vb 4
2184 root 1.68 \& static gint
2185     \& event_poll_func (GPollFD *fds, guint nfds, gint timeout)
2186     \& {
2187     \& int got_events = 0;
2188     \&
2189     \& for (n = 0; n < nfds; ++n)
2190     \& // create/start io watcher that sets the relevant bits in fds[n] and increment got_events
2191     \&
2192     \& if (timeout >= 0)
2193     \& // create/start timer
2194     \&
2195     \& // poll
2196     \& ev_loop (EV_A_ 0);
2197     \&
2198     \& // stop timer again
2199     \& if (timeout >= 0)
2200     \& ev_timer_stop (EV_A_ &to);
2201 root 1.60 \&
2202 root 1.68 \& // stop io watchers again \- their callbacks should have set
2203     \& for (n = 0; n < nfds; ++n)
2204     \& ev_io_stop (EV_A_ iow [n]);
2205     \&
2206     \& return got_events;
2207     \& }
2208 root 1.44 .Ve
2209 root 1.17 .ie n .Sh """ev_embed"" \- when one backend isn't enough..."
2210     .el .Sh "\f(CWev_embed\fP \- when one backend isn't enough..."
2211     .IX Subsection "ev_embed - when one backend isn't enough..."
2212 root 1.10 This is a rather advanced watcher type that lets you embed one event loop
2213 root 1.11 into another (currently only \f(CW\*(C`ev_io\*(C'\fR events are supported in the embedded
2214     loop, other types of watchers might be handled in a delayed or incorrect
2215 root 1.57 fashion and must not be used).
2216 root 1.10 .PP
2217     There are primarily two reasons you would want that: work around bugs and
2218     prioritise I/O.
2219     .PP
2220     As an example for a bug workaround, the kqueue backend might only support
2221     sockets on some platform, so it is unusable as generic backend, but you
2222     still want to make use of it because you have many sockets and it scales
2223     so nicely. In this case, you would create a kqueue-based loop and embed it
2224     into your default loop (which might use e.g. poll). Overall operation will
2225     be a bit slower because first libev has to poll and then call kevent, but
2226     at least you can use both at what they are best.
2227     .PP
2228     As for prioritising I/O: rarely you have the case where some fds have
2229     to be watched and handled very quickly (with low latency), and even
2230     priorities and idle watchers might have too much overhead. In this case
2231     you would put all the high priority stuff in one loop and all the rest in
2232     a second one, and embed the second one in the first.
2233     .PP
2234 root 1.11 As long as the watcher is active, the callback will be invoked every time
2235     there might be events pending in the embedded loop. The callback must then
2236     call \f(CW\*(C`ev_embed_sweep (mainloop, watcher)\*(C'\fR to make a single sweep and invoke
2237     their callbacks (you could also start an idle watcher to give the embedded
2238     loop strictly lower priority for example). You can also set the callback
2239     to \f(CW0\fR, in which case the embed watcher will automatically execute the
2240     embedded loop sweep.
2241     .PP
2242 root 1.10 As long as the watcher is started it will automatically handle events. The
2243     callback will be invoked whenever some events have been handled. You can
2244     set the callback to \f(CW0\fR to avoid having to specify one if you are not
2245     interested in that.
2246     .PP
2247     Also, there have not currently been made special provisions for forking:
2248     when you fork, you not only have to call \f(CW\*(C`ev_loop_fork\*(C'\fR on both loops,
2249     but you will also have to stop and restart any \f(CW\*(C`ev_embed\*(C'\fR watchers
2250     yourself.
2251     .PP
2252     Unfortunately, not all backends are embeddable, only the ones returned by
2253     \&\f(CW\*(C`ev_embeddable_backends\*(C'\fR are, which, unfortunately, does not include any
2254     portable one.
2255     .PP
2256     So when you want to use this feature you will always have to be prepared
2257     that you cannot get an embeddable loop. The recommended way to get around
2258     this is to have a separate variables for your embeddable loop, try to
2259 root 1.60 create it, and if that fails, use the normal loop for everything.
2260 root 1.50 .PP
2261     \fIWatcher-Specific Functions and Data Members\fR
2262     .IX Subsection "Watcher-Specific Functions and Data Members"
2263 root 1.11 .IP "ev_embed_init (ev_embed *, callback, struct ev_loop *embedded_loop)" 4
2264     .IX Item "ev_embed_init (ev_embed *, callback, struct ev_loop *embedded_loop)"
2265 root 1.10 .PD 0
2266 root 1.11 .IP "ev_embed_set (ev_embed *, callback, struct ev_loop *embedded_loop)" 4
2267     .IX Item "ev_embed_set (ev_embed *, callback, struct ev_loop *embedded_loop)"
2268 root 1.10 .PD
2269 root 1.11 Configures the watcher to embed the given loop, which must be
2270     embeddable. If the callback is \f(CW0\fR, then \f(CW\*(C`ev_embed_sweep\*(C'\fR will be
2271     invoked automatically, otherwise it is the responsibility of the callback
2272     to invoke it (it will continue to be called until the sweep has been done,
2273 root 1.68 if you do not want that, you need to temporarily stop the embed watcher).
2274 root 1.11 .IP "ev_embed_sweep (loop, ev_embed *)" 4
2275     .IX Item "ev_embed_sweep (loop, ev_embed *)"
2276     Make a single, non-blocking sweep over the embedded loop. This works
2277     similarly to \f(CW\*(C`ev_loop (embedded_loop, EVLOOP_NONBLOCK)\*(C'\fR, but in the most
2278 root 1.68 appropriate way for embedded loops.
2279 root 1.54 .IP "struct ev_loop *other [read\-only]" 4
2280     .IX Item "struct ev_loop *other [read-only]"
2281 root 1.22 The embedded event loop.
2282 root 1.60 .PP
2283     \fIExamples\fR
2284     .IX Subsection "Examples"
2285     .PP
2286     Example: Try to get an embeddable event loop and embed it into the default
2287     event loop. If that is not possible, use the default loop. The default
2288 root 1.68 loop is stored in \f(CW\*(C`loop_hi\*(C'\fR, while the embeddable loop is stored in
2289     \&\f(CW\*(C`loop_lo\*(C'\fR (which is \f(CW\*(C`loop_hi\*(C'\fR in the case no embeddable loop can be
2290 root 1.60 used).
2291     .PP
2292     .Vb 3
2293 root 1.68 \& struct ev_loop *loop_hi = ev_default_init (0);
2294     \& struct ev_loop *loop_lo = 0;
2295     \& struct ev_embed embed;
2296     \&
2297     \& // see if there is a chance of getting one that works
2298     \& // (remember that a flags value of 0 means autodetection)
2299     \& loop_lo = ev_embeddable_backends () & ev_recommended_backends ()
2300     \& ? ev_loop_new (ev_embeddable_backends () & ev_recommended_backends ())
2301     \& : 0;
2302     \&
2303     \& // if we got one, then embed it, otherwise default to loop_hi
2304     \& if (loop_lo)
2305     \& {
2306     \& ev_embed_init (&embed, 0, loop_lo);
2307     \& ev_embed_start (loop_hi, &embed);
2308     \& }
2309     \& else
2310     \& loop_lo = loop_hi;
2311 root 1.60 .Ve
2312     .PP
2313     Example: Check if kqueue is available but not recommended and create
2314     a kqueue backend for use with sockets (which usually work with any
2315     kqueue implementation). Store the kqueue/socket\-only event loop in
2316     \&\f(CW\*(C`loop_socket\*(C'\fR. (One might optionally use \f(CW\*(C`EVFLAG_NOENV\*(C'\fR, too).
2317     .PP
2318     .Vb 3
2319 root 1.68 \& struct ev_loop *loop = ev_default_init (0);
2320     \& struct ev_loop *loop_socket = 0;
2321     \& struct ev_embed embed;
2322     \&
2323     \& if (ev_supported_backends () & ~ev_recommended_backends () & EVBACKEND_KQUEUE)
2324     \& if ((loop_socket = ev_loop_new (EVBACKEND_KQUEUE))
2325     \& {
2326     \& ev_embed_init (&embed, 0, loop_socket);
2327     \& ev_embed_start (loop, &embed);
2328     \& }
2329 root 1.60 \&
2330 root 1.68 \& if (!loop_socket)
2331     \& loop_socket = loop;
2332 root 1.60 \&
2333 root 1.68 \& // now use loop_socket for all sockets, and loop for everything else
2334 root 1.60 .Ve
2335 root 1.24 .ie n .Sh """ev_fork"" \- the audacity to resume the event loop after a fork"
2336     .el .Sh "\f(CWev_fork\fP \- the audacity to resume the event loop after a fork"
2337     .IX Subsection "ev_fork - the audacity to resume the event loop after a fork"
2338     Fork watchers are called when a \f(CW\*(C`fork ()\*(C'\fR was detected (usually because
2339     whoever is a good citizen cared to tell libev about it by calling
2340     \&\f(CW\*(C`ev_default_fork\*(C'\fR or \f(CW\*(C`ev_loop_fork\*(C'\fR). The invocation is done before the
2341     event loop blocks next and before \f(CW\*(C`ev_check\*(C'\fR watchers are being called,
2342     and only in the child after the fork. If whoever good citizen calling
2343     \&\f(CW\*(C`ev_default_fork\*(C'\fR cheats and calls it in the wrong process, the fork
2344     handlers will be invoked, too, of course.
2345 root 1.51 .PP
2346     \fIWatcher-Specific Functions and Data Members\fR
2347     .IX Subsection "Watcher-Specific Functions and Data Members"
2348 root 1.24 .IP "ev_fork_init (ev_signal *, callback)" 4
2349     .IX Item "ev_fork_init (ev_signal *, callback)"
2350     Initialises and configures the fork watcher \- it has no parameters of any
2351     kind. There is a \f(CW\*(C`ev_fork_set\*(C'\fR macro, but using it is utterly pointless,
2352     believe me.
2353 root 1.61 .ie n .Sh """ev_async"" \- how to wake up another event loop"
2354     .el .Sh "\f(CWev_async\fP \- how to wake up another event loop"
2355     .IX Subsection "ev_async - how to wake up another event loop"
2356     In general, you cannot use an \f(CW\*(C`ev_loop\*(C'\fR from multiple threads or other
2357     asynchronous sources such as signal handlers (as opposed to multiple event
2358     loops \- those are of course safe to use in different threads).
2359     .PP
2360     Sometimes, however, you need to wake up another event loop you do not
2361     control, for example because it belongs to another thread. This is what
2362     \&\f(CW\*(C`ev_async\*(C'\fR watchers do: as long as the \f(CW\*(C`ev_async\*(C'\fR watcher is active, you
2363     can signal it by calling \f(CW\*(C`ev_async_send\*(C'\fR, which is thread\- and signal
2364     safe.
2365     .PP
2366     This functionality is very similar to \f(CW\*(C`ev_signal\*(C'\fR watchers, as signals,
2367     too, are asynchronous in nature, and signals, too, will be compressed
2368     (i.e. the number of callback invocations may be less than the number of
2369     \&\f(CW\*(C`ev_async_sent\*(C'\fR calls).
2370     .PP
2371     Unlike \f(CW\*(C`ev_signal\*(C'\fR watchers, \f(CW\*(C`ev_async\*(C'\fR works with any event loop, not
2372     just the default loop.
2373     .PP
2374     \fIQueueing\fR
2375     .IX Subsection "Queueing"
2376     .PP
2377     \&\f(CW\*(C`ev_async\*(C'\fR does not support queueing of data in any way. The reason
2378     is that the author does not know of a simple (or any) algorithm for a
2379     multiple-writer-single-reader queue that works in all cases and doesn't
2380     need elaborate support such as pthreads.
2381     .PP
2382     That means that if you want to queue data, you have to provide your own
2383     queue. But at least I can tell you would implement locking around your
2384     queue:
2385     .IP "queueing from a signal handler context" 4
2386     .IX Item "queueing from a signal handler context"
2387     To implement race-free queueing, you simply add to the queue in the signal
2388     handler but you block the signal handler in the watcher callback. Here is an example that does that for
2389 root 1.68 some fictitious \s-1SIGUSR1\s0 handler:
2390 root 1.61 .Sp
2391     .Vb 1
2392     \& static ev_async mysig;
2393     \&
2394     \& static void
2395     \& sigusr1_handler (void)
2396     \& {
2397     \& sometype data;
2398     \&
2399     \& // no locking etc.
2400     \& queue_put (data);
2401     \& ev_async_send (EV_DEFAULT_ &mysig);
2402     \& }
2403     \&
2404     \& static void
2405     \& mysig_cb (EV_P_ ev_async *w, int revents)
2406     \& {
2407     \& sometype data;
2408     \& sigset_t block, prev;
2409     \&
2410     \& sigemptyset (&block);
2411     \& sigaddset (&block, SIGUSR1);
2412     \& sigprocmask (SIG_BLOCK, &block, &prev);
2413     \&
2414     \& while (queue_get (&data))
2415     \& process (data);
2416     \&
2417     \& if (sigismember (&prev, SIGUSR1)
2418     \& sigprocmask (SIG_UNBLOCK, &block, 0);
2419     \& }
2420     .Ve
2421     .Sp
2422     (Note: pthreads in theory requires you to use \f(CW\*(C`pthread_setmask\*(C'\fR
2423     instead of \f(CW\*(C`sigprocmask\*(C'\fR when you use threads, but libev doesn't do it
2424     either...).
2425     .IP "queueing from a thread context" 4
2426     .IX Item "queueing from a thread context"
2427     The strategy for threads is different, as you cannot (easily) block
2428     threads but you can easily preempt them, so to queue safely you need to
2429     employ a traditional mutex lock, such as in this pthread example:
2430     .Sp
2431     .Vb 2
2432     \& static ev_async mysig;
2433     \& static pthread_mutex_t mymutex = PTHREAD_MUTEX_INITIALIZER;
2434     \&
2435     \& static void
2436     \& otherthread (void)
2437     \& {
2438     \& // only need to lock the actual queueing operation
2439     \& pthread_mutex_lock (&mymutex);
2440     \& queue_put (data);
2441     \& pthread_mutex_unlock (&mymutex);
2442     \&
2443     \& ev_async_send (EV_DEFAULT_ &mysig);
2444     \& }
2445     \&
2446     \& static void
2447     \& mysig_cb (EV_P_ ev_async *w, int revents)
2448     \& {
2449     \& pthread_mutex_lock (&mymutex);
2450     \&
2451     \& while (queue_get (&data))
2452     \& process (data);
2453     \&
2454     \& pthread_mutex_unlock (&mymutex);
2455     \& }
2456     .Ve
2457     .PP
2458     \fIWatcher-Specific Functions and Data Members\fR
2459     .IX Subsection "Watcher-Specific Functions and Data Members"
2460     .IP "ev_async_init (ev_async *, callback)" 4
2461     .IX Item "ev_async_init (ev_async *, callback)"
2462     Initialises and configures the async watcher \- it has no parameters of any
2463     kind. There is a \f(CW\*(C`ev_asynd_set\*(C'\fR macro, but using it is utterly pointless,
2464     believe me.
2465     .IP "ev_async_send (loop, ev_async *)" 4
2466     .IX Item "ev_async_send (loop, ev_async *)"
2467     Sends/signals/activates the given \f(CW\*(C`ev_async\*(C'\fR watcher, that is, feeds
2468     an \f(CW\*(C`EV_ASYNC\*(C'\fR event on the watcher into the event loop. Unlike
2469     \&\f(CW\*(C`ev_feed_event\*(C'\fR, this call is safe to do in other threads, signal or
2470 root 1.68 similar contexts (see the discussion of \f(CW\*(C`EV_ATOMIC_T\*(C'\fR in the embedding
2471 root 1.61 section below on what exactly this means).
2472     .Sp
2473 root 1.68 This call incurs the overhead of a system call only once per loop iteration,
2474     so while the overhead might be noticeable, it doesn't apply to repeated
2475 root 1.61 calls to \f(CW\*(C`ev_async_send\*(C'\fR.
2476 root 1.63 .IP "bool = ev_async_pending (ev_async *)" 4
2477     .IX Item "bool = ev_async_pending (ev_async *)"
2478     Returns a non-zero value when \f(CW\*(C`ev_async_send\*(C'\fR has been called on the
2479     watcher but the event has not yet been processed (or even noted) by the
2480     event loop.
2481     .Sp
2482     \&\f(CW\*(C`ev_async_send\*(C'\fR sets a flag in the watcher and wakes up the loop. When
2483     the loop iterates next and checks for the watcher to have become active,
2484     it will reset the flag again. \f(CW\*(C`ev_async_pending\*(C'\fR can be used to very
2485 root 1.68 quickly check whether invoking the loop might be a good idea.
2486 root 1.63 .Sp
2487 root 1.68 Not that this does \fInot\fR check whether the watcher itself is pending, only
2488     whether it has been requested to make this watcher pending.
2489 root 1.1 .SH "OTHER FUNCTIONS"
2490     .IX Header "OTHER FUNCTIONS"
2491     There are some other functions of possible interest. Described. Here. Now.
2492     .IP "ev_once (loop, int fd, int events, ev_tstamp timeout, callback)" 4
2493     .IX Item "ev_once (loop, int fd, int events, ev_tstamp timeout, callback)"
2494     This function combines a simple timer and an I/O watcher, calls your
2495     callback on whichever event happens first and automatically stop both
2496     watchers. This is useful if you want to wait for a single event on an fd
2497     or timeout without having to allocate/configure/start/stop/free one or
2498     more watchers yourself.
2499     .Sp
2500     If \f(CW\*(C`fd\*(C'\fR is less than 0, then no I/O watcher will be started and events
2501     is being ignored. Otherwise, an \f(CW\*(C`ev_io\*(C'\fR watcher for the given \f(CW\*(C`fd\*(C'\fR and
2502 root 1.68 \&\f(CW\*(C`events\*(C'\fR set will be created and started.
2503 root 1.1 .Sp
2504     If \f(CW\*(C`timeout\*(C'\fR is less than 0, then no timeout watcher will be
2505     started. Otherwise an \f(CW\*(C`ev_timer\*(C'\fR watcher with after = \f(CW\*(C`timeout\*(C'\fR (and
2506     repeat = 0) will be started. While \f(CW0\fR is a valid timeout, it is of
2507     dubious value.
2508     .Sp
2509     The callback has the type \f(CW\*(C`void (*cb)(int revents, void *arg)\*(C'\fR and gets
2510     passed an \f(CW\*(C`revents\*(C'\fR set like normal event callbacks (a combination of
2511     \&\f(CW\*(C`EV_ERROR\*(C'\fR, \f(CW\*(C`EV_READ\*(C'\fR, \f(CW\*(C`EV_WRITE\*(C'\fR or \f(CW\*(C`EV_TIMEOUT\*(C'\fR) and the \f(CW\*(C`arg\*(C'\fR
2512     value passed to \f(CW\*(C`ev_once\*(C'\fR:
2513     .Sp
2514     .Vb 7
2515 root 1.68 \& static void stdin_ready (int revents, void *arg)
2516     \& {
2517     \& if (revents & EV_TIMEOUT)
2518     \& /* doh, nothing entered */;
2519     \& else if (revents & EV_READ)
2520     \& /* stdin might have data for us, joy! */;
2521     \& }
2522 root 1.60 \&
2523 root 1.68 \& ev_once (STDIN_FILENO, EV_READ, 10., stdin_ready, 0);
2524 root 1.1 .Ve
2525 root 1.11 .IP "ev_feed_event (ev_loop *, watcher *, int revents)" 4
2526     .IX Item "ev_feed_event (ev_loop *, watcher *, int revents)"
2527 root 1.1 Feeds the given event set into the event loop, as if the specified event
2528     had happened for the specified watcher (which must be a pointer to an
2529     initialised but not necessarily started event watcher).
2530 root 1.11 .IP "ev_feed_fd_event (ev_loop *, int fd, int revents)" 4
2531     .IX Item "ev_feed_fd_event (ev_loop *, int fd, int revents)"
2532 root 1.1 Feed an event on the given fd, as if a file descriptor backend detected
2533     the given events it.
2534 root 1.11 .IP "ev_feed_signal_event (ev_loop *loop, int signum)" 4
2535     .IX Item "ev_feed_signal_event (ev_loop *loop, int signum)"
2536 root 1.68 Feed an event as if the given signal occurred (\f(CW\*(C`loop\*(C'\fR must be the default
2537 root 1.11 loop!).
2538 root 1.1 .SH "LIBEVENT EMULATION"
2539     .IX Header "LIBEVENT EMULATION"
2540     Libev offers a compatibility emulation layer for libevent. It cannot
2541     emulate the internals of libevent, so here are some usage hints:
2542 root 1.60 .IP "\(bu" 4
2543     Use it by including <event.h>, as usual.
2544     .IP "\(bu" 4
2545     The following members are fully supported: ev_base, ev_callback,
2546     ev_arg, ev_fd, ev_res, ev_events.
2547     .IP "\(bu" 4
2548     Avoid using ev_flags and the EVLIST_*\-macros, while it is
2549     maintained by libev, it does not work exactly the same way as in libevent (consider
2550     it a private \s-1API\s0).
2551     .IP "\(bu" 4
2552     Priorities are not currently supported. Initialising priorities
2553     will fail and all watchers will have the same priority, even though there
2554     is an ev_pri field.
2555     .IP "\(bu" 4
2556 root 1.64 In libevent, the last base created gets the signals, in libev, the
2557     first base created (== the default loop) gets the signals.
2558     .IP "\(bu" 4
2559 root 1.60 Other members are not supported.
2560     .IP "\(bu" 4
2561     The libev emulation is \fInot\fR \s-1ABI\s0 compatible to libevent, you need
2562     to use the libev header file and library.
2563 root 1.1 .SH "\*(C+ SUPPORT"
2564     .IX Header " SUPPORT"
2565 root 1.13 Libev comes with some simplistic wrapper classes for \*(C+ that mainly allow
2566 root 1.68 you to use some convenience methods to start/stop watchers and also change
2567 root 1.13 the callback model to a model using method callbacks on objects.
2568     .PP
2569     To use it,
2570     .PP
2571     .Vb 1
2572 root 1.68 \& #include <ev++.h>
2573 root 1.13 .Ve
2574     .PP
2575 root 1.41 This automatically includes \fIev.h\fR and puts all of its definitions (many
2576     of them macros) into the global namespace. All \*(C+ specific things are
2577     put into the \f(CW\*(C`ev\*(C'\fR namespace. It should support all the same embedding
2578     options as \fIev.h\fR, most notably \f(CW\*(C`EV_MULTIPLICITY\*(C'\fR.
2579     .PP
2580 root 1.42 Care has been taken to keep the overhead low. The only data member the \*(C+
2581     classes add (compared to plain C\-style watchers) is the event loop pointer
2582     that the watcher is associated with (or no additional members at all if
2583     you disable \f(CW\*(C`EV_MULTIPLICITY\*(C'\fR when embedding libev).
2584 root 1.41 .PP
2585 root 1.42 Currently, functions, and static and non-static member functions can be
2586 root 1.41 used as callbacks. Other types should be easy to add as long as they only
2587     need one additional pointer for context. If you need support for other
2588     types of functors please contact the author (preferably after implementing
2589     it).
2590 root 1.13 .PP
2591     Here is a list of things available in the \f(CW\*(C`ev\*(C'\fR namespace:
2592     .ie n .IP """ev::READ""\fR, \f(CW""ev::WRITE"" etc." 4
2593     .el .IP "\f(CWev::READ\fR, \f(CWev::WRITE\fR etc." 4
2594     .IX Item "ev::READ, ev::WRITE etc."
2595     These are just enum values with the same values as the \f(CW\*(C`EV_READ\*(C'\fR etc.
2596     macros from \fIev.h\fR.
2597     .ie n .IP """ev::tstamp""\fR, \f(CW""ev::now""" 4
2598     .el .IP "\f(CWev::tstamp\fR, \f(CWev::now\fR" 4
2599     .IX Item "ev::tstamp, ev::now"
2600     Aliases to the same types/functions as with the \f(CW\*(C`ev_\*(C'\fR prefix.
2601     .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
2602     .el .IP "\f(CWev::io\fR, \f(CWev::timer\fR, \f(CWev::periodic\fR, \f(CWev::idle\fR, \f(CWev::sig\fR etc." 4
2603     .IX Item "ev::io, ev::timer, ev::periodic, ev::idle, ev::sig etc."
2604     For each \f(CW\*(C`ev_TYPE\*(C'\fR watcher in \fIev.h\fR there is a corresponding class of
2605     the same name in the \f(CW\*(C`ev\*(C'\fR namespace, with the exception of \f(CW\*(C`ev_signal\*(C'\fR
2606     which is called \f(CW\*(C`ev::sig\*(C'\fR to avoid clashes with the \f(CW\*(C`signal\*(C'\fR macro
2607     defines by many implementations.
2608     .Sp
2609     All of those classes have these methods:
2610     .RS 4
2611 root 1.41 .IP "ev::TYPE::TYPE ()" 4
2612     .IX Item "ev::TYPE::TYPE ()"
2613 root 1.13 .PD 0
2614 root 1.41 .IP "ev::TYPE::TYPE (struct ev_loop *)" 4
2615     .IX Item "ev::TYPE::TYPE (struct ev_loop *)"
2616 root 1.13 .IP "ev::TYPE::~TYPE" 4
2617     .IX Item "ev::TYPE::~TYPE"
2618     .PD
2619 root 1.41 The constructor (optionally) takes an event loop to associate the watcher
2620     with. If it is omitted, it will use \f(CW\*(C`EV_DEFAULT\*(C'\fR.
2621     .Sp
2622     The constructor calls \f(CW\*(C`ev_init\*(C'\fR for you, which means you have to call the
2623     \&\f(CW\*(C`set\*(C'\fR method before starting it.
2624     .Sp
2625     It will not set a callback, however: You have to call the templated \f(CW\*(C`set\*(C'\fR
2626     method to set a callback before you can start the watcher.
2627     .Sp
2628     (The reason why you have to use a method is a limitation in \*(C+ which does
2629     not allow explicit template arguments for constructors).
2630 root 1.13 .Sp
2631     The destructor automatically stops the watcher if it is active.
2632 root 1.41 .IP "w\->set<class, &class::method> (object *)" 4
2633     .IX Item "w->set<class, &class::method> (object *)"
2634     This method sets the callback method to call. The method has to have a
2635     signature of \f(CW\*(C`void (*)(ev_TYPE &, int)\*(C'\fR, it receives the watcher as
2636     first argument and the \f(CW\*(C`revents\*(C'\fR as second. The object must be given as
2637     parameter and is stored in the \f(CW\*(C`data\*(C'\fR member of the watcher.
2638     .Sp
2639     This method synthesizes efficient thunking code to call your method from
2640     the C callback that libev requires. If your compiler can inline your
2641     callback (i.e. it is visible to it at the place of the \f(CW\*(C`set\*(C'\fR call and
2642     your compiler is good :), then the method will be fully inlined into the
2643     thunking function, making it as fast as a direct C callback.
2644     .Sp
2645     Example: simple class declaration and watcher initialisation
2646     .Sp
2647     .Vb 4
2648 root 1.68 \& struct myclass
2649     \& {
2650     \& void io_cb (ev::io &w, int revents) { }
2651     \& }
2652     \&
2653     \& myclass obj;
2654     \& ev::io iow;
2655     \& iow.set <myclass, &myclass::io_cb> (&obj);
2656 root 1.41 .Ve
2657 root 1.43 .IP "w\->set<function> (void *data = 0)" 4
2658     .IX Item "w->set<function> (void *data = 0)"
2659 root 1.41 Also sets a callback, but uses a static method or plain function as
2660     callback. The optional \f(CW\*(C`data\*(C'\fR argument will be stored in the watcher's
2661     \&\f(CW\*(C`data\*(C'\fR member and is free for you to use.
2662     .Sp
2663 root 1.43 The prototype of the \f(CW\*(C`function\*(C'\fR must be \f(CW\*(C`void (*)(ev::TYPE &w, int)\*(C'\fR.
2664     .Sp
2665 root 1.41 See the method\-\f(CW\*(C`set\*(C'\fR above for more details.
2666 root 1.43 .Sp
2667     Example:
2668     .Sp
2669     .Vb 2
2670 root 1.68 \& static void io_cb (ev::io &w, int revents) { }
2671     \& iow.set <io_cb> ();
2672 root 1.43 .Ve
2673 root 1.13 .IP "w\->set (struct ev_loop *)" 4
2674     .IX Item "w->set (struct ev_loop *)"
2675     Associates a different \f(CW\*(C`struct ev_loop\*(C'\fR with this watcher. You can only
2676     do this when the watcher is inactive (and not pending either).
2677 root 1.68 .IP "w\->set ([arguments])" 4
2678     .IX Item "w->set ([arguments])"
2679     Basically the same as \f(CW\*(C`ev_TYPE_set\*(C'\fR, with the same arguments. Must be
2680 root 1.41 called at least once. Unlike the C counterpart, an active watcher gets
2681     automatically stopped and restarted when reconfiguring it with this
2682     method.
2683 root 1.13 .IP "w\->start ()" 4
2684     .IX Item "w->start ()"
2685 root 1.41 Starts the watcher. Note that there is no \f(CW\*(C`loop\*(C'\fR argument, as the
2686     constructor already stores the event loop.
2687 root 1.13 .IP "w\->stop ()" 4
2688     .IX Item "w->stop ()"
2689     Stops the watcher if it is active. Again, no \f(CW\*(C`loop\*(C'\fR argument.
2690 root 1.52 .ie n .IP "w\->again () (""ev::timer""\fR, \f(CW""ev::periodic"" only)" 4
2691     .el .IP "w\->again () (\f(CWev::timer\fR, \f(CWev::periodic\fR only)" 4
2692     .IX Item "w->again () (ev::timer, ev::periodic only)"
2693 root 1.13 For \f(CW\*(C`ev::timer\*(C'\fR and \f(CW\*(C`ev::periodic\*(C'\fR, this invokes the corresponding
2694     \&\f(CW\*(C`ev_TYPE_again\*(C'\fR function.
2695 root 1.52 .ie n .IP "w\->sweep () (""ev::embed"" only)" 4
2696     .el .IP "w\->sweep () (\f(CWev::embed\fR only)" 4
2697     .IX Item "w->sweep () (ev::embed only)"
2698 root 1.13 Invokes \f(CW\*(C`ev_embed_sweep\*(C'\fR.
2699 root 1.52 .ie n .IP "w\->update () (""ev::stat"" only)" 4
2700     .el .IP "w\->update () (\f(CWev::stat\fR only)" 4
2701     .IX Item "w->update () (ev::stat only)"
2702 root 1.23 Invokes \f(CW\*(C`ev_stat_stat\*(C'\fR.
2703 root 1.13 .RE
2704     .RS 4
2705     .RE
2706     .PP
2707     Example: Define a class with an \s-1IO\s0 and idle watcher, start one of them in
2708     the constructor.
2709     .PP
2710     .Vb 4
2711 root 1.68 \& class myclass
2712     \& {
2713     \& ev::io io; void io_cb (ev::io &w, int revents);
2714     \& ev:idle idle void idle_cb (ev::idle &w, int revents);
2715     \&
2716     \& myclass (int fd)
2717     \& {
2718     \& io .set <myclass, &myclass::io_cb > (this);
2719     \& idle.set <myclass, &myclass::idle_cb> (this);
2720     \&
2721     \& io.start (fd, ev::READ);
2722     \& }
2723     \& };
2724 root 1.13 .Ve
2725 root 1.62 .SH "OTHER LANGUAGE BINDINGS"
2726     .IX Header "OTHER LANGUAGE BINDINGS"
2727     Libev does not offer other language bindings itself, but bindings for a
2728 root 1.68 number of languages exist in the form of third-party packages. If you know
2729 root 1.62 any interesting language binding in addition to the ones listed here, drop
2730     me a note.
2731     .IP "Perl" 4
2732     .IX Item "Perl"
2733     The \s-1EV\s0 module implements the full libev \s-1API\s0 and is actually used to test
2734     libev. \s-1EV\s0 is developed together with libev. Apart from the \s-1EV\s0 core module,
2735     there are additional modules that implement libev-compatible interfaces
2736     to \f(CW\*(C`libadns\*(C'\fR (\f(CW\*(C`EV::ADNS\*(C'\fR), \f(CW\*(C`Net::SNMP\*(C'\fR (\f(CW\*(C`Net::SNMP::EV\*(C'\fR) and the
2737     \&\f(CW\*(C`libglib\*(C'\fR event core (\f(CW\*(C`Glib::EV\*(C'\fR and \f(CW\*(C`EV::Glib\*(C'\fR).
2738     .Sp
2739 root 1.68 It can be found and installed via \s-1CPAN\s0, its homepage is at
2740 root 1.62 <http://software.schmorp.de/pkg/EV>.
2741 root 1.68 .IP "Python" 4
2742     .IX Item "Python"
2743     Python bindings can be found at <http://code.google.com/p/pyev/>. It
2744     seems to be quite complete and well-documented. Note, however, that the
2745     patch they require for libev is outright dangerous as it breaks the \s-1ABI\s0
2746     for everybody else, and therefore, should never be applied in an installed
2747     libev (if python requires an incompatible \s-1ABI\s0 then it needs to embed
2748     libev).
2749 root 1.62 .IP "Ruby" 4
2750     .IX Item "Ruby"
2751     Tony Arcieri has written a ruby extension that offers access to a subset
2752 root 1.68 of the libev \s-1API\s0 and adds file handle abstractions, asynchronous \s-1DNS\s0 and
2753 root 1.62 more on top of it. It can be found via gem servers. Its homepage is at
2754     <http://rev.rubyforge.org/>.
2755     .IP "D" 4
2756     .IX Item "D"
2757     Leandro Lucarella has written a D language binding (\fIev.d\fR) for libev, to
2758     be found at <http://git.llucax.com.ar/?p=software/ev.d.git;a=summary>.
2759 root 1.24 .SH "MACRO MAGIC"
2760     .IX Header "MACRO MAGIC"
2761 root 1.68 Libev can be compiled with a variety of options, the most fundamental
2762 root 1.52 of which is \f(CW\*(C`EV_MULTIPLICITY\*(C'\fR. This option determines whether (most)
2763     functions and callbacks have an initial \f(CW\*(C`struct ev_loop *\*(C'\fR argument.
2764 root 1.24 .PP
2765     To make it easier to write programs that cope with either variant, the
2766     following macros are defined:
2767     .ie n .IP """EV_A""\fR, \f(CW""EV_A_""" 4
2768     .el .IP "\f(CWEV_A\fR, \f(CWEV_A_\fR" 4
2769     .IX Item "EV_A, EV_A_"
2770     This provides the loop \fIargument\fR for functions, if one is required (\*(L"ev
2771     loop argument\*(R"). The \f(CW\*(C`EV_A\*(C'\fR form is used when this is the sole argument,
2772     \&\f(CW\*(C`EV_A_\*(C'\fR is used when other arguments are following. Example:
2773     .Sp
2774     .Vb 3
2775 root 1.68 \& ev_unref (EV_A);
2776     \& ev_timer_add (EV_A_ watcher);
2777     \& ev_loop (EV_A_ 0);
2778 root 1.24 .Ve
2779     .Sp
2780     It assumes the variable \f(CW\*(C`loop\*(C'\fR of type \f(CW\*(C`struct ev_loop *\*(C'\fR is in scope,
2781     which is often provided by the following macro.
2782     .ie n .IP """EV_P""\fR, \f(CW""EV_P_""" 4
2783     .el .IP "\f(CWEV_P\fR, \f(CWEV_P_\fR" 4
2784     .IX Item "EV_P, EV_P_"
2785     This provides the loop \fIparameter\fR for functions, if one is required (\*(L"ev
2786     loop parameter\*(R"). The \f(CW\*(C`EV_P\*(C'\fR form is used when this is the sole parameter,
2787     \&\f(CW\*(C`EV_P_\*(C'\fR is used when other parameters are following. Example:
2788     .Sp
2789     .Vb 2
2790 root 1.68 \& // this is how ev_unref is being declared
2791     \& static void ev_unref (EV_P);
2792 root 1.60 \&
2793 root 1.68 \& // this is how you can declare your typical callback
2794     \& static void cb (EV_P_ ev_timer *w, int revents)
2795 root 1.24 .Ve
2796     .Sp
2797     It declares a parameter \f(CW\*(C`loop\*(C'\fR of type \f(CW\*(C`struct ev_loop *\*(C'\fR, quite
2798     suitable for use with \f(CW\*(C`EV_A\*(C'\fR.
2799     .ie n .IP """EV_DEFAULT""\fR, \f(CW""EV_DEFAULT_""" 4
2800     .el .IP "\f(CWEV_DEFAULT\fR, \f(CWEV_DEFAULT_\fR" 4
2801     .IX Item "EV_DEFAULT, EV_DEFAULT_"
2802     Similar to the other two macros, this gives you the value of the default
2803     loop, if multiple loops are supported (\*(L"ev loop default\*(R").
2804 root 1.64 .ie n .IP """EV_DEFAULT_UC""\fR, \f(CW""EV_DEFAULT_UC_""" 4
2805     .el .IP "\f(CWEV_DEFAULT_UC\fR, \f(CWEV_DEFAULT_UC_\fR" 4
2806     .IX Item "EV_DEFAULT_UC, EV_DEFAULT_UC_"
2807     Usage identical to \f(CW\*(C`EV_DEFAULT\*(C'\fR and \f(CW\*(C`EV_DEFAULT_\*(C'\fR, but requires that the
2808     default loop has been initialised (\f(CW\*(C`UC\*(C'\fR == unchecked). Their behaviour
2809     is undefined when the default loop has not been initialised by a previous
2810     execution of \f(CW\*(C`EV_DEFAULT\*(C'\fR, \f(CW\*(C`EV_DEFAULT_\*(C'\fR or \f(CW\*(C`ev_default_init (...)\*(C'\fR.
2811     .Sp
2812     It is often prudent to use \f(CW\*(C`EV_DEFAULT\*(C'\fR when initialising the first
2813     watcher in a function but use \f(CW\*(C`EV_DEFAULT_UC\*(C'\fR afterwards.
2814 root 1.24 .PP
2815 root 1.36 Example: Declare and initialise a check watcher, utilising the above
2816 root 1.38 macros so it will work regardless of whether multiple loops are supported
2817 root 1.36 or not.
2818 root 1.24 .PP
2819     .Vb 5
2820 root 1.68 \& static void
2821     \& check_cb (EV_P_ ev_timer *w, int revents)
2822     \& {
2823     \& ev_check_stop (EV_A_ w);
2824     \& }
2825     \&
2826     \& ev_check check;
2827     \& ev_check_init (&check, check_cb);
2828     \& ev_check_start (EV_DEFAULT_ &check);
2829     \& ev_loop (EV_DEFAULT_ 0);
2830 root 1.24 .Ve
2831 root 1.14 .SH "EMBEDDING"
2832     .IX Header "EMBEDDING"
2833     Libev can (and often is) directly embedded into host
2834     applications. Examples of applications that embed it include the Deliantra
2835     Game Server, the \s-1EV\s0 perl module, the \s-1GNU\s0 Virtual Private Ethernet (gvpe)
2836 root 1.60 and rxvt-unicode.
2837 root 1.14 .PP
2838 root 1.54 The goal is to enable you to just copy the necessary files into your
2839 root 1.14 source directory without having to change even a single line in them, so
2840     you can easily upgrade by simply copying (or having a checked-out copy of
2841     libev somewhere in your source tree).
2842     .Sh "\s-1FILESETS\s0"
2843     .IX Subsection "FILESETS"
2844     Depending on what features you need you need to include one or more sets of files
2845 root 1.68 in your application.
2846 root 1.14 .PP
2847     \fI\s-1CORE\s0 \s-1EVENT\s0 \s-1LOOP\s0\fR
2848     .IX Subsection "CORE EVENT LOOP"
2849     .PP
2850     To include only the libev core (all the \f(CW\*(C`ev_*\*(C'\fR functions), with manual
2851     configuration (no autoconf):
2852     .PP
2853     .Vb 2
2854 root 1.68 \& #define EV_STANDALONE 1
2855     \& #include "ev.c"
2856 root 1.14 .Ve
2857     .PP
2858     This will automatically include \fIev.h\fR, too, and should be done in a
2859     single C source file only to provide the function implementations. To use
2860     it, do the same for \fIev.h\fR in all files wishing to use this \s-1API\s0 (best
2861     done by writing a wrapper around \fIev.h\fR that you can include instead and
2862     where you can put other configuration options):
2863     .PP
2864     .Vb 2
2865 root 1.68 \& #define EV_STANDALONE 1
2866     \& #include "ev.h"
2867 root 1.14 .Ve
2868     .PP
2869     Both header files and implementation files can be compiled with a \*(C+
2870     compiler (at least, thats a stated goal, and breakage will be treated
2871     as a bug).
2872     .PP
2873     You need the following files in your source tree, or in a directory
2874     in your include path (e.g. in libev/ when using \-Ilibev):
2875     .PP
2876     .Vb 4
2877 root 1.68 \& ev.h
2878     \& ev.c
2879     \& ev_vars.h
2880     \& ev_wrap.h
2881     \&
2882     \& ev_win32.c required on win32 platforms only
2883     \&
2884     \& ev_select.c only when select backend is enabled (which is enabled by default)
2885     \& ev_poll.c only when poll backend is enabled (disabled by default)
2886     \& ev_epoll.c only when the epoll backend is enabled (disabled by default)
2887     \& ev_kqueue.c only when the kqueue backend is enabled (disabled by default)
2888     \& ev_port.c only when the solaris port backend is enabled (disabled by default)
2889 root 1.14 .Ve
2890     .PP
2891     \&\fIev.c\fR includes the backend files directly when enabled, so you only need
2892 root 1.18 to compile this single file.
2893 root 1.14 .PP
2894     \fI\s-1LIBEVENT\s0 \s-1COMPATIBILITY\s0 \s-1API\s0\fR
2895     .IX Subsection "LIBEVENT COMPATIBILITY API"
2896     .PP
2897     To include the libevent compatibility \s-1API\s0, also include:
2898     .PP
2899     .Vb 1
2900 root 1.68 \& #include "event.c"
2901 root 1.14 .Ve
2902     .PP
2903     in the file including \fIev.c\fR, and:
2904     .PP
2905     .Vb 1
2906 root 1.68 \& #include "event.h"
2907 root 1.14 .Ve
2908     .PP
2909     in the files that want to use the libevent \s-1API\s0. This also includes \fIev.h\fR.
2910     .PP
2911     You need the following additional files for this:
2912     .PP
2913     .Vb 2
2914 root 1.68 \& event.h
2915     \& event.c
2916 root 1.14 .Ve
2917     .PP
2918     \fI\s-1AUTOCONF\s0 \s-1SUPPORT\s0\fR
2919     .IX Subsection "AUTOCONF SUPPORT"
2920     .PP
2921 root 1.68 Instead of using \f(CW\*(C`EV_STANDALONE=1\*(C'\fR and providing your configuration in
2922 root 1.14 whatever way you want, you can also \f(CW\*(C`m4_include([libev.m4])\*(C'\fR in your
2923 root 1.18 \&\fIconfigure.ac\fR and leave \f(CW\*(C`EV_STANDALONE\*(C'\fR undefined. \fIev.c\fR will then
2924     include \fIconfig.h\fR and configure itself accordingly.
2925 root 1.14 .PP
2926     For this of course you need the m4 file:
2927     .PP
2928     .Vb 1
2929 root 1.68 \& libev.m4
2930 root 1.14 .Ve
2931     .Sh "\s-1PREPROCESSOR\s0 \s-1SYMBOLS/MACROS\s0"
2932     .IX Subsection "PREPROCESSOR SYMBOLS/MACROS"
2933 root 1.64 Libev can be configured via a variety of preprocessor symbols you have to
2934 root 1.68 define before including any of its files. The default in the absence of
2935 root 1.64 autoconf is noted for every option.
2936 root 1.14 .IP "\s-1EV_STANDALONE\s0" 4
2937     .IX Item "EV_STANDALONE"
2938     Must always be \f(CW1\fR if you do not use autoconf configuration, which
2939     keeps libev from including \fIconfig.h\fR, and it also defines dummy
2940     implementations for some libevent functions (such as logging, which is not
2941     supported). It will also not define any of the structs usually found in
2942     \&\fIevent.h\fR that are not directly supported by the libev core alone.
2943     .IP "\s-1EV_USE_MONOTONIC\s0" 4
2944     .IX Item "EV_USE_MONOTONIC"
2945     If defined to be \f(CW1\fR, libev will try to detect the availability of the
2946 root 1.68 monotonic clock option at both compile time and runtime. Otherwise no use
2947 root 1.14 of the monotonic clock option will be attempted. If you enable this, you
2948     usually have to link against librt or something similar. Enabling it when
2949 root 1.54 the functionality isn't available is safe, though, although you have
2950 root 1.14 to make sure you link against any libraries where the \f(CW\*(C`clock_gettime\*(C'\fR
2951     function is hiding in (often \fI\-lrt\fR).
2952     .IP "\s-1EV_USE_REALTIME\s0" 4
2953     .IX Item "EV_USE_REALTIME"
2954     If defined to be \f(CW1\fR, libev will try to detect the availability of the
2955 root 1.68 real-time clock option at compile time (and assume its availability at
2956     runtime if successful). Otherwise no use of the real-time clock option will
2957 root 1.14 be attempted. This effectively replaces \f(CW\*(C`gettimeofday\*(C'\fR by \f(CW\*(C`clock_get
2958 root 1.54 (CLOCK_REALTIME, ...)\*(C'\fR and will not normally affect correctness. See the
2959     note about libraries in the description of \f(CW\*(C`EV_USE_MONOTONIC\*(C'\fR, though.
2960 root 1.56 .IP "\s-1EV_USE_NANOSLEEP\s0" 4
2961     .IX Item "EV_USE_NANOSLEEP"
2962     If defined to be \f(CW1\fR, libev will assume that \f(CW\*(C`nanosleep ()\*(C'\fR is available
2963     and will use it for delays. Otherwise it will use \f(CW\*(C`select ()\*(C'\fR.
2964 root 1.64 .IP "\s-1EV_USE_EVENTFD\s0" 4
2965     .IX Item "EV_USE_EVENTFD"
2966     If defined to be \f(CW1\fR, then libev will assume that \f(CW\*(C`eventfd ()\*(C'\fR is
2967     available and will probe for kernel support at runtime. This will improve
2968     \&\f(CW\*(C`ev_signal\*(C'\fR and \f(CW\*(C`ev_async\*(C'\fR performance and reduce resource consumption.
2969     If undefined, it will be enabled if the headers indicate GNU/Linux + Glibc
2970     2.7 or newer, otherwise disabled.
2971 root 1.14 .IP "\s-1EV_USE_SELECT\s0" 4
2972     .IX Item "EV_USE_SELECT"
2973     If undefined or defined to be \f(CW1\fR, libev will compile in support for the
2974 root 1.68 \&\f(CW\*(C`select\*(C'\fR(2) backend. No attempt at auto-detection will be done: if no
2975 root 1.14 other method takes over, select will be it. Otherwise the select backend
2976     will not be compiled in.
2977     .IP "\s-1EV_SELECT_USE_FD_SET\s0" 4
2978     .IX Item "EV_SELECT_USE_FD_SET"
2979     If defined to \f(CW1\fR, then the select backend will use the system \f(CW\*(C`fd_set\*(C'\fR
2980     structure. This is useful if libev doesn't compile due to a missing
2981 root 1.68 \&\f(CW\*(C`NFDBITS\*(C'\fR or \f(CW\*(C`fd_mask\*(C'\fR definition or it mis-guesses the bitset layout on
2982 root 1.14 exotic systems. This usually limits the range of file descriptors to some
2983     low limit such as 1024 or might have other limitations (winsocket only
2984     allows 64 sockets). The \f(CW\*(C`FD_SETSIZE\*(C'\fR macro, set before compilation, might
2985     influence the size of the \f(CW\*(C`fd_set\*(C'\fR used.
2986     .IP "\s-1EV_SELECT_IS_WINSOCKET\s0" 4
2987     .IX Item "EV_SELECT_IS_WINSOCKET"
2988     When defined to \f(CW1\fR, the select backend will assume that
2989     select/socket/connect etc. don't understand file descriptors but
2990     wants osf handles on win32 (this is the case when the select to
2991     be used is the winsock select). This means that it will call
2992     \&\f(CW\*(C`_get_osfhandle\*(C'\fR on the fd to convert it to an \s-1OS\s0 handle. Otherwise,
2993     it is assumed that all these functions actually work on fds, even
2994     on win32. Should not be defined on non\-win32 platforms.
2995 root 1.60 .IP "\s-1EV_FD_TO_WIN32_HANDLE\s0" 4
2996     .IX Item "EV_FD_TO_WIN32_HANDLE"
2997     If \f(CW\*(C`EV_SELECT_IS_WINSOCKET\*(C'\fR is enabled, then libev needs a way to map
2998     file descriptors to socket handles. When not defining this symbol (the
2999     default), then libev will call \f(CW\*(C`_get_osfhandle\*(C'\fR, which is usually
3000     correct. In some cases, programs use their own file descriptor management,
3001     in which case they can provide this function to map fds to socket handles.
3002 root 1.14 .IP "\s-1EV_USE_POLL\s0" 4
3003     .IX Item "EV_USE_POLL"
3004     If defined to be \f(CW1\fR, libev will compile in support for the \f(CW\*(C`poll\*(C'\fR(2)
3005     backend. Otherwise it will be enabled on non\-win32 platforms. It
3006     takes precedence over select.
3007     .IP "\s-1EV_USE_EPOLL\s0" 4
3008     .IX Item "EV_USE_EPOLL"
3009     If defined to be \f(CW1\fR, libev will compile in support for the Linux
3010     \&\f(CW\*(C`epoll\*(C'\fR(7) backend. Its availability will be detected at runtime,
3011 root 1.64 otherwise another method will be used as fallback. This is the preferred
3012     backend for GNU/Linux systems. If undefined, it will be enabled if the
3013     headers indicate GNU/Linux + Glibc 2.4 or newer, otherwise disabled.
3014 root 1.14 .IP "\s-1EV_USE_KQUEUE\s0" 4
3015     .IX Item "EV_USE_KQUEUE"
3016     If defined to be \f(CW1\fR, libev will compile in support for the \s-1BSD\s0 style
3017     \&\f(CW\*(C`kqueue\*(C'\fR(2) backend. Its actual availability will be detected at runtime,
3018     otherwise another method will be used as fallback. This is the preferred
3019     backend for \s-1BSD\s0 and BSD-like systems, although on most BSDs kqueue only
3020     supports some types of fds correctly (the only platform we found that
3021     supports ptys for example was NetBSD), so kqueue might be compiled in, but
3022     not be used unless explicitly requested. The best way to use it is to find
3023 root 1.16 out whether kqueue supports your type of fd properly and use an embedded
3024 root 1.14 kqueue loop.
3025     .IP "\s-1EV_USE_PORT\s0" 4
3026     .IX Item "EV_USE_PORT"
3027     If defined to be \f(CW1\fR, libev will compile in support for the Solaris
3028     10 port style backend. Its availability will be detected at runtime,
3029     otherwise another method will be used as fallback. This is the preferred
3030     backend for Solaris 10 systems.
3031     .IP "\s-1EV_USE_DEVPOLL\s0" 4
3032     .IX Item "EV_USE_DEVPOLL"
3033 root 1.68 Reserved for future expansion, works like the \s-1USE\s0 symbols above.
3034 root 1.30 .IP "\s-1EV_USE_INOTIFY\s0" 4
3035     .IX Item "EV_USE_INOTIFY"
3036     If defined to be \f(CW1\fR, libev will compile in support for the Linux inotify
3037     interface to speed up \f(CW\*(C`ev_stat\*(C'\fR watchers. Its actual availability will
3038 root 1.64 be detected at runtime. If undefined, it will be enabled if the headers
3039     indicate GNU/Linux + Glibc 2.4 or newer, otherwise disabled.
3040 root 1.61 .IP "\s-1EV_ATOMIC_T\s0" 4
3041     .IX Item "EV_ATOMIC_T"
3042     Libev requires an integer type (suitable for storing \f(CW0\fR or \f(CW1\fR) whose
3043     access is atomic with respect to other threads or signal contexts. No such
3044     type is easily found in the C language, so you can provide your own type
3045     that you know is safe for your purposes. It is used both for signal handler \*(L"locking\*(R"
3046     as well as for signal and thread safety in \f(CW\*(C`ev_async\*(C'\fR watchers.
3047     .Sp
3048 root 1.68 In the absence of this define, libev will use \f(CW\*(C`sig_atomic_t volatile\*(C'\fR
3049 root 1.61 (from \fIsignal.h\fR), which is usually good enough on most platforms.
3050 root 1.14 .IP "\s-1EV_H\s0" 4
3051     .IX Item "EV_H"
3052     The name of the \fIev.h\fR header file used to include it. The default if
3053 root 1.60 undefined is \f(CW"ev.h"\fR in \fIevent.h\fR, \fIev.c\fR and \fIev++.h\fR. This can be
3054     used to virtually rename the \fIev.h\fR header file in case of conflicts.
3055 root 1.14 .IP "\s-1EV_CONFIG_H\s0" 4
3056     .IX Item "EV_CONFIG_H"
3057     If \f(CW\*(C`EV_STANDALONE\*(C'\fR isn't \f(CW1\fR, this variable can be used to override
3058     \&\fIev.c\fR's idea of where to find the \fIconfig.h\fR file, similarly to
3059     \&\f(CW\*(C`EV_H\*(C'\fR, above.
3060     .IP "\s-1EV_EVENT_H\s0" 4
3061     .IX Item "EV_EVENT_H"
3062     Similarly to \f(CW\*(C`EV_H\*(C'\fR, this macro can be used to override \fIevent.c\fR's idea
3063 root 1.60 of how the \fIevent.h\fR header can be found, the default is \f(CW"event.h"\fR.
3064 root 1.14 .IP "\s-1EV_PROTOTYPES\s0" 4
3065     .IX Item "EV_PROTOTYPES"
3066     If defined to be \f(CW0\fR, then \fIev.h\fR will not define any function
3067     prototypes, but still define all the structs and other symbols. This is
3068     occasionally useful if you want to provide your own wrapper functions
3069     around libev functions.
3070     .IP "\s-1EV_MULTIPLICITY\s0" 4
3071     .IX Item "EV_MULTIPLICITY"
3072     If undefined or defined to \f(CW1\fR, then all event-loop-specific functions
3073     will have the \f(CW\*(C`struct ev_loop *\*(C'\fR as first argument, and you can create
3074     additional independent event loops. Otherwise there will be no support
3075     for multiple event loops and there is no first event loop pointer
3076     argument. Instead, all functions act on the single default loop.
3077 root 1.39 .IP "\s-1EV_MINPRI\s0" 4
3078     .IX Item "EV_MINPRI"
3079     .PD 0
3080     .IP "\s-1EV_MAXPRI\s0" 4
3081     .IX Item "EV_MAXPRI"
3082     .PD
3083     The range of allowed priorities. \f(CW\*(C`EV_MINPRI\*(C'\fR must be smaller or equal to
3084     \&\f(CW\*(C`EV_MAXPRI\*(C'\fR, but otherwise there are no non-obvious limitations. You can
3085     provide for more priorities by overriding those symbols (usually defined
3086     to be \f(CW\*(C`\-2\*(C'\fR and \f(CW2\fR, respectively).
3087     .Sp
3088     When doing priority-based operations, libev usually has to linearly search
3089     all the priorities, so having many of them (hundreds) uses a lot of space
3090     and time, so using the defaults of five priorities (\-2 .. +2) is usually
3091     fine.
3092     .Sp
3093 root 1.68 If your embedding application does not need any priorities, defining these both to
3094     \&\f(CW0\fR will save some memory and \s-1CPU\s0.
3095 root 1.22 .IP "\s-1EV_PERIODIC_ENABLE\s0" 4
3096     .IX Item "EV_PERIODIC_ENABLE"
3097     If undefined or defined to be \f(CW1\fR, then periodic timers are supported. If
3098     defined to be \f(CW0\fR, then they are not. Disabling them saves a few kB of
3099     code.
3100 root 1.37 .IP "\s-1EV_IDLE_ENABLE\s0" 4
3101     .IX Item "EV_IDLE_ENABLE"
3102     If undefined or defined to be \f(CW1\fR, then idle watchers are supported. If
3103     defined to be \f(CW0\fR, then they are not. Disabling them saves a few kB of
3104     code.
3105 root 1.22 .IP "\s-1EV_EMBED_ENABLE\s0" 4
3106     .IX Item "EV_EMBED_ENABLE"
3107     If undefined or defined to be \f(CW1\fR, then embed watchers are supported. If
3108     defined to be \f(CW0\fR, then they are not.
3109     .IP "\s-1EV_STAT_ENABLE\s0" 4
3110     .IX Item "EV_STAT_ENABLE"
3111     If undefined or defined to be \f(CW1\fR, then stat watchers are supported. If
3112     defined to be \f(CW0\fR, then they are not.
3113 root 1.24 .IP "\s-1EV_FORK_ENABLE\s0" 4
3114     .IX Item "EV_FORK_ENABLE"
3115     If undefined or defined to be \f(CW1\fR, then fork watchers are supported. If
3116     defined to be \f(CW0\fR, then they are not.
3117 root 1.61 .IP "\s-1EV_ASYNC_ENABLE\s0" 4
3118     .IX Item "EV_ASYNC_ENABLE"
3119     If undefined or defined to be \f(CW1\fR, then async watchers are supported. If
3120     defined to be \f(CW0\fR, then they are not.
3121 root 1.22 .IP "\s-1EV_MINIMAL\s0" 4
3122     .IX Item "EV_MINIMAL"
3123     If you need to shave off some kilobytes of code at the expense of some
3124 root 1.65 speed, define this symbol to \f(CW1\fR. Currently this is used to override some
3125 root 1.68 inlining decisions, saves roughly 30% code size on amd64. It also selects a
3126 root 1.65 much smaller 2\-heap for timer management over the default 4\-heap.
3127 root 1.25 .IP "\s-1EV_PID_HASHSIZE\s0" 4
3128     .IX Item "EV_PID_HASHSIZE"
3129     \&\f(CW\*(C`ev_child\*(C'\fR watchers use a small hash table to distribute workload by
3130     pid. The default size is \f(CW16\fR (or \f(CW1\fR with \f(CW\*(C`EV_MINIMAL\*(C'\fR), usually more
3131     than enough. If you need to manage thousands of children you might want to
3132 root 1.30 increase this value (\fImust\fR be a power of two).
3133     .IP "\s-1EV_INOTIFY_HASHSIZE\s0" 4
3134     .IX Item "EV_INOTIFY_HASHSIZE"
3135 root 1.59 \&\f(CW\*(C`ev_stat\*(C'\fR watchers use a small hash table to distribute workload by
3136 root 1.30 inotify watch id. The default size is \f(CW16\fR (or \f(CW1\fR with \f(CW\*(C`EV_MINIMAL\*(C'\fR),
3137     usually more than enough. If you need to manage thousands of \f(CW\*(C`ev_stat\*(C'\fR
3138     watchers you might want to increase this value (\fImust\fR be a power of
3139     two).
3140 root 1.65 .IP "\s-1EV_USE_4HEAP\s0" 4
3141     .IX Item "EV_USE_4HEAP"
3142     Heaps are not very cache-efficient. To improve the cache-efficiency of the
3143     timer and periodics heap, libev uses a 4\-heap when this symbol is defined
3144 root 1.67 to \f(CW1\fR. The 4\-heap uses more complicated (longer) code but has
3145 root 1.68 noticeably faster performance with many (thousands) of watchers.
3146 root 1.65 .Sp
3147     The default is \f(CW1\fR unless \f(CW\*(C`EV_MINIMAL\*(C'\fR is set in which case it is \f(CW0\fR
3148     (disabled).
3149     .IP "\s-1EV_HEAP_CACHE_AT\s0" 4
3150     .IX Item "EV_HEAP_CACHE_AT"
3151     Heaps are not very cache-efficient. To improve the cache-efficiency of the
3152     timer and periodics heap, libev can cache the timestamp (\fIat\fR) within
3153     the heap structure (selected by defining \f(CW\*(C`EV_HEAP_CACHE_AT\*(C'\fR to \f(CW1\fR),
3154     which uses 8\-12 bytes more per watcher and a few hundred bytes more code,
3155 root 1.67 but avoids random read accesses on heap changes. This improves performance
3156 root 1.68 noticeably with with many (hundreds) of watchers.
3157 root 1.65 .Sp
3158     The default is \f(CW1\fR unless \f(CW\*(C`EV_MINIMAL\*(C'\fR is set in which case it is \f(CW0\fR
3159     (disabled).
3160 root 1.67 .IP "\s-1EV_VERIFY\s0" 4
3161     .IX Item "EV_VERIFY"
3162     Controls how much internal verification (see \f(CW\*(C`ev_loop_verify ()\*(C'\fR) will
3163     be done: If set to \f(CW0\fR, no internal verification code will be compiled
3164     in. If set to \f(CW1\fR, then verification code will be compiled in, but not
3165     called. If set to \f(CW2\fR, then the internal verification code will be
3166     called once per loop, which can slow down libev. If set to \f(CW3\fR, then the
3167     verification code will be called very frequently, which will slow down
3168     libev considerably.
3169     .Sp
3170     The default is \f(CW1\fR, unless \f(CW\*(C`EV_MINIMAL\*(C'\fR is set, in which case it will be
3171     \&\f(CW0.\fR
3172 root 1.14 .IP "\s-1EV_COMMON\s0" 4
3173     .IX Item "EV_COMMON"
3174     By default, all watchers have a \f(CW\*(C`void *data\*(C'\fR member. By redefining
3175     this macro to a something else you can include more and other types of
3176     members. You have to define it each time you include one of the files,
3177     though, and it must be identical each time.
3178     .Sp
3179     For example, the perl \s-1EV\s0 module uses something like this:
3180     .Sp
3181     .Vb 3
3182 root 1.68 \& #define EV_COMMON \e
3183     \& SV *self; /* contains this struct */ \e
3184     \& SV *cb_sv, *fh /* note no trailing ";" */
3185 root 1.14 .Ve
3186 root 1.19 .IP "\s-1EV_CB_DECLARE\s0 (type)" 4
3187     .IX Item "EV_CB_DECLARE (type)"
3188 root 1.14 .PD 0
3189 root 1.19 .IP "\s-1EV_CB_INVOKE\s0 (watcher, revents)" 4
3190     .IX Item "EV_CB_INVOKE (watcher, revents)"
3191     .IP "ev_set_cb (ev, cb)" 4
3192     .IX Item "ev_set_cb (ev, cb)"
3193 root 1.14 .PD
3194     Can be used to change the callback member declaration in each watcher,
3195     and the way callbacks are invoked and set. Must expand to a struct member
3196 root 1.54 definition and a statement, respectively. See the \fIev.h\fR header file for
3197 root 1.14 their default definitions. One possible use for overriding these is to
3198 root 1.19 avoid the \f(CW\*(C`struct ev_loop *\*(C'\fR as first argument in all cases, or to use
3199     method calls instead of plain function calls in \*(C+.
3200 root 1.53 .Sh "\s-1EXPORTED\s0 \s-1API\s0 \s-1SYMBOLS\s0"
3201     .IX Subsection "EXPORTED API SYMBOLS"
3202 root 1.68 If you need to re-export the \s-1API\s0 (e.g. via a \s-1DLL\s0) and you need a list of
3203 root 1.53 exported symbols, you can use the provided \fISymbol.*\fR files which list
3204     all public symbols, one per line:
3205 root 1.60 .PP
3206 root 1.53 .Vb 2
3207 root 1.68 \& Symbols.ev for libev proper
3208     \& Symbols.event for the libevent emulation
3209 root 1.53 .Ve
3210 root 1.60 .PP
3211 root 1.53 This can also be used to rename all public symbols to avoid clashes with
3212     multiple versions of libev linked together (which is obviously bad in
3213 root 1.68 itself, but sometimes it is inconvenient to avoid this).
3214 root 1.60 .PP
3215 root 1.54 A sed command like this will create wrapper \f(CW\*(C`#define\*(C'\fR's that you need to
3216 root 1.53 include before including \fIev.h\fR:
3217 root 1.60 .PP
3218 root 1.53 .Vb 1
3219 root 1.60 \& <Symbols.ev sed \-e "s/.*/#define & myprefix_&/" >wrap.h
3220 root 1.53 .Ve
3221 root 1.60 .PP
3222 root 1.53 This would create a file \fIwrap.h\fR which essentially looks like this:
3223 root 1.60 .PP
3224 root 1.53 .Vb 4
3225     \& #define ev_backend myprefix_ev_backend
3226     \& #define ev_check_start myprefix_ev_check_start
3227     \& #define ev_check_stop myprefix_ev_check_stop
3228     \& ...
3229     .Ve
3230 root 1.14 .Sh "\s-1EXAMPLES\s0"
3231     .IX Subsection "EXAMPLES"
3232     For a real-world example of a program the includes libev
3233     verbatim, you can have a look at the \s-1EV\s0 perl module
3234     (<http://software.schmorp.de/pkg/EV.html>). It has the libev files in
3235     the \fIlibev/\fR subdirectory and includes them in the \fI\s-1EV/EVAPI\s0.h\fR (public
3236     interface) and \fI\s-1EV\s0.xs\fR (implementation) files. Only the \fI\s-1EV\s0.xs\fR file
3237     will be compiled. It is pretty complex because it provides its own header
3238     file.
3239 root 1.60 .PP
3240 root 1.14 The usage in rxvt-unicode is simpler. It has a \fIev_cpp.h\fR header file
3241 root 1.36 that everybody includes and which overrides some configure choices:
3242 root 1.60 .PP
3243 root 1.36 .Vb 9
3244 root 1.68 \& #define EV_MINIMAL 1
3245     \& #define EV_USE_POLL 0
3246     \& #define EV_MULTIPLICITY 0
3247     \& #define EV_PERIODIC_ENABLE 0
3248     \& #define EV_STAT_ENABLE 0
3249     \& #define EV_FORK_ENABLE 0
3250     \& #define EV_CONFIG_H <config.h>
3251     \& #define EV_MINPRI 0
3252     \& #define EV_MAXPRI 0
3253 root 1.60 \&
3254 root 1.68 \& #include "ev++.h"
3255 root 1.14 .Ve
3256 root 1.60 .PP
3257 root 1.14 And a \fIev_cpp.C\fR implementation file that contains libev proper and is compiled:
3258 root 1.60 .PP
3259 root 1.14 .Vb 2
3260 root 1.68 \& #include "ev_cpp.h"
3261     \& #include "ev.c"
3262 root 1.14 .Ve
3263 root 1.64 .SH "THREADS AND COROUTINES"
3264     .IX Header "THREADS AND COROUTINES"
3265     .Sh "\s-1THREADS\s0"
3266     .IX Subsection "THREADS"
3267 root 1.68 Libev itself is completely thread-safe, but it uses no locking. This
3268 root 1.64 means that you can use as many loops as you want in parallel, as long as
3269     only one thread ever calls into one libev function with the same loop
3270     parameter.
3271     .PP
3272     Or put differently: calls with different loop parameters can be done in
3273     parallel from multiple threads, calls with the same loop parameter must be
3274     done serially (but can be done from different threads, as long as only one
3275     thread ever is inside a call at any point in time, e.g. by using a mutex
3276     per loop).
3277     .PP
3278     If you want to know which design is best for your problem, then I cannot
3279     help you but by giving some generic advice:
3280     .IP "\(bu" 4
3281     most applications have a main thread: use the default libev loop
3282 root 1.68 in that thread, or create a separate thread running only the default loop.
3283 root 1.64 .Sp
3284     This helps integrating other libraries or software modules that use libev
3285     themselves and don't care/know about threading.
3286     .IP "\(bu" 4
3287     one loop per thread is usually a good model.
3288     .Sp
3289     Doing this is almost never wrong, sometimes a better-performance model
3290     exists, but it is always a good start.
3291     .IP "\(bu" 4
3292     other models exist, such as the leader/follower pattern, where one
3293 root 1.68 loop is handed through multiple threads in a kind of round-robin fashion.
3294 root 1.64 .Sp
3295 root 1.68 Choosing a model is hard \- look around, learn, know that usually you can do
3296 root 1.64 better than you currently do :\-)
3297     .IP "\(bu" 4
3298     often you need to talk to some other thread which blocks in the
3299     event loop \- \f(CW\*(C`ev_async\*(C'\fR watchers can be used to wake them up from other
3300     threads safely (or from signal contexts...).
3301     .Sh "\s-1COROUTINES\s0"
3302     .IX Subsection "COROUTINES"
3303 root 1.68 Libev is much more accommodating to coroutines (\*(L"cooperative threads\*(R"):
3304 root 1.64 libev fully supports nesting calls to it's functions from different
3305     coroutines (e.g. you can call \f(CW\*(C`ev_loop\*(C'\fR on the same loop from two
3306     different coroutines and switch freely between both coroutines running the
3307     loop, as long as you don't confuse yourself). The only exception is that
3308     you must not do this from \f(CW\*(C`ev_periodic\*(C'\fR reschedule callbacks.
3309     .PP
3310     Care has been invested into making sure that libev does not keep local
3311     state inside \f(CW\*(C`ev_loop\*(C'\fR, and other calls do not usually allow coroutine
3312     switches.
3313 root 1.21 .SH "COMPLEXITIES"
3314     .IX Header "COMPLEXITIES"
3315     In this section the complexities of (many of) the algorithms used inside
3316     libev will be explained. For complexity discussions about backends see the
3317     documentation for \f(CW\*(C`ev_default_init\*(C'\fR.
3318 root 1.60 .PP
3319 root 1.40 All of the following are about amortised time: If an array needs to be
3320     extended, libev needs to realloc and move the whole array, but this
3321     happens asymptotically never with higher number of elements, so O(1) might
3322     mean it might do a lengthy realloc operation in rare cases, but on average
3323     it is much faster and asymptotically approaches constant time.
3324 root 1.21 .IP "Starting and stopping timer/periodic watchers: O(log skipped_other_timers)" 4
3325     .IX Item "Starting and stopping timer/periodic watchers: O(log skipped_other_timers)"
3326 root 1.39 This means that, when you have a watcher that triggers in one hour and
3327     there are 100 watchers that would trigger before that then inserting will
3328 root 1.59 have to skip roughly seven (\f(CW\*(C`ld 100\*(C'\fR) of these watchers.
3329     .IP "Changing timer/periodic watchers (by autorepeat or calling again): O(log skipped_other_timers)" 4
3330     .IX Item "Changing timer/periodic watchers (by autorepeat or calling again): O(log skipped_other_timers)"
3331     That means that changing a timer costs less than removing/adding them
3332 root 1.39 as only the relative motion in the event queue has to be paid for.
3333 root 1.61 .IP "Starting io/check/prepare/idle/signal/child/fork/async watchers: O(1)" 4
3334     .IX Item "Starting io/check/prepare/idle/signal/child/fork/async watchers: O(1)"
3335 root 1.40 These just add the watcher into an array or at the head of a list.
3336 root 1.61 .IP "Stopping check/prepare/idle/fork/async watchers: O(1)" 4
3337     .IX Item "Stopping check/prepare/idle/fork/async watchers: O(1)"
3338 root 1.59 .PD 0
3339 root 1.30 .IP "Stopping an io/signal/child watcher: O(number_of_watchers_for_this_(fd/signal/pid % \s-1EV_PID_HASHSIZE\s0))" 4
3340     .IX Item "Stopping an io/signal/child watcher: O(number_of_watchers_for_this_(fd/signal/pid % EV_PID_HASHSIZE))"
3341 root 1.59 .PD
3342 root 1.39 These watchers are stored in lists then need to be walked to find the
3343     correct watcher to remove. The lists are usually short (you don't usually
3344     have many watchers waiting for the same fd or signal).
3345 root 1.59 .IP "Finding the next timer in each loop iteration: O(1)" 4
3346     .IX Item "Finding the next timer in each loop iteration: O(1)"
3347 root 1.65 By virtue of using a binary or 4\-heap, the next timer is always found at a
3348     fixed position in the storage array.
3349 root 1.21 .IP "Each change on a file descriptor per loop iteration: O(number_of_watchers_for_this_fd)" 4
3350     .IX Item "Each change on a file descriptor per loop iteration: O(number_of_watchers_for_this_fd)"
3351 root 1.39 A change means an I/O watcher gets started or stopped, which requires
3352 root 1.59 libev to recalculate its status (and possibly tell the kernel, depending
3353 root 1.68 on backend and whether \f(CW\*(C`ev_io_set\*(C'\fR was used).
3354 root 1.59 .IP "Activating one watcher (putting it into the pending state): O(1)" 4
3355     .IX Item "Activating one watcher (putting it into the pending state): O(1)"
3356 root 1.39 .PD 0
3357     .IP "Priority handling: O(number_of_priorities)" 4
3358     .IX Item "Priority handling: O(number_of_priorities)"
3359     .PD
3360     Priorities are implemented by allocating some space for each
3361     priority. When doing priority-based operations, libev usually has to
3362 root 1.59 linearly search all the priorities, but starting/stopping and activating
3363 root 1.61 watchers becomes O(1) w.r.t. priority handling.
3364     .IP "Sending an ev_async: O(1)" 4
3365     .IX Item "Sending an ev_async: O(1)"
3366     .PD 0
3367     .IP "Processing ev_async_send: O(number_of_async_watchers)" 4
3368     .IX Item "Processing ev_async_send: O(number_of_async_watchers)"
3369     .IP "Processing signals: O(max_signal_number)" 4
3370     .IX Item "Processing signals: O(max_signal_number)"
3371     .PD
3372 root 1.68 Sending involves a system call \fIiff\fR there were no other \f(CW\*(C`ev_async_send\*(C'\fR
3373 root 1.61 calls in the current loop iteration. Checking for async and signal events
3374     involves iterating over all running async watchers or all signal numbers.
3375 root 1.68 .SH "WIN32 PLATFORM LIMITATIONS AND WORKAROUNDS"
3376     .IX Header "WIN32 PLATFORM LIMITATIONS AND WORKAROUNDS"
3377 root 1.60 Win32 doesn't support any of the standards (e.g. \s-1POSIX\s0) that libev
3378     requires, and its I/O model is fundamentally incompatible with the \s-1POSIX\s0
3379     model. Libev still offers limited functionality on this platform in
3380     the form of the \f(CW\*(C`EVBACKEND_SELECT\*(C'\fR backend, and only supports socket
3381     descriptors. This only applies when using Win32 natively, not when using
3382     e.g. cygwin.
3383     .PP
3384 root 1.65 Lifting these limitations would basically require the full
3385     re-implementation of the I/O system. If you are into these kinds of
3386     things, then note that glib does exactly that for you in a very portable
3387     way (note also that glib is the slowest event library known to man).
3388     .PP
3389 root 1.60 There is no supported compilation method available on windows except
3390     embedding it into other applications.
3391     .PP
3392 root 1.68 Not a libev limitation but worth mentioning: windows apparently doesn't
3393     accept large writes: instead of resulting in a partial write, windows will
3394     either accept everything or return \f(CW\*(C`ENOBUFS\*(C'\fR if the buffer is too large,
3395     so make sure you only write small amounts into your sockets (less than a
3396     megabyte seems safe, but thsi apparently depends on the amount of memory
3397     available).
3398     .PP
3399 root 1.65 Due to the many, low, and arbitrary limits on the win32 platform and
3400     the abysmal performance of winsockets, using a large number of sockets
3401     is not recommended (and not reasonable). If your program needs to use
3402     more than a hundred or so sockets, then likely it needs to use a totally
3403 root 1.67 different implementation for windows, as libev offers the \s-1POSIX\s0 readiness
3404 root 1.65 notification model, which cannot be implemented efficiently on windows
3405 root 1.68 (Microsoft monopoly games).
3406     .PP
3407     A typical way to use libev under windows is to embed it (see the embedding
3408     section for details) and use the following \fIevwrap.h\fR header file instead
3409     of \fIev.h\fR:
3410     .PP
3411     .Vb 2
3412     \& #define EV_STANDALONE /* keeps ev from requiring config.h */
3413     \& #define EV_SELECT_IS_WINSOCKET 1 /* configure libev for windows select */
3414     \&
3415     \& #include "ev.h"
3416     .Ve
3417     .PP
3418     And compile the following \fIevwrap.c\fR file into your project (make sure
3419     you do \fInot\fR compile the \fIev.c\fR or any other embedded soruce files!):
3420     .PP
3421     .Vb 2
3422     \& #include "evwrap.h"
3423     \& #include "ev.c"
3424     .Ve
3425 root 1.60 .IP "The winsocket select function" 4
3426     .IX Item "The winsocket select function"
3427 root 1.67 The winsocket \f(CW\*(C`select\*(C'\fR function doesn't follow \s-1POSIX\s0 in that it
3428     requires socket \fIhandles\fR and not socket \fIfile descriptors\fR (it is
3429     also extremely buggy). This makes select very inefficient, and also
3430 root 1.68 requires a mapping from file descriptors to socket handles (the Microsoft
3431     C runtime provides the function \f(CW\*(C`_open_osfhandle\*(C'\fR for this). See the
3432 root 1.67 discussion of the \f(CW\*(C`EV_SELECT_USE_FD_SET\*(C'\fR, \f(CW\*(C`EV_SELECT_IS_WINSOCKET\*(C'\fR and
3433     \&\f(CW\*(C`EV_FD_TO_WIN32_HANDLE\*(C'\fR preprocessor symbols for more info.
3434 root 1.60 .Sp
3435 root 1.68 The configuration for a \*(L"naked\*(R" win32 using the Microsoft runtime
3436 root 1.60 libraries and raw winsocket select is:
3437     .Sp
3438     .Vb 2
3439 root 1.68 \& #define EV_USE_SELECT 1
3440     \& #define EV_SELECT_IS_WINSOCKET 1 /* forces EV_SELECT_USE_FD_SET, too */
3441 root 1.60 .Ve
3442     .Sp
3443     Note that winsockets handling of fd sets is O(n), so you can easily get a
3444     complexity in the O(nA\*^X) range when using win32.
3445     .IP "Limited number of file descriptors" 4
3446     .IX Item "Limited number of file descriptors"
3447 root 1.65 Windows has numerous arbitrary (and low) limits on things.
3448     .Sp
3449     Early versions of winsocket's select only supported waiting for a maximum
3450     of \f(CW64\fR handles (probably owning to the fact that all windows kernels
3451 root 1.68 can only wait for \f(CW64\fR things at the same time internally; Microsoft
3452 root 1.65 recommends spawning a chain of threads and wait for 63 handles and the
3453     previous thread in each. Great).
3454 root 1.60 .Sp
3455     Newer versions support more handles, but you need to define \f(CW\*(C`FD_SETSIZE\*(C'\fR
3456     to some high number (e.g. \f(CW2048\fR) before compiling the winsocket select
3457     call (which might be in libev or elsewhere, for example, perl does its own
3458     select emulation on windows).
3459     .Sp
3460 root 1.68 Another limit is the number of file descriptors in the Microsoft runtime
3461 root 1.60 libraries, which by default is \f(CW64\fR (there must be a hidden \fI64\fR fetish
3462 root 1.68 or something like this inside Microsoft). You can increase this by calling
3463 root 1.60 \&\f(CW\*(C`_setmaxstdio\*(C'\fR, which can increase this limit to \f(CW2048\fR (another
3464 root 1.68 arbitrary limit), but is broken in many versions of the Microsoft runtime
3465 root 1.60 libraries.
3466     .Sp
3467     This might get you to about \f(CW512\fR or \f(CW2048\fR sockets (depending on
3468     windows version and/or the phase of the moon). To get more, you need to
3469     wrap all I/O functions and provide your own fd management, but the cost of
3470     calling select (O(nA\*^X)) will likely make this unworkable.
3471 root 1.65 .SH "PORTABILITY REQUIREMENTS"
3472     .IX Header "PORTABILITY REQUIREMENTS"
3473     In addition to a working ISO-C implementation, libev relies on a few
3474     additional extensions:
3475 root 1.68 .ie n .IP """void (*)(ev_watcher_type *, int revents)""\fR must have compatible calling conventions regardless of \f(CW""ev_watcher_type *""." 4
3476     .el .IP "\f(CWvoid (*)(ev_watcher_type *, int revents)\fR must have compatible calling conventions regardless of \f(CWev_watcher_type *\fR." 4
3477     .IX Item "void (*)(ev_watcher_type *, int revents) must have compatible calling conventions regardless of ev_watcher_type *."
3478     Libev assumes not only that all watcher pointers have the same internal
3479     structure (guaranteed by \s-1POSIX\s0 but not by \s-1ISO\s0 C for example), but it also
3480     assumes that the same (machine) code can be used to call any watcher
3481     callback: The watcher callbacks have different type signatures, but libev
3482     calls them using an \f(CW\*(C`ev_watcher *\*(C'\fR internally.
3483 root 1.65 .ie n .IP """sig_atomic_t volatile"" must be thread-atomic as well" 4
3484     .el .IP "\f(CWsig_atomic_t volatile\fR must be thread-atomic as well" 4
3485     .IX Item "sig_atomic_t volatile must be thread-atomic as well"
3486     The type \f(CW\*(C`sig_atomic_t volatile\*(C'\fR (or whatever is defined as
3487     \&\f(CW\*(C`EV_ATOMIC_T\*(C'\fR) must be atomic w.r.t. accesses from different
3488     threads. This is not part of the specification for \f(CW\*(C`sig_atomic_t\*(C'\fR, but is
3489     believed to be sufficiently portable.
3490     .ie n .IP """sigprocmask"" must work in a threaded environment" 4
3491     .el .IP "\f(CWsigprocmask\fR must work in a threaded environment" 4
3492     .IX Item "sigprocmask must work in a threaded environment"
3493     Libev uses \f(CW\*(C`sigprocmask\*(C'\fR to temporarily block signals. This is not
3494     allowed in a threaded program (\f(CW\*(C`pthread_sigmask\*(C'\fR has to be used). Typical
3495     pthread implementations will either allow \f(CW\*(C`sigprocmask\*(C'\fR in the \*(L"main
3496     thread\*(R" or will block signals process-wide, both behaviours would
3497     be compatible with libev. Interaction between \f(CW\*(C`sigprocmask\*(C'\fR and
3498     \&\f(CW\*(C`pthread_sigmask\*(C'\fR could complicate things, however.
3499     .Sp
3500     The most portable way to handle signals is to block signals in all threads
3501     except the initial one, and run the default loop in the initial thread as
3502     well.
3503     .ie n .IP """long"" must be large enough for common memory allocation sizes" 4
3504     .el .IP "\f(CWlong\fR must be large enough for common memory allocation sizes" 4
3505     .IX Item "long must be large enough for common memory allocation sizes"
3506     To improve portability and simplify using libev, libev uses \f(CW\*(C`long\*(C'\fR
3507     internally instead of \f(CW\*(C`size_t\*(C'\fR when allocating its data structures. On
3508     non-POSIX systems (Microsoft...) this might be unexpectedly low, but
3509     is still at least 31 bits everywhere, which is enough for hundreds of
3510     millions of watchers.
3511     .ie n .IP """double"" must hold a time value in seconds with enough accuracy" 4
3512     .el .IP "\f(CWdouble\fR must hold a time value in seconds with enough accuracy" 4
3513     .IX Item "double must hold a time value in seconds with enough accuracy"
3514     The type \f(CW\*(C`double\*(C'\fR is used to represent timestamps. It is required to
3515     have at least 51 bits of mantissa (and 9 bits of exponent), which is good
3516     enough for at least into the year 4000. This requirement is fulfilled by
3517     implementations implementing \s-1IEEE\s0 754 (basically all existing ones).
3518     .PP
3519     If you know of other additional requirements drop me a note.
3520 root 1.67 .SH "COMPILER WARNINGS"
3521     .IX Header "COMPILER WARNINGS"
3522     Depending on your compiler and compiler settings, you might get no or a
3523     lot of warnings when compiling libev code. Some people are apparently
3524     scared by this.
3525     .PP
3526     However, these are unavoidable for many reasons. For one, each compiler
3527     has different warnings, and each user has different tastes regarding
3528     warning options. \*(L"Warn-free\*(R" code therefore cannot be a goal except when
3529 root 1.68 targeting a specific compiler and compiler-version.
3530 root 1.67 .PP
3531     Another reason is that some compiler warnings require elaborate
3532     workarounds, or other changes to the code that make it less clear and less
3533     maintainable.
3534     .PP
3535     And of course, some compiler warnings are just plain stupid, or simply
3536 root 1.68 wrong (because they don't actually warn about the condition their message
3537 root 1.67 seems to warn about).
3538     .PP
3539     While libev is written to generate as few warnings as possible,
3540     \&\*(L"warn-free\*(R" code is not a goal, and it is recommended not to build libev
3541     with any compiler warnings enabled unless you are prepared to cope with
3542     them (e.g. by ignoring them). Remember that warnings are just that:
3543     warnings, not errors, or proof of bugs.
3544     .SH "VALGRIND"
3545     .IX Header "VALGRIND"
3546     Valgrind has a special section here because it is a popular tool that is
3547     highly useful, but valgrind reports are very hard to interpret.
3548     .PP
3549     If you think you found a bug (memory leak, uninitialised data access etc.)
3550     in libev, then check twice: If valgrind reports something like:
3551     .PP
3552     .Vb 3
3553     \& ==2274== definitely lost: 0 bytes in 0 blocks.
3554     \& ==2274== possibly lost: 0 bytes in 0 blocks.
3555     \& ==2274== still reachable: 256 bytes in 1 blocks.
3556     .Ve
3557     .PP
3558 root 1.68 Then there is no memory leak. Similarly, under some circumstances,
3559 root 1.67 valgrind might report kernel bugs as if it were a bug in libev, or it
3560     might be confused (it is a very good tool, but only a tool).
3561     .PP
3562     If you are unsure about something, feel free to contact the mailing list
3563     with the full valgrind report and an explanation on why you think this is
3564     a bug in libev. However, don't be annoyed when you get a brisk \*(L"this is
3565     no bug\*(R" answer and take the chance of learning how to interpret valgrind
3566     properly.
3567     .PP
3568     If you need, for some reason, empty reports from valgrind for your project
3569     I suggest using suppression lists.
3570 root 1.1 .SH "AUTHOR"
3571     .IX Header "AUTHOR"
3572     Marc Lehmann <libev@schmorp.de>.
3573 root 1.60 .SH "POD ERRORS"
3574     .IX Header "POD ERRORS"
3575     Hey! \fBThe above document had some coding errors, which are explained below:\fR
3576 root 1.69 .IP "Around line 3122:" 4
3577     .IX Item "Around line 3122:"
3578 root 1.60 You forgot a '=back' before '=head2'