ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/libev/ev.pod
Revision: 1.158
Committed: Wed May 21 12:51:38 2008 UTC (15 years, 11 months ago) by root
Branch: MAIN
Changes since 1.157: +5 -0 lines
Log Message:
*** empty log message ***

File Contents

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