#### 3949 lines 179 KiB Groff Raw Blame History

 ```.\" Automatically generated by Pod::Man 2.16 (Pod::Simple 3.05) ``` ```.\" ``` ```.\" Standard preamble: ``` ```.\" ======================================================================== ``` ```.de Sh \" Subsection heading ``` ```.br ``` ```.if t .Sp ``` ```.ne 5 ``` ```.PP ``` ```\fB\\\$1\fR ``` ```.PP ``` ```.. ``` ```.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" '' ``` ```'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 (.Sh), items (.Ip), and index ``` ```.\" entries marked with X<> in POD. Of course, you'll have to process the ``` ```.\" output yourself in some meaningful fashion. ``` ```.ie \nF \{\ ``` ```. de IX ``` ```. tm Index:\\\$1\t\\n%\t"\\\$2" ``` ```.. ``` ```. nr % 0 ``` ```. rr F ``` ```.\} ``` ```.el \{\ ``` ```. de IX ``` ```.. ``` ```.\} ``` ```.\" ``` ```.\" 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 "2008-10-30" "libev-3.48" "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 ``` ```.Sh "\s-1EXAMPLE\s0 \s-1PROGRAM\s0" ``` ```.IX Subsection "EXAMPLE PROGRAM" ``` ```.Vb 2 ``` ```\& // a single header file is required ``` ```\& #include ``` ```\& ``` ```\& // 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_loop\*(Aqs to stop iterating ``` ```\& ev_unloop (EV_A_ EVUNLOOP_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_loop to stop iterating ``` ```\& ev_unloop (EV_A_ EVUNLOOP_ONE); ``` ```\& } ``` ```\& ``` ```\& int ``` ```\& main (void) ``` ```\& { ``` ```\& // use the default event loop unless you have special needs ``` ```\& ev_loop *loop = ev_default_loop (0); ``` ```\& ``` ```\& // 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_loop (loop, 0); ``` ```\& ``` ```\& // unloop was called, so exit ``` ```\& return 0; ``` ```\& } ``` ```.Ve ``` ```.SH "DESCRIPTION" ``` ```.IX Header "DESCRIPTION" ``` ```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 ``` ```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. ``` ```.Sh "\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), 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). ``` ```.Sh "\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`ev_loop *\*(C'\fR) will not have ``` ```this argument. ``` ```.Sh "\s-1TIME\s0 \s-1REPRESENTATION\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 (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, and when you need to do any calculations on ``` ```it, you should treat it as some floating point value. Unlike the name ``` ```component \f(CW\*(C`stamp\*(C'\fR might indicate, it is also used for time differences ``` ```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. ``` ```.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. Basically ``` ```this is a sub-second-resolution \f(CW\*(C`sleep ()\*(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. ``` ```.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. 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 ``` ```is the theoretical, all-platform, value. To find which 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)) [\s-1NOT\s0 \s-1REENTRANT\s0]" 4 ``` ```.IX Item "ev_set_allocator (void *(*cb)(void *ptr, long size)) [NOT REENTRANT]" ``` ```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)); [\s-1NOT\s0 \s-1REENTRANT\s0]" 4 ``` ```.IX Item "ev_set_syserr_cb (void (*cb)(const char *msg)); [NOT REENTRANT]" ``` ```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 ``` ```.SH "FUNCTIONS CONTROLLING THE EVENT LOOP" ``` ```.IX Header "FUNCTIONS CONTROLLING THE EVENT LOOP" ``` ```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, as there is also an \f(CW\*(C`ev_loop\*(C'\fR ``` ```\&\fIfunction\fR). ``` ```.PP ``` ```The library knows two types of such loops, the \fIdefault\fR loop, which ``` ```supports signals and child events, and dynamically created 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 will initialise the default event loop if it hasn't been initialised ``` ```yet and return it. If the default loop could not be initialised, returns ``` ```false. If it already was initialised it simply returns it (and ignores the ``` ```flags. If that is troubling you, check \f(CW\*(C`ev_backend ()\*(C'\fR afterwards). ``` ```.Sp ``` ```If you don't know what event loop to use, use the one returned from this ``` ```function. ``` ```.Sp ``` ```Note that this function is \fInot\fR thread-safe, so if you want to use it ``` ```from multiple threads, you have to lock (note also that this 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_signal\*(C'\fR and ``` ```\&\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 that 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 ``` ```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, or to work ``` ```around bugs. ``` ```.ie n .IP """EVFLAG_FORKCHECK""" 4 ``` ```.el .IP "\f(CWEVFLAG_FORKCHECK\fR" 4 ``` ```.IX Item "EVFLAG_FORKCHECK" ``` ```Instead of calling \f(CW\*(C`ev_default_fork\*(C'\fR or \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) 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 """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)" ``` ```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 n 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 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. ``` ```.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 ``` ```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 (but ``` ```sane, unlike 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) 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 ``` ```Please note that Solaris event ports can deliver a lot of spurious ``` ```notifications, so you need to use non-blocking I/O or other means to avoid ``` ```blocking when no data (or space) is available. ``` ```.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, with the exception of the spurious readiness ``` ```notifications, 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 ``` ```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. ``` ```.RE ``` ```.RS 4 ``` ```.Sp ``` ```If one or more of these 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: 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 ``` ```.Sp ``` ```Example: Use whatever libev has to offer, but make sure that kqueue is ``` ```used if available (warning, breaks stuff, best use only with your own ``` ```private event loop and only if you know the \s-1OS\s0 supports your types of ``` ```fds): ``` ```.Sp ``` ```.Vb 1 ``` ```\& ev_default_loop (ev_recommended_backends () | EVBACKEND_KQUEUE); ``` ```.Ve ``` ```.RE ``` ```.IP "struct ev_loop *ev_loop_new (unsigned int flags)" 4 ``` ```.IX Item "struct ev_loop *ev_loop_new (unsigned int flags)" ``` ```Similar to \f(CW\*(C`ev_default_loop\*(C'\fR, but always creates a new event loop that is ``` ```always distinct from the default loop. Unlike the default loop, it cannot ``` ```handle signal and child watchers, and attempts to do so will be greeted by ``` ```undefined behaviour (or a failed assertion if assertions are enabled). ``` ```.Sp ``` ```Note that this function \fIis\fR thread-safe, and the recommended 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 ``` ```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 ``` ```.IP "ev_default_destroy ()" 4 ``` ```.IX Item "ev_default_destroy ()" ``` ```Destroys the default loop again (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 ``` ```In general it is not advisable to call this function except in the ``` ```rare occasion where you really need to free e.g. the signal handling ``` ```pipe fds. 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_destroy (loop)" 4 ``` ```.IX Item "ev_loop_destroy (loop)" ``` ```Like \f(CW\*(C`ev_default_destroy\*(C'\fR, but destroys an event loop created by an ``` ```earlier call to \f(CW\*(C`ev_loop_new\*(C'\fR. ``` ```.IP "ev_default_fork ()" 4 ``` ```.IX Item "ev_default_fork ()" ``` ```This function sets a flag that causes subsequent \f(CW\*(C`ev_loop\*(C'\fR iterations ``` ```to reinitialise the kernel state for backends that have one. Despite the ``` ```name, you can call it anytime, but it makes most sense after forking, in ``` ```the child process (or both child and parent, but that again makes little ``` ```sense). You \fImust\fR call it in the child before using any of the libev ``` ```functions, and it will only take effect at the next \f(CW\*(C`ev_loop\*(C'\fR iteration. ``` ```.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 library in the child. If ``` ```you just fork+exec, you don't have to call it at all. ``` ```.Sp ``` ```The function itself is quite fast and it's usually not a problem to call ``` ```it just in case after a fork. To make this easy, the function will fit in ``` ```quite nicely into a call to \f(CW\*(C`pthread_atfork\*(C'\fR: ``` ```.Sp ``` ```.Vb 1 ``` ```\& pthread_atfork (0, 0, ev_default_fork); ``` ```.Ve ``` ```.IP "ev_loop_fork (loop)" 4 ``` ```.IX Item "ev_loop_fork (loop)" ``` ```Like \f(CW\*(C`ev_default_fork\*(C'\fR, but acts on an event loop created by ``` ```\&\f(CW\*(C`ev_loop_new\*(C'\fR. Yes, you have to call this on every allocated event loop ``` ```after fork that you want to re-use in the child, and how you do this is ``` ```entirely your own problem. ``` ```.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_loop_count (loop)" 4 ``` ```.IX Item "unsigned int ev_loop_count (loop)" ``` ```Returns the count of loop iterations for the 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. ``` ```.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_loop ()\*(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_loop (loop, int flags)" 4 ``` ```.IX Item "ev_loop (loop, int flags)" ``` ```Finally, this is it, the event handler. This function usually is called ``` ```after you initialised all your watchers and you want to start handling ``` ```events. ``` ```.Sp ``` ```If the flags argument is specified as \f(CW0\fR, it will not return until ``` ```either no event watchers are active anymore or \f(CW\*(C`ev_unloop\*(C'\fR was called. ``` ```.Sp ``` ```Please note that an explicit \f(CW\*(C`ev_unloop\*(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 ``` ```A flags value of \f(CW\*(C`EVLOOP_NONBLOCK\*(C'\fR will look for new events, will handle ``` ```those events and any already outstanding ones, but will not block your ``` ```process in case there are no events and will return after one iteration of ``` ```the loop. ``` ```.Sp ``` ```A flags value of \f(CW\*(C`EVLOOP_ONESHOT\*(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_loop\*(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_loop\*(C'\fR does: ``` ```.Sp ``` ```.Vb 10 ``` ```\& \- Before the first iteration, call any pending watchers. ``` ```\& * 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 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, EVLOOP_NONBLOCK or not having ``` ```\& any active watchers at all will result in not sleeping). ``` ```\& \- Sleep if the I/O and timer collect interval say so. ``` ```\& \- 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. ``` ```\& \- Unless any events are pending now, queue all idle watchers. ``` ```\& \- 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_unloop has been called, or EVLOOP_ONESHOT or EVLOOP_NONBLOCK ``` ```\& were used, or there are no active watchers, return, otherwise ``` ```\& continue with step *. ``` ```.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_loop (my_loop, 0); ``` ```\& ... jobs done or somebody called unloop. yeah! ``` ```.Ve ``` ```.IP "ev_unloop (loop, how)" 4 ``` ```.IX Item "ev_unloop (loop, how)" ``` ```Can be used to make a call to \f(CW\*(C`ev_loop\*(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`EVUNLOOP_ONE\*(C'\fR, which will make the innermost \f(CW\*(C`ev_loop\*(C'\fR call return, or ``` ```\&\f(CW\*(C`EVUNLOOP_ALL\*(C'\fR, which will make all nested \f(CW\*(C`ev_loop\*(C'\fR calls return. ``` ```.Sp ``` ```This \*(L"unloop state\*(R" will be cleared when entering \f(CW\*(C`ev_loop\*(C'\fR again. ``` ```.Sp ``` ```It is safe to call \f(CW\*(C`ev_unloop\*(C'\fR from otuside any \f(CW\*(C`ev_loop\*(C'\fR calls. ``` ```.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_loop\*(C'\fR will not return on its own. ``` ```.Sp ``` ```If you have a watcher you never unregister that should not keep \f(CW\*(C`ev_loop\*(C'\fR ``` ```from returning, call \fIev_unref()\fR after starting, and \fIev_ref()\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_loop\*(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). ``` ```.Sp ``` ```Example: Create a signal watcher, but keep it from keeping \f(CW\*(C`ev_loop\*(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); ``` ```\& evf_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 be not affected. Setting this to a non-null value will ``` ```introduce an additional \f(CW\*(C`ev_sleep ()\*(C'\fR call into most loop iterations. ``` ```.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. ``` ```.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. ``` ```.IP "ev_loop_verify (loop)" 4 ``` ```.IX Item "ev_loop_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 a structure that you create and register to record your ``` ```interest in some event. For instance, if 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_unloop (loop, EVUNLOOP_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_loop (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 gets 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_TIMEOUT""" 4 ``` ```.el .IP "\f(CWEV_TIMEOUT\fR" 4 ``` ```.IX Item "EV_TIMEOUT" ``` ```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_loop\*(C'\fR starts ``` ```to gather new events, and all \f(CW\*(C`ev_check\*(C'\fR watchers are invoked just after ``` ```\&\f(CW\*(C`ev_loop\*(C'\fR has gathered them, but before it invokes any callbacks for any ``` ```received events. 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_loop\*(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_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_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. ``` ```.Sh "\s-1GENERIC\s0 \s-1WATCHER\s0 \s-1FUNCTIONS\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 *, [args])" 4 ``` ```.el .IP "\f(CWev_TYPE_set\fR (ev_TYPE *, [args])" 4 ``` ```.IX Item "ev_TYPE_set (ev_TYPE *, [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_cb_set (ev_TYPE *watcher, callback)" 4 ``` ```.IX Item "ev_cb_set (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, priority)" 4 ``` ```.IX Item "ev_set_priority (ev_TYPE *watcher, 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 ``` ```This means that priorities are \fIonly\fR used for ordering callback ``` ```invocation after new events have been received. This is useful, for ``` ```example, to reduce latency after idling, or more often, to bind two ``` ```watchers on the same event and make sure one is called first. ``` ```.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 ``` ```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 ``` ```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. ``` ```.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. ``` ```.Sh "\s-1ASSOCIATING\s0 \s-1CUSTOM\s0 \s-1DATA\s0 \s-1WITH\s0 A \s-1WATCHER\s0" ``` ```.IX Subsection "ASSOCIATING CUSTOM DATA WITH A WATCHER" ``` ```Each watcher has, by default, a member \f(CW\*(C`void *data\*(C'\fR that you can change ``` ```and read at any time: libev will completely ignore it. This can be used ``` ```to associate arbitrary data with your watcher. If you need more data and ``` ```don't want to allocate memory and store a pointer to it in that data ``` ```member, you can also \*(L"subclass\*(R" the watcher type and provide your own ``` ```data: ``` ```.PP ``` ```.Vb 7 ``` ```\& struct my_io ``` ```\& { ``` ```\& ev_io io; ``` ```\& int otherfd; ``` ```\& void *somedata; ``` ```\& struct whatever *mostinteresting; ``` ```\& }; ``` ```\& ``` ```\& ... ``` ```\& struct my_io w; ``` ```\& ev_io_init (&w.io, my_cb, fd, EV_READ); ``` ```.Ve ``` ```.PP ``` ```And since your callback will be called with a pointer to the watcher, you ``` ```can cast it back to your own type: ``` ```.PP ``` ```.Vb 5 ``` ```\& static void my_cb (struct ev_loop *loop, ev_io *w_, int revents) ``` ```\& { ``` ```\& struct my_io *w = (struct my_io *)w_; ``` ```\& ... ``` ```\& } ``` ```.Ve ``` ```.PP ``` ```More interesting and less C\-conformant ways of casting your callback type ``` ```instead have been omitted. ``` ```.PP ``` ```Another common scenario is to use some data structure with multiple ``` ```embedded watchers: ``` ```.PP ``` ```.Vb 6 ``` ```\& struct my_biggy ``` ```\& { ``` ```\& int some_data; ``` ```\& ev_timer t1; ``` ```\& ev_timer t2; ``` ```\& } ``` ```.Ve ``` ```.PP ``` ```In this case getting the pointer to \f(CW\*(C`my_biggy\*(C'\fR is a bit more ``` ```complicated: Either you store the address of your \f(CW\*(C`my_biggy\*(C'\fR struct ``` ```in the \f(CW\*(C`data\*(C'\fR member of the watcher (for woozies), or you need to use ``` ```some pointer arithmetic using \f(CW\*(C`offsetof\*(C'\fR inside your watchers (for real ``` ```programmers): ``` ```.PP ``` ```.Vb 1 ``` ```\& #include ``` ```\& ``` ```\& static void ``` ```\& t1_cb (EV_P_ ev_timer *w, int revents) ``` ```\& { ``` ```\& struct my_biggy big = (struct my_biggy * ``` ```\& (((char *)w) \- offsetof (struct my_biggy, t1)); ``` ```\& } ``` ```\& ``` ```\& static void ``` ```\& t2_cb (EV_P_ ev_timer *w, int revents) ``` ```\& { ``` ```\& struct my_biggy big = (struct my_biggy * ``` ```\& (((char *)w) \- offsetof (struct my_biggy, t2)); ``` ```\& } ``` ```.Ve ``` ```.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 .Sh """ev_io"" \- is this file descriptor readable or writable?" ``` ```.el .Sh "\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 ``` ```If you cannot use non-blocking mode, then force the use of a ``` ```known-to-be-good backend (at the time of this writing, this includes only ``` ```\&\f(CW\*(C`EVBACKEND_SELECT\*(C'\fR and \f(CW\*(C`EVBACKEND_POLL\*(C'\fR). ``` ```.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. Not only are some backends known to create a ``` ```lot of those (for example Solaris ports), 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 our Xlib example, Xlib 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 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. ``` ```.PP ``` ```To support fork in your programs, you either have to call ``` ```\&\f(CW\*(C`ev_default_fork ()\*(C'\fR or \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 ``` ```\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_loop (loop, 0); ``` ```.Ve ``` ```.ie n .Sh """ev_timer"" \- relative and optionally repeating timeouts" ``` ```.el .Sh "\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, but if multiple timers become ready during the same loop iteration ``` ```then order of execution is undefined. ``` ```.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_timer_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 1 ``` ```\& ev_tstamp last_activity; // time of last activity ``` ```\& ``` ```\& static void ``` ```\& callback (EV_P_ ev_timer *w, int revents) ``` ```\& { ``` ```\& ev_tstamp now = ev_now (EV_A); ``` ```\& ev_tstamp timeout = last_activity + 60.; ``` ```\& ``` ```\& // if last_activity + 60. is older than now, we did time out ``` ```\& if (timeout < now) ``` ```\& { ``` ```\& // timeout occured, take action ``` ```\& } ``` ```\& else ``` ```\& { ``` ```\& // callback was invoked, but there was some activity, re\-arm ``` ```\& // the watcher to fire in last_activity + 60, which is ``` ```\& // guaranteed to be in the future, so "again" is positive: ``` ```\& w\->again = timeout \- now; ``` ```\& ev_timer_again (EV_A_ w); ``` ```\& } ``` ```\& } ``` ```.Ve ``` ```.Sp ``` ```To summarise the callback: first calculate the real timeout (defined ``` ```as \*(L"60 seconds after the last activity\*(R"), then check if that time has ``` ```been reached, which means something \fIdid\fR, in fact, time out. Otherwise ``` ```the callback was invoked too early (\f(CW\*(C`timeout\*(C'\fR is in the future), so ``` ```re-schedule the timer to fire at that future time, to see if maybe we have ``` ```a timeout then. ``` ```.Sp ``` ```Note how \f(CW\*(C`ev_timer_again\*(C'\fR is used, taking advantage of the ``` ```\&\f(CW\*(C`ev_timer_again\*(C'\fR optimisation when the timer is already running. ``` ```.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 timer, simply initialise the watcher and set \f(CW\*(C`last_activity\*(C'\fR ``` ```to the current time (meaning we just have some activity :), then call the ``` ```callback, which will \*(L"do the right thing\*(R" and start the timer: ``` ```.Sp ``` ```.Vb 3 ``` ```\& ev_timer_init (timer, callback); ``` ```\& last_activity = ev_now (loop); ``` ```\& callback (loop, timer, EV_TIMEOUT); ``` ```.Ve ``` ```.Sp ``` ```And 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 1 ``` ```\& last_actiivty = ev_now (loop); ``` ```.Ve ``` ```.Sp ``` ```This technique is slightly more complex, but in most cases where the ``` ```time-out is unlikely to be triggered, much more efficient. ``` ```.Sp ``` ```Changing the timeout is trivial as well (if it isn't hard-coded in the ``` ```callback :) \- just change the timeout and invoke the callback, which will ``` ```fix things for you. ``` ```.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 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 two system calls): \s-1EV\s0 therefore updates its idea of the current ``` ```time only before and after \f(CW\*(C`ev_loop\*(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 this to adjust for this: ``` ```.PP ``` ```.Vb 1 ``` ```\& ev_timer_set (&timer, after + ev_now () \- ev_time (), 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. ``` ```.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 restart it again if it is ``` ```repeating. The exact semantics are: ``` ```.Sp ``` ```If the timer is pending, its pending status is cleared. ``` ```.Sp ``` ```If the timer is started but non-repeating, stop it (as if it timed out). ``` ```.Sp ``` ```If the timer is repeating, either start it if necessary (with the ``` ```\&\f(CW\*(C`repeat\*(C'\fR value), or reset the running timer to the \f(CW\*(C`repeat\*(C'\fR value. ``` ```.Sp ``` ```This sounds a bit complicated, see \*(L"Be smart about timeouts\*(R", above, for a ``` ```usage example. ``` ```.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_loop (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 .Sh """ev_periodic"" \- to cron or not to cron?" ``` ```.el .Sh "\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's, they are not based on real time (or relative time) ``` ```but on wall clock time (absolute time). You can tell a periodic watcher ``` ```to trigger after some specific point in time. For example, if you tell a ``` ```periodic watcher to trigger in 10 seconds (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 more than year ``` ```to trigger the event (unlike an \f(CW\*(C`ev_timer\*(C'\fR, which would still trigger ``` ```roughly 10 seconds later as it uses a relative timeout). ``` ```.PP ``` ```\&\f(CW\*(C`ev_periodic\*(C'\fRs 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. ``` ```.PP ``` ```As with timers, the callback is guaranteed to be invoked only when the ``` ```time (\f(CW\*(C`at\*(C'\fR) has passed, but if multiple periodic timers become ready ``` ```during the same loop iteration, then order of execution is undefined. ``` ```.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 at, ev_tstamp interval, reschedule_cb)" 4 ``` ```.IX Item "ev_periodic_init (ev_periodic *, callback, ev_tstamp at, ev_tstamp interval, reschedule_cb)" ``` ```.PD 0 ``` ```.IP "ev_periodic_set (ev_periodic *, ev_tstamp after, ev_tstamp repeat, reschedule_cb)" 4 ``` ```.IX Item "ev_periodic_set (ev_periodic *, ev_tstamp after, ev_tstamp repeat, reschedule_cb)" ``` ```.PD ``` ```Lots of arguments, lets 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 (at = time, interval = reschedule_cb = 0) ``` ```.Sp ``` ```In this configuration the watcher triggers an event after the wall clock ``` ```time \f(CW\*(C`at\*(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 ``` ```only run when the system clock reaches or surpasses this time. ``` ```.IP "\(bu" 4 ``` ```repeating interval timer (at = offset, interval > 0, reschedule_cb = 0) ``` ```.Sp ``` ```In this mode the watcher will always be scheduled to time out at the next ``` ```\&\f(CW\*(C`at + N * interval\*(C'\fR time (for some integer N, which can also be negative) ``` ```and then repeat, regardless of any time jumps. ``` ```.Sp ``` ```This can be used to create timers that do not drift with respect to the ``` ```system clock, for example, here is a \f(CW\*(C`ev_periodic\*(C'\fR that triggers each ``` ```hour, on the hour: ``` ```.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 = at (mod interval)\*(C'\fR, regardless of any time jumps. ``` ```.Sp ``` ```For numerical stability it is preferable that the \f(CW\*(C`at\*(C'\fR value is near ``` ```\&\f(CW\*(C`ev_now ()\*(C'\fR (the current time), but there is no range requirement for ``` ```this value, and in fact is often specified as zero. ``` ```.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 (at and interval ignored, reschedule_cb = callback) ``` ```.Sp ``` ```In this mode the values for \f(CW\*(C`interval\*(C'\fR and \f(CW\*(C`at\*(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\s0 \s-1NOT\s0 stop or destroy any periodic watcher, ``` ```ever, or make \s-1ANY\s0 event loop modifications whatsoever\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. ``` ```.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`at\*(C'\fR value passed to \f(CW\*(C`ev_periodic_set\*(C'\fR). ``` ```.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_io *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 .Sh """ev_signal"" \- signal me when a signal gets signalled!" ``` ```.el .Sh "\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 it's best to deliver signals synchronously, i.e. as part of the ``` ```normal event processing, like any other event. ``` ```.PP ``` ```If you want signals 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 per signal. Only when the ``` ```first watcher gets started will libev actually register a signal handler ``` ```with the kernel (thus it coexists with your own signal handlers as long as ``` ```you don't register any with libev for the same signal). Similarly, when ``` ```the last signal watcher for a signal is stopped, libev will reset the ``` ```signal handler to \s-1SIG_DFL\s0 (regardless of what it was set to before). ``` ```.PP ``` ```If possible and supported, libev will install its handlers with ``` ```\&\f(CW\*(C`SA_RESTART\*(C'\fR 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 ``` ```\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_unloop (loop, EVUNLOOP_ALL); ``` ```\& } ``` ```\& ``` ```\& ev_signal signal_watcher; ``` ```\& ev_signal_init (&signal_watcher, sigint_cb, SIGINT); ``` ```\& ev_signal_start (loop, &signal_watcher); ``` ```.Ve ``` ```.ie n .Sh """ev_child"" \- watch out for process status changes" ``` ```.el .Sh "\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 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 ``` ```\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. ``` ```.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 .Sh """ev_stat"" \- did the file attributes just change?" ``` ```.el .Sh "\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. ``` ```.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" 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). ``` ```.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 (generally ``` ```only available with Linux 2.6.25 or above due to bugs in earlier ``` ```implementations) 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 the path exists, 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 ``` ```\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 .Sh """ev_idle"" \- when you've got nothing better to do..." ``` ```.el .Sh "\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 ``` ```\fIWatcher-Specific Functions and Data Members\fR ``` ```.IX Subsection "Watcher-Specific Functions and Data Members" ``` ```.IP "ev_idle_init (ev_signal *, callback)" 4 ``` ```.IX Item "ev_idle_init (ev_signal *, 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 7 ``` ```\& static void ``` ```\& idle_cb (struct ev_loop *loop, ev_idle *w, int revents) ``` ```\& { ``` ```\& 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_cb); ``` ```.Ve ``` ```.ie n .Sh """ev_prepare""\fP and \f(CW""ev_check"" \- customise your event loop!" ``` ```.el .Sh "\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 usually (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_loop\*(C'\fR or similar functions that enter ``` ```the current event loop 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 ``` ```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 ``` ```\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); ``` ```\& 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 ``` ```\& timer_cb (EV_P_ ev_timer *w, int revents) ``` ```\& { ``` ```\& adns_state ads = (adns_state)w\->data; ``` ```\& update_now (EV_A); ``` ```\& ``` ```\& adns_processtimeouts (ads, &tv_now); ``` ```\& } ``` ```\& ``` ```\& static void ``` ```\& io_cb (EV_P_ ev_io *w, int revents) ``` ```\& { ``` ```\& adns_state ads = (adns_state)w\->data; ``` ```\& update_now (EV_A); ``` ```\& ``` ```\& if (revents & EV_READ ) adns_processreadable (ads, w\->fd, &tv_now); ``` ```\& if (revents & EV_WRITE) adns_processwriteable (ads, w\->fd, &tv_now); ``` ```\& } ``` ```\& ``` ```\& // do not ever call adns_afterpoll ``` ```.Ve ``` ```.PP ``` ```Method 4: Do not use a prepare or check watcher because the module you ``` ```want to embed is not flexible enough to support it. Instead, you can ``` ```override their poll function. The drawback with this solution is that the ``` ```main loop is now no longer controllable by \s-1EV\s0. The \f(CW\*(C`Glib::EV\*(C'\fR module uses ``` ```this approach, effectively embedding \s-1EV\s0 as a client into the horrible ``` ```libglib event loop. ``` ```.PP ``` ```.Vb 4 ``` ```\& static gint ``` ```\& event_poll_func (GPollFD *fds, guint nfds, gint timeout) ``` ```\& { ``` ```\& int got_events = 0; ``` ```\& ``` ```\& for (n = 0; n < nfds; ++n) ``` ```\& // create/start io watcher that sets the relevant bits in fds[n] and increment got_events ``` ```\& ``` ```\& if (timeout >= 0) ``` ```\& // create/start timer ``` ```\& ``` ```\& // poll ``` ```\& ev_loop (EV_A_ 0); ``` ```\& ``` ```\& // stop timer again ``` ```\& if (timeout >= 0) ``` ```\& ev_timer_stop (EV_A_ &to); ``` ```\& ``` ```\& // stop io watchers again \- their callbacks should have set ``` ```\& for (n = 0; n < nfds; ++n) ``` ```\& ev_io_stop (EV_A_ iow [n]); ``` ```\& ``` ```\& return got_events; ``` ```\& } ``` ```.Ve ``` ```.ie n .Sh """ev_embed"" \- when one backend isn't enough..." ``` ```.el .Sh "\f(CWev_embed\fP \- when one backend isn't enough..." ``` ```.IX Subsection "ev_embed - when one backend isn't enough..." ``` ```This is a rather advanced watcher type that lets you embed one event loop ``` ```into another (currently only \f(CW\*(C`ev_io\*(C'\fR events are supported in the embedded ``` ```loop, other types of watchers might be handled in a delayed or incorrect ``` ```fashion and must not be used). ``` ```.PP ``` ```There are primarily two reasons you would want that: work around bugs and ``` ```prioritise I/O. ``` ```.PP ``` ```As an example for a bug workaround, the kqueue backend might only support ``` ```sockets on some platform, so it is unusable as generic backend, but you ``` ```still want to make use of it because you have many sockets and it scales ``` ```so nicely. In this case, you would create a kqueue-based loop and embed ``` ```it into your default loop (which might use e.g. poll). Overall operation ``` ```will be a bit slower because first libev has to call \f(CW\*(C`poll\*(C'\fR and then ``` ```\&\f(CW\*(C`kevent\*(C'\fR, but at least you can use both mechanisms for what they are ``` ```best: \f(CW\*(C`kqueue\*(C'\fR for scalable sockets and \f(CW\*(C`poll\*(C'\fR if you want it to work :) ``` ```.PP ``` ```As for prioritising I/O: under rare circumstances you have the case where ``` ```some fds have to be watched and handled very quickly (with low latency), ``` ```and even priorities and idle watchers might have too much overhead. In ``` ```this case you would put all the high priority stuff in one loop and all ``` ```the rest in a second one, and embed the second one in the first. ``` ```.PP ``` ```As long as the watcher is active, the callback will be invoked every time ``` ```there might be events pending in the embedded loop. The callback must then ``` ```call \f(CW\*(C`ev_embed_sweep (mainloop, watcher)\*(C'\fR to make a single sweep and invoke ``` ```their callbacks (you could also start an idle watcher to give the embedded ``` ```loop strictly lower priority for example). You can also set the callback ``` ```to \f(CW0\fR, in which case the embed watcher will automatically execute the ``` ```embedded loop sweep. ``` ```.PP ``` ```As long as the watcher is started it will automatically handle events. The ``` ```callback will be invoked whenever some events have been handled. You can ``` ```set the callback to \f(CW0\fR to avoid having to specify one if you are not ``` ```interested in that. ``` ```.PP ``` ```Also, there have not currently been made special provisions for forking: ``` ```when you fork, you not only have to call \f(CW\*(C`ev_loop_fork\*(C'\fR on both loops, ``` ```but you will also have to stop and restart any \f(CW\*(C`ev_embed\*(C'\fR watchers ``` ```yourself \- but you can use a fork watcher to handle this automatically, ``` ```and future versions of libev might do just that. ``` ```.PP ``` ```Unfortunately, not all backends are embeddable: only the ones returned by ``` ```\&\f(CW\*(C`ev_embeddable_backends\*(C'\fR are, which, unfortunately, does not include any ``` ```portable one. ``` ```.PP ``` ```So when you want to use this feature you will always have to be prepared ``` ```that you cannot get an embeddable loop. The recommended way to get around ``` ```this is to have a separate variables for your embeddable loop, try to ``` ```create it, and if that fails, use the normal loop for everything. ``` ```.PP ``` ```\fI\f(CI\*(C`ev_embed\*(C'\fI and fork\fR ``` ```.IX Subsection "ev_embed and fork" ``` ```.PP ``` ```While the \f(CW\*(C`ev_embed\*(C'\fR watcher is running, forks in the embedding loop will ``` ```automatically be applied to the embedded loop as well, so no special ``` ```fork handling is required in that case. When the watcher is not running, ``` ```however, it is still the task of the libev user to call \f(CW\*(C`ev_loop_fork ()\*(C'\fR ``` ```as applicable. ``` ```.PP ``` ```\fIWatcher-Specific Functions and Data Members\fR ``` ```.IX Subsection "Watcher-Specific Functions and Data Members" ``` ```.IP "ev_embed_init (ev_embed *, callback, struct ev_loop *embedded_loop)" 4 ``` ```.IX Item "ev_embed_init (ev_embed *, callback, struct ev_loop *embedded_loop)" ``` ```.PD 0 ``` ```.IP "ev_embed_set (ev_embed *, callback, struct ev_loop *embedded_loop)" 4 ``` ```.IX Item "ev_embed_set (ev_embed *, callback, struct ev_loop *embedded_loop)" ``` ```.PD ``` ```Configures the watcher to embed the given loop, which must be ``` ```embeddable. If the callback is \f(CW0\fR, then \f(CW\*(C`ev_embed_sweep\*(C'\fR will be ``` ```invoked automatically, otherwise it is the responsibility of the callback ``` ```to invoke it (it will continue to be called until the sweep has been done, ``` ```if you do not want that, you need to temporarily stop the embed watcher). ``` ```.IP "ev_embed_sweep (loop, ev_embed *)" 4 ``` ```.IX Item "ev_embed_sweep (loop, ev_embed *)" ``` ```Make a single, non-blocking sweep over the embedded loop. This works ``` ```similarly to \f(CW\*(C`ev_loop (embedded_loop, EVLOOP_NONBLOCK)\*(C'\fR, but in the most ``` ```appropriate way for embedded loops. ``` ```.IP "struct ev_loop *other [read\-only]" 4 ``` ```.IX Item "struct ev_loop *other [read-only]" ``` ```The embedded event loop. ``` ```.PP ``` ```\fIExamples\fR ``` ```.IX Subsection "Examples" ``` ```.PP ``` ```Example: Try to get an embeddable event loop and embed it into the default ``` ```event loop. If that is not possible, use the default loop. The default ``` ```loop is stored in \f(CW\*(C`loop_hi\*(C'\fR, while the embeddable loop is stored in ``` ```\&\f(CW\*(C`loop_lo\*(C'\fR (which is \f(CW\*(C`loop_hi\*(C'\fR in the case no embeddable loop can be ``` ```used). ``` ```.PP ``` ```.Vb 3 ``` ```\& struct ev_loop *loop_hi = ev_default_init (0); ``` ```\& struct ev_loop *loop_lo = 0; ``` ```\& ev_embed embed; ``` ```\& ``` ```\& // see if there is a chance of getting one that works ``` ```\& // (remember that a flags value of 0 means autodetection) ``` ```\& loop_lo = ev_embeddable_backends () & ev_recommended_backends () ``` ```\& ? ev_loop_new (ev_embeddable_backends () & ev_recommended_backends ()) ``` ```\& : 0; ``` ```\& ``` ```\& // if we got one, then embed it, otherwise default to loop_hi ``` ```\& if (loop_lo) ``` ```\& { ``` ```\& ev_embed_init (&embed, 0, loop_lo); ``` ```\& ev_embed_start (loop_hi, &embed); ``` ```\& } ``` ```\& else ``` ```\& loop_lo = loop_hi; ``` ```.Ve ``` ```.PP ``` ```Example: Check if kqueue is available but not recommended and create ``` ```a kqueue backend for use with sockets (which usually work with any ``` ```kqueue implementation). Store the kqueue/socket\-only event loop in ``` ```\&\f(CW\*(C`loop_socket\*(C'\fR. (One might optionally use \f(CW\*(C`EVFLAG_NOENV\*(C'\fR, too). ``` ```.PP ``` ```.Vb 3 ``` ```\& struct ev_loop *loop = ev_default_init (0); ``` ```\& struct ev_loop *loop_socket = 0; ``` ```\& ev_embed embed; ``` ```\& ``` ```\& if (ev_supported_backends () & ~ev_recommended_backends () & EVBACKEND_KQUEUE) ``` ```\& if ((loop_socket = ev_loop_new (EVBACKEND_KQUEUE)) ``` ```\& { ``` ```\& ev_embed_init (&embed, 0, loop_socket); ``` ```\& ev_embed_start (loop, &embed); ``` ```\& } ``` ```\& ``` ```\& if (!loop_socket) ``` ```\& loop_socket = loop; ``` ```\& ``` ```\& // now use loop_socket for all sockets, and loop for everything else ``` ```.Ve ``` ```.ie n .Sh """ev_fork"" \- the audacity to resume the event loop after a fork" ``` ```.el .Sh "\f(CWev_fork\fP \- the audacity to resume the event loop after a fork" ``` ```.IX Subsection "ev_fork - the audacity to resume the event loop after a fork" ``` ```Fork watchers are called when a \f(CW\*(C`fork ()\*(C'\fR was detected (usually because ``` ```whoever is a good citizen cared to tell libev about it by calling ``` ```\&\f(CW\*(C`ev_default_fork\*(C'\fR or \f(CW\*(C`ev_loop_fork\*(C'\fR). The invocation is done before the ``` ```event loop blocks next and before \f(CW\*(C`ev_check\*(C'\fR watchers are being called, ``` ```and only in the child after the fork. If whoever good citizen calling ``` ```\&\f(CW\*(C`ev_default_fork\*(C'\fR cheats and calls it in the wrong process, the fork ``` ```handlers will be invoked, too, of course. ``` ```.PP ``` ```\fIWatcher-Specific Functions and Data Members\fR ``` ```.IX Subsection "Watcher-Specific Functions and Data Members" ``` ```.IP "ev_fork_init (ev_signal *, callback)" 4 ``` ```.IX Item "ev_fork_init (ev_signal *, callback)" ``` ```Initialises and configures the fork watcher \- it has no parameters of any ``` ```kind. There is a \f(CW\*(C`ev_fork_set\*(C'\fR macro, but using it is utterly pointless, ``` ```believe me. ``` ```.ie n .Sh """ev_async"" \- how to wake up another event loop" ``` ```.el .Sh "\f(CWev_async\fP \- how to wake up another event loop" ``` ```.IX Subsection "ev_async - how to wake up another event loop" ``` ```In general, you cannot use an \f(CW\*(C`ev_loop\*(C'\fR from multiple threads or other ``` ```asynchronous sources such as signal handlers (as opposed to multiple event ``` ```loops \- those are of course safe to use in different threads). ``` ```.PP ``` ```Sometimes, however, you need to wake up another event loop you do not ``` ```control, for example because it belongs to another thread. This is what ``` ```\&\f(CW\*(C`ev_async\*(C'\fR watchers do: as long as the \f(CW\*(C`ev_async\*(C'\fR watcher is active, you ``` ```can signal it by calling \f(CW\*(C`ev_async_send\*(C'\fR, which is thread\- and signal ``` ```safe. ``` ```.PP ``` ```This functionality is very similar to \f(CW\*(C`ev_signal\*(C'\fR watchers, as signals, ``` ```too, are asynchronous in nature, and signals, too, will be compressed ``` ```(i.e. the number of callback invocations may be less than the number of ``` ```\&\f(CW\*(C`ev_async_sent\*(C'\fR calls). ``` ```.PP ``` ```Unlike \f(CW\*(C`ev_signal\*(C'\fR watchers, \f(CW\*(C`ev_async\*(C'\fR works with any event loop, not ``` ```just the default loop. ``` ```.PP ``` ```\fIQueueing\fR ``` ```.IX Subsection "Queueing" ``` ```.PP ``` ```\&\f(CW\*(C`ev_async\*(C'\fR does not support queueing of data in any way. The reason ``` ```is that the author does not know of a simple (or any) algorithm for a ``` ```multiple-writer-single-reader queue that works in all cases and doesn't ``` ```need elaborate support such as pthreads. ``` ```.PP ``` ```That means that if you want to queue data, you have to provide your own ``` ```queue. But at least I can tell you how to implement locking around your ``` ```queue: ``` ```.IP "queueing from a signal handler context" 4 ``` ```.IX Item "queueing from a signal handler context" ``` ```To implement race-free queueing, you simply add to the queue in the signal ``` ```handler but you block the signal handler in the watcher callback. Here is ``` ```an example that does that for some fictitious \s-1SIGUSR1\s0 handler: ``` ```.Sp ``` ```.Vb 1 ``` ```\& static ev_async mysig; ``` ```\& ``` ```\& static void ``` ```\& sigusr1_handler (void) ``` ```\& { ``` ```\& sometype data; ``` ```\& ``` ```\& // no locking etc. ``` ```\& queue_put (data); ``` ```\& ev_async_send (EV_DEFAULT_ &mysig); ``` ```\& } ``` ```\& ``` ```\& static void ``` ```\& mysig_cb (EV_P_ ev_async *w, int revents) ``` ```\& { ``` ```\& sometype data; ``` ```\& sigset_t block, prev; ``` ```\& ``` ```\& sigemptyset (&block); ``` ```\& sigaddset (&block, SIGUSR1); ``` ```\& sigprocmask (SIG_BLOCK, &block, &prev); ``` ```\& ``` ```\& while (queue_get (&data)) ``` ```\& process (data); ``` ```\& ``` ```\& if (sigismember (&prev, SIGUSR1) ``` ```\& sigprocmask (SIG_UNBLOCK, &block, 0); ``` ```\& } ``` ```.Ve ``` ```.Sp ``` ```(Note: pthreads in theory requires you to use \f(CW\*(C`pthread_setmask\*(C'\fR ``` ```instead of \f(CW\*(C`sigprocmask\*(C'\fR when you use threads, but libev doesn't do it ``` ```either...). ``` ```.IP "queueing from a thread context" 4 ``` ```.IX Item "queueing from a thread context" ``` ```The strategy for threads is different, as you cannot (easily) block ``` ```threads but you can easily preempt them, so to queue safely you need to ``` ```employ a traditional mutex lock, such as in this pthread example: ``` ```.Sp ``` ```.Vb 2 ``` ```\& static ev_async mysig; ``` ```\& static pthread_mutex_t mymutex = PTHREAD_MUTEX_INITIALIZER; ``` ```\& ``` ```\& static void ``` ```\& otherthread (void) ``` ```\& { ``` ```\& // only need to lock the actual queueing operation ``` ```\& pthread_mutex_lock (&mymutex); ``` ```\& queue_put (data); ``` ```\& pthread_mutex_unlock (&mymutex); ``` ```\& ``` ```\& ev_async_send (EV_DEFAULT_ &mysig); ``` ```\& } ``` ```\& ``` ```\& static void ``` ```\& mysig_cb (EV_P_ ev_async *w, int revents) ``` ```\& { ``` ```\& pthread_mutex_lock (&mymutex); ``` ```\& ``` ```\& while (queue_get (&data)) ``` ```\& process (data); ``` ```\& ``` ```\& pthread_mutex_unlock (&mymutex); ``` ```\& } ``` ```.Ve ``` ```.PP ``` ```\fIWatcher-Specific Functions and Data Members\fR ``` ```.IX Subsection "Watcher-Specific Functions and Data Members" ``` ```.IP "ev_async_init (ev_async *, callback)" 4 ``` ```.IX Item "ev_async_init (ev_async *, callback)" ``` ```Initialises and configures the async watcher \- it has no parameters of any ``` ```kind. There is a \f(CW\*(C`ev_async_set\*(C'\fR macro, but using it is utterly pointless, ``` ```trust me. ``` ```.IP "ev_async_send (loop, ev_async *)" 4 ``` ```.IX Item "ev_async_send (loop, ev_async *)" ``` ```Sends/signals/activates the given \f(CW\*(C`ev_async\*(C'\fR watcher, that is, feeds ``` ```an \f(CW\*(C`EV_ASYNC\*(C'\fR event on the watcher into the event loop. Unlike ``` ```\&\f(CW\*(C`ev_feed_event\*(C'\fR, this call is safe to do from other threads, signal or ``` ```similar contexts (see the discussion of \f(CW\*(C`EV_ATOMIC_T\*(C'\fR in the embedding ``` ```section below on what exactly this means). ``` ```.Sp ``` ```This call incurs the overhead of a system call only once per loop iteration, ``` ```so while the overhead might be noticeable, it doesn't apply to repeated ``` ```calls to \f(CW\*(C`ev_async_send\*(C'\fR. ``` ```.IP "bool = ev_async_pending (ev_async *)" 4 ``` ```.IX Item "bool = ev_async_pending (ev_async *)" ``` ```Returns a non-zero value when \f(CW\*(C`ev_async_send\*(C'\fR has been called on the ``` ```watcher but the event has not yet been processed (or even noted) by the ``` ```event loop. ``` ```.Sp ``` ```\&\f(CW\*(C`ev_async_send\*(C'\fR sets a flag in the watcher and wakes up the loop. When ``` ```the loop iterates next and checks for the watcher to have become active, ``` ```it will reset the flag again. \f(CW\*(C`ev_async_pending\*(C'\fR can be used to very ``` ```quickly check whether invoking the loop might be a good idea. ``` ```.Sp ``` ```Not that this does \fInot\fR check whether the watcher itself is pending, only ``` ```whether it has been requested to make this watcher pending. ``` ```.SH "OTHER FUNCTIONS" ``` ```.IX Header "OTHER FUNCTIONS" ``` ```There are some other functions of possible interest. Described. Here. Now. ``` ```.IP "ev_once (loop, int fd, int events, ev_tstamp timeout, callback)" 4 ``` ```.IX Item "ev_once (loop, int fd, int events, ev_tstamp timeout, callback)" ``` ```This function combines a simple timer and an I/O watcher, calls your ``` ```callback on whichever event happens first and automatically stops both ``` ```watchers. This is useful if you want to wait for a single event on an fd ``` ```or timeout without having to allocate/configure/start/stop/free one or ``` ```more watchers yourself. ``` ```.Sp ``` ```If \f(CW\*(C`fd\*(C'\fR is less than 0, then no I/O watcher will be started and the ``` ```\&\f(CW\*(C`events\*(C'\fR argument is being ignored. Otherwise, an \f(CW\*(C`ev_io\*(C'\fR watcher for ``` ```the given \f(CW\*(C`fd\*(C'\fR and \f(CW\*(C`events\*(C'\fR set will be created and started. ``` ```.Sp ``` ```If \f(CW\*(C`timeout\*(C'\fR is less than 0, then no timeout watcher will be ``` ```started. Otherwise an \f(CW\*(C`ev_timer\*(C'\fR watcher with after = \f(CW\*(C`timeout\*(C'\fR (and ``` ```repeat = 0) will be started. \f(CW0\fR is a valid timeout. ``` ```.Sp ``` ```The callback has the type \f(CW\*(C`void (*cb)(int revents, void *arg)\*(C'\fR and gets ``` ```passed an \f(CW\*(C`revents\*(C'\fR set like normal event callbacks (a combination of ``` ```\&\f(CW\*(C`EV_ERROR\*(C'\fR, \f(CW\*(C`EV_READ\*(C'\fR, \f(CW\*(C`EV_WRITE\*(C'\fR or \f(CW\*(C`EV_TIMEOUT\*(C'\fR) and the \f(CW\*(C`arg\*(C'\fR ``` ```value passed to \f(CW\*(C`ev_once\*(C'\fR. Note that it is possible to receive \fIboth\fR ``` ```a timeout and an io event at the same time \- you probably should give io ``` ```events precedence. ``` ```.Sp ``` ```Example: wait up to ten seconds for data to appear on \s-1STDIN_FILENO\s0. ``` ```.Sp ``` ```.Vb 7 ``` ```\& static void stdin_ready (int revents, void *arg) ``` ```\& { ``` ```\& if (revents & EV_READ) ``` ```\& /* stdin might have data for us, joy! */; ``` ```\& else if (revents & EV_TIMEOUT) ``` ```\& /* doh, nothing entered */; ``` ```\& } ``` ```\& ``` ```\& ev_once (STDIN_FILENO, EV_READ, 10., stdin_ready, 0); ``` ```.Ve ``` ```.IP "ev_feed_event (struct ev_loop *, watcher *, int revents)" 4 ``` ```.IX Item "ev_feed_event (struct ev_loop *, 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). ``` ```.IP "ev_feed_fd_event (struct ev_loop *, int fd, int revents)" 4 ``` ```.IX Item "ev_feed_fd_event (struct ev_loop *, int fd, int revents)" ``` ```Feed an event on the given fd, as if a file descriptor backend detected ``` ```the given events it. ``` ```.IP "ev_feed_signal_event (struct ev_loop *loop, int signum)" 4 ``` ```.IX Item "ev_feed_signal_event (struct ev_loop *loop, int signum)" ``` ```Feed an event as if the given signal occurred (\f(CW\*(C`loop\*(C'\fR must be the default ``` ```loop!). ``` ```.SH "LIBEVENT EMULATION" ``` ```.IX Header "LIBEVENT EMULATION" ``` ```Libev offers a compatibility emulation layer for libevent. It cannot ``` ```emulate the internals of libevent, so here are some usage hints: ``` ```.IP "\(bu" 4 ``` ```Use it by including , as usual. ``` ```.IP "\(bu" 4 ``` ```The following members are fully supported: ev_base, ev_callback, ``` ```ev_arg, ev_fd, ev_res, ev_events. ``` ```.IP "\(bu" 4 ``` ```Avoid using ev_flags and the EVLIST_*\-macros, while it is ``` ```maintained by libev, it does not work exactly the same way as in libevent (consider ``` ```it a private \s-1API\s0). ``` ```.IP "\(bu" 4 ``` ```Priorities are not currently supported. Initialising priorities ``` ```will fail and all watchers will have the same priority, even though there ``` ```is an ev_pri field. ``` ```.IP "\(bu" 4 ``` ```In libevent, the last base created gets the signals, in libev, the ``` ```first base created (== the default loop) gets the signals. ``` ```.IP "\(bu" 4 ``` ```Other members are not supported. ``` ```.IP "\(bu" 4 ``` ```The libev emulation is \fInot\fR \s-1ABI\s0 compatible to libevent, you need ``` ```to use the libev header file and library. ``` ```.SH "\*(C+ SUPPORT" ``` ```.IX Header " SUPPORT" ``` ```Libev comes with some simplistic wrapper classes for \*(C+ that mainly allow ``` ```you to use some convenience methods to start/stop watchers and also change ``` ```the callback model to a model using method callbacks on objects. ``` ```.PP ``` ```To use it, ``` ```.PP ``` ```.Vb 1 ``` ```\& #include ``` ```.Ve ``` ```.PP ``` ```This automatically includes \fIev.h\fR and puts all of its definitions (many ``` ```of them macros) into the global namespace. All \*(C+ specific things are ``` ```put into the \f(CW\*(C`ev\*(C'\fR namespace. It should support all the same embedding ``` ```options as \fIev.h\fR, most notably \f(CW\*(C`EV_MULTIPLICITY\*(C'\fR. ``` ```.PP ``` ```Care has been taken to keep the overhead low. The only data member the \*(C+ ``` ```classes add (compared to plain C\-style watchers) is the event loop pointer ``` ```that the watcher is associated with (or no additional members at all if ``` ```you disable \f(CW\*(C`EV_MULTIPLICITY\*(C'\fR when embedding libev). ``` ```.PP ``` ```Currently, functions, and static and non-static member functions can be ``` ```used as callbacks. Other types should be easy to add as long as they only ``` ```need one additional pointer for context. If you need support for other ``` ```types of functors please contact the author (preferably after implementing ``` ```it). ``` ```.PP ``` ```Here is a list of things available in the \f(CW\*(C`ev\*(C'\fR namespace: ``` ```.ie n .IP """ev::READ""\fR, \f(CW""ev::WRITE"" etc." 4 ``` ```.el .IP "\f(CWev::READ\fR, \f(CWev::WRITE\fR etc." 4 ``` ```.IX Item "ev::READ, ev::WRITE etc." ``` ```These are just enum values with the same values as the \f(CW\*(C`EV_READ\*(C'\fR etc. ``` ```macros from \fIev.h\fR. ``` ```.ie n .IP """ev::tstamp""\fR, \f(CW""ev::now""" 4 ``` ```.el .IP "\f(CWev::tstamp\fR, \f(CWev::now\fR" 4 ``` ```.IX Item "ev::tstamp, ev::now" ``` ```Aliases to the same types/functions as with the \f(CW\*(C`ev_\*(C'\fR prefix. ``` ```.ie n .IP """ev::io""\fR, \f(CW""ev::timer""\fR, \f(CW""ev::periodic""\fR, \f(CW""ev::idle""\fR, \f(CW""ev::sig"" etc." 4 ``` ```.el .IP "\f(CWev::io\fR, \f(CWev::timer\fR, \f(CWev::periodic\fR, \f(CWev::idle\fR, \f(CWev::sig\fR etc." 4 ``` ```.IX Item "ev::io, ev::timer, ev::periodic, ev::idle, ev::sig etc." ``` ```For each \f(CW\*(C`ev_TYPE\*(C'\fR watcher in \fIev.h\fR there is a corresponding class of ``` ```the same name in the \f(CW\*(C`ev\*(C'\fR namespace, with the exception of \f(CW\*(C`ev_signal\*(C'\fR ``` ```which is called \f(CW\*(C`ev::sig\*(C'\fR to avoid clashes with the \f(CW\*(C`signal\*(C'\fR macro ``` ```defines by many implementations. ``` ```.Sp ``` ```All of those classes have these methods: ``` ```.RS 4 ``` ```.IP "ev::TYPE::TYPE ()" 4 ``` ```.IX Item "ev::TYPE::TYPE ()" ``` ```.PD 0 ``` ```.IP "ev::TYPE::TYPE (struct ev_loop *)" 4 ``` ```.IX Item "ev::TYPE::TYPE (struct ev_loop *)" ``` ```.IP "ev::TYPE::~TYPE" 4 ``` ```.IX Item "ev::TYPE::~TYPE" ``` ```.PD ``` ```The constructor (optionally) takes an event loop to associate the watcher ``` ```with. If it is omitted, it will use \f(CW\*(C`EV_DEFAULT\*(C'\fR. ``` ```.Sp ``` ```The constructor calls \f(CW\*(C`ev_init\*(C'\fR for you, which means you have to call the ``` ```\&\f(CW\*(C`set\*(C'\fR method before starting it. ``` ```.Sp ``` ```It will not set a callback, however: You have to call the templated \f(CW\*(C`set\*(C'\fR ``` ```method to set a callback before you can start the watcher. ``` ```.Sp ``` ```(The reason why you have to use a method is a limitation in \*(C+ which does ``` ```not allow explicit template arguments for constructors). ``` ```.Sp ``` ```The destructor automatically stops the watcher if it is active. ``` ```.IP "w\->set (object *)" 4 ``` ```.IX Item "w->set (object *)" ``` ```This method sets the callback method to call. The method has to have a ``` ```signature of \f(CW\*(C`void (*)(ev_TYPE &, int)\*(C'\fR, it receives the watcher as ``` ```first argument and the \f(CW\*(C`revents\*(C'\fR as second. The object must be given as ``` ```parameter and is stored in the \f(CW\*(C`data\*(C'\fR member of the watcher. ``` ```.Sp ``` ```This method synthesizes efficient thunking code to call your method from ``` ```the C callback that libev requires. If your compiler can inline your ``` ```callback (i.e. it is visible to it at the place of the \f(CW\*(C`set\*(C'\fR call and ``` ```your compiler is good :), then the method will be fully inlined into the ``` ```thunking function, making it as fast as a direct C callback. ``` ```.Sp ``` ```Example: simple class declaration and watcher initialisation ``` ```.Sp ``` ```.Vb 4 ``` ```\& struct myclass ``` ```\& { ``` ```\& void io_cb (ev::io &w, int revents) { } ``` ```\& } ``` ```\& ``` ```\& myclass obj; ``` ```\& ev::io iow; ``` ```\& iow.set (&obj); ``` ```.Ve ``` ```.IP "w\->set (void *data = 0)" 4 ``` ```.IX Item "w->set (void *data = 0)" ``` ```Also sets a callback, but uses a static method or plain function as ``` ```callback. The optional \f(CW\*(C`data\*(C'\fR argument will be stored in the watcher's ``` ```\&\f(CW\*(C`data\*(C'\fR member and is free for you to use. ``` ```.Sp ``` ```The prototype of the \f(CW\*(C`function\*(C'\fR must be \f(CW\*(C`void (*)(ev::TYPE &w, int)\*(C'\fR. ``` ```.Sp ``` ```See the method\-\f(CW\*(C`set\*(C'\fR above for more details. ``` ```.Sp ``` ```Example: Use a plain function as callback. ``` ```.Sp ``` ```.Vb 2 ``` ```\& static void io_cb (ev::io &w, int revents) { } ``` ```\& iow.set (); ``` ```.Ve ``` ```.IP "w\->set (struct ev_loop *)" 4 ``` ```.IX Item "w->set (struct ev_loop *)" ``` ```Associates a different \f(CW\*(C`struct ev_loop\*(C'\fR with this watcher. You can only ``` ```do this when the watcher is inactive (and not pending either). ``` ```.IP "w\->set ([arguments])" 4 ``` ```.IX Item "w->set ([arguments])" ``` ```Basically the same as \f(CW\*(C`ev_TYPE_set\*(C'\fR, with the same arguments. Must be ``` ```called at least once. Unlike the C counterpart, an active watcher gets ``` ```automatically stopped and restarted when reconfiguring it with this ``` ```method. ``` ```.IP "w\->start ()" 4 ``` ```.IX Item "w->start ()" ``` ```Starts the watcher. Note that there is no \f(CW\*(C`loop\*(C'\fR argument, as the ``` ```constructor already stores the event loop. ``` ```.IP "w\->stop ()" 4 ``` ```.IX Item "w->stop ()" ``` ```Stops the watcher if it is active. Again, no \f(CW\*(C`loop\*(C'\fR argument. ``` ```.ie n .IP "w\->again () (""ev::timer""\fR, \f(CW""ev::periodic"" only)" 4 ``` ```.el .IP "w\->again () (\f(CWev::timer\fR, \f(CWev::periodic\fR only)" 4 ``` ```.IX Item "w->again () (ev::timer, ev::periodic only)" ``` ```For \f(CW\*(C`ev::timer\*(C'\fR and \f(CW\*(C`ev::periodic\*(C'\fR, this invokes the corresponding ``` ```\&\f(CW\*(C`ev_TYPE_again\*(C'\fR function. ``` ```.ie n .IP "w\->sweep () (""ev::embed"" only)" 4 ``` ```.el .IP "w\->sweep () (\f(CWev::embed\fR only)" 4 ``` ```.IX Item "w->sweep () (ev::embed only)" ``` ```Invokes \f(CW\*(C`ev_embed_sweep\*(C'\fR. ``` ```.ie n .IP "w\->update () (""ev::stat"" only)" 4 ``` ```.el .IP "w\->update () (\f(CWev::stat\fR only)" 4 ``` ```.IX Item "w->update () (ev::stat only)" ``` ```Invokes \f(CW\*(C`ev_stat_stat\*(C'\fR. ``` ```.RE ``` ```.RS 4 ``` ```.RE ``` ```.PP ``` ```Example: Define a class with an \s-1IO\s0 and idle watcher, start one of them in ``` ```the constructor. ``` ```.PP ``` ```.Vb 4 ``` ```\& class myclass ``` ```\& { ``` ```\& ev::io io ; void io_cb (ev::io &w, int revents); ``` ```\& ev::idle idle; void idle_cb (ev::idle &w, int revents); ``` ```\& ``` ```\& myclass (int fd) ``` ```\& { ``` ```\& io .set (this); ``` ```\& idle.set (this); ``` ```\& ``` ```\& io.start (fd, ev::READ); ``` ```\& } ``` ```\& }; ``` ```.Ve ``` ```.SH "OTHER LANGUAGE BINDINGS" ``` ```.IX Header "OTHER LANGUAGE BINDINGS" ``` ```Libev does not offer other language bindings itself, but bindings for a ``` ```number of languages exist in the form of third-party packages. If you know ``` ```any interesting language binding in addition to the ones listed here, drop ``` ```me a note. ``` ```.IP "Perl" 4 ``` ```.IX Item "Perl" ``` ```The \s-1EV\s0 module implements the full libev \s-1API\s0 and is actually used to test ``` ```libev. \s-1EV\s0 is developed together with libev. Apart from the \s-1EV\s0 core module, ``` ```there are additional modules that implement libev-compatible interfaces ``` ```to \f(CW\*(C`libadns\*(C'\fR (\f(CW\*(C`EV::ADNS\*(C'\fR, but \f(CW\*(C`AnyEvent::DNS\*(C'\fR is preferred nowadays), ``` ```\&\f(CW\*(C`Net::SNMP\*(C'\fR (\f(CW\*(C`Net::SNMP::EV\*(C'\fR) and the \f(CW\*(C`libglib\*(C'\fR event core (\f(CW\*(C`Glib::EV\*(C'\fR ``` ```and \f(CW\*(C`EV::Glib\*(C'\fR). ``` ```.Sp ``` ```It can be found and installed via \s-1CPAN\s0, its homepage is at ``` ```. ``` ```.IP "Python" 4 ``` ```.IX Item "Python" ``` ```Python bindings can be found at . It ``` ```seems to be quite complete and well-documented. Note, however, that the ``` ```patch they require for libev is outright dangerous as it breaks the \s-1ABI\s0 ``` ```for everybody else, and therefore, should never be applied in an installed ``` ```libev (if python requires an incompatible \s-1ABI\s0 then it needs to embed ``` ```libev). ``` ```.IP "Ruby" 4 ``` ```.IX Item "Ruby" ``` ```Tony Arcieri has written a ruby extension that offers access to a subset ``` ```of the libev \s-1API\s0 and adds file handle abstractions, asynchronous \s-1DNS\s0 and ``` ```more on top of it. It can be found via gem servers. Its homepage is at ``` ```. ``` ```.IP "D" 4 ``` ```.IX Item "D" ``` ```Leandro Lucarella has written a D language binding (\fIev.d\fR) for libev, to ``` ```be found at . ``` ```.IP "Ocaml" 4 ``` ```.IX Item "Ocaml" ``` ```Erkki Seppala has written Ocaml bindings for libev, to be found at ``` ```. ``` ```.SH "MACRO MAGIC" ``` ```.IX Header "MACRO MAGIC" ``` ```Libev can be compiled with a variety of options, the most fundamental ``` ```of which is \f(CW\*(C`EV_MULTIPLICITY\*(C'\fR. This option determines whether (most) ``` ```functions and callbacks have an initial \f(CW\*(C`struct ev_loop *\*(C'\fR argument. ``` ```.PP ``` ```To make it easier to write programs that cope with either variant, the ``` ```following macros are defined: ``` ```.ie n .IP """EV_A""\fR, \f(CW""EV_A_""" 4 ``` ```.el .IP "\f(CWEV_A\fR, \f(CWEV_A_\fR" 4 ``` ```.IX Item "EV_A, EV_A_" ``` ```This provides the loop \fIargument\fR for functions, if one is required (\*(L"ev ``` ```loop argument\*(R"). The \f(CW\*(C`EV_A\*(C'\fR form is used when this is the sole argument, ``` ```\&\f(CW\*(C`EV_A_\*(C'\fR is used when other arguments are following. Example: ``` ```.Sp ``` ```.Vb 3 ``` ```\& ev_unref (EV_A); ``` ```\& ev_timer_add (EV_A_ watcher); ``` ```\& ev_loop (EV_A_ 0); ``` ```.Ve ``` ```.Sp ``` ```It assumes the variable \f(CW\*(C`loop\*(C'\fR of type \f(CW\*(C`struct ev_loop *\*(C'\fR is in scope, ``` ```which is often provided by the following macro. ``` ```.ie n .IP """EV_P""\fR, \f(CW""EV_P_""" 4 ``` ```.el .IP "\f(CWEV_P\fR, \f(CWEV_P_\fR" 4 ``` ```.IX Item "EV_P, EV_P_" ``` ```This provides the loop \fIparameter\fR for functions, if one is required (\*(L"ev ``` ```loop parameter\*(R"). The \f(CW\*(C`EV_P\*(C'\fR form is used when this is the sole parameter, ``` ```\&\f(CW\*(C`EV_P_\*(C'\fR is used when other parameters are following. Example: ``` ```.Sp ``` ```.Vb 2 ``` ```\& // this is how ev_unref is being declared ``` ```\& static void ev_unref (EV_P); ``` ```\& ``` ```\& // this is how you can declare your typical callback ``` ```\& static void cb (EV_P_ ev_timer *w, int revents) ``` ```.Ve ``` ```.Sp ``` ```It declares a parameter \f(CW\*(C`loop\*(C'\fR of type \f(CW\*(C`struct ev_loop *\*(C'\fR, quite ``` ```suitable for use with \f(CW\*(C`EV_A\*(C'\fR. ``` ```.ie n .IP """EV_DEFAULT""\fR, \f(CW""EV_DEFAULT_""" 4 ``` ```.el .IP "\f(CWEV_DEFAULT\fR, \f(CWEV_DEFAULT_\fR" 4 ``` ```.IX Item "EV_DEFAULT, EV_DEFAULT_" ``` ```Similar to the other two macros, this gives you the value of the default ``` ```loop, if multiple loops are supported (\*(L"ev loop default\*(R"). ``` ```.ie n .IP """EV_DEFAULT_UC""\fR, \f(CW""EV_DEFAULT_UC_""" 4 ``` ```.el .IP "\f(CWEV_DEFAULT_UC\fR, \f(CWEV_DEFAULT_UC_\fR" 4 ``` ```.IX Item "EV_DEFAULT_UC, EV_DEFAULT_UC_" ``` ```Usage identical to \f(CW\*(C`EV_DEFAULT\*(C'\fR and \f(CW\*(C`EV_DEFAULT_\*(C'\fR, but requires that the ``` ```default loop has been initialised (\f(CW\*(C`UC\*(C'\fR == unchecked). Their behaviour ``` ```is undefined when the default loop has not been initialised by a previous ``` ```execution of \f(CW\*(C`EV_DEFAULT\*(C'\fR, \f(CW\*(C`EV_DEFAULT_\*(C'\fR or \f(CW\*(C`ev_default_init (...)\*(C'\fR. ``` ```.Sp ``` ```It is often prudent to use \f(CW\*(C`EV_DEFAULT\*(C'\fR when initialising the first ``` ```watcher in a function but use \f(CW\*(C`EV_DEFAULT_UC\*(C'\fR afterwards. ``` ```.PP ``` ```Example: Declare and initialise a check watcher, utilising the above ``` ```macros so it will work regardless of whether multiple loops are supported ``` ```or not. ``` ```.PP ``` ```.Vb 5 ``` ```\& static void ``` ```\& check_cb (EV_P_ ev_timer *w, int revents) ``` ```\& { ``` ```\& ev_check_stop (EV_A_ w); ``` ```\& } ``` ```\& ``` ```\& ev_check check; ``` ```\& ev_check_init (&check, check_cb); ``` ```\& ev_check_start (EV_DEFAULT_ &check); ``` ```\& ev_loop (EV_DEFAULT_ 0); ``` ```.Ve ``` ```.SH "EMBEDDING" ``` ```.IX Header "EMBEDDING" ``` ```Libev can (and often is) directly embedded into host ``` ```applications. Examples of applications that embed it include the Deliantra ``` ```Game Server, the \s-1EV\s0 perl module, the \s-1GNU\s0 Virtual Private Ethernet (gvpe) ``` ```and rxvt-unicode. ``` ```.PP ``` ```The goal is to enable you to just copy the necessary files into your ``` ```source directory without having to change even a single line in them, so ``` ```you can easily upgrade by simply copying (or having a checked-out copy of ``` ```libev somewhere in your source tree). ``` ```.Sh "\s-1FILESETS\s0" ``` ```.IX Subsection "FILESETS" ``` ```Depending on what features you need you need to include one or more sets of files ``` ```in your application. ``` ```.PP ``` ```\fI\s-1CORE\s0 \s-1EVENT\s0 \s-1LOOP\s0\fR ``` ```.IX Subsection "CORE EVENT LOOP" ``` ```.PP ``` ```To include only the libev core (all the \f(CW\*(C`ev_*\*(C'\fR functions), with manual ``` ```configuration (no autoconf): ``` ```.PP ``` ```.Vb 2 ``` ```\& #define EV_STANDALONE 1 ``` ```\& #include "ev.c" ``` ```.Ve ``` ```.PP ``` ```This will automatically include \fIev.h\fR, too, and should be done in a ``` ```single C source file only to provide the function implementations. To use ``` ```it, do the same for \fIev.h\fR in all files wishing to use this \s-1API\s0 (best ``` ```done by writing a wrapper around \fIev.h\fR that you can include instead and ``` ```where you can put other configuration options): ``` ```.PP ``` ```.Vb 2 ``` ```\& #define EV_STANDALONE 1 ``` ```\& #include "ev.h" ``` ```.Ve ``` ```.PP ``` ```Both header files and implementation files can be compiled with a \*(C+ ``` ```compiler (at least, that's a stated goal, and breakage will be treated ``` ```as a bug). ``` ```.PP ``` ```You need the following files in your source tree, or in a directory ``` ```in your include path (e.g. in libev/ when using \-Ilibev): ``` ```.PP ``` ```.Vb 4 ``` ```\& ev.h ``` ```\& ev.c ``` ```\& ev_vars.h ``` ```\& ev_wrap.h ``` ```\& ``` ```\& ev_win32.c required on win32 platforms only ``` ```\& ``` ```\& ev_select.c only when select backend is enabled (which is enabled by default) ``` ```\& ev_poll.c only when poll backend is enabled (disabled by default) ``` ```\& ev_epoll.c only when the epoll backend is enabled (disabled by default) ``` ```\& ev_kqueue.c only when the kqueue backend is enabled (disabled by default) ``` ```\& ev_port.c only when the solaris port backend is enabled (disabled by default) ``` ```.Ve ``` ```.PP ``` ```\&\fIev.c\fR includes the backend files directly when enabled, so you only need ``` ```to compile this single file. ``` ```.PP ``` ```\fI\s-1LIBEVENT\s0 \s-1COMPATIBILITY\s0 \s-1API\s0\fR ``` ```.IX Subsection "LIBEVENT COMPATIBILITY API" ``` ```.PP ``` ```To include the libevent compatibility \s-1API\s0, also include: ``` ```.PP ``` ```.Vb 1 ``` ```\& #include "event.c" ``` ```.Ve ``` ```.PP ``` ```in the file including \fIev.c\fR, and: ``` ```.PP ``` ```.Vb 1 ```