5648 lines 259 KiB Groff Raw Blame History

 ```.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.29) ``` ```.\" ``` ```.\" Standard preamble: ``` ```.\" ======================================================================== ``` ```.de Sp \" Vertical space (when we can't use .PP) ``` ```.if t .sp .5v ``` ```.if n .sp ``` ```.. ``` ```.de Vb \" Begin verbatim text ``` ```.ft CW ``` ```.nf ``` ```.ne \\\$1 ``` ```.. ``` ```.de Ve \" End verbatim text ``` ```.ft R ``` ```.fi ``` ```.. ``` ```.\" Set up some character translations and predefined strings. \*(-- will ``` ```.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left ``` ```.\" double quote, and \*(R" will give a right double quote. \*(C+ will ``` ```.\" give a nicer C++. Capital omega is used to do unbreakable dashes and ``` ```.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, ``` ```.\" nothing in troff, for use with C<>. ``` ```.tr \(*W- ``` ```.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' ``` ```.ie n \{\ ``` ```. ds -- \(*W- ``` ```. ds PI pi ``` ```. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch ``` ```. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch ``` ```. ds L" "" ``` ```. ds R" "" ``` ```. ds C` "" ``` ```. ds C' "" ``` ```'br\} ``` ```.el\{\ ``` ```. ds -- \|\(em\| ``` ```. ds PI \(*p ``` ```. ds L" `` ``` ```. ds R" '' ``` ```. ds C` ``` ```. ds C' ``` ```'br\} ``` ```.\" ``` ```.\" Escape single quotes in literal strings from groff's Unicode transform. ``` ```.ie \n(.g .ds Aq \(aq ``` ```.el .ds Aq ' ``` ```.\" ``` ```.\" If the F register is turned on, we'll generate index entries on stderr for ``` ```.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index ``` ```.\" entries marked with X<> in POD. Of course, you'll have to process the ``` ```.\" output yourself in some meaningful fashion. ``` ```.\" ``` ```.\" Avoid warning from groff about undefined register 'F'. ``` ```.de IX ``` ```.. ``` ```.nr rF 0 ``` ```.if \n(.g .if rF .nr rF 1 ``` ```.if (\n(rF:(\n(.g==0)) \{ ``` ```. if \nF \{ ``` ```. de IX ``` ```. tm Index:\\\$1\t\\n%\t"\\\$2" ``` ```.. ``` ```. if !\nF==2 \{ ``` ```. nr % 0 ``` ```. nr F 2 ``` ```. \} ``` ```. \} ``` ```.\} ``` ```.rr rF ``` ```.\" ``` ```.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). ``` ```.\" Fear. Run. Save yourself. No user-serviceable parts. ``` ```. \" fudge factors for nroff and troff ``` ```.if n \{\ ``` ```. ds #H 0 ``` ```. ds #V .8m ``` ```. ds #F .3m ``` ```. ds #[ \f1 ``` ```. ds #] \fP ``` ```.\} ``` ```.if t \{\ ``` ```. ds #H ((1u-(\\\\n(.fu%2u))*.13m) ``` ```. ds #V .6m ``` ```. ds #F 0 ``` ```. ds #[ \& ``` ```. ds #] \& ``` ```.\} ``` ```. \" simple accents for nroff and troff ``` ```.if n \{\ ``` ```. ds ' \& ``` ```. ds ` \& ``` ```. ds ^ \& ``` ```. ds , \& ``` ```. ds ~ ~ ``` ```. ds / ``` ```.\} ``` ```.if t \{\ ``` ```. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" ``` ```. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' ``` ```. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' ``` ```. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' ``` ```. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' ``` ```. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' ``` ```.\} ``` ```. \" troff and (daisy-wheel) nroff accents ``` ```.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' ``` ```.ds 8 \h'\*(#H'\(*b\h'-\*(#H' ``` ```.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] ``` ```.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' ``` ```.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' ``` ```.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] ``` ```.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] ``` ```.ds ae a\h'-(\w'a'u*4/10)'e ``` ```.ds Ae A\h'-(\w'A'u*4/10)'E ``` ```. \" corrections for vroff ``` ```.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' ``` ```.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' ``` ```. \" for low resolution devices (crt and lpr) ``` ```.if \n(.H>23 .if \n(.V>19 \ ``` ```\{\ ``` ```. ds : e ``` ```. ds 8 ss ``` ```. ds o a ``` ```. ds d- d\h'-1'\(ga ``` ```. ds D- D\h'-1'\(hy ``` ```. ds th \o'bp' ``` ```. ds Th \o'LP' ``` ```. ds ae ae ``` ```. ds Ae AE ``` ```.\} ``` ```.rm #[ #] #H #V #F C ``` ```.\" ======================================================================== ``` ```.\" ``` ```.IX Title "LIBEV 3" ``` ```.TH LIBEV 3 "2017-06-21" "libev-4.24" "libev - high performance full featured event loop" ``` ```.\" For nroff, turn off justification. Always turn off hyphenation; it makes ``` ```.\" way too many mistakes in technical documents. ``` ```.if n .ad l ``` ```.nh ``` ```.SH "NAME" ``` ```libev \- a high performance full\-featured event loop written in C ``` ```.SH "SYNOPSIS" ``` ```.IX Header "SYNOPSIS" ``` ```.Vb 1 ``` ```\& #include ``` ```.Ve ``` ```.SS "\s-1EXAMPLE PROGRAM\s0" ``` ```.IX Subsection "EXAMPLE PROGRAM" ``` ```.Vb 2 ``` ```\& // a single header file is required ``` ```\& #include ``` ```\& ``` ```\& #include // for puts ``` ```\& ``` ```\& // every watcher type has its own typedef\*(Aqd struct ``` ```\& // with the name ev_TYPE ``` ```\& ev_io stdin_watcher; ``` ```\& ev_timer timeout_watcher; ``` ```\& ``` ```\& // all watcher callbacks have a similar signature ``` ```\& // this callback is called when data is readable on stdin ``` ```\& static void ``` ```\& stdin_cb (EV_P_ ev_io *w, int revents) ``` ```\& { ``` ```\& puts ("stdin ready"); ``` ```\& // for one\-shot events, one must manually stop the watcher ``` ```\& // with its corresponding stop function. ``` ```\& ev_io_stop (EV_A_ w); ``` ```\& ``` ```\& // this causes all nested ev_run\*(Aqs to stop iterating ``` ```\& ev_break (EV_A_ EVBREAK_ALL); ``` ```\& } ``` ```\& ``` ```\& // another callback, this time for a time\-out ``` ```\& static void ``` ```\& timeout_cb (EV_P_ ev_timer *w, int revents) ``` ```\& { ``` ```\& puts ("timeout"); ``` ```\& // this causes the innermost ev_run to stop iterating ``` ```\& ev_break (EV_A_ EVBREAK_ONE); ``` ```\& } ``` ```\& ``` ```\& int ``` ```\& main (void) ``` ```\& { ``` ```\& // use the default event loop unless you have special needs ``` ```\& struct ev_loop *loop = EV_DEFAULT; ``` ```\& ``` ```\& // initialise an io watcher, then start it ``` ```\& // this one will watch for stdin to become readable ``` ```\& ev_io_init (&stdin_watcher, stdin_cb, /*STDIN_FILENO*/ 0, EV_READ); ``` ```\& ev_io_start (loop, &stdin_watcher); ``` ```\& ``` ```\& // initialise a timer watcher, then start it ``` ```\& // simple non\-repeating 5.5 second timeout ``` ```\& ev_timer_init (&timeout_watcher, timeout_cb, 5.5, 0.); ``` ```\& ev_timer_start (loop, &timeout_watcher); ``` ```\& ``` ```\& // now wait for events to arrive ``` ```\& ev_run (loop, 0); ``` ```\& ``` ```\& // break was called, so exit ``` ```\& return 0; ``` ```\& } ``` ```.Ve ``` ```.SH "ABOUT THIS DOCUMENT" ``` ```.IX Header "ABOUT THIS DOCUMENT" ``` ```This document documents the libev software package. ``` ```.PP ``` ```The newest version of this document is also available as an html-formatted ``` ```web page you might find easier to navigate when reading it for the first ``` ```time: . ``` ```.PP ``` ```While this document tries to be as complete as possible in documenting ``` ```libev, its usage and the rationale behind its design, it is not a tutorial ``` ```on event-based programming, nor will it introduce event-based programming ``` ```with libev. ``` ```.PP ``` ```Familiarity with event based programming techniques in general is assumed ``` ```throughout this document. ``` ```.SH "WHAT TO READ WHEN IN A HURRY" ``` ```.IX Header "WHAT TO READ WHEN IN A HURRY" ``` ```This manual tries to be very detailed, but unfortunately, this also makes ``` ```it very long. If you just want to know the basics of libev, I suggest ``` ```reading \*(L"\s-1ANATOMY OF A WATCHER\*(R"\s0, then the \*(L"\s-1EXAMPLE PROGRAM\*(R"\s0 above and ``` ```look up the missing functions in \*(L"\s-1GLOBAL FUNCTIONS\*(R"\s0 and the \f(CW\*(C`ev_io\*(C'\fR and ``` ```\&\f(CW\*(C`ev_timer\*(C'\fR sections in \*(L"\s-1WATCHER TYPES\*(R"\s0. ``` ```.SH "ABOUT LIBEV" ``` ```.IX Header "ABOUT LIBEV" ``` ```Libev is an event loop: you register interest in certain events (such as a ``` ```file descriptor being readable or a timeout occurring), and it will manage ``` ```these event sources and provide your program with events. ``` ```.PP ``` ```To do this, it must take more or less complete control over your process ``` ```(or thread) by executing the \fIevent loop\fR handler, and will then ``` ```communicate events via a callback mechanism. ``` ```.PP ``` ```You register interest in certain events by registering so-called \fIevent ``` ```watchers\fR, which are relatively small C structures you initialise with the ``` ```details of the event, and then hand it over to libev by \fIstarting\fR the ``` ```watcher. ``` ```.SS "\s-1FEATURES\s0" ``` ```.IX Subsection "FEATURES" ``` ```Libev supports \f(CW\*(C`select\*(C'\fR, \f(CW\*(C`poll\*(C'\fR, the Linux-specific \f(CW\*(C`epoll\*(C'\fR, the ``` ```BSD-specific \f(CW\*(C`kqueue\*(C'\fR and the Solaris-specific event port mechanisms ``` ```for file descriptor events (\f(CW\*(C`ev_io\*(C'\fR), the Linux \f(CW\*(C`inotify\*(C'\fR interface ``` ```(for \f(CW\*(C`ev_stat\*(C'\fR), Linux eventfd/signalfd (for faster and cleaner ``` ```inter-thread wakeup (\f(CW\*(C`ev_async\*(C'\fR)/signal handling (\f(CW\*(C`ev_signal\*(C'\fR)) relative ``` ```timers (\f(CW\*(C`ev_timer\*(C'\fR), absolute timers with customised rescheduling ``` ```(\f(CW\*(C`ev_periodic\*(C'\fR), synchronous signals (\f(CW\*(C`ev_signal\*(C'\fR), process status ``` ```change events (\f(CW\*(C`ev_child\*(C'\fR), and event watchers dealing with the event ``` ```loop mechanism itself (\f(CW\*(C`ev_idle\*(C'\fR, \f(CW\*(C`ev_embed\*(C'\fR, \f(CW\*(C`ev_prepare\*(C'\fR and ``` ```\&\f(CW\*(C`ev_check\*(C'\fR watchers) as well as file watchers (\f(CW\*(C`ev_stat\*(C'\fR) and even ``` ```limited support for fork events (\f(CW\*(C`ev_fork\*(C'\fR). ``` ```.PP ``` ```It also is quite fast (see this ``` ```benchmark comparing it to libevent ``` ```for example). ``` ```.SS "\s-1CONVENTIONS\s0" ``` ```.IX Subsection "CONVENTIONS" ``` ```Libev is very configurable. In this manual the default (and most common) ``` ```configuration will be described, which supports multiple event loops. For ``` ```more info about various configuration options please have a look at ``` ```\&\fB\s-1EMBED\s0\fR section in this manual. If libev was configured without support ``` ```for multiple event loops, then all functions taking an initial argument of ``` ```name \f(CW\*(C`loop\*(C'\fR (which is always of type \f(CW\*(C`struct ev_loop *\*(C'\fR) will not have ``` ```this argument. ``` ```.SS "\s-1TIME REPRESENTATION\s0" ``` ```.IX Subsection "TIME REPRESENTATION" ``` ```Libev represents time as a single floating point number, representing ``` ```the (fractional) number of seconds since the (\s-1POSIX\s0) epoch (in practice ``` ```somewhere near the beginning of 1970, details are complicated, don't ``` ```ask). This type is called \f(CW\*(C`ev_tstamp\*(C'\fR, which is what you should use ``` ```too. It usually aliases to the \f(CW\*(C`double\*(C'\fR type in C. When you need to do ``` ```any calculations on it, you should treat it as some floating point value. ``` ```.PP ``` ```Unlike the name component \f(CW\*(C`stamp\*(C'\fR might indicate, it is also used for ``` ```time differences (e.g. delays) throughout libev. ``` ```.SH "ERROR HANDLING" ``` ```.IX Header "ERROR HANDLING" ``` ```Libev knows three classes of errors: operating system errors, usage errors ``` ```and internal errors (bugs). ``` ```.PP ``` ```When libev catches an operating system error it cannot handle (for example ``` ```a system call indicating a condition libev cannot fix), it calls the callback ``` ```set via \f(CW\*(C`ev_set_syserr_cb\*(C'\fR, which is supposed to fix the problem or ``` ```abort. The default is to print a diagnostic message and to call \f(CW\*(C`abort ``` ```()\*(C'\fR. ``` ```.PP ``` ```When libev detects a usage error such as a negative timer interval, then ``` ```it will print a diagnostic message and abort (via the \f(CW\*(C`assert\*(C'\fR mechanism, ``` ```so \f(CW\*(C`NDEBUG\*(C'\fR will disable this checking): these are programming errors in ``` ```the libev caller and need to be fixed there. ``` ```.PP ``` ```Libev also has a few internal error-checking \f(CW\*(C`assert\*(C'\fRions, and also has ``` ```extensive consistency checking code. These do not trigger under normal ``` ```circumstances, as they indicate either a bug in libev or worse. ``` ```.SH "GLOBAL FUNCTIONS" ``` ```.IX Header "GLOBAL FUNCTIONS" ``` ```These functions can be called anytime, even before initialising the ``` ```library in any way. ``` ```.IP "ev_tstamp ev_time ()" 4 ``` ```.IX Item "ev_tstamp ev_time ()" ``` ```Returns the current time as libev would use it. Please note that the ``` ```\&\f(CW\*(C`ev_now\*(C'\fR function is usually faster and also often returns the timestamp ``` ```you actually want to know. Also interesting is the combination of ``` ```\&\f(CW\*(C`ev_now_update\*(C'\fR and \f(CW\*(C`ev_now\*(C'\fR. ``` ```.IP "ev_sleep (ev_tstamp interval)" 4 ``` ```.IX Item "ev_sleep (ev_tstamp interval)" ``` ```Sleep for the given interval: The current thread will be blocked ``` ```until either it is interrupted or the given time interval has ``` ```passed (approximately \- it might return a bit earlier even if not ``` ```interrupted). Returns immediately if \f(CW\*(C`interval <= 0\*(C'\fR. ``` ```.Sp ``` ```Basically this is a sub-second-resolution \f(CW\*(C`sleep ()\*(C'\fR. ``` ```.Sp ``` ```The range of the \f(CW\*(C`interval\*(C'\fR is limited \- libev only guarantees to work ``` ```with sleep times of up to one day (\f(CW\*(C`interval <= 86400\*(C'\fR). ``` ```.IP "int ev_version_major ()" 4 ``` ```.IX Item "int ev_version_major ()" ``` ```.PD 0 ``` ```.IP "int ev_version_minor ()" 4 ``` ```.IX Item "int ev_version_minor ()" ``` ```.PD ``` ```You can find out the major and minor \s-1ABI\s0 version numbers of the library ``` ```you linked against by calling the functions \f(CW\*(C`ev_version_major\*(C'\fR and ``` ```\&\f(CW\*(C`ev_version_minor\*(C'\fR. If you want, you can compare against the global ``` ```symbols \f(CW\*(C`EV_VERSION_MAJOR\*(C'\fR and \f(CW\*(C`EV_VERSION_MINOR\*(C'\fR, which specify the ``` ```version of the library your program was compiled against. ``` ```.Sp ``` ```These version numbers refer to the \s-1ABI\s0 version of the library, not the ``` ```release version. ``` ```.Sp ``` ```Usually, it's a good idea to terminate if the major versions mismatch, ``` ```as this indicates an incompatible change. Minor versions are usually ``` ```compatible to older versions, so a larger minor version alone is usually ``` ```not a problem. ``` ```.Sp ``` ```Example: Make sure we haven't accidentally been linked against the wrong ``` ```version (note, however, that this will not detect other \s-1ABI\s0 mismatches, ``` ```such as \s-1LFS\s0 or reentrancy). ``` ```.Sp ``` ```.Vb 3 ``` ```\& assert (("libev version mismatch", ``` ```\& ev_version_major () == EV_VERSION_MAJOR ``` ```\& && ev_version_minor () >= EV_VERSION_MINOR)); ``` ```.Ve ``` ```.IP "unsigned int ev_supported_backends ()" 4 ``` ```.IX Item "unsigned int ev_supported_backends ()" ``` ```Return the set of all backends (i.e. their corresponding \f(CW\*(C`EV_BACKEND_*\*(C'\fR ``` ```value) compiled into this binary of libev (independent of their ``` ```availability on the system you are running on). See \f(CW\*(C`ev_default_loop\*(C'\fR for ``` ```a description of the set values. ``` ```.Sp ``` ```Example: make sure we have the epoll method, because yeah this is cool and ``` ```a must have and can we have a torrent of it please!!!11 ``` ```.Sp ``` ```.Vb 2 ``` ```\& assert (("sorry, no epoll, no sex", ``` ```\& ev_supported_backends () & EVBACKEND_EPOLL)); ``` ```.Ve ``` ```.IP "unsigned int ev_recommended_backends ()" 4 ``` ```.IX Item "unsigned int ev_recommended_backends ()" ``` ```Return the set of all backends compiled into this binary of libev and ``` ```also recommended for this platform, meaning it will work for most file ``` ```descriptor types. This set is often smaller than the one returned by ``` ```\&\f(CW\*(C`ev_supported_backends\*(C'\fR, as for example kqueue is broken on most BSDs ``` ```and will not be auto-detected unless you explicitly request it (assuming ``` ```you know what you are doing). This is the set of backends that libev will ``` ```probe for if you specify no backends explicitly. ``` ```.IP "unsigned int ev_embeddable_backends ()" 4 ``` ```.IX Item "unsigned int ev_embeddable_backends ()" ``` ```Returns the set of backends that are embeddable in other event loops. This ``` ```value is platform-specific but can include backends not available on the ``` ```current system. To find which embeddable backends might be supported on ``` ```the current system, you would need to look at \f(CW\*(C`ev_embeddable_backends () ``` ```& ev_supported_backends ()\*(C'\fR, likewise for recommended ones. ``` ```.Sp ``` ```See the description of \f(CW\*(C`ev_embed\*(C'\fR watchers for more info. ``` ```.IP "ev_set_allocator (void *(*cb)(void *ptr, long size) throw ())" 4 ``` ```.IX Item "ev_set_allocator (void *(*cb)(void *ptr, long size) throw ())" ``` ```Sets the allocation function to use (the prototype is similar \- the ``` ```semantics are identical to the \f(CW\*(C`realloc\*(C'\fR C89/SuS/POSIX function). It is ``` ```used to allocate and free memory (no surprises here). If it returns zero ``` ```when memory needs to be allocated (\f(CW\*(C`size != 0\*(C'\fR), the library might abort ``` ```or take some potentially destructive action. ``` ```.Sp ``` ```Since some systems (at least OpenBSD and Darwin) fail to implement ``` ```correct \f(CW\*(C`realloc\*(C'\fR semantics, libev will use a wrapper around the system ``` ```\&\f(CW\*(C`realloc\*(C'\fR and \f(CW\*(C`free\*(C'\fR functions by default. ``` ```.Sp ``` ```You could override this function in high-availability programs to, say, ``` ```free some memory if it cannot allocate memory, to use a special allocator, ``` ```or even to sleep a while and retry until some memory is available. ``` ```.Sp ``` ```Example: Replace the libev allocator with one that waits a bit and then ``` ```retries (example requires a standards-compliant \f(CW\*(C`realloc\*(C'\fR). ``` ```.Sp ``` ```.Vb 6 ``` ```\& static void * ``` ```\& persistent_realloc (void *ptr, size_t size) ``` ```\& { ``` ```\& for (;;) ``` ```\& { ``` ```\& void *newptr = realloc (ptr, size); ``` ```\& ``` ```\& if (newptr) ``` ```\& return newptr; ``` ```\& ``` ```\& sleep (60); ``` ```\& } ``` ```\& } ``` ```\& ``` ```\& ... ``` ```\& ev_set_allocator (persistent_realloc); ``` ```.Ve ``` ```.IP "ev_set_syserr_cb (void (*cb)(const char *msg) throw ())" 4 ``` ```.IX Item "ev_set_syserr_cb (void (*cb)(const char *msg) throw ())" ``` ```Set the callback function to call on a retryable system call error (such ``` ```as failed select, poll, epoll_wait). The message is a printable string ``` ```indicating the system call or subsystem causing the problem. If this ``` ```callback is set, then libev will expect it to remedy the situation, no ``` ```matter what, when it returns. That is, libev will generally retry the ``` ```requested operation, or, if the condition doesn't go away, do bad stuff ``` ```(such as abort). ``` ```.Sp ``` ```Example: This is basically the same thing that libev does internally, too. ``` ```.Sp ``` ```.Vb 6 ``` ```\& static void ``` ```\& fatal_error (const char *msg) ``` ```\& { ``` ```\& perror (msg); ``` ```\& abort (); ``` ```\& } ``` ```\& ``` ```\& ... ``` ```\& ev_set_syserr_cb (fatal_error); ``` ```.Ve ``` ```.IP "ev_feed_signal (int signum)" 4 ``` ```.IX Item "ev_feed_signal (int signum)" ``` ```This function can be used to \*(L"simulate\*(R" a signal receive. It is completely ``` ```safe to call this function at any time, from any context, including signal ``` ```handlers or random threads. ``` ```.Sp ``` ```Its main use is to customise signal handling in your process, especially ``` ```in the presence of threads. For example, you could block signals ``` ```by default in all threads (and specifying \f(CW\*(C`EVFLAG_NOSIGMASK\*(C'\fR when ``` ```creating any loops), and in one thread, use \f(CW\*(C`sigwait\*(C'\fR or any other ``` ```mechanism to wait for signals, then \*(L"deliver\*(R" them to libev by calling ``` ```\&\f(CW\*(C`ev_feed_signal\*(C'\fR. ``` ```.SH "FUNCTIONS CONTROLLING EVENT LOOPS" ``` ```.IX Header "FUNCTIONS CONTROLLING EVENT LOOPS" ``` ```An event loop is described by a \f(CW\*(C`struct ev_loop *\*(C'\fR (the \f(CW\*(C`struct\*(C'\fR is ``` ```\&\fInot\fR optional in this case unless libev 3 compatibility is disabled, as ``` ```libev 3 had an \f(CW\*(C`ev_loop\*(C'\fR function colliding with the struct name). ``` ```.PP ``` ```The library knows two types of such loops, the \fIdefault\fR loop, which ``` ```supports child process events, and dynamically created event loops which ``` ```do not. ``` ```.IP "struct ev_loop *ev_default_loop (unsigned int flags)" 4 ``` ```.IX Item "struct ev_loop *ev_default_loop (unsigned int flags)" ``` ```This returns the \*(L"default\*(R" event loop object, which is what you should ``` ```normally use when you just need \*(L"the event loop\*(R". Event loop objects and ``` ```the \f(CW\*(C`flags\*(C'\fR parameter are described in more detail in the entry for ``` ```\&\f(CW\*(C`ev_loop_new\*(C'\fR. ``` ```.Sp ``` ```If the default loop is already initialised then this function simply ``` ```returns it (and ignores the flags. If that is troubling you, check ``` ```\&\f(CW\*(C`ev_backend ()\*(C'\fR afterwards). Otherwise it will create it with the given ``` ```flags, which should almost always be \f(CW0\fR, unless the caller is also the ``` ```one calling \f(CW\*(C`ev_run\*(C'\fR or otherwise qualifies as \*(L"the main program\*(R". ``` ```.Sp ``` ```If you don't know what event loop to use, use the one returned from this ``` ```function (or via the \f(CW\*(C`EV_DEFAULT\*(C'\fR macro). ``` ```.Sp ``` ```Note that this function is \fInot\fR thread-safe, so if you want to use it ``` ```from multiple threads, you have to employ some kind of mutex (note also ``` ```that this case is unlikely, as loops cannot be shared easily between ``` ```threads anyway). ``` ```.Sp ``` ```The default loop is the only loop that can handle \f(CW\*(C`ev_child\*(C'\fR watchers, ``` ```and to do this, it always registers a handler for \f(CW\*(C`SIGCHLD\*(C'\fR. If this is ``` ```a problem for your application you can either create a dynamic loop with ``` ```\&\f(CW\*(C`ev_loop_new\*(C'\fR which doesn't do that, or you can simply overwrite the ``` ```\&\f(CW\*(C`SIGCHLD\*(C'\fR signal handler \fIafter\fR calling \f(CW\*(C`ev_default_init\*(C'\fR. ``` ```.Sp ``` ```Example: This is the most typical usage. ``` ```.Sp ``` ```.Vb 2 ``` ```\& if (!ev_default_loop (0)) ``` ```\& fatal ("could not initialise libev, bad \$LIBEV_FLAGS in environment?"); ``` ```.Ve ``` ```.Sp ``` ```Example: Restrict libev to the select and poll backends, and do not allow ``` ```environment settings to be taken into account: ``` ```.Sp ``` ```.Vb 1 ``` ```\& ev_default_loop (EVBACKEND_POLL | EVBACKEND_SELECT | EVFLAG_NOENV); ``` ```.Ve ``` ```.IP "struct ev_loop *ev_loop_new (unsigned int flags)" 4 ``` ```.IX Item "struct ev_loop *ev_loop_new (unsigned int flags)" ``` ```This will create and initialise a new event loop object. If the loop ``` ```could not be initialised, returns false. ``` ```.Sp ``` ```This function is thread-safe, and one common way to use libev with ``` ```threads is indeed to create one loop per thread, and using the default ``` ```loop in the \*(L"main\*(R" or \*(L"initial\*(R" thread. ``` ```.Sp ``` ```The flags argument can be used to specify special behaviour or specific ``` ```backends to use, and is usually specified as \f(CW0\fR (or \f(CW\*(C`EVFLAG_AUTO\*(C'\fR). ``` ```.Sp ``` ```The following flags are supported: ``` ```.RS 4 ``` ```.ie n .IP """EVFLAG_AUTO""" 4 ``` ```.el .IP "\f(CWEVFLAG_AUTO\fR" 4 ``` ```.IX Item "EVFLAG_AUTO" ``` ```The default flags value. Use this if you have no clue (it's the right ``` ```thing, believe me). ``` ```.ie n .IP """EVFLAG_NOENV""" 4 ``` ```.el .IP "\f(CWEVFLAG_NOENV\fR" 4 ``` ```.IX Item "EVFLAG_NOENV" ``` ```If this flag bit is or'ed into the flag value (or the program runs setuid ``` ```or setgid) then libev will \fInot\fR look at the environment variable ``` ```\&\f(CW\*(C`LIBEV_FLAGS\*(C'\fR. Otherwise (the default), this environment variable will ``` ```override the flags completely if it is found in the environment. This is ``` ```useful to try out specific backends to test their performance, to work ``` ```around bugs, or to make libev threadsafe (accessing environment variables ``` ```cannot be done in a threadsafe way, but usually it works if no other ``` ```thread modifies them). ``` ```.ie n .IP """EVFLAG_FORKCHECK""" 4 ``` ```.el .IP "\f(CWEVFLAG_FORKCHECK\fR" 4 ``` ```.IX Item "EVFLAG_FORKCHECK" ``` ```Instead of calling \f(CW\*(C`ev_loop_fork\*(C'\fR manually after a fork, you can also ``` ```make libev check for a fork in each iteration by enabling this flag. ``` ```.Sp ``` ```This works by calling \f(CW\*(C`getpid ()\*(C'\fR on every iteration of the loop, ``` ```and thus this might slow down your event loop if you do a lot of loop ``` ```iterations and little real work, but is usually not noticeable (on my ``` ```GNU/Linux system for example, \f(CW\*(C`getpid\*(C'\fR is actually a simple 5\-insn sequence ``` ```without a system call and thus \fIvery\fR fast, but my GNU/Linux system also has ``` ```\&\f(CW\*(C`pthread_atfork\*(C'\fR which is even faster). ``` ```.Sp ``` ```The big advantage of this flag is that you can forget about fork (and ``` ```forget about forgetting to tell libev about forking, although you still ``` ```have to ignore \f(CW\*(C`SIGPIPE\*(C'\fR) when you use this flag. ``` ```.Sp ``` ```This flag setting cannot be overridden or specified in the \f(CW\*(C`LIBEV_FLAGS\*(C'\fR ``` ```environment variable. ``` ```.ie n .IP """EVFLAG_NOINOTIFY""" 4 ``` ```.el .IP "\f(CWEVFLAG_NOINOTIFY\fR" 4 ``` ```.IX Item "EVFLAG_NOINOTIFY" ``` ```When this flag is specified, then libev will not attempt to use the ``` ```\&\fIinotify\fR \s-1API\s0 for its \f(CW\*(C`ev_stat\*(C'\fR watchers. Apart from debugging and ``` ```testing, this flag can be useful to conserve inotify file descriptors, as ``` ```otherwise each loop using \f(CW\*(C`ev_stat\*(C'\fR watchers consumes one inotify handle. ``` ```.ie n .IP """EVFLAG_SIGNALFD""" 4 ``` ```.el .IP "\f(CWEVFLAG_SIGNALFD\fR" 4 ``` ```.IX Item "EVFLAG_SIGNALFD" ``` ```When this flag is specified, then libev will attempt to use the ``` ```\&\fIsignalfd\fR \s-1API\s0 for its \f(CW\*(C`ev_signal\*(C'\fR (and \f(CW\*(C`ev_child\*(C'\fR) watchers. This \s-1API\s0 ``` ```delivers signals synchronously, which makes it both faster and might make ``` ```it possible to get the queued signal data. It can also simplify signal ``` ```handling with threads, as long as you properly block signals in your ``` ```threads that are not interested in handling them. ``` ```.Sp ``` ```Signalfd will not be used by default as this changes your signal mask, and ``` ```there are a lot of shoddy libraries and programs (glib's threadpool for ``` ```example) that can't properly initialise their signal masks. ``` ```.ie n .IP """EVFLAG_NOSIGMASK""" 4 ``` ```.el .IP "\f(CWEVFLAG_NOSIGMASK\fR" 4 ``` ```.IX Item "EVFLAG_NOSIGMASK" ``` ```When this flag is specified, then libev will avoid to modify the signal ``` ```mask. Specifically, this means you have to make sure signals are unblocked ``` ```when you want to receive them. ``` ```.Sp ``` ```This behaviour is useful when you want to do your own signal handling, or ``` ```want to handle signals only in specific threads and want to avoid libev ``` ```unblocking the signals. ``` ```.Sp ``` ```It's also required by \s-1POSIX\s0 in a threaded program, as libev calls ``` ```\&\f(CW\*(C`sigprocmask\*(C'\fR, whose behaviour is officially unspecified. ``` ```.Sp ``` ```This flag's behaviour will become the default in future versions of libev. ``` ```.ie n .IP """EVBACKEND_SELECT"" (value 1, portable select backend)" 4 ``` ```.el .IP "\f(CWEVBACKEND_SELECT\fR (value 1, portable select backend)" 4 ``` ```.IX Item "EVBACKEND_SELECT (value 1, portable select backend)" ``` ```This is your standard \fIselect\fR\|(2) backend. Not \fIcompletely\fR standard, as ``` ```libev tries to roll its own fd_set with no limits on the number of fds, ``` ```but if that fails, expect a fairly low limit on the number of fds when ``` ```using this backend. It doesn't scale too well (O(highest_fd)), but its ``` ```usually the fastest backend for a low number of (low-numbered :) fds. ``` ```.Sp ``` ```To get good performance out of this backend you need a high amount of ``` ```parallelism (most of the file descriptors should be busy). If you are ``` ```writing a server, you should \f(CW\*(C`accept ()\*(C'\fR in a loop to accept as many ``` ```connections as possible during one iteration. You might also want to have ``` ```a look at \f(CW\*(C`ev_set_io_collect_interval ()\*(C'\fR to increase the amount of ``` ```readiness notifications you get per iteration. ``` ```.Sp ``` ```This backend maps \f(CW\*(C`EV_READ\*(C'\fR to the \f(CW\*(C`readfds\*(C'\fR set and \f(CW\*(C`EV_WRITE\*(C'\fR to the ``` ```\&\f(CW\*(C`writefds\*(C'\fR set (and to work around Microsoft Windows bugs, also onto the ``` ```\&\f(CW\*(C`exceptfds\*(C'\fR set on that platform). ``` ```.ie n .IP """EVBACKEND_POLL"" (value 2, poll backend, available everywhere except on windows)" 4 ``` ```.el .IP "\f(CWEVBACKEND_POLL\fR (value 2, poll backend, available everywhere except on windows)" 4 ``` ```.IX Item "EVBACKEND_POLL (value 2, poll backend, available everywhere except on windows)" ``` ```And this is your standard \fIpoll\fR\|(2) backend. It's more complicated ``` ```than select, but handles sparse fds better and has no artificial ``` ```limit on the number of fds you can use (except it will slow down ``` ```considerably with a lot of inactive fds). It scales similarly to select, ``` ```i.e. O(total_fds). See the entry for \f(CW\*(C`EVBACKEND_SELECT\*(C'\fR, above, for ``` ```performance tips. ``` ```.Sp ``` ```This backend maps \f(CW\*(C`EV_READ\*(C'\fR to \f(CW\*(C`POLLIN | POLLERR | POLLHUP\*(C'\fR, and ``` ```\&\f(CW\*(C`EV_WRITE\*(C'\fR to \f(CW\*(C`POLLOUT | POLLERR | POLLHUP\*(C'\fR. ``` ```.ie n .IP """EVBACKEND_EPOLL"" (value 4, Linux)" 4 ``` ```.el .IP "\f(CWEVBACKEND_EPOLL\fR (value 4, Linux)" 4 ``` ```.IX Item "EVBACKEND_EPOLL (value 4, Linux)" ``` ```Use the linux-specific \fIepoll\fR\|(7) interface (for both pre\- and post\-2.6.9 ``` ```kernels). ``` ```.Sp ``` ```For few fds, this backend is a bit little slower than poll and select, but ``` ```it scales phenomenally better. While poll and select usually scale like ``` ```O(total_fds) where total_fds is the total number of fds (or the highest ``` ```fd), epoll scales either O(1) or O(active_fds). ``` ```.Sp ``` ```The epoll mechanism deserves honorable mention as the most misdesigned ``` ```of the more advanced event mechanisms: mere annoyances include silently ``` ```dropping file descriptors, requiring a system call per change per file ``` ```descriptor (and unnecessary guessing of parameters), problems with dup, ``` ```returning before the timeout value, resulting in additional iterations ``` ```(and only giving 5ms accuracy while select on the same platform gives ``` ```0.1ms) and so on. The biggest issue is fork races, however \- if a program ``` ```forks then \fIboth\fR parent and child process have to recreate the epoll ``` ```set, which can take considerable time (one syscall per file descriptor) ``` ```and is of course hard to detect. ``` ```.Sp ``` ```Epoll is also notoriously buggy \- embedding epoll fds \fIshould\fR work, ``` ```but of course \fIdoesn't\fR, and epoll just loves to report events for ``` ```totally \fIdifferent\fR file descriptors (even already closed ones, so ``` ```one cannot even remove them from the set) than registered in the set ``` ```(especially on \s-1SMP\s0 systems). Libev tries to counter these spurious ``` ```notifications by employing an additional generation counter and comparing ``` ```that against the events to filter out spurious ones, recreating the set ``` ```when required. Epoll also erroneously rounds down timeouts, but gives you ``` ```no way to know when and by how much, so sometimes you have to busy-wait ``` ```because epoll returns immediately despite a nonzero timeout. And last ``` ```not least, it also refuses to work with some file descriptors which work ``` ```perfectly fine with \f(CW\*(C`select\*(C'\fR (files, many character devices...). ``` ```.Sp ``` ```Epoll is truly the train wreck among event poll mechanisms, a frankenpoll, ``` ```cobbled together in a hurry, no thought to design or interaction with ``` ```others. Oh, the pain, will it ever stop... ``` ```.Sp ``` ```While stopping, setting and starting an I/O watcher in the same iteration ``` ```will result in some caching, there is still a system call per such ``` ```incident (because the same \fIfile descriptor\fR could point to a different ``` ```\&\fIfile description\fR now), so its best to avoid that. Also, \f(CW\*(C`dup ()\*(C'\fR'ed ``` ```file descriptors might not work very well if you register events for both ``` ```file descriptors. ``` ```.Sp ``` ```Best performance from this backend is achieved by not unregistering all ``` ```watchers for a file descriptor until it has been closed, if possible, ``` ```i.e. keep at least one watcher active per fd at all times. Stopping and ``` ```starting a watcher (without re-setting it) also usually doesn't cause ``` ```extra overhead. A fork can both result in spurious notifications as well ``` ```as in libev having to destroy and recreate the epoll object, which can ``` ```take considerable time and thus should be avoided. ``` ```.Sp ``` ```All this means that, in practice, \f(CW\*(C`EVBACKEND_SELECT\*(C'\fR can be as fast or ``` ```faster than epoll for maybe up to a hundred file descriptors, depending on ``` ```the usage. So sad. ``` ```.Sp ``` ```While nominally embeddable in other event loops, this feature is broken in ``` ```all kernel versions tested so far. ``` ```.Sp ``` ```This backend maps \f(CW\*(C`EV_READ\*(C'\fR and \f(CW\*(C`EV_WRITE\*(C'\fR in the same way as ``` ```\&\f(CW\*(C`EVBACKEND_POLL\*(C'\fR. ``` ```.ie n .IP """EVBACKEND_KQUEUE"" (value 8, most \s-1BSD\s0 clones)" 4 ``` ```.el .IP "\f(CWEVBACKEND_KQUEUE\fR (value 8, most \s-1BSD\s0 clones)" 4 ``` ```.IX Item "EVBACKEND_KQUEUE (value 8, most BSD clones)" ``` ```Kqueue deserves special mention, as at the time of this writing, it ``` ```was broken on all BSDs except NetBSD (usually it doesn't work reliably ``` ```with anything but sockets and pipes, except on Darwin, where of course ``` ```it's completely useless). Unlike epoll, however, whose brokenness ``` ```is by design, these kqueue bugs can (and eventually will) be fixed ``` ```without \s-1API\s0 changes to existing programs. For this reason it's not being ``` ```\&\*(L"auto-detected\*(R" unless you explicitly specify it in the flags (i.e. using ``` ```\&\f(CW\*(C`EVBACKEND_KQUEUE\*(C'\fR) or libev was compiled on a known-to-be-good (\-enough) ``` ```system like NetBSD. ``` ```.Sp ``` ```You still can embed kqueue into a normal poll or select backend and use it ``` ```only for sockets (after having made sure that sockets work with kqueue on ``` ```the target platform). See \f(CW\*(C`ev_embed\*(C'\fR watchers for more info. ``` ```.Sp ``` ```It scales in the same way as the epoll backend, but the interface to the ``` ```kernel is more efficient (which says nothing about its actual speed, of ``` ```course). While stopping, setting and starting an I/O watcher does never ``` ```cause an extra system call as with \f(CW\*(C`EVBACKEND_EPOLL\*(C'\fR, it still adds up to ``` ```two event changes per incident. Support for \f(CW\*(C`fork ()\*(C'\fR is very bad (you ``` ```might have to leak fd's on fork, but it's more sane than epoll) and it ``` ```drops fds silently in similarly hard-to-detect cases. ``` ```.Sp ``` ```This backend usually performs well under most conditions. ``` ```.Sp ``` ```While nominally embeddable in other event loops, this doesn't work ``` ```everywhere, so you might need to test for this. And since it is broken ``` ```almost everywhere, you should only use it when you have a lot of sockets ``` ```(for which it usually works), by embedding it into another event loop ``` ```(e.g. \f(CW\*(C`EVBACKEND_SELECT\*(C'\fR or \f(CW\*(C`EVBACKEND_POLL\*(C'\fR (but \f(CW\*(C`poll\*(C'\fR is of course ``` ```also broken on \s-1OS X\s0)) and, did I mention it, using it only for sockets. ``` ```.Sp ``` ```This backend maps \f(CW\*(C`EV_READ\*(C'\fR into an \f(CW\*(C`EVFILT_READ\*(C'\fR kevent with ``` ```\&\f(CW\*(C`NOTE_EOF\*(C'\fR, and \f(CW\*(C`EV_WRITE\*(C'\fR into an \f(CW\*(C`EVFILT_WRITE\*(C'\fR kevent with ``` ```\&\f(CW\*(C`NOTE_EOF\*(C'\fR. ``` ```.ie n .IP """EVBACKEND_DEVPOLL"" (value 16, Solaris 8)" 4 ``` ```.el .IP "\f(CWEVBACKEND_DEVPOLL\fR (value 16, Solaris 8)" 4 ``` ```.IX Item "EVBACKEND_DEVPOLL (value 16, Solaris 8)" ``` ```This is not implemented yet (and might never be, unless you send me an ``` ```implementation). According to reports, \f(CW\*(C`/dev/poll\*(C'\fR only supports sockets ``` ```and is not embeddable, which would limit the usefulness of this backend ``` ```immensely. ``` ```.ie n .IP """EVBACKEND_PORT"" (value 32, Solaris 10)" 4 ``` ```.el .IP "\f(CWEVBACKEND_PORT\fR (value 32, Solaris 10)" 4 ``` ```.IX Item "EVBACKEND_PORT (value 32, Solaris 10)" ``` ```This uses the Solaris 10 event port mechanism. As with everything on Solaris, ``` ```it's really slow, but it still scales very well (O(active_fds)). ``` ```.Sp ``` ```While this backend scales well, it requires one system call per active ``` ```file descriptor per loop iteration. For small and medium numbers of file ``` ```descriptors a \*(L"slow\*(R" \f(CW\*(C`EVBACKEND_SELECT\*(C'\fR or \f(CW\*(C`EVBACKEND_POLL\*(C'\fR backend ``` ```might perform better. ``` ```.Sp ``` ```On the positive side, this backend actually performed fully to ``` ```specification in all tests and is fully embeddable, which is a rare feat ``` ```among the OS-specific backends (I vastly prefer correctness over speed ``` ```hacks). ``` ```.Sp ``` ```On the negative side, the interface is \fIbizarre\fR \- so bizarre that ``` ```even sun itself gets it wrong in their code examples: The event polling ``` ```function sometimes returns events to the caller even though an error ``` ```occurred, but with no indication whether it has done so or not (yes, it's ``` ```even documented that way) \- deadly for edge-triggered interfaces where you ``` ```absolutely have to know whether an event occurred or not because you have ``` ```to re-arm the watcher. ``` ```.Sp ``` ```Fortunately libev seems to be able to work around these idiocies. ``` ```.Sp ``` ```This backend maps \f(CW\*(C`EV_READ\*(C'\fR and \f(CW\*(C`EV_WRITE\*(C'\fR in the same way as ``` ```\&\f(CW\*(C`EVBACKEND_POLL\*(C'\fR. ``` ```.ie n .IP """EVBACKEND_ALL""" 4 ``` ```.el .IP "\f(CWEVBACKEND_ALL\fR" 4 ``` ```.IX Item "EVBACKEND_ALL" ``` ```Try all backends (even potentially broken ones that wouldn't be tried ``` ```with \f(CW\*(C`EVFLAG_AUTO\*(C'\fR). Since this is a mask, you can do stuff such as ``` ```\&\f(CW\*(C`EVBACKEND_ALL & ~EVBACKEND_KQUEUE\*(C'\fR. ``` ```.Sp ``` ```It is definitely not recommended to use this flag, use whatever ``` ```\&\f(CW\*(C`ev_recommended_backends ()\*(C'\fR returns, or simply do not specify a backend ``` ```at all. ``` ```.ie n .IP """EVBACKEND_MASK""" 4 ``` ```.el .IP "\f(CWEVBACKEND_MASK\fR" 4 ``` ```.IX Item "EVBACKEND_MASK" ``` ```Not a backend at all, but a mask to select all backend bits from a ``` ```\&\f(CW\*(C`flags\*(C'\fR value, in case you want to mask out any backends from a flags ``` ```value (e.g. when modifying the \f(CW\*(C`LIBEV_FLAGS\*(C'\fR environment variable). ``` ```.RE ``` ```.RS 4 ``` ```.Sp ``` ```If one or more of the backend flags are or'ed into the flags value, ``` ```then only these backends will be tried (in the reverse order as listed ``` ```here). If none are specified, all backends in \f(CW\*(C`ev_recommended_backends ``` ```()\*(C'\fR will be tried. ``` ```.Sp ``` ```Example: Try to create a event loop that uses epoll and nothing else. ``` ```.Sp ``` ```.Vb 3 ``` ```\& struct ev_loop *epoller = ev_loop_new (EVBACKEND_EPOLL | EVFLAG_NOENV); ``` ```\& if (!epoller) ``` ```\& fatal ("no epoll found here, maybe it hides under your chair"); ``` ```.Ve ``` ```.Sp ``` ```Example: Use whatever libev has to offer, but make sure that kqueue is ``` ```used if available. ``` ```.Sp ``` ```.Vb 1 ``` ```\& struct ev_loop *loop = ev_loop_new (ev_recommended_backends () | EVBACKEND_KQUEUE); ``` ```.Ve ``` ```.RE ``` ```.IP "ev_loop_destroy (loop)" 4 ``` ```.IX Item "ev_loop_destroy (loop)" ``` ```Destroys an event loop object (frees all memory and kernel state ``` ```etc.). None of the active event watchers will be stopped in the normal ``` ```sense, so e.g. \f(CW\*(C`ev_is_active\*(C'\fR might still return true. It is your ``` ```responsibility to either stop all watchers cleanly yourself \fIbefore\fR ``` ```calling this function, or cope with the fact afterwards (which is usually ``` ```the easiest thing, you can just ignore the watchers and/or \f(CW\*(C`free ()\*(C'\fR them ``` ```for example). ``` ```.Sp ``` ```Note that certain global state, such as signal state (and installed signal ``` ```handlers), will not be freed by this function, and related watchers (such ``` ```as signal and child watchers) would need to be stopped manually. ``` ```.Sp ``` ```This function is normally used on loop objects allocated by ``` ```\&\f(CW\*(C`ev_loop_new\*(C'\fR, but it can also be used on the default loop returned by ``` ```\&\f(CW\*(C`ev_default_loop\*(C'\fR, in which case it is not thread-safe. ``` ```.Sp ``` ```Note that it is not advisable to call this function on the default loop ``` ```except in the rare occasion where you really need to free its resources. ``` ```If you need dynamically allocated loops it is better to use \f(CW\*(C`ev_loop_new\*(C'\fR ``` ```and \f(CW\*(C`ev_loop_destroy\*(C'\fR. ``` ```.IP "ev_loop_fork (loop)" 4 ``` ```.IX Item "ev_loop_fork (loop)" ``` ```This function sets a flag that causes subsequent \f(CW\*(C`ev_run\*(C'\fR iterations ``` ```to reinitialise the kernel state for backends that have one. Despite ``` ```the name, you can call it anytime you are allowed to start or stop ``` ```watchers (except inside an \f(CW\*(C`ev_prepare\*(C'\fR callback), but it makes most ``` ```sense after forking, in the child process. You \fImust\fR call it (or use ``` ```\&\f(CW\*(C`EVFLAG_FORKCHECK\*(C'\fR) in the child before resuming or calling \f(CW\*(C`ev_run\*(C'\fR. ``` ```.Sp ``` ```In addition, if you want to reuse a loop (via this function or ``` ```\&\f(CW\*(C`EVFLAG_FORKCHECK\*(C'\fR), you \fIalso\fR have to ignore \f(CW\*(C`SIGPIPE\*(C'\fR. ``` ```.Sp ``` ```Again, you \fIhave\fR to call it on \fIany\fR loop that you want to re-use after ``` ```a fork, \fIeven if you do not plan to use the loop in the parent\fR. This is ``` ```because some kernel interfaces *cough* \fIkqueue\fR *cough* do funny things ``` ```during fork. ``` ```.Sp ``` ```On the other hand, you only need to call this function in the child ``` ```process if and only if you want to use the event loop in the child. If ``` ```you just fork+exec or create a new loop in the child, you don't have to ``` ```call it at all (in fact, \f(CW\*(C`epoll\*(C'\fR is so badly broken that it makes a ``` ```difference, but libev will usually detect this case on its own and do a ``` ```costly reset of the backend). ``` ```.Sp ``` ```The function itself is quite fast and it's usually not a problem to call ``` ```it just in case after a fork. ``` ```.Sp ``` ```Example: Automate calling \f(CW\*(C`ev_loop_fork\*(C'\fR on the default loop when ``` ```using pthreads. ``` ```.Sp ``` ```.Vb 5 ``` ```\& static void ``` ```\& post_fork_child (void) ``` ```\& { ``` ```\& ev_loop_fork (EV_DEFAULT); ``` ```\& } ``` ```\& ``` ```\& ... ``` ```\& pthread_atfork (0, 0, post_fork_child); ``` ```.Ve ``` ```.IP "int ev_is_default_loop (loop)" 4 ``` ```.IX Item "int ev_is_default_loop (loop)" ``` ```Returns true when the given loop is, in fact, the default loop, and false ``` ```otherwise. ``` ```.IP "unsigned int ev_iteration (loop)" 4 ``` ```.IX Item "unsigned int ev_iteration (loop)" ``` ```Returns the current iteration count for the event loop, which is identical ``` ```to the number of times libev did poll for new events. It starts at \f(CW0\fR ``` ```and happily wraps around with enough iterations. ``` ```.Sp ``` ```This value can sometimes be useful as a generation counter of sorts (it ``` ```\&\*(L"ticks\*(R" the number of loop iterations), as it roughly corresponds with ``` ```\&\f(CW\*(C`ev_prepare\*(C'\fR and \f(CW\*(C`ev_check\*(C'\fR calls \- and is incremented between the ``` ```prepare and check phases. ``` ```.IP "unsigned int ev_depth (loop)" 4 ``` ```.IX Item "unsigned int ev_depth (loop)" ``` ```Returns the number of times \f(CW\*(C`ev_run\*(C'\fR was entered minus the number of ``` ```times \f(CW\*(C`ev_run\*(C'\fR was exited normally, in other words, the recursion depth. ``` ```.Sp ``` ```Outside \f(CW\*(C`ev_run\*(C'\fR, this number is zero. In a callback, this number is ``` ```\&\f(CW1\fR, unless \f(CW\*(C`ev_run\*(C'\fR was invoked recursively (or from another thread), ``` ```in which case it is higher. ``` ```.Sp ``` ```Leaving \f(CW\*(C`ev_run\*(C'\fR abnormally (setjmp/longjmp, cancelling the thread, ``` ```throwing an exception etc.), doesn't count as \*(L"exit\*(R" \- consider this ``` ```as a hint to avoid such ungentleman-like behaviour unless it's really ``` ```convenient, in which case it is fully supported. ``` ```.IP "unsigned int ev_backend (loop)" 4 ``` ```.IX Item "unsigned int ev_backend (loop)" ``` ```Returns one of the \f(CW\*(C`EVBACKEND_*\*(C'\fR flags indicating the event backend in ``` ```use. ``` ```.IP "ev_tstamp ev_now (loop)" 4 ``` ```.IX Item "ev_tstamp ev_now (loop)" ``` ```Returns the current \*(L"event loop time\*(R", which is the time the event loop ``` ```received events and started processing them. This timestamp does not ``` ```change as long as callbacks are being processed, and this is also the base ``` ```time used for relative timers. You can treat it as the timestamp of the ``` ```event occurring (or more correctly, libev finding out about it). ``` ```.IP "ev_now_update (loop)" 4 ``` ```.IX Item "ev_now_update (loop)" ``` ```Establishes the current time by querying the kernel, updating the time ``` ```returned by \f(CW\*(C`ev_now ()\*(C'\fR in the progress. This is a costly operation and ``` ```is usually done automatically within \f(CW\*(C`ev_run ()\*(C'\fR. ``` ```.Sp ``` ```This function is rarely useful, but when some event callback runs for a ``` ```very long time without entering the event loop, updating libev's idea of ``` ```the current time is a good idea. ``` ```.Sp ``` ```See also \*(L"The special problem of time updates\*(R" in the \f(CW\*(C`ev_timer\*(C'\fR section. ``` ```.IP "ev_suspend (loop)" 4 ``` ```.IX Item "ev_suspend (loop)" ``` ```.PD 0 ``` ```.IP "ev_resume (loop)" 4 ``` ```.IX Item "ev_resume (loop)" ``` ```.PD ``` ```These two functions suspend and resume an event loop, for use when the ``` ```loop is not used for a while and timeouts should not be processed. ``` ```.Sp ``` ```A typical use case would be an interactive program such as a game: When ``` ```the user presses \f(CW\*(C`^Z\*(C'\fR to suspend the game and resumes it an hour later it ``` ```would be best to handle timeouts as if no time had actually passed while ``` ```the program was suspended. This can be achieved by calling \f(CW\*(C`ev_suspend\*(C'\fR ``` ```in your \f(CW\*(C`SIGTSTP\*(C'\fR handler, sending yourself a \f(CW\*(C`SIGSTOP\*(C'\fR and calling ``` ```\&\f(CW\*(C`ev_resume\*(C'\fR directly afterwards to resume timer processing. ``` ```.Sp ``` ```Effectively, all \f(CW\*(C`ev_timer\*(C'\fR watchers will be delayed by the time spend ``` ```between \f(CW\*(C`ev_suspend\*(C'\fR and \f(CW\*(C`ev_resume\*(C'\fR, and all \f(CW\*(C`ev_periodic\*(C'\fR watchers ``` ```will be rescheduled (that is, they will lose any events that would have ``` ```occurred while suspended). ``` ```.Sp ``` ```After calling \f(CW\*(C`ev_suspend\*(C'\fR you \fBmust not\fR call \fIany\fR function on the ``` ```given loop other than \f(CW\*(C`ev_resume\*(C'\fR, and you \fBmust not\fR call \f(CW\*(C`ev_resume\*(C'\fR ``` ```without a previous call to \f(CW\*(C`ev_suspend\*(C'\fR. ``` ```.Sp ``` ```Calling \f(CW\*(C`ev_suspend\*(C'\fR/\f(CW\*(C`ev_resume\*(C'\fR has the side effect of updating the ``` ```event loop time (see \f(CW\*(C`ev_now_update\*(C'\fR). ``` ```.IP "bool ev_run (loop, int flags)" 4 ``` ```.IX Item "bool ev_run (loop, int flags)" ``` ```Finally, this is it, the event handler. This function usually is called ``` ```after you have initialised all your watchers and you want to start ``` ```handling events. It will ask the operating system for any new events, call ``` ```the watcher callbacks, and then repeat the whole process indefinitely: This ``` ```is why event loops are called \fIloops\fR. ``` ```.Sp ``` ```If the flags argument is specified as \f(CW0\fR, it will keep handling events ``` ```until either no event watchers are active anymore or \f(CW\*(C`ev_break\*(C'\fR was ``` ```called. ``` ```.Sp ``` ```The return value is false if there are no more active watchers (which ``` ```usually means \*(L"all jobs done\*(R" or \*(L"deadlock\*(R"), and true in all other cases ``` ```(which usually means " you should call \f(CW\*(C`ev_run\*(C'\fR again"). ``` ```.Sp ``` ```Please note that an explicit \f(CW\*(C`ev_break\*(C'\fR is usually better than ``` ```relying on all watchers to be stopped when deciding when a program has ``` ```finished (especially in interactive programs), but having a program ``` ```that automatically loops as long as it has to and no longer by virtue ``` ```of relying on its watchers stopping correctly, that is truly a thing of ``` ```beauty. ``` ```.Sp ``` ```This function is \fImostly\fR exception-safe \- you can break out of a ``` ```\&\f(CW\*(C`ev_run\*(C'\fR call by calling \f(CW\*(C`longjmp\*(C'\fR in a callback, throwing a \*(C+ ``` ```exception and so on. This does not decrement the \f(CW\*(C`ev_depth\*(C'\fR value, nor ``` ```will it clear any outstanding \f(CW\*(C`EVBREAK_ONE\*(C'\fR breaks. ``` ```.Sp ``` ```A flags value of \f(CW\*(C`EVRUN_NOWAIT\*(C'\fR will look for new events, will handle ``` ```those events and any already outstanding ones, but will not wait and ``` ```block your process in case there are no events and will return after one ``` ```iteration of the loop. This is sometimes useful to poll and handle new ``` ```events while doing lengthy calculations, to keep the program responsive. ``` ```.Sp ``` ```A flags value of \f(CW\*(C`EVRUN_ONCE\*(C'\fR will look for new events (waiting if ``` ```necessary) and will handle those and any already outstanding ones. It ``` ```will block your process until at least one new event arrives (which could ``` ```be an event internal to libev itself, so there is no guarantee that a ``` ```user-registered callback will be called), and will return after one ``` ```iteration of the loop. ``` ```.Sp ``` ```This is useful if you are waiting for some external event in conjunction ``` ```with something not expressible using other libev watchers (i.e. "roll your ``` ```own \f(CW\*(C`ev_run\*(C'\fR"). However, a pair of \f(CW\*(C`ev_prepare\*(C'\fR/\f(CW\*(C`ev_check\*(C'\fR watchers is ``` ```usually a better approach for this kind of thing. ``` ```.Sp ``` ```Here are the gory details of what \f(CW\*(C`ev_run\*(C'\fR does (this is for your ``` ```understanding, not a guarantee that things will work exactly like this in ``` ```future versions): ``` ```.Sp ``` ```.Vb 10 ``` ```\& \- Increment loop depth. ``` ```\& \- Reset the ev_break status. ``` ```\& \- Before the first iteration, call any pending watchers. ``` ```\& LOOP: ``` ```\& \- If EVFLAG_FORKCHECK was used, check for a fork. ``` ```\& \- If a fork was detected (by any means), queue and call all fork watchers. ``` ```\& \- Queue and call all prepare watchers. ``` ```\& \- If ev_break was called, goto FINISH. ``` ```\& \- If we have been forked, detach and recreate the kernel state ``` ```\& as to not disturb the other process. ``` ```\& \- Update the kernel state with all outstanding changes. ``` ```\& \- Update the "event loop time" (ev_now ()). ``` ```\& \- Calculate for how long to sleep or block, if at all ``` ```\& (active idle watchers, EVRUN_NOWAIT or not having ``` ```\& any active watchers at all will result in not sleeping). ``` ```\& \- Sleep if the I/O and timer collect interval say so. ``` ```\& \- Increment loop iteration counter. ``` ```\& \- Block the process, waiting for any events. ``` ```\& \- Queue all outstanding I/O (fd) events. ``` ```\& \- Update the "event loop time" (ev_now ()), and do time jump adjustments. ``` ```\& \- Queue all expired timers. ``` ```\& \- Queue all expired periodics. ``` ```\& \- Queue all idle watchers with priority higher than that of pending events. ``` ```\& \- Queue all check watchers. ``` ```\& \- Call all queued watchers in reverse order (i.e. check watchers first). ``` ```\& Signals and child watchers are implemented as I/O watchers, and will ``` ```\& be handled here by queueing them when their watcher gets executed. ``` ```\& \- If ev_break has been called, or EVRUN_ONCE or EVRUN_NOWAIT ``` ```\& were used, or there are no active watchers, goto FINISH, otherwise ``` ```\& continue with step LOOP. ``` ```\& FINISH: ``` ```\& \- Reset the ev_break status iff it was EVBREAK_ONE. ``` ```\& \- Decrement the loop depth. ``` ```\& \- Return. ``` ```.Ve ``` ```.Sp ``` ```Example: Queue some jobs and then loop until no events are outstanding ``` ```anymore. ``` ```.Sp ``` ```.Vb 4 ``` ```\& ... queue jobs here, make sure they register event watchers as long ``` ```\& ... as they still have work to do (even an idle watcher will do..) ``` ```\& ev_run (my_loop, 0); ``` ```\& ... jobs done or somebody called break. yeah! ``` ```.Ve ``` ```.IP "ev_break (loop, how)" 4 ``` ```.IX Item "ev_break (loop, how)" ``` ```Can be used to make a call to \f(CW\*(C`ev_run\*(C'\fR return early (but only after it ``` ```has processed all outstanding events). The \f(CW\*(C`how\*(C'\fR argument must be either ``` ```\&\f(CW\*(C`EVBREAK_ONE\*(C'\fR, which will make the innermost \f(CW\*(C`ev_run\*(C'\fR call return, or ``` ```\&\f(CW\*(C`EVBREAK_ALL\*(C'\fR, which will make all nested \f(CW\*(C`ev_run\*(C'\fR calls return. ``` ```.Sp ``` ```This \*(L"break state\*(R" will be cleared on the next call to \f(CW\*(C`ev_run\*(C'\fR. ``` ```.Sp ``` ```It is safe to call \f(CW\*(C`ev_break\*(C'\fR from outside any \f(CW\*(C`ev_run\*(C'\fR calls, too, in ``` ```which case it will have no effect. ``` ```.IP "ev_ref (loop)" 4 ``` ```.IX Item "ev_ref (loop)" ``` ```.PD 0 ``` ```.IP "ev_unref (loop)" 4 ``` ```.IX Item "ev_unref (loop)" ``` ```.PD ``` ```Ref/unref can be used to add or remove a reference count on the event ``` ```loop: Every watcher keeps one reference, and as long as the reference ``` ```count is nonzero, \f(CW\*(C`ev_run\*(C'\fR will not return on its own. ``` ```.Sp ``` ```This is useful when you have a watcher that you never intend to ``` ```unregister, but that nevertheless should not keep \f(CW\*(C`ev_run\*(C'\fR from ``` ```returning. In such a case, call \f(CW\*(C`ev_unref\*(C'\fR after starting, and \f(CW\*(C`ev_ref\*(C'\fR ``` ```before stopping it. ``` ```.Sp ``` ```As an example, libev itself uses this for its internal signal pipe: It ``` ```is not visible to the libev user and should not keep \f(CW\*(C`ev_run\*(C'\fR from ``` ```exiting if no event watchers registered by it are active. It is also an ``` ```excellent way to do this for generic recurring timers or from within ``` ```third-party libraries. Just remember to \fIunref after start\fR and \fIref ``` ```before stop\fR (but only if the watcher wasn't active before, or was active ``` ```before, respectively. Note also that libev might stop watchers itself ``` ```(e.g. non-repeating timers) in which case you have to \f(CW\*(C`ev_ref\*(C'\fR ``` ```in the callback). ``` ```.Sp ``` ```Example: Create a signal watcher, but keep it from keeping \f(CW\*(C`ev_run\*(C'\fR ``` ```running when nothing else is active. ``` ```.Sp ``` ```.Vb 4 ``` ```\& ev_signal exitsig; ``` ```\& ev_signal_init (&exitsig, sig_cb, SIGINT); ``` ```\& ev_signal_start (loop, &exitsig); ``` ```\& ev_unref (loop); ``` ```.Ve ``` ```.Sp ``` ```Example: For some weird reason, unregister the above signal handler again. ``` ```.Sp ``` ```.Vb 2 ``` ```\& ev_ref (loop); ``` ```\& ev_signal_stop (loop, &exitsig); ``` ```.Ve ``` ```.IP "ev_set_io_collect_interval (loop, ev_tstamp interval)" 4 ``` ```.IX Item "ev_set_io_collect_interval (loop, ev_tstamp interval)" ``` ```.PD 0 ``` ```.IP "ev_set_timeout_collect_interval (loop, ev_tstamp interval)" 4 ``` ```.IX Item "ev_set_timeout_collect_interval (loop, ev_tstamp interval)" ``` ```.PD ``` ```These advanced functions influence the time that libev will spend waiting ``` ```for events. Both time intervals are by default \f(CW0\fR, meaning that libev ``` ```will try to invoke timer/periodic callbacks and I/O callbacks with minimum ``` ```latency. ``` ```.Sp ``` ```Setting these to a higher value (the \f(CW\*(C`interval\*(C'\fR \fImust\fR be >= \f(CW0\fR) ``` ```allows libev to delay invocation of I/O and timer/periodic callbacks ``` ```to increase efficiency of loop iterations (or to increase power-saving ``` ```opportunities). ``` ```.Sp ``` ```The idea is that sometimes your program runs just fast enough to handle ``` ```one (or very few) event(s) per loop iteration. While this makes the ``` ```program responsive, it also wastes a lot of \s-1CPU\s0 time to poll for new ``` ```events, especially with backends like \f(CW\*(C`select ()\*(C'\fR which have a high ``` ```overhead for the actual polling but can deliver many events at once. ``` ```.Sp ``` ```By setting a higher \fIio collect interval\fR you allow libev to spend more ``` ```time collecting I/O events, so you can handle more events per iteration, ``` ```at the cost of increasing latency. Timeouts (both \f(CW\*(C`ev_periodic\*(C'\fR and ``` ```\&\f(CW\*(C`ev_timer\*(C'\fR) will not be affected. Setting this to a non-null value will ``` ```introduce an additional \f(CW\*(C`ev_sleep ()\*(C'\fR call into most loop iterations. The ``` ```sleep time ensures that libev will not poll for I/O events more often then ``` ```once per this interval, on average (as long as the host time resolution is ``` ```good enough). ``` ```.Sp ``` ```Likewise, by setting a higher \fItimeout collect interval\fR you allow libev ``` ```to spend more time collecting timeouts, at the expense of increased ``` ```latency/jitter/inexactness (the watcher callback will be called ``` ```later). \f(CW\*(C`ev_io\*(C'\fR watchers will not be affected. Setting this to a non-null ``` ```value will not introduce any overhead in libev. ``` ```.Sp ``` ```Many (busy) programs can usually benefit by setting the I/O collect ``` ```interval to a value near \f(CW0.1\fR or so, which is often enough for ``` ```interactive servers (of course not for games), likewise for timeouts. It ``` ```usually doesn't make much sense to set it to a lower value than \f(CW0.01\fR, ``` ```as this approaches the timing granularity of most systems. Note that if ``` ```you do transactions with the outside world and you can't increase the ``` ```parallelity, then this setting will limit your transaction rate (if you ``` ```need to poll once per transaction and the I/O collect interval is 0.01, ``` ```then you can't do more than 100 transactions per second). ``` ```.Sp ``` ```Setting the \fItimeout collect interval\fR can improve the opportunity for ``` ```saving power, as the program will \*(L"bundle\*(R" timer callback invocations that ``` ```are \*(L"near\*(R" in time together, by delaying some, thus reducing the number of ``` ```times the process sleeps and wakes up again. Another useful technique to ``` ```reduce iterations/wake\-ups is to use \f(CW\*(C`ev_periodic\*(C'\fR watchers and make sure ``` ```they fire on, say, one-second boundaries only. ``` ```.Sp ``` ```Example: we only need 0.1s timeout granularity, and we wish not to poll ``` ```more often than 100 times per second: ``` ```.Sp ``` ```.Vb 2 ``` ```\& ev_set_timeout_collect_interval (EV_DEFAULT_UC_ 0.1); ``` ```\& ev_set_io_collect_interval (EV_DEFAULT_UC_ 0.01); ``` ```.Ve ``` ```.IP "ev_invoke_pending (loop)" 4 ``` ```.IX Item "ev_invoke_pending (loop)" ``` ```This call will simply invoke all pending watchers while resetting their ``` ```pending state. Normally, \f(CW\*(C`ev_run\*(C'\fR does this automatically when required, ``` ```but when overriding the invoke callback this call comes handy. This ``` ```function can be invoked from a watcher \- this can be useful for example ``` ```when you want to do some lengthy calculation and want to pass further ``` ```event handling to another thread (you still have to make sure only one ``` ```thread executes within \f(CW\*(C`ev_invoke_pending\*(C'\fR or \f(CW\*(C`ev_run\*(C'\fR of course). ``` ```.IP "int ev_pending_count (loop)" 4 ``` ```.IX Item "int ev_pending_count (loop)" ``` ```Returns the number of pending watchers \- zero indicates that no watchers ``` ```are pending. ``` ```.IP "ev_set_invoke_pending_cb (loop, void (*invoke_pending_cb)(\s-1EV_P\s0))" 4 ``` ```.IX Item "ev_set_invoke_pending_cb (loop, void (*invoke_pending_cb)(EV_P))" ``` ```This overrides the invoke pending functionality of the loop: Instead of ``` ```invoking all pending watchers when there are any, \f(CW\*(C`ev_run\*(C'\fR will call ``` ```this callback instead. This is useful, for example, when you want to ``` ```invoke the actual watchers inside another context (another thread etc.). ``` ```.Sp ``` ```If you want to reset the callback, use \f(CW\*(C`ev_invoke_pending\*(C'\fR as new ``` ```callback. ``` ```.IP "ev_set_loop_release_cb (loop, void (*release)(\s-1EV_P\s0) throw (), void (*acquire)(\s-1EV_P\s0) throw ())" 4 ``` ```.IX Item "ev_set_loop_release_cb (loop, void (*release)(EV_P) throw (), void (*acquire)(EV_P) throw ())" ``` ```Sometimes you want to share the same loop between multiple threads. This ``` ```can be done relatively simply by putting mutex_lock/unlock calls around ``` ```each call to a libev function. ``` ```.Sp ``` ```However, \f(CW\*(C`ev_run\*(C'\fR can run an indefinite time, so it is not feasible ``` ```to wait for it to return. One way around this is to wake up the event ``` ```loop via \f(CW\*(C`ev_break\*(C'\fR and \f(CW\*(C`ev_async_send\*(C'\fR, another way is to set these ``` ```\&\fIrelease\fR and \fIacquire\fR callbacks on the loop. ``` ```.Sp ``` ```When set, then \f(CW\*(C`release\*(C'\fR will be called just before the thread is ``` ```suspended waiting for new events, and \f(CW\*(C`acquire\*(C'\fR is called just ``` ```afterwards. ``` ```.Sp ``` ```Ideally, \f(CW\*(C`release\*(C'\fR will just call your mutex_unlock function, and ``` ```\&\f(CW\*(C`acquire\*(C'\fR will just call the mutex_lock function again. ``` ```.Sp ``` ```While event loop modifications are allowed between invocations of ``` ```\&\f(CW\*(C`release\*(C'\fR and \f(CW\*(C`acquire\*(C'\fR (that's their only purpose after all), no ``` ```modifications done will affect the event loop, i.e. adding watchers will ``` ```have no effect on the set of file descriptors being watched, or the time ``` ```waited. Use an \f(CW\*(C`ev_async\*(C'\fR watcher to wake up \f(CW\*(C`ev_run\*(C'\fR when you want it ``` ```to take note of any changes you made. ``` ```.Sp ``` ```In theory, threads executing \f(CW\*(C`ev_run\*(C'\fR will be async-cancel safe between ``` ```invocations of \f(CW\*(C`release\*(C'\fR and \f(CW\*(C`acquire\*(C'\fR. ``` ```.Sp ``` ```See also the locking example in the \f(CW\*(C`THREADS\*(C'\fR section later in this ``` ```document. ``` ```.IP "ev_set_userdata (loop, void *data)" 4 ``` ```.IX Item "ev_set_userdata (loop, void *data)" ``` ```.PD 0 ``` ```.IP "void *ev_userdata (loop)" 4 ``` ```.IX Item "void *ev_userdata (loop)" ``` ```.PD ``` ```Set and retrieve a single \f(CW\*(C`void *\*(C'\fR associated with a loop. When ``` ```\&\f(CW\*(C`ev_set_userdata\*(C'\fR has never been called, then \f(CW\*(C`ev_userdata\*(C'\fR returns ``` ```\&\f(CW0\fR. ``` ```.Sp ``` ```These two functions can be used to associate arbitrary data with a loop, ``` ```and are intended solely for the \f(CW\*(C`invoke_pending_cb\*(C'\fR, \f(CW\*(C`release\*(C'\fR and ``` ```\&\f(CW\*(C`acquire\*(C'\fR callbacks described above, but of course can be (ab\-)used for ``` ```any other purpose as well. ``` ```.IP "ev_verify (loop)" 4 ``` ```.IX Item "ev_verify (loop)" ``` ```This function only does something when \f(CW\*(C`EV_VERIFY\*(C'\fR support has been ``` ```compiled in, which is the default for non-minimal builds. It tries to go ``` ```through all internal structures and checks them for validity. If anything ``` ```is found to be inconsistent, it will print an error message to standard ``` ```error and call \f(CW\*(C`abort ()\*(C'\fR. ``` ```.Sp ``` ```This can be used to catch bugs inside libev itself: under normal ``` ```circumstances, this function will never abort as of course libev keeps its ``` ```data structures consistent. ``` ```.SH "ANATOMY OF A WATCHER" ``` ```.IX Header "ANATOMY OF A WATCHER" ``` ```In the following description, uppercase \f(CW\*(C`TYPE\*(C'\fR in names stands for the ``` ```watcher type, e.g. \f(CW\*(C`ev_TYPE_start\*(C'\fR can mean \f(CW\*(C`ev_timer_start\*(C'\fR for timer ``` ```watchers and \f(CW\*(C`ev_io_start\*(C'\fR for I/O watchers. ``` ```.PP ``` ```A watcher is an opaque structure that you allocate and register to record ``` ```your interest in some event. To make a concrete example, imagine you want ``` ```to wait for \s-1STDIN\s0 to become readable, you would create an \f(CW\*(C`ev_io\*(C'\fR watcher ``` ```for that: ``` ```.PP ``` ```.Vb 5 ``` ```\& static void my_cb (struct ev_loop *loop, ev_io *w, int revents) ``` ```\& { ``` ```\& ev_io_stop (w); ``` ```\& ev_break (loop, EVBREAK_ALL); ``` ```\& } ``` ```\& ``` ```\& struct ev_loop *loop = ev_default_loop (0); ``` ```\& ``` ```\& ev_io stdin_watcher; ``` ```\& ``` ```\& ev_init (&stdin_watcher, my_cb); ``` ```\& ev_io_set (&stdin_watcher, STDIN_FILENO, EV_READ); ``` ```\& ev_io_start (loop, &stdin_watcher); ``` ```\& ``` ```\& ev_run (loop, 0); ``` ```.Ve ``` ```.PP ``` ```As you can see, you are responsible for allocating the memory for your ``` ```watcher structures (and it is \fIusually\fR a bad idea to do this on the ``` ```stack). ``` ```.PP ``` ```Each watcher has an associated watcher structure (called \f(CW\*(C`struct ev_TYPE\*(C'\fR ``` ```or simply \f(CW\*(C`ev_TYPE\*(C'\fR, as typedefs are provided for all watcher structs). ``` ```.PP ``` ```Each watcher structure must be initialised by a call to \f(CW\*(C`ev_init (watcher ``` ```*, callback)\*(C'\fR, which expects a callback to be provided. This callback is ``` ```invoked each time the event occurs (or, in the case of I/O watchers, each ``` ```time the event loop detects that the file descriptor given is readable ``` ```and/or writable). ``` ```.PP ``` ```Each watcher type further has its own \f(CW\*(C`ev_TYPE_set (watcher *, ...)\*(C'\fR ``` ```macro to configure it, with arguments specific to the watcher type. There ``` ```is also a macro to combine initialisation and setting in one call: \f(CW\*(C`ev_TYPE_init (watcher *, callback, ...)\*(C'\fR. ``` ```.PP ``` ```To make the watcher actually watch out for events, you have to start it ``` ```with a watcher-specific start function (\f(CW\*(C`ev_TYPE_start (loop, watcher ``` ```*)\*(C'\fR), and you can stop watching for events at any time by calling the ``` ```corresponding stop function (\f(CW\*(C`ev_TYPE_stop (loop, watcher *)\*(C'\fR. ``` ```.PP ``` ```As long as your watcher is active (has been started but not stopped) you ``` ```must not touch the values stored in it. Most specifically you must never ``` ```reinitialise it or call its \f(CW\*(C`ev_TYPE_set\*(C'\fR macro. ``` ```.PP ``` ```Each and every callback receives the event loop pointer as first, the ``` ```registered watcher structure as second, and a bitset of received events as ``` ```third argument. ``` ```.PP ``` ```The received events usually include a single bit per event type received ``` ```(you can receive multiple events at the same time). The possible bit masks ``` ```are: ``` ```.ie n .IP """EV_READ""" 4 ``` ```.el .IP "\f(CWEV_READ\fR" 4 ``` ```.IX Item "EV_READ" ``` ```.PD 0 ``` ```.ie n .IP """EV_WRITE""" 4 ``` ```.el .IP "\f(CWEV_WRITE\fR" 4 ``` ```.IX Item "EV_WRITE" ``` ```.PD ``` ```The file descriptor in the \f(CW\*(C`ev_io\*(C'\fR watcher has become readable and/or ``` ```writable. ``` ```.ie n .IP """EV_TIMER""" 4 ``` ```.el .IP "\f(CWEV_TIMER\fR" 4 ``` ```.IX Item "EV_TIMER" ``` ```The \f(CW\*(C`ev_timer\*(C'\fR watcher has timed out. ``` ```.ie n .IP """EV_PERIODIC""" 4 ``` ```.el .IP "\f(CWEV_PERIODIC\fR" 4 ``` ```.IX Item "EV_PERIODIC" ``` ```The \f(CW\*(C`ev_periodic\*(C'\fR watcher has timed out. ``` ```.ie n .IP """EV_SIGNAL""" 4 ``` ```.el .IP "\f(CWEV_SIGNAL\fR" 4 ``` ```.IX Item "EV_SIGNAL" ``` ```The signal specified in the \f(CW\*(C`ev_signal\*(C'\fR watcher has been received by a thread. ``` ```.ie n .IP """EV_CHILD""" 4 ``` ```.el .IP "\f(CWEV_CHILD\fR" 4 ``` ```.IX Item "EV_CHILD" ``` ```The pid specified in the \f(CW\*(C`ev_child\*(C'\fR watcher has received a status change. ``` ```.ie n .IP """EV_STAT""" 4 ``` ```.el .IP "\f(CWEV_STAT\fR" 4 ``` ```.IX Item "EV_STAT" ``` ```The path specified in the \f(CW\*(C`ev_stat\*(C'\fR watcher changed its attributes somehow. ``` ```.ie n .IP """EV_IDLE""" 4 ``` ```.el .IP "\f(CWEV_IDLE\fR" 4 ``` ```.IX Item "EV_IDLE" ``` ```The \f(CW\*(C`ev_idle\*(C'\fR watcher has determined that you have nothing better to do. ``` ```.ie n .IP """EV_PREPARE""" 4 ``` ```.el .IP "\f(CWEV_PREPARE\fR" 4 ``` ```.IX Item "EV_PREPARE" ``` ```.PD 0 ``` ```.ie n .IP """EV_CHECK""" 4 ``` ```.el .IP "\f(CWEV_CHECK\fR" 4 ``` ```.IX Item "EV_CHECK" ``` ```.PD ``` ```All \f(CW\*(C`ev_prepare\*(C'\fR watchers are invoked just \fIbefore\fR \f(CW\*(C`ev_run\*(C'\fR starts to ``` ```gather new events, and all \f(CW\*(C`ev_check\*(C'\fR watchers are queued (not invoked) ``` ```just after \f(CW\*(C`ev_run\*(C'\fR has gathered them, but before it queues any callbacks ``` ```for any received events. That means \f(CW\*(C`ev_prepare\*(C'\fR watchers are the last ``` ```watchers invoked before the event loop sleeps or polls for new events, and ``` ```\&\f(CW\*(C`ev_check\*(C'\fR watchers will be invoked before any other watchers of the same ``` ```or lower priority within an event loop iteration. ``` ```.Sp ``` ```Callbacks of both watcher types can start and stop as many watchers as ``` ```they want, and all of them will be taken into account (for example, a ``` ```\&\f(CW\*(C`ev_prepare\*(C'\fR watcher might start an idle watcher to keep \f(CW\*(C`ev_run\*(C'\fR from ``` ```blocking). ``` ```.ie n .IP """EV_EMBED""" 4 ``` ```.el .IP "\f(CWEV_EMBED\fR" 4 ``` ```.IX Item "EV_EMBED" ``` ```The embedded event loop specified in the \f(CW\*(C`ev_embed\*(C'\fR watcher needs attention. ``` ```.ie n .IP """EV_FORK""" 4 ``` ```.el .IP "\f(CWEV_FORK\fR" 4 ``` ```.IX Item "EV_FORK" ``` ```The event loop has been resumed in the child process after fork (see ``` ```\&\f(CW\*(C`ev_fork\*(C'\fR). ``` ```.ie n .IP """EV_CLEANUP""" 4 ``` ```.el .IP "\f(CWEV_CLEANUP\fR" 4 ``` ```.IX Item "EV_CLEANUP" ``` ```The event loop is about to be destroyed (see \f(CW\*(C`ev_cleanup\*(C'\fR). ``` ```.ie n .IP """EV_ASYNC""" 4 ``` ```.el .IP "\f(CWEV_ASYNC\fR" 4 ``` ```.IX Item "EV_ASYNC" ``` ```The given async watcher has been asynchronously notified (see \f(CW\*(C`ev_async\*(C'\fR). ``` ```.ie n .IP """EV_CUSTOM""" 4 ``` ```.el .IP "\f(CWEV_CUSTOM\fR" 4 ``` ```.IX Item "EV_CUSTOM" ``` ```Not ever sent (or otherwise used) by libev itself, but can be freely used ``` ```by libev users to signal watchers (e.g. via \f(CW\*(C`ev_feed_event\*(C'\fR). ``` ```.ie n .IP """EV_ERROR""" 4 ``` ```.el .IP "\f(CWEV_ERROR\fR" 4 ``` ```.IX Item "EV_ERROR" ``` ```An unspecified error has occurred, the watcher has been stopped. This might ``` ```happen because the watcher could not be properly started because libev ``` ```ran out of memory, a file descriptor was found to be closed or any other ``` ```problem. Libev considers these application bugs. ``` ```.Sp ``` ```You best act on it by reporting the problem and somehow coping with the ``` ```watcher being stopped. Note that well-written programs should not receive ``` ```an error ever, so when your watcher receives it, this usually indicates a ``` ```bug in your program. ``` ```.Sp ``` ```Libev will usually signal a few \*(L"dummy\*(R" events together with an error, for ``` ```example it might indicate that a fd is readable or writable, and if your ``` ```callbacks is well-written it can just attempt the operation and cope with ``` ```the error from \fIread()\fR or \fIwrite()\fR. This will not work in multi-threaded ``` ```programs, though, as the fd could already be closed and reused for another ``` ```thing, so beware. ``` ```.SS "\s-1GENERIC WATCHER FUNCTIONS\s0" ``` ```.IX Subsection "GENERIC WATCHER FUNCTIONS" ``` ```.ie n .IP """ev_init"" (ev_TYPE *watcher, callback)" 4 ``` ```.el .IP "\f(CWev_init\fR (ev_TYPE *watcher, callback)" 4 ``` ```.IX Item "ev_init (ev_TYPE *watcher, callback)" ``` ```This macro initialises the generic portion of a watcher. The contents ``` ```of the watcher object can be arbitrary (so \f(CW\*(C`malloc\*(C'\fR will do). Only ``` ```the generic parts of the watcher are initialised, you \fIneed\fR to call ``` ```the type-specific \f(CW\*(C`ev_TYPE_set\*(C'\fR macro afterwards to initialise the ``` ```type-specific parts. For each type there is also a \f(CW\*(C`ev_TYPE_init\*(C'\fR macro ``` ```which rolls both calls into one. ``` ```.Sp ``` ```You can reinitialise a watcher at any time as long as it has been stopped ``` ```(or never started) and there are no pending events outstanding. ``` ```.Sp ``` ```The callback is always of type \f(CW\*(C`void (*)(struct ev_loop *loop, ev_TYPE *watcher, ``` ```int revents)\*(C'\fR. ``` ```.Sp ``` ```Example: Initialise an \f(CW\*(C`ev_io\*(C'\fR watcher in two steps. ``` ```.Sp ``` ```.Vb 3 ``` ```\& ev_io w; ``` ```\& ev_init (&w, my_cb); ``` ```\& ev_io_set (&w, STDIN_FILENO, EV_READ); ``` ```.Ve ``` ```.ie n .IP """ev_TYPE_set"" (ev_TYPE *watcher, [args])" 4 ``` ```.el .IP "\f(CWev_TYPE_set\fR (ev_TYPE *watcher, [args])" 4 ``` ```.IX Item "ev_TYPE_set (ev_TYPE *watcher, [args])" ``` ```This macro initialises the type-specific parts of a watcher. You need to ``` ```call \f(CW\*(C`ev_init\*(C'\fR at least once before you call this macro, but you can ``` ```call \f(CW\*(C`ev_TYPE_set\*(C'\fR any number of times. You must not, however, call this ``` ```macro on a watcher that is active (it can be pending, however, which is a ``` ```difference to the \f(CW\*(C`ev_init\*(C'\fR macro). ``` ```.Sp ``` ```Although some watcher types do not have type-specific arguments ``` ```(e.g. \f(CW\*(C`ev_prepare\*(C'\fR) you still need to call its \f(CW\*(C`set\*(C'\fR macro. ``` ```.Sp ``` ```See \f(CW\*(C`ev_init\*(C'\fR, above, for an example. ``` ```.ie n .IP """ev_TYPE_init"" (ev_TYPE *watcher, callback, [args])" 4 ``` ```.el .IP "\f(CWev_TYPE_init\fR (ev_TYPE *watcher, callback, [args])" 4 ``` ```.IX Item "ev_TYPE_init (ev_TYPE *watcher, callback, [args])" ``` ```This convenience macro rolls both \f(CW\*(C`ev_init\*(C'\fR and \f(CW\*(C`ev_TYPE_set\*(C'\fR macro ``` ```calls into a single call. This is the most convenient method to initialise ``` ```a watcher. The same limitations apply, of course. ``` ```.Sp ``` ```Example: Initialise and set an \f(CW\*(C`ev_io\*(C'\fR watcher in one step. ``` ```.Sp ``` ```.Vb 1 ``` ```\& ev_io_init (&w, my_cb, STDIN_FILENO, EV_READ); ``` ```.Ve ``` ```.ie n .IP """ev_TYPE_start"" (loop, ev_TYPE *watcher)" 4 ``` ```.el .IP "\f(CWev_TYPE_start\fR (loop, ev_TYPE *watcher)" 4 ``` ```.IX Item "ev_TYPE_start (loop, ev_TYPE *watcher)" ``` ```Starts (activates) the given watcher. Only active watchers will receive ``` ```events. If the watcher is already active nothing will happen. ``` ```.Sp ``` ```Example: Start the \f(CW\*(C`ev_io\*(C'\fR watcher that is being abused as example in this ``` ```whole section. ``` ```.Sp ``` ```.Vb 1 ``` ```\& ev_io_start (EV_DEFAULT_UC, &w); ``` ```.Ve ``` ```.ie n .IP """ev_TYPE_stop"" (loop, ev_TYPE *watcher)" 4 ``` ```.el .IP "\f(CWev_TYPE_stop\fR (loop, ev_TYPE *watcher)" 4 ``` ```.IX Item "ev_TYPE_stop (loop, ev_TYPE *watcher)" ``` ```Stops the given watcher if active, and clears the pending status (whether ``` ```the watcher was active or not). ``` ```.Sp ``` ```It is possible that stopped watchers are pending \- for example, ``` ```non-repeating timers are being stopped when they become pending \- but ``` ```calling \f(CW\*(C`ev_TYPE_stop\*(C'\fR ensures that the watcher is neither active nor ``` ```pending. If you want to free or reuse the memory used by the watcher it is ``` ```therefore a good idea to always call its \f(CW\*(C`ev_TYPE_stop\*(C'\fR function. ``` ```.IP "bool ev_is_active (ev_TYPE *watcher)" 4 ``` ```.IX Item "bool ev_is_active (ev_TYPE *watcher)" ``` ```Returns a true value iff the watcher is active (i.e. it has been started ``` ```and not yet been stopped). As long as a watcher is active you must not modify ``` ```it. ``` ```.IP "bool ev_is_pending (ev_TYPE *watcher)" 4 ``` ```.IX Item "bool ev_is_pending (ev_TYPE *watcher)" ``` ```Returns a true value iff the watcher is pending, (i.e. it has outstanding ``` ```events but its callback has not yet been invoked). As long as a watcher ``` ```is pending (but not active) you must not call an init function on it (but ``` ```\&\f(CW\*(C`ev_TYPE_set\*(C'\fR is safe), you must not change its priority, and you must ``` ```make sure the watcher is available to libev (e.g. you cannot \f(CW\*(C`free ()\*(C'\fR ``` ```it). ``` ```.IP "callback ev_cb (ev_TYPE *watcher)" 4 ``` ```.IX Item "callback ev_cb (ev_TYPE *watcher)" ``` ```Returns the callback currently set on the watcher. ``` ```.IP "ev_set_cb (ev_TYPE *watcher, callback)" 4 ``` ```.IX Item "ev_set_cb (ev_TYPE *watcher, callback)" ``` ```Change the callback. You can change the callback at virtually any time ``` ```(modulo threads). ``` ```.IP "ev_set_priority (ev_TYPE *watcher, int priority)" 4 ``` ```.IX Item "ev_set_priority (ev_TYPE *watcher, int priority)" ``` ```.PD 0 ``` ```.IP "int ev_priority (ev_TYPE *watcher)" 4 ``` ```.IX Item "int ev_priority (ev_TYPE *watcher)" ``` ```.PD ``` ```Set and query the priority of the watcher. The priority is a small ``` ```integer between \f(CW\*(C`EV_MAXPRI\*(C'\fR (default: \f(CW2\fR) and \f(CW\*(C`EV_MINPRI\*(C'\fR ``` ```(default: \f(CW\*(C`\-2\*(C'\fR). Pending watchers with higher priority will be invoked ``` ```before watchers with lower priority, but priority will not keep watchers ``` ```from being executed (except for \f(CW\*(C`ev_idle\*(C'\fR watchers). ``` ```.Sp ``` ```If you need to suppress invocation when higher priority events are pending ``` ```you need to look at \f(CW\*(C`ev_idle\*(C'\fR watchers, which provide this functionality. ``` ```.Sp ``` ```You \fImust not\fR change the priority of a watcher as long as it is active or ``` ```pending. ``` ```.Sp ``` ```Setting a priority outside the range of \f(CW\*(C`EV_MINPRI\*(C'\fR to \f(CW\*(C`EV_MAXPRI\*(C'\fR is ``` ```fine, as long as you do not mind that the priority value you query might ``` ```or might not have been clamped to the valid range. ``` ```.Sp ``` ```The default priority used by watchers when no priority has been set is ``` ```always \f(CW0\fR, which is supposed to not be too high and not be too low :). ``` ```.Sp ``` ```See \*(L"\s-1WATCHER PRIORITY MODELS\*(R"\s0, below, for a more thorough treatment of ``` ```priorities. ``` ```.IP "ev_invoke (loop, ev_TYPE *watcher, int revents)" 4 ``` ```.IX Item "ev_invoke (loop, ev_TYPE *watcher, int revents)" ``` ```Invoke the \f(CW\*(C`watcher\*(C'\fR with the given \f(CW\*(C`loop\*(C'\fR and \f(CW\*(C`revents\*(C'\fR. Neither ``` ```\&\f(CW\*(C`loop\*(C'\fR nor \f(CW\*(C`revents\*(C'\fR need to be valid as long as the watcher callback ``` ```can deal with that fact, as both are simply passed through to the ``` ```callback. ``` ```.IP "int ev_clear_pending (loop, ev_TYPE *watcher)" 4 ``` ```.IX Item "int ev_clear_pending (loop, ev_TYPE *watcher)" ``` ```If the watcher is pending, this function clears its pending status and ``` ```returns its \f(CW\*(C`revents\*(C'\fR bitset (as if its callback was invoked). If the ``` ```watcher isn't pending it does nothing and returns \f(CW0\fR. ``` ```.Sp ``` ```Sometimes it can be useful to \*(L"poll\*(R" a watcher instead of waiting for its ``` ```callback to be invoked, which can be accomplished with this function. ``` ```.IP "ev_feed_event (loop, ev_TYPE *watcher, int revents)" 4 ``` ```.IX Item "ev_feed_event (loop, ev_TYPE *watcher, int revents)" ``` ```Feeds the given event set into the event loop, as if the specified event ``` ```had happened for the specified watcher (which must be a pointer to an ``` ```initialised but not necessarily started event watcher). Obviously you must ``` ```not free the watcher as long as it has pending events. ``` ```.Sp ``` ```Stopping the watcher, letting libev invoke it, or calling ``` ```\&\f(CW\*(C`ev_clear_pending\*(C'\fR will clear the pending event, even if the watcher was ``` ```not started in the first place. ``` ```.Sp ``` ```See also \f(CW\*(C`ev_feed_fd_event\*(C'\fR and \f(CW\*(C`ev_feed_signal_event\*(C'\fR for related ``` ```functions that do not need a watcher. ``` ```.PP ``` ```See also the \*(L"\s-1ASSOCIATING CUSTOM DATA WITH A WATCHER\*(R"\s0 and \*(L"\s-1BUILDING YOUR ``` ```OWN COMPOSITE WATCHERS\*(R"\s0 idioms. ``` ```.SS "\s-1WATCHER STATES\s0" ``` ```.IX Subsection "WATCHER STATES" ``` ```There are various watcher states mentioned throughout this manual \- ``` ```active, pending and so on. In this section these states and the rules to ``` ```transition between them will be described in more detail \- and while these ``` ```rules might look complicated, they usually do \*(L"the right thing\*(R". ``` ```.IP "initialised" 4 ``` ```.IX Item "initialised" ``` ```Before a watcher can be registered with the event loop it has to be ``` ```initialised. This can be done with a call to \f(CW\*(C`ev_TYPE_init\*(C'\fR, or calls to ``` ```\&\f(CW\*(C`ev_init\*(C'\fR followed by the watcher-specific \f(CW\*(C`ev_TYPE_set\*(C'\fR function. ``` ```.Sp ``` ```In this state it is simply some block of memory that is suitable for ``` ```use in an event loop. It can be moved around, freed, reused etc. at ``` ```will \- as long as you either keep the memory contents intact, or call ``` ```\&\f(CW\*(C`ev_TYPE_init\*(C'\fR again. ``` ```.IP "started/running/active" 4 ``` ```.IX Item "started/running/active" ``` ```Once a watcher has been started with a call to \f(CW\*(C`ev_TYPE_start\*(C'\fR it becomes ``` ```property of the event loop, and is actively waiting for events. While in ``` ```this state it cannot be accessed (except in a few documented ways), moved, ``` ```freed or anything else \- the only legal thing is to keep a pointer to it, ``` ```and call libev functions on it that are documented to work on active watchers. ``` ```.IP "pending" 4 ``` ```.IX Item "pending" ``` ```If a watcher is active and libev determines that an event it is interested ``` ```in has occurred (such as a timer expiring), it will become pending. It will ``` ```stay in this pending state until either it is stopped or its callback is ``` ```about to be invoked, so it is not normally pending inside the watcher ``` ```callback. ``` ```.Sp ``` ```The watcher might or might not be active while it is pending (for example, ``` ```an expired non-repeating timer can be pending but no longer active). If it ``` ```is stopped, it can be freely accessed (e.g. by calling \f(CW\*(C`ev_TYPE_set\*(C'\fR), ``` ```but it is still property of the event loop at this time, so cannot be ``` ```moved, freed or reused. And if it is active the rules described in the ``` ```previous item still apply. ``` ```.Sp ``` ```It is also possible to feed an event on a watcher that is not active (e.g. ``` ```via \f(CW\*(C`ev_feed_event\*(C'\fR), in which case it becomes pending without being ``` ```active. ``` ```.IP "stopped" 4 ``` ```.IX Item "stopped" ``` ```A watcher can be stopped implicitly by libev (in which case it might still ``` ```be pending), or explicitly by calling its \f(CW\*(C`ev_TYPE_stop\*(C'\fR function. The ``` ```latter will clear any pending state the watcher might be in, regardless ``` ```of whether it was active or not, so stopping a watcher explicitly before ``` ```freeing it is often a good idea. ``` ```.Sp ``` ```While stopped (and not pending) the watcher is essentially in the ``` ```initialised state, that is, it can be reused, moved, modified in any way ``` ```you wish (but when you trash the memory block, you need to \f(CW\*(C`ev_TYPE_init\*(C'\fR ``` ```it again). ``` ```.SS "\s-1WATCHER PRIORITY MODELS\s0" ``` ```.IX Subsection "WATCHER PRIORITY MODELS" ``` ```Many event loops support \fIwatcher priorities\fR, which are usually small ``` ```integers that influence the ordering of event callback invocation ``` ```between watchers in some way, all else being equal. ``` ```.PP ``` ```In libev, Watcher priorities can be set using \f(CW\*(C`ev_set_priority\*(C'\fR. See its ``` ```description for the more technical details such as the actual priority ``` ```range. ``` ```.PP ``` ```There are two common ways how these these priorities are being interpreted ``` ```by event loops: ``` ```.PP ``` ```In the more common lock-out model, higher priorities \*(L"lock out\*(R" invocation ``` ```of lower priority watchers, which means as long as higher priority ``` ```watchers receive events, lower priority watchers are not being invoked. ``` ```.PP ``` ```The less common only-for-ordering model uses priorities solely to order ``` ```callback invocation within a single event loop iteration: Higher priority ``` ```watchers are invoked before lower priority ones, but they all get invoked ``` ```before polling for new events. ``` ```.PP ``` ```Libev uses the second (only-for-ordering) model for all its watchers ``` ```except for idle watchers (which use the lock-out model). ``` ```.PP ``` ```The rationale behind this is that implementing the lock-out model for ``` ```watchers is not well supported by most kernel interfaces, and most event ``` ```libraries will just poll for the same events again and again as long as ``` ```their callbacks have not been executed, which is very inefficient in the ``` ```common case of one high-priority watcher locking out a mass of lower ``` ```priority ones. ``` ```.PP ``` ```Static (ordering) priorities are most useful when you have two or more ``` ```watchers handling the same resource: a typical usage example is having an ``` ```\&\f(CW\*(C`ev_io\*(C'\fR watcher to receive data, and an associated \f(CW\*(C`ev_timer\*(C'\fR to handle ``` ```timeouts. Under load, data might be received while the program handles ``` ```other jobs, but since timers normally get invoked first, the timeout ``` ```handler will be executed before checking for data. In that case, giving ``` ```the timer a lower priority than the I/O watcher ensures that I/O will be ``` ```handled first even under adverse conditions (which is usually, but not ``` ```always, what you want). ``` ```.PP ``` ```Since idle watchers use the \*(L"lock-out\*(R" model, meaning that idle watchers ``` ```will only be executed when no same or higher priority watchers have ``` ```received events, they can be used to implement the \*(L"lock-out\*(R" model when ``` ```required. ``` ```.PP ``` ```For example, to emulate how many other event libraries handle priorities, ``` ```you can associate an \f(CW\*(C`ev_idle\*(C'\fR watcher to each such watcher, and in ``` ```the normal watcher callback, you just start the idle watcher. The real ``` ```processing is done in the idle watcher callback. This causes libev to ``` ```continuously poll and process kernel event data for the watcher, but when ``` ```the lock-out case is known to be rare (which in turn is rare :), this is ``` ```workable. ``` ```.PP ``` ```Usually, however, the lock-out model implemented that way will perform ``` ```miserably under the type of load it was designed to handle. In that case, ``` ```it might be preferable to stop the real watcher before starting the ``` ```idle watcher, so the kernel will not have to process the event in case ``` ```the actual processing will be delayed for considerable time. ``` ```.PP ``` ```Here is an example of an I/O watcher that should run at a strictly lower ``` ```priority than the default, and which should only process data when no ``` ```other events are pending: ``` ```.PP ``` ```.Vb 2 ``` ```\& ev_idle idle; // actual processing watcher ``` ```\& ev_io io; // actual event watcher ``` ```\& ``` ```\& static void ``` ```\& io_cb (EV_P_ ev_io *w, int revents) ``` ```\& { ``` ```\& // stop the I/O watcher, we received the event, but ``` ```\& // are not yet ready to handle it. ``` ```\& ev_io_stop (EV_A_ w); ``` ```\& ``` ```\& // start the idle watcher to handle the actual event. ``` ```\& // it will not be executed as long as other watchers ``` ```\& // with the default priority are receiving events. ``` ```\& ev_idle_start (EV_A_ &idle); ``` ```\& } ``` ```\& ``` ```\& static void ``` ```\& idle_cb (EV_P_ ev_idle *w, int revents) ``` ```\& { ``` ```\& // actual processing ``` ```\& read (STDIN_FILENO, ...); ``` ```\& ``` ```\& // have to start the I/O watcher again, as ``` ```\& // we have handled the event ``` ```\& ev_io_start (EV_P_ &io); ``` ```\& } ``` ```\& ``` ```\& // initialisation ``` ```\& ev_idle_init (&idle, idle_cb); ``` ```\& ev_io_init (&io, io_cb, STDIN_FILENO, EV_READ); ``` ```\& ev_io_start (EV_DEFAULT_ &io); ``` ```.Ve ``` ```.PP ``` ```In the \*(L"real\*(R" world, it might also be beneficial to start a timer, so that ``` ```low-priority connections can not be locked out forever under load. This ``` ```enables your program to keep a lower latency for important connections ``` ```during short periods of high load, while not completely locking out less ``` ```important ones. ``` ```.SH "WATCHER TYPES" ``` ```.IX Header "WATCHER TYPES" ``` ```This section describes each watcher in detail, but will not repeat ``` ```information given in the last section. Any initialisation/set macros, ``` ```functions and members specific to the watcher type are explained. ``` ```.PP ``` ```Members are additionally marked with either \fI[read\-only]\fR, meaning that, ``` ```while the watcher is active, you can look at the member and expect some ``` ```sensible content, but you must not modify it (you can modify it while the ``` ```watcher is stopped to your hearts content), or \fI[read\-write]\fR, which ``` ```means you can expect it to have some sensible content while the watcher ``` ```is active, but you can also modify it. Modifying it may not do something ``` ```sensible or take immediate effect (or do anything at all), but libev will ``` ```not crash or malfunction in any way. ``` ```.ie n .SS """ev_io"" \- is this file descriptor readable or writable?" ``` ```.el .SS "\f(CWev_io\fP \- is this file descriptor readable or writable?" ``` ```.IX Subsection "ev_io - is this file descriptor readable or writable?" ``` ```I/O watchers check whether a file descriptor is readable or writable ``` ```in each iteration of the event loop, or, more precisely, when reading ``` ```would not block the process and writing would at least be able to write ``` ```some data. This behaviour is called level-triggering because you keep ``` ```receiving events as long as the condition persists. Remember you can stop ``` ```the watcher if you don't want to act on the event and neither want to ``` ```receive future events. ``` ```.PP ``` ```In general you can register as many read and/or write event watchers per ``` ```fd as you want (as long as you don't confuse yourself). Setting all file ``` ```descriptors to non-blocking mode is also usually a good idea (but not ``` ```required if you know what you are doing). ``` ```.PP ``` ```Another thing you have to watch out for is that it is quite easy to ``` ```receive \*(L"spurious\*(R" readiness notifications, that is, your callback might ``` ```be called with \f(CW\*(C`EV_READ\*(C'\fR but a subsequent \f(CW\*(C`read\*(C'\fR(2) will actually block ``` ```because there is no data. It is very easy to get into this situation even ``` ```with a relatively standard program structure. Thus it is best to always ``` ```use non-blocking I/O: An extra \f(CW\*(C`read\*(C'\fR(2) returning \f(CW\*(C`EAGAIN\*(C'\fR is far ``` ```preferable to a program hanging until some data arrives. ``` ```.PP ``` ```If you cannot run the fd in non-blocking mode (for example you should ``` ```not play around with an Xlib connection), then you have to separately ``` ```re-test whether a file descriptor is really ready with a known-to-be good ``` ```interface such as poll (fortunately in the case of Xlib, it already does ``` ```this on its own, so its quite safe to use). Some people additionally ``` ```use \f(CW\*(C`SIGALRM\*(C'\fR and an interval timer, just to be sure you won't block ``` ```indefinitely. ``` ```.PP ``` ```But really, best use non-blocking mode. ``` ```.PP ``` ```\fIThe special problem of disappearing file descriptors\fR ``` ```.IX Subsection "The special problem of disappearing file descriptors" ``` ```.PP ``` ```Some backends (e.g. kqueue, epoll) need to be told about closing a file ``` ```descriptor (either due to calling \f(CW\*(C`close\*(C'\fR explicitly or any other means, ``` ```such as \f(CW\*(C`dup2\*(C'\fR). The reason is that you register interest in some file ``` ```descriptor, but when it goes away, the operating system will silently drop ``` ```this interest. If another file descriptor with the same number then is ``` ```registered with libev, there is no efficient way to see that this is, in ``` ```fact, a different file descriptor. ``` ```.PP ``` ```To avoid having to explicitly tell libev about such cases, libev follows ``` ```the following policy: Each time \f(CW\*(C`ev_io_set\*(C'\fR is being called, libev ``` ```will assume that this is potentially a new file descriptor, otherwise ``` ```it is assumed that the file descriptor stays the same. That means that ``` ```you \fIhave\fR to call \f(CW\*(C`ev_io_set\*(C'\fR (or \f(CW\*(C`ev_io_init\*(C'\fR) when you change the ``` ```descriptor even if the file descriptor number itself did not change. ``` ```.PP ``` ```This is how one would do it normally anyway, the important point is that ``` ```the libev application should not optimise around libev but should leave ``` ```optimisations to libev. ``` ```.PP ``` ```\fIThe special problem of dup'ed file descriptors\fR ``` ```.IX Subsection "The special problem of dup'ed file descriptors" ``` ```.PP ``` ```Some backends (e.g. epoll), cannot register events for file descriptors, ``` ```but only events for the underlying file descriptions. That means when you ``` ```have \f(CW\*(C`dup ()\*(C'\fR'ed file descriptors or weirder constellations, and register ``` ```events for them, only one file descriptor might actually receive events. ``` ```.PP ``` ```There is no workaround possible except not registering events ``` ```for potentially \f(CW\*(C`dup ()\*(C'\fR'ed file descriptors, or to resort to ``` ```\&\f(CW\*(C`EVBACKEND_SELECT\*(C'\fR or \f(CW\*(C`EVBACKEND_POLL\*(C'\fR. ``` ```.PP ``` ```\fIThe special problem of files\fR ``` ```.IX Subsection "The special problem of files" ``` ```.PP ``` ```Many people try to use \f(CW\*(C`select\*(C'\fR (or libev) on file descriptors ``` ```representing files, and expect it to become ready when their program ``` ```doesn't block on disk accesses (which can take a long time on their own). ``` ```.PP ``` ```However, this cannot ever work in the \*(L"expected\*(R" way \- you get a readiness ``` ```notification as soon as the kernel knows whether and how much data is ``` ```there, and in the case of open files, that's always the case, so you ``` ```always get a readiness notification instantly, and your read (or possibly ``` ```write) will still block on the disk I/O. ``` ```.PP ``` ```Another way to view it is that in the case of sockets, pipes, character ``` ```devices and so on, there is another party (the sender) that delivers data ``` ```on its own, but in the case of files, there is no such thing: the disk ``` ```will not send data on its own, simply because it doesn't know what you ``` ```wish to read \- you would first have to request some data. ``` ```.PP ``` ```Since files are typically not-so-well supported by advanced notification ``` ```mechanism, libev tries hard to emulate \s-1POSIX\s0 behaviour with respect ``` ```to files, even though you should not use it. The reason for this is ``` ```convenience: sometimes you want to watch \s-1STDIN\s0 or \s-1STDOUT,\s0 which is ``` ```usually a tty, often a pipe, but also sometimes files or special devices ``` ```(for example, \f(CW\*(C`epoll\*(C'\fR on Linux works with \fI/dev/random\fR but not with ``` ```\&\fI/dev/urandom\fR), and even though the file might better be served with ``` ```asynchronous I/O instead of with non-blocking I/O, it is still useful when ``` ```it \*(L"just works\*(R" instead of freezing. ``` ```.PP ``` ```So avoid file descriptors pointing to files when you know it (e.g. use ``` ```libeio), but use them when it is convenient, e.g. for \s-1STDIN/STDOUT,\s0 or ``` ```when you rarely read from a file instead of from a socket, and want to ``` ```reuse the same code path. ``` ```.PP ``` ```\fIThe special problem of fork\fR ``` ```.IX Subsection "The special problem of fork" ``` ```.PP ``` ```Some backends (epoll, kqueue) do not support \f(CW\*(C`fork ()\*(C'\fR at all or exhibit ``` ```useless behaviour. Libev fully supports fork, but needs to be told about ``` ```it in the child if you want to continue to use it in the child. ``` ```.PP ``` ```To support fork in your child processes, you have to call \f(CW\*(C`ev_loop_fork ``` ```()\*(C'\fR after a fork in the child, enable \f(CW\*(C`EVFLAG_FORKCHECK\*(C'\fR, or resort to ``` ```\&\f(CW\*(C`EVBACKEND_SELECT\*(C'\fR or \f(CW\*(C`EVBACKEND_POLL\*(C'\fR. ``` ```.PP ``` ```\fIThe special problem of \s-1SIGPIPE\s0\fR ``` ```.IX Subsection "The special problem of SIGPIPE" ``` ```.PP ``` ```While not really specific to libev, it is easy to forget about \f(CW\*(C`SIGPIPE\*(C'\fR: ``` ```when writing to a pipe whose other end has been closed, your program gets ``` ```sent a \s-1SIGPIPE,\s0 which, by default, aborts your program. For most programs ``` ```this is sensible behaviour, for daemons, this is usually undesirable. ``` ```.PP ``` ```So when you encounter spurious, unexplained daemon exits, make sure you ``` ```ignore \s-1SIGPIPE \s0(and maybe make sure you log the exit status of your daemon ``` ```somewhere, as that would have given you a big clue). ``` ```.PP ``` ```\fIThe special problem of \fIaccept()\fIing when you can't\fR ``` ```.IX Subsection "The special problem of accept()ing when you can't" ``` ```.PP ``` ```Many implementations of the \s-1POSIX \s0\f(CW\*(C`accept\*(C'\fR function (for example, ``` ```found in post\-2004 Linux) have the peculiar behaviour of not removing a ``` ```connection from the pending queue in all error cases. ``` ```.PP ``` ```For example, larger servers often run out of file descriptors (because ``` ```of resource limits), causing \f(CW\*(C`accept\*(C'\fR to fail with \f(CW\*(C`ENFILE\*(C'\fR but not ``` ```rejecting the connection, leading to libev signalling readiness on ``` ```the next iteration again (the connection still exists after all), and ``` ```typically causing the program to loop at 100% \s-1CPU\s0 usage. ``` ```.PP ``` ```Unfortunately, the set of errors that cause this issue differs between ``` ```operating systems, there is usually little the app can do to remedy the ``` ```situation, and no known thread-safe method of removing the connection to ``` ```cope with overload is known (to me). ``` ```.PP ``` ```One of the easiest ways to handle this situation is to just ignore it ``` ```\&\- when the program encounters an overload, it will just loop until the ``` ```situation is over. While this is a form of busy waiting, no \s-1OS\s0 offers an ``` ```event-based way to handle this situation, so it's the best one can do. ``` ```.PP ``` ```A better way to handle the situation is to log any errors other than ``` ```\&\f(CW\*(C`EAGAIN\*(C'\fR and \f(CW\*(C`EWOULDBLOCK\*(C'\fR, making sure not to flood the log with such ``` ```messages, and continue as usual, which at least gives the user an idea of ``` ```what could be wrong (\*(L"raise the ulimit!\*(R"). For extra points one could stop ``` ```the \f(CW\*(C`ev_io\*(C'\fR watcher on the listening fd \*(L"for a while\*(R", which reduces \s-1CPU\s0 ``` ```usage. ``` ```.PP ``` ```If your program is single-threaded, then you could also keep a dummy file ``` ```descriptor for overload situations (e.g. by opening \fI/dev/null\fR), and ``` ```when you run into \f(CW\*(C`ENFILE\*(C'\fR or \f(CW\*(C`EMFILE\*(C'\fR, close it, run \f(CW\*(C`accept\*(C'\fR, ``` ```close that fd, and create a new dummy fd. This will gracefully refuse ``` ```clients under typical overload conditions. ``` ```.PP ``` ```The last way to handle it is to simply log the error and \f(CW\*(C`exit\*(C'\fR, as ``` ```is often done with \f(CW\*(C`malloc\*(C'\fR failures, but this results in an easy ``` ```opportunity for a DoS attack. ``` ```.PP ``` ```\fIWatcher-Specific Functions\fR ``` ```.IX Subsection "Watcher-Specific Functions" ``` ```.IP "ev_io_init (ev_io *, callback, int fd, int events)" 4 ``` ```.IX Item "ev_io_init (ev_io *, callback, int fd, int events)" ``` ```.PD 0 ``` ```.IP "ev_io_set (ev_io *, int fd, int events)" 4 ``` ```.IX Item "ev_io_set (ev_io *, int fd, int events)" ``` ```.PD ``` ```Configures an \f(CW\*(C`ev_io\*(C'\fR watcher. The \f(CW\*(C`fd\*(C'\fR is the file descriptor to ``` ```receive events for and \f(CW\*(C`events\*(C'\fR is either \f(CW\*(C`EV_READ\*(C'\fR, \f(CW\*(C`EV_WRITE\*(C'\fR or ``` ```\&\f(CW\*(C`EV_READ | EV_WRITE\*(C'\fR, to express the desire to receive the given events. ``` ```.IP "int fd [read\-only]" 4 ``` ```.IX Item "int fd [read-only]" ``` ```The file descriptor being watched. ``` ```.IP "int events [read\-only]" 4 ``` ```.IX Item "int events [read-only]" ``` ```The events being watched. ``` ```.PP ``` ```\fIExamples\fR ``` ```.IX Subsection "Examples" ``` ```.PP ``` ```Example: Call \f(CW\*(C`stdin_readable_cb\*(C'\fR when \s-1STDIN_FILENO\s0 has become, well ``` ```readable, but only once. Since it is likely line-buffered, you could ``` ```attempt to read a whole line in the callback. ``` ```.PP ``` ```.Vb 6 ``` ```\& static void ``` ```\& stdin_readable_cb (struct ev_loop *loop, ev_io *w, int revents) ``` ```\& { ``` ```\& ev_io_stop (loop, w); ``` ```\& .. read from stdin here (or from w\->fd) and handle any I/O errors ``` ```\& } ``` ```\& ``` ```\& ... ``` ```\& struct ev_loop *loop = ev_default_init (0); ``` ```\& ev_io stdin_readable; ``` ```\& ev_io_init (&stdin_readable, stdin_readable_cb, STDIN_FILENO, EV_READ); ``` ```\& ev_io_start (loop, &stdin_readable); ``` ```\& ev_run (loop, 0); ``` ```.Ve ``` ```.ie n .SS """ev_timer"" \- relative and optionally repeating timeouts" ``` ```.el .SS "\f(CWev_timer\fP \- relative and optionally repeating timeouts" ``` ```.IX Subsection "ev_timer - relative and optionally repeating timeouts" ``` ```Timer watchers are simple relative timers that generate an event after a ``` ```given time, and optionally repeating in regular intervals after that. ``` ```.PP ``` ```The timers are based on real time, that is, if you register an event that ``` ```times out after an hour and you reset your system clock to January last ``` ```year, it will still time out after (roughly) one hour. \*(L"Roughly\*(R" because ``` ```detecting time jumps is hard, and some inaccuracies are unavoidable (the ``` ```monotonic clock option helps a lot here). ``` ```.PP ``` ```The callback is guaranteed to be invoked only \fIafter\fR its timeout has ``` ```passed (not \fIat\fR, so on systems with very low-resolution clocks this ``` ```might introduce a small delay, see \*(L"the special problem of being too ``` ```early\*(R", below). If multiple timers become ready during the same loop ``` ```iteration then the ones with earlier time-out values are invoked before ``` ```ones of the same priority with later time-out values (but this is no ``` ```longer true when a callback calls \f(CW\*(C`ev_run\*(C'\fR recursively). ``` ```.PP ``` ```\fIBe smart about timeouts\fR ``` ```.IX Subsection "Be smart about timeouts" ``` ```.PP ``` ```Many real-world problems involve some kind of timeout, usually for error ``` ```recovery. A typical example is an \s-1HTTP\s0 request \- if the other side hangs, ``` ```you want to raise some error after a while. ``` ```.PP ``` ```What follows are some ways to handle this problem, from obvious and ``` ```inefficient to smart and efficient. ``` ```.PP ``` ```In the following, a 60 second activity timeout is assumed \- a timeout that ``` ```gets reset to 60 seconds each time there is activity (e.g. each time some ``` ```data or other life sign was received). ``` ```.IP "1. Use a timer and stop, reinitialise and start it on activity." 4 ``` ```.IX Item "1. Use a timer and stop, reinitialise and start it on activity." ``` ```This is the most obvious, but not the most simple way: In the beginning, ``` ```start the watcher: ``` ```.Sp ``` ```.Vb 2 ``` ```\& ev_timer_init (timer, callback, 60., 0.); ``` ```\& ev_timer_start (loop, timer); ``` ```.Ve ``` ```.Sp ``` ```Then, each time there is some activity, \f(CW\*(C`ev_timer_stop\*(C'\fR it, initialise it ``` ```and start it again: ``` ```.Sp ``` ```.Vb 3 ``` ```\& ev_timer_stop (loop, timer); ``` ```\& ev_timer_set (timer, 60., 0.); ``` ```\& ev_timer_start (loop, timer); ``` ```.Ve ``` ```.Sp ``` ```This is relatively simple to implement, but means that each time there is ``` ```some activity, libev will first have to remove the timer from its internal ``` ```data structure and then add it again. Libev tries to be fast, but it's ``` ```still not a constant-time operation. ``` ```.ie n .IP "2. Use a timer and re-start it with ""ev_timer_again"" inactivity." 4 ``` ```.el .IP "2. Use a timer and re-start it with \f(CWev_timer_again\fR inactivity." 4 ``` ```.IX Item "2. Use a timer and re-start it with ev_timer_again inactivity." ``` ```This is the easiest way, and involves using \f(CW\*(C`ev_timer_again\*(C'\fR instead of ``` ```\&\f(CW\*(C`ev_timer_start\*(C'\fR. ``` ```.Sp ``` ```To implement this, configure an \f(CW\*(C`ev_timer\*(C'\fR with a \f(CW\*(C`repeat\*(C'\fR value ``` ```of \f(CW60\fR and then call \f(CW\*(C`ev_timer_again\*(C'\fR at start and each time you ``` ```successfully read or write some data. If you go into an idle state where ``` ```you do not expect data to travel on the socket, you can \f(CW\*(C`ev_timer_stop\*(C'\fR ``` ```the timer, and \f(CW\*(C`ev_timer_again\*(C'\fR will automatically restart it if need be. ``` ```.Sp ``` ```That means you can ignore both the \f(CW\*(C`ev_timer_start\*(C'\fR function and the ``` ```\&\f(CW\*(C`after\*(C'\fR argument to \f(CW\*(C`ev_timer_set\*(C'\fR, and only ever use the \f(CW\*(C`repeat\*(C'\fR ``` ```member and \f(CW\*(C`ev_timer_again\*(C'\fR. ``` ```.Sp ``` ```At start: ``` ```.Sp ``` ```.Vb 3 ``` ```\& ev_init (timer, callback); ``` ```\& timer\->repeat = 60.; ``` ```\& ev_timer_again (loop, timer); ``` ```.Ve ``` ```.Sp ``` ```Each time there is some activity: ``` ```.Sp ``` ```.Vb 1 ``` ```\& ev_timer_again (loop, timer); ``` ```.Ve ``` ```.Sp ``` ```It is even possible to change the time-out on the fly, regardless of ``` ```whether the watcher is active or not: ``` ```.Sp ``` ```.Vb 2 ``` ```\& timer\->repeat = 30.; ``` ```\& ev_timer_again (loop, timer); ``` ```.Ve ``` ```.Sp ``` ```This is slightly more efficient then stopping/starting the timer each time ``` ```you want to modify its timeout value, as libev does not have to completely ``` ```remove and re-insert the timer from/into its internal data structure. ``` ```.Sp ``` ```It is, however, even simpler than the \*(L"obvious\*(R" way to do it. ``` ```.IP "3. Let the timer time out, but then re-arm it as required." 4 ``` ```.IX Item "3. Let the timer time out, but then re-arm it as required." ``` ```This method is more tricky, but usually most efficient: Most timeouts are ``` ```relatively long compared to the intervals between other activity \- in ``` ```our example, within 60 seconds, there are usually many I/O events with ``` ```associated activity resets. ``` ```.Sp ``` ```In this case, it would be more efficient to leave the \f(CW\*(C`ev_timer\*(C'\fR alone, ``` ```but remember the time of last activity, and check for a real timeout only ``` ```within the callback: ``` ```.Sp ``` ```.Vb 3 ``` ```\& ev_tstamp timeout = 60.; ``` ```\& ev_tstamp last_activity; // time of last activity ``` ```\& ev_timer timer; ``` ```\& ``` ```\& static void ``` ```\& callback (EV_P_ ev_timer *w, int revents) ``` ```\& { ``` ```\& // calculate when the timeout would happen ``` ```\& ev_tstamp after = last_activity \- ev_now (EV_A) + timeout; ``` ```\& ``` ```\& // if negative, it means we the timeout already occurred ``` ```\& if (after < 0.) ``` ```\& { ``` ```\& // timeout occurred, take action ``` ```\& } ``` ```\& else ``` ```\& { ``` ```\& // callback was invoked, but there was some recent ``` ```\& // activity. simply restart the timer to time out ``` ```\& // after "after" seconds, which is the earliest time ``` ```\& // the timeout can occur. ``` ```\& ev_timer_set (w, after, 0.); ``` ```\& ev_timer_start (EV_A_ w); ``` ```\& } ``` ```\& } ``` ```.Ve ``` ```.Sp ``` ```To summarise the callback: first calculate in how many seconds the ``` ```timeout will occur (by calculating the absolute time when it would occur, ``` ```\&\f(CW\*(C`last_activity + timeout\*(C'\fR, and subtracting the current time, \f(CW\*(C`ev_now ``` ```(EV_A)\*(C'\fR from that). ``` ```.Sp ``` ```If this value is negative, then we are already past the timeout, i.e. we ``` ```timed out, and need to do whatever is needed in this case. ``` ```.Sp ``` ```Otherwise, we now the earliest time at which the timeout would trigger, ``` ```and simply start the timer with this timeout value. ``` ```.Sp ``` ```In other words, each time the callback is invoked it will check whether ``` ```the timeout occurred. If not, it will simply reschedule itself to check ``` ```again at the earliest time it could time out. Rinse. Repeat. ``` ```.Sp ``` ```This scheme causes more callback invocations (about one every 60 seconds ``` ```minus half the average time between activity), but virtually no calls to ``` ```libev to change the timeout. ``` ```.Sp ``` ```To start the machinery, simply initialise the watcher and set ``` ```\&\f(CW\*(C`last_activity\*(C'\fR to the current time (meaning there was some activity just ``` ```now), then call the callback, which will \*(L"do the right thing\*(R" and start ``` ```the timer: ``` ```.Sp ``` ```.Vb 3 ``` ```\& last_activity = ev_now (EV_A); ``` ```\& ev_init (&timer, callback); ``` ```\& callback (EV_A_ &timer, 0); ``` ```.Ve ``` ```.Sp ``` ```When there is some activity, simply store the current time in ``` ```\&\f(CW\*(C`last_activity\*(C'\fR, no libev calls at all: ``` ```.Sp ``` ```.Vb 2 ``` ```\& if (activity detected) ``` ```\& last_activity = ev_now (EV_A); ``` ```.Ve ``` ```.Sp ``` ```When your timeout value changes, then the timeout can be changed by simply ``` ```providing a new value, stopping the timer and calling the callback, which ``` ```will again do the right thing (for example, time out immediately :). ``` ```.Sp ``` ```.Vb 3 ``` ```\& timeout = new_value; ``` ```\& ev_timer_stop (EV_A_ &timer); ``` ```\& callback (EV_A_ &timer, 0); ``` ```.Ve ``` ```.Sp ``` ```This technique is slightly more complex, but in most cases where the ``` ```time-out is unlikely to be triggered, much more efficient. ``` ```.IP "4. Wee, just use a double-linked list for your timeouts." 4 ``` ```.IX Item "4. Wee, just use a double-linked list for your timeouts." ``` ```If there is not one request, but many thousands (millions...), all ``` ```employing some kind of timeout with the same timeout value, then one can ``` ```do even better: ``` ```.Sp ``` ```When starting the timeout, calculate the timeout value and put the timeout ``` ```at the \fIend\fR of the list. ``` ```.Sp ``` ```Then use an \f(CW\*(C`ev_timer\*(C'\fR to fire when the timeout at the \fIbeginning\fR of ``` ```the list is expected to fire (for example, using the technique #3). ``` ```.Sp ``` ```When there is some activity, remove the timer from the list, recalculate ``` ```the timeout, append it to the end of the list again, and make sure to ``` ```update the \f(CW\*(C`ev_timer\*(C'\fR if it was taken from the beginning of the list. ``` ```.Sp ``` ```This way, one can manage an unlimited number of timeouts in O(1) time for ``` ```starting, stopping and updating the timers, at the expense of a major ``` ```complication, and having to use a constant timeout. The constant timeout ``` ```ensures that the list stays sorted. ``` ```.PP ``` ```So which method the best? ``` ```.PP ``` ```Method #2 is a simple no-brain-required solution that is adequate in most ``` ```situations. Method #3 requires a bit more thinking, but handles many cases ``` ```better, and isn't very complicated either. In most case, choosing either ``` ```one is fine, with #3 being better in typical situations. ``` ```.PP ``` ```Method #1 is almost always a bad idea, and buys you nothing. Method #4 is ``` ```rather complicated, but extremely efficient, something that really pays ``` ```off after the first million or so of active timers, i.e. it's usually ``` ```overkill :) ``` ```.PP ``` ```\fIThe special problem of being too early\fR ``` ```.IX Subsection "The special problem of being too early" ``` ```.PP ``` ```If you ask a timer to call your callback after three seconds, then ``` ```you expect it to be invoked after three seconds \- but of course, this ``` ```cannot be guaranteed to infinite precision. Less obviously, it cannot be ``` ```guaranteed to any precision by libev \- imagine somebody suspending the ``` ```process with a \s-1STOP\s0 signal for a few hours for example. ``` ```.PP ``` ```So, libev tries to invoke your callback as soon as possible \fIafter\fR the ``` ```delay has occurred, but cannot guarantee this. ``` ```.PP ``` ```A less obvious failure mode is calling your callback too early: many event ``` ```loops compare timestamps with a \*(L"elapsed delay >= requested delay\*(R", but ``` ```this can cause your callback to be invoked much earlier than you would ``` ```expect. ``` ```.PP ``` ```To see why, imagine a system with a clock that only offers full second ``` ```resolution (think windows if you can't come up with a broken enough \s-1OS\s0 ``` ```yourself). If you schedule a one-second timer at the time 500.9, then the ``` ```event loop will schedule your timeout to elapse at a system time of 500 ``` ```(500.9 truncated to the resolution) + 1, or 501. ``` ```.PP ``` ```If an event library looks at the timeout 0.1s later, it will see \*(L"501 >= ``` ```501\*(R" and invoke the callback 0.1s after it was started, even though a ``` ```one-second delay was requested \- this is being \*(L"too early\*(R", despite best ``` ```intentions. ``` ```.PP ``` ```This is the reason why libev will never invoke the callback if the elapsed ``` ```delay equals the requested delay, but only when the elapsed delay is ``` ```larger than the requested delay. In the example above, libev would only invoke ``` ```the callback at system time 502, or 1.1s after the timer was started. ``` ```.PP ``` ```So, while libev cannot guarantee that your callback will be invoked ``` ```exactly when requested, it \fIcan\fR and \fIdoes\fR guarantee that the requested ``` ```delay has actually elapsed, or in other words, it always errs on the \*(L"too ``` ```late\*(R" side of things. ``` ```.PP ``` ```\fIThe special problem of time updates\fR ``` ```.IX Subsection "The special problem of time updates" ``` ```.PP ``` ```Establishing the current time is a costly operation (it usually takes ``` ```at least one system call): \s-1EV\s0 therefore updates its idea of the current ``` ```time only before and after \f(CW\*(C`ev_run\*(C'\fR collects new events, which causes a ``` ```growing difference between \f(CW\*(C`ev_now ()\*(C'\fR and \f(CW\*(C`ev_time ()\*(C'\fR when handling ``` ```lots of events in one iteration. ``` ```.PP ``` ```The relative timeouts are calculated relative to the \f(CW\*(C`ev_now ()\*(C'\fR ``` ```time. This is usually the right thing as this timestamp refers to the time ``` ```of the event triggering whatever timeout you are modifying/starting. If ``` ```you suspect event processing to be delayed and you \fIneed\fR to base the ``` ```timeout on the current time, use something like the following to adjust ``` ```for it: ``` ```.PP ``` ```.Vb 1 ``` ```\& ev_timer_set (&timer, after + (ev_time () \- ev_now ()), 0.); ``` ```.Ve ``` ```.PP ``` ```If the event loop is suspended for a long time, you can also force an ``` ```update of the time returned by \f(CW\*(C`ev_now ()\*(C'\fR by calling \f(CW\*(C`ev_now_update ``` ```()\*(C'\fR, although that will push the event time of all outstanding events ``` ```further into the future. ``` ```.PP ``` ```\fIThe special problem of unsynchronised clocks\fR ``` ```.IX Subsection "The special problem of unsynchronised clocks" ``` ```.PP ``` ```Modern systems have a variety of clocks \- libev itself uses the normal ``` ```\&\*(L"wall clock\*(R" clock and, if available, the monotonic clock (to avoid time ``` ```jumps). ``` ```.PP ``` ```Neither of these clocks is synchronised with each other or any other clock ``` ```on the system, so \f(CW\*(C`ev_time ()\*(C'\fR might return a considerably different time ``` ```than \f(CW\*(C`gettimeofday ()\*(C'\fR or \f(CW\*(C`time ()\*(C'\fR. On a GNU/Linux system, for example, ``` ```a call to \f(CW\*(C`gettimeofday\*(C'\fR might return a second count that is one higher ``` ```than a directly following call to \f(CW\*(C`time\*(C'\fR. ``` ```.PP ``` ```The moral of this is to only compare libev-related timestamps with ``` ```\&\f(CW\*(C`ev_time ()\*(C'\fR and \f(CW\*(C`ev_now ()\*(C'\fR, at least if you want better precision than ``` ```a second or so. ``` ```.PP ``` ```One more problem arises due to this lack of synchronisation: if libev uses ``` ```the system monotonic clock and you compare timestamps from \f(CW\*(C`ev_time\*(C'\fR ``` ```or \f(CW\*(C`ev_now\*(C'\fR from when you started your timer and when your callback is ``` ```invoked, you will find that sometimes the callback is a bit \*(L"early\*(R". ``` ```.PP ``` ```This is because \f(CW\*(C`ev_timer\*(C'\fRs work in real time, not wall clock time, so ``` ```libev makes sure your callback is not invoked before the delay happened, ``` ```\&\fImeasured according to the real time\fR, not the system clock. ``` ```.PP ``` ```If your timeouts are based on a physical timescale (e.g. \*(L"time out this ``` ```connection after 100 seconds\*(R") then this shouldn't bother you as it is ``` ```exactly the right behaviour. ``` ```.PP ``` ```If you want to compare wall clock/system timestamps to your timers, then ``` ```you need to use \f(CW\*(C`ev_periodic\*(C'\fRs, as these are based on the wall clock ``` ```time, where your comparisons will always generate correct results. ``` ```.PP ``` ```\fIThe special problems of suspended animation\fR ``` ```.IX Subsection "The special problems of suspended animation" ``` ```.PP ``` ```When you leave the server world it is quite customary to hit machines that ``` ```can suspend/hibernate \- what happens to the clocks during such a suspend? ``` ```.PP ``` ```Some quick tests made with a Linux 2.6.28 indicate that a suspend freezes ``` ```all processes, while the clocks (\f(CW\*(C`times\*(C'\fR, \f(CW\*(C`CLOCK_MONOTONIC\*(C'\fR) continue ``` ```to run until the system is suspended, but they will not advance while the ``` ```system is suspended. That means, on resume, it will be as if the program ``` ```was frozen for a few seconds, but the suspend time will not be counted ``` ```towards \f(CW\*(C`ev_timer\*(C'\fR when a monotonic clock source is used. The real time ``` ```clock advanced as expected, but if it is used as sole clocksource, then a ``` ```long suspend would be detected as a time jump by libev, and timers would ``` ```be adjusted accordingly. ``` ```.PP ``` ```I would not be surprised to see different behaviour in different between ``` ```operating systems, \s-1OS\s0 versions or even different hardware. ``` ```.PP ``` ```The other form of suspend (job control, or sending a \s-1SIGSTOP\s0) will see a ``` ```time jump in the monotonic clocks and the realtime clock. If the program ``` ```is suspended for a very long time, and monotonic clock sources are in use, ``` ```then you can expect \f(CW\*(C`ev_timer\*(C'\fRs to expire as the full suspension time ``` ```will be counted towards the timers. When no monotonic clock source is in ``` ```use, then libev will again assume a timejump and adjust accordingly. ``` ```.PP ``` ```It might be beneficial for this latter case to call \f(CW\*(C`ev_suspend\*(C'\fR ``` ```and \f(CW\*(C`ev_resume\*(C'\fR in code that handles \f(CW\*(C`SIGTSTP\*(C'\fR, to at least get ``` ```deterministic behaviour in this case (you can do nothing against ``` ```\&\f(CW\*(C`SIGSTOP\*(C'\fR). ``` ```.PP ``` ```\fIWatcher-Specific Functions and Data Members\fR ``` ```.IX Subsection "Watcher-Specific Functions and Data Members" ``` ```.IP "ev_timer_init (ev_timer *, callback, ev_tstamp after, ev_tstamp repeat)" 4 ``` ```.IX Item "ev_timer_init (ev_timer *, callback, ev_tstamp after, ev_tstamp repeat)" ``` ```.PD 0 ``` ```.IP "ev_timer_set (ev_timer *, ev_tstamp after, ev_tstamp repeat)" 4 ``` ```.IX Item "ev_timer_set (ev_timer *, ev_tstamp after, ev_tstamp repeat)" ``` ```.PD ``` ```Configure the timer to trigger after \f(CW\*(C`after\*(C'\fR seconds. If \f(CW\*(C`repeat\*(C'\fR ``` ```is \f(CW0.\fR, then it will automatically be stopped once the timeout is ``` ```reached. If it is positive, then the timer will automatically be ``` ```configured to trigger again \f(CW\*(C`repeat\*(C'\fR seconds later, again, and again, ``` ```until stopped manually. ``` ```.Sp ``` ```The timer itself will do a best-effort at avoiding drift, that is, if ``` ```you configure a timer to trigger every 10 seconds, then it will normally ``` ```trigger at exactly 10 second intervals. If, however, your program cannot ``` ```keep up with the timer (because it takes longer than those 10 seconds to ``` ```do stuff) the timer will not fire more than once per event loop iteration. ``` ```.IP "ev_timer_again (loop, ev_timer *)" 4 ``` ```.IX Item "ev_timer_again (loop, ev_timer *)" ``` ```This will act as if the timer timed out, and restarts it again if it is ``` ```repeating. It basically works like calling \f(CW\*(C`ev_timer_stop\*(C'\fR, updating the ``` ```timeout to the \f(CW\*(C`repeat\*(C'\fR value and calling \f(CW\*(C`ev_timer_start\*(C'\fR. ``` ```.Sp ``` ```The exact semantics are as in the following rules, all of which will be ``` ```applied to the watcher: ``` ```.RS 4 ``` ```.IP "If the timer is pending, the pending status is always cleared." 4 ``` ```.IX Item "If the timer is pending, the pending status is always cleared." ``` ```.PD 0 ``` ```.IP "If the timer is started but non-repeating, stop it (as if it timed out, without invoking it)." 4 ``` ```.IX Item "If the timer is started but non-repeating, stop it (as if it timed out, without invoking it)." ``` ```.ie n .IP "If the timer is repeating, make the ""repeat"" value the new timeout and start the timer, if necessary." 4 ``` ```.el .IP "If the timer is repeating, make the \f(CWrepeat\fR value the new timeout and start the timer, if necessary." 4 ``` ```.IX Item "If the timer is repeating, make the repeat value the new timeout and start the timer, if necessary." ``` ```.RE ``` ```.RS 4 ``` ```.PD ``` ```.Sp ``` ```This sounds a bit complicated, see \*(L"Be smart about timeouts\*(R", above, for a ``` ```usage example. ``` ```.RE ``` ```.IP "ev_tstamp ev_timer_remaining (loop, ev_timer *)" 4 ``` ```.IX Item "ev_tstamp ev_timer_remaining (loop, ev_timer *)" ``` ```Returns the remaining time until a timer fires. If the timer is active, ``` ```then this time is relative to the current event loop time, otherwise it's ``` ```the timeout value currently configured. ``` ```.Sp ``` ```That is, after an \f(CW\*(C`ev_timer_set (w, 5, 7)\*(C'\fR, \f(CW\*(C`ev_timer_remaining\*(C'\fR returns ``` ```\&\f(CW5\fR. When the timer is started and one second passes, \f(CW\*(C`ev_timer_remaining\*(C'\fR ``` ```will return \f(CW4\fR. When the timer expires and is restarted, it will return ``` ```roughly \f(CW7\fR (likely slightly less as callback invocation takes some time, ``` ```too), and so on. ``` ```.IP "ev_tstamp repeat [read\-write]" 4 ``` ```.IX Item "ev_tstamp repeat [read-write]" ``` ```The current \f(CW\*(C`repeat\*(C'\fR value. Will be used each time the watcher times out ``` ```or \f(CW\*(C`ev_timer_again\*(C'\fR is called, and determines the next timeout (if any), ``` ```which is also when any modifications are taken into account. ``` ```.PP ``` ```\fIExamples\fR ``` ```.IX Subsection "Examples" ``` ```.PP ``` ```Example: Create a timer that fires after 60 seconds. ``` ```.PP ``` ```.Vb 5 ``` ```\& static void ``` ```\& one_minute_cb (struct ev_loop *loop, ev_timer *w, int revents) ``` ```\& { ``` ```\& .. one minute over, w is actually stopped right here ``` ```\& } ``` ```\& ``` ```\& ev_timer mytimer; ``` ```\& ev_timer_init (&mytimer, one_minute_cb, 60., 0.); ``` ```\& ev_timer_start (loop, &mytimer); ``` ```.Ve ``` ```.PP ``` ```Example: Create a timeout timer that times out after 10 seconds of ``` ```inactivity. ``` ```.PP ``` ```.Vb 5 ``` ```\& static void ``` ```\& timeout_cb (struct ev_loop *loop, ev_timer *w, int revents) ``` ```\& { ``` ```\& .. ten seconds without any activity ``` ```\& } ``` ```\& ``` ```\& ev_timer mytimer; ``` ```\& ev_timer_init (&mytimer, timeout_cb, 0., 10.); /* note, only repeat used */ ``` ```\& ev_timer_again (&mytimer); /* start timer */ ``` ```\& ev_run (loop, 0); ``` ```\& ``` ```\& // and in some piece of code that gets executed on any "activity": ``` ```\& // reset the timeout to start ticking again at 10 seconds ``` ```\& ev_timer_again (&mytimer); ``` ```.Ve ``` ```.ie n .SS """ev_periodic"" \- to cron or not to cron?" ``` ```.el .SS "\f(CWev_periodic\fP \- to cron or not to cron?" ``` ```.IX Subsection "ev_periodic - to cron or not to cron?" ``` ```Periodic watchers are also timers of a kind, but they are very versatile ``` ```(and unfortunately a bit complex). ``` ```.PP ``` ```Unlike \f(CW\*(C`ev_timer\*(C'\fR, periodic watchers are not based on real time (or ``` ```relative time, the physical time that passes) but on wall clock time ``` ```(absolute time, the thing you can read on your calendar or clock). The ``` ```difference is that wall clock time can run faster or slower than real ``` ```time, and time jumps are not uncommon (e.g. when you adjust your ``` ```wrist-watch). ``` ```.PP ``` ```You can tell a periodic watcher to trigger after some specific point ``` ```in time: for example, if you tell a periodic watcher to trigger \*(L"in 10 ``` ```seconds\*(R" (by specifying e.g. \f(CW\*(C`ev_now () + 10.\*(C'\fR, that is, an absolute time ``` ```not a delay) and then reset your system clock to January of the previous ``` ```year, then it will take a year or more to trigger the event (unlike an ``` ```\&\f(CW\*(C`ev_timer\*(C'\fR, which would still trigger roughly 10 seconds after starting ``` ```it, as it uses a relative timeout). ``` ```.PP ``` ```\&\f(CW\*(C`ev_periodic\*(C'\fR watchers can also be used to implement vastly more complex ``` ```timers, such as triggering an event on each \*(L"midnight, local time\*(R", or ``` ```other complicated rules. This cannot be done with \f(CW\*(C`ev_timer\*(C'\fR watchers, as ``` ```those cannot react to time jumps. ``` ```.PP ``` ```As with timers, the callback is guaranteed to be invoked only when the ``` ```point in time where it is supposed to trigger has passed. If multiple ``` ```timers become ready during the same loop iteration then the ones with ``` ```earlier time-out values are invoked before ones with later time-out values ``` ```(but this is no longer true when a callback calls \f(CW\*(C`ev_run\*(C'\fR recursively). ``` ```.PP ``` ```\fIWatcher-Specific Functions and Data Members\fR ``` ```.IX Subsection "Watcher-Specific Functions and Data Members" ``` ```.IP "ev_periodic_init (ev_periodic *, callback, ev_tstamp offset, ev_tstamp interval, reschedule_cb)" 4 ``` ```.IX Item "ev_periodic_init (ev_periodic *, callback, ev_tstamp offset, ev_tstamp interval, reschedule_cb)" ``` ```.PD 0 ``` ```.IP "ev_periodic_set (ev_periodic *, ev_tstamp offset, ev_tstamp interval, reschedule_cb)" 4 ``` ```.IX Item "ev_periodic_set (ev_periodic *, ev_tstamp offset, ev_tstamp interval, reschedule_cb)" ``` ```.PD ``` ```Lots of arguments, let's sort it out... There are basically three modes of ``` ```operation, and we will explain them from simplest to most complex: ``` ```.RS 4 ``` ```.IP "\(bu" 4 ``` ```absolute timer (offset = absolute time, interval = 0, reschedule_cb = 0) ``` ```.Sp ``` ```In this configuration the watcher triggers an event after the wall clock ``` ```time \f(CW\*(C`offset\*(C'\fR has passed. It will not repeat and will not adjust when a ``` ```time jump occurs, that is, if it is to be run at January 1st 2011 then it ``` ```will be stopped and invoked when the system clock reaches or surpasses ``` ```this point in time. ``` ```.IP "\(bu" 4 ``` ```repeating interval timer (offset = offset within interval, interval > 0, reschedule_cb = 0) ``` ```.Sp ``` ```In this mode the watcher will always be scheduled to time out at the next ``` ```\&\f(CW\*(C`offset + N * interval\*(C'\fR time (for some integer N, which can also be ``` ```negative) and then repeat, regardless of any time jumps. The \f(CW\*(C`offset\*(C'\fR ``` ```argument is merely an offset into the \f(CW\*(C`interval\*(C'\fR periods. ``` ```.Sp ``` ```This can be used to create timers that do not drift with respect to the ``` ```system clock, for example, here is an \f(CW\*(C`ev_periodic\*(C'\fR that triggers each ``` ```hour, on the hour (with respect to \s-1UTC\s0): ``` ```.Sp ``` ```.Vb 1 ``` ```\& ev_periodic_set (&periodic, 0., 3600., 0); ``` ```.Ve ``` ```.Sp ``` ```This doesn't mean there will always be 3600 seconds in between triggers, ``` ```but only that the callback will be called when the system time shows a ``` ```full hour (\s-1UTC\s0), or more correctly, when the system time is evenly divisible ``` ```by 3600. ``` ```.Sp ``` ```Another way to think about it (for the mathematically inclined) is that ``` ```\&\f(CW\*(C`ev_periodic\*(C'\fR will try to run the callback in this mode at the next possible ``` ```time where \f(CW\*(C`time = offset (mod interval)\*(C'\fR, regardless of any time jumps. ``` ```.Sp ``` ```The \f(CW\*(C`interval\*(C'\fR \fI\s-1MUST\s0\fR be positive, and for numerical stability, the ``` ```interval value should be higher than \f(CW\*(C`1/8192\*(C'\fR (which is around 100 ``` ```microseconds) and \f(CW\*(C`offset\*(C'\fR should be higher than \f(CW0\fR and should have ``` ```at most a similar magnitude as the current time (say, within a factor of ``` ```ten). Typical values for offset are, in fact, \f(CW0\fR or something between ``` ```\&\f(CW0\fR and \f(CW\*(C`interval\*(C'\fR, which is also the recommended range. ``` ```.Sp ``` ```Note also that there is an upper limit to how often a timer can fire (\s-1CPU\s0 ``` ```speed for example), so if \f(CW\*(C`interval\*(C'\fR is very small then timing stability ``` ```will of course deteriorate. Libev itself tries to be exact to be about one ``` ```millisecond (if the \s-1OS\s0 supports it and the machine is fast enough). ``` ```.IP "\(bu" 4 ``` ```manual reschedule mode (offset ignored, interval ignored, reschedule_cb = callback) ``` ```.Sp ``` ```In this mode the values for \f(CW\*(C`interval\*(C'\fR and \f(CW\*(C`offset\*(C'\fR are both being ``` ```ignored. Instead, each time the periodic watcher gets scheduled, the ``` ```reschedule callback will be called with the watcher as first, and the ``` ```current time as second argument. ``` ```.Sp ``` ```\&\s-1NOTE: \s0\fIThis callback \s-1MUST NOT\s0 stop or destroy any periodic watcher, ever, ``` ```or make \s-1ANY\s0 other event loop modifications whatsoever, unless explicitly ``` ```allowed by documentation here\fR. ``` ```.Sp ``` ```If you need to stop it, return \f(CW\*(C`now + 1e30\*(C'\fR (or so, fudge fudge) and stop ``` ```it afterwards (e.g. by starting an \f(CW\*(C`ev_prepare\*(C'\fR watcher, which is the ``` ```only event loop modification you are allowed to do). ``` ```.Sp ``` ```The callback prototype is \f(CW\*(C`ev_tstamp (*reschedule_cb)(ev_periodic ``` ```*w, ev_tstamp now)\*(C'\fR, e.g.: ``` ```.Sp ``` ```.Vb 5 ``` ```\& static ev_tstamp ``` ```\& my_rescheduler (ev_periodic *w, ev_tstamp now) ``` ```\& { ``` ```\& return now + 60.; ``` ```\& } ``` ```.Ve ``` ```.Sp ``` ```It must return the next time to trigger, based on the passed time value ``` ```(that is, the lowest time value larger than to the second argument). It ``` ```will usually be called just before the callback will be triggered, but ``` ```might be called at other times, too. ``` ```.Sp ``` ```\&\s-1NOTE: \s0\fIThis callback must always return a time that is higher than or ``` ```equal to the passed \f(CI\*(C`now\*(C'\fI value\fR. ``` ```.Sp ``` ```This can be used to create very complex timers, such as a timer that ``` ```triggers on \*(L"next midnight, local time\*(R". To do this, you would calculate the ``` ```next midnight after \f(CW\*(C`now\*(C'\fR and return the timestamp value for this. How ``` ```you do this is, again, up to you (but it is not trivial, which is the main ``` ```reason I omitted it as an example). ``` ```.RE ``` ```.RS 4 ``` ```.RE ``` ```.IP "ev_periodic_again (loop, ev_periodic *)" 4 ``` ```.IX Item "ev_periodic_again (loop, ev_periodic *)" ``` ```Simply stops and restarts the periodic watcher again. This is only useful ``` ```when you changed some parameters or the reschedule callback would return ``` ```a different time than the last time it was called (e.g. in a crond like ``` ```program when the crontabs have changed). ``` ```.IP "ev_tstamp ev_periodic_at (ev_periodic *)" 4 ``` ```.IX Item "ev_tstamp ev_periodic_at (ev_periodic *)" ``` ```When active, returns the absolute time that the watcher is supposed ``` ```to trigger next. This is not the same as the \f(CW\*(C`offset\*(C'\fR argument to ``` ```\&\f(CW\*(C`ev_periodic_set\*(C'\fR, but indeed works even in interval and manual ``` ```rescheduling modes. ``` ```.IP "ev_tstamp offset [read\-write]" 4 ``` ```.IX Item "ev_tstamp offset [read-write]" ``` ```When repeating, this contains the offset value, otherwise this is the ``` ```absolute point in time (the \f(CW\*(C`offset\*(C'\fR value passed to \f(CW\*(C`ev_periodic_set\*(C'\fR, ``` ```although libev might modify this value for better numerical stability). ``` ```.Sp ``` ```Can be modified any time, but changes only take effect when the periodic ``` ```timer fires or \f(CW\*(C`ev_periodic_again\*(C'\fR is being called. ``` ```.IP "ev_tstamp interval [read\-write]" 4 ``` ```.IX Item "ev_tstamp interval [read-write]" ``` ```The current interval value. Can be modified any time, but changes only ``` ```take effect when the periodic timer fires or \f(CW\*(C`ev_periodic_again\*(C'\fR is being ``` ```called. ``` ```.IP "ev_tstamp (*reschedule_cb)(ev_periodic *w, ev_tstamp now) [read\-write]" 4 ``` ```.IX Item "ev_tstamp (*reschedule_cb)(ev_periodic *w, ev_tstamp now) [read-write]" ``` ```The current reschedule callback, or \f(CW0\fR, if this functionality is ``` ```switched off. Can be changed any time, but changes only take effect when ``` ```the periodic timer fires or \f(CW\*(C`ev_periodic_again\*(C'\fR is being called. ``` ```.PP ``` ```\fIExamples\fR ``` ```.IX Subsection "Examples" ``` ```.PP ``` ```Example: Call a callback every hour, or, more precisely, whenever the ``` ```system time is divisible by 3600. The callback invocation times have ``` ```potentially a lot of jitter, but good long-term stability. ``` ```.PP ``` ```.Vb 5 ``` ```\& static void ``` ```\& clock_cb (struct ev_loop *loop, ev_periodic *w, int revents) ``` ```\& { ``` ```\& ... its now a full hour (UTC, or TAI or whatever your clock follows) ``` ```\& } ``` ```\& ``` ```\& ev_periodic hourly_tick; ``` ```\& ev_periodic_init (&hourly_tick, clock_cb, 0., 3600., 0); ``` ```\& ev_periodic_start (loop, &hourly_tick); ``` ```.Ve ``` ```.PP ``` ```Example: The same as above, but use a reschedule callback to do it: ``` ```.PP ``` ```.Vb 1 ``` ```\& #include ``` ```\& ``` ```\& static ev_tstamp ``` ```\& my_scheduler_cb (ev_periodic *w, ev_tstamp now) ``` ```\& { ``` ```\& return now + (3600. \- fmod (now, 3600.)); ``` ```\& } ``` ```\& ``` ```\& ev_periodic_init (&hourly_tick, clock_cb, 0., 0., my_scheduler_cb); ``` ```.Ve ``` ```.PP ``` ```Example: Call a callback every hour, starting now: ``` ```.PP ``` ```.Vb 4 ``` ```\& ev_periodic hourly_tick; ``` ```\& ev_periodic_init (&hourly_tick, clock_cb, ``` ```\& fmod (ev_now (loop), 3600.), 3600., 0); ``` ```\& ev_periodic_start (loop, &hourly_tick); ``` ```.Ve ``` ```.ie n .SS """ev_signal"" \- signal me when a signal gets signalled!" ``` ```.el .SS "\f(CWev_signal\fP \- signal me when a signal gets signalled!" ``` ```.IX Subsection "ev_signal - signal me when a signal gets signalled!" ``` ```Signal watchers will trigger an event when the process receives a specific ``` ```signal one or more times. Even though signals are very asynchronous, libev ``` ```will try its best to deliver signals synchronously, i.e. as part of the ``` ```normal event processing, like any other event. ``` ```.PP ``` ```If you want signals to be delivered truly asynchronously, just use ``` ```\&\f(CW\*(C`sigaction\*(C'\fR as you would do without libev and forget about sharing ``` ```the signal. You can even use \f(CW\*(C`ev_async\*(C'\fR from a signal handler to ``` ```synchronously wake up an event loop. ``` ```.PP ``` ```You can configure as many watchers as you like for the same signal, but ``` ```only within the same loop, i.e. you can watch for \f(CW\*(C`SIGINT\*(C'\fR in your ``` ```default loop and for \f(CW\*(C`SIGIO\*(C'\fR in another loop, but you cannot watch for ``` ```\&\f(CW\*(C`SIGINT\*(C'\fR in both the default loop and another loop at the same time. At ``` ```the moment, \f(CW\*(C`SIGCHLD\*(C'\fR is permanently tied to the default loop. ``` ```.PP ``` ```Only after the first watcher for a signal is started will libev actually ``` ```register something with the kernel. It thus coexists with your own signal ``` ```handlers as long as you don't register any with libev for the same signal. ``` ```.PP ``` ```If possible and supported, libev will install its handlers with ``` ```\&\f(CW\*(C`SA_RESTART\*(C'\fR (or equivalent) behaviour enabled, so system calls should ``` ```not be unduly interrupted. If you have a problem with system calls getting ``` ```interrupted by signals you can block all signals in an \f(CW\*(C`ev_check\*(C'\fR watcher ``` ```and unblock them in an \f(CW\*(C`ev_prepare\*(C'\fR watcher. ``` ```.PP ``` ```\fIThe special problem of inheritance over fork/execve/pthread_create\fR ``` ```.IX Subsection "The special problem of inheritance over fork/execve/pthread_create" ``` ```.PP ``` ```Both the signal mask (\f(CW\*(C`sigprocmask\*(C'\fR) and the signal disposition ``` ```(\f(CW\*(C`sigaction\*(C'\fR) are unspecified after starting a signal watcher (and after ``` ```stopping it again), that is, libev might or might not block the signal, ``` ```and might or might not set or restore the installed signal handler (but ``` ```see \f(CW\*(C`EVFLAG_NOSIGMASK\*(C'\fR). ``` ```.PP ``` ```While this does not matter for the signal disposition (libev never ``` ```sets signals to \f(CW\*(C`SIG_IGN\*(C'\fR, so handlers will be reset to \f(CW\*(C`SIG_DFL\*(C'\fR on ``` ```\&\f(CW\*(C`execve\*(C'\fR), this matters for the signal mask: many programs do not expect ``` ```certain signals to be blocked. ``` ```.PP ``` ```This means that before calling \f(CW\*(C`exec\*(C'\fR (from the child) you should reset ``` ```the signal mask to whatever \*(L"default\*(R" you expect (all clear is a good ``` ```choice usually). ``` ```.PP ``` ```The simplest way to ensure that the signal mask is reset in the child is ``` ```to install a fork handler with \f(CW\*(C`pthread_atfork\*(C'\fR that resets it. That will ``` ```catch fork calls done by libraries (such as the libc) as well. ``` ```.PP ``` ```In current versions of libev, the signal will not be blocked indefinitely ``` ```unless you use the \f(CW\*(C`signalfd\*(C'\fR \s-1API \s0(\f(CW\*(C`EV_SIGNALFD\*(C'\fR). While this reduces ``` ```the window of opportunity for problems, it will not go away, as libev ``` ```\&\fIhas\fR to modify the signal mask, at least temporarily. ``` ```.PP ``` ```So I can't stress this enough: \fIIf you do not reset your signal mask when ``` ```you expect it to be empty, you have a race condition in your code\fR. This ``` ```is not a libev-specific thing, this is true for most event libraries. ``` ```.PP ``` ```\fIThe special problem of threads signal handling\fR ``` ```.IX Subsection "The special problem of threads signal handling" ``` ```.PP ``` ```\&\s-1POSIX\s0 threads has problematic signal handling semantics, specifically, ``` ```a lot of functionality (sigfd, sigwait etc.) only really works if all ``` ```threads in a process block signals, which is hard to achieve. ``` ```.PP ``` ```When you want to use sigwait (or mix libev signal handling with your own ``` ```for the same signals), you can tackle this problem by globally blocking ``` ```all signals before creating any threads (or creating them with a fully set ``` ```sigprocmask) and also specifying the \f(CW\*(C`EVFLAG_NOSIGMASK\*(C'\fR when creating ``` ```loops. Then designate one thread as \*(L"signal receiver thread\*(R" which handles ``` ```these signals. You can pass on any signals that libev might be interested ``` ```in by calling \f(CW\*(C`ev_feed_signal\*(C'\fR. ``` ```.PP ``` ```\fIWatcher-Specific Functions and Data Members\fR ``` ```.IX Subsection "Watcher-Specific Functions and Data Members" ``` ```.IP "ev_signal_init (ev_signal *, callback, int signum)" 4 ``` ```.IX Item "ev_signal_init (ev_signal *, callback, int signum)" ``` ```.PD 0 ``` ```.IP "ev_signal_set (ev_signal *, int signum)" 4 ``` ```.IX Item "ev_signal_set (ev_signal *, int signum)" ``` ```.PD ``` ```Configures the watcher to trigger on the given signal number (usually one ``` ```of the \f(CW\*(C`SIGxxx\*(C'\fR constants). ``` ```.IP "int signum [read\-only]" 4 ``` ```.IX Item "int signum [read-only]" ``` ```The signal the watcher watches out for. ``` ```.PP ``` ```\fIExamples\fR ``` ```.IX Subsection "Examples" ``` ```.PP ``` ```Example: Try to exit cleanly on \s-1SIGINT.\s0 ``` ```.PP ``` ```.Vb 5 ``` ```\& static void ``` ```\& sigint_cb (struct ev_loop *loop, ev_signal *w, int revents) ``` ```\& { ``` ```\& ev_break (loop, EVBREAK_ALL); ``` ```\& } ``` ```\& ``` ```\& ev_signal signal_watcher; ``` ```\& ev_signal_init (&signal_watcher, sigint_cb, SIGINT); ``` ```\& ev_signal_start (loop, &signal_watcher); ``` ```.Ve ``` ```.ie n .SS """ev_child"" \- watch out for process status changes" ``` ```.el .SS "\f(CWev_child\fP \- watch out for process status changes" ``` ```.IX Subsection "ev_child - watch out for process status changes" ``` ```Child watchers trigger when your process receives a \s-1SIGCHLD\s0 in response to ``` ```some child status changes (most typically when a child of yours dies or ``` ```exits). It is permissible to install a child watcher \fIafter\fR the child ``` ```has been forked (which implies it might have already exited), as long ``` ```as the event loop isn't entered (or is continued from a watcher), i.e., ``` ```forking and then immediately registering a watcher for the child is fine, ``` ```but forking and registering a watcher a few event loop iterations later or ``` ```in the next callback invocation is not. ``` ```.PP ``` ```Only the default event loop is capable of handling signals, and therefore ``` ```you can only register child watchers in the default event loop. ``` ```.PP ``` ```Due to some design glitches inside libev, child watchers will always be ``` ```handled at maximum priority (their priority is set to \f(CW\*(C`EV_MAXPRI\*(C'\fR by ``` ```libev) ``` ```.PP ``` ```\fIProcess Interaction\fR ``` ```.IX Subsection "Process Interaction" ``` ```.PP ``` ```Libev grabs \f(CW\*(C`SIGCHLD\*(C'\fR as soon as the default event loop is ``` ```initialised. This is necessary to guarantee proper behaviour even if the ``` ```first child watcher is started after the child exits. The occurrence ``` ```of \f(CW\*(C`SIGCHLD\*(C'\fR is recorded asynchronously, but child reaping is done ``` ```synchronously as part of the event loop processing. Libev always reaps all ``` ```children, even ones not watched. ``` ```.PP ``` ```\fIOverriding the Built-In Processing\fR ``` ```.IX Subsection "Overriding the Built-In Processing" ``` ```.PP ``` ```Libev offers no special support for overriding the built-in child ``` ```processing, but if your application collides with libev's default child ``` ```handler, you can override it easily by installing your own handler for ``` ```\&\f(CW\*(C`SIGCHLD\*(C'\fR after initialising the default loop, and making sure the ``` ```default loop never gets destroyed. You are encouraged, however, to use an ``` ```event-based approach to child reaping and thus use libev's support for ``` ```that, so other libev users can use \f(CW\*(C`ev_child\*(C'\fR watchers freely. ``` ```.PP ``` ```\fIStopping the Child Watcher\fR ``` ```.IX Subsection "Stopping the Child Watcher" ``` ```.PP ``` ```Currently, the child watcher never gets stopped, even when the ``` ```child terminates, so normally one needs to stop the watcher in the ``` ```callback. Future versions of libev might stop the watcher automatically ``` ```when a child exit is detected (calling \f(CW\*(C`ev_child_stop\*(C'\fR twice is not a ``` ```problem). ``` ```.PP ``` ```\fIWatcher-Specific Functions and Data Members\fR ``` ```.IX Subsection "Watcher-Specific Functions and Data Members" ``` ```.IP "ev_child_init (ev_child *, callback, int pid, int trace)" 4 ``` ```.IX Item "ev_child_init (ev_child *, callback, int pid, int trace)" ``` ```.PD 0 ``` ```.IP "ev_child_set (ev_child *, int pid, int trace)" 4 ``` ```.IX Item "ev_child_set (ev_child *, int pid, int trace)" ``` ```.PD ``` ```Configures the watcher to wait for status changes of process \f(CW\*(C`pid\*(C'\fR (or ``` ```\&\fIany\fR process if \f(CW\*(C`pid\*(C'\fR is specified as \f(CW0\fR). The callback can look ``` ```at the \f(CW\*(C`rstatus\*(C'\fR member of the \f(CW\*(C`ev_child\*(C'\fR watcher structure to see ``` ```the status word (use the macros from \f(CW\*(C`sys/wait.h\*(C'\fR and see your systems ``` ```\&\f(CW\*(C`waitpid\*(C'\fR documentation). The \f(CW\*(C`rpid\*(C'\fR member contains the pid of the ``` ```process causing the status change. \f(CW\*(C`trace\*(C'\fR must be either \f(CW0\fR (only ``` ```activate the watcher when the process terminates) or \f(CW1\fR (additionally ``` ```activate the watcher when the process is stopped or continued). ``` ```.IP "int pid [read\-only]" 4 ``` ```.IX Item "int pid [read-only]" ``` ```The process id this watcher watches out for, or \f(CW0\fR, meaning any process id. ``` ```.IP "int rpid [read\-write]" 4 ``` ```.IX Item "int rpid [read-write]" ``` ```The process id that detected a status change. ``` ```.IP "int rstatus [read\-write]" 4 ``` ```.IX Item "int rstatus [read-write]" ``` ```The process exit/trace status caused by \f(CW\*(C`rpid\*(C'\fR (see your systems ``` ```\&\f(CW\*(C`waitpid\*(C'\fR and \f(CW\*(C`sys/wait.h\*(C'\fR documentation for details). ``` ```.PP ``` ```\fIExamples\fR ``` ```.IX Subsection "Examples" ``` ```.PP ``` ```Example: \f(CW\*(C`fork()\*(C'\fR a new process and install a child handler to wait for ``` ```its completion. ``` ```.PP ``` ```.Vb 1 ``` ```\& ev_child cw; ``` ```\& ``` ```\& static void ``` ```\& child_cb (EV_P_ ev_child *w, int revents) ``` ```\& { ``` ```\& ev_child_stop (EV_A_ w); ``` ```\& printf ("process %d exited with status %x\en", w\->rpid, w\->rstatus); ``` ```\& } ``` ```\& ``` ```\& pid_t pid = fork (); ``` ```\& ``` ```\& if (pid < 0) ``` ```\& // error ``` ```\& else if (pid == 0) ``` ```\& { ``` ```\& // the forked child executes here ``` ```\& exit (1); ``` ```\& } ``` ```\& else ``` ```\& { ``` ```\& ev_child_init (&cw, child_cb, pid, 0); ``` ```\& ev_child_start (EV_DEFAULT_ &cw); ``` ```\& } ``` ```.Ve ``` ```.ie n .SS """ev_stat"" \- did the file attributes just change?" ``` ```.el .SS "\f(CWev_stat\fP \- did the file attributes just change?" ``` ```.IX Subsection "ev_stat - did the file attributes just change?" ``` ```This watches a file system path for attribute changes. That is, it calls ``` ```\&\f(CW\*(C`stat\*(C'\fR on that path in regular intervals (or when the \s-1OS\s0 says it changed) ``` ```and sees if it changed compared to the last time, invoking the callback ``` ```if it did. Starting the watcher \f(CW\*(C`stat\*(C'\fR's the file, so only changes that ``` ```happen after the watcher has been started will be reported. ``` ```.PP ``` ```The path does not need to exist: changing from \*(L"path exists\*(R" to \*(L"path does ``` ```not exist\*(R" is a status change like any other. The condition \*(L"path does not ``` ```exist\*(R" (or more correctly \*(L"path cannot be stat'ed\*(R") is signified by the ``` ```\&\f(CW\*(C`st_nlink\*(C'\fR field being zero (which is otherwise always forced to be at ``` ```least one) and all the other fields of the stat buffer having unspecified ``` ```contents. ``` ```.PP ``` ```The path \fImust not\fR end in a slash or contain special components such as ``` ```\&\f(CW\*(C`.\*(C'\fR or \f(CW\*(C`..\*(C'\fR. The path \fIshould\fR be absolute: If it is relative and ``` ```your working directory changes, then the behaviour is undefined. ``` ```.PP ``` ```Since there is no portable change notification interface available, the ``` ```portable implementation simply calls \f(CWstat(2)\fR regularly on the path ``` ```to see if it changed somehow. You can specify a recommended polling ``` ```interval for this case. If you specify a polling interval of \f(CW0\fR (highly ``` ```recommended!) then a \fIsuitable, unspecified default\fR value will be used ``` ```(which you can expect to be around five seconds, although this might ``` ```change dynamically). Libev will also impose a minimum interval which is ``` ```currently around \f(CW0.1\fR, but that's usually overkill. ``` ```.PP ``` ```This watcher type is not meant for massive numbers of stat watchers, ``` ```as even with OS-supported change notifications, this can be ``` ```resource-intensive. ``` ```.PP ``` ```At the time of this writing, the only OS-specific interface implemented ``` ```is the Linux inotify interface (implementing kqueue support is left as an ``` ```exercise for the reader. Note, however, that the author sees no way of ``` ```implementing \f(CW\*(C`ev_stat\*(C'\fR semantics with kqueue, except as a hint). ``` ```.PP ``` ```\fI\s-1ABI\s0 Issues (Largefile Support)\fR ``` ```.IX Subsection "ABI Issues (Largefile Support)" ``` ```.PP ``` ```Libev by default (unless the user overrides this) uses the default ``` ```compilation environment, which means that on systems with large file ``` ```support disabled by default, you get the 32 bit version of the stat ``` ```structure. When using the library from programs that change the \s-1ABI\s0 to ``` ```use 64 bit file offsets the programs will fail. In that case you have to ``` ```compile libev with the same flags to get binary compatibility. This is ``` ```obviously the case with any flags that change the \s-1ABI,\s0 but the problem is ``` ```most noticeably displayed with ev_stat and large file support. ``` ```.PP ``` ```The solution for this is to lobby your distribution maker to make large ``` ```file interfaces available by default (as e.g. FreeBSD does) and not ``` ```optional. Libev cannot simply switch on large file support because it has ``` ```to exchange stat structures with application programs compiled using the ``` ```default compilation environment. ``` ```.PP ``` ```\fIInotify and Kqueue\fR ``` ```.IX Subsection "Inotify and Kqueue" ``` ```.PP ``` ```When \f(CW\*(C`inotify (7)\*(C'\fR support has been compiled into libev and present at ``` ```runtime, it will be used to speed up change detection where possible. The ``` ```inotify descriptor will be created lazily when the first \f(CW\*(C`ev_stat\*(C'\fR ``` ```watcher is being started. ``` ```.PP ``` ```Inotify presence does not change the semantics of \f(CW\*(C`ev_stat\*(C'\fR watchers ``` ```except that changes might be detected earlier, and in some cases, to avoid ``` ```making regular \f(CW\*(C`stat\*(C'\fR calls. Even in the presence of inotify support ``` ```there are many cases where libev has to resort to regular \f(CW\*(C`stat\*(C'\fR polling, ``` ```but as long as kernel 2.6.25 or newer is used (2.6.24 and older have too ``` ```many bugs), the path exists (i.e. stat succeeds), and the path resides on ``` ```a local filesystem (libev currently assumes only ext2/3, jfs, reiserfs and ``` ```xfs are fully working) libev usually gets away without polling. ``` ```.PP ``` ```There is no support for kqueue, as apparently it cannot be used to ``` ```implement this functionality, due to the requirement of having a file ``` ```descriptor open on the object at all times, and detecting renames, unlinks ``` ```etc. is difficult. ``` ```.PP ``` ```\fI\f(CI\*(C`stat ()\*(C'\fI is a synchronous operation\fR ``` ```.IX Subsection "stat () is a synchronous operation" ``` ```.PP ``` ```Libev doesn't normally do any kind of I/O itself, and so is not blocking ``` ```the process. The exception are \f(CW\*(C`ev_stat\*(C'\fR watchers \- those call \f(CW\*(C`stat ``` ```()\*(C'\fR, which is a synchronous operation. ``` ```.PP ``` ```For local paths, this usually doesn't matter: unless the system is very ``` ```busy or the intervals between stat's are large, a stat call will be fast, ``` ```as the path data is usually in memory already (except when starting the ``` ```watcher). ``` ```.PP ``` ```For networked file systems, calling \f(CW\*(C`stat ()\*(C'\fR can block an indefinite ``` ```time due to network issues, and even under good conditions, a stat call ``` ```often takes multiple milliseconds. ``` ```.PP ``` ```Therefore, it is best to avoid using \f(CW\*(C`ev_stat\*(C'\fR watchers on networked ``` ```paths, although this is fully supported by libev. ``` ```.PP ``` ```\fIThe special problem of stat time resolution\fR ``` ```.IX Subsection "The special problem of stat time resolution" ``` ```.PP ``` ```The \f(CW\*(C`stat ()\*(C'\fR system call only supports full-second resolution portably, ``` ```and even on systems where the resolution is higher, most file systems ``` ```still only support whole seconds. ``` ```.PP ``` ```That means that, if the time is the only thing that changes, you can ``` ```easily miss updates: on the first update, \f(CW\*(C`ev_stat\*(C'\fR detects a change and ``` ```calls your callback, which does something. When there is another update ``` ```within the same second, \f(CW\*(C`ev_stat\*(C'\fR will be unable to detect unless the ``` ```stat data does change in other ways (e.g. file size). ``` ```.PP ``` ```The solution to this is to delay acting on a change for slightly more ``` ```than a second (or till slightly after the next full second boundary), using ``` ```a roughly one-second-delay \f(CW\*(C`ev_timer\*(C'\fR (e.g. \f(CW\*(C`ev_timer_set (w, 0., 1.02); ``` ```ev_timer_again (loop, w)\*(C'\fR). ``` ```.PP ``` ```The \f(CW.02\fR offset is added to work around small timing inconsistencies ``` ```of some operating systems (where the second counter of the current time ``` ```might be be delayed. One such system is the Linux kernel, where a call to ``` ```\&\f(CW\*(C`gettimeofday\*(C'\fR might return a timestamp with a full second later than ``` ```a subsequent \f(CW\*(C`time\*(C'\fR call \- if the equivalent of \f(CW\*(C`time ()\*(C'\fR is used to ``` ```update file times then there will be a small window where the kernel uses ``` ```the previous second to update file times but libev might already execute ``` ```the timer callback). ``` ```.PP ``` ```\fIWatcher-Specific Functions and Data Members\fR ``` ```.IX Subsection "Watcher-Specific Functions and Data Members" ``` ```.IP "ev_stat_init (ev_stat *, callback, const char *path, ev_tstamp interval)" 4 ``` ```.IX Item "ev_stat_init (ev_stat *, callback, const char *path, ev_tstamp interval)" ``` ```.PD 0 ``` ```.IP "ev_stat_set (ev_stat *, const char *path, ev_tstamp interval)" 4 ``` ```.IX Item "ev_stat_set (ev_stat *, const char *path, ev_tstamp interval)" ``` ```.PD ``` ```Configures the watcher to wait for status changes of the given ``` ```\&\f(CW\*(C`path\*(C'\fR. The \f(CW\*(C`interval\*(C'\fR is a hint on how quickly a change is expected to ``` ```be detected and should normally be specified as \f(CW0\fR to let libev choose ``` ```a suitable value. The memory pointed to by \f(CW\*(C`path\*(C'\fR must point to the same ``` ```path for as long as the watcher is active. ``` ```.Sp ``` ```The callback will receive an \f(CW\*(C`EV_STAT\*(C'\fR event when a change was detected, ``` ```relative to the attributes at the time the watcher was started (or the ``` ```last change was detected). ``` ```.IP "ev_stat_stat (loop, ev_stat *)" 4 ``` ```.IX Item "ev_stat_stat (loop, ev_stat *)" ``` ```Updates the stat buffer immediately with new values. If you change the ``` ```watched path in your callback, you could call this function to avoid ``` ```detecting this change (while introducing a race condition if you are not ``` ```the only one changing the path). Can also be useful simply to find out the ``` ```new values. ``` ```.IP "ev_statdata attr [read\-only]" 4 ``` ```.IX Item "ev_statdata attr [read-only]" ``` ```The most-recently detected attributes of the file. Although the type is ``` ```\&\f(CW\*(C`ev_statdata\*(C'\fR, this is usually the (or one of the) \f(CW\*(C`struct stat\*(C'\fR types ``` ```suitable for your system, but you can only rely on the POSIX-standardised ``` ```members to be present. If the \f(CW\*(C`st_nlink\*(C'\fR member is \f(CW0\fR, then there was ``` ```some error while \f(CW\*(C`stat\*(C'\fRing the file. ``` ```.IP "ev_statdata prev [read\-only]" 4 ``` ```.IX Item "ev_statdata prev [read-only]" ``` ```The previous attributes of the file. The callback gets invoked whenever ``` ```\&\f(CW\*(C`prev\*(C'\fR != \f(CW\*(C`attr\*(C'\fR, or, more precisely, one or more of these members ``` ```differ: \f(CW\*(C`st_dev\*(C'\fR, \f(CW\*(C`st_ino\*(C'\fR, \f(CW\*(C`st_mode\*(C'\fR, \f(CW\*(C`st_nlink\*(C'\fR, \f(CW\*(C`st_uid\*(C'\fR, ``` ```\&\f(CW\*(C`st_gid\*(C'\fR, \f(CW\*(C`st_rdev\*(C'\fR, \f(CW\*(C`st_size\*(C'\fR, \f(CW\*(C`st_atime\*(C'\fR, \f(CW\*(C`st_mtime\*(C'\fR, \f(CW\*(C`st_ctime\*(C'\fR. ``` ```.IP "ev_tstamp interval [read\-only]" 4 ``` ```.IX Item "ev_tstamp interval [read-only]" ``` ```The specified interval. ``` ```.IP "const char *path [read\-only]" 4 ``` ```.IX Item "const char *path [read-only]" ``` ```The file system path that is being watched. ``` ```.PP ``` ```\fIExamples\fR ``` ```.IX Subsection "Examples" ``` ```.PP ``` ```Example: Watch \f(CW\*(C`/etc/passwd\*(C'\fR for attribute changes. ``` ```.PP ``` ```.Vb 10 ``` ```\& static void ``` ```\& passwd_cb (struct ev_loop *loop, ev_stat *w, int revents) ``` ```\& { ``` ```\& /* /etc/passwd changed in some way */ ``` ```\& if (w\->attr.st_nlink) ``` ```\& { ``` ```\& printf ("passwd current size %ld\en", (long)w\->attr.st_size); ``` ```\& printf ("passwd current atime %ld\en", (long)w\->attr.st_mtime); ``` ```\& printf ("passwd current mtime %ld\en", (long)w\->attr.st_mtime); ``` ```\& } ``` ```\& else ``` ```\& /* you shalt not abuse printf for puts */ ``` ```\& puts ("wow, /etc/passwd is not there, expect problems. " ``` ```\& "if this is windows, they already arrived\en"); ``` ```\& } ``` ```\& ``` ```\& ... ``` ```\& ev_stat passwd; ``` ```\& ``` ```\& ev_stat_init (&passwd, passwd_cb, "/etc/passwd", 0.); ``` ```\& ev_stat_start (loop, &passwd); ``` ```.Ve ``` ```.PP ``` ```Example: Like above, but additionally use a one-second delay so we do not ``` ```miss updates (however, frequent updates will delay processing, too, so ``` ```one might do the work both on \f(CW\*(C`ev_stat\*(C'\fR callback invocation \fIand\fR on ``` ```\&\f(CW\*(C`ev_timer\*(C'\fR callback invocation). ``` ```.PP ``` ```.Vb 2 ``` ```\& static ev_stat passwd; ``` ```\& static ev_timer timer; ``` ```\& ``` ```\& static void ``` ```\& timer_cb (EV_P_ ev_timer *w, int revents) ``` ```\& { ``` ```\& ev_timer_stop (EV_A_ w); ``` ```\& ``` ```\& /* now it\*(Aqs one second after the most recent passwd change */ ``` ```\& } ``` ```\& ``` ```\& static void ``` ```\& stat_cb (EV_P_ ev_stat *w, int revents) ``` ```\& { ``` ```\& /* reset the one\-second timer */ ``` ```\& ev_timer_again (EV_A_ &timer); ``` ```\& } ``` ```\& ``` ```\& ... ``` ```\& ev_stat_init (&passwd, stat_cb, "/etc/passwd", 0.); ``` ```\& ev_stat_start (loop, &passwd); ``` ```\& ev_timer_init (&timer, timer_cb, 0., 1.02); ``` ```.Ve ``` ```.ie n .SS """ev_idle"" \- when you've got nothing better to do..." ``` ```.el .SS "\f(CWev_idle\fP \- when you've got nothing better to do..." ``` ```.IX Subsection "ev_idle - when you've got nothing better to do..." ``` ```Idle watchers trigger events when no other events of the same or higher ``` ```priority are pending (prepare, check and other idle watchers do not count ``` ```as receiving \*(L"events\*(R"). ``` ```.PP ``` ```That is, as long as your process is busy handling sockets or timeouts ``` ```(or even signals, imagine) of the same or higher priority it will not be ``` ```triggered. But when your process is idle (or only lower-priority watchers ``` ```are pending), the idle watchers are being called once per event loop ``` ```iteration \- until stopped, that is, or your process receives more events ``` ```and becomes busy again with higher priority stuff. ``` ```.PP ``` ```The most noteworthy effect is that as long as any idle watchers are ``` ```active, the process will not block when waiting for new events. ``` ```.PP ``` ```Apart from keeping your process non-blocking (which is a useful ``` ```effect on its own sometimes), idle watchers are a good place to do ``` ```\&\*(L"pseudo-background processing\*(R", or delay processing stuff to after the ``` ```event loop has handled all outstanding events. ``` ```.PP ``` ```\fIAbusing an \f(CI\*(C`ev_idle\*(C'\fI watcher for its side-effect\fR ``` ```.IX Subsection "Abusing an ev_idle watcher for its side-effect" ``` ```.PP ``` ```As long as there is at least one active idle watcher, libev will never ``` ```sleep unnecessarily. Or in other words, it will loop as fast as possible. ``` ```For this to work, the idle watcher doesn't need to be invoked at all \- the ``` ```lowest priority will do. ``` ```.PP ``` ```This mode of operation can be useful together with an \f(CW\*(C`ev_check\*(C'\fR watcher, ``` ```to do something on each event loop iteration \- for example to balance load ``` ```between different connections. ``` ```.PP ``` ```See \*(L"Abusing an ev_check watcher for its side-effect\*(R" for a longer ``` ```example. ``` ```.PP ``` ```\fIWatcher-Specific Functions and Data Members\fR ``` ```.IX Subsection "Watcher-Specific Functions and Data Members" ``` ```.IP "ev_idle_init (ev_idle *, callback)" 4 ``` ```.IX Item "ev_idle_init (ev_idle *, callback)" ``` ```Initialises and configures the idle watcher \- it has no parameters of any ``` ```kind. There is a \f(CW\*(C`ev_idle_set\*(C'\fR macro, but using it is utterly pointless, ``` ```believe me. ``` ```.PP ``` ```\fIExamples\fR ``` ```.IX Subsection "Examples" ``` ```.PP ``` ```Example: Dynamically allocate an \f(CW\*(C`ev_idle\*(C'\fR watcher, start it, and in the ``` ```callback, free it. Also, use no error checking, as usual. ``` ```.PP ``` ```.Vb 5 ``` ```\& static void ``` ```\& idle_cb (struct ev_loop *loop, ev_idle *w, int revents) ``` ```\& { ``` ```\& // stop the watcher ``` ```\& ev_idle_stop (loop, w); ``` ```\& ``` ```\& // now we can free it ``` ```\& free (w); ``` ```\& ``` ```\& // now do something you wanted to do when the program has ``` ```\& // no longer anything immediate to do. ``` ```\& } ``` ```\& ``` ```\& ev_idle *idle_watcher = malloc (sizeof (ev_idle)); ``` ```\& ev_idle_init (idle_watcher, idle_cb); ``` ```\& ev_idle_start (loop, idle_watcher); ``` ```.Ve ``` ```.ie n .SS """ev_prepare"" and ""ev_check"" \- customise your event loop!" ``` ```.el .SS "\f(CWev_prepare\fP and \f(CWev_check\fP \- customise your event loop!" ``` ```.IX Subsection "ev_prepare and ev_check - customise your event loop!" ``` ```Prepare and check watchers are often (but not always) used in pairs: ``` ```prepare watchers get invoked before the process blocks and check watchers ``` ```afterwards. ``` ```.PP ``` ```You \fImust not\fR call \f(CW\*(C`ev_run\*(C'\fR (or similar functions that enter the ``` ```current event loop) or \f(CW\*(C`ev_loop_fork\*(C'\fR from either \f(CW\*(C`ev_prepare\*(C'\fR or ``` ```\&\f(CW\*(C`ev_check\*(C'\fR watchers. Other loops than the current one are fine, ``` ```however. The rationale behind this is that you do not need to check ``` ```for recursion in those watchers, i.e. the sequence will always be ``` ```\&\f(CW\*(C`ev_prepare\*(C'\fR, blocking, \f(CW\*(C`ev_check\*(C'\fR so if you have one watcher of each ``` ```kind they will always be called in pairs bracketing the blocking call. ``` ```.PP ``` ```Their main purpose is to integrate other event mechanisms into libev and ``` ```their use is somewhat advanced. They could be used, for example, to track ``` ```variable changes, implement your own watchers, integrate net-snmp or a ``` ```coroutine library and lots more. They are also occasionally useful if ``` ```you cache some data and want to flush it before blocking (for example, ``` ```in X programs you might want to do an \f(CW\*(C`XFlush ()\*(C'\fR in an \f(CW\*(C`ev_prepare\*(C'\fR ``` ```watcher). ``` ```.PP ``` ```This is done by examining in each prepare call which file descriptors ``` ```need to be watched by the other library, registering \f(CW\*(C`ev_io\*(C'\fR watchers ``` ```for them and starting an \f(CW\*(C`ev_timer\*(C'\fR watcher for any timeouts (many ``` ```libraries provide exactly this functionality). Then, in the check watcher, ``` ```you check for any events that occurred (by checking the pending status ``` ```of all watchers and stopping them) and call back into the library. The ``` ```I/O and timer callbacks will never actually be called (but must be valid ``` ```nevertheless, because you never know, you know?). ``` ```.PP ``` ```As another example, the Perl Coro module uses these hooks to integrate ``` ```coroutines into libev programs, by yielding to other active coroutines ``` ```during each prepare and only letting the process block if no coroutines ``` ```are ready to run (it's actually more complicated: it only runs coroutines ``` ```with priority higher than or equal to the event loop and one coroutine ``` ```of lower priority, but only once, using idle watchers to keep the event ``` ```loop from blocking if lower-priority coroutines are active, thus mapping ``` ```low-priority coroutines to idle/background tasks). ``` ```.PP ``` ```When used for this purpose, it is recommended to give \f(CW\*(C`ev_check\*(C'\fR watchers ``` ```highest (\f(CW\*(C`EV_MAXPRI\*(C'\fR) priority, to ensure that they are being run before ``` ```any other watchers after the poll (this doesn't matter for \f(CW\*(C`ev_prepare\*(C'\fR ``` ```watchers). ``` ```.PP ``` ```Also, \f(CW\*(C`ev_check\*(C'\fR watchers (and \f(CW\*(C`ev_prepare\*(C'\fR watchers, too) should not ``` ```activate (\*(L"feed\*(R") events into libev. While libev fully supports this, they ``` ```might get executed before other \f(CW\*(C`ev_check\*(C'\fR watchers did their job. As ``` ```\&\f(CW\*(C`ev_check\*(C'\fR watchers are often used to embed other (non-libev) event ``` ```loops those other event loops might be in an unusable state until their ``` ```\&\f(CW\*(C`ev_check\*(C'\fR watcher ran (always remind yourself to coexist peacefully with ``` ```others). ``` ```.PP ``` ```\fIAbusing an \f(CI\*(C`ev_check\*(C'\fI watcher for its side-effect\fR ``` ```.IX Subsection "Abusing an ev_check watcher for its side-effect" ``` ```.PP ``` ```\&\f(CW\*(C`ev_check\*(C'\fR (and less often also \f(CW\*(C`ev_prepare\*(C'\fR) watchers can also be ``` ```useful because they are called once per event loop iteration. For ``` ```example, if you want to handle a large number of connections fairly, you ``` ```normally only do a bit of work for each active connection, and if there ``` ```is more work to do, you wait for the next event loop iteration, so other ``` ```connections have a chance of making progress. ``` ```.PP ``` ```Using an \f(CW\*(C`ev_check\*(C'\fR watcher is almost enough: it will be called on the ``` ```next event loop iteration. However, that isn't as soon as possible \- ``` ```without external events, your \f(CW\*(C`ev_check\*(C'\fR watcher will not be invoked. ``` ```.PP ``` ```This is where \f(CW\*(C`ev_idle\*(C'\fR watchers come in handy \- all you need is a ``` ```single global idle watcher that is active as long as you have one active ``` ```\&\f(CW\*(C`ev_check\*(C'\fR watcher. The \f(CW\*(C`ev_idle\*(C'\fR watcher makes sure the event loop ``` ```will not sleep, and the \f(CW\*(C`ev_check\*(C'\fR watcher makes sure a callback gets ``` ```invoked. Neither watcher alone can do that. ``` ```.PP ``` ```\fIWatcher-Specific Functions and Data Members\fR ``` ```.IX Subsection "Watcher-Specific Functions and Data Members" ``` ```.IP "ev_prepare_init (ev_prepare *, callback)" 4 ``` ```.IX Item "ev_prepare_init (ev_prepare *, callback)" ``` ```.PD 0 ``` ```.IP "ev_check_init (ev_check *, callback)" 4 ``` ```.IX Item "ev_check_init (ev_check *, callback)" ``` ```.PD ``` ```Initialises and configures the prepare or check watcher \- they have no ``` ```parameters of any kind. There are \f(CW\*(C`ev_prepare_set\*(C'\fR and \f(CW\*(C`ev_check_set\*(C'\fR ``` ```macros, but using them is utterly, utterly, utterly and completely ``` ```pointless. ``` ```.PP ``` ```\fIExamples\fR ``` ```.IX Subsection "Examples" ``` ```.PP ``` ```There are a number of principal ways to embed other event loops or modules ``` ```into libev. Here are some ideas on how to include libadns into libev ``` ```(there is a Perl module named \f(CW\*(C`EV::ADNS\*(C'\fR that does this, which you could ``` ```use as a working example. Another Perl module named \f(CW\*(C`EV::Glib\*(C'\fR embeds a ``` ```Glib main context into libev, and finally, \f(CW\*(C`Glib::EV\*(C'\fR embeds \s-1EV\s0 into the ``` ```Glib event loop). ``` ```.PP ``` ```Method 1: Add \s-1IO\s0 watchers and a timeout watcher in a prepare handler, ``` ```and in a check watcher, destroy them and call into libadns. What follows ``` ```is pseudo-code only of course. This requires you to either use a low ``` ```priority for the check watcher or use \f(CW\*(C`ev_clear_pending\*(C'\fR explicitly, as ``` ```the callbacks for the IO/timeout watchers might not have been called yet. ``` ```.PP ``` ```.Vb 2 ``` ```\& static ev_io iow [nfd]; ``` ```\& static ev_timer tw; ``` ```\& ``` ```\& static void ``` ```\& io_cb (struct ev_loop *loop, ev_io *w, int revents) ``` ```\& { ``` ```\& } ``` ```\& ``` ```\& // create io watchers for each fd and a timer before blocking ``` ```\& static void ``` ```\& adns_prepare_cb (struct ev_loop *loop, ev_prepare *w, int revents) ``` ```\& { ``` ```\& int timeout = 3600000; ``` ```\& struct pollfd fds [nfd]; ``` ```\& // actual code will need to loop here and realloc etc. ``` ```\& adns_beforepoll (ads, fds, &nfd, &timeout, timeval_from (ev_time ())); ``` ```\& ``` ```\& /* the callback is illegal, but won\*(Aqt be called as we stop during check */ ``` ```\& ev_timer_init (&tw, 0, timeout * 1e\-3, 0.); ``` ```\& ev_timer_start (loop, &tw); ``` ```\& ``` ```\& // create one ev_io per pollfd ``` ```\& for (int i = 0; i < nfd; ++i) ``` ```\& { ``` ```\& ev_io_init (iow + i, io_cb, fds [i].fd, ``` ```\& ((fds [i].events & POLLIN ? EV_READ : 0) ``` ```\& | (fds [i].events & POLLOUT ? EV_WRITE : 0))); ``` ```\& ``` ```\& fds [i].revents = 0; ``` ```\& ev_io_start (loop, iow + i); ``` ```\& } ``` ```\& } ``` ```\& ``` ```\& // stop all watchers after blocking ``` ```\& static void ``` ```\& adns_check_cb (struct ev_loop *loop, ev_check *w, int revents) ``` ```\& { ``` ```\& ev_timer_stop (loop, &tw); ``` ```\& ``` ```\& for (int i = 0; i < nfd; ++i) ``` ```\& { ``` ```\& // set the relevant poll flags ``` ```\& // could also call adns_processreadable etc. here ``` ```\& struct pollfd *fd = fds + i; ``` ```\& int revents = ev_clear_pending (iow + i); ``` ```\& if (revents & EV_READ ) fd\->revents |= fd\->events & POLLIN; ``` ```\& if (revents & EV_WRITE) fd\->revents |= fd\->events & POLLOUT; ``` ```\& ``` ```\& // now stop the watcher ``` ```\& ev_io_stop (loop, iow + i); ``` ```\& } ``` ```\& ``` ```\& adns_afterpoll (adns, fds, nfd, timeval_from (ev_now (loop)); ``` ```\& } ``` ```.Ve ``` ```.PP ``` ```Method 2: This would be just like method 1, but you run \f(CW\*(C`adns_afterpoll\*(C'\fR ``` ```in the prepare watcher and would dispose of the check watcher. ``` ```.PP ``` ```Method 3: If the module to be embedded supports explicit event ``` ```notification (libadns does), you can also make use of the actual watcher ``` ```callbacks, and only destroy/create the watchers in the prepare watcher. ``` ```.PP ``` ```.Vb 5 ``` ```\& static void ``` `\&<`