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