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