ViewVC Help
View File | Revision Log | Show Annotations | Download File
Revision: 1.61
Committed: Thu Mar 13 13:06:15 2008 UTC (16 years, 4 months ago) by root
Branch: MAIN
CVS Tags: rel-3_1
Changes since 1.60: +275 -40 lines
Log Message:
*** empty log message ***

File Contents

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