ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/libev/ev.pod
Revision: 1.138
Committed: Mon Mar 31 01:14:12 2008 UTC (16 years, 1 month ago) by root
Branch: MAIN
Changes since 1.137: +12 -0 lines
Log Message:
*** empty log message ***

File Contents

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