From 6718627e9d47a9a658465c2f20fe6edd40138608 Mon Sep 17 00:00:00 2001 From: wangyu- Date: Wed, 29 Aug 2018 02:03:10 -0500 Subject: [PATCH] added libev files --- libev/CVS/Entries | 31 + libev/CVS/Repository | 1 + libev/CVS/Root | 1 + libev/Changes | 517 ++++ libev/LICENSE | 37 + libev/Makefile.am | 20 + libev/README | 58 + libev/README.embed | 3 + libev/Symbols.ev | 73 + libev/Symbols.event | 24 + libev/autogen.sh | 3 + libev/configure.ac | 27 + libev/ev++.h | 816 ++++++ libev/ev.3 | 5647 +++++++++++++++++++++++++++++++++++++++++ libev/ev.c | 5144 +++++++++++++++++++++++++++++++++++++ libev/ev.h | 854 +++++++ libev/ev.pod | 5570 ++++++++++++++++++++++++++++++++++++++++ libev/ev_epoll.c | 285 +++ libev/ev_kqueue.c | 218 ++ libev/ev_poll.c | 151 ++ libev/ev_port.c | 189 ++ libev/ev_select.c | 316 +++ libev/ev_vars.h | 204 ++ libev/ev_win32.c | 162 ++ libev/ev_wrap.h | 200 ++ libev/event.c | 425 ++++ libev/event.h | 177 ++ libev/event_compat.h | 226 ++ libev/import_libevent | 131 + libev/libev.m4 | 42 + libev/update_ev_c | 8 + libev/update_ev_wrap | 19 + libev/update_symbols | 7 + makefile | 2 +- my_ev.cpp | 16 + my_ev.h | 5 + my_ev_common.h | 18 + 37 files changed, 21626 insertions(+), 1 deletion(-) create mode 100644 libev/CVS/Entries create mode 100644 libev/CVS/Repository create mode 100644 libev/CVS/Root create mode 100644 libev/Changes create mode 100644 libev/LICENSE create mode 100644 libev/Makefile.am create mode 100644 libev/README create mode 100644 libev/README.embed create mode 100644 libev/Symbols.ev create mode 100644 libev/Symbols.event create mode 100644 libev/autogen.sh create mode 100644 libev/configure.ac create mode 100644 libev/ev++.h create mode 100644 libev/ev.3 create mode 100644 libev/ev.c create mode 100644 libev/ev.h create mode 100644 libev/ev.pod create mode 100644 libev/ev_epoll.c create mode 100644 libev/ev_kqueue.c create mode 100644 libev/ev_poll.c create mode 100644 libev/ev_port.c create mode 100644 libev/ev_select.c create mode 100644 libev/ev_vars.h create mode 100644 libev/ev_win32.c create mode 100644 libev/ev_wrap.h create mode 100644 libev/event.c create mode 100644 libev/event.h create mode 100644 libev/event_compat.h create mode 100755 libev/import_libevent create mode 100644 libev/libev.m4 create mode 100755 libev/update_ev_c create mode 100755 libev/update_ev_wrap create mode 100755 libev/update_symbols create mode 100644 my_ev.cpp create mode 100644 my_ev.h create mode 100644 my_ev_common.h diff --git a/libev/CVS/Entries b/libev/CVS/Entries new file mode 100644 index 0000000..5e21fb8 --- /dev/null +++ b/libev/CVS/Entries @@ -0,0 +1,31 @@ +/Changes/1.315/Wed Jun 21 14:42:30 2017// +/LICENSE/1.11/Thu Jan 16 11:51:05 2014// +/Makefile.am/1.9/Wed Dec 21 18:16:08 2011// +/README/1.21/Fri Mar 30 17:43:55 2012// +/README.embed/1.29/Sat Nov 24 10:10:26 2007// +/Symbols.ev/1.14/Tue Jan 11 13:45:28 2011// +/Symbols.event/1.4/Tue May 8 15:52:13 2012// +/autogen.sh/1.3/Mon May 30 15:28:54 2011// +/configure.ac/1.42/Wed Dec 28 04:22:06 2016// +/ev++.h/1.63/Fri Dec 1 06:37:30 2017// +/ev.3/1.107/Wed Jun 21 14:42:30 2017// +/ev.c/1.481/Thu Jun 1 20:25:50 2017// +/ev.h/1.187/Wed Dec 28 04:22:06 2016// +/ev.pod/1.441/Thu Jul 13 10:46:52 2017// +/ev_epoll.c/1.72/Wed Jun 21 14:42:30 2017// +/ev_kqueue.c/1.56/Thu Feb 18 04:48:05 2016// +/ev_poll.c/1.40/Thu Feb 18 04:48:05 2016// +/ev_port.c/1.29/Thu Feb 18 04:48:05 2016// +/ev_select.c/1.56/Thu Feb 18 04:48:05 2016// +/ev_vars.h/1.58/Tue Sep 9 21:51:35 2014// +/ev_win32.c/1.18/Thu Nov 12 07:02:37 2015// +/ev_wrap.h/1.38/Tue Nov 6 20:56:50 2012// +/event.c/1.52/Mon Apr 2 23:14:41 2012// +/event.h/1.26/Mon Apr 2 23:15:27 2012// +/event_compat.h/1.8/Wed Feb 16 08:02:51 2011// +/import_libevent/1.29/Tue Apr 15 04:34:07 2008// +/libev.m4/1.16/Mon Oct 28 12:36:44 2013// +/update_ev_c/1.2/Wed Jan 18 12:13:14 2012// +/update_ev_wrap/1.6/Sun May 6 13:09:29 2012// +/update_symbols/1.1/Wed Dec 19 01:59:29 2007// +D diff --git a/libev/CVS/Repository b/libev/CVS/Repository new file mode 100644 index 0000000..16429a4 --- /dev/null +++ b/libev/CVS/Repository @@ -0,0 +1 @@ +libev diff --git a/libev/CVS/Root b/libev/CVS/Root new file mode 100644 index 0000000..4f19ed2 --- /dev/null +++ b/libev/CVS/Root @@ -0,0 +1 @@ +:pserver:anonymous@cvs.schmorp.de/schmorpforge diff --git a/libev/Changes b/libev/Changes new file mode 100644 index 0000000..9968527 --- /dev/null +++ b/libev/Changes @@ -0,0 +1,517 @@ +Revision history for libev, a high-performance and full-featured event loop. + + - ANDROID => __ANDROID__ (reported by enh@google.com). + - disable epoll_create1 on android because it has broken header files + and google is unwilling to fix them (reported by enh@google.com). + +4.24 Wed Dec 28 05:19:55 CET 2016 + - bump version to 4.24, as the release tarball inexplicably + didn't have the right version in ev.h, even though the cvs-tagged + version did have the right one (reported by Ales Teska). + +4.23 Wed Nov 16 18:23:41 CET 2016 + - move some declarations at the beginning to help certain retarded + microsoft compilers, even though their documentation claims + otherwise (reported by Ruslan Osmanov). + +4.22 Sun Dec 20 22:11:50 CET 2015 + - when epoll detects unremovable fds in the fd set, rebuild + only the epoll descriptor, not the signal pipe, to avoid + SIGPIPE in ev_async_send. This doesn't solve it on fork, + so document what needs to be done in ev_loop_fork + (analyzed by Benjamin Mahler). + - remove superfluous sys/timeb.h include on win32 + (analyzed by Jason Madden). + - updated libecb. + +4.20 Sat Jun 20 13:01:43 CEST 2015 + - prefer noexcept over throw () with C++ 11. + - update ecb.h due to incompatibilities with c11. + - fix a potential aliasing issue when reading and writing + watcher callbacks. + +4.19 Thu Sep 25 08:18:25 CEST 2014 + - ev.h wasn't valid C++ anymore, which tripped compilers other than + clang, msvc or gcc (analyzed by Raphael 'kena' Poss). Unfortunately, + C++ doesn't support typedefs for function pointers fully, so the affected + declarations have to spell out the types each time. + - when not using autoconf, tighten the check for clock_gettime and related + functionality. + +4.18 Fri Sep 5 17:55:26 CEST 2014 + - events on files were not always generated properly with the + epoll backend (testcase by Assaf Inbal). + - mark event pipe fd as cloexec after a fork (analyzed by Sami Farin). + - (ecb) support m68k, m88k and sh (patch by Miod Vallat). + - use a reasonable fallback for EV_NSIG instead of erroring out + when we can't detect the signal set size. + - in the absence of autoconf, do not use the clock syscall + on glibc >= 2.17 (avoids the syscall AND -lrt on systems + doing clock_gettime in userspace). + - ensure extern "C" function pointers are used for externally-visible + loop callbacks (not watcher callbacks yet). + - (ecb) work around memory barriers and volatile apparently both being + broken in visual studio 2008 and later (analysed and patch by Nicolas Noble). + +4.15 Fri Mar 1 12:04:50 CET 2013 + - destroying a non-default loop would stop the global waitpid + watcher (Denis Bilenko). + - queueing pending watchers of higher priority from a watcher now invokes + them in a timely fashion (reported by Denis Bilenko). + - add throw() to all libev functions that cannot throw exceptions, for + further code size decrease when compiling for C++. + - add throw () to callbacks that must not throw exceptions (allocator, + syserr, loop acquire/release, periodic reschedule cbs). + - fix event_base_loop return code, add event_get_callback, event_base_new, + event_base_get_method calls to improve libevent 1.x emulation and add + some libevent 2.x functionality (based on a patch by Jeff Davey). + - add more memory fences to fix a bug reported by Jeff Davey. Better + be overfenced than underprotected. + - ev_run now returns a boolean status (true meaning watchers are + still active). + - ev_once: undef EV_ERROR in ev_kqueue.c, to avoid clashing with + libev's EV_ERROR (reported by 191919). + - (ecb) add memory fence support for xlC (Darin McBride). + - (ecb) add memory fence support for gcc-mips (Anton Kirilov). + - (ecb) add memory fence support for gcc-alpha (Christian Weisgerber). + - work around some kernels losing file descriptors by leaking + the kqueue descriptor in the child. + - work around linux inotify not reporting IN_ATTRIB changes for directories + in many cases. + - include sys/syscall.h instead of plain syscall.h. + - check for io watcher loops in ev_verify, check for the most + common reported usage bug in ev_io_start. + - choose socket vs. WSASocket at compiletime using EV_USE_WSASOCKET. + - always use WSASend/WSARecv directly on windows, hoping that this + works in all cases (unlike read/write/send/recv...). + - try to detect signals around a fork faster (test program by + Denis Bilenko). + - work around recent glibc versions that leak memory in realloc. + - rename ev::embed::set to ev::embed::set_embed to avoid clashing + the watcher base set (loop) method. + - rewrite the async/signal pipe logic to always keep a valid fd, which + simplifies (and hopefully correctifies :) the race checking + on fork, at the cost of one extra fd. + - add fat, msdos, jffs2, ramfs, ntfs and btrfs to the list of + inotify-supporting filesystems. + - move orig_CFLAGS assignment to after AC_INIT, as newer autoconf + versions ignore it before + (https://bugzilla.redhat.com/show_bug.cgi?id=908096). + - add some untested android support. + - enum expressions must be of type int (reported by Juan Pablo L). + +4.11 Sat Feb 4 19:52:39 CET 2012 + - INCOMPATIBLE CHANGE: ev_timer_again now clears the pending status, as + was documented already, but not implemented in the repeating case. + - new compiletime symbols: EV_NO_SMP and EV_NO_THREADS. + - fix a race where the workaround against the epoll fork bugs + caused signals to not be handled anymore. + - correct backend_fudge for most backends, and implement a windows + specific workaround to avoid looping because we call both + select and Sleep, both with different time resolutions. + - document range and guarantees of ev_sleep. + - document reasonable ranges for periodics interval and offset. + - rename backend_fudge to backend_mintime to avoid future confusion :) + - change the default periodic reschedule function to hopefully be more + exact and correct even in corner cases or in the far future. + - do not rely on -lm anymore: use it when available but use our + own floor () if it is missing. This should make it easier to embed, + as no external libraries are required. + - strategically import macros from libecb and mark rarely-used functions + as cache-cold (saving almost 2k code size on typical amd64 setups). + - add Symbols.ev and Symbols.event files, that were missing. + - fix backend_mintime value for epoll (was 1/1024, is 1/1000 now). + - fix #3 "be smart about timeouts" to not "deadlock" when + timeout == now, also improve the section overall. + - avoid "AVOIDING FINISHING BEFORE RETURNING" idiom. + - support new EV_API_STATIC mode to make all libev symbols + static. + - supply default CFLAGS of -g -O3 with gcc when original CFLAGS + were empty. + +4.04 Wed Feb 16 09:01:51 CET 2011 + - fix two problems in the native win32 backend, where reuse of fd's + with different underlying handles caused handles not to be removed + or added to the select set (analyzed and tested by Bert Belder). + - do no rely on ceil() in ev_e?poll.c. + - backport libev to HP-UX versions before 11 v3. + - configure did not detect nanosleep and clock_gettime properly when + they are available in the libc (as opposed to -lrt). + +4.03 Tue Jan 11 14:37:25 CET 2011 + - officially support polling files with all backends. + - support files, /dev/zero etc. the same way as select in the epoll + backend, by generating events on our own. + - ports backend: work around solaris bug 6874410 and many related ones + (EINTR, maybe more), with no performance loss (note that the solaris + bug report is actually wrong, reality is far more bizarre and broken + than that). + - define EV_READ/EV_WRITE as macros in event.h, as some programs use + #ifdef to test for them. + - new (experimental) function: ev_feed_signal. + - new (to become default) EVFLAG_NOSIGMASK flag. + - new EVBACKEND_MASK symbol. + - updated COMMON IDIOMS SECTION. + +4.01 Fri Nov 5 21:51:29 CET 2010 + - automake fucked it up, apparently, --add-missing -f is not quite enough + to make it update its files, so 4.00 didn't install ev++.h and + event.h on make install. grrr. + - ev_loop(count|depth) didn't return anything (Robin Haberkorn). + - change EV_UNDEF to 0xffffffff to silence some overzealous compilers. + - use "(libev) " prefix for all libev error messages now. + +4.00 Mon Oct 25 12:32:12 CEST 2010 + - "PORTING FROM LIBEV 3.X TO 4.X" (in ev.pod) is recommended reading. + - ev_embed_stop did not correctly stop the watcher (very good + testcase by Vladimir Timofeev). + - ev_run will now always update the current loop time - it erroneously + didn't when idle watchers were active, causing timers not to fire. + - fix a bug where a timeout of zero caused the timer not to fire + in the libevent emulation (testcase by Péter Szabó). + - applied win32 fixes by Michael Lenaghan (also James Mansion). + - replace EV_MINIMAL by EV_FEATURES. + - prefer EPOLL_CTL_ADD over EPOLL_CTL_MOD in some more cases, as it + seems the former is *much* faster than the latter. + - linux kernel version detection (for inotify bug workarounds) + did not work properly. + - reduce the number of spurious wake-ups with the ports backend. + - remove dependency on sys/queue.h on freebsd (patch by Vanilla Hsu). + - do async init within ev_async_start, not ev_async_set, which avoids + an API quirk where the set function must be called in the C++ API + even when there is nothing to set. + - add (undocumented) EV_ENABLE when adding events with kqueue, + this might help with OS X, which seems to need it despite documenting + not to need it (helpfully pointed out by Tilghman Lesher). + - do not use poll by default on freebsd, it's broken (what isn't + on freebsd...). + - allow to embed epoll on kernels >= 2.6.32. + - configure now prepends -O3, not appends it, so one can still + override it. + - ev.pod: greatly expanded the portability section, added a porting + section, a description of watcher states and made lots of minor fixes. + - disable poll backend on AIX, the poll header spams the namespace + and it's not worth working around dead platforms (reported + and analyzed by Aivars Kalvans). + - improve header file compatibility of the standalone eventfd code + in an obscure case. + - implement EV_AVOID_STDIO option. + - do not use sscanf to parse linux version number (smaller, faster, + no sscanf dependency). + - new EV_CHILD_ENABLE and EV_SIGNAL_ENABLE configurable settings. + - update libev.m4 HAVE_CLOCK_SYSCALL test for newer glibcs. + - add section on accept() problems to the manpage. + - rename EV_TIMEOUT to EV_TIMER. + - rename ev_loop_count/depth/verify/loop/unloop. + - remove ev_default_destroy and ev_default_fork. + - switch to two-digit minor version. + - work around an apparent gentoo compiler bug. + - define _DARWIN_UNLIMITED_SELECT. just so. + - use enum instead of #define for most constants. + - improve compatibility to older C++ compilers. + - (experimental) ev_run/ev_default_loop/ev_break/ev_loop_new have now + default arguments when compiled as C++. + - enable automake dependency tracking. + - ev_loop_new no longer leaks memory when loop creation failed. + - new ev_cleanup watcher type. + +3.9 Thu Dec 31 07:59:59 CET 2009 + - signalfd is no longer used by default and has to be requested + explicitly - this means that easy to catch bugs become hard to + catch race conditions, but the users have spoken. + - point out the unspecified signal mask in the documentation, and + that this is a race condition regardless of EV_SIGNALFD. + - backport inotify code to C89. + - inotify file descriptors could leak into child processes. + - ev_stat watchers could keep an erroneous extra ref on the loop, + preventing exit when unregistering all watchers (testcases + provided by ry@tinyclouds.org). + - implement EV_WIN32_HANDLE_TO_FD and EV_WIN32_CLOSE_FD configuration + symbols to make it easier for apps to do their own fd management. + - support EV_IDLE_ENABLE being disabled in ev++.h + (patch by Didier Spezia). + - take advantage of inotify_init1, if available, to set cloexec/nonblock + on fd creation, to avoid races. + - the signal handling pipe wasn't always initialised under windows + (analysed by lekma). + - changed minimum glibc requirement from glibc 2.9 to 2.7, for + signalfd. + - add missing string.h include (Denis F. Latypoff). + - only replace ev_stat.prev when we detect an actual difference, + so prev is (almost) always different to attr. this might + have caused the problems with 04_stat.t. + - add ev::timer->remaining () method to C++ API. + +3.8 Sun Aug 9 14:30:45 CEST 2009 + - incompatible change: do not necessarily reset signal handler + to SIG_DFL when a sighandler is stopped. + - ev_default_destroy did not properly free or zero some members, + potentially causing crashes and memory corruption on repeated + ev_default_destroy/ev_default_loop calls. + - take advantage of signalfd on GNU/Linux systems. + - document that the signal mask might be in an unspecified + state when using libev's signal handling. + - take advantage of some GNU/Linux calls to set cloexec/nonblock + on fd creation, to avoid race conditions. + +3.7 Fri Jul 17 16:36:32 CEST 2009 + - ev_unloop and ev_loop wrongly used a global variable to exit loops, + instead of using a per-loop variable (bug caught by accident...). + - the ev_set_io_collect_interval interpretation has changed. + - add new functionality: ev_set_userdata, ev_userdata, + ev_set_invoke_pending_cb, ev_set_loop_release_cb, + ev_invoke_pending, ev_pending_count, together with a long example + about thread locking. + - add ev_timer_remaining (as requested by Denis F. Latypoff). + - add ev_loop_depth. + - calling ev_unloop in fork/prepare watchers will no longer poll + for new events. + - Denis F. Latypoff corrected many typos in example code snippets. + - honor autoconf detection of EV_USE_CLOCK_SYSCALL, also double- + check that the syscall number is available before trying to + use it (reported by ry@tinyclouds). + - use GetSystemTimeAsFileTime instead of _timeb on windows, for + slightly higher accuracy. + - properly declare ev_loop_verify and ev_now_update even when + !EV_MULTIPLICITY. + - do not compile in any priority code when EV_MAXPRI == EV_MINPRI. + - support EV_MINIMAL==2 for a reduced API. + - actually 0-initialise struct sigaction when installing signals. + - add section on hibernate and stopped processes to ev_timer docs. + +3.6 Tue Apr 28 02:49:30 CEST 2009 + - multiple timers becoming ready within an event loop iteration + will be invoked in the "correct" order now. + - do not leave the event loop early just because we have no active + watchers, fixing a problem when embedding a kqueue loop + that has active kernel events but no registered watchers + (reported by blacksand blacksand). + - correctly zero the idx values for arrays, so destroying and + reinitialising the default loop actually works (patch by + Malek Hadj-Ali). + - implement ev_suspend and ev_resume. + - new EV_CUSTOM revents flag for use by applications. + - add documentation section about priorities. + - add a glossary to the documentation. + - extend the ev_fork description slightly. + - optimize a jump out of call_pending. + +3.53 Sun Feb 15 02:38:20 CET 2009 + - fix a bug in event pipe creation on win32 that would cause a + failed assertion on event loop creation (patch by Malek Hadj-Ali). + - probe for CLOCK_REALTIME support at runtime as well and fall + back to gettimeofday if there is an error, to support older + operating systems with newer header files/libraries. + - prefer gettimeofday over clock_gettime with USE_CLOCK_SYSCALL + (default most everywhere), otherwise not. + +3.52 Wed Jan 7 21:43:02 CET 2009 + - fix compilation of select backend in fd_set mode when NFDBITS is + missing (to get it to compile on QNX, reported by Rodrigo Campos). + - better select-nfds handling when select backend is in fd_set mode. + - diagnose fd_set overruns when select backend is in fd_set mode. + - due to a thinko, instead of disabling everything but + select on the borked OS X platform, everything but select was + allowed (reported by Emanuele Giaquinta). + - actually verify that local and remote port are matching in + libev's socketpair emulation, which makes denial-of-service + attacks harder (but not impossible - it's windows). Make sure + it even works under vista, which thinks that getpeer/sockname + should return fantasy port numbers. + - include "libev" in all assertion messages for potentially + clearer diagnostics. + - event_get_version (libevent compatibility) returned + a useless string instead of the expected version string + (patch by W.C.A. Wijngaards). + +3.51 Wed Dec 24 23:00:11 CET 2008 + - fix a bug where an inotify watcher was added twice, causing + freezes on hash collisions (reported and analysed by Graham Leggett). + - new config symbol, EV_USE_CLOCK_SYSCALL, to make libev use + a direct syscall - slower, but no dependency on librt et al. + - assume negative return values != -1 signals success of port_getn + (http://cvs.epicsol.org/cgi/viewcvs.cgi/epic5/source/newio.c?rev=1.52) + (no known failure reports, but it doesn't hurt). + - fork detection in ev_embed now stops and restarts the watcher + automatically. + - EXPERIMENTAL: default the method to operator () in ev++.h, + to make it nicer to use functors (requested by Benedek László). + - fixed const object callbacks in ev++.h. + - replaced loop_ref argument of watcher.set (loop) by a direct + ev_loop * in ev++.h, to avoid clashes with functor patch. + - do not try to watch the empty string via inotify. + - inotify watchers could be leaked under certain circumstances. + - OS X 10.5 is actually even more broken than earlier versions, + so fall back to select on that piece of garbage. + - fixed some weirdness in the ev_embed documentation. + +3.49 Wed Nov 19 11:26:53 CET 2008 + - ev_stat watchers will now use inotify as a mere hint on + kernels <2.6.25, or if the filesystem is not in the + "known to be good" list. + - better mingw32 compatibility (it's not as borked as native win32) + (analysed by Roger Pack). + - include stdio.h in the example program, as too many people are + confused by the weird C language otherwise. I guess the next thing + I get told is that the "..." ellipses in the examples don't compile + with their C compiler. + +3.48 Thu Oct 30 09:02:37 CET 2008 + - further optimise away the EPOLL_CTL_ADD/MOD combo in the epoll + backend by assuming the kernel event mask hasn't changed if + ADD fails with EEXIST. + - work around spurious event notification bugs in epoll by using + a 32-bit generation counter. recreate kernel state if we receive + spurious notifications or unwanted events. this is very costly, + but I didn't come up with this horrible design. + - use memset to initialise most arrays now and do away with the + init functions. + - expand time-out strategies into a "Be smart about timeouts" section. + - drop the "struct" from all ev_watcher declarations in the + documentation and did other clarifications (yeah, it was a mistake + to have a struct AND a function called ev_loop). + - fix a bug where ev_default would not initialise the default + loop again after it was destroyed with ev_default_destroy. + - rename syserr to ev_syserr to avoid name clashes when embedding, + do similar changes for event.c. + +3.45 Tue Oct 21 21:59:26 CEST 2008 + - disable inotify usage on linux <2.6.25, as it is broken + (reported by Yoann Vandoorselaere). + - ev_stat erroneously would try to add inotify watchers + even when inotify wasn't available (this should only + have a performance impact). + - ev_once now passes both timeout and io to the callback if both + occur concurrently, instead of giving timeouts precedence. + - disable EV_USE_INOTIFY when sys/inotify.h is too old. + +3.44 Mon Sep 29 05:18:39 CEST 2008 + - embed watchers now automatically invoke ev_loop_fork on the + embedded loop when the parent loop forks. + - new function: ev_now_update (loop). + - verify_watcher was not marked static. + - improve the "associating..." manpage section. + - documentation tweaks here and there. + +3.43 Sun Jul 6 05:34:41 CEST 2008 + - include more include files on windows to get struct _stati64 + (reported by Chris Hulbert, but doesn't quite fix his issue). + - add missing #include in ev.c on windows (reported by + Matt Tolton). + +3.42 Tue Jun 17 12:12:07 CEST 2008 + - work around yet another windows bug: FD_SET actually adds fd's + multiple times to the fd_*SET*, despite official MSN docs claiming + otherwise. Reported and well-analysed by Matt Tolton. + - define NFDBITS to 0 when EV_SELECT_IS_WINSOCKET to make it compile + (reported any analysed by Chris Hulbert). + - fix a bug in ev_ebadf (this function is only used to catch + programming errors in the libev user). reported by Matt Tolton. + - fix a bug in fd_intern on win32 (could lead to compile errors + under some circumstances, but would work correctly if it compiles). + reported by Matt Tolton. + - (try to) work around missing lstat on windows. + - pass in the write fd set as except fd set under windows. windows + is so uncontrollably lame that it requires this. this means that + switching off oobinline is not supported (but tcp/ip doesn't + have oob, so that would be stupid anyways. + - use posix module symbol to auto-detect monotonic clock presence + and some other default values. + +3.41 Fri May 23 18:42:54 CEST 2008 + - work around an obscure bug in winsocket select: if you + provide only empty fd sets then select returns WSAEINVAL. how sucky. + - improve timer scheduling stability and reduce use of time_epsilon. + - use 1-based 2-heap for EV_MINIMAL, simplifies code, reduces + codesize and makes for better cache-efficiency. + - use 3-based 4-heap for !EV_MINIMAL. this makes better use + of cpu cache lines and gives better growth behaviour than + 2-based heaps. + - cache timestamp within heap for !EV_MINIMAL, to avoid random + memory accesses. + - document/add EV_USE_4HEAP and EV_HEAP_CACHE_AT. + - fix a potential aliasing issue in ev_timer_again. + - add/document ev_periodic_at, retract direct access to ->at. + - improve ev_stat docs. + - add portability requirements section. + - fix manpage headers etc. + - normalise WSA error codes to lower range on windows. + - add consistency check code that can be called automatically + or on demand to check for internal structures (ev_loop_verify). + +3.31 Wed Apr 16 20:45:04 CEST 2008 + - added last minute fix for ev_poll.c by Brandon Black. + +3.3 Wed Apr 16 19:04:10 CEST 2008 + - event_base_loopexit should return 0 on success + (W.C.A. Wijngaards). + - added linux eventfd support. + - try to autodetect epoll and inotify support + by libc header version if not using autoconf. + - new symbols: EV_DEFAULT_UC and EV_DEFAULT_UC_. + - declare functions defined in ev.h as inline if + C99 or gcc are available. + - enable inlining with gcc versions 2 and 3. + - work around broken poll implementations potentially + not clearing revents field in ev_poll (Brandon Black) + (no such systems are known at this time). + - work around a bug in realloc on openbsd and darwin, + also makes the erroneous valgrind complaints + go away (noted by various people). + - fix ev_async_pending, add c++ wrapper for ev_async + (based on patch sent by Johannes Deisenhofer). + - add sensible set method to ev::embed. + - made integer constants type int in ev.h. + +3.2 Wed Apr 2 17:11:19 CEST 2008 + - fix a 64 bit overflow issue in the select backend, + by using fd_mask instead of int for the mask. + - rename internal sighandler to avoid clash with very old perls. + - entering ev_loop will not clear the ONESHOT or NONBLOCKING + flags of any outer loops anymore. + - add ev_async_pending. + +3.1 Thu Mar 13 13:45:22 CET 2008 + - implement ev_async watchers. + - only initialise signal pipe on demand. + - make use of sig_atomic_t configurable. + - improved documentation. + +3.0 Mon Jan 28 13:14:47 CET 2008 + - API/ABI bump to version 3.0. + - ev++.h includes "ev.h" by default now, not . + - slightly improved documentation. + - speed up signal detection after a fork. + - only optionally return trace status changed in ev_child + watchers. + - experimental (and undocumented) loop wrappers for ev++.h. + +2.01 Tue Dec 25 08:04:41 CET 2007 + - separate Changes file. + - fix ev_path_set => ev_stat_set typo. + - remove event_compat.h from the libev tarball. + - change how include files are found. + - doc updates. + - update licenses, explicitly allow for GPL relicensing. + +2.0 Sat Dec 22 17:47:03 CET 2007 + - new ev_sleep, ev_set_(io|timeout)_collect_interval. + - removed epoll from embeddable fd set. + - fix embed watchers. + - renamed ev_embed.loop to other. + - added exported Symbol tables. + - undefine member wrapper macros at the end of ev.c. + - respect EV_H in ev++.h. + +1.86 Tue Dec 18 02:36:57 CET 2007 + - fix memleak on loop destroy (not relevant for perl). + +1.85 Fri Dec 14 20:32:40 CET 2007 + - fix some aliasing issues w.r.t. timers and periodics + (not relevant for perl). + +(for historic versions refer to EV/Changes, found in the Perl interface) + +0.1 Wed Oct 31 21:31:48 CET 2007 + - original version; hacked together in <24h. + diff --git a/libev/LICENSE b/libev/LICENSE new file mode 100644 index 0000000..2fdabd4 --- /dev/null +++ b/libev/LICENSE @@ -0,0 +1,37 @@ +All files in libev are +Copyright (c)2007,2008,2009,2010,2011,2012,2013 Marc Alexander Lehmann. + +Redistribution and use in source and binary forms, with or without +modification, are permitted provided that the following conditions are +met: + + * Redistributions of source code must retain the above copyright + notice, this list of conditions and the following disclaimer. + + * Redistributions in binary form must reproduce the above + copyright notice, this list of conditions and the following + disclaimer in the documentation and/or other materials provided + with the distribution. + +THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + +Alternatively, the contents of this package may be used under the terms +of the GNU General Public License ("GPL") version 2 or any later version, +in which case the provisions of the GPL are applicable instead of the +above. If you wish to allow the use of your version of this package only +under the terms of the GPL and not to allow others to use your version of +this file under the BSD license, indicate your decision by deleting the +provisions above and replace them with the notice and other provisions +required by the GPL in this and the other files of this package. If you do +not delete the provisions above, a recipient may use your version of this +file under either the BSD or the GPL. diff --git a/libev/Makefile.am b/libev/Makefile.am new file mode 100644 index 0000000..059305b --- /dev/null +++ b/libev/Makefile.am @@ -0,0 +1,20 @@ +AUTOMAKE_OPTIONS = foreign + +VERSION_INFO = 4:0:0 + +EXTRA_DIST = LICENSE Changes libev.m4 autogen.sh \ + ev_vars.h ev_wrap.h \ + ev_epoll.c ev_select.c ev_poll.c ev_kqueue.c ev_port.c ev_win32.c \ + ev.3 ev.pod Symbols.ev Symbols.event + +man_MANS = ev.3 + +include_HEADERS = ev.h ev++.h event.h + +lib_LTLIBRARIES = libev.la + +libev_la_SOURCES = ev.c event.c +libev_la_LDFLAGS = -version-info $(VERSION_INFO) + +ev.3: ev.pod + pod2man -n LIBEV -r "libev-$(VERSION)" -c "libev - high performance full featured event loop" -s3 <$< >$@ diff --git a/libev/README b/libev/README new file mode 100644 index 0000000..31f6193 --- /dev/null +++ b/libev/README @@ -0,0 +1,58 @@ +libev is a high-performance event loop/event model with lots of features. +(see benchmark at http://libev.schmorp.de/bench.html) + + +ABOUT + + Homepage: http://software.schmorp.de/pkg/libev + Mailinglist: libev@lists.schmorp.de + http://lists.schmorp.de/cgi-bin/mailman/listinfo/libev + Library Documentation: http://pod.tst.eu/http://cvs.schmorp.de/libev/ev.pod + + Libev is modelled (very losely) after libevent and the Event perl + module, but is faster, scales better and is more correct, and also more + featureful. And also smaller. Yay. + + Some of the specialties of libev not commonly found elsewhere are: + + - extensive and detailed, readable documentation (not doxygen garbage). + - fully supports fork, can detect fork in various ways and automatically + re-arms kernel mechanisms that do not support fork. + - highly optimised select, poll, epoll, kqueue and event ports backends. + - filesystem object (path) watching (with optional linux inotify support). + - wallclock-based times (using absolute time, cron-like). + - relative timers/timeouts (handle time jumps). + - fast intra-thread communication between multiple + event loops (with optional fast linux eventfd backend). + - extremely easy to embed (fully documented, no dependencies, + autoconf supported but optional). + - very small codebase, no bloated library, simple code. + - fully extensible by being able to plug into the event loop, + integrate other event loops, integrate other event loop users. + - very little memory use (small watchers, small event loop data). + - optional C++ interface allowing method and function callbacks + at no extra memory or runtime overhead. + - optional Perl interface with similar characteristics (capable + of running Glib/Gtk2 on libev). + - support for other languages (multiple C++ interfaces, D, Ruby, + Python) available from third-parties. + + Examples of programs that embed libev: the EV perl module, node.js, + auditd, rxvt-unicode, gvpe (GNU Virtual Private Ethernet), the + Deliantra MMORPG server (http://www.deliantra.net/), Rubinius (a + next-generation Ruby VM), the Ebb web server, the Rev event toolkit. + + +CONTRIBUTORS + + libev was written and designed by Marc Lehmann and Emanuele Giaquinta. + + The following people sent in patches or made other noteworthy + contributions to the design (for minor patches, see the Changes + file. If I forgot to include you, please shout at me, it was an + accident): + + W.C.A. Wijngaards + Christopher Layne + Chris Brody + diff --git a/libev/README.embed b/libev/README.embed new file mode 100644 index 0000000..0d1bd5e --- /dev/null +++ b/libev/README.embed @@ -0,0 +1,3 @@ +This file is now included in the main libev documentation, see + + http://cvs.schmorp.de/libev/ev.html diff --git a/libev/Symbols.ev b/libev/Symbols.ev new file mode 100644 index 0000000..7a29a75 --- /dev/null +++ b/libev/Symbols.ev @@ -0,0 +1,73 @@ +ev_async_send +ev_async_start +ev_async_stop +ev_backend +ev_break +ev_check_start +ev_check_stop +ev_child_start +ev_child_stop +ev_cleanup_start +ev_cleanup_stop +ev_clear_pending +ev_default_loop +ev_default_loop_ptr +ev_depth +ev_embed_start +ev_embed_stop +ev_embed_sweep +ev_embeddable_backends +ev_feed_event +ev_feed_fd_event +ev_feed_signal +ev_feed_signal_event +ev_fork_start +ev_fork_stop +ev_idle_start +ev_idle_stop +ev_invoke +ev_invoke_pending +ev_io_start +ev_io_stop +ev_iteration +ev_loop_destroy +ev_loop_fork +ev_loop_new +ev_now +ev_now_update +ev_once +ev_pending_count +ev_periodic_again +ev_periodic_start +ev_periodic_stop +ev_prepare_start +ev_prepare_stop +ev_recommended_backends +ev_ref +ev_resume +ev_run +ev_set_allocator +ev_set_invoke_pending_cb +ev_set_io_collect_interval +ev_set_loop_release_cb +ev_set_syserr_cb +ev_set_timeout_collect_interval +ev_set_userdata +ev_signal_start +ev_signal_stop +ev_sleep +ev_stat_start +ev_stat_stat +ev_stat_stop +ev_supported_backends +ev_suspend +ev_time +ev_timer_again +ev_timer_remaining +ev_timer_start +ev_timer_stop +ev_unref +ev_userdata +ev_verify +ev_version_major +ev_version_minor diff --git a/libev/Symbols.event b/libev/Symbols.event new file mode 100644 index 0000000..799d424 --- /dev/null +++ b/libev/Symbols.event @@ -0,0 +1,24 @@ +event_active +event_add +event_base_dispatch +event_base_free +event_base_get_method +event_base_loop +event_base_loopexit +event_base_new +event_base_once +event_base_priority_init +event_base_set +event_del +event_dispatch +event_get_callback +event_get_method +event_get_version +event_init +event_loop +event_loopexit +event_once +event_pending +event_priority_init +event_priority_set +event_set diff --git a/libev/autogen.sh b/libev/autogen.sh new file mode 100644 index 0000000..8056ee7 --- /dev/null +++ b/libev/autogen.sh @@ -0,0 +1,3 @@ +#!/bin/sh + +autoreconf --install --symlink --force diff --git a/libev/configure.ac b/libev/configure.ac new file mode 100644 index 0000000..2590f8f --- /dev/null +++ b/libev/configure.ac @@ -0,0 +1,27 @@ +AC_INIT + +orig_CFLAGS="$CFLAGS" + +AC_CONFIG_SRCDIR([ev_epoll.c]) + +dnl also update ev.h! +AM_INIT_AUTOMAKE(libev,4.24) +AC_CONFIG_HEADERS([config.h]) +AM_MAINTAINER_MODE + +AC_PROG_CC + +dnl Supply default CFLAGS, if not specified +if test -z "$orig_CFLAGS"; then + if test x$GCC = xyes; then + CFLAGS="-g -O3" + fi +fi + +AC_PROG_INSTALL +AC_PROG_LIBTOOL + +m4_include([libev.m4]) + +AC_CONFIG_FILES([Makefile]) +AC_OUTPUT diff --git a/libev/ev++.h b/libev/ev++.h new file mode 100644 index 0000000..c9b453b --- /dev/null +++ b/libev/ev++.h @@ -0,0 +1,816 @@ +/* + * libev simple C++ wrapper classes + * + * Copyright (c) 2007,2008,2010 Marc Alexander Lehmann + * All rights reserved. + * + * Redistribution and use in source and binary forms, with or without modifica- + * tion, are permitted provided that the following conditions are met: + * + * 1. Redistributions of source code must retain the above copyright notice, + * this list of conditions and the following disclaimer. + * + * 2. Redistributions in binary form must reproduce the above copyright + * notice, this list of conditions and the following disclaimer in the + * documentation and/or other materials provided with the distribution. + * + * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR IMPLIED + * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MER- + * CHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO + * EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPE- + * CIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, + * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; + * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, + * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTH- + * ERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED + * OF THE POSSIBILITY OF SUCH DAMAGE. + * + * Alternatively, the contents of this file may be used under the terms of + * the GNU General Public License ("GPL") version 2 or any later version, + * in which case the provisions of the GPL are applicable instead of + * the above. If you wish to allow the use of your version of this file + * only under the terms of the GPL and not to allow others to use your + * version of this file under the BSD license, indicate your decision + * by deleting the provisions above and replace them with the notice + * and other provisions required by the GPL. If you do not delete the + * provisions above, a recipient may use your version of this file under + * either the BSD or the GPL. + */ + +#ifndef EVPP_H__ +#define EVPP_H__ + +#ifdef EV_H +# include EV_H +#else +# include "ev.h" +#endif + +#ifndef EV_USE_STDEXCEPT +# define EV_USE_STDEXCEPT 1 +#endif + +#if EV_USE_STDEXCEPT +# include +#endif + +namespace ev { + + typedef ev_tstamp tstamp; + + enum { + UNDEF = EV_UNDEF, + NONE = EV_NONE, + READ = EV_READ, + WRITE = EV_WRITE, +#if EV_COMPAT3 + TIMEOUT = EV_TIMEOUT, +#endif + TIMER = EV_TIMER, + PERIODIC = EV_PERIODIC, + SIGNAL = EV_SIGNAL, + CHILD = EV_CHILD, + STAT = EV_STAT, + IDLE = EV_IDLE, + CHECK = EV_CHECK, + PREPARE = EV_PREPARE, + FORK = EV_FORK, + ASYNC = EV_ASYNC, + EMBED = EV_EMBED, +# undef ERROR // some systems stupidly #define ERROR + ERROR = EV_ERROR + }; + + enum + { + AUTO = EVFLAG_AUTO, + NOENV = EVFLAG_NOENV, + FORKCHECK = EVFLAG_FORKCHECK, + + SELECT = EVBACKEND_SELECT, + POLL = EVBACKEND_POLL, + EPOLL = EVBACKEND_EPOLL, + KQUEUE = EVBACKEND_KQUEUE, + DEVPOLL = EVBACKEND_DEVPOLL, + PORT = EVBACKEND_PORT + }; + + enum + { +#if EV_COMPAT3 + NONBLOCK = EVLOOP_NONBLOCK, + ONESHOT = EVLOOP_ONESHOT, +#endif + NOWAIT = EVRUN_NOWAIT, + ONCE = EVRUN_ONCE + }; + + enum how_t + { + ONE = EVBREAK_ONE, + ALL = EVBREAK_ALL + }; + + struct bad_loop +#if EV_USE_STDEXCEPT + : std::runtime_error +#endif + { +#if EV_USE_STDEXCEPT + bad_loop () + : std::runtime_error ("libev event loop cannot be initialized, bad value of LIBEV_FLAGS?") + { + } +#endif + }; + +#ifdef EV_AX +# undef EV_AX +#endif + +#ifdef EV_AX_ +# undef EV_AX_ +#endif + +#if EV_MULTIPLICITY +# define EV_AX raw_loop +# define EV_AX_ raw_loop, +#else +# define EV_AX +# define EV_AX_ +#endif + + struct loop_ref + { + loop_ref (EV_P) throw () +#if EV_MULTIPLICITY + : EV_AX (EV_A) +#endif + { + } + + bool operator == (const loop_ref &other) const throw () + { +#if EV_MULTIPLICITY + return EV_AX == other.EV_AX; +#else + return true; +#endif + } + + bool operator != (const loop_ref &other) const throw () + { +#if EV_MULTIPLICITY + return ! (*this == other); +#else + return false; +#endif + } + +#if EV_MULTIPLICITY + bool operator == (const EV_P) const throw () + { + return this->EV_AX == EV_A; + } + + bool operator != (const EV_P) const throw () + { + return ! (*this == EV_A); + } + + operator struct ev_loop * () const throw () + { + return EV_AX; + } + + operator const struct ev_loop * () const throw () + { + return EV_AX; + } + + bool is_default () const throw () + { + return EV_AX == ev_default_loop (0); + } +#endif + +#if EV_COMPAT3 + void loop (int flags = 0) + { + ev_run (EV_AX_ flags); + } + + void unloop (how_t how = ONE) throw () + { + ev_break (EV_AX_ how); + } +#endif + + void run (int flags = 0) + { + ev_run (EV_AX_ flags); + } + + void break_loop (how_t how = ONE) throw () + { + ev_break (EV_AX_ how); + } + + void post_fork () throw () + { + ev_loop_fork (EV_AX); + } + + unsigned int backend () const throw () + { + return ev_backend (EV_AX); + } + + tstamp now () const throw () + { + return ev_now (EV_AX); + } + + void ref () throw () + { + ev_ref (EV_AX); + } + + void unref () throw () + { + ev_unref (EV_AX); + } + +#if EV_FEATURE_API + unsigned int iteration () const throw () + { + return ev_iteration (EV_AX); + } + + unsigned int depth () const throw () + { + return ev_depth (EV_AX); + } + + void set_io_collect_interval (tstamp interval) throw () + { + ev_set_io_collect_interval (EV_AX_ interval); + } + + void set_timeout_collect_interval (tstamp interval) throw () + { + ev_set_timeout_collect_interval (EV_AX_ interval); + } +#endif + + // function callback + void once (int fd, int events, tstamp timeout, void (*cb)(int, void *), void *arg = 0) throw () + { + ev_once (EV_AX_ fd, events, timeout, cb, arg); + } + + // method callback + template + void once (int fd, int events, tstamp timeout, K *object) throw () + { + once (fd, events, timeout, method_thunk, object); + } + + // default method == operator () + template + void once (int fd, int events, tstamp timeout, K *object) throw () + { + once (fd, events, timeout, method_thunk, object); + } + + template + static void method_thunk (int revents, void *arg) + { + (static_cast(arg)->*method) + (revents); + } + + // no-argument method callback + template + void once (int fd, int events, tstamp timeout, K *object) throw () + { + once (fd, events, timeout, method_noargs_thunk, object); + } + + template + static void method_noargs_thunk (int revents, void *arg) + { + (static_cast(arg)->*method) + (); + } + + // simpler function callback + template + void once (int fd, int events, tstamp timeout) throw () + { + once (fd, events, timeout, simpler_func_thunk); + } + + template + static void simpler_func_thunk (int revents, void *arg) + { + (*cb) + (revents); + } + + // simplest function callback + template + void once (int fd, int events, tstamp timeout) throw () + { + once (fd, events, timeout, simplest_func_thunk); + } + + template + static void simplest_func_thunk (int revents, void *arg) + { + (*cb) + (); + } + + void feed_fd_event (int fd, int revents) throw () + { + ev_feed_fd_event (EV_AX_ fd, revents); + } + + void feed_signal_event (int signum) throw () + { + ev_feed_signal_event (EV_AX_ signum); + } + +#if EV_MULTIPLICITY + struct ev_loop* EV_AX; +#endif + + }; + +#if EV_MULTIPLICITY + struct dynamic_loop : loop_ref + { + + dynamic_loop (unsigned int flags = AUTO) throw (bad_loop) + : loop_ref (ev_loop_new (flags)) + { + if (!EV_AX) + throw bad_loop (); + } + + ~dynamic_loop () throw () + { + ev_loop_destroy (EV_AX); + EV_AX = 0; + } + + private: + + dynamic_loop (const dynamic_loop &); + + dynamic_loop & operator= (const dynamic_loop &); + + }; +#endif + + struct default_loop : loop_ref + { + default_loop (unsigned int flags = AUTO) throw (bad_loop) +#if EV_MULTIPLICITY + : loop_ref (ev_default_loop (flags)) +#endif + { + if ( +#if EV_MULTIPLICITY + !EV_AX +#else + !ev_default_loop (flags) +#endif + ) + throw bad_loop (); + } + + private: + default_loop (const default_loop &); + default_loop &operator = (const default_loop &); + }; + + inline loop_ref get_default_loop () throw () + { +#if EV_MULTIPLICITY + return ev_default_loop (0); +#else + return loop_ref (); +#endif + } + +#undef EV_AX +#undef EV_AX_ + +#undef EV_PX +#undef EV_PX_ +#if EV_MULTIPLICITY +# define EV_PX loop_ref EV_A +# define EV_PX_ loop_ref EV_A_ +#else +# define EV_PX +# define EV_PX_ +#endif + + template + struct base : ev_watcher + { + #if EV_MULTIPLICITY + EV_PX; + + // loop set + void set (EV_P) throw () + { + this->EV_A = EV_A; + } + #endif + + base (EV_PX) throw () + #if EV_MULTIPLICITY + : EV_A (EV_A) + #endif + { + ev_init (this, 0); + } + + void set_ (const void *data, void (*cb)(EV_P_ ev_watcher *w, int revents)) throw () + { + this->data = (void *)data; + ev_set_cb (static_cast(this), cb); + } + + // function callback + template + void set (void *data = 0) throw () + { + set_ (data, function_thunk); + } + + template + static void function_thunk (EV_P_ ev_watcher *w, int revents) + { + function + (*static_cast(w), revents); + } + + // method callback + template + void set (K *object) throw () + { + set_ (object, method_thunk); + } + + // default method == operator () + template + void set (K *object) throw () + { + set_ (object, method_thunk); + } + + template + static void method_thunk (EV_P_ ev_watcher *w, int revents) + { + (static_cast(w->data)->*method) + (*static_cast(w), revents); + } + + // no-argument callback + template + void set (K *object) throw () + { + set_ (object, method_noargs_thunk); + } + + template + static void method_noargs_thunk (EV_P_ ev_watcher *w, int revents) + { + (static_cast(w->data)->*method) + (); + } + + void operator ()(int events = EV_UNDEF) + { + return + ev_cb (static_cast(this)) + (static_cast(this), events); + } + + bool is_active () const throw () + { + return ev_is_active (static_cast(this)); + } + + bool is_pending () const throw () + { + return ev_is_pending (static_cast(this)); + } + + void feed_event (int revents) throw () + { + ev_feed_event (EV_A_ static_cast(this), revents); + } + }; + + inline tstamp now (EV_P) throw () + { + return ev_now (EV_A); + } + + inline void delay (tstamp interval) throw () + { + ev_sleep (interval); + } + + inline int version_major () throw () + { + return ev_version_major (); + } + + inline int version_minor () throw () + { + return ev_version_minor (); + } + + inline unsigned int supported_backends () throw () + { + return ev_supported_backends (); + } + + inline unsigned int recommended_backends () throw () + { + return ev_recommended_backends (); + } + + inline unsigned int embeddable_backends () throw () + { + return ev_embeddable_backends (); + } + + inline void set_allocator (void *(*cb)(void *ptr, long size) throw ()) throw () + { + ev_set_allocator (cb); + } + + inline void set_syserr_cb (void (*cb)(const char *msg) throw ()) throw () + { + ev_set_syserr_cb (cb); + } + + #if EV_MULTIPLICITY + #define EV_CONSTRUCT(cppstem,cstem) \ + (EV_PX = get_default_loop ()) throw () \ + : base (EV_A) \ + { \ + } + #else + #define EV_CONSTRUCT(cppstem,cstem) \ + () throw () \ + { \ + } + #endif + + /* using a template here would require quite a few more lines, + * so a macro solution was chosen */ + #define EV_BEGIN_WATCHER(cppstem,cstem) \ + \ + struct cppstem : base \ + { \ + void start () throw () \ + { \ + ev_ ## cstem ## _start (EV_A_ static_cast(this)); \ + } \ + \ + void stop () throw () \ + { \ + ev_ ## cstem ## _stop (EV_A_ static_cast(this)); \ + } \ + \ + cppstem EV_CONSTRUCT(cppstem,cstem) \ + \ + ~cppstem () throw () \ + { \ + stop (); \ + } \ + \ + using base::set; \ + \ + private: \ + \ + cppstem (const cppstem &o); \ + \ + cppstem &operator =(const cppstem &o); \ + \ + public: + + #define EV_END_WATCHER(cppstem,cstem) \ + }; + + EV_BEGIN_WATCHER (io, io) + void set (int fd, int events) throw () + { + int active = is_active (); + if (active) stop (); + ev_io_set (static_cast(this), fd, events); + if (active) start (); + } + + void set (int events) throw () + { + int active = is_active (); + if (active) stop (); + ev_io_set (static_cast(this), fd, events); + if (active) start (); + } + + void start (int fd, int events) throw () + { + set (fd, events); + start (); + } + EV_END_WATCHER (io, io) + + EV_BEGIN_WATCHER (timer, timer) + void set (ev_tstamp after, ev_tstamp repeat = 0.) throw () + { + int active = is_active (); + if (active) stop (); + ev_timer_set (static_cast(this), after, repeat); + if (active) start (); + } + + void start (ev_tstamp after, ev_tstamp repeat = 0.) throw () + { + set (after, repeat); + start (); + } + + void again () throw () + { + ev_timer_again (EV_A_ static_cast(this)); + } + + ev_tstamp remaining () + { + return ev_timer_remaining (EV_A_ static_cast(this)); + } + EV_END_WATCHER (timer, timer) + + #if EV_PERIODIC_ENABLE + EV_BEGIN_WATCHER (periodic, periodic) + void set (ev_tstamp at, ev_tstamp interval = 0.) throw () + { + int active = is_active (); + if (active) stop (); + ev_periodic_set (static_cast(this), at, interval, 0); + if (active) start (); + } + + void start (ev_tstamp at, ev_tstamp interval = 0.) throw () + { + set (at, interval); + start (); + } + + void again () throw () + { + ev_periodic_again (EV_A_ static_cast(this)); + } + EV_END_WATCHER (periodic, periodic) + #endif + + #if EV_SIGNAL_ENABLE + EV_BEGIN_WATCHER (sig, signal) + void set (int signum) throw () + { + int active = is_active (); + if (active) stop (); + ev_signal_set (static_cast(this), signum); + if (active) start (); + } + + void start (int signum) throw () + { + set (signum); + start (); + } + EV_END_WATCHER (sig, signal) + #endif + + #if EV_CHILD_ENABLE + EV_BEGIN_WATCHER (child, child) + void set (int pid, int trace = 0) throw () + { + int active = is_active (); + if (active) stop (); + ev_child_set (static_cast(this), pid, trace); + if (active) start (); + } + + void start (int pid, int trace = 0) throw () + { + set (pid, trace); + start (); + } + EV_END_WATCHER (child, child) + #endif + + #if EV_STAT_ENABLE + EV_BEGIN_WATCHER (stat, stat) + void set (const char *path, ev_tstamp interval = 0.) throw () + { + int active = is_active (); + if (active) stop (); + ev_stat_set (static_cast(this), path, interval); + if (active) start (); + } + + void start (const char *path, ev_tstamp interval = 0.) throw () + { + stop (); + set (path, interval); + start (); + } + + void update () throw () + { + ev_stat_stat (EV_A_ static_cast(this)); + } + EV_END_WATCHER (stat, stat) + #endif + + #if EV_IDLE_ENABLE + EV_BEGIN_WATCHER (idle, idle) + void set () throw () { } + EV_END_WATCHER (idle, idle) + #endif + + #if EV_PREPARE_ENABLE + EV_BEGIN_WATCHER (prepare, prepare) + void set () throw () { } + EV_END_WATCHER (prepare, prepare) + #endif + + #if EV_CHECK_ENABLE + EV_BEGIN_WATCHER (check, check) + void set () throw () { } + EV_END_WATCHER (check, check) + #endif + + #if EV_EMBED_ENABLE + EV_BEGIN_WATCHER (embed, embed) + void set_embed (struct ev_loop *embedded_loop) throw () + { + int active = is_active (); + if (active) stop (); + ev_embed_set (static_cast(this), embedded_loop); + if (active) start (); + } + + void start (struct ev_loop *embedded_loop) throw () + { + set (embedded_loop); + start (); + } + + void sweep () + { + ev_embed_sweep (EV_A_ static_cast(this)); + } + EV_END_WATCHER (embed, embed) + #endif + + #if EV_FORK_ENABLE + EV_BEGIN_WATCHER (fork, fork) + void set () throw () { } + EV_END_WATCHER (fork, fork) + #endif + + #if EV_ASYNC_ENABLE + EV_BEGIN_WATCHER (async, async) + void send () throw () + { + ev_async_send (EV_A_ static_cast(this)); + } + + bool async_pending () throw () + { + return ev_async_pending (static_cast(this)); + } + EV_END_WATCHER (async, async) + #endif + + #undef EV_PX + #undef EV_PX_ + #undef EV_CONSTRUCT + #undef EV_BEGIN_WATCHER + #undef EV_END_WATCHER +} + +#endif + diff --git a/libev/ev.3 b/libev/ev.3 new file mode 100644 index 0000000..9d6b203 --- /dev/null +++ b/libev/ev.3 @@ -0,0 +1,5647 @@ +.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.29) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" Set up some character translations and predefined strings. \*(-- will +.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left +.\" double quote, and \*(R" will give a right double quote. \*(C+ will +.\" give a nicer C++. Capital omega is used to do unbreakable dashes and +.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, +.\" nothing in troff, for use with C<>. +.tr \(*W- +.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' +.ie n \{\ +. ds -- \(*W- +. ds PI pi +. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch +. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch +. ds L" "" +. ds R" "" +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds -- \|\(em\| +. ds PI \(*p +. ds L" `` +. ds R" '' +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is turned on, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{ +. if \nF \{ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). +.\" Fear. Run. Save yourself. No user-serviceable parts. +. \" fudge factors for nroff and troff +.if n \{\ +. ds #H 0 +. ds #V .8m +. ds #F .3m +. ds #[ \f1 +. ds #] \fP +.\} +.if t \{\ +. ds #H ((1u-(\\\\n(.fu%2u))*.13m) +. ds #V .6m +. ds #F 0 +. ds #[ \& +. ds #] \& +.\} +. \" simple accents for nroff and troff +.if n \{\ +. ds ' \& +. ds ` \& +. ds ^ \& +. ds , \& +. ds ~ ~ +. ds / +.\} +.if t \{\ +. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" +. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' +. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' +. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' +. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' +. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' +.\} +. \" troff and (daisy-wheel) nroff accents +.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' +.ds 8 \h'\*(#H'\(*b\h'-\*(#H' +.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] +.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' +.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' +.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] +.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] +.ds ae a\h'-(\w'a'u*4/10)'e +.ds Ae A\h'-(\w'A'u*4/10)'E +. \" corrections for vroff +.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' +.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' +. \" for low resolution devices (crt and lpr) +.if \n(.H>23 .if \n(.V>19 \ +\{\ +. ds : e +. ds 8 ss +. ds o a +. ds d- d\h'-1'\(ga +. ds D- D\h'-1'\(hy +. ds th \o'bp' +. ds Th \o'LP' +. ds ae ae +. ds Ae AE +.\} +.rm #[ #] #H #V #F C +.\" ======================================================================== +.\" +.IX Title "LIBEV 3" +.TH LIBEV 3 "2017-06-21" "libev-4.24" "libev - high performance full featured event loop" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH "NAME" +libev \- a high performance full\-featured event loop written in C +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +.Ve +.SS "\s-1EXAMPLE PROGRAM\s0" +.IX Subsection "EXAMPLE PROGRAM" +.Vb 2 +\& // a single header file is required +\& #include +\& +\& #include // for puts +\& +\& // every watcher type has its own typedef\*(Aqd struct +\& // with the name ev_TYPE +\& ev_io stdin_watcher; +\& ev_timer timeout_watcher; +\& +\& // all watcher callbacks have a similar signature +\& // this callback is called when data is readable on stdin +\& static void +\& stdin_cb (EV_P_ ev_io *w, int revents) +\& { +\& puts ("stdin ready"); +\& // for one\-shot events, one must manually stop the watcher +\& // with its corresponding stop function. +\& ev_io_stop (EV_A_ w); +\& +\& // this causes all nested ev_run\*(Aqs to stop iterating +\& ev_break (EV_A_ EVBREAK_ALL); +\& } +\& +\& // another callback, this time for a time\-out +\& static void +\& timeout_cb (EV_P_ ev_timer *w, int revents) +\& { +\& puts ("timeout"); +\& // this causes the innermost ev_run to stop iterating +\& ev_break (EV_A_ EVBREAK_ONE); +\& } +\& +\& int +\& main (void) +\& { +\& // use the default event loop unless you have special needs +\& struct ev_loop *loop = EV_DEFAULT; +\& +\& // initialise an io watcher, then start it +\& // this one will watch for stdin to become readable +\& ev_io_init (&stdin_watcher, stdin_cb, /*STDIN_FILENO*/ 0, EV_READ); +\& ev_io_start (loop, &stdin_watcher); +\& +\& // initialise a timer watcher, then start it +\& // simple non\-repeating 5.5 second timeout +\& ev_timer_init (&timeout_watcher, timeout_cb, 5.5, 0.); +\& ev_timer_start (loop, &timeout_watcher); +\& +\& // now wait for events to arrive +\& ev_run (loop, 0); +\& +\& // break was called, so exit +\& return 0; +\& } +.Ve +.SH "ABOUT THIS DOCUMENT" +.IX Header "ABOUT THIS DOCUMENT" +This document documents the libev software package. +.PP +The newest version of this document is also available as an html-formatted +web page you might find easier to navigate when reading it for the first +time: . +.PP +While this document tries to be as complete as possible in documenting +libev, its usage and the rationale behind its design, it is not a tutorial +on event-based programming, nor will it introduce event-based programming +with libev. +.PP +Familiarity with event based programming techniques in general is assumed +throughout this document. +.SH "WHAT TO READ WHEN IN A HURRY" +.IX Header "WHAT TO READ WHEN IN A HURRY" +This manual tries to be very detailed, but unfortunately, this also makes +it very long. If you just want to know the basics of libev, I suggest +reading \*(L"\s-1ANATOMY OF A WATCHER\*(R"\s0, then the \*(L"\s-1EXAMPLE PROGRAM\*(R"\s0 above and +look up the missing functions in \*(L"\s-1GLOBAL FUNCTIONS\*(R"\s0 and the \f(CW\*(C`ev_io\*(C'\fR and +\&\f(CW\*(C`ev_timer\*(C'\fR sections in \*(L"\s-1WATCHER TYPES\*(R"\s0. +.SH "ABOUT LIBEV" +.IX Header "ABOUT LIBEV" +Libev is an event loop: you register interest in certain events (such as a +file descriptor being readable or a timeout occurring), and it will manage +these event sources and provide your program with events. +.PP +To do this, it must take more or less complete control over your process +(or thread) by executing the \fIevent loop\fR handler, and will then +communicate events via a callback mechanism. +.PP +You register interest in certain events by registering so-called \fIevent +watchers\fR, which are relatively small C structures you initialise with the +details of the event, and then hand it over to libev by \fIstarting\fR the +watcher. +.SS "\s-1FEATURES\s0" +.IX Subsection "FEATURES" +Libev supports \f(CW\*(C`select\*(C'\fR, \f(CW\*(C`poll\*(C'\fR, the Linux-specific \f(CW\*(C`epoll\*(C'\fR, the +BSD-specific \f(CW\*(C`kqueue\*(C'\fR and the Solaris-specific event port mechanisms +for file descriptor events (\f(CW\*(C`ev_io\*(C'\fR), the Linux \f(CW\*(C`inotify\*(C'\fR interface +(for \f(CW\*(C`ev_stat\*(C'\fR), Linux eventfd/signalfd (for faster and cleaner +inter-thread wakeup (\f(CW\*(C`ev_async\*(C'\fR)/signal handling (\f(CW\*(C`ev_signal\*(C'\fR)) relative +timers (\f(CW\*(C`ev_timer\*(C'\fR), absolute timers with customised rescheduling +(\f(CW\*(C`ev_periodic\*(C'\fR), synchronous signals (\f(CW\*(C`ev_signal\*(C'\fR), process status +change events (\f(CW\*(C`ev_child\*(C'\fR), and event watchers dealing with the event +loop mechanism itself (\f(CW\*(C`ev_idle\*(C'\fR, \f(CW\*(C`ev_embed\*(C'\fR, \f(CW\*(C`ev_prepare\*(C'\fR and +\&\f(CW\*(C`ev_check\*(C'\fR watchers) as well as file watchers (\f(CW\*(C`ev_stat\*(C'\fR) and even +limited support for fork events (\f(CW\*(C`ev_fork\*(C'\fR). +.PP +It also is quite fast (see this +benchmark comparing it to libevent +for example). +.SS "\s-1CONVENTIONS\s0" +.IX Subsection "CONVENTIONS" +Libev is very configurable. In this manual the default (and most common) +configuration will be described, which supports multiple event loops. For +more info about various configuration options please have a look at +\&\fB\s-1EMBED\s0\fR section in this manual. If libev was configured without support +for multiple event loops, then all functions taking an initial argument of +name \f(CW\*(C`loop\*(C'\fR (which is always of type \f(CW\*(C`struct ev_loop *\*(C'\fR) will not have +this argument. +.SS "\s-1TIME REPRESENTATION\s0" +.IX Subsection "TIME REPRESENTATION" +Libev represents time as a single floating point number, representing +the (fractional) number of seconds since the (\s-1POSIX\s0) epoch (in practice +somewhere near the beginning of 1970, details are complicated, don't +ask). This type is called \f(CW\*(C`ev_tstamp\*(C'\fR, which is what you should use +too. It usually aliases to the \f(CW\*(C`double\*(C'\fR type in C. When you need to do +any calculations on it, you should treat it as some floating point value. +.PP +Unlike the name component \f(CW\*(C`stamp\*(C'\fR might indicate, it is also used for +time differences (e.g. delays) throughout libev. +.SH "ERROR HANDLING" +.IX Header "ERROR HANDLING" +Libev knows three classes of errors: operating system errors, usage errors +and internal errors (bugs). +.PP +When libev catches an operating system error it cannot handle (for example +a system call indicating a condition libev cannot fix), it calls the callback +set via \f(CW\*(C`ev_set_syserr_cb\*(C'\fR, which is supposed to fix the problem or +abort. The default is to print a diagnostic message and to call \f(CW\*(C`abort +()\*(C'\fR. +.PP +When libev detects a usage error such as a negative timer interval, then +it will print a diagnostic message and abort (via the \f(CW\*(C`assert\*(C'\fR mechanism, +so \f(CW\*(C`NDEBUG\*(C'\fR will disable this checking): these are programming errors in +the libev caller and need to be fixed there. +.PP +Libev also has a few internal error-checking \f(CW\*(C`assert\*(C'\fRions, and also has +extensive consistency checking code. These do not trigger under normal +circumstances, as they indicate either a bug in libev or worse. +.SH "GLOBAL FUNCTIONS" +.IX Header "GLOBAL FUNCTIONS" +These functions can be called anytime, even before initialising the +library in any way. +.IP "ev_tstamp ev_time ()" 4 +.IX Item "ev_tstamp ev_time ()" +Returns the current time as libev would use it. Please note that the +\&\f(CW\*(C`ev_now\*(C'\fR function is usually faster and also often returns the timestamp +you actually want to know. Also interesting is the combination of +\&\f(CW\*(C`ev_now_update\*(C'\fR and \f(CW\*(C`ev_now\*(C'\fR. +.IP "ev_sleep (ev_tstamp interval)" 4 +.IX Item "ev_sleep (ev_tstamp interval)" +Sleep for the given interval: The current thread will be blocked +until either it is interrupted or the given time interval has +passed (approximately \- it might return a bit earlier even if not +interrupted). Returns immediately if \f(CW\*(C`interval <= 0\*(C'\fR. +.Sp +Basically this is a sub-second-resolution \f(CW\*(C`sleep ()\*(C'\fR. +.Sp +The range of the \f(CW\*(C`interval\*(C'\fR is limited \- libev only guarantees to work +with sleep times of up to one day (\f(CW\*(C`interval <= 86400\*(C'\fR). +.IP "int ev_version_major ()" 4 +.IX Item "int ev_version_major ()" +.PD 0 +.IP "int ev_version_minor ()" 4 +.IX Item "int ev_version_minor ()" +.PD +You can find out the major and minor \s-1ABI\s0 version numbers of the library +you linked against by calling the functions \f(CW\*(C`ev_version_major\*(C'\fR and +\&\f(CW\*(C`ev_version_minor\*(C'\fR. If you want, you can compare against the global +symbols \f(CW\*(C`EV_VERSION_MAJOR\*(C'\fR and \f(CW\*(C`EV_VERSION_MINOR\*(C'\fR, which specify the +version of the library your program was compiled against. +.Sp +These version numbers refer to the \s-1ABI\s0 version of the library, not the +release version. +.Sp +Usually, it's a good idea to terminate if the major versions mismatch, +as this indicates an incompatible change. Minor versions are usually +compatible to older versions, so a larger minor version alone is usually +not a problem. +.Sp +Example: Make sure we haven't accidentally been linked against the wrong +version (note, however, that this will not detect other \s-1ABI\s0 mismatches, +such as \s-1LFS\s0 or reentrancy). +.Sp +.Vb 3 +\& assert (("libev version mismatch", +\& ev_version_major () == EV_VERSION_MAJOR +\& && ev_version_minor () >= EV_VERSION_MINOR)); +.Ve +.IP "unsigned int ev_supported_backends ()" 4 +.IX Item "unsigned int ev_supported_backends ()" +Return the set of all backends (i.e. their corresponding \f(CW\*(C`EV_BACKEND_*\*(C'\fR +value) compiled into this binary of libev (independent of their +availability on the system you are running on). See \f(CW\*(C`ev_default_loop\*(C'\fR for +a description of the set values. +.Sp +Example: make sure we have the epoll method, because yeah this is cool and +a must have and can we have a torrent of it please!!!11 +.Sp +.Vb 2 +\& assert (("sorry, no epoll, no sex", +\& ev_supported_backends () & EVBACKEND_EPOLL)); +.Ve +.IP "unsigned int ev_recommended_backends ()" 4 +.IX Item "unsigned int ev_recommended_backends ()" +Return the set of all backends compiled into this binary of libev and +also recommended for this platform, meaning it will work for most file +descriptor types. This set is often smaller than the one returned by +\&\f(CW\*(C`ev_supported_backends\*(C'\fR, as for example kqueue is broken on most BSDs +and will not be auto-detected unless you explicitly request it (assuming +you know what you are doing). This is the set of backends that libev will +probe for if you specify no backends explicitly. +.IP "unsigned int ev_embeddable_backends ()" 4 +.IX Item "unsigned int ev_embeddable_backends ()" +Returns the set of backends that are embeddable in other event loops. This +value is platform-specific but can include backends not available on the +current system. To find which embeddable backends might be supported on +the current system, you would need to look at \f(CW\*(C`ev_embeddable_backends () +& ev_supported_backends ()\*(C'\fR, likewise for recommended ones. +.Sp +See the description of \f(CW\*(C`ev_embed\*(C'\fR watchers for more info. +.IP "ev_set_allocator (void *(*cb)(void *ptr, long size) throw ())" 4 +.IX Item "ev_set_allocator (void *(*cb)(void *ptr, long size) throw ())" +Sets the allocation function to use (the prototype is similar \- the +semantics are identical to the \f(CW\*(C`realloc\*(C'\fR C89/SuS/POSIX function). It is +used to allocate and free memory (no surprises here). If it returns zero +when memory needs to be allocated (\f(CW\*(C`size != 0\*(C'\fR), the library might abort +or take some potentially destructive action. +.Sp +Since some systems (at least OpenBSD and Darwin) fail to implement +correct \f(CW\*(C`realloc\*(C'\fR semantics, libev will use a wrapper around the system +\&\f(CW\*(C`realloc\*(C'\fR and \f(CW\*(C`free\*(C'\fR functions by default. +.Sp +You could override this function in high-availability programs to, say, +free some memory if it cannot allocate memory, to use a special allocator, +or even to sleep a while and retry until some memory is available. +.Sp +Example: Replace the libev allocator with one that waits a bit and then +retries (example requires a standards-compliant \f(CW\*(C`realloc\*(C'\fR). +.Sp +.Vb 6 +\& static void * +\& persistent_realloc (void *ptr, size_t size) +\& { +\& for (;;) +\& { +\& void *newptr = realloc (ptr, size); +\& +\& if (newptr) +\& return newptr; +\& +\& sleep (60); +\& } +\& } +\& +\& ... +\& ev_set_allocator (persistent_realloc); +.Ve +.IP "ev_set_syserr_cb (void (*cb)(const char *msg) throw ())" 4 +.IX Item "ev_set_syserr_cb (void (*cb)(const char *msg) throw ())" +Set the callback function to call on a retryable system call error (such +as failed select, poll, epoll_wait). The message is a printable string +indicating the system call or subsystem causing the problem. If this +callback is set, then libev will expect it to remedy the situation, no +matter what, when it returns. That is, libev will generally retry the +requested operation, or, if the condition doesn't go away, do bad stuff +(such as abort). +.Sp +Example: This is basically the same thing that libev does internally, too. +.Sp +.Vb 6 +\& static void +\& fatal_error (const char *msg) +\& { +\& perror (msg); +\& abort (); +\& } +\& +\& ... +\& ev_set_syserr_cb (fatal_error); +.Ve +.IP "ev_feed_signal (int signum)" 4 +.IX Item "ev_feed_signal (int signum)" +This function can be used to \*(L"simulate\*(R" a signal receive. It is completely +safe to call this function at any time, from any context, including signal +handlers or random threads. +.Sp +Its main use is to customise signal handling in your process, especially +in the presence of threads. For example, you could block signals +by default in all threads (and specifying \f(CW\*(C`EVFLAG_NOSIGMASK\*(C'\fR when +creating any loops), and in one thread, use \f(CW\*(C`sigwait\*(C'\fR or any other +mechanism to wait for signals, then \*(L"deliver\*(R" them to libev by calling +\&\f(CW\*(C`ev_feed_signal\*(C'\fR. +.SH "FUNCTIONS CONTROLLING EVENT LOOPS" +.IX Header "FUNCTIONS CONTROLLING EVENT LOOPS" +An event loop is described by a \f(CW\*(C`struct ev_loop *\*(C'\fR (the \f(CW\*(C`struct\*(C'\fR is +\&\fInot\fR optional in this case unless libev 3 compatibility is disabled, as +libev 3 had an \f(CW\*(C`ev_loop\*(C'\fR function colliding with the struct name). +.PP +The library knows two types of such loops, the \fIdefault\fR loop, which +supports child process events, and dynamically created event loops which +do not. +.IP "struct ev_loop *ev_default_loop (unsigned int flags)" 4 +.IX Item "struct ev_loop *ev_default_loop (unsigned int flags)" +This returns the \*(L"default\*(R" event loop object, which is what you should +normally use when you just need \*(L"the event loop\*(R". Event loop objects and +the \f(CW\*(C`flags\*(C'\fR parameter are described in more detail in the entry for +\&\f(CW\*(C`ev_loop_new\*(C'\fR. +.Sp +If the default loop is already initialised then this function simply +returns it (and ignores the flags. If that is troubling you, check +\&\f(CW\*(C`ev_backend ()\*(C'\fR afterwards). Otherwise it will create it with the given +flags, which should almost always be \f(CW0\fR, unless the caller is also the +one calling \f(CW\*(C`ev_run\*(C'\fR or otherwise qualifies as \*(L"the main program\*(R". +.Sp +If you don't know what event loop to use, use the one returned from this +function (or via the \f(CW\*(C`EV_DEFAULT\*(C'\fR macro). +.Sp +Note that this function is \fInot\fR thread-safe, so if you want to use it +from multiple threads, you have to employ some kind of mutex (note also +that this case is unlikely, as loops cannot be shared easily between +threads anyway). +.Sp +The default loop is the only loop that can handle \f(CW\*(C`ev_child\*(C'\fR watchers, +and to do this, it always registers a handler for \f(CW\*(C`SIGCHLD\*(C'\fR. If this is +a problem for your application you can either create a dynamic loop with +\&\f(CW\*(C`ev_loop_new\*(C'\fR which doesn't do that, or you can simply overwrite the +\&\f(CW\*(C`SIGCHLD\*(C'\fR signal handler \fIafter\fR calling \f(CW\*(C`ev_default_init\*(C'\fR. +.Sp +Example: This is the most typical usage. +.Sp +.Vb 2 +\& if (!ev_default_loop (0)) +\& fatal ("could not initialise libev, bad $LIBEV_FLAGS in environment?"); +.Ve +.Sp +Example: Restrict libev to the select and poll backends, and do not allow +environment settings to be taken into account: +.Sp +.Vb 1 +\& ev_default_loop (EVBACKEND_POLL | EVBACKEND_SELECT | EVFLAG_NOENV); +.Ve +.IP "struct ev_loop *ev_loop_new (unsigned int flags)" 4 +.IX Item "struct ev_loop *ev_loop_new (unsigned int flags)" +This will create and initialise a new event loop object. If the loop +could not be initialised, returns false. +.Sp +This function is thread-safe, and one common way to use libev with +threads is indeed to create one loop per thread, and using the default +loop in the \*(L"main\*(R" or \*(L"initial\*(R" thread. +.Sp +The flags argument can be used to specify special behaviour or specific +backends to use, and is usually specified as \f(CW0\fR (or \f(CW\*(C`EVFLAG_AUTO\*(C'\fR). +.Sp +The following flags are supported: +.RS 4 +.ie n .IP """EVFLAG_AUTO""" 4 +.el .IP "\f(CWEVFLAG_AUTO\fR" 4 +.IX Item "EVFLAG_AUTO" +The default flags value. Use this if you have no clue (it's the right +thing, believe me). +.ie n .IP """EVFLAG_NOENV""" 4 +.el .IP "\f(CWEVFLAG_NOENV\fR" 4 +.IX Item "EVFLAG_NOENV" +If this flag bit is or'ed into the flag value (or the program runs setuid +or setgid) then libev will \fInot\fR look at the environment variable +\&\f(CW\*(C`LIBEV_FLAGS\*(C'\fR. Otherwise (the default), this environment variable will +override the flags completely if it is found in the environment. This is +useful to try out specific backends to test their performance, to work +around bugs, or to make libev threadsafe (accessing environment variables +cannot be done in a threadsafe way, but usually it works if no other +thread modifies them). +.ie n .IP """EVFLAG_FORKCHECK""" 4 +.el .IP "\f(CWEVFLAG_FORKCHECK\fR" 4 +.IX Item "EVFLAG_FORKCHECK" +Instead of calling \f(CW\*(C`ev_loop_fork\*(C'\fR manually after a fork, you can also +make libev check for a fork in each iteration by enabling this flag. +.Sp +This works by calling \f(CW\*(C`getpid ()\*(C'\fR on every iteration of the loop, +and thus this might slow down your event loop if you do a lot of loop +iterations and little real work, but is usually not noticeable (on my +GNU/Linux system for example, \f(CW\*(C`getpid\*(C'\fR is actually a simple 5\-insn sequence +without a system call and thus \fIvery\fR fast, but my GNU/Linux system also has +\&\f(CW\*(C`pthread_atfork\*(C'\fR which is even faster). +.Sp +The big advantage of this flag is that you can forget about fork (and +forget about forgetting to tell libev about forking, although you still +have to ignore \f(CW\*(C`SIGPIPE\*(C'\fR) when you use this flag. +.Sp +This flag setting cannot be overridden or specified in the \f(CW\*(C`LIBEV_FLAGS\*(C'\fR +environment variable. +.ie n .IP """EVFLAG_NOINOTIFY""" 4 +.el .IP "\f(CWEVFLAG_NOINOTIFY\fR" 4 +.IX Item "EVFLAG_NOINOTIFY" +When this flag is specified, then libev will not attempt to use the +\&\fIinotify\fR \s-1API\s0 for its \f(CW\*(C`ev_stat\*(C'\fR watchers. Apart from debugging and +testing, this flag can be useful to conserve inotify file descriptors, as +otherwise each loop using \f(CW\*(C`ev_stat\*(C'\fR watchers consumes one inotify handle. +.ie n .IP """EVFLAG_SIGNALFD""" 4 +.el .IP "\f(CWEVFLAG_SIGNALFD\fR" 4 +.IX Item "EVFLAG_SIGNALFD" +When this flag is specified, then libev will attempt to use the +\&\fIsignalfd\fR \s-1API\s0 for its \f(CW\*(C`ev_signal\*(C'\fR (and \f(CW\*(C`ev_child\*(C'\fR) watchers. This \s-1API\s0 +delivers signals synchronously, which makes it both faster and might make +it possible to get the queued signal data. It can also simplify signal +handling with threads, as long as you properly block signals in your +threads that are not interested in handling them. +.Sp +Signalfd will not be used by default as this changes your signal mask, and +there are a lot of shoddy libraries and programs (glib's threadpool for +example) that can't properly initialise their signal masks. +.ie n .IP """EVFLAG_NOSIGMASK""" 4 +.el .IP "\f(CWEVFLAG_NOSIGMASK\fR" 4 +.IX Item "EVFLAG_NOSIGMASK" +When this flag is specified, then libev will avoid to modify the signal +mask. Specifically, this means you have to make sure signals are unblocked +when you want to receive them. +.Sp +This behaviour is useful when you want to do your own signal handling, or +want to handle signals only in specific threads and want to avoid libev +unblocking the signals. +.Sp +It's also required by \s-1POSIX\s0 in a threaded program, as libev calls +\&\f(CW\*(C`sigprocmask\*(C'\fR, whose behaviour is officially unspecified. +.Sp +This flag's behaviour will become the default in future versions of libev. +.ie n .IP """EVBACKEND_SELECT"" (value 1, portable select backend)" 4 +.el .IP "\f(CWEVBACKEND_SELECT\fR (value 1, portable select backend)" 4 +.IX Item "EVBACKEND_SELECT (value 1, portable select backend)" +This is your standard \fIselect\fR\|(2) backend. Not \fIcompletely\fR standard, as +libev tries to roll its own fd_set with no limits on the number of fds, +but if that fails, expect a fairly low limit on the number of fds when +using this backend. It doesn't scale too well (O(highest_fd)), but its +usually the fastest backend for a low number of (low-numbered :) fds. +.Sp +To get good performance out of this backend you need a high amount of +parallelism (most of the file descriptors should be busy). If you are +writing a server, you should \f(CW\*(C`accept ()\*(C'\fR in a loop to accept as many +connections as possible during one iteration. You might also want to have +a look at \f(CW\*(C`ev_set_io_collect_interval ()\*(C'\fR to increase the amount of +readiness notifications you get per iteration. +.Sp +This backend maps \f(CW\*(C`EV_READ\*(C'\fR to the \f(CW\*(C`readfds\*(C'\fR set and \f(CW\*(C`EV_WRITE\*(C'\fR to the +\&\f(CW\*(C`writefds\*(C'\fR set (and to work around Microsoft Windows bugs, also onto the +\&\f(CW\*(C`exceptfds\*(C'\fR set on that platform). +.ie n .IP """EVBACKEND_POLL"" (value 2, poll backend, available everywhere except on windows)" 4 +.el .IP "\f(CWEVBACKEND_POLL\fR (value 2, poll backend, available everywhere except on windows)" 4 +.IX Item "EVBACKEND_POLL (value 2, poll backend, available everywhere except on windows)" +And this is your standard \fIpoll\fR\|(2) backend. It's more complicated +than select, but handles sparse fds better and has no artificial +limit on the number of fds you can use (except it will slow down +considerably with a lot of inactive fds). It scales similarly to select, +i.e. O(total_fds). See the entry for \f(CW\*(C`EVBACKEND_SELECT\*(C'\fR, above, for +performance tips. +.Sp +This backend maps \f(CW\*(C`EV_READ\*(C'\fR to \f(CW\*(C`POLLIN | POLLERR | POLLHUP\*(C'\fR, and +\&\f(CW\*(C`EV_WRITE\*(C'\fR to \f(CW\*(C`POLLOUT | POLLERR | POLLHUP\*(C'\fR. +.ie n .IP """EVBACKEND_EPOLL"" (value 4, Linux)" 4 +.el .IP "\f(CWEVBACKEND_EPOLL\fR (value 4, Linux)" 4 +.IX Item "EVBACKEND_EPOLL (value 4, Linux)" +Use the linux-specific \fIepoll\fR\|(7) interface (for both pre\- and post\-2.6.9 +kernels). +.Sp +For few fds, this backend is a bit little slower than poll and select, but +it scales phenomenally better. While poll and select usually scale like +O(total_fds) where total_fds is the total number of fds (or the highest +fd), epoll scales either O(1) or O(active_fds). +.Sp +The epoll mechanism deserves honorable mention as the most misdesigned +of the more advanced event mechanisms: mere annoyances include silently +dropping file descriptors, requiring a system call per change per file +descriptor (and unnecessary guessing of parameters), problems with dup, +returning before the timeout value, resulting in additional iterations +(and only giving 5ms accuracy while select on the same platform gives +0.1ms) and so on. The biggest issue is fork races, however \- if a program +forks then \fIboth\fR parent and child process have to recreate the epoll +set, which can take considerable time (one syscall per file descriptor) +and is of course hard to detect. +.Sp +Epoll is also notoriously buggy \- embedding epoll fds \fIshould\fR work, +but of course \fIdoesn't\fR, and epoll just loves to report events for +totally \fIdifferent\fR file descriptors (even already closed ones, so +one cannot even remove them from the set) than registered in the set +(especially on \s-1SMP\s0 systems). Libev tries to counter these spurious +notifications by employing an additional generation counter and comparing +that against the events to filter out spurious ones, recreating the set +when required. Epoll also erroneously rounds down timeouts, but gives you +no way to know when and by how much, so sometimes you have to busy-wait +because epoll returns immediately despite a nonzero timeout. And last +not least, it also refuses to work with some file descriptors which work +perfectly fine with \f(CW\*(C`select\*(C'\fR (files, many character devices...). +.Sp +Epoll is truly the train wreck among event poll mechanisms, a frankenpoll, +cobbled together in a hurry, no thought to design or interaction with +others. Oh, the pain, will it ever stop... +.Sp +While stopping, setting and starting an I/O watcher in the same iteration +will result in some caching, there is still a system call per such +incident (because the same \fIfile descriptor\fR could point to a different +\&\fIfile description\fR now), so its best to avoid that. Also, \f(CW\*(C`dup ()\*(C'\fR'ed +file descriptors might not work very well if you register events for both +file descriptors. +.Sp +Best performance from this backend is achieved by not unregistering all +watchers for a file descriptor until it has been closed, if possible, +i.e. keep at least one watcher active per fd at all times. Stopping and +starting a watcher (without re-setting it) also usually doesn't cause +extra overhead. A fork can both result in spurious notifications as well +as in libev having to destroy and recreate the epoll object, which can +take considerable time and thus should be avoided. +.Sp +All this means that, in practice, \f(CW\*(C`EVBACKEND_SELECT\*(C'\fR can be as fast or +faster than epoll for maybe up to a hundred file descriptors, depending on +the usage. So sad. +.Sp +While nominally embeddable in other event loops, this feature is broken in +all kernel versions tested so far. +.Sp +This backend maps \f(CW\*(C`EV_READ\*(C'\fR and \f(CW\*(C`EV_WRITE\*(C'\fR in the same way as +\&\f(CW\*(C`EVBACKEND_POLL\*(C'\fR. +.ie n .IP """EVBACKEND_KQUEUE"" (value 8, most \s-1BSD\s0 clones)" 4 +.el .IP "\f(CWEVBACKEND_KQUEUE\fR (value 8, most \s-1BSD\s0 clones)" 4 +.IX Item "EVBACKEND_KQUEUE (value 8, most BSD clones)" +Kqueue deserves special mention, as at the time of this writing, it +was broken on all BSDs except NetBSD (usually it doesn't work reliably +with anything but sockets and pipes, except on Darwin, where of course +it's completely useless). Unlike epoll, however, whose brokenness +is by design, these kqueue bugs can (and eventually will) be fixed +without \s-1API\s0 changes to existing programs. For this reason it's not being +\&\*(L"auto-detected\*(R" unless you explicitly specify it in the flags (i.e. using +\&\f(CW\*(C`EVBACKEND_KQUEUE\*(C'\fR) or libev was compiled on a known-to-be-good (\-enough) +system like NetBSD. +.Sp +You still can embed kqueue into a normal poll or select backend and use it +only for sockets (after having made sure that sockets work with kqueue on +the target platform). See \f(CW\*(C`ev_embed\*(C'\fR watchers for more info. +.Sp +It scales in the same way as the epoll backend, but the interface to the +kernel is more efficient (which says nothing about its actual speed, of +course). While stopping, setting and starting an I/O watcher does never +cause an extra system call as with \f(CW\*(C`EVBACKEND_EPOLL\*(C'\fR, it still adds up to +two event changes per incident. Support for \f(CW\*(C`fork ()\*(C'\fR is very bad (you +might have to leak fd's on fork, but it's more sane than epoll) and it +drops fds silently in similarly hard-to-detect cases. +.Sp +This backend usually performs well under most conditions. +.Sp +While nominally embeddable in other event loops, this doesn't work +everywhere, so you might need to test for this. And since it is broken +almost everywhere, you should only use it when you have a lot of sockets +(for which it usually works), by embedding it into another event loop +(e.g. \f(CW\*(C`EVBACKEND_SELECT\*(C'\fR or \f(CW\*(C`EVBACKEND_POLL\*(C'\fR (but \f(CW\*(C`poll\*(C'\fR is of course +also broken on \s-1OS X\s0)) and, did I mention it, using it only for sockets. +.Sp +This backend maps \f(CW\*(C`EV_READ\*(C'\fR into an \f(CW\*(C`EVFILT_READ\*(C'\fR kevent with +\&\f(CW\*(C`NOTE_EOF\*(C'\fR, and \f(CW\*(C`EV_WRITE\*(C'\fR into an \f(CW\*(C`EVFILT_WRITE\*(C'\fR kevent with +\&\f(CW\*(C`NOTE_EOF\*(C'\fR. +.ie n .IP """EVBACKEND_DEVPOLL"" (value 16, Solaris 8)" 4 +.el .IP "\f(CWEVBACKEND_DEVPOLL\fR (value 16, Solaris 8)" 4 +.IX Item "EVBACKEND_DEVPOLL (value 16, Solaris 8)" +This is not implemented yet (and might never be, unless you send me an +implementation). According to reports, \f(CW\*(C`/dev/poll\*(C'\fR only supports sockets +and is not embeddable, which would limit the usefulness of this backend +immensely. +.ie n .IP """EVBACKEND_PORT"" (value 32, Solaris 10)" 4 +.el .IP "\f(CWEVBACKEND_PORT\fR (value 32, Solaris 10)" 4 +.IX Item "EVBACKEND_PORT (value 32, Solaris 10)" +This uses the Solaris 10 event port mechanism. As with everything on Solaris, +it's really slow, but it still scales very well (O(active_fds)). +.Sp +While this backend scales well, it requires one system call per active +file descriptor per loop iteration. For small and medium numbers of file +descriptors a \*(L"slow\*(R" \f(CW\*(C`EVBACKEND_SELECT\*(C'\fR or \f(CW\*(C`EVBACKEND_POLL\*(C'\fR backend +might perform better. +.Sp +On the positive side, this backend actually performed fully to +specification in all tests and is fully embeddable, which is a rare feat +among the OS-specific backends (I vastly prefer correctness over speed +hacks). +.Sp +On the negative side, the interface is \fIbizarre\fR \- so bizarre that +even sun itself gets it wrong in their code examples: The event polling +function sometimes returns events to the caller even though an error +occurred, but with no indication whether it has done so or not (yes, it's +even documented that way) \- deadly for edge-triggered interfaces where you +absolutely have to know whether an event occurred or not because you have +to re-arm the watcher. +.Sp +Fortunately libev seems to be able to work around these idiocies. +.Sp +This backend maps \f(CW\*(C`EV_READ\*(C'\fR and \f(CW\*(C`EV_WRITE\*(C'\fR in the same way as +\&\f(CW\*(C`EVBACKEND_POLL\*(C'\fR. +.ie n .IP """EVBACKEND_ALL""" 4 +.el .IP "\f(CWEVBACKEND_ALL\fR" 4 +.IX Item "EVBACKEND_ALL" +Try all backends (even potentially broken ones that wouldn't be tried +with \f(CW\*(C`EVFLAG_AUTO\*(C'\fR). Since this is a mask, you can do stuff such as +\&\f(CW\*(C`EVBACKEND_ALL & ~EVBACKEND_KQUEUE\*(C'\fR. +.Sp +It is definitely not recommended to use this flag, use whatever +\&\f(CW\*(C`ev_recommended_backends ()\*(C'\fR returns, or simply do not specify a backend +at all. +.ie n .IP """EVBACKEND_MASK""" 4 +.el .IP "\f(CWEVBACKEND_MASK\fR" 4 +.IX Item "EVBACKEND_MASK" +Not a backend at all, but a mask to select all backend bits from a +\&\f(CW\*(C`flags\*(C'\fR value, in case you want to mask out any backends from a flags +value (e.g. when modifying the \f(CW\*(C`LIBEV_FLAGS\*(C'\fR environment variable). +.RE +.RS 4 +.Sp +If one or more of the backend flags are or'ed into the flags value, +then only these backends will be tried (in the reverse order as listed +here). If none are specified, all backends in \f(CW\*(C`ev_recommended_backends +()\*(C'\fR will be tried. +.Sp +Example: Try to create a event loop that uses epoll and nothing else. +.Sp +.Vb 3 +\& struct ev_loop *epoller = ev_loop_new (EVBACKEND_EPOLL | EVFLAG_NOENV); +\& if (!epoller) +\& fatal ("no epoll found here, maybe it hides under your chair"); +.Ve +.Sp +Example: Use whatever libev has to offer, but make sure that kqueue is +used if available. +.Sp +.Vb 1 +\& struct ev_loop *loop = ev_loop_new (ev_recommended_backends () | EVBACKEND_KQUEUE); +.Ve +.RE +.IP "ev_loop_destroy (loop)" 4 +.IX Item "ev_loop_destroy (loop)" +Destroys an event loop object (frees all memory and kernel state +etc.). None of the active event watchers will be stopped in the normal +sense, so e.g. \f(CW\*(C`ev_is_active\*(C'\fR might still return true. It is your +responsibility to either stop all watchers cleanly yourself \fIbefore\fR +calling this function, or cope with the fact afterwards (which is usually +the easiest thing, you can just ignore the watchers and/or \f(CW\*(C`free ()\*(C'\fR them +for example). +.Sp +Note that certain global state, such as signal state (and installed signal +handlers), will not be freed by this function, and related watchers (such +as signal and child watchers) would need to be stopped manually. +.Sp +This function is normally used on loop objects allocated by +\&\f(CW\*(C`ev_loop_new\*(C'\fR, but it can also be used on the default loop returned by +\&\f(CW\*(C`ev_default_loop\*(C'\fR, in which case it is not thread-safe. +.Sp +Note that it is not advisable to call this function on the default loop +except in the rare occasion where you really need to free its resources. +If you need dynamically allocated loops it is better to use \f(CW\*(C`ev_loop_new\*(C'\fR +and \f(CW\*(C`ev_loop_destroy\*(C'\fR. +.IP "ev_loop_fork (loop)" 4 +.IX Item "ev_loop_fork (loop)" +This function sets a flag that causes subsequent \f(CW\*(C`ev_run\*(C'\fR iterations +to reinitialise the kernel state for backends that have one. Despite +the name, you can call it anytime you are allowed to start or stop +watchers (except inside an \f(CW\*(C`ev_prepare\*(C'\fR callback), but it makes most +sense after forking, in the child process. You \fImust\fR call it (or use +\&\f(CW\*(C`EVFLAG_FORKCHECK\*(C'\fR) in the child before resuming or calling \f(CW\*(C`ev_run\*(C'\fR. +.Sp +In addition, if you want to reuse a loop (via this function or +\&\f(CW\*(C`EVFLAG_FORKCHECK\*(C'\fR), you \fIalso\fR have to ignore \f(CW\*(C`SIGPIPE\*(C'\fR. +.Sp +Again, you \fIhave\fR to call it on \fIany\fR loop that you want to re-use after +a fork, \fIeven if you do not plan to use the loop in the parent\fR. This is +because some kernel interfaces *cough* \fIkqueue\fR *cough* do funny things +during fork. +.Sp +On the other hand, you only need to call this function in the child +process if and only if you want to use the event loop in the child. If +you just fork+exec or create a new loop in the child, you don't have to +call it at all (in fact, \f(CW\*(C`epoll\*(C'\fR is so badly broken that it makes a +difference, but libev will usually detect this case on its own and do a +costly reset of the backend). +.Sp +The function itself is quite fast and it's usually not a problem to call +it just in case after a fork. +.Sp +Example: Automate calling \f(CW\*(C`ev_loop_fork\*(C'\fR on the default loop when +using pthreads. +.Sp +.Vb 5 +\& static void +\& post_fork_child (void) +\& { +\& ev_loop_fork (EV_DEFAULT); +\& } +\& +\& ... +\& pthread_atfork (0, 0, post_fork_child); +.Ve +.IP "int ev_is_default_loop (loop)" 4 +.IX Item "int ev_is_default_loop (loop)" +Returns true when the given loop is, in fact, the default loop, and false +otherwise. +.IP "unsigned int ev_iteration (loop)" 4 +.IX Item "unsigned int ev_iteration (loop)" +Returns the current iteration count for the event loop, which is identical +to the number of times libev did poll for new events. It starts at \f(CW0\fR +and happily wraps around with enough iterations. +.Sp +This value can sometimes be useful as a generation counter of sorts (it +\&\*(L"ticks\*(R" the number of loop iterations), as it roughly corresponds with +\&\f(CW\*(C`ev_prepare\*(C'\fR and \f(CW\*(C`ev_check\*(C'\fR calls \- and is incremented between the +prepare and check phases. +.IP "unsigned int ev_depth (loop)" 4 +.IX Item "unsigned int ev_depth (loop)" +Returns the number of times \f(CW\*(C`ev_run\*(C'\fR was entered minus the number of +times \f(CW\*(C`ev_run\*(C'\fR was exited normally, in other words, the recursion depth. +.Sp +Outside \f(CW\*(C`ev_run\*(C'\fR, this number is zero. In a callback, this number is +\&\f(CW1\fR, unless \f(CW\*(C`ev_run\*(C'\fR was invoked recursively (or from another thread), +in which case it is higher. +.Sp +Leaving \f(CW\*(C`ev_run\*(C'\fR abnormally (setjmp/longjmp, cancelling the thread, +throwing an exception etc.), doesn't count as \*(L"exit\*(R" \- consider this +as a hint to avoid such ungentleman-like behaviour unless it's really +convenient, in which case it is fully supported. +.IP "unsigned int ev_backend (loop)" 4 +.IX Item "unsigned int ev_backend (loop)" +Returns one of the \f(CW\*(C`EVBACKEND_*\*(C'\fR flags indicating the event backend in +use. +.IP "ev_tstamp ev_now (loop)" 4 +.IX Item "ev_tstamp ev_now (loop)" +Returns the current \*(L"event loop time\*(R", which is the time the event loop +received events and started processing them. This timestamp does not +change as long as callbacks are being processed, and this is also the base +time used for relative timers. You can treat it as the timestamp of the +event occurring (or more correctly, libev finding out about it). +.IP "ev_now_update (loop)" 4 +.IX Item "ev_now_update (loop)" +Establishes the current time by querying the kernel, updating the time +returned by \f(CW\*(C`ev_now ()\*(C'\fR in the progress. This is a costly operation and +is usually done automatically within \f(CW\*(C`ev_run ()\*(C'\fR. +.Sp +This function is rarely useful, but when some event callback runs for a +very long time without entering the event loop, updating libev's idea of +the current time is a good idea. +.Sp +See also \*(L"The special problem of time updates\*(R" in the \f(CW\*(C`ev_timer\*(C'\fR section. +.IP "ev_suspend (loop)" 4 +.IX Item "ev_suspend (loop)" +.PD 0 +.IP "ev_resume (loop)" 4 +.IX Item "ev_resume (loop)" +.PD +These two functions suspend and resume an event loop, for use when the +loop is not used for a while and timeouts should not be processed. +.Sp +A typical use case would be an interactive program such as a game: When +the user presses \f(CW\*(C`^Z\*(C'\fR to suspend the game and resumes it an hour later it +would be best to handle timeouts as if no time had actually passed while +the program was suspended. This can be achieved by calling \f(CW\*(C`ev_suspend\*(C'\fR +in your \f(CW\*(C`SIGTSTP\*(C'\fR handler, sending yourself a \f(CW\*(C`SIGSTOP\*(C'\fR and calling +\&\f(CW\*(C`ev_resume\*(C'\fR directly afterwards to resume timer processing. +.Sp +Effectively, all \f(CW\*(C`ev_timer\*(C'\fR watchers will be delayed by the time spend +between \f(CW\*(C`ev_suspend\*(C'\fR and \f(CW\*(C`ev_resume\*(C'\fR, and all \f(CW\*(C`ev_periodic\*(C'\fR watchers +will be rescheduled (that is, they will lose any events that would have +occurred while suspended). +.Sp +After calling \f(CW\*(C`ev_suspend\*(C'\fR you \fBmust not\fR call \fIany\fR function on the +given loop other than \f(CW\*(C`ev_resume\*(C'\fR, and you \fBmust not\fR call \f(CW\*(C`ev_resume\*(C'\fR +without a previous call to \f(CW\*(C`ev_suspend\*(C'\fR. +.Sp +Calling \f(CW\*(C`ev_suspend\*(C'\fR/\f(CW\*(C`ev_resume\*(C'\fR has the side effect of updating the +event loop time (see \f(CW\*(C`ev_now_update\*(C'\fR). +.IP "bool ev_run (loop, int flags)" 4 +.IX Item "bool ev_run (loop, int flags)" +Finally, this is it, the event handler. This function usually is called +after you have initialised all your watchers and you want to start +handling events. It will ask the operating system for any new events, call +the watcher callbacks, and then repeat the whole process indefinitely: This +is why event loops are called \fIloops\fR. +.Sp +If the flags argument is specified as \f(CW0\fR, it will keep handling events +until either no event watchers are active anymore or \f(CW\*(C`ev_break\*(C'\fR was +called. +.Sp +The return value is false if there are no more active watchers (which +usually means \*(L"all jobs done\*(R" or \*(L"deadlock\*(R"), and true in all other cases +(which usually means " you should call \f(CW\*(C`ev_run\*(C'\fR again"). +.Sp +Please note that an explicit \f(CW\*(C`ev_break\*(C'\fR is usually better than +relying on all watchers to be stopped when deciding when a program has +finished (especially in interactive programs), but having a program +that automatically loops as long as it has to and no longer by virtue +of relying on its watchers stopping correctly, that is truly a thing of +beauty. +.Sp +This function is \fImostly\fR exception-safe \- you can break out of a +\&\f(CW\*(C`ev_run\*(C'\fR call by calling \f(CW\*(C`longjmp\*(C'\fR in a callback, throwing a \*(C+ +exception and so on. This does not decrement the \f(CW\*(C`ev_depth\*(C'\fR value, nor +will it clear any outstanding \f(CW\*(C`EVBREAK_ONE\*(C'\fR breaks. +.Sp +A flags value of \f(CW\*(C`EVRUN_NOWAIT\*(C'\fR will look for new events, will handle +those events and any already outstanding ones, but will not wait and +block your process in case there are no events and will return after one +iteration of the loop. This is sometimes useful to poll and handle new +events while doing lengthy calculations, to keep the program responsive. +.Sp +A flags value of \f(CW\*(C`EVRUN_ONCE\*(C'\fR will look for new events (waiting if +necessary) and will handle those and any already outstanding ones. It +will block your process until at least one new event arrives (which could +be an event internal to libev itself, so there is no guarantee that a +user-registered callback will be called), and will return after one +iteration of the loop. +.Sp +This is useful if you are waiting for some external event in conjunction +with something not expressible using other libev watchers (i.e. "roll your +own \f(CW\*(C`ev_run\*(C'\fR"). However, a pair of \f(CW\*(C`ev_prepare\*(C'\fR/\f(CW\*(C`ev_check\*(C'\fR watchers is +usually a better approach for this kind of thing. +.Sp +Here are the gory details of what \f(CW\*(C`ev_run\*(C'\fR does (this is for your +understanding, not a guarantee that things will work exactly like this in +future versions): +.Sp +.Vb 10 +\& \- Increment loop depth. +\& \- Reset the ev_break status. +\& \- Before the first iteration, call any pending watchers. +\& LOOP: +\& \- If EVFLAG_FORKCHECK was used, check for a fork. +\& \- If a fork was detected (by any means), queue and call all fork watchers. +\& \- Queue and call all prepare watchers. +\& \- If ev_break was called, goto FINISH. +\& \- If we have been forked, detach and recreate the kernel state +\& as to not disturb the other process. +\& \- Update the kernel state with all outstanding changes. +\& \- Update the "event loop time" (ev_now ()). +\& \- Calculate for how long to sleep or block, if at all +\& (active idle watchers, EVRUN_NOWAIT or not having +\& any active watchers at all will result in not sleeping). +\& \- Sleep if the I/O and timer collect interval say so. +\& \- Increment loop iteration counter. +\& \- Block the process, waiting for any events. +\& \- Queue all outstanding I/O (fd) events. +\& \- Update the "event loop time" (ev_now ()), and do time jump adjustments. +\& \- Queue all expired timers. +\& \- Queue all expired periodics. +\& \- Queue all idle watchers with priority higher than that of pending events. +\& \- Queue all check watchers. +\& \- Call all queued watchers in reverse order (i.e. check watchers first). +\& Signals and child watchers are implemented as I/O watchers, and will +\& be handled here by queueing them when their watcher gets executed. +\& \- If ev_break has been called, or EVRUN_ONCE or EVRUN_NOWAIT +\& were used, or there are no active watchers, goto FINISH, otherwise +\& continue with step LOOP. +\& FINISH: +\& \- Reset the ev_break status iff it was EVBREAK_ONE. +\& \- Decrement the loop depth. +\& \- Return. +.Ve +.Sp +Example: Queue some jobs and then loop until no events are outstanding +anymore. +.Sp +.Vb 4 +\& ... queue jobs here, make sure they register event watchers as long +\& ... as they still have work to do (even an idle watcher will do..) +\& ev_run (my_loop, 0); +\& ... jobs done or somebody called break. yeah! +.Ve +.IP "ev_break (loop, how)" 4 +.IX Item "ev_break (loop, how)" +Can be used to make a call to \f(CW\*(C`ev_run\*(C'\fR return early (but only after it +has processed all outstanding events). The \f(CW\*(C`how\*(C'\fR argument must be either +\&\f(CW\*(C`EVBREAK_ONE\*(C'\fR, which will make the innermost \f(CW\*(C`ev_run\*(C'\fR call return, or +\&\f(CW\*(C`EVBREAK_ALL\*(C'\fR, which will make all nested \f(CW\*(C`ev_run\*(C'\fR calls return. +.Sp +This \*(L"break state\*(R" will be cleared on the next call to \f(CW\*(C`ev_run\*(C'\fR. +.Sp +It is safe to call \f(CW\*(C`ev_break\*(C'\fR from outside any \f(CW\*(C`ev_run\*(C'\fR calls, too, in +which case it will have no effect. +.IP "ev_ref (loop)" 4 +.IX Item "ev_ref (loop)" +.PD 0 +.IP "ev_unref (loop)" 4 +.IX Item "ev_unref (loop)" +.PD +Ref/unref can be used to add or remove a reference count on the event +loop: Every watcher keeps one reference, and as long as the reference +count is nonzero, \f(CW\*(C`ev_run\*(C'\fR will not return on its own. +.Sp +This is useful when you have a watcher that you never intend to +unregister, but that nevertheless should not keep \f(CW\*(C`ev_run\*(C'\fR from +returning. In such a case, call \f(CW\*(C`ev_unref\*(C'\fR after starting, and \f(CW\*(C`ev_ref\*(C'\fR +before stopping it. +.Sp +As an example, libev itself uses this for its internal signal pipe: It +is not visible to the libev user and should not keep \f(CW\*(C`ev_run\*(C'\fR from +exiting if no event watchers registered by it are active. It is also an +excellent way to do this for generic recurring timers or from within +third-party libraries. Just remember to \fIunref after start\fR and \fIref +before stop\fR (but only if the watcher wasn't active before, or was active +before, respectively. Note also that libev might stop watchers itself +(e.g. non-repeating timers) in which case you have to \f(CW\*(C`ev_ref\*(C'\fR +in the callback). +.Sp +Example: Create a signal watcher, but keep it from keeping \f(CW\*(C`ev_run\*(C'\fR +running when nothing else is active. +.Sp +.Vb 4 +\& ev_signal exitsig; +\& ev_signal_init (&exitsig, sig_cb, SIGINT); +\& ev_signal_start (loop, &exitsig); +\& ev_unref (loop); +.Ve +.Sp +Example: For some weird reason, unregister the above signal handler again. +.Sp +.Vb 2 +\& ev_ref (loop); +\& ev_signal_stop (loop, &exitsig); +.Ve +.IP "ev_set_io_collect_interval (loop, ev_tstamp interval)" 4 +.IX Item "ev_set_io_collect_interval (loop, ev_tstamp interval)" +.PD 0 +.IP "ev_set_timeout_collect_interval (loop, ev_tstamp interval)" 4 +.IX Item "ev_set_timeout_collect_interval (loop, ev_tstamp interval)" +.PD +These advanced functions influence the time that libev will spend waiting +for events. Both time intervals are by default \f(CW0\fR, meaning that libev +will try to invoke timer/periodic callbacks and I/O callbacks with minimum +latency. +.Sp +Setting these to a higher value (the \f(CW\*(C`interval\*(C'\fR \fImust\fR be >= \f(CW0\fR) +allows libev to delay invocation of I/O and timer/periodic callbacks +to increase efficiency of loop iterations (or to increase power-saving +opportunities). +.Sp +The idea is that sometimes your program runs just fast enough to handle +one (or very few) event(s) per loop iteration. While this makes the +program responsive, it also wastes a lot of \s-1CPU\s0 time to poll for new +events, especially with backends like \f(CW\*(C`select ()\*(C'\fR which have a high +overhead for the actual polling but can deliver many events at once. +.Sp +By setting a higher \fIio collect interval\fR you allow libev to spend more +time collecting I/O events, so you can handle more events per iteration, +at the cost of increasing latency. Timeouts (both \f(CW\*(C`ev_periodic\*(C'\fR and +\&\f(CW\*(C`ev_timer\*(C'\fR) will not be affected. Setting this to a non-null value will +introduce an additional \f(CW\*(C`ev_sleep ()\*(C'\fR call into most loop iterations. The +sleep time ensures that libev will not poll for I/O events more often then +once per this interval, on average (as long as the host time resolution is +good enough). +.Sp +Likewise, by setting a higher \fItimeout collect interval\fR you allow libev +to spend more time collecting timeouts, at the expense of increased +latency/jitter/inexactness (the watcher callback will be called +later). \f(CW\*(C`ev_io\*(C'\fR watchers will not be affected. Setting this to a non-null +value will not introduce any overhead in libev. +.Sp +Many (busy) programs can usually benefit by setting the I/O collect +interval to a value near \f(CW0.1\fR or so, which is often enough for +interactive servers (of course not for games), likewise for timeouts. It +usually doesn't make much sense to set it to a lower value than \f(CW0.01\fR, +as this approaches the timing granularity of most systems. Note that if +you do transactions with the outside world and you can't increase the +parallelity, then this setting will limit your transaction rate (if you +need to poll once per transaction and the I/O collect interval is 0.01, +then you can't do more than 100 transactions per second). +.Sp +Setting the \fItimeout collect interval\fR can improve the opportunity for +saving power, as the program will \*(L"bundle\*(R" timer callback invocations that +are \*(L"near\*(R" in time together, by delaying some, thus reducing the number of +times the process sleeps and wakes up again. Another useful technique to +reduce iterations/wake\-ups is to use \f(CW\*(C`ev_periodic\*(C'\fR watchers and make sure +they fire on, say, one-second boundaries only. +.Sp +Example: we only need 0.1s timeout granularity, and we wish not to poll +more often than 100 times per second: +.Sp +.Vb 2 +\& ev_set_timeout_collect_interval (EV_DEFAULT_UC_ 0.1); +\& ev_set_io_collect_interval (EV_DEFAULT_UC_ 0.01); +.Ve +.IP "ev_invoke_pending (loop)" 4 +.IX Item "ev_invoke_pending (loop)" +This call will simply invoke all pending watchers while resetting their +pending state. Normally, \f(CW\*(C`ev_run\*(C'\fR does this automatically when required, +but when overriding the invoke callback this call comes handy. This +function can be invoked from a watcher \- this can be useful for example +when you want to do some lengthy calculation and want to pass further +event handling to another thread (you still have to make sure only one +thread executes within \f(CW\*(C`ev_invoke_pending\*(C'\fR or \f(CW\*(C`ev_run\*(C'\fR of course). +.IP "int ev_pending_count (loop)" 4 +.IX Item "int ev_pending_count (loop)" +Returns the number of pending watchers \- zero indicates that no watchers +are pending. +.IP "ev_set_invoke_pending_cb (loop, void (*invoke_pending_cb)(\s-1EV_P\s0))" 4 +.IX Item "ev_set_invoke_pending_cb (loop, void (*invoke_pending_cb)(EV_P))" +This overrides the invoke pending functionality of the loop: Instead of +invoking all pending watchers when there are any, \f(CW\*(C`ev_run\*(C'\fR will call +this callback instead. This is useful, for example, when you want to +invoke the actual watchers inside another context (another thread etc.). +.Sp +If you want to reset the callback, use \f(CW\*(C`ev_invoke_pending\*(C'\fR as new +callback. +.IP "ev_set_loop_release_cb (loop, void (*release)(\s-1EV_P\s0) throw (), void (*acquire)(\s-1EV_P\s0) throw ())" 4 +.IX Item "ev_set_loop_release_cb (loop, void (*release)(EV_P) throw (), void (*acquire)(EV_P) throw ())" +Sometimes you want to share the same loop between multiple threads. This +can be done relatively simply by putting mutex_lock/unlock calls around +each call to a libev function. +.Sp +However, \f(CW\*(C`ev_run\*(C'\fR can run an indefinite time, so it is not feasible +to wait for it to return. One way around this is to wake up the event +loop via \f(CW\*(C`ev_break\*(C'\fR and \f(CW\*(C`ev_async_send\*(C'\fR, another way is to set these +\&\fIrelease\fR and \fIacquire\fR callbacks on the loop. +.Sp +When set, then \f(CW\*(C`release\*(C'\fR will be called just before the thread is +suspended waiting for new events, and \f(CW\*(C`acquire\*(C'\fR is called just +afterwards. +.Sp +Ideally, \f(CW\*(C`release\*(C'\fR will just call your mutex_unlock function, and +\&\f(CW\*(C`acquire\*(C'\fR will just call the mutex_lock function again. +.Sp +While event loop modifications are allowed between invocations of +\&\f(CW\*(C`release\*(C'\fR and \f(CW\*(C`acquire\*(C'\fR (that's their only purpose after all), no +modifications done will affect the event loop, i.e. adding watchers will +have no effect on the set of file descriptors being watched, or the time +waited. Use an \f(CW\*(C`ev_async\*(C'\fR watcher to wake up \f(CW\*(C`ev_run\*(C'\fR when you want it +to take note of any changes you made. +.Sp +In theory, threads executing \f(CW\*(C`ev_run\*(C'\fR will be async-cancel safe between +invocations of \f(CW\*(C`release\*(C'\fR and \f(CW\*(C`acquire\*(C'\fR. +.Sp +See also the locking example in the \f(CW\*(C`THREADS\*(C'\fR section later in this +document. +.IP "ev_set_userdata (loop, void *data)" 4 +.IX Item "ev_set_userdata (loop, void *data)" +.PD 0 +.IP "void *ev_userdata (loop)" 4 +.IX Item "void *ev_userdata (loop)" +.PD +Set and retrieve a single \f(CW\*(C`void *\*(C'\fR associated with a loop. When +\&\f(CW\*(C`ev_set_userdata\*(C'\fR has never been called, then \f(CW\*(C`ev_userdata\*(C'\fR returns +\&\f(CW0\fR. +.Sp +These two functions can be used to associate arbitrary data with a loop, +and are intended solely for the \f(CW\*(C`invoke_pending_cb\*(C'\fR, \f(CW\*(C`release\*(C'\fR and +\&\f(CW\*(C`acquire\*(C'\fR callbacks described above, but of course can be (ab\-)used for +any other purpose as well. +.IP "ev_verify (loop)" 4 +.IX Item "ev_verify (loop)" +This function only does something when \f(CW\*(C`EV_VERIFY\*(C'\fR support has been +compiled in, which is the default for non-minimal builds. It tries to go +through all internal structures and checks them for validity. If anything +is found to be inconsistent, it will print an error message to standard +error and call \f(CW\*(C`abort ()\*(C'\fR. +.Sp +This can be used to catch bugs inside libev itself: under normal +circumstances, this function will never abort as of course libev keeps its +data structures consistent. +.SH "ANATOMY OF A WATCHER" +.IX Header "ANATOMY OF A WATCHER" +In the following description, uppercase \f(CW\*(C`TYPE\*(C'\fR in names stands for the +watcher type, e.g. \f(CW\*(C`ev_TYPE_start\*(C'\fR can mean \f(CW\*(C`ev_timer_start\*(C'\fR for timer +watchers and \f(CW\*(C`ev_io_start\*(C'\fR for I/O watchers. +.PP +A watcher is an opaque structure that you allocate and register to record +your interest in some event. To make a concrete example, imagine you want +to wait for \s-1STDIN\s0 to become readable, you would create an \f(CW\*(C`ev_io\*(C'\fR watcher +for that: +.PP +.Vb 5 +\& static void my_cb (struct ev_loop *loop, ev_io *w, int revents) +\& { +\& ev_io_stop (w); +\& ev_break (loop, EVBREAK_ALL); +\& } +\& +\& struct ev_loop *loop = ev_default_loop (0); +\& +\& ev_io stdin_watcher; +\& +\& ev_init (&stdin_watcher, my_cb); +\& ev_io_set (&stdin_watcher, STDIN_FILENO, EV_READ); +\& ev_io_start (loop, &stdin_watcher); +\& +\& ev_run (loop, 0); +.Ve +.PP +As you can see, you are responsible for allocating the memory for your +watcher structures (and it is \fIusually\fR a bad idea to do this on the +stack). +.PP +Each watcher has an associated watcher structure (called \f(CW\*(C`struct ev_TYPE\*(C'\fR +or simply \f(CW\*(C`ev_TYPE\*(C'\fR, as typedefs are provided for all watcher structs). +.PP +Each watcher structure must be initialised by a call to \f(CW\*(C`ev_init (watcher +*, callback)\*(C'\fR, which expects a callback to be provided. This callback is +invoked each time the event occurs (or, in the case of I/O watchers, each +time the event loop detects that the file descriptor given is readable +and/or writable). +.PP +Each watcher type further has its own \f(CW\*(C`ev_TYPE_set (watcher *, ...)\*(C'\fR +macro to configure it, with arguments specific to the watcher type. There +is also a macro to combine initialisation and setting in one call: \f(CW\*(C`ev_TYPE_init (watcher *, callback, ...)\*(C'\fR. +.PP +To make the watcher actually watch out for events, you have to start it +with a watcher-specific start function (\f(CW\*(C`ev_TYPE_start (loop, watcher +*)\*(C'\fR), and you can stop watching for events at any time by calling the +corresponding stop function (\f(CW\*(C`ev_TYPE_stop (loop, watcher *)\*(C'\fR. +.PP +As long as your watcher is active (has been started but not stopped) you +must not touch the values stored in it. Most specifically you must never +reinitialise it or call its \f(CW\*(C`ev_TYPE_set\*(C'\fR macro. +.PP +Each and every callback receives the event loop pointer as first, the +registered watcher structure as second, and a bitset of received events as +third argument. +.PP +The received events usually include a single bit per event type received +(you can receive multiple events at the same time). The possible bit masks +are: +.ie n .IP """EV_READ""" 4 +.el .IP "\f(CWEV_READ\fR" 4 +.IX Item "EV_READ" +.PD 0 +.ie n .IP """EV_WRITE""" 4 +.el .IP "\f(CWEV_WRITE\fR" 4 +.IX Item "EV_WRITE" +.PD +The file descriptor in the \f(CW\*(C`ev_io\*(C'\fR watcher has become readable and/or +writable. +.ie n .IP """EV_TIMER""" 4 +.el .IP "\f(CWEV_TIMER\fR" 4 +.IX Item "EV_TIMER" +The \f(CW\*(C`ev_timer\*(C'\fR watcher has timed out. +.ie n .IP """EV_PERIODIC""" 4 +.el .IP "\f(CWEV_PERIODIC\fR" 4 +.IX Item "EV_PERIODIC" +The \f(CW\*(C`ev_periodic\*(C'\fR watcher has timed out. +.ie n .IP """EV_SIGNAL""" 4 +.el .IP "\f(CWEV_SIGNAL\fR" 4 +.IX Item "EV_SIGNAL" +The signal specified in the \f(CW\*(C`ev_signal\*(C'\fR watcher has been received by a thread. +.ie n .IP """EV_CHILD""" 4 +.el .IP "\f(CWEV_CHILD\fR" 4 +.IX Item "EV_CHILD" +The pid specified in the \f(CW\*(C`ev_child\*(C'\fR watcher has received a status change. +.ie n .IP """EV_STAT""" 4 +.el .IP "\f(CWEV_STAT\fR" 4 +.IX Item "EV_STAT" +The path specified in the \f(CW\*(C`ev_stat\*(C'\fR watcher changed its attributes somehow. +.ie n .IP """EV_IDLE""" 4 +.el .IP "\f(CWEV_IDLE\fR" 4 +.IX Item "EV_IDLE" +The \f(CW\*(C`ev_idle\*(C'\fR watcher has determined that you have nothing better to do. +.ie n .IP """EV_PREPARE""" 4 +.el .IP "\f(CWEV_PREPARE\fR" 4 +.IX Item "EV_PREPARE" +.PD 0 +.ie n .IP """EV_CHECK""" 4 +.el .IP "\f(CWEV_CHECK\fR" 4 +.IX Item "EV_CHECK" +.PD +All \f(CW\*(C`ev_prepare\*(C'\fR watchers are invoked just \fIbefore\fR \f(CW\*(C`ev_run\*(C'\fR starts to +gather new events, and all \f(CW\*(C`ev_check\*(C'\fR watchers are queued (not invoked) +just after \f(CW\*(C`ev_run\*(C'\fR has gathered them, but before it queues any callbacks +for any received events. That means \f(CW\*(C`ev_prepare\*(C'\fR watchers are the last +watchers invoked before the event loop sleeps or polls for new events, and +\&\f(CW\*(C`ev_check\*(C'\fR watchers will be invoked before any other watchers of the same +or lower priority within an event loop iteration. +.Sp +Callbacks of both watcher types can start and stop as many watchers as +they want, and all of them will be taken into account (for example, a +\&\f(CW\*(C`ev_prepare\*(C'\fR watcher might start an idle watcher to keep \f(CW\*(C`ev_run\*(C'\fR from +blocking). +.ie n .IP """EV_EMBED""" 4 +.el .IP "\f(CWEV_EMBED\fR" 4 +.IX Item "EV_EMBED" +The embedded event loop specified in the \f(CW\*(C`ev_embed\*(C'\fR watcher needs attention. +.ie n .IP """EV_FORK""" 4 +.el .IP "\f(CWEV_FORK\fR" 4 +.IX Item "EV_FORK" +The event loop has been resumed in the child process after fork (see +\&\f(CW\*(C`ev_fork\*(C'\fR). +.ie n .IP """EV_CLEANUP""" 4 +.el .IP "\f(CWEV_CLEANUP\fR" 4 +.IX Item "EV_CLEANUP" +The event loop is about to be destroyed (see \f(CW\*(C`ev_cleanup\*(C'\fR). +.ie n .IP """EV_ASYNC""" 4 +.el .IP "\f(CWEV_ASYNC\fR" 4 +.IX Item "EV_ASYNC" +The given async watcher has been asynchronously notified (see \f(CW\*(C`ev_async\*(C'\fR). +.ie n .IP """EV_CUSTOM""" 4 +.el .IP "\f(CWEV_CUSTOM\fR" 4 +.IX Item "EV_CUSTOM" +Not ever sent (or otherwise used) by libev itself, but can be freely used +by libev users to signal watchers (e.g. via \f(CW\*(C`ev_feed_event\*(C'\fR). +.ie n .IP """EV_ERROR""" 4 +.el .IP "\f(CWEV_ERROR\fR" 4 +.IX Item "EV_ERROR" +An unspecified error has occurred, the watcher has been stopped. This might +happen because the watcher could not be properly started because libev +ran out of memory, a file descriptor was found to be closed or any other +problem. Libev considers these application bugs. +.Sp +You best act on it by reporting the problem and somehow coping with the +watcher being stopped. Note that well-written programs should not receive +an error ever, so when your watcher receives it, this usually indicates a +bug in your program. +.Sp +Libev will usually signal a few \*(L"dummy\*(R" events together with an error, for +example it might indicate that a fd is readable or writable, and if your +callbacks is well-written it can just attempt the operation and cope with +the error from \fIread()\fR or \fIwrite()\fR. This will not work in multi-threaded +programs, though, as the fd could already be closed and reused for another +thing, so beware. +.SS "\s-1GENERIC WATCHER FUNCTIONS\s0" +.IX Subsection "GENERIC WATCHER FUNCTIONS" +.ie n .IP """ev_init"" (ev_TYPE *watcher, callback)" 4 +.el .IP "\f(CWev_init\fR (ev_TYPE *watcher, callback)" 4 +.IX Item "ev_init (ev_TYPE *watcher, callback)" +This macro initialises the generic portion of a watcher. The contents +of the watcher object can be arbitrary (so \f(CW\*(C`malloc\*(C'\fR will do). Only +the generic parts of the watcher are initialised, you \fIneed\fR to call +the type-specific \f(CW\*(C`ev_TYPE_set\*(C'\fR macro afterwards to initialise the +type-specific parts. For each type there is also a \f(CW\*(C`ev_TYPE_init\*(C'\fR macro +which rolls both calls into one. +.Sp +You can reinitialise a watcher at any time as long as it has been stopped +(or never started) and there are no pending events outstanding. +.Sp +The callback is always of type \f(CW\*(C`void (*)(struct ev_loop *loop, ev_TYPE *watcher, +int revents)\*(C'\fR. +.Sp +Example: Initialise an \f(CW\*(C`ev_io\*(C'\fR watcher in two steps. +.Sp +.Vb 3 +\& ev_io w; +\& ev_init (&w, my_cb); +\& ev_io_set (&w, STDIN_FILENO, EV_READ); +.Ve +.ie n .IP """ev_TYPE_set"" (ev_TYPE *watcher, [args])" 4 +.el .IP "\f(CWev_TYPE_set\fR (ev_TYPE *watcher, [args])" 4 +.IX Item "ev_TYPE_set (ev_TYPE *watcher, [args])" +This macro initialises the type-specific parts of a watcher. You need to +call \f(CW\*(C`ev_init\*(C'\fR at least once before you call this macro, but you can +call \f(CW\*(C`ev_TYPE_set\*(C'\fR any number of times. You must not, however, call this +macro on a watcher that is active (it can be pending, however, which is a +difference to the \f(CW\*(C`ev_init\*(C'\fR macro). +.Sp +Although some watcher types do not have type-specific arguments +(e.g. \f(CW\*(C`ev_prepare\*(C'\fR) you still need to call its \f(CW\*(C`set\*(C'\fR macro. +.Sp +See \f(CW\*(C`ev_init\*(C'\fR, above, for an example. +.ie n .IP """ev_TYPE_init"" (ev_TYPE *watcher, callback, [args])" 4 +.el .IP "\f(CWev_TYPE_init\fR (ev_TYPE *watcher, callback, [args])" 4 +.IX Item "ev_TYPE_init (ev_TYPE *watcher, callback, [args])" +This convenience macro rolls both \f(CW\*(C`ev_init\*(C'\fR and \f(CW\*(C`ev_TYPE_set\*(C'\fR macro +calls into a single call. This is the most convenient method to initialise +a watcher. The same limitations apply, of course. +.Sp +Example: Initialise and set an \f(CW\*(C`ev_io\*(C'\fR watcher in one step. +.Sp +.Vb 1 +\& ev_io_init (&w, my_cb, STDIN_FILENO, EV_READ); +.Ve +.ie n .IP """ev_TYPE_start"" (loop, ev_TYPE *watcher)" 4 +.el .IP "\f(CWev_TYPE_start\fR (loop, ev_TYPE *watcher)" 4 +.IX Item "ev_TYPE_start (loop, ev_TYPE *watcher)" +Starts (activates) the given watcher. Only active watchers will receive +events. If the watcher is already active nothing will happen. +.Sp +Example: Start the \f(CW\*(C`ev_io\*(C'\fR watcher that is being abused as example in this +whole section. +.Sp +.Vb 1 +\& ev_io_start (EV_DEFAULT_UC, &w); +.Ve +.ie n .IP """ev_TYPE_stop"" (loop, ev_TYPE *watcher)" 4 +.el .IP "\f(CWev_TYPE_stop\fR (loop, ev_TYPE *watcher)" 4 +.IX Item "ev_TYPE_stop (loop, ev_TYPE *watcher)" +Stops the given watcher if active, and clears the pending status (whether +the watcher was active or not). +.Sp +It is possible that stopped watchers are pending \- for example, +non-repeating timers are being stopped when they become pending \- but +calling \f(CW\*(C`ev_TYPE_stop\*(C'\fR ensures that the watcher is neither active nor +pending. If you want to free or reuse the memory used by the watcher it is +therefore a good idea to always call its \f(CW\*(C`ev_TYPE_stop\*(C'\fR function. +.IP "bool ev_is_active (ev_TYPE *watcher)" 4 +.IX Item "bool ev_is_active (ev_TYPE *watcher)" +Returns a true value iff the watcher is active (i.e. it has been started +and not yet been stopped). As long as a watcher is active you must not modify +it. +.IP "bool ev_is_pending (ev_TYPE *watcher)" 4 +.IX Item "bool ev_is_pending (ev_TYPE *watcher)" +Returns a true value iff the watcher is pending, (i.e. it has outstanding +events but its callback has not yet been invoked). As long as a watcher +is pending (but not active) you must not call an init function on it (but +\&\f(CW\*(C`ev_TYPE_set\*(C'\fR is safe), you must not change its priority, and you must +make sure the watcher is available to libev (e.g. you cannot \f(CW\*(C`free ()\*(C'\fR +it). +.IP "callback ev_cb (ev_TYPE *watcher)" 4 +.IX Item "callback ev_cb (ev_TYPE *watcher)" +Returns the callback currently set on the watcher. +.IP "ev_set_cb (ev_TYPE *watcher, callback)" 4 +.IX Item "ev_set_cb (ev_TYPE *watcher, callback)" +Change the callback. You can change the callback at virtually any time +(modulo threads). +.IP "ev_set_priority (ev_TYPE *watcher, int priority)" 4 +.IX Item "ev_set_priority (ev_TYPE *watcher, int priority)" +.PD 0 +.IP "int ev_priority (ev_TYPE *watcher)" 4 +.IX Item "int ev_priority (ev_TYPE *watcher)" +.PD +Set and query the priority of the watcher. The priority is a small +integer between \f(CW\*(C`EV_MAXPRI\*(C'\fR (default: \f(CW2\fR) and \f(CW\*(C`EV_MINPRI\*(C'\fR +(default: \f(CW\*(C`\-2\*(C'\fR). Pending watchers with higher priority will be invoked +before watchers with lower priority, but priority will not keep watchers +from being executed (except for \f(CW\*(C`ev_idle\*(C'\fR watchers). +.Sp +If you need to suppress invocation when higher priority events are pending +you need to look at \f(CW\*(C`ev_idle\*(C'\fR watchers, which provide this functionality. +.Sp +You \fImust not\fR change the priority of a watcher as long as it is active or +pending. +.Sp +Setting a priority outside the range of \f(CW\*(C`EV_MINPRI\*(C'\fR to \f(CW\*(C`EV_MAXPRI\*(C'\fR is +fine, as long as you do not mind that the priority value you query might +or might not have been clamped to the valid range. +.Sp +The default priority used by watchers when no priority has been set is +always \f(CW0\fR, which is supposed to not be too high and not be too low :). +.Sp +See \*(L"\s-1WATCHER PRIORITY MODELS\*(R"\s0, below, for a more thorough treatment of +priorities. +.IP "ev_invoke (loop, ev_TYPE *watcher, int revents)" 4 +.IX Item "ev_invoke (loop, ev_TYPE *watcher, int revents)" +Invoke the \f(CW\*(C`watcher\*(C'\fR with the given \f(CW\*(C`loop\*(C'\fR and \f(CW\*(C`revents\*(C'\fR. Neither +\&\f(CW\*(C`loop\*(C'\fR nor \f(CW\*(C`revents\*(C'\fR need to be valid as long as the watcher callback +can deal with that fact, as both are simply passed through to the +callback. +.IP "int ev_clear_pending (loop, ev_TYPE *watcher)" 4 +.IX Item "int ev_clear_pending (loop, ev_TYPE *watcher)" +If the watcher is pending, this function clears its pending status and +returns its \f(CW\*(C`revents\*(C'\fR bitset (as if its callback was invoked). If the +watcher isn't pending it does nothing and returns \f(CW0\fR. +.Sp +Sometimes it can be useful to \*(L"poll\*(R" a watcher instead of waiting for its +callback to be invoked, which can be accomplished with this function. +.IP "ev_feed_event (loop, ev_TYPE *watcher, int revents)" 4 +.IX Item "ev_feed_event (loop, ev_TYPE *watcher, int revents)" +Feeds the given event set into the event loop, as if the specified event +had happened for the specified watcher (which must be a pointer to an +initialised but not necessarily started event watcher). Obviously you must +not free the watcher as long as it has pending events. +.Sp +Stopping the watcher, letting libev invoke it, or calling +\&\f(CW\*(C`ev_clear_pending\*(C'\fR will clear the pending event, even if the watcher was +not started in the first place. +.Sp +See also \f(CW\*(C`ev_feed_fd_event\*(C'\fR and \f(CW\*(C`ev_feed_signal_event\*(C'\fR for related +functions that do not need a watcher. +.PP +See also the \*(L"\s-1ASSOCIATING CUSTOM DATA WITH A WATCHER\*(R"\s0 and \*(L"\s-1BUILDING YOUR +OWN COMPOSITE WATCHERS\*(R"\s0 idioms. +.SS "\s-1WATCHER STATES\s0" +.IX Subsection "WATCHER STATES" +There are various watcher states mentioned throughout this manual \- +active, pending and so on. In this section these states and the rules to +transition between them will be described in more detail \- and while these +rules might look complicated, they usually do \*(L"the right thing\*(R". +.IP "initialised" 4 +.IX Item "initialised" +Before a watcher can be registered with the event loop it has to be +initialised. This can be done with a call to \f(CW\*(C`ev_TYPE_init\*(C'\fR, or calls to +\&\f(CW\*(C`ev_init\*(C'\fR followed by the watcher-specific \f(CW\*(C`ev_TYPE_set\*(C'\fR function. +.Sp +In this state it is simply some block of memory that is suitable for +use in an event loop. It can be moved around, freed, reused etc. at +will \- as long as you either keep the memory contents intact, or call +\&\f(CW\*(C`ev_TYPE_init\*(C'\fR again. +.IP "started/running/active" 4 +.IX Item "started/running/active" +Once a watcher has been started with a call to \f(CW\*(C`ev_TYPE_start\*(C'\fR it becomes +property of the event loop, and is actively waiting for events. While in +this state it cannot be accessed (except in a few documented ways), moved, +freed or anything else \- the only legal thing is to keep a pointer to it, +and call libev functions on it that are documented to work on active watchers. +.IP "pending" 4 +.IX Item "pending" +If a watcher is active and libev determines that an event it is interested +in has occurred (such as a timer expiring), it will become pending. It will +stay in this pending state until either it is stopped or its callback is +about to be invoked, so it is not normally pending inside the watcher +callback. +.Sp +The watcher might or might not be active while it is pending (for example, +an expired non-repeating timer can be pending but no longer active). If it +is stopped, it can be freely accessed (e.g. by calling \f(CW\*(C`ev_TYPE_set\*(C'\fR), +but it is still property of the event loop at this time, so cannot be +moved, freed or reused. And if it is active the rules described in the +previous item still apply. +.Sp +It is also possible to feed an event on a watcher that is not active (e.g. +via \f(CW\*(C`ev_feed_event\*(C'\fR), in which case it becomes pending without being +active. +.IP "stopped" 4 +.IX Item "stopped" +A watcher can be stopped implicitly by libev (in which case it might still +be pending), or explicitly by calling its \f(CW\*(C`ev_TYPE_stop\*(C'\fR function. The +latter will clear any pending state the watcher might be in, regardless +of whether it was active or not, so stopping a watcher explicitly before +freeing it is often a good idea. +.Sp +While stopped (and not pending) the watcher is essentially in the +initialised state, that is, it can be reused, moved, modified in any way +you wish (but when you trash the memory block, you need to \f(CW\*(C`ev_TYPE_init\*(C'\fR +it again). +.SS "\s-1WATCHER PRIORITY MODELS\s0" +.IX Subsection "WATCHER PRIORITY MODELS" +Many event loops support \fIwatcher priorities\fR, which are usually small +integers that influence the ordering of event callback invocation +between watchers in some way, all else being equal. +.PP +In libev, Watcher priorities can be set using \f(CW\*(C`ev_set_priority\*(C'\fR. See its +description for the more technical details such as the actual priority +range. +.PP +There are two common ways how these these priorities are being interpreted +by event loops: +.PP +In the more common lock-out model, higher priorities \*(L"lock out\*(R" invocation +of lower priority watchers, which means as long as higher priority +watchers receive events, lower priority watchers are not being invoked. +.PP +The less common only-for-ordering model uses priorities solely to order +callback invocation within a single event loop iteration: Higher priority +watchers are invoked before lower priority ones, but they all get invoked +before polling for new events. +.PP +Libev uses the second (only-for-ordering) model for all its watchers +except for idle watchers (which use the lock-out model). +.PP +The rationale behind this is that implementing the lock-out model for +watchers is not well supported by most kernel interfaces, and most event +libraries will just poll for the same events again and again as long as +their callbacks have not been executed, which is very inefficient in the +common case of one high-priority watcher locking out a mass of lower +priority ones. +.PP +Static (ordering) priorities are most useful when you have two or more +watchers handling the same resource: a typical usage example is having an +\&\f(CW\*(C`ev_io\*(C'\fR watcher to receive data, and an associated \f(CW\*(C`ev_timer\*(C'\fR to handle +timeouts. Under load, data might be received while the program handles +other jobs, but since timers normally get invoked first, the timeout +handler will be executed before checking for data. In that case, giving +the timer a lower priority than the I/O watcher ensures that I/O will be +handled first even under adverse conditions (which is usually, but not +always, what you want). +.PP +Since idle watchers use the \*(L"lock-out\*(R" model, meaning that idle watchers +will only be executed when no same or higher priority watchers have +received events, they can be used to implement the \*(L"lock-out\*(R" model when +required. +.PP +For example, to emulate how many other event libraries handle priorities, +you can associate an \f(CW\*(C`ev_idle\*(C'\fR watcher to each such watcher, and in +the normal watcher callback, you just start the idle watcher. The real +processing is done in the idle watcher callback. This causes libev to +continuously poll and process kernel event data for the watcher, but when +the lock-out case is known to be rare (which in turn is rare :), this is +workable. +.PP +Usually, however, the lock-out model implemented that way will perform +miserably under the type of load it was designed to handle. In that case, +it might be preferable to stop the real watcher before starting the +idle watcher, so the kernel will not have to process the event in case +the actual processing will be delayed for considerable time. +.PP +Here is an example of an I/O watcher that should run at a strictly lower +priority than the default, and which should only process data when no +other events are pending: +.PP +.Vb 2 +\& ev_idle idle; // actual processing watcher +\& ev_io io; // actual event watcher +\& +\& static void +\& io_cb (EV_P_ ev_io *w, int revents) +\& { +\& // stop the I/O watcher, we received the event, but +\& // are not yet ready to handle it. +\& ev_io_stop (EV_A_ w); +\& +\& // start the idle watcher to handle the actual event. +\& // it will not be executed as long as other watchers +\& // with the default priority are receiving events. +\& ev_idle_start (EV_A_ &idle); +\& } +\& +\& static void +\& idle_cb (EV_P_ ev_idle *w, int revents) +\& { +\& // actual processing +\& read (STDIN_FILENO, ...); +\& +\& // have to start the I/O watcher again, as +\& // we have handled the event +\& ev_io_start (EV_P_ &io); +\& } +\& +\& // initialisation +\& ev_idle_init (&idle, idle_cb); +\& ev_io_init (&io, io_cb, STDIN_FILENO, EV_READ); +\& ev_io_start (EV_DEFAULT_ &io); +.Ve +.PP +In the \*(L"real\*(R" world, it might also be beneficial to start a timer, so that +low-priority connections can not be locked out forever under load. This +enables your program to keep a lower latency for important connections +during short periods of high load, while not completely locking out less +important ones. +.SH "WATCHER TYPES" +.IX Header "WATCHER TYPES" +This section describes each watcher in detail, but will not repeat +information given in the last section. Any initialisation/set macros, +functions and members specific to the watcher type are explained. +.PP +Members are additionally marked with either \fI[read\-only]\fR, meaning that, +while the watcher is active, you can look at the member and expect some +sensible content, but you must not modify it (you can modify it while the +watcher is stopped to your hearts content), or \fI[read\-write]\fR, which +means you can expect it to have some sensible content while the watcher +is active, but you can also modify it. Modifying it may not do something +sensible or take immediate effect (or do anything at all), but libev will +not crash or malfunction in any way. +.ie n .SS """ev_io"" \- is this file descriptor readable or writable?" +.el .SS "\f(CWev_io\fP \- is this file descriptor readable or writable?" +.IX Subsection "ev_io - is this file descriptor readable or writable?" +I/O watchers check whether a file descriptor is readable or writable +in each iteration of the event loop, or, more precisely, when reading +would not block the process and writing would at least be able to write +some data. This behaviour is called level-triggering because you keep +receiving events as long as the condition persists. Remember you can stop +the watcher if you don't want to act on the event and neither want to +receive future events. +.PP +In general you can register as many read and/or write event watchers per +fd as you want (as long as you don't confuse yourself). Setting all file +descriptors to non-blocking mode is also usually a good idea (but not +required if you know what you are doing). +.PP +Another thing you have to watch out for is that it is quite easy to +receive \*(L"spurious\*(R" readiness notifications, that is, your callback might +be called with \f(CW\*(C`EV_READ\*(C'\fR but a subsequent \f(CW\*(C`read\*(C'\fR(2) will actually block +because there is no data. It is very easy to get into this situation even +with a relatively standard program structure. Thus it is best to always +use non-blocking I/O: An extra \f(CW\*(C`read\*(C'\fR(2) returning \f(CW\*(C`EAGAIN\*(C'\fR is far +preferable to a program hanging until some data arrives. +.PP +If you cannot run the fd in non-blocking mode (for example you should +not play around with an Xlib connection), then you have to separately +re-test whether a file descriptor is really ready with a known-to-be good +interface such as poll (fortunately in the case of Xlib, it already does +this on its own, so its quite safe to use). Some people additionally +use \f(CW\*(C`SIGALRM\*(C'\fR and an interval timer, just to be sure you won't block +indefinitely. +.PP +But really, best use non-blocking mode. +.PP +\fIThe special problem of disappearing file descriptors\fR +.IX Subsection "The special problem of disappearing file descriptors" +.PP +Some backends (e.g. kqueue, epoll) need to be told about closing a file +descriptor (either due to calling \f(CW\*(C`close\*(C'\fR explicitly or any other means, +such as \f(CW\*(C`dup2\*(C'\fR). The reason is that you register interest in some file +descriptor, but when it goes away, the operating system will silently drop +this interest. If another file descriptor with the same number then is +registered with libev, there is no efficient way to see that this is, in +fact, a different file descriptor. +.PP +To avoid having to explicitly tell libev about such cases, libev follows +the following policy: Each time \f(CW\*(C`ev_io_set\*(C'\fR is being called, libev +will assume that this is potentially a new file descriptor, otherwise +it is assumed that the file descriptor stays the same. That means that +you \fIhave\fR to call \f(CW\*(C`ev_io_set\*(C'\fR (or \f(CW\*(C`ev_io_init\*(C'\fR) when you change the +descriptor even if the file descriptor number itself did not change. +.PP +This is how one would do it normally anyway, the important point is that +the libev application should not optimise around libev but should leave +optimisations to libev. +.PP +\fIThe special problem of dup'ed file descriptors\fR +.IX Subsection "The special problem of dup'ed file descriptors" +.PP +Some backends (e.g. epoll), cannot register events for file descriptors, +but only events for the underlying file descriptions. That means when you +have \f(CW\*(C`dup ()\*(C'\fR'ed file descriptors or weirder constellations, and register +events for them, only one file descriptor might actually receive events. +.PP +There is no workaround possible except not registering events +for potentially \f(CW\*(C`dup ()\*(C'\fR'ed file descriptors, or to resort to +\&\f(CW\*(C`EVBACKEND_SELECT\*(C'\fR or \f(CW\*(C`EVBACKEND_POLL\*(C'\fR. +.PP +\fIThe special problem of files\fR +.IX Subsection "The special problem of files" +.PP +Many people try to use \f(CW\*(C`select\*(C'\fR (or libev) on file descriptors +representing files, and expect it to become ready when their program +doesn't block on disk accesses (which can take a long time on their own). +.PP +However, this cannot ever work in the \*(L"expected\*(R" way \- you get a readiness +notification as soon as the kernel knows whether and how much data is +there, and in the case of open files, that's always the case, so you +always get a readiness notification instantly, and your read (or possibly +write) will still block on the disk I/O. +.PP +Another way to view it is that in the case of sockets, pipes, character +devices and so on, there is another party (the sender) that delivers data +on its own, but in the case of files, there is no such thing: the disk +will not send data on its own, simply because it doesn't know what you +wish to read \- you would first have to request some data. +.PP +Since files are typically not-so-well supported by advanced notification +mechanism, libev tries hard to emulate \s-1POSIX\s0 behaviour with respect +to files, even though you should not use it. The reason for this is +convenience: sometimes you want to watch \s-1STDIN\s0 or \s-1STDOUT,\s0 which is +usually a tty, often a pipe, but also sometimes files or special devices +(for example, \f(CW\*(C`epoll\*(C'\fR on Linux works with \fI/dev/random\fR but not with +\&\fI/dev/urandom\fR), and even though the file might better be served with +asynchronous I/O instead of with non-blocking I/O, it is still useful when +it \*(L"just works\*(R" instead of freezing. +.PP +So avoid file descriptors pointing to files when you know it (e.g. use +libeio), but use them when it is convenient, e.g. for \s-1STDIN/STDOUT,\s0 or +when you rarely read from a file instead of from a socket, and want to +reuse the same code path. +.PP +\fIThe special problem of fork\fR +.IX Subsection "The special problem of fork" +.PP +Some backends (epoll, kqueue) do not support \f(CW\*(C`fork ()\*(C'\fR at all or exhibit +useless behaviour. Libev fully supports fork, but needs to be told about +it in the child if you want to continue to use it in the child. +.PP +To support fork in your child processes, you have to call \f(CW\*(C`ev_loop_fork +()\*(C'\fR after a fork in the child, enable \f(CW\*(C`EVFLAG_FORKCHECK\*(C'\fR, or resort to +\&\f(CW\*(C`EVBACKEND_SELECT\*(C'\fR or \f(CW\*(C`EVBACKEND_POLL\*(C'\fR. +.PP +\fIThe special problem of \s-1SIGPIPE\s0\fR +.IX Subsection "The special problem of SIGPIPE" +.PP +While not really specific to libev, it is easy to forget about \f(CW\*(C`SIGPIPE\*(C'\fR: +when writing to a pipe whose other end has been closed, your program gets +sent a \s-1SIGPIPE,\s0 which, by default, aborts your program. For most programs +this is sensible behaviour, for daemons, this is usually undesirable. +.PP +So when you encounter spurious, unexplained daemon exits, make sure you +ignore \s-1SIGPIPE \s0(and maybe make sure you log the exit status of your daemon +somewhere, as that would have given you a big clue). +.PP +\fIThe special problem of \fIaccept()\fIing when you can't\fR +.IX Subsection "The special problem of accept()ing when you can't" +.PP +Many implementations of the \s-1POSIX \s0\f(CW\*(C`accept\*(C'\fR function (for example, +found in post\-2004 Linux) have the peculiar behaviour of not removing a +connection from the pending queue in all error cases. +.PP +For example, larger servers often run out of file descriptors (because +of resource limits), causing \f(CW\*(C`accept\*(C'\fR to fail with \f(CW\*(C`ENFILE\*(C'\fR but not +rejecting the connection, leading to libev signalling readiness on +the next iteration again (the connection still exists after all), and +typically causing the program to loop at 100% \s-1CPU\s0 usage. +.PP +Unfortunately, the set of errors that cause this issue differs between +operating systems, there is usually little the app can do to remedy the +situation, and no known thread-safe method of removing the connection to +cope with overload is known (to me). +.PP +One of the easiest ways to handle this situation is to just ignore it +\&\- when the program encounters an overload, it will just loop until the +situation is over. While this is a form of busy waiting, no \s-1OS\s0 offers an +event-based way to handle this situation, so it's the best one can do. +.PP +A better way to handle the situation is to log any errors other than +\&\f(CW\*(C`EAGAIN\*(C'\fR and \f(CW\*(C`EWOULDBLOCK\*(C'\fR, making sure not to flood the log with such +messages, and continue as usual, which at least gives the user an idea of +what could be wrong (\*(L"raise the ulimit!\*(R"). For extra points one could stop +the \f(CW\*(C`ev_io\*(C'\fR watcher on the listening fd \*(L"for a while\*(R", which reduces \s-1CPU\s0 +usage. +.PP +If your program is single-threaded, then you could also keep a dummy file +descriptor for overload situations (e.g. by opening \fI/dev/null\fR), and +when you run into \f(CW\*(C`ENFILE\*(C'\fR or \f(CW\*(C`EMFILE\*(C'\fR, close it, run \f(CW\*(C`accept\*(C'\fR, +close that fd, and create a new dummy fd. This will gracefully refuse +clients under typical overload conditions. +.PP +The last way to handle it is to simply log the error and \f(CW\*(C`exit\*(C'\fR, as +is often done with \f(CW\*(C`malloc\*(C'\fR failures, but this results in an easy +opportunity for a DoS attack. +.PP +\fIWatcher-Specific Functions\fR +.IX Subsection "Watcher-Specific Functions" +.IP "ev_io_init (ev_io *, callback, int fd, int events)" 4 +.IX Item "ev_io_init (ev_io *, callback, int fd, int events)" +.PD 0 +.IP "ev_io_set (ev_io *, int fd, int events)" 4 +.IX Item "ev_io_set (ev_io *, int fd, int events)" +.PD +Configures an \f(CW\*(C`ev_io\*(C'\fR watcher. The \f(CW\*(C`fd\*(C'\fR is the file descriptor to +receive events for and \f(CW\*(C`events\*(C'\fR is either \f(CW\*(C`EV_READ\*(C'\fR, \f(CW\*(C`EV_WRITE\*(C'\fR or +\&\f(CW\*(C`EV_READ | EV_WRITE\*(C'\fR, to express the desire to receive the given events. +.IP "int fd [read\-only]" 4 +.IX Item "int fd [read-only]" +The file descriptor being watched. +.IP "int events [read\-only]" 4 +.IX Item "int events [read-only]" +The events being watched. +.PP +\fIExamples\fR +.IX Subsection "Examples" +.PP +Example: Call \f(CW\*(C`stdin_readable_cb\*(C'\fR when \s-1STDIN_FILENO\s0 has become, well +readable, but only once. Since it is likely line-buffered, you could +attempt to read a whole line in the callback. +.PP +.Vb 6 +\& static void +\& stdin_readable_cb (struct ev_loop *loop, ev_io *w, int revents) +\& { +\& ev_io_stop (loop, w); +\& .. read from stdin here (or from w\->fd) and handle any I/O errors +\& } +\& +\& ... +\& struct ev_loop *loop = ev_default_init (0); +\& ev_io stdin_readable; +\& ev_io_init (&stdin_readable, stdin_readable_cb, STDIN_FILENO, EV_READ); +\& ev_io_start (loop, &stdin_readable); +\& ev_run (loop, 0); +.Ve +.ie n .SS """ev_timer"" \- relative and optionally repeating timeouts" +.el .SS "\f(CWev_timer\fP \- relative and optionally repeating timeouts" +.IX Subsection "ev_timer - relative and optionally repeating timeouts" +Timer watchers are simple relative timers that generate an event after a +given time, and optionally repeating in regular intervals after that. +.PP +The timers are based on real time, that is, if you register an event that +times out after an hour and you reset your system clock to January last +year, it will still time out after (roughly) one hour. \*(L"Roughly\*(R" because +detecting time jumps is hard, and some inaccuracies are unavoidable (the +monotonic clock option helps a lot here). +.PP +The callback is guaranteed to be invoked only \fIafter\fR its timeout has +passed (not \fIat\fR, so on systems with very low-resolution clocks this +might introduce a small delay, see \*(L"the special problem of being too +early\*(R", below). If multiple timers become ready during the same loop +iteration then the ones with earlier time-out values are invoked before +ones of the same priority with later time-out values (but this is no +longer true when a callback calls \f(CW\*(C`ev_run\*(C'\fR recursively). +.PP +\fIBe smart about timeouts\fR +.IX Subsection "Be smart about timeouts" +.PP +Many real-world problems involve some kind of timeout, usually for error +recovery. A typical example is an \s-1HTTP\s0 request \- if the other side hangs, +you want to raise some error after a while. +.PP +What follows are some ways to handle this problem, from obvious and +inefficient to smart and efficient. +.PP +In the following, a 60 second activity timeout is assumed \- a timeout that +gets reset to 60 seconds each time there is activity (e.g. each time some +data or other life sign was received). +.IP "1. Use a timer and stop, reinitialise and start it on activity." 4 +.IX Item "1. Use a timer and stop, reinitialise and start it on activity." +This is the most obvious, but not the most simple way: In the beginning, +start the watcher: +.Sp +.Vb 2 +\& ev_timer_init (timer, callback, 60., 0.); +\& ev_timer_start (loop, timer); +.Ve +.Sp +Then, each time there is some activity, \f(CW\*(C`ev_timer_stop\*(C'\fR it, initialise it +and start it again: +.Sp +.Vb 3 +\& ev_timer_stop (loop, timer); +\& ev_timer_set (timer, 60., 0.); +\& ev_timer_start (loop, timer); +.Ve +.Sp +This is relatively simple to implement, but means that each time there is +some activity, libev will first have to remove the timer from its internal +data structure and then add it again. Libev tries to be fast, but it's +still not a constant-time operation. +.ie n .IP "2. Use a timer and re-start it with ""ev_timer_again"" inactivity." 4 +.el .IP "2. Use a timer and re-start it with \f(CWev_timer_again\fR inactivity." 4 +.IX Item "2. Use a timer and re-start it with ev_timer_again inactivity." +This is the easiest way, and involves using \f(CW\*(C`ev_timer_again\*(C'\fR instead of +\&\f(CW\*(C`ev_timer_start\*(C'\fR. +.Sp +To implement this, configure an \f(CW\*(C`ev_timer\*(C'\fR with a \f(CW\*(C`repeat\*(C'\fR value +of \f(CW60\fR and then call \f(CW\*(C`ev_timer_again\*(C'\fR at start and each time you +successfully read or write some data. If you go into an idle state where +you do not expect data to travel on the socket, you can \f(CW\*(C`ev_timer_stop\*(C'\fR +the timer, and \f(CW\*(C`ev_timer_again\*(C'\fR will automatically restart it if need be. +.Sp +That means you can ignore both the \f(CW\*(C`ev_timer_start\*(C'\fR function and the +\&\f(CW\*(C`after\*(C'\fR argument to \f(CW\*(C`ev_timer_set\*(C'\fR, and only ever use the \f(CW\*(C`repeat\*(C'\fR +member and \f(CW\*(C`ev_timer_again\*(C'\fR. +.Sp +At start: +.Sp +.Vb 3 +\& ev_init (timer, callback); +\& timer\->repeat = 60.; +\& ev_timer_again (loop, timer); +.Ve +.Sp +Each time there is some activity: +.Sp +.Vb 1 +\& ev_timer_again (loop, timer); +.Ve +.Sp +It is even possible to change the time-out on the fly, regardless of +whether the watcher is active or not: +.Sp +.Vb 2 +\& timer\->repeat = 30.; +\& ev_timer_again (loop, timer); +.Ve +.Sp +This is slightly more efficient then stopping/starting the timer each time +you want to modify its timeout value, as libev does not have to completely +remove and re-insert the timer from/into its internal data structure. +.Sp +It is, however, even simpler than the \*(L"obvious\*(R" way to do it. +.IP "3. Let the timer time out, but then re-arm it as required." 4 +.IX Item "3. Let the timer time out, but then re-arm it as required." +This method is more tricky, but usually most efficient: Most timeouts are +relatively long compared to the intervals between other activity \- in +our example, within 60 seconds, there are usually many I/O events with +associated activity resets. +.Sp +In this case, it would be more efficient to leave the \f(CW\*(C`ev_timer\*(C'\fR alone, +but remember the time of last activity, and check for a real timeout only +within the callback: +.Sp +.Vb 3 +\& ev_tstamp timeout = 60.; +\& ev_tstamp last_activity; // time of last activity +\& ev_timer timer; +\& +\& static void +\& callback (EV_P_ ev_timer *w, int revents) +\& { +\& // calculate when the timeout would happen +\& ev_tstamp after = last_activity \- ev_now (EV_A) + timeout; +\& +\& // if negative, it means we the timeout already occurred +\& if (after < 0.) +\& { +\& // timeout occurred, take action +\& } +\& else +\& { +\& // callback was invoked, but there was some recent +\& // activity. simply restart the timer to time out +\& // after "after" seconds, which is the earliest time +\& // the timeout can occur. +\& ev_timer_set (w, after, 0.); +\& ev_timer_start (EV_A_ w); +\& } +\& } +.Ve +.Sp +To summarise the callback: first calculate in how many seconds the +timeout will occur (by calculating the absolute time when it would occur, +\&\f(CW\*(C`last_activity + timeout\*(C'\fR, and subtracting the current time, \f(CW\*(C`ev_now +(EV_A)\*(C'\fR from that). +.Sp +If this value is negative, then we are already past the timeout, i.e. we +timed out, and need to do whatever is needed in this case. +.Sp +Otherwise, we now the earliest time at which the timeout would trigger, +and simply start the timer with this timeout value. +.Sp +In other words, each time the callback is invoked it will check whether +the timeout occurred. If not, it will simply reschedule itself to check +again at the earliest time it could time out. Rinse. Repeat. +.Sp +This scheme causes more callback invocations (about one every 60 seconds +minus half the average time between activity), but virtually no calls to +libev to change the timeout. +.Sp +To start the machinery, simply initialise the watcher and set +\&\f(CW\*(C`last_activity\*(C'\fR to the current time (meaning there was some activity just +now), then call the callback, which will \*(L"do the right thing\*(R" and start +the timer: +.Sp +.Vb 3 +\& last_activity = ev_now (EV_A); +\& ev_init (&timer, callback); +\& callback (EV_A_ &timer, 0); +.Ve +.Sp +When there is some activity, simply store the current time in +\&\f(CW\*(C`last_activity\*(C'\fR, no libev calls at all: +.Sp +.Vb 2 +\& if (activity detected) +\& last_activity = ev_now (EV_A); +.Ve +.Sp +When your timeout value changes, then the timeout can be changed by simply +providing a new value, stopping the timer and calling the callback, which +will again do the right thing (for example, time out immediately :). +.Sp +.Vb 3 +\& timeout = new_value; +\& ev_timer_stop (EV_A_ &timer); +\& callback (EV_A_ &timer, 0); +.Ve +.Sp +This technique is slightly more complex, but in most cases where the +time-out is unlikely to be triggered, much more efficient. +.IP "4. Wee, just use a double-linked list for your timeouts." 4 +.IX Item "4. Wee, just use a double-linked list for your timeouts." +If there is not one request, but many thousands (millions...), all +employing some kind of timeout with the same timeout value, then one can +do even better: +.Sp +When starting the timeout, calculate the timeout value and put the timeout +at the \fIend\fR of the list. +.Sp +Then use an \f(CW\*(C`ev_timer\*(C'\fR to fire when the timeout at the \fIbeginning\fR of +the list is expected to fire (for example, using the technique #3). +.Sp +When there is some activity, remove the timer from the list, recalculate +the timeout, append it to the end of the list again, and make sure to +update the \f(CW\*(C`ev_timer\*(C'\fR if it was taken from the beginning of the list. +.Sp +This way, one can manage an unlimited number of timeouts in O(1) time for +starting, stopping and updating the timers, at the expense of a major +complication, and having to use a constant timeout. The constant timeout +ensures that the list stays sorted. +.PP +So which method the best? +.PP +Method #2 is a simple no-brain-required solution that is adequate in most +situations. Method #3 requires a bit more thinking, but handles many cases +better, and isn't very complicated either. In most case, choosing either +one is fine, with #3 being better in typical situations. +.PP +Method #1 is almost always a bad idea, and buys you nothing. Method #4 is +rather complicated, but extremely efficient, something that really pays +off after the first million or so of active timers, i.e. it's usually +overkill :) +.PP +\fIThe special problem of being too early\fR +.IX Subsection "The special problem of being too early" +.PP +If you ask a timer to call your callback after three seconds, then +you expect it to be invoked after three seconds \- but of course, this +cannot be guaranteed to infinite precision. Less obviously, it cannot be +guaranteed to any precision by libev \- imagine somebody suspending the +process with a \s-1STOP\s0 signal for a few hours for example. +.PP +So, libev tries to invoke your callback as soon as possible \fIafter\fR the +delay has occurred, but cannot guarantee this. +.PP +A less obvious failure mode is calling your callback too early: many event +loops compare timestamps with a \*(L"elapsed delay >= requested delay\*(R", but +this can cause your callback to be invoked much earlier than you would +expect. +.PP +To see why, imagine a system with a clock that only offers full second +resolution (think windows if you can't come up with a broken enough \s-1OS\s0 +yourself). If you schedule a one-second timer at the time 500.9, then the +event loop will schedule your timeout to elapse at a system time of 500 +(500.9 truncated to the resolution) + 1, or 501. +.PP +If an event library looks at the timeout 0.1s later, it will see \*(L"501 >= +501\*(R" and invoke the callback 0.1s after it was started, even though a +one-second delay was requested \- this is being \*(L"too early\*(R", despite best +intentions. +.PP +This is the reason why libev will never invoke the callback if the elapsed +delay equals the requested delay, but only when the elapsed delay is +larger than the requested delay. In the example above, libev would only invoke +the callback at system time 502, or 1.1s after the timer was started. +.PP +So, while libev cannot guarantee that your callback will be invoked +exactly when requested, it \fIcan\fR and \fIdoes\fR guarantee that the requested +delay has actually elapsed, or in other words, it always errs on the \*(L"too +late\*(R" side of things. +.PP +\fIThe special problem of time updates\fR +.IX Subsection "The special problem of time updates" +.PP +Establishing the current time is a costly operation (it usually takes +at least one system call): \s-1EV\s0 therefore updates its idea of the current +time only before and after \f(CW\*(C`ev_run\*(C'\fR collects new events, which causes a +growing difference between \f(CW\*(C`ev_now ()\*(C'\fR and \f(CW\*(C`ev_time ()\*(C'\fR when handling +lots of events in one iteration. +.PP +The relative timeouts are calculated relative to the \f(CW\*(C`ev_now ()\*(C'\fR +time. This is usually the right thing as this timestamp refers to the time +of the event triggering whatever timeout you are modifying/starting. If +you suspect event processing to be delayed and you \fIneed\fR to base the +timeout on the current time, use something like the following to adjust +for it: +.PP +.Vb 1 +\& ev_timer_set (&timer, after + (ev_time () \- ev_now ()), 0.); +.Ve +.PP +If the event loop is suspended for a long time, you can also force an +update of the time returned by \f(CW\*(C`ev_now ()\*(C'\fR by calling \f(CW\*(C`ev_now_update +()\*(C'\fR, although that will push the event time of all outstanding events +further into the future. +.PP +\fIThe special problem of unsynchronised clocks\fR +.IX Subsection "The special problem of unsynchronised clocks" +.PP +Modern systems have a variety of clocks \- libev itself uses the normal +\&\*(L"wall clock\*(R" clock and, if available, the monotonic clock (to avoid time +jumps). +.PP +Neither of these clocks is synchronised with each other or any other clock +on the system, so \f(CW\*(C`ev_time ()\*(C'\fR might return a considerably different time +than \f(CW\*(C`gettimeofday ()\*(C'\fR or \f(CW\*(C`time ()\*(C'\fR. On a GNU/Linux system, for example, +a call to \f(CW\*(C`gettimeofday\*(C'\fR might return a second count that is one higher +than a directly following call to \f(CW\*(C`time\*(C'\fR. +.PP +The moral of this is to only compare libev-related timestamps with +\&\f(CW\*(C`ev_time ()\*(C'\fR and \f(CW\*(C`ev_now ()\*(C'\fR, at least if you want better precision than +a second or so. +.PP +One more problem arises due to this lack of synchronisation: if libev uses +the system monotonic clock and you compare timestamps from \f(CW\*(C`ev_time\*(C'\fR +or \f(CW\*(C`ev_now\*(C'\fR from when you started your timer and when your callback is +invoked, you will find that sometimes the callback is a bit \*(L"early\*(R". +.PP +This is because \f(CW\*(C`ev_timer\*(C'\fRs work in real time, not wall clock time, so +libev makes sure your callback is not invoked before the delay happened, +\&\fImeasured according to the real time\fR, not the system clock. +.PP +If your timeouts are based on a physical timescale (e.g. \*(L"time out this +connection after 100 seconds\*(R") then this shouldn't bother you as it is +exactly the right behaviour. +.PP +If you want to compare wall clock/system timestamps to your timers, then +you need to use \f(CW\*(C`ev_periodic\*(C'\fRs, as these are based on the wall clock +time, where your comparisons will always generate correct results. +.PP +\fIThe special problems of suspended animation\fR +.IX Subsection "The special problems of suspended animation" +.PP +When you leave the server world it is quite customary to hit machines that +can suspend/hibernate \- what happens to the clocks during such a suspend? +.PP +Some quick tests made with a Linux 2.6.28 indicate that a suspend freezes +all processes, while the clocks (\f(CW\*(C`times\*(C'\fR, \f(CW\*(C`CLOCK_MONOTONIC\*(C'\fR) continue +to run until the system is suspended, but they will not advance while the +system is suspended. That means, on resume, it will be as if the program +was frozen for a few seconds, but the suspend time will not be counted +towards \f(CW\*(C`ev_timer\*(C'\fR when a monotonic clock source is used. The real time +clock advanced as expected, but if it is used as sole clocksource, then a +long suspend would be detected as a time jump by libev, and timers would +be adjusted accordingly. +.PP +I would not be surprised to see different behaviour in different between +operating systems, \s-1OS\s0 versions or even different hardware. +.PP +The other form of suspend (job control, or sending a \s-1SIGSTOP\s0) will see a +time jump in the monotonic clocks and the realtime clock. If the program +is suspended for a very long time, and monotonic clock sources are in use, +then you can expect \f(CW\*(C`ev_timer\*(C'\fRs to expire as the full suspension time +will be counted towards the timers. When no monotonic clock source is in +use, then libev will again assume a timejump and adjust accordingly. +.PP +It might be beneficial for this latter case to call \f(CW\*(C`ev_suspend\*(C'\fR +and \f(CW\*(C`ev_resume\*(C'\fR in code that handles \f(CW\*(C`SIGTSTP\*(C'\fR, to at least get +deterministic behaviour in this case (you can do nothing against +\&\f(CW\*(C`SIGSTOP\*(C'\fR). +.PP +\fIWatcher-Specific Functions and Data Members\fR +.IX Subsection "Watcher-Specific Functions and Data Members" +.IP "ev_timer_init (ev_timer *, callback, ev_tstamp after, ev_tstamp repeat)" 4 +.IX Item "ev_timer_init (ev_timer *, callback, ev_tstamp after, ev_tstamp repeat)" +.PD 0 +.IP "ev_timer_set (ev_timer *, ev_tstamp after, ev_tstamp repeat)" 4 +.IX Item "ev_timer_set (ev_timer *, ev_tstamp after, ev_tstamp repeat)" +.PD +Configure the timer to trigger after \f(CW\*(C`after\*(C'\fR seconds. If \f(CW\*(C`repeat\*(C'\fR +is \f(CW0.\fR, then it will automatically be stopped once the timeout is +reached. If it is positive, then the timer will automatically be +configured to trigger again \f(CW\*(C`repeat\*(C'\fR seconds later, again, and again, +until stopped manually. +.Sp +The timer itself will do a best-effort at avoiding drift, that is, if +you configure a timer to trigger every 10 seconds, then it will normally +trigger at exactly 10 second intervals. If, however, your program cannot +keep up with the timer (because it takes longer than those 10 seconds to +do stuff) the timer will not fire more than once per event loop iteration. +.IP "ev_timer_again (loop, ev_timer *)" 4 +.IX Item "ev_timer_again (loop, ev_timer *)" +This will act as if the timer timed out, and restarts it again if it is +repeating. It basically works like calling \f(CW\*(C`ev_timer_stop\*(C'\fR, updating the +timeout to the \f(CW\*(C`repeat\*(C'\fR value and calling \f(CW\*(C`ev_timer_start\*(C'\fR. +.Sp +The exact semantics are as in the following rules, all of which will be +applied to the watcher: +.RS 4 +.IP "If the timer is pending, the pending status is always cleared." 4 +.IX Item "If the timer is pending, the pending status is always cleared." +.PD 0 +.IP "If the timer is started but non-repeating, stop it (as if it timed out, without invoking it)." 4 +.IX Item "If the timer is started but non-repeating, stop it (as if it timed out, without invoking it)." +.ie n .IP "If the timer is repeating, make the ""repeat"" value the new timeout and start the timer, if necessary." 4 +.el .IP "If the timer is repeating, make the \f(CWrepeat\fR value the new timeout and start the timer, if necessary." 4 +.IX Item "If the timer is repeating, make the repeat value the new timeout and start the timer, if necessary." +.RE +.RS 4 +.PD +.Sp +This sounds a bit complicated, see \*(L"Be smart about timeouts\*(R", above, for a +usage example. +.RE +.IP "ev_tstamp ev_timer_remaining (loop, ev_timer *)" 4 +.IX Item "ev_tstamp ev_timer_remaining (loop, ev_timer *)" +Returns the remaining time until a timer fires. If the timer is active, +then this time is relative to the current event loop time, otherwise it's +the timeout value currently configured. +.Sp +That is, after an \f(CW\*(C`ev_timer_set (w, 5, 7)\*(C'\fR, \f(CW\*(C`ev_timer_remaining\*(C'\fR returns +\&\f(CW5\fR. When the timer is started and one second passes, \f(CW\*(C`ev_timer_remaining\*(C'\fR +will return \f(CW4\fR. When the timer expires and is restarted, it will return +roughly \f(CW7\fR (likely slightly less as callback invocation takes some time, +too), and so on. +.IP "ev_tstamp repeat [read\-write]" 4 +.IX Item "ev_tstamp repeat [read-write]" +The current \f(CW\*(C`repeat\*(C'\fR value. Will be used each time the watcher times out +or \f(CW\*(C`ev_timer_again\*(C'\fR is called, and determines the next timeout (if any), +which is also when any modifications are taken into account. +.PP +\fIExamples\fR +.IX Subsection "Examples" +.PP +Example: Create a timer that fires after 60 seconds. +.PP +.Vb 5 +\& static void +\& one_minute_cb (struct ev_loop *loop, ev_timer *w, int revents) +\& { +\& .. one minute over, w is actually stopped right here +\& } +\& +\& ev_timer mytimer; +\& ev_timer_init (&mytimer, one_minute_cb, 60., 0.); +\& ev_timer_start (loop, &mytimer); +.Ve +.PP +Example: Create a timeout timer that times out after 10 seconds of +inactivity. +.PP +.Vb 5 +\& static void +\& timeout_cb (struct ev_loop *loop, ev_timer *w, int revents) +\& { +\& .. ten seconds without any activity +\& } +\& +\& ev_timer mytimer; +\& ev_timer_init (&mytimer, timeout_cb, 0., 10.); /* note, only repeat used */ +\& ev_timer_again (&mytimer); /* start timer */ +\& ev_run (loop, 0); +\& +\& // and in some piece of code that gets executed on any "activity": +\& // reset the timeout to start ticking again at 10 seconds +\& ev_timer_again (&mytimer); +.Ve +.ie n .SS """ev_periodic"" \- to cron or not to cron?" +.el .SS "\f(CWev_periodic\fP \- to cron or not to cron?" +.IX Subsection "ev_periodic - to cron or not to cron?" +Periodic watchers are also timers of a kind, but they are very versatile +(and unfortunately a bit complex). +.PP +Unlike \f(CW\*(C`ev_timer\*(C'\fR, periodic watchers are not based on real time (or +relative time, the physical time that passes) but on wall clock time +(absolute time, the thing you can read on your calendar or clock). The +difference is that wall clock time can run faster or slower than real +time, and time jumps are not uncommon (e.g. when you adjust your +wrist-watch). +.PP +You can tell a periodic watcher to trigger after some specific point +in time: for example, if you tell a periodic watcher to trigger \*(L"in 10 +seconds\*(R" (by specifying e.g. \f(CW\*(C`ev_now () + 10.\*(C'\fR, that is, an absolute time +not a delay) and then reset your system clock to January of the previous +year, then it will take a year or more to trigger the event (unlike an +\&\f(CW\*(C`ev_timer\*(C'\fR, which would still trigger roughly 10 seconds after starting +it, as it uses a relative timeout). +.PP +\&\f(CW\*(C`ev_periodic\*(C'\fR watchers can also be used to implement vastly more complex +timers, such as triggering an event on each \*(L"midnight, local time\*(R", or +other complicated rules. This cannot be done with \f(CW\*(C`ev_timer\*(C'\fR watchers, as +those cannot react to time jumps. +.PP +As with timers, the callback is guaranteed to be invoked only when the +point in time where it is supposed to trigger has passed. If multiple +timers become ready during the same loop iteration then the ones with +earlier time-out values are invoked before ones with later time-out values +(but this is no longer true when a callback calls \f(CW\*(C`ev_run\*(C'\fR recursively). +.PP +\fIWatcher-Specific Functions and Data Members\fR +.IX Subsection "Watcher-Specific Functions and Data Members" +.IP "ev_periodic_init (ev_periodic *, callback, ev_tstamp offset, ev_tstamp interval, reschedule_cb)" 4 +.IX Item "ev_periodic_init (ev_periodic *, callback, ev_tstamp offset, ev_tstamp interval, reschedule_cb)" +.PD 0 +.IP "ev_periodic_set (ev_periodic *, ev_tstamp offset, ev_tstamp interval, reschedule_cb)" 4 +.IX Item "ev_periodic_set (ev_periodic *, ev_tstamp offset, ev_tstamp interval, reschedule_cb)" +.PD +Lots of arguments, let's sort it out... There are basically three modes of +operation, and we will explain them from simplest to most complex: +.RS 4 +.IP "\(bu" 4 +absolute timer (offset = absolute time, interval = 0, reschedule_cb = 0) +.Sp +In this configuration the watcher triggers an event after the wall clock +time \f(CW\*(C`offset\*(C'\fR has passed. It will not repeat and will not adjust when a +time jump occurs, that is, if it is to be run at January 1st 2011 then it +will be stopped and invoked when the system clock reaches or surpasses +this point in time. +.IP "\(bu" 4 +repeating interval timer (offset = offset within interval, interval > 0, reschedule_cb = 0) +.Sp +In this mode the watcher will always be scheduled to time out at the next +\&\f(CW\*(C`offset + N * interval\*(C'\fR time (for some integer N, which can also be +negative) and then repeat, regardless of any time jumps. The \f(CW\*(C`offset\*(C'\fR +argument is merely an offset into the \f(CW\*(C`interval\*(C'\fR periods. +.Sp +This can be used to create timers that do not drift with respect to the +system clock, for example, here is an \f(CW\*(C`ev_periodic\*(C'\fR that triggers each +hour, on the hour (with respect to \s-1UTC\s0): +.Sp +.Vb 1 +\& ev_periodic_set (&periodic, 0., 3600., 0); +.Ve +.Sp +This doesn't mean there will always be 3600 seconds in between triggers, +but only that the callback will be called when the system time shows a +full hour (\s-1UTC\s0), or more correctly, when the system time is evenly divisible +by 3600. +.Sp +Another way to think about it (for the mathematically inclined) is that +\&\f(CW\*(C`ev_periodic\*(C'\fR will try to run the callback in this mode at the next possible +time where \f(CW\*(C`time = offset (mod interval)\*(C'\fR, regardless of any time jumps. +.Sp +The \f(CW\*(C`interval\*(C'\fR \fI\s-1MUST\s0\fR be positive, and for numerical stability, the +interval value should be higher than \f(CW\*(C`1/8192\*(C'\fR (which is around 100 +microseconds) and \f(CW\*(C`offset\*(C'\fR should be higher than \f(CW0\fR and should have +at most a similar magnitude as the current time (say, within a factor of +ten). Typical values for offset are, in fact, \f(CW0\fR or something between +\&\f(CW0\fR and \f(CW\*(C`interval\*(C'\fR, which is also the recommended range. +.Sp +Note also that there is an upper limit to how often a timer can fire (\s-1CPU\s0 +speed for example), so if \f(CW\*(C`interval\*(C'\fR is very small then timing stability +will of course deteriorate. Libev itself tries to be exact to be about one +millisecond (if the \s-1OS\s0 supports it and the machine is fast enough). +.IP "\(bu" 4 +manual reschedule mode (offset ignored, interval ignored, reschedule_cb = callback) +.Sp +In this mode the values for \f(CW\*(C`interval\*(C'\fR and \f(CW\*(C`offset\*(C'\fR are both being +ignored. Instead, each time the periodic watcher gets scheduled, the +reschedule callback will be called with the watcher as first, and the +current time as second argument. +.Sp +\&\s-1NOTE: \s0\fIThis callback \s-1MUST NOT\s0 stop or destroy any periodic watcher, ever, +or make \s-1ANY\s0 other event loop modifications whatsoever, unless explicitly +allowed by documentation here\fR. +.Sp +If you need to stop it, return \f(CW\*(C`now + 1e30\*(C'\fR (or so, fudge fudge) and stop +it afterwards (e.g. by starting an \f(CW\*(C`ev_prepare\*(C'\fR watcher, which is the +only event loop modification you are allowed to do). +.Sp +The callback prototype is \f(CW\*(C`ev_tstamp (*reschedule_cb)(ev_periodic +*w, ev_tstamp now)\*(C'\fR, e.g.: +.Sp +.Vb 5 +\& static ev_tstamp +\& my_rescheduler (ev_periodic *w, ev_tstamp now) +\& { +\& return now + 60.; +\& } +.Ve +.Sp +It must return the next time to trigger, based on the passed time value +(that is, the lowest time value larger than to the second argument). It +will usually be called just before the callback will be triggered, but +might be called at other times, too. +.Sp +\&\s-1NOTE: \s0\fIThis callback must always return a time that is higher than or +equal to the passed \f(CI\*(C`now\*(C'\fI value\fR. +.Sp +This can be used to create very complex timers, such as a timer that +triggers on \*(L"next midnight, local time\*(R". To do this, you would calculate the +next midnight after \f(CW\*(C`now\*(C'\fR and return the timestamp value for this. How +you do this is, again, up to you (but it is not trivial, which is the main +reason I omitted it as an example). +.RE +.RS 4 +.RE +.IP "ev_periodic_again (loop, ev_periodic *)" 4 +.IX Item "ev_periodic_again (loop, ev_periodic *)" +Simply stops and restarts the periodic watcher again. This is only useful +when you changed some parameters or the reschedule callback would return +a different time than the last time it was called (e.g. in a crond like +program when the crontabs have changed). +.IP "ev_tstamp ev_periodic_at (ev_periodic *)" 4 +.IX Item "ev_tstamp ev_periodic_at (ev_periodic *)" +When active, returns the absolute time that the watcher is supposed +to trigger next. This is not the same as the \f(CW\*(C`offset\*(C'\fR argument to +\&\f(CW\*(C`ev_periodic_set\*(C'\fR, but indeed works even in interval and manual +rescheduling modes. +.IP "ev_tstamp offset [read\-write]" 4 +.IX Item "ev_tstamp offset [read-write]" +When repeating, this contains the offset value, otherwise this is the +absolute point in time (the \f(CW\*(C`offset\*(C'\fR value passed to \f(CW\*(C`ev_periodic_set\*(C'\fR, +although libev might modify this value for better numerical stability). +.Sp +Can be modified any time, but changes only take effect when the periodic +timer fires or \f(CW\*(C`ev_periodic_again\*(C'\fR is being called. +.IP "ev_tstamp interval [read\-write]" 4 +.IX Item "ev_tstamp interval [read-write]" +The current interval value. Can be modified any time, but changes only +take effect when the periodic timer fires or \f(CW\*(C`ev_periodic_again\*(C'\fR is being +called. +.IP "ev_tstamp (*reschedule_cb)(ev_periodic *w, ev_tstamp now) [read\-write]" 4 +.IX Item "ev_tstamp (*reschedule_cb)(ev_periodic *w, ev_tstamp now) [read-write]" +The current reschedule callback, or \f(CW0\fR, if this functionality is +switched off. Can be changed any time, but changes only take effect when +the periodic timer fires or \f(CW\*(C`ev_periodic_again\*(C'\fR is being called. +.PP +\fIExamples\fR +.IX Subsection "Examples" +.PP +Example: Call a callback every hour, or, more precisely, whenever the +system time is divisible by 3600. The callback invocation times have +potentially a lot of jitter, but good long-term stability. +.PP +.Vb 5 +\& static void +\& clock_cb (struct ev_loop *loop, ev_periodic *w, int revents) +\& { +\& ... its now a full hour (UTC, or TAI or whatever your clock follows) +\& } +\& +\& ev_periodic hourly_tick; +\& ev_periodic_init (&hourly_tick, clock_cb, 0., 3600., 0); +\& ev_periodic_start (loop, &hourly_tick); +.Ve +.PP +Example: The same as above, but use a reschedule callback to do it: +.PP +.Vb 1 +\& #include +\& +\& static ev_tstamp +\& my_scheduler_cb (ev_periodic *w, ev_tstamp now) +\& { +\& return now + (3600. \- fmod (now, 3600.)); +\& } +\& +\& ev_periodic_init (&hourly_tick, clock_cb, 0., 0., my_scheduler_cb); +.Ve +.PP +Example: Call a callback every hour, starting now: +.PP +.Vb 4 +\& ev_periodic hourly_tick; +\& ev_periodic_init (&hourly_tick, clock_cb, +\& fmod (ev_now (loop), 3600.), 3600., 0); +\& ev_periodic_start (loop, &hourly_tick); +.Ve +.ie n .SS """ev_signal"" \- signal me when a signal gets signalled!" +.el .SS "\f(CWev_signal\fP \- signal me when a signal gets signalled!" +.IX Subsection "ev_signal - signal me when a signal gets signalled!" +Signal watchers will trigger an event when the process receives a specific +signal one or more times. Even though signals are very asynchronous, libev +will try its best to deliver signals synchronously, i.e. as part of the +normal event processing, like any other event. +.PP +If you want signals to be delivered truly asynchronously, just use +\&\f(CW\*(C`sigaction\*(C'\fR as you would do without libev and forget about sharing +the signal. You can even use \f(CW\*(C`ev_async\*(C'\fR from a signal handler to +synchronously wake up an event loop. +.PP +You can configure as many watchers as you like for the same signal, but +only within the same loop, i.e. you can watch for \f(CW\*(C`SIGINT\*(C'\fR in your +default loop and for \f(CW\*(C`SIGIO\*(C'\fR in another loop, but you cannot watch for +\&\f(CW\*(C`SIGINT\*(C'\fR in both the default loop and another loop at the same time. At +the moment, \f(CW\*(C`SIGCHLD\*(C'\fR is permanently tied to the default loop. +.PP +Only after the first watcher for a signal is started will libev actually +register something with the kernel. It thus coexists with your own signal +handlers as long as you don't register any with libev for the same signal. +.PP +If possible and supported, libev will install its handlers with +\&\f(CW\*(C`SA_RESTART\*(C'\fR (or equivalent) behaviour enabled, so system calls should +not be unduly interrupted. If you have a problem with system calls getting +interrupted by signals you can block all signals in an \f(CW\*(C`ev_check\*(C'\fR watcher +and unblock them in an \f(CW\*(C`ev_prepare\*(C'\fR watcher. +.PP +\fIThe special problem of inheritance over fork/execve/pthread_create\fR +.IX Subsection "The special problem of inheritance over fork/execve/pthread_create" +.PP +Both the signal mask (\f(CW\*(C`sigprocmask\*(C'\fR) and the signal disposition +(\f(CW\*(C`sigaction\*(C'\fR) are unspecified after starting a signal watcher (and after +stopping it again), that is, libev might or might not block the signal, +and might or might not set or restore the installed signal handler (but +see \f(CW\*(C`EVFLAG_NOSIGMASK\*(C'\fR). +.PP +While this does not matter for the signal disposition (libev never +sets signals to \f(CW\*(C`SIG_IGN\*(C'\fR, so handlers will be reset to \f(CW\*(C`SIG_DFL\*(C'\fR on +\&\f(CW\*(C`execve\*(C'\fR), this matters for the signal mask: many programs do not expect +certain signals to be blocked. +.PP +This means that before calling \f(CW\*(C`exec\*(C'\fR (from the child) you should reset +the signal mask to whatever \*(L"default\*(R" you expect (all clear is a good +choice usually). +.PP +The simplest way to ensure that the signal mask is reset in the child is +to install a fork handler with \f(CW\*(C`pthread_atfork\*(C'\fR that resets it. That will +catch fork calls done by libraries (such as the libc) as well. +.PP +In current versions of libev, the signal will not be blocked indefinitely +unless you use the \f(CW\*(C`signalfd\*(C'\fR \s-1API \s0(\f(CW\*(C`EV_SIGNALFD\*(C'\fR). While this reduces +the window of opportunity for problems, it will not go away, as libev +\&\fIhas\fR to modify the signal mask, at least temporarily. +.PP +So I can't stress this enough: \fIIf you do not reset your signal mask when +you expect it to be empty, you have a race condition in your code\fR. This +is not a libev-specific thing, this is true for most event libraries. +.PP +\fIThe special problem of threads signal handling\fR +.IX Subsection "The special problem of threads signal handling" +.PP +\&\s-1POSIX\s0 threads has problematic signal handling semantics, specifically, +a lot of functionality (sigfd, sigwait etc.) only really works if all +threads in a process block signals, which is hard to achieve. +.PP +When you want to use sigwait (or mix libev signal handling with your own +for the same signals), you can tackle this problem by globally blocking +all signals before creating any threads (or creating them with a fully set +sigprocmask) and also specifying the \f(CW\*(C`EVFLAG_NOSIGMASK\*(C'\fR when creating +loops. Then designate one thread as \*(L"signal receiver thread\*(R" which handles +these signals. You can pass on any signals that libev might be interested +in by calling \f(CW\*(C`ev_feed_signal\*(C'\fR. +.PP +\fIWatcher-Specific Functions and Data Members\fR +.IX Subsection "Watcher-Specific Functions and Data Members" +.IP "ev_signal_init (ev_signal *, callback, int signum)" 4 +.IX Item "ev_signal_init (ev_signal *, callback, int signum)" +.PD 0 +.IP "ev_signal_set (ev_signal *, int signum)" 4 +.IX Item "ev_signal_set (ev_signal *, int signum)" +.PD +Configures the watcher to trigger on the given signal number (usually one +of the \f(CW\*(C`SIGxxx\*(C'\fR constants). +.IP "int signum [read\-only]" 4 +.IX Item "int signum [read-only]" +The signal the watcher watches out for. +.PP +\fIExamples\fR +.IX Subsection "Examples" +.PP +Example: Try to exit cleanly on \s-1SIGINT.\s0 +.PP +.Vb 5 +\& static void +\& sigint_cb (struct ev_loop *loop, ev_signal *w, int revents) +\& { +\& ev_break (loop, EVBREAK_ALL); +\& } +\& +\& ev_signal signal_watcher; +\& ev_signal_init (&signal_watcher, sigint_cb, SIGINT); +\& ev_signal_start (loop, &signal_watcher); +.Ve +.ie n .SS """ev_child"" \- watch out for process status changes" +.el .SS "\f(CWev_child\fP \- watch out for process status changes" +.IX Subsection "ev_child - watch out for process status changes" +Child watchers trigger when your process receives a \s-1SIGCHLD\s0 in response to +some child status changes (most typically when a child of yours dies or +exits). It is permissible to install a child watcher \fIafter\fR the child +has been forked (which implies it might have already exited), as long +as the event loop isn't entered (or is continued from a watcher), i.e., +forking and then immediately registering a watcher for the child is fine, +but forking and registering a watcher a few event loop iterations later or +in the next callback invocation is not. +.PP +Only the default event loop is capable of handling signals, and therefore +you can only register child watchers in the default event loop. +.PP +Due to some design glitches inside libev, child watchers will always be +handled at maximum priority (their priority is set to \f(CW\*(C`EV_MAXPRI\*(C'\fR by +libev) +.PP +\fIProcess Interaction\fR +.IX Subsection "Process Interaction" +.PP +Libev grabs \f(CW\*(C`SIGCHLD\*(C'\fR as soon as the default event loop is +initialised. This is necessary to guarantee proper behaviour even if the +first child watcher is started after the child exits. The occurrence +of \f(CW\*(C`SIGCHLD\*(C'\fR is recorded asynchronously, but child reaping is done +synchronously as part of the event loop processing. Libev always reaps all +children, even ones not watched. +.PP +\fIOverriding the Built-In Processing\fR +.IX Subsection "Overriding the Built-In Processing" +.PP +Libev offers no special support for overriding the built-in child +processing, but if your application collides with libev's default child +handler, you can override it easily by installing your own handler for +\&\f(CW\*(C`SIGCHLD\*(C'\fR after initialising the default loop, and making sure the +default loop never gets destroyed. You are encouraged, however, to use an +event-based approach to child reaping and thus use libev's support for +that, so other libev users can use \f(CW\*(C`ev_child\*(C'\fR watchers freely. +.PP +\fIStopping the Child Watcher\fR +.IX Subsection "Stopping the Child Watcher" +.PP +Currently, the child watcher never gets stopped, even when the +child terminates, so normally one needs to stop the watcher in the +callback. Future versions of libev might stop the watcher automatically +when a child exit is detected (calling \f(CW\*(C`ev_child_stop\*(C'\fR twice is not a +problem). +.PP +\fIWatcher-Specific Functions and Data Members\fR +.IX Subsection "Watcher-Specific Functions and Data Members" +.IP "ev_child_init (ev_child *, callback, int pid, int trace)" 4 +.IX Item "ev_child_init (ev_child *, callback, int pid, int trace)" +.PD 0 +.IP "ev_child_set (ev_child *, int pid, int trace)" 4 +.IX Item "ev_child_set (ev_child *, int pid, int trace)" +.PD +Configures the watcher to wait for status changes of process \f(CW\*(C`pid\*(C'\fR (or +\&\fIany\fR process if \f(CW\*(C`pid\*(C'\fR is specified as \f(CW0\fR). The callback can look +at the \f(CW\*(C`rstatus\*(C'\fR member of the \f(CW\*(C`ev_child\*(C'\fR watcher structure to see +the status word (use the macros from \f(CW\*(C`sys/wait.h\*(C'\fR and see your systems +\&\f(CW\*(C`waitpid\*(C'\fR documentation). The \f(CW\*(C`rpid\*(C'\fR member contains the pid of the +process causing the status change. \f(CW\*(C`trace\*(C'\fR must be either \f(CW0\fR (only +activate the watcher when the process terminates) or \f(CW1\fR (additionally +activate the watcher when the process is stopped or continued). +.IP "int pid [read\-only]" 4 +.IX Item "int pid [read-only]" +The process id this watcher watches out for, or \f(CW0\fR, meaning any process id. +.IP "int rpid [read\-write]" 4 +.IX Item "int rpid [read-write]" +The process id that detected a status change. +.IP "int rstatus [read\-write]" 4 +.IX Item "int rstatus [read-write]" +The process exit/trace status caused by \f(CW\*(C`rpid\*(C'\fR (see your systems +\&\f(CW\*(C`waitpid\*(C'\fR and \f(CW\*(C`sys/wait.h\*(C'\fR documentation for details). +.PP +\fIExamples\fR +.IX Subsection "Examples" +.PP +Example: \f(CW\*(C`fork()\*(C'\fR a new process and install a child handler to wait for +its completion. +.PP +.Vb 1 +\& ev_child cw; +\& +\& static void +\& child_cb (EV_P_ ev_child *w, int revents) +\& { +\& ev_child_stop (EV_A_ w); +\& printf ("process %d exited with status %x\en", w\->rpid, w\->rstatus); +\& } +\& +\& pid_t pid = fork (); +\& +\& if (pid < 0) +\& // error +\& else if (pid == 0) +\& { +\& // the forked child executes here +\& exit (1); +\& } +\& else +\& { +\& ev_child_init (&cw, child_cb, pid, 0); +\& ev_child_start (EV_DEFAULT_ &cw); +\& } +.Ve +.ie n .SS """ev_stat"" \- did the file attributes just change?" +.el .SS "\f(CWev_stat\fP \- did the file attributes just change?" +.IX Subsection "ev_stat - did the file attributes just change?" +This watches a file system path for attribute changes. That is, it calls +\&\f(CW\*(C`stat\*(C'\fR on that path in regular intervals (or when the \s-1OS\s0 says it changed) +and sees if it changed compared to the last time, invoking the callback +if it did. Starting the watcher \f(CW\*(C`stat\*(C'\fR's the file, so only changes that +happen after the watcher has been started will be reported. +.PP +The path does not need to exist: changing from \*(L"path exists\*(R" to \*(L"path does +not exist\*(R" is a status change like any other. The condition \*(L"path does not +exist\*(R" (or more correctly \*(L"path cannot be stat'ed\*(R") is signified by the +\&\f(CW\*(C`st_nlink\*(C'\fR field being zero (which is otherwise always forced to be at +least one) and all the other fields of the stat buffer having unspecified +contents. +.PP +The path \fImust not\fR end in a slash or contain special components such as +\&\f(CW\*(C`.\*(C'\fR or \f(CW\*(C`..\*(C'\fR. The path \fIshould\fR be absolute: If it is relative and +your working directory changes, then the behaviour is undefined. +.PP +Since there is no portable change notification interface available, the +portable implementation simply calls \f(CWstat(2)\fR regularly on the path +to see if it changed somehow. You can specify a recommended polling +interval for this case. If you specify a polling interval of \f(CW0\fR (highly +recommended!) then a \fIsuitable, unspecified default\fR value will be used +(which you can expect to be around five seconds, although this might +change dynamically). Libev will also impose a minimum interval which is +currently around \f(CW0.1\fR, but that's usually overkill. +.PP +This watcher type is not meant for massive numbers of stat watchers, +as even with OS-supported change notifications, this can be +resource-intensive. +.PP +At the time of this writing, the only OS-specific interface implemented +is the Linux inotify interface (implementing kqueue support is left as an +exercise for the reader. Note, however, that the author sees no way of +implementing \f(CW\*(C`ev_stat\*(C'\fR semantics with kqueue, except as a hint). +.PP +\fI\s-1ABI\s0 Issues (Largefile Support)\fR +.IX Subsection "ABI Issues (Largefile Support)" +.PP +Libev by default (unless the user overrides this) uses the default +compilation environment, which means that on systems with large file +support disabled by default, you get the 32 bit version of the stat +structure. When using the library from programs that change the \s-1ABI\s0 to +use 64 bit file offsets the programs will fail. In that case you have to +compile libev with the same flags to get binary compatibility. This is +obviously the case with any flags that change the \s-1ABI,\s0 but the problem is +most noticeably displayed with ev_stat and large file support. +.PP +The solution for this is to lobby your distribution maker to make large +file interfaces available by default (as e.g. FreeBSD does) and not +optional. Libev cannot simply switch on large file support because it has +to exchange stat structures with application programs compiled using the +default compilation environment. +.PP +\fIInotify and Kqueue\fR +.IX Subsection "Inotify and Kqueue" +.PP +When \f(CW\*(C`inotify (7)\*(C'\fR support has been compiled into libev and present at +runtime, it will be used to speed up change detection where possible. The +inotify descriptor will be created lazily when the first \f(CW\*(C`ev_stat\*(C'\fR +watcher is being started. +.PP +Inotify presence does not change the semantics of \f(CW\*(C`ev_stat\*(C'\fR watchers +except that changes might be detected earlier, and in some cases, to avoid +making regular \f(CW\*(C`stat\*(C'\fR calls. Even in the presence of inotify support +there are many cases where libev has to resort to regular \f(CW\*(C`stat\*(C'\fR polling, +but as long as kernel 2.6.25 or newer is used (2.6.24 and older have too +many bugs), the path exists (i.e. stat succeeds), and the path resides on +a local filesystem (libev currently assumes only ext2/3, jfs, reiserfs and +xfs are fully working) libev usually gets away without polling. +.PP +There is no support for kqueue, as apparently it cannot be used to +implement this functionality, due to the requirement of having a file +descriptor open on the object at all times, and detecting renames, unlinks +etc. is difficult. +.PP +\fI\f(CI\*(C`stat ()\*(C'\fI is a synchronous operation\fR +.IX Subsection "stat () is a synchronous operation" +.PP +Libev doesn't normally do any kind of I/O itself, and so is not blocking +the process. The exception are \f(CW\*(C`ev_stat\*(C'\fR watchers \- those call \f(CW\*(C`stat +()\*(C'\fR, which is a synchronous operation. +.PP +For local paths, this usually doesn't matter: unless the system is very +busy or the intervals between stat's are large, a stat call will be fast, +as the path data is usually in memory already (except when starting the +watcher). +.PP +For networked file systems, calling \f(CW\*(C`stat ()\*(C'\fR can block an indefinite +time due to network issues, and even under good conditions, a stat call +often takes multiple milliseconds. +.PP +Therefore, it is best to avoid using \f(CW\*(C`ev_stat\*(C'\fR watchers on networked +paths, although this is fully supported by libev. +.PP +\fIThe special problem of stat time resolution\fR +.IX Subsection "The special problem of stat time resolution" +.PP +The \f(CW\*(C`stat ()\*(C'\fR system call only supports full-second resolution portably, +and even on systems where the resolution is higher, most file systems +still only support whole seconds. +.PP +That means that, if the time is the only thing that changes, you can +easily miss updates: on the first update, \f(CW\*(C`ev_stat\*(C'\fR detects a change and +calls your callback, which does something. When there is another update +within the same second, \f(CW\*(C`ev_stat\*(C'\fR will be unable to detect unless the +stat data does change in other ways (e.g. file size). +.PP +The solution to this is to delay acting on a change for slightly more +than a second (or till slightly after the next full second boundary), using +a roughly one-second-delay \f(CW\*(C`ev_timer\*(C'\fR (e.g. \f(CW\*(C`ev_timer_set (w, 0., 1.02); +ev_timer_again (loop, w)\*(C'\fR). +.PP +The \f(CW.02\fR offset is added to work around small timing inconsistencies +of some operating systems (where the second counter of the current time +might be be delayed. One such system is the Linux kernel, where a call to +\&\f(CW\*(C`gettimeofday\*(C'\fR might return a timestamp with a full second later than +a subsequent \f(CW\*(C`time\*(C'\fR call \- if the equivalent of \f(CW\*(C`time ()\*(C'\fR is used to +update file times then there will be a small window where the kernel uses +the previous second to update file times but libev might already execute +the timer callback). +.PP +\fIWatcher-Specific Functions and Data Members\fR +.IX Subsection "Watcher-Specific Functions and Data Members" +.IP "ev_stat_init (ev_stat *, callback, const char *path, ev_tstamp interval)" 4 +.IX Item "ev_stat_init (ev_stat *, callback, const char *path, ev_tstamp interval)" +.PD 0 +.IP "ev_stat_set (ev_stat *, const char *path, ev_tstamp interval)" 4 +.IX Item "ev_stat_set (ev_stat *, const char *path, ev_tstamp interval)" +.PD +Configures the watcher to wait for status changes of the given +\&\f(CW\*(C`path\*(C'\fR. The \f(CW\*(C`interval\*(C'\fR is a hint on how quickly a change is expected to +be detected and should normally be specified as \f(CW0\fR to let libev choose +a suitable value. The memory pointed to by \f(CW\*(C`path\*(C'\fR must point to the same +path for as long as the watcher is active. +.Sp +The callback will receive an \f(CW\*(C`EV_STAT\*(C'\fR event when a change was detected, +relative to the attributes at the time the watcher was started (or the +last change was detected). +.IP "ev_stat_stat (loop, ev_stat *)" 4 +.IX Item "ev_stat_stat (loop, ev_stat *)" +Updates the stat buffer immediately with new values. If you change the +watched path in your callback, you could call this function to avoid +detecting this change (while introducing a race condition if you are not +the only one changing the path). Can also be useful simply to find out the +new values. +.IP "ev_statdata attr [read\-only]" 4 +.IX Item "ev_statdata attr [read-only]" +The most-recently detected attributes of the file. Although the type is +\&\f(CW\*(C`ev_statdata\*(C'\fR, this is usually the (or one of the) \f(CW\*(C`struct stat\*(C'\fR types +suitable for your system, but you can only rely on the POSIX-standardised +members to be present. If the \f(CW\*(C`st_nlink\*(C'\fR member is \f(CW0\fR, then there was +some error while \f(CW\*(C`stat\*(C'\fRing the file. +.IP "ev_statdata prev [read\-only]" 4 +.IX Item "ev_statdata prev [read-only]" +The previous attributes of the file. The callback gets invoked whenever +\&\f(CW\*(C`prev\*(C'\fR != \f(CW\*(C`attr\*(C'\fR, or, more precisely, one or more of these members +differ: \f(CW\*(C`st_dev\*(C'\fR, \f(CW\*(C`st_ino\*(C'\fR, \f(CW\*(C`st_mode\*(C'\fR, \f(CW\*(C`st_nlink\*(C'\fR, \f(CW\*(C`st_uid\*(C'\fR, +\&\f(CW\*(C`st_gid\*(C'\fR, \f(CW\*(C`st_rdev\*(C'\fR, \f(CW\*(C`st_size\*(C'\fR, \f(CW\*(C`st_atime\*(C'\fR, \f(CW\*(C`st_mtime\*(C'\fR, \f(CW\*(C`st_ctime\*(C'\fR. +.IP "ev_tstamp interval [read\-only]" 4 +.IX Item "ev_tstamp interval [read-only]" +The specified interval. +.IP "const char *path [read\-only]" 4 +.IX Item "const char *path [read-only]" +The file system path that is being watched. +.PP +\fIExamples\fR +.IX Subsection "Examples" +.PP +Example: Watch \f(CW\*(C`/etc/passwd\*(C'\fR for attribute changes. +.PP +.Vb 10 +\& static void +\& passwd_cb (struct ev_loop *loop, ev_stat *w, int revents) +\& { +\& /* /etc/passwd changed in some way */ +\& if (w\->attr.st_nlink) +\& { +\& printf ("passwd current size %ld\en", (long)w\->attr.st_size); +\& printf ("passwd current atime %ld\en", (long)w\->attr.st_mtime); +\& printf ("passwd current mtime %ld\en", (long)w\->attr.st_mtime); +\& } +\& else +\& /* you shalt not abuse printf for puts */ +\& puts ("wow, /etc/passwd is not there, expect problems. " +\& "if this is windows, they already arrived\en"); +\& } +\& +\& ... +\& ev_stat passwd; +\& +\& ev_stat_init (&passwd, passwd_cb, "/etc/passwd", 0.); +\& ev_stat_start (loop, &passwd); +.Ve +.PP +Example: Like above, but additionally use a one-second delay so we do not +miss updates (however, frequent updates will delay processing, too, so +one might do the work both on \f(CW\*(C`ev_stat\*(C'\fR callback invocation \fIand\fR on +\&\f(CW\*(C`ev_timer\*(C'\fR callback invocation). +.PP +.Vb 2 +\& static ev_stat passwd; +\& static ev_timer timer; +\& +\& static void +\& timer_cb (EV_P_ ev_timer *w, int revents) +\& { +\& ev_timer_stop (EV_A_ w); +\& +\& /* now it\*(Aqs one second after the most recent passwd change */ +\& } +\& +\& static void +\& stat_cb (EV_P_ ev_stat *w, int revents) +\& { +\& /* reset the one\-second timer */ +\& ev_timer_again (EV_A_ &timer); +\& } +\& +\& ... +\& ev_stat_init (&passwd, stat_cb, "/etc/passwd", 0.); +\& ev_stat_start (loop, &passwd); +\& ev_timer_init (&timer, timer_cb, 0., 1.02); +.Ve +.ie n .SS """ev_idle"" \- when you've got nothing better to do..." +.el .SS "\f(CWev_idle\fP \- when you've got nothing better to do..." +.IX Subsection "ev_idle - when you've got nothing better to do..." +Idle watchers trigger events when no other events of the same or higher +priority are pending (prepare, check and other idle watchers do not count +as receiving \*(L"events\*(R"). +.PP +That is, as long as your process is busy handling sockets or timeouts +(or even signals, imagine) of the same or higher priority it will not be +triggered. But when your process is idle (or only lower-priority watchers +are pending), the idle watchers are being called once per event loop +iteration \- until stopped, that is, or your process receives more events +and becomes busy again with higher priority stuff. +.PP +The most noteworthy effect is that as long as any idle watchers are +active, the process will not block when waiting for new events. +.PP +Apart from keeping your process non-blocking (which is a useful +effect on its own sometimes), idle watchers are a good place to do +\&\*(L"pseudo-background processing\*(R", or delay processing stuff to after the +event loop has handled all outstanding events. +.PP +\fIAbusing an \f(CI\*(C`ev_idle\*(C'\fI watcher for its side-effect\fR +.IX Subsection "Abusing an ev_idle watcher for its side-effect" +.PP +As long as there is at least one active idle watcher, libev will never +sleep unnecessarily. Or in other words, it will loop as fast as possible. +For this to work, the idle watcher doesn't need to be invoked at all \- the +lowest priority will do. +.PP +This mode of operation can be useful together with an \f(CW\*(C`ev_check\*(C'\fR watcher, +to do something on each event loop iteration \- for example to balance load +between different connections. +.PP +See \*(L"Abusing an ev_check watcher for its side-effect\*(R" for a longer +example. +.PP +\fIWatcher-Specific Functions and Data Members\fR +.IX Subsection "Watcher-Specific Functions and Data Members" +.IP "ev_idle_init (ev_idle *, callback)" 4 +.IX Item "ev_idle_init (ev_idle *, callback)" +Initialises and configures the idle watcher \- it has no parameters of any +kind. There is a \f(CW\*(C`ev_idle_set\*(C'\fR macro, but using it is utterly pointless, +believe me. +.PP +\fIExamples\fR +.IX Subsection "Examples" +.PP +Example: Dynamically allocate an \f(CW\*(C`ev_idle\*(C'\fR watcher, start it, and in the +callback, free it. Also, use no error checking, as usual. +.PP +.Vb 5 +\& static void +\& idle_cb (struct ev_loop *loop, ev_idle *w, int revents) +\& { +\& // stop the watcher +\& ev_idle_stop (loop, w); +\& +\& // now we can free it +\& free (w); +\& +\& // now do something you wanted to do when the program has +\& // no longer anything immediate to do. +\& } +\& +\& ev_idle *idle_watcher = malloc (sizeof (ev_idle)); +\& ev_idle_init (idle_watcher, idle_cb); +\& ev_idle_start (loop, idle_watcher); +.Ve +.ie n .SS """ev_prepare"" and ""ev_check"" \- customise your event loop!" +.el .SS "\f(CWev_prepare\fP and \f(CWev_check\fP \- customise your event loop!" +.IX Subsection "ev_prepare and ev_check - customise your event loop!" +Prepare and check watchers are often (but not always) used in pairs: +prepare watchers get invoked before the process blocks and check watchers +afterwards. +.PP +You \fImust not\fR call \f(CW\*(C`ev_run\*(C'\fR (or similar functions that enter the +current event loop) or \f(CW\*(C`ev_loop_fork\*(C'\fR from either \f(CW\*(C`ev_prepare\*(C'\fR or +\&\f(CW\*(C`ev_check\*(C'\fR watchers. Other loops than the current one are fine, +however. The rationale behind this is that you do not need to check +for recursion in those watchers, i.e. the sequence will always be +\&\f(CW\*(C`ev_prepare\*(C'\fR, blocking, \f(CW\*(C`ev_check\*(C'\fR so if you have one watcher of each +kind they will always be called in pairs bracketing the blocking call. +.PP +Their main purpose is to integrate other event mechanisms into libev and +their use is somewhat advanced. They could be used, for example, to track +variable changes, implement your own watchers, integrate net-snmp or a +coroutine library and lots more. They are also occasionally useful if +you cache some data and want to flush it before blocking (for example, +in X programs you might want to do an \f(CW\*(C`XFlush ()\*(C'\fR in an \f(CW\*(C`ev_prepare\*(C'\fR +watcher). +.PP +This is done by examining in each prepare call which file descriptors +need to be watched by the other library, registering \f(CW\*(C`ev_io\*(C'\fR watchers +for them and starting an \f(CW\*(C`ev_timer\*(C'\fR watcher for any timeouts (many +libraries provide exactly this functionality). Then, in the check watcher, +you check for any events that occurred (by checking the pending status +of all watchers and stopping them) and call back into the library. The +I/O and timer callbacks will never actually be called (but must be valid +nevertheless, because you never know, you know?). +.PP +As another example, the Perl Coro module uses these hooks to integrate +coroutines into libev programs, by yielding to other active coroutines +during each prepare and only letting the process block if no coroutines +are ready to run (it's actually more complicated: it only runs coroutines +with priority higher than or equal to the event loop and one coroutine +of lower priority, but only once, using idle watchers to keep the event +loop from blocking if lower-priority coroutines are active, thus mapping +low-priority coroutines to idle/background tasks). +.PP +When used for this purpose, it is recommended to give \f(CW\*(C`ev_check\*(C'\fR watchers +highest (\f(CW\*(C`EV_MAXPRI\*(C'\fR) priority, to ensure that they are being run before +any other watchers after the poll (this doesn't matter for \f(CW\*(C`ev_prepare\*(C'\fR +watchers). +.PP +Also, \f(CW\*(C`ev_check\*(C'\fR watchers (and \f(CW\*(C`ev_prepare\*(C'\fR watchers, too) should not +activate (\*(L"feed\*(R") events into libev. While libev fully supports this, they +might get executed before other \f(CW\*(C`ev_check\*(C'\fR watchers did their job. As +\&\f(CW\*(C`ev_check\*(C'\fR watchers are often used to embed other (non-libev) event +loops those other event loops might be in an unusable state until their +\&\f(CW\*(C`ev_check\*(C'\fR watcher ran (always remind yourself to coexist peacefully with +others). +.PP +\fIAbusing an \f(CI\*(C`ev_check\*(C'\fI watcher for its side-effect\fR +.IX Subsection "Abusing an ev_check watcher for its side-effect" +.PP +\&\f(CW\*(C`ev_check\*(C'\fR (and less often also \f(CW\*(C`ev_prepare\*(C'\fR) watchers can also be +useful because they are called once per event loop iteration. For +example, if you want to handle a large number of connections fairly, you +normally only do a bit of work for each active connection, and if there +is more work to do, you wait for the next event loop iteration, so other +connections have a chance of making progress. +.PP +Using an \f(CW\*(C`ev_check\*(C'\fR watcher is almost enough: it will be called on the +next event loop iteration. However, that isn't as soon as possible \- +without external events, your \f(CW\*(C`ev_check\*(C'\fR watcher will not be invoked. +.PP +This is where \f(CW\*(C`ev_idle\*(C'\fR watchers come in handy \- all you need is a +single global idle watcher that is active as long as you have one active +\&\f(CW\*(C`ev_check\*(C'\fR watcher. The \f(CW\*(C`ev_idle\*(C'\fR watcher makes sure the event loop +will not sleep, and the \f(CW\*(C`ev_check\*(C'\fR watcher makes sure a callback gets +invoked. Neither watcher alone can do that. +.PP +\fIWatcher-Specific Functions and Data Members\fR +.IX Subsection "Watcher-Specific Functions and Data Members" +.IP "ev_prepare_init (ev_prepare *, callback)" 4 +.IX Item "ev_prepare_init (ev_prepare *, callback)" +.PD 0 +.IP "ev_check_init (ev_check *, callback)" 4 +.IX Item "ev_check_init (ev_check *, callback)" +.PD +Initialises and configures the prepare or check watcher \- they have no +parameters of any kind. There are \f(CW\*(C`ev_prepare_set\*(C'\fR and \f(CW\*(C`ev_check_set\*(C'\fR +macros, but using them is utterly, utterly, utterly and completely +pointless. +.PP +\fIExamples\fR +.IX Subsection "Examples" +.PP +There are a number of principal ways to embed other event loops or modules +into libev. Here are some ideas on how to include libadns into libev +(there is a Perl module named \f(CW\*(C`EV::ADNS\*(C'\fR that does this, which you could +use as a working example. Another Perl module named \f(CW\*(C`EV::Glib\*(C'\fR embeds a +Glib main context into libev, and finally, \f(CW\*(C`Glib::EV\*(C'\fR embeds \s-1EV\s0 into the +Glib event loop). +.PP +Method 1: Add \s-1IO\s0 watchers and a timeout watcher in a prepare handler, +and in a check watcher, destroy them and call into libadns. What follows +is pseudo-code only of course. This requires you to either use a low +priority for the check watcher or use \f(CW\*(C`ev_clear_pending\*(C'\fR explicitly, as +the callbacks for the IO/timeout watchers might not have been called yet. +.PP +.Vb 2 +\& static ev_io iow [nfd]; +\& static ev_timer tw; +\& +\& static void +\& io_cb (struct ev_loop *loop, ev_io *w, int revents) +\& { +\& } +\& +\& // create io watchers for each fd and a timer before blocking +\& static void +\& adns_prepare_cb (struct ev_loop *loop, ev_prepare *w, int revents) +\& { +\& int timeout = 3600000; +\& struct pollfd fds [nfd]; +\& // actual code will need to loop here and realloc etc. +\& adns_beforepoll (ads, fds, &nfd, &timeout, timeval_from (ev_time ())); +\& +\& /* the callback is illegal, but won\*(Aqt be called as we stop during check */ +\& ev_timer_init (&tw, 0, timeout * 1e\-3, 0.); +\& ev_timer_start (loop, &tw); +\& +\& // create one ev_io per pollfd +\& for (int i = 0; i < nfd; ++i) +\& { +\& ev_io_init (iow + i, io_cb, fds [i].fd, +\& ((fds [i].events & POLLIN ? EV_READ : 0) +\& | (fds [i].events & POLLOUT ? EV_WRITE : 0))); +\& +\& fds [i].revents = 0; +\& ev_io_start (loop, iow + i); +\& } +\& } +\& +\& // stop all watchers after blocking +\& static void +\& adns_check_cb (struct ev_loop *loop, ev_check *w, int revents) +\& { +\& ev_timer_stop (loop, &tw); +\& +\& for (int i = 0; i < nfd; ++i) +\& { +\& // set the relevant poll flags +\& // could also call adns_processreadable etc. here +\& struct pollfd *fd = fds + i; +\& int revents = ev_clear_pending (iow + i); +\& if (revents & EV_READ ) fd\->revents |= fd\->events & POLLIN; +\& if (revents & EV_WRITE) fd\->revents |= fd\->events & POLLOUT; +\& +\& // now stop the watcher +\& ev_io_stop (loop, iow + i); +\& } +\& +\& adns_afterpoll (adns, fds, nfd, timeval_from (ev_now (loop)); +\& } +.Ve +.PP +Method 2: This would be just like method 1, but you run \f(CW\*(C`adns_afterpoll\*(C'\fR +in the prepare watcher and would dispose of the check watcher. +.PP +Method 3: If the module to be embedded supports explicit event +notification (libadns does), you can also make use of the actual watcher +callbacks, and only destroy/create the watchers in the prepare watcher. +.PP +.Vb 5 +\& static void +\& 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_run (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 .SS """ev_embed"" \- when one backend isn't enough..." +.el .SS "\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 (the callback doesn't need to invoke the +\&\f(CW\*(C`ev_embed_sweep\*(C'\fR function directly, it could also start an idle watcher +to give the embedded loop strictly lower priority for example). +.PP +You can also set the callback to \f(CW0\fR, in which case the embed watcher +will automatically execute the embedded loop sweep whenever necessary. +.PP +Fork detection will be handled transparently while the \f(CW\*(C`ev_embed\*(C'\fR watcher +is active, i.e., the embedded loop will automatically be forked when the +embedding loop forks. In other cases, the user is responsible for calling +\&\f(CW\*(C`ev_loop_fork\*(C'\fR on the embedded loop. +.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 *, struct ev_loop *embedded_loop)" 4 +.IX Item "ev_embed_set (ev_embed *, 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_run (embedded_loop, EVRUN_NOWAIT)\*(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 .SS """ev_fork"" \- the audacity to resume the event loop after a fork" +.el .SS "\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_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 +\fIThe special problem of life after fork \- how is it possible?\fR +.IX Subsection "The special problem of life after fork - how is it possible?" +.PP +Most uses of \f(CW\*(C`fork ()\*(C'\fR consist of forking, then some simple calls to set +up/change the process environment, followed by a call to \f(CW\*(C`exec()\*(C'\fR. This +sequence should be handled by libev without any problems. +.PP +This changes when the application actually wants to do event handling +in the child, or both parent in child, in effect \*(L"continuing\*(R" after the +fork. +.PP +The default mode of operation (for libev, with application help to detect +forks) is to duplicate all the state in the child, as would be expected +when \fIeither\fR the parent \fIor\fR the child process continues. +.PP +When both processes want to continue using libev, then this is usually the +wrong result. In that case, usually one process (typically the parent) is +supposed to continue with all watchers in place as before, while the other +process typically wants to start fresh, i.e. without any active watchers. +.PP +The cleanest and most efficient way to achieve that with libev is to +simply create a new event loop, which of course will be \*(L"empty\*(R", and +use that for new watchers. This has the advantage of not touching more +memory than necessary, and thus avoiding the copy-on-write, and the +disadvantage of having to use multiple event loops (which do not support +signal watchers). +.PP +When this is not possible, or you want to use the default loop for +other reasons, then in the process that wants to start \*(L"fresh\*(R", call +\&\f(CW\*(C`ev_loop_destroy (EV_DEFAULT)\*(C'\fR followed by \f(CW\*(C`ev_default_loop (...)\*(C'\fR. +Destroying the default loop will \*(L"orphan\*(R" (not stop) all registered +watchers, so you have to be careful not to execute code that modifies +those watchers. Note also that in that case, you have to re-register any +signal watchers. +.PP +\fIWatcher-Specific Functions and Data Members\fR +.IX Subsection "Watcher-Specific Functions and Data Members" +.IP "ev_fork_init (ev_fork *, callback)" 4 +.IX Item "ev_fork_init (ev_fork *, 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, +really. +.ie n .SS """ev_cleanup"" \- even the best things end" +.el .SS "\f(CWev_cleanup\fP \- even the best things end" +.IX Subsection "ev_cleanup - even the best things end" +Cleanup watchers are called just before the event loop is being destroyed +by a call to \f(CW\*(C`ev_loop_destroy\*(C'\fR. +.PP +While there is no guarantee that the event loop gets destroyed, cleanup +watchers provide a convenient method to install cleanup hooks for your +program, worker threads and so on \- you just to make sure to destroy the +loop when you want them to be invoked. +.PP +Cleanup watchers are invoked in the same way as any other watcher. Unlike +all other watchers, they do not keep a reference to the event loop (which +makes a lot of sense if you think about it). Like all other watchers, you +can call libev functions in the callback, except \f(CW\*(C`ev_cleanup_start\*(C'\fR. +.PP +\fIWatcher-Specific Functions and Data Members\fR +.IX Subsection "Watcher-Specific Functions and Data Members" +.IP "ev_cleanup_init (ev_cleanup *, callback)" 4 +.IX Item "ev_cleanup_init (ev_cleanup *, callback)" +Initialises and configures the cleanup watcher \- it has no parameters of +any kind. There is a \f(CW\*(C`ev_cleanup_set\*(C'\fR macro, but using it is utterly +pointless, I assure you. +.PP +Example: Register an atexit handler to destroy the default loop, so any +cleanup functions are called. +.PP +.Vb 5 +\& static void +\& program_exits (void) +\& { +\& ev_loop_destroy (EV_DEFAULT_UC); +\& } +\& +\& ... +\& atexit (program_exits); +.Ve +.ie n .SS """ev_async"" \- how to wake up an event loop" +.el .SS "\f(CWev_async\fP \- how to wake up an event loop" +.IX Subsection "ev_async - how to wake up an 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 an 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_send\*(C'\fR calls). In fact, you could use signal watchers as a kind +of \*(L"global async watchers\*(R" by using a watcher on an otherwise unused +signal, and \f(CW\*(C`ev_feed_signal\*(C'\fR to signal this watcher from another thread, +even without knowing which loop owns the signal. +.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 or unportable memory access +semantics. +.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, and instantly +returns. +.Sp +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 +Note that, as with other watchers in libev, multiple events might get +compressed into a single callback invocation (another way to look at +this is that \f(CW\*(C`ev_async\*(C'\fR watchers are level-triggered: they are set on +\&\f(CW\*(C`ev_async_send\*(C'\fR, reset when the event loop detects that). +.Sp +This call incurs the overhead of at most one extra system call per event +loop iteration, if the event loop is blocked, and no syscall at all if +the event loop (or your program) is processing events. That means that +repeated calls are basically free (there is no need to avoid calls for +performance reasons) and that the overhead becomes smaller (typically +zero) under load. +.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: there +is a time window between the event loop checking and resetting the async +notification, and the callback being invoked. +.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 is +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_TIMER\*(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_TIMER) +\& /* doh, nothing entered */; +\& } +\& +\& ev_once (STDIN_FILENO, EV_READ, 10., stdin_ready, 0); +.Ve +.IP "ev_feed_fd_event (loop, int fd, int revents)" 4 +.IX Item "ev_feed_fd_event (loop, int fd, int revents)" +Feed an event on the given fd, as if a file descriptor backend detected +the given events. +.IP "ev_feed_signal_event (loop, int signum)" 4 +.IX Item "ev_feed_signal_event (loop, int signum)" +Feed an event as if the given signal occurred. See also \f(CW\*(C`ev_feed_signal\*(C'\fR, +which is async-safe. +.SH "COMMON OR USEFUL IDIOMS (OR BOTH)" +.IX Header "COMMON OR USEFUL IDIOMS (OR BOTH)" +This section explains some common idioms that are not immediately +obvious. Note that examples are sprinkled over the whole manual, and this +section only contains stuff that wouldn't fit anywhere else. +.SS "\s-1ASSOCIATING CUSTOM DATA WITH A WATCHER\s0" +.IX Subsection "ASSOCIATING CUSTOM DATA WITH A WATCHER" +Each watcher has, by default, a \f(CW\*(C`void *data\*(C'\fR member that you can read +or modify 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 separately 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 +function type instead have been omitted. +.SS "\s-1BUILDING YOUR OWN COMPOSITE WATCHERS\s0" +.IX Subsection "BUILDING YOUR OWN COMPOSITE WATCHERS" +Another common scenario is to use some data structure with multiple +embedded watchers, in effect creating your own watcher that combines +multiple libev event sources into one \*(L"super-watcher\*(R": +.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 \*(C+ coders), 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 +.SS "\s-1AVOIDING FINISHING BEFORE RETURNING\s0" +.IX Subsection "AVOIDING FINISHING BEFORE RETURNING" +Often you have structures like this in event-based programs: +.PP +.Vb 4 +\& callback () +\& { +\& free (request); +\& } +\& +\& request = start_new_request (..., callback); +.Ve +.PP +The intent is to start some \*(L"lengthy\*(R" operation. The \f(CW\*(C`request\*(C'\fR could be +used to cancel the operation, or do other things with it. +.PP +It's not uncommon to have code paths in \f(CW\*(C`start_new_request\*(C'\fR that +immediately invoke the callback, for example, to report errors. Or you add +some caching layer that finds that it can skip the lengthy aspects of the +operation and simply invoke the callback with the result. +.PP +The problem here is that this will happen \fIbefore\fR \f(CW\*(C`start_new_request\*(C'\fR +has returned, so \f(CW\*(C`request\*(C'\fR is not set. +.PP +Even if you pass the request by some safer means to the callback, you +might want to do something to the request after starting it, such as +canceling it, which probably isn't working so well when the callback has +already been invoked. +.PP +A common way around all these issues is to make sure that +\&\f(CW\*(C`start_new_request\*(C'\fR \fIalways\fR returns before the callback is invoked. If +\&\f(CW\*(C`start_new_request\*(C'\fR immediately knows the result, it can artificially +delay invoking the callback by using a \f(CW\*(C`prepare\*(C'\fR or \f(CW\*(C`idle\*(C'\fR watcher for +example, or more sneakily, by reusing an existing (stopped) watcher and +pushing it into the pending queue: +.PP +.Vb 2 +\& ev_set_cb (watcher, callback); +\& ev_feed_event (EV_A_ watcher, 0); +.Ve +.PP +This way, \f(CW\*(C`start_new_request\*(C'\fR can safely return before the callback is +invoked, while not delaying callback invocation too much. +.SS "\s-1MODEL/NESTED EVENT LOOP INVOCATIONS AND EXIT CONDITIONS\s0" +.IX Subsection "MODEL/NESTED EVENT LOOP INVOCATIONS AND EXIT CONDITIONS" +Often (especially in \s-1GUI\s0 toolkits) there are places where you have +\&\fImodal\fR interaction, which is most easily implemented by recursively +invoking \f(CW\*(C`ev_run\*(C'\fR. +.PP +This brings the problem of exiting \- a callback might want to finish the +main \f(CW\*(C`ev_run\*(C'\fR call, but not the nested one (e.g. user clicked \*(L"Quit\*(R", but +a modal \*(L"Are you sure?\*(R" dialog is still waiting), or just the nested one +and not the main one (e.g. user clocked \*(L"Ok\*(R" in a modal dialog), or some +other combination: In these cases, a simple \f(CW\*(C`ev_break\*(C'\fR will not work. +.PP +The solution is to maintain \*(L"break this loop\*(R" variable for each \f(CW\*(C`ev_run\*(C'\fR +invocation, and use a loop around \f(CW\*(C`ev_run\*(C'\fR until the condition is +triggered, using \f(CW\*(C`EVRUN_ONCE\*(C'\fR: +.PP +.Vb 2 +\& // main loop +\& int exit_main_loop = 0; +\& +\& while (!exit_main_loop) +\& ev_run (EV_DEFAULT_ EVRUN_ONCE); +\& +\& // in a modal watcher +\& int exit_nested_loop = 0; +\& +\& while (!exit_nested_loop) +\& ev_run (EV_A_ EVRUN_ONCE); +.Ve +.PP +To exit from any of these loops, just set the corresponding exit variable: +.PP +.Vb 2 +\& // exit modal loop +\& exit_nested_loop = 1; +\& +\& // exit main program, after modal loop is finished +\& exit_main_loop = 1; +\& +\& // exit both +\& exit_main_loop = exit_nested_loop = 1; +.Ve +.SS "\s-1THREAD LOCKING EXAMPLE\s0" +.IX Subsection "THREAD LOCKING EXAMPLE" +Here is a fictitious example of how to run an event loop in a different +thread from where callbacks are being invoked and watchers are +created/added/removed. +.PP +For a real-world example, see the \f(CW\*(C`EV::Loop::Async\*(C'\fR perl module, +which uses exactly this technique (which is suited for many high-level +languages). +.PP +The example uses a pthread mutex to protect the loop data, a condition +variable to wait for callback invocations, an async watcher to notify the +event loop thread and an unspecified mechanism to wake up the main thread. +.PP +First, you need to associate some data with the event loop: +.PP +.Vb 6 +\& typedef struct { +\& mutex_t lock; /* global loop lock */ +\& ev_async async_w; +\& thread_t tid; +\& cond_t invoke_cv; +\& } userdata; +\& +\& void prepare_loop (EV_P) +\& { +\& // for simplicity, we use a static userdata struct. +\& static userdata u; +\& +\& ev_async_init (&u\->async_w, async_cb); +\& ev_async_start (EV_A_ &u\->async_w); +\& +\& pthread_mutex_init (&u\->lock, 0); +\& pthread_cond_init (&u\->invoke_cv, 0); +\& +\& // now associate this with the loop +\& ev_set_userdata (EV_A_ u); +\& ev_set_invoke_pending_cb (EV_A_ l_invoke); +\& ev_set_loop_release_cb (EV_A_ l_release, l_acquire); +\& +\& // then create the thread running ev_run +\& pthread_create (&u\->tid, 0, l_run, EV_A); +\& } +.Ve +.PP +The callback for the \f(CW\*(C`ev_async\*(C'\fR watcher does nothing: the watcher is used +solely to wake up the event loop so it takes notice of any new watchers +that might have been added: +.PP +.Vb 5 +\& static void +\& async_cb (EV_P_ ev_async *w, int revents) +\& { +\& // just used for the side effects +\& } +.Ve +.PP +The \f(CW\*(C`l_release\*(C'\fR and \f(CW\*(C`l_acquire\*(C'\fR callbacks simply unlock/lock the mutex +protecting the loop data, respectively. +.PP +.Vb 6 +\& static void +\& l_release (EV_P) +\& { +\& userdata *u = ev_userdata (EV_A); +\& pthread_mutex_unlock (&u\->lock); +\& } +\& +\& static void +\& l_acquire (EV_P) +\& { +\& userdata *u = ev_userdata (EV_A); +\& pthread_mutex_lock (&u\->lock); +\& } +.Ve +.PP +The event loop thread first acquires the mutex, and then jumps straight +into \f(CW\*(C`ev_run\*(C'\fR: +.PP +.Vb 4 +\& void * +\& l_run (void *thr_arg) +\& { +\& struct ev_loop *loop = (struct ev_loop *)thr_arg; +\& +\& l_acquire (EV_A); +\& pthread_setcanceltype (PTHREAD_CANCEL_ASYNCHRONOUS, 0); +\& ev_run (EV_A_ 0); +\& l_release (EV_A); +\& +\& return 0; +\& } +.Ve +.PP +Instead of invoking all pending watchers, the \f(CW\*(C`l_invoke\*(C'\fR callback will +signal the main thread via some unspecified mechanism (signals? pipe +writes? \f(CW\*(C`Async::Interrupt\*(C'\fR?) and then waits until all pending watchers +have been called (in a while loop because a) spurious wakeups are possible +and b) skipping inter-thread-communication when there are no pending +watchers is very beneficial): +.PP +.Vb 4 +\& static void +\& l_invoke (EV_P) +\& { +\& userdata *u = ev_userdata (EV_A); +\& +\& while (ev_pending_count (EV_A)) +\& { +\& wake_up_other_thread_in_some_magic_or_not_so_magic_way (); +\& pthread_cond_wait (&u\->invoke_cv, &u\->lock); +\& } +\& } +.Ve +.PP +Now, whenever the main thread gets told to invoke pending watchers, it +will grab the lock, call \f(CW\*(C`ev_invoke_pending\*(C'\fR and then signal the loop +thread to continue: +.PP +.Vb 4 +\& static void +\& real_invoke_pending (EV_P) +\& { +\& userdata *u = ev_userdata (EV_A); +\& +\& pthread_mutex_lock (&u\->lock); +\& ev_invoke_pending (EV_A); +\& pthread_cond_signal (&u\->invoke_cv); +\& pthread_mutex_unlock (&u\->lock); +\& } +.Ve +.PP +Whenever you want to start/stop a watcher or do other modifications to an +event loop, you will now have to lock: +.PP +.Vb 2 +\& ev_timer timeout_watcher; +\& userdata *u = ev_userdata (EV_A); +\& +\& ev_timer_init (&timeout_watcher, timeout_cb, 5.5, 0.); +\& +\& pthread_mutex_lock (&u\->lock); +\& ev_timer_start (EV_A_ &timeout_watcher); +\& ev_async_send (EV_A_ &u\->async_w); +\& pthread_mutex_unlock (&u\->lock); +.Ve +.PP +Note that sending the \f(CW\*(C`ev_async\*(C'\fR watcher is required because otherwise +an event loop currently blocking in the kernel will have no knowledge +about the newly added timer. By waking up the loop it will pick up any new +watchers in the next event loop iteration. +.SS "\s-1THREADS, COROUTINES, CONTINUATIONS, QUEUES... INSTEAD OF CALLBACKS\s0" +.IX Subsection "THREADS, COROUTINES, CONTINUATIONS, QUEUES... INSTEAD OF CALLBACKS" +While the overhead of a callback that e.g. schedules a thread is small, it +is still an overhead. If you embed libev, and your main usage is with some +kind of threads or coroutines, you might want to customise libev so that +doesn't need callbacks anymore. +.PP +Imagine you have coroutines that you can switch to using a function +\&\f(CW\*(C`switch_to (coro)\*(C'\fR, that libev runs in a coroutine called \f(CW\*(C`libev_coro\*(C'\fR +and that due to some magic, the currently active coroutine is stored in a +global called \f(CW\*(C`current_coro\*(C'\fR. Then you can build your own \*(L"wait for libev +event\*(R" primitive by changing \f(CW\*(C`EV_CB_DECLARE\*(C'\fR and \f(CW\*(C`EV_CB_INVOKE\*(C'\fR (note +the differing \f(CW\*(C`;\*(C'\fR conventions): +.PP +.Vb 2 +\& #define EV_CB_DECLARE(type) struct my_coro *cb; +\& #define EV_CB_INVOKE(watcher) switch_to ((watcher)\->cb) +.Ve +.PP +That means instead of having a C callback function, you store the +coroutine to switch to in each watcher, and instead of having libev call +your callback, you instead have it switch to that coroutine. +.PP +A coroutine might now wait for an event with a function called +\&\f(CW\*(C`wait_for_event\*(C'\fR. (the watcher needs to be started, as always, but it doesn't +matter when, or whether the watcher is active or not when this function is +called): +.PP +.Vb 6 +\& void +\& wait_for_event (ev_watcher *w) +\& { +\& ev_set_cb (w, current_coro); +\& switch_to (libev_coro); +\& } +.Ve +.PP +That basically suspends the coroutine inside \f(CW\*(C`wait_for_event\*(C'\fR and +continues the libev coroutine, which, when appropriate, switches back to +this or any other coroutine. +.PP +You can do similar tricks if you have, say, threads with an event queue \- +instead of storing a coroutine, you store the queue object and instead of +switching to a coroutine, you push the watcher onto the queue and notify +any waiters. +.PP +To embed libev, see \*(L"\s-1EMBEDDING\*(R"\s0, but in short, it's easiest to create two +files, \fImy_ev.h\fR and \fImy_ev.c\fR that include the respective libev files: +.PP +.Vb 4 +\& // my_ev.h +\& #define EV_CB_DECLARE(type) struct my_coro *cb; +\& #define EV_CB_INVOKE(watcher) switch_to ((watcher)\->cb) +\& #include "../libev/ev.h" +\& +\& // my_ev.c +\& #define EV_H "my_ev.h" +\& #include "../libev/ev.c" +.Ve +.PP +And then use \fImy_ev.h\fR when you would normally use \fIev.h\fR, and compile +\&\fImy_ev.c\fR into your project. When properly specifying include paths, you +can even use \fIev.h\fR as header file name directly. +.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 +Only the libevent\-1.4.1\-beta \s-1API\s0 is being emulated. +.Sp +This was the newest libevent version available when libev was implemented, +and is still mostly unchanged in 2010. +.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 +base that registered the signal 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" +.SS "C \s-1API\s0" +.IX Subsection "C API" +The normal C \s-1API\s0 should work fine when used from \*(C+: both ev.h and the +libev sources can be compiled as \*(C+. Therefore, code that uses the C \s-1API\s0 +will work fine. +.PP +Proper exception specifications might have to be added to callbacks passed +to libev: exceptions may be thrown only from watcher callbacks, all +other callbacks (allocator, syserr, loop acquire/release and periodic +reschedule callbacks) must not throw exceptions, and might need a \f(CW\*(C`throw +()\*(C'\fR specification. If you have code that needs to be compiled as both C +and \*(C+ you can use the \f(CW\*(C`EV_THROW\*(C'\fR macro for this: +.PP +.Vb 6 +\& static void +\& fatal_error (const char *msg) EV_THROW +\& { +\& perror (msg); +\& abort (); +\& } +\& +\& ... +\& ev_set_syserr_cb (fatal_error); +.Ve +.PP +The only \s-1API\s0 functions that can currently throw exceptions are \f(CW\*(C`ev_run\*(C'\fR, +\&\f(CW\*(C`ev_invoke\*(C'\fR, \f(CW\*(C`ev_invoke_pending\*(C'\fR and \f(CW\*(C`ev_loop_destroy\*(C'\fR (the latter +because it runs cleanup watchers). +.PP +Throwing exceptions in watcher callbacks is only supported if libev itself +is compiled with a \*(C+ compiler or your C and \*(C+ environments allow +throwing exceptions through C libraries (most do). +.SS "\*(C+ \s-1API\s0" +.IX Subsection " API" +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, static and non-static member functions and classes +with \f(CW\*(C`operator ()\*(C'\fR 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 +For all this to work, your \*(C+ compiler either has to use the same calling +conventions as your C compiler (for static member functions), or you have +to embed libev and compile libev itself as \*(C+. +.PP +Here is a list of things available in the \f(CW\*(C`ev\*(C'\fR namespace: +.ie n .IP """ev::READ"", ""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"", ""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"", ""ev::timer"", ""ev::periodic"", ""ev::idle"", ""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 +defined 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 (loop)" 4 +.IX Item "ev::TYPE::TYPE (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 (object *)" 4 +.IX Item "w->set (object *)" +This is a variation of a method callback \- leaving out the method to call +will default the method to \f(CW\*(C`operator ()\*(C'\fR, which makes it possible to use +functor objects without having to manually specify the \f(CW\*(C`operator ()\*(C'\fR all +the time. Incidentally, you can then also leave out the template argument +list. +.Sp +The \f(CW\*(C`operator ()\*(C'\fR method prototype must be \f(CW\*(C`void operator ()(watcher &w, +int revents)\*(C'\fR. +.Sp +See the method\-\f(CW\*(C`set\*(C'\fR above for more details. +.Sp +Example: use a functor object as callback. +.Sp +.Vb 7 +\& struct myfunctor +\& { +\& void operator() (ev::io &w, int revents) +\& { +\& ... +\& } +\& } +\& +\& myfunctor f; +\& +\& ev::io w; +\& w.set (&f); +.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 (loop)" 4 +.IX Item "w->set (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 (except for \f(CW\*(C`ev::embed\*(C'\fR watchers>), +with the same arguments. Either this method or a suitable start method +must be called at least once. Unlike the C counterpart, an active watcher +gets automatically stopped and restarted when reconfiguring it with this +method. +.Sp +For \f(CW\*(C`ev::embed\*(C'\fR watchers this method is called \f(CW\*(C`set_embed\*(C'\fR, to avoid +clashing with the \f(CW\*(C`set (loop)\*(C'\fR 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\->start ([arguments])" 4 +.IX Item "w->start ([arguments])" +Instead of calling \f(CW\*(C`set\*(C'\fR and \f(CW\*(C`start\*(C'\fR methods separately, it is often +convenient to wrap them in one call. Uses the same type of arguments as +the configure \f(CW\*(C`set\*(C'\fR method of the watcher. +.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"", ""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 two I/O and idle watchers, start the I/O +watchers in the constructor. +.PP +.Vb 5 +\& class myclass +\& { +\& ev::io io ; void io_cb (ev::io &w, int revents); +\& ev::io io2 ; void io2_cb (ev::io &w, int revents); +\& ev::idle idle; void idle_cb (ev::idle &w, int revents); +\& +\& myclass (int fd) +\& { +\& io .set (this); +\& io2 .set (this); +\& idle.set (this); +\& +\& io.set (fd, ev::WRITE); // configure the watcher +\& io.start (); // start it whenever convenient +\& +\& io2.start (fd, ev::READ); // set + start in one call +\& } +\& }; +.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. +.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 +. +.Sp +Roger Pack reports that using the link order \f(CW\*(C`\-lws2_32 \-lmsvcrt\-ruby\-190\*(C'\fR +makes rev work even on mingw. +.IP "Haskell" 4 +.IX Item "Haskell" +A haskell binding to libev is available 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 +. +.IP "Lua" 4 +.IX Item "Lua" +Brian Maher has written a partial interface to libev for lua (at the +time of this writing, only \f(CW\*(C`ev_io\*(C'\fR and \f(CW\*(C`ev_timer\*(C'\fR), to be found at +. +.IP "Javascript" 4 +.IX Item "Javascript" +Node.js () uses libev as the underlying event library. +.IP "Others" 4 +.IX Item "Others" +There are others, and I stopped counting. +.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"", ""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_run (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"", ""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"", ""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"). The default loop +will be initialised if it isn't already initialised. +.Sp +For non-multiplicity builds, these macros do nothing, so you always have +to initialise the loop somewhere. +.ie n .IP """EV_DEFAULT_UC"", ""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_run (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). +.SS "\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 EVENT LOOP\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 +\& ev_poll.c only when poll backend is enabled +\& ev_epoll.c only when the epoll backend is enabled +\& ev_kqueue.c only when the kqueue backend is enabled +\& ev_port.c only when the solaris port backend is enabled +.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 COMPATIBILITY API\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 +\& #include "event.h" +.Ve +.PP +in the files that want to use the libevent \s-1API.\s0 This also includes \fIev.h\fR. +.PP +You need the following additional files for this: +.PP +.Vb 2 +\& event.h +\& event.c +.Ve +.PP +\fI\s-1AUTOCONF SUPPORT\s0\fR +.IX Subsection "AUTOCONF SUPPORT" +.PP +Instead of using \f(CW\*(C`EV_STANDALONE=1\*(C'\fR and providing your configuration in +whatever way you want, you can also \f(CW\*(C`m4_include([libev.m4])\*(C'\fR in your +\&\fIconfigure.ac\fR and leave \f(CW\*(C`EV_STANDALONE\*(C'\fR undefined. \fIev.c\fR will then +include \fIconfig.h\fR and configure itself accordingly. +.PP +For this of course you need the m4 file: +.PP +.Vb 1 +\& libev.m4 +.Ve +.SS "\s-1PREPROCESSOR SYMBOLS/MACROS\s0" +.IX Subsection "PREPROCESSOR SYMBOLS/MACROS" +Libev can be configured via a variety of preprocessor symbols you have to +define before including (or compiling) any of its files. The default in +the absence of autoconf is documented for every option. +.PP +Symbols marked with \*(L"(h)\*(R" do not change the \s-1ABI,\s0 and can have different +values when compiling libev vs. including \fIev.h\fR, so it is permissible +to redefine them before including \fIev.h\fR without breaking compatibility +to a compiled library. All other symbols change the \s-1ABI,\s0 which means all +users of libev and the libev code itself must be compiled with compatible +settings. +.IP "\s-1EV_COMPAT3 \s0(h)" 4 +.IX Item "EV_COMPAT3 (h)" +Backwards compatibility is a major concern for libev. This is why this +release of libev comes with wrappers for the functions and symbols that +have been renamed between libev version 3 and 4. +.Sp +You can disable these wrappers (to test compatibility with future +versions) by defining \f(CW\*(C`EV_COMPAT3\*(C'\fR to \f(CW0\fR when compiling your +sources. This has the additional advantage that you can drop the \f(CW\*(C`struct\*(C'\fR +from \f(CW\*(C`struct ev_loop\*(C'\fR declarations, as libev will provide an \f(CW\*(C`ev_loop\*(C'\fR +typedef in that case. +.Sp +In some future version, the default for \f(CW\*(C`EV_COMPAT3\*(C'\fR will become \f(CW0\fR, +and in some even more future version the compatibility code will be +removed completely. +.IP "\s-1EV_STANDALONE \s0(h)" 4 +.IX Item "EV_STANDALONE (h)" +Must always be \f(CW1\fR if you do not use autoconf configuration, which +keeps libev from including \fIconfig.h\fR, and it also defines dummy +implementations for some libevent functions (such as logging, which is not +supported). It will also not define any of the structs usually found in +\&\fIevent.h\fR that are not directly supported by the libev core alone. +.Sp +In standalone mode, libev will still try to automatically deduce the +configuration, but has to be more conservative. +.IP "\s-1EV_USE_FLOOR\s0" 4 +.IX Item "EV_USE_FLOOR" +If defined to be \f(CW1\fR, libev will use the \f(CW\*(C`floor ()\*(C'\fR function for its +periodic reschedule calculations, otherwise libev will fall back on a +portable (slower) implementation. If you enable this, you usually have to +link against libm or something equivalent. Enabling this when the \f(CW\*(C`floor\*(C'\fR +function is not available will fail, so the safe default is to not enable +this. +.IP "\s-1EV_USE_MONOTONIC\s0" 4 +.IX Item "EV_USE_MONOTONIC" +If defined to be \f(CW1\fR, libev will try to detect the availability of the +monotonic clock option at both compile time and runtime. Otherwise no +use of the monotonic clock option will be attempted. If you enable this, +you usually have to link against librt or something similar. Enabling it +when the functionality isn't available is safe, though, although you have +to make sure you link against any libraries where the \f(CW\*(C`clock_gettime\*(C'\fR +function is hiding in (often \fI\-lrt\fR). See also \f(CW\*(C`EV_USE_CLOCK_SYSCALL\*(C'\fR. +.IP "\s-1EV_USE_REALTIME\s0" 4 +.IX Item "EV_USE_REALTIME" +If defined to be \f(CW1\fR, libev will try to detect the availability of the +real-time clock option at compile time (and assume its availability +at runtime if successful). Otherwise no use of the real-time clock +option will be attempted. This effectively replaces \f(CW\*(C`gettimeofday\*(C'\fR +by \f(CW\*(C`clock_get (CLOCK_REALTIME, ...)\*(C'\fR and will not normally affect +correctness. See the note about libraries in the description of +\&\f(CW\*(C`EV_USE_MONOTONIC\*(C'\fR, though. Defaults to the opposite value of +\&\f(CW\*(C`EV_USE_CLOCK_SYSCALL\*(C'\fR. +.IP "\s-1EV_USE_CLOCK_SYSCALL\s0" 4 +.IX Item "EV_USE_CLOCK_SYSCALL" +If defined to be \f(CW1\fR, libev will try to use a direct syscall instead +of calling the system-provided \f(CW\*(C`clock_gettime\*(C'\fR function. This option +exists because on GNU/Linux, \f(CW\*(C`clock_gettime\*(C'\fR is in \f(CW\*(C`librt\*(C'\fR, but \f(CW\*(C`librt\*(C'\fR +unconditionally pulls in \f(CW\*(C`libpthread\*(C'\fR, slowing down single-threaded +programs needlessly. Using a direct syscall is slightly slower (in +theory), because no optimised vdso implementation can be used, but avoids +the pthread dependency. Defaults to \f(CW1\fR on GNU/Linux with glibc 2.x or +higher, as it simplifies linking (no need for \f(CW\*(C`\-lrt\*(C'\fR). +.IP "\s-1EV_USE_NANOSLEEP\s0" 4 +.IX Item "EV_USE_NANOSLEEP" +If defined to be \f(CW1\fR, libev will assume that \f(CW\*(C`nanosleep ()\*(C'\fR is available +and will use it for delays. Otherwise it will use \f(CW\*(C`select ()\*(C'\fR. +.IP "\s-1EV_USE_EVENTFD\s0" 4 +.IX Item "EV_USE_EVENTFD" +If defined to be \f(CW1\fR, then libev will assume that \f(CW\*(C`eventfd ()\*(C'\fR is +available and will probe for kernel support at runtime. This will improve +\&\f(CW\*(C`ev_signal\*(C'\fR and \f(CW\*(C`ev_async\*(C'\fR performance and reduce resource consumption. +If undefined, it will be enabled if the headers indicate GNU/Linux + Glibc +2.7 or newer, otherwise disabled. +.IP "\s-1EV_USE_SELECT\s0" 4 +.IX Item "EV_USE_SELECT" +If undefined or defined to be \f(CW1\fR, libev will compile in support for the +\&\f(CW\*(C`select\*(C'\fR(2) backend. No attempt at auto-detection will be done: if no +other method takes over, select will be it. Otherwise the select backend +will not be compiled in. +.IP "\s-1EV_SELECT_USE_FD_SET\s0" 4 +.IX Item "EV_SELECT_USE_FD_SET" +If defined to \f(CW1\fR, then the select backend will use the system \f(CW\*(C`fd_set\*(C'\fR +structure. This is useful if libev doesn't compile due to a missing +\&\f(CW\*(C`NFDBITS\*(C'\fR or \f(CW\*(C`fd_mask\*(C'\fR definition or it mis-guesses the bitset layout +on exotic systems. This usually limits the range of file descriptors to +some low limit such as 1024 or might have other limitations (winsocket +only allows 64 sockets). The \f(CW\*(C`FD_SETSIZE\*(C'\fR macro, set before compilation, +configures the maximum size of the \f(CW\*(C`fd_set\*(C'\fR. +.IP "\s-1EV_SELECT_IS_WINSOCKET\s0" 4 +.IX Item "EV_SELECT_IS_WINSOCKET" +When defined to \f(CW1\fR, the select backend will assume that +select/socket/connect etc. don't understand file descriptors but +wants osf handles on win32 (this is the case when the select to +be used is the winsock select). This means that it will call +\&\f(CW\*(C`_get_osfhandle\*(C'\fR on the fd to convert it to an \s-1OS\s0 handle. Otherwise, +it is assumed that all these functions actually work on fds, even +on win32. Should not be defined on non\-win32 platforms. +.IP "\s-1EV_FD_TO_WIN32_HANDLE\s0(fd)" 4 +.IX Item "EV_FD_TO_WIN32_HANDLE(fd)" +If \f(CW\*(C`EV_SELECT_IS_WINSOCKET\*(C'\fR is enabled, then libev needs a way to map +file descriptors to socket handles. When not defining this symbol (the +default), then libev will call \f(CW\*(C`_get_osfhandle\*(C'\fR, which is usually +correct. In some cases, programs use their own file descriptor management, +in which case they can provide this function to map fds to socket handles. +.IP "\s-1EV_WIN32_HANDLE_TO_FD\s0(handle)" 4 +.IX Item "EV_WIN32_HANDLE_TO_FD(handle)" +If \f(CW\*(C`EV_SELECT_IS_WINSOCKET\*(C'\fR then libev maps handles to file descriptors +using the standard \f(CW\*(C`_open_osfhandle\*(C'\fR function. For programs implementing +their own fd to handle mapping, overwriting this function makes it easier +to do so. This can be done by defining this macro to an appropriate value. +.IP "\s-1EV_WIN32_CLOSE_FD\s0(fd)" 4 +.IX Item "EV_WIN32_CLOSE_FD(fd)" +If programs implement their own fd to handle mapping on win32, then this +macro can be used to override the \f(CW\*(C`close\*(C'\fR function, useful to unregister +file descriptors again. Note that the replacement function has to close +the underlying \s-1OS\s0 handle. +.IP "\s-1EV_USE_WSASOCKET\s0" 4 +.IX Item "EV_USE_WSASOCKET" +If defined to be \f(CW1\fR, libev will use \f(CW\*(C`WSASocket\*(C'\fR to create its internal +communication socket, which works better in some environments. Otherwise, +the normal \f(CW\*(C`socket\*(C'\fR function will be used, which works better in other +environments. +.IP "\s-1EV_USE_POLL\s0" 4 +.IX Item "EV_USE_POLL" +If defined to be \f(CW1\fR, libev will compile in support for the \f(CW\*(C`poll\*(C'\fR(2) +backend. Otherwise it will be enabled on non\-win32 platforms. It +takes precedence over select. +.IP "\s-1EV_USE_EPOLL\s0" 4 +.IX Item "EV_USE_EPOLL" +If defined to be \f(CW1\fR, libev will compile in support for the Linux +\&\f(CW\*(C`epoll\*(C'\fR(7) backend. Its availability will be detected at runtime, +otherwise another method will be used as fallback. This is the preferred +backend for GNU/Linux systems. If undefined, it will be enabled if the +headers indicate GNU/Linux + Glibc 2.4 or newer, otherwise disabled. +.IP "\s-1EV_USE_KQUEUE\s0" 4 +.IX Item "EV_USE_KQUEUE" +If defined to be \f(CW1\fR, libev will compile in support for the \s-1BSD\s0 style +\&\f(CW\*(C`kqueue\*(C'\fR(2) backend. Its actual availability will be detected at runtime, +otherwise another method will be used as fallback. This is the preferred +backend for \s-1BSD\s0 and BSD-like systems, although on most BSDs kqueue only +supports some types of fds correctly (the only platform we found that +supports ptys for example was NetBSD), so kqueue might be compiled in, but +not be used unless explicitly requested. The best way to use it is to find +out whether kqueue supports your type of fd properly and use an embedded +kqueue loop. +.IP "\s-1EV_USE_PORT\s0" 4 +.IX Item "EV_USE_PORT" +If defined to be \f(CW1\fR, libev will compile in support for the Solaris +10 port style backend. Its availability will be detected at runtime, +otherwise another method will be used as fallback. This is the preferred +backend for Solaris 10 systems. +.IP "\s-1EV_USE_DEVPOLL\s0" 4 +.IX Item "EV_USE_DEVPOLL" +Reserved for future expansion, works like the \s-1USE\s0 symbols above. +.IP "\s-1EV_USE_INOTIFY\s0" 4 +.IX Item "EV_USE_INOTIFY" +If defined to be \f(CW1\fR, libev will compile in support for the Linux inotify +interface to speed up \f(CW\*(C`ev_stat\*(C'\fR watchers. Its actual availability will +be detected at runtime. If undefined, it will be enabled if the headers +indicate GNU/Linux + Glibc 2.4 or newer, otherwise disabled. +.IP "\s-1EV_NO_SMP\s0" 4 +.IX Item "EV_NO_SMP" +If defined to be \f(CW1\fR, libev will assume that memory is always coherent +between threads, that is, threads can be used, but threads never run on +different cpus (or different cpu cores). This reduces dependencies +and makes libev faster. +.IP "\s-1EV_NO_THREADS\s0" 4 +.IX Item "EV_NO_THREADS" +If defined to be \f(CW1\fR, libev will assume that it will never be called from +different threads (that includes signal handlers), which is a stronger +assumption than \f(CW\*(C`EV_NO_SMP\*(C'\fR, above. This reduces dependencies and makes +libev faster. +.IP "\s-1EV_ATOMIC_T\s0" 4 +.IX Item "EV_ATOMIC_T" +Libev requires an integer type (suitable for storing \f(CW0\fR or \f(CW1\fR) whose +access is atomic with respect to other threads or signal contexts. No +such type is easily found in the C language, so you can provide your own +type that you know is safe for your purposes. It is used both for signal +handler \*(L"locking\*(R" as well as for signal and thread safety in \f(CW\*(C`ev_async\*(C'\fR +watchers. +.Sp +In the absence of this define, libev will use \f(CW\*(C`sig_atomic_t volatile\*(C'\fR +(from \fIsignal.h\fR), which is usually good enough on most platforms. +.IP "\s-1EV_H \s0(h)" 4 +.IX Item "EV_H (h)" +The name of the \fIev.h\fR header file used to include it. The default if +undefined is \f(CW"ev.h"\fR in \fIevent.h\fR, \fIev.c\fR and \fIev++.h\fR. This can be +used to virtually rename the \fIev.h\fR header file in case of conflicts. +.IP "\s-1EV_CONFIG_H \s0(h)" 4 +.IX Item "EV_CONFIG_H (h)" +If \f(CW\*(C`EV_STANDALONE\*(C'\fR isn't \f(CW1\fR, this variable can be used to override +\&\fIev.c\fR's idea of where to find the \fIconfig.h\fR file, similarly to +\&\f(CW\*(C`EV_H\*(C'\fR, above. +.IP "\s-1EV_EVENT_H \s0(h)" 4 +.IX Item "EV_EVENT_H (h)" +Similarly to \f(CW\*(C`EV_H\*(C'\fR, this macro can be used to override \fIevent.c\fR's idea +of how the \fIevent.h\fR header can be found, the default is \f(CW"event.h"\fR. +.IP "\s-1EV_PROTOTYPES \s0(h)" 4 +.IX Item "EV_PROTOTYPES (h)" +If defined to be \f(CW0\fR, then \fIev.h\fR will not define any function +prototypes, but still define all the structs and other symbols. This is +occasionally useful if you want to provide your own wrapper functions +around libev functions. +.IP "\s-1EV_MULTIPLICITY\s0" 4 +.IX Item "EV_MULTIPLICITY" +If undefined or defined to \f(CW1\fR, then all event-loop-specific functions +will have the \f(CW\*(C`struct ev_loop *\*(C'\fR as first argument, and you can create +additional independent event loops. Otherwise there will be no support +for multiple event loops and there is no first event loop pointer +argument. Instead, all functions act on the single default loop. +.Sp +Note that \f(CW\*(C`EV_DEFAULT\*(C'\fR and \f(CW\*(C`EV_DEFAULT_\*(C'\fR will no longer provide a +default loop when multiplicity is switched off \- you always have to +initialise the loop manually in this case. +.IP "\s-1EV_MINPRI\s0" 4 +.IX Item "EV_MINPRI" +.PD 0 +.IP "\s-1EV_MAXPRI\s0" 4 +.IX Item "EV_MAXPRI" +.PD +The range of allowed priorities. \f(CW\*(C`EV_MINPRI\*(C'\fR must be smaller or equal to +\&\f(CW\*(C`EV_MAXPRI\*(C'\fR, but otherwise there are no non-obvious limitations. You can +provide for more priorities by overriding those symbols (usually defined +to be \f(CW\*(C`\-2\*(C'\fR and \f(CW2\fR, respectively). +.Sp +When doing priority-based operations, libev usually has to linearly search +all the priorities, so having many of them (hundreds) uses a lot of space +and time, so using the defaults of five priorities (\-2 .. +2) is usually +fine. +.Sp +If your embedding application does not need any priorities, defining these +both to \f(CW0\fR will save some memory and \s-1CPU.\s0 +.IP "\s-1EV_PERIODIC_ENABLE, EV_IDLE_ENABLE, EV_EMBED_ENABLE, EV_STAT_ENABLE, EV_PREPARE_ENABLE, EV_CHECK_ENABLE, EV_FORK_ENABLE, EV_SIGNAL_ENABLE, EV_ASYNC_ENABLE, EV_CHILD_ENABLE.\s0" 4 +.IX Item "EV_PERIODIC_ENABLE, EV_IDLE_ENABLE, EV_EMBED_ENABLE, EV_STAT_ENABLE, EV_PREPARE_ENABLE, EV_CHECK_ENABLE, EV_FORK_ENABLE, EV_SIGNAL_ENABLE, EV_ASYNC_ENABLE, EV_CHILD_ENABLE." +If undefined or defined to be \f(CW1\fR (and the platform supports it), then +the respective watcher type is supported. If defined to be \f(CW0\fR, then it +is not. Disabling watcher types mainly saves code size. +.IP "\s-1EV_FEATURES\s0" 4 +.IX Item "EV_FEATURES" +If you need to shave off some kilobytes of code at the expense of some +speed (but with the full \s-1API\s0), you can define this symbol to request +certain subsets of functionality. The default is to enable all features +that can be enabled on the platform. +.Sp +A typical way to use this symbol is to define it to \f(CW0\fR (or to a bitset +with some broad features you want) and then selectively re-enable +additional parts you want, for example if you want everything minimal, +but multiple event loop support, async and child watchers and the poll +backend, use this: +.Sp +.Vb 5 +\& #define EV_FEATURES 0 +\& #define EV_MULTIPLICITY 1 +\& #define EV_USE_POLL 1 +\& #define EV_CHILD_ENABLE 1 +\& #define EV_ASYNC_ENABLE 1 +.Ve +.Sp +The actual value is a bitset, it can be a combination of the following +values (by default, all of these are enabled): +.RS 4 +.ie n .IP "1 \- faster/larger code" 4 +.el .IP "\f(CW1\fR \- faster/larger code" 4 +.IX Item "1 - faster/larger code" +Use larger code to speed up some operations. +.Sp +Currently this is used to override some inlining decisions (enlarging the +code size by roughly 30% on amd64). +.Sp +When optimising for size, use of compiler flags such as \f(CW\*(C`\-Os\*(C'\fR with +gcc is recommended, as well as \f(CW\*(C`\-DNDEBUG\*(C'\fR, as libev contains a number of +assertions. +.Sp +The default is off when \f(CW\*(C`_\|_OPTIMIZE_SIZE_\|_\*(C'\fR is defined by your compiler +(e.g. gcc with \f(CW\*(C`\-Os\*(C'\fR). +.ie n .IP "2 \- faster/larger data structures" 4 +.el .IP "\f(CW2\fR \- faster/larger data structures" 4 +.IX Item "2 - faster/larger data structures" +Replaces the small 2\-heap for timer management by a faster 4\-heap, larger +hash table sizes and so on. This will usually further increase code size +and can additionally have an effect on the size of data structures at +runtime. +.Sp +The default is off when \f(CW\*(C`_\|_OPTIMIZE_SIZE_\|_\*(C'\fR is defined by your compiler +(e.g. gcc with \f(CW\*(C`\-Os\*(C'\fR). +.ie n .IP "4 \- full \s-1API\s0 configuration" 4 +.el .IP "\f(CW4\fR \- full \s-1API\s0 configuration" 4 +.IX Item "4 - full API configuration" +This enables priorities (sets \f(CW\*(C`EV_MAXPRI\*(C'\fR=2 and \f(CW\*(C`EV_MINPRI\*(C'\fR=\-2), and +enables multiplicity (\f(CW\*(C`EV_MULTIPLICITY\*(C'\fR=1). +.ie n .IP "8 \- full \s-1API\s0" 4 +.el .IP "\f(CW8\fR \- full \s-1API\s0" 4 +.IX Item "8 - full API" +This enables a lot of the \*(L"lesser used\*(R" \s-1API\s0 functions. See \f(CW\*(C`ev.h\*(C'\fR for +details on which parts of the \s-1API\s0 are still available without this +feature, and do not complain if this subset changes over time. +.ie n .IP "16 \- enable all optional watcher types" 4 +.el .IP "\f(CW16\fR \- enable all optional watcher types" 4 +.IX Item "16 - enable all optional watcher types" +Enables all optional watcher types. If you want to selectively enable +only some watcher types other than I/O and timers (e.g. prepare, +embed, async, child...) you can enable them manually by defining +\&\f(CW\*(C`EV_watchertype_ENABLE\*(C'\fR to \f(CW1\fR instead. +.ie n .IP "32 \- enable all backends" 4 +.el .IP "\f(CW32\fR \- enable all backends" 4 +.IX Item "32 - enable all backends" +This enables all backends \- without this feature, you need to enable at +least one backend manually (\f(CW\*(C`EV_USE_SELECT\*(C'\fR is a good choice). +.ie n .IP "64 \- enable OS-specific ""helper"" APIs" 4 +.el .IP "\f(CW64\fR \- enable OS-specific ``helper'' APIs" 4 +.IX Item "64 - enable OS-specific helper APIs" +Enable inotify, eventfd, signalfd and similar OS-specific helper APIs by +default. +.RE +.RS 4 +.Sp +Compiling with \f(CW\*(C`gcc \-Os \-DEV_STANDALONE \-DEV_USE_EPOLL=1 \-DEV_FEATURES=0\*(C'\fR +reduces the compiled size of libev from 24.7Kb code/2.8Kb data to 6.5Kb +code/0.3Kb data on my GNU/Linux amd64 system, while still giving you I/O +watchers, timers and monotonic clock support. +.Sp +With an intelligent-enough linker (gcc+binutils are intelligent enough +when you use \f(CW\*(C`\-Wl,\-\-gc\-sections \-ffunction\-sections\*(C'\fR) functions unused by +your program might be left out as well \- a binary starting a timer and an +I/O watcher then might come out at only 5Kb. +.RE +.IP "\s-1EV_API_STATIC\s0" 4 +.IX Item "EV_API_STATIC" +If this symbol is defined (by default it is not), then all identifiers +will have static linkage. This means that libev will not export any +identifiers, and you cannot link against libev anymore. This can be useful +when you embed libev, only want to use libev functions in a single file, +and do not want its identifiers to be visible. +.Sp +To use this, define \f(CW\*(C`EV_API_STATIC\*(C'\fR and include \fIev.c\fR in the file that +wants to use libev. +.Sp +This option only works when libev is compiled with a C compiler, as \*(C+ +doesn't support the required declaration syntax. +.IP "\s-1EV_AVOID_STDIO\s0" 4 +.IX Item "EV_AVOID_STDIO" +If this is set to \f(CW1\fR at compiletime, then libev will avoid using stdio +functions (printf, scanf, perror etc.). This will increase the code size +somewhat, but if your program doesn't otherwise depend on stdio and your +libc allows it, this avoids linking in the stdio library which is quite +big. +.Sp +Note that error messages might become less precise when this option is +enabled. +.IP "\s-1EV_NSIG\s0" 4 +.IX Item "EV_NSIG" +The highest supported signal number, +1 (or, the number of +signals): Normally, libev tries to deduce the maximum number of signals +automatically, but sometimes this fails, in which case it can be +specified. Also, using a lower number than detected (\f(CW32\fR should be +good for about any system in existence) can save some memory, as libev +statically allocates some 12\-24 bytes per signal number. +.IP "\s-1EV_PID_HASHSIZE\s0" 4 +.IX Item "EV_PID_HASHSIZE" +\&\f(CW\*(C`ev_child\*(C'\fR watchers use a small hash table to distribute workload by +pid. The default size is \f(CW16\fR (or \f(CW1\fR with \f(CW\*(C`EV_FEATURES\*(C'\fR disabled), +usually more than enough. If you need to manage thousands of children you +might want to increase this value (\fImust\fR be a power of two). +.IP "\s-1EV_INOTIFY_HASHSIZE\s0" 4 +.IX Item "EV_INOTIFY_HASHSIZE" +\&\f(CW\*(C`ev_stat\*(C'\fR watchers use a small hash table to distribute workload by +inotify watch id. The default size is \f(CW16\fR (or \f(CW1\fR with \f(CW\*(C`EV_FEATURES\*(C'\fR +disabled), usually more than enough. If you need to manage thousands of +\&\f(CW\*(C`ev_stat\*(C'\fR watchers you might want to increase this value (\fImust\fR be a +power of two). +.IP "\s-1EV_USE_4HEAP\s0" 4 +.IX Item "EV_USE_4HEAP" +Heaps are not very cache-efficient. To improve the cache-efficiency of the +timer and periodics heaps, libev uses a 4\-heap when this symbol is defined +to \f(CW1\fR. The 4\-heap uses more complicated (longer) code but has noticeably +faster performance with many (thousands) of watchers. +.Sp +The default is \f(CW1\fR, unless \f(CW\*(C`EV_FEATURES\*(C'\fR overrides it, in which case it +will be \f(CW0\fR. +.IP "\s-1EV_HEAP_CACHE_AT\s0" 4 +.IX Item "EV_HEAP_CACHE_AT" +Heaps are not very cache-efficient. To improve the cache-efficiency of the +timer and periodics heaps, libev can cache the timestamp (\fIat\fR) within +the heap structure (selected by defining \f(CW\*(C`EV_HEAP_CACHE_AT\*(C'\fR to \f(CW1\fR), +which uses 8\-12 bytes more per watcher and a few hundred bytes more code, +but avoids random read accesses on heap changes. This improves performance +noticeably with many (hundreds) of watchers. +.Sp +The default is \f(CW1\fR, unless \f(CW\*(C`EV_FEATURES\*(C'\fR overrides it, in which case it +will be \f(CW0\fR. +.IP "\s-1EV_VERIFY\s0" 4 +.IX Item "EV_VERIFY" +Controls how much internal verification (see \f(CW\*(C`ev_verify ()\*(C'\fR) will +be done: If set to \f(CW0\fR, no internal verification code will be compiled +in. If set to \f(CW1\fR, then verification code will be compiled in, but not +called. If set to \f(CW2\fR, then the internal verification code will be +called once per loop, which can slow down libev. If set to \f(CW3\fR, then the +verification code will be called very frequently, which will slow down +libev considerably. +.Sp +The default is \f(CW1\fR, unless \f(CW\*(C`EV_FEATURES\*(C'\fR overrides it, in which case it +will be \f(CW0\fR. +.IP "\s-1EV_COMMON\s0" 4 +.IX Item "EV_COMMON" +By default, all watchers have a \f(CW\*(C`void *data\*(C'\fR member. By redefining +this macro to something else you can include more and other types of +members. You have to define it each time you include one of the files, +though, and it must be identical each time. +.Sp +For example, the perl \s-1EV\s0 module uses something like this: +.Sp +.Vb 3 +\& #define EV_COMMON \e +\& SV *self; /* contains this struct */ \e +\& SV *cb_sv, *fh /* note no trailing ";" */ +.Ve +.IP "\s-1EV_CB_DECLARE \s0(type)" 4 +.IX Item "EV_CB_DECLARE (type)" +.PD 0 +.IP "\s-1EV_CB_INVOKE \s0(watcher, revents)" 4 +.IX Item "EV_CB_INVOKE (watcher, revents)" +.IP "ev_set_cb (ev, cb)" 4 +.IX Item "ev_set_cb (ev, cb)" +.PD +Can be used to change the callback member declaration in each watcher, +and the way callbacks are invoked and set. Must expand to a struct member +definition and a statement, respectively. See the \fIev.h\fR header file for +their default definitions. One possible use for overriding these is to +avoid the \f(CW\*(C`struct ev_loop *\*(C'\fR as first argument in all cases, or to use +method calls instead of plain function calls in \*(C+. +.SS "\s-1EXPORTED API SYMBOLS\s0" +.IX Subsection "EXPORTED API SYMBOLS" +If you need to re-export the \s-1API \s0(e.g. via a \s-1DLL\s0) and you need a list of +exported symbols, you can use the provided \fISymbol.*\fR files which list +all public symbols, one per line: +.PP +.Vb 2 +\& Symbols.ev for libev proper +\& Symbols.event for the libevent emulation +.Ve +.PP +This can also be used to rename all public symbols to avoid clashes with +multiple versions of libev linked together (which is obviously bad in +itself, but sometimes it is inconvenient to avoid this). +.PP +A sed command like this will create wrapper \f(CW\*(C`#define\*(C'\fR's that you need to +include before including \fIev.h\fR: +.PP +.Vb 1 +\& wrap.h +.Ve +.PP +This would create a file \fIwrap.h\fR which essentially looks like this: +.PP +.Vb 4 +\& #define ev_backend myprefix_ev_backend +\& #define ev_check_start myprefix_ev_check_start +\& #define ev_check_stop myprefix_ev_check_stop +\& ... +.Ve +.SS "\s-1EXAMPLES\s0" +.IX Subsection "EXAMPLES" +For a real-world example of a program the includes libev +verbatim, you can have a look at the \s-1EV\s0 perl module +(). It has the libev files in +the \fIlibev/\fR subdirectory and includes them in the \fI\s-1EV/EVAPI\s0.h\fR (public +interface) and \fI\s-1EV\s0.xs\fR (implementation) files. Only the \fI\s-1EV\s0.xs\fR file +will be compiled. It is pretty complex because it provides its own header +file. +.PP +The usage in rxvt-unicode is simpler. It has a \fIev_cpp.h\fR header file +that everybody includes and which overrides some configure choices: +.PP +.Vb 8 +\& #define EV_FEATURES 8 +\& #define EV_USE_SELECT 1 +\& #define EV_PREPARE_ENABLE 1 +\& #define EV_IDLE_ENABLE 1 +\& #define EV_SIGNAL_ENABLE 1 +\& #define EV_CHILD_ENABLE 1 +\& #define EV_USE_STDEXCEPT 0 +\& #define EV_CONFIG_H +\& +\& #include "ev++.h" +.Ve +.PP +And a \fIev_cpp.C\fR implementation file that contains libev proper and is compiled: +.PP +.Vb 2 +\& #include "ev_cpp.h" +\& #include "ev.c" +.Ve +.SH "INTERACTION WITH OTHER PROGRAMS, LIBRARIES OR THE ENVIRONMENT" +.IX Header "INTERACTION WITH OTHER PROGRAMS, LIBRARIES OR THE ENVIRONMENT" +.SS "\s-1THREADS AND COROUTINES\s0" +.IX Subsection "THREADS AND COROUTINES" +\fI\s-1THREADS\s0\fR +.IX Subsection "THREADS" +.PP +All libev functions are reentrant and thread-safe unless explicitly +documented otherwise, but libev implements no locking itself. This means +that you can use as many loops as you want in parallel, as long as there +are no concurrent calls into any libev function with the same loop +parameter (\f(CW\*(C`ev_default_*\*(C'\fR calls have an implicit default loop parameter, +of course): libev guarantees that different event loops share no data +structures that need any locking. +.PP +Or to put it differently: calls with different loop parameters can be done +concurrently from multiple threads, calls with the same loop parameter +must be done serially (but can be done from different threads, as long as +only one thread ever is inside a call at any point in time, e.g. by using +a mutex per loop). +.PP +Specifically to support threads (and signal handlers), libev implements +so-called \f(CW\*(C`ev_async\*(C'\fR watchers, which allow some limited form of +concurrency on the same event loop, namely waking it up \*(L"from the +outside\*(R". +.PP +If you want to know which design (one loop, locking, or multiple loops +without or something else still) is best for your problem, then I cannot +help you, but here is some generic advice: +.IP "\(bu" 4 +most applications have a main thread: use the default libev loop +in that thread, or create a separate thread running only the default loop. +.Sp +This helps integrating other libraries or software modules that use libev +themselves and don't care/know about threading. +.IP "\(bu" 4 +one loop per thread is usually a good model. +.Sp +Doing this is almost never wrong, sometimes a better-performance model +exists, but it is always a good start. +.IP "\(bu" 4 +other models exist, such as the leader/follower pattern, where one +loop is handed through multiple threads in a kind of round-robin fashion. +.Sp +Choosing a model is hard \- look around, learn, know that usually you can do +better than you currently do :\-) +.IP "\(bu" 4 +often you need to talk to some other thread which blocks in the +event loop. +.Sp +\&\f(CW\*(C`ev_async\*(C'\fR watchers can be used to wake them up from other threads safely +(or from signal contexts...). +.Sp +An example use would be to communicate signals or other events that only +work in the default loop by registering the signal watcher with the +default loop and triggering an \f(CW\*(C`ev_async\*(C'\fR watcher from the default loop +watcher callback into the event loop interested in the signal. +.PP +See also \*(L"\s-1THREAD LOCKING EXAMPLE\*(R"\s0. +.PP +\fI\s-1COROUTINES\s0\fR +.IX Subsection "COROUTINES" +.PP +Libev is very accommodating to coroutines (\*(L"cooperative threads\*(R"): +libev fully supports nesting calls to its functions from different +coroutines (e.g. you can call \f(CW\*(C`ev_run\*(C'\fR on the same loop from two +different coroutines, and switch freely between both coroutines running +the loop, as long as you don't confuse yourself). The only exception is +that you must not do this from \f(CW\*(C`ev_periodic\*(C'\fR reschedule callbacks. +.PP +Care has been taken to ensure that libev does not keep local state inside +\&\f(CW\*(C`ev_run\*(C'\fR, and other calls do not usually allow for coroutine switches as +they do not call any callbacks. +.SS "\s-1COMPILER WARNINGS\s0" +.IX Subsection "COMPILER WARNINGS" +Depending on your compiler and compiler settings, you might get no or a +lot of warnings when compiling libev code. Some people are apparently +scared by this. +.PP +However, these are unavoidable for many reasons. For one, each compiler +has different warnings, and each user has different tastes regarding +warning options. \*(L"Warn-free\*(R" code therefore cannot be a goal except when +targeting a specific compiler and compiler-version. +.PP +Another reason is that some compiler warnings require elaborate +workarounds, or other changes to the code that make it less clear and less +maintainable. +.PP +And of course, some compiler warnings are just plain stupid, or simply +wrong (because they don't actually warn about the condition their message +seems to warn about). For example, certain older gcc versions had some +warnings that resulted in an extreme number of false positives. These have +been fixed, but some people still insist on making code warn-free with +such buggy versions. +.PP +While libev is written to generate as few warnings as possible, +\&\*(L"warn-free\*(R" code is not a goal, and it is recommended not to build libev +with any compiler warnings enabled unless you are prepared to cope with +them (e.g. by ignoring them). Remember that warnings are just that: +warnings, not errors, or proof of bugs. +.SS "\s-1VALGRIND\s0" +.IX Subsection "VALGRIND" +Valgrind has a special section here because it is a popular tool that is +highly useful. Unfortunately, valgrind reports are very hard to interpret. +.PP +If you think you found a bug (memory leak, uninitialised data access etc.) +in libev, then check twice: If valgrind reports something like: +.PP +.Vb 3 +\& ==2274== definitely lost: 0 bytes in 0 blocks. +\& ==2274== possibly lost: 0 bytes in 0 blocks. +\& ==2274== still reachable: 256 bytes in 1 blocks. +.Ve +.PP +Then there is no memory leak, just as memory accounted to global variables +is not a memleak \- the memory is still being referenced, and didn't leak. +.PP +Similarly, under some circumstances, valgrind might report kernel bugs +as if it were a bug in libev (e.g. in realloc or in the poll backend, +although an acceptable workaround has been found here), or it might be +confused. +.PP +Keep in mind that valgrind is a very good tool, but only a tool. Don't +make it into some kind of religion. +.PP +If you are unsure about something, feel free to contact the mailing list +with the full valgrind report and an explanation on why you think this +is a bug in libev (best check the archives, too :). However, don't be +annoyed when you get a brisk \*(L"this is no bug\*(R" answer and take the chance +of learning how to interpret valgrind properly. +.PP +If you need, for some reason, empty reports from valgrind for your project +I suggest using suppression lists. +.SH "PORTABILITY NOTES" +.IX Header "PORTABILITY NOTES" +.SS "\s-1GNU/LINUX 32 BIT LIMITATIONS\s0" +.IX Subsection "GNU/LINUX 32 BIT LIMITATIONS" +GNU/Linux is the only common platform that supports 64 bit file/large file +interfaces but \fIdisables\fR them by default. +.PP +That means that libev compiled in the default environment doesn't support +files larger than 2GiB or so, which mainly affects \f(CW\*(C`ev_stat\*(C'\fR watchers. +.PP +Unfortunately, many programs try to work around this GNU/Linux issue +by enabling the large file \s-1API,\s0 which makes them incompatible with the +standard libev compiled for their system. +.PP +Likewise, libev cannot enable the large file \s-1API\s0 itself as this would +suddenly make it incompatible to the default compile time environment, +i.e. all programs not using special compile switches. +.SS "\s-1OS/X AND DARWIN BUGS\s0" +.IX Subsection "OS/X AND DARWIN BUGS" +The whole thing is a bug if you ask me \- basically any system interface +you touch is broken, whether it is locales, poll, kqueue or even the +OpenGL drivers. +.PP +\fI\f(CI\*(C`kqueue\*(C'\fI is buggy\fR +.IX Subsection "kqueue is buggy" +.PP +The kqueue syscall is broken in all known versions \- most versions support +only sockets, many support pipes. +.PP +Libev tries to work around this by not using \f(CW\*(C`kqueue\*(C'\fR by default on this +rotten platform, but of course you can still ask for it when creating a +loop \- embedding a socket-only kqueue loop into a select-based one is +probably going to work well. +.PP +\fI\f(CI\*(C`poll\*(C'\fI is buggy\fR +.IX Subsection "poll is buggy" +.PP +Instead of fixing \f(CW\*(C`kqueue\*(C'\fR, Apple replaced their (working) \f(CW\*(C`poll\*(C'\fR +implementation by something calling \f(CW\*(C`kqueue\*(C'\fR internally around the 10.5.6 +release, so now \f(CW\*(C`kqueue\*(C'\fR \fIand\fR \f(CW\*(C`poll\*(C'\fR are broken. +.PP +Libev tries to work around this by not using \f(CW\*(C`poll\*(C'\fR by default on +this rotten platform, but of course you can still ask for it when creating +a loop. +.PP +\fI\f(CI\*(C`select\*(C'\fI is buggy\fR +.IX Subsection "select is buggy" +.PP +All that's left is \f(CW\*(C`select\*(C'\fR, and of course Apple found a way to fuck this +one up as well: On \s-1OS/X, \s0\f(CW\*(C`select\*(C'\fR actively limits the number of file +descriptors you can pass in to 1024 \- your program suddenly crashes when +you use more. +.PP +There is an undocumented \*(L"workaround\*(R" for this \- defining +\&\f(CW\*(C`_DARWIN_UNLIMITED_SELECT\*(C'\fR, which libev tries to use, so select \fIshould\fR +work on \s-1OS/X.\s0 +.SS "\s-1SOLARIS PROBLEMS AND WORKAROUNDS\s0" +.IX Subsection "SOLARIS PROBLEMS AND WORKAROUNDS" +\fI\f(CI\*(C`errno\*(C'\fI reentrancy\fR +.IX Subsection "errno reentrancy" +.PP +The default compile environment on Solaris is unfortunately so +thread-unsafe that you can't even use components/libraries compiled +without \f(CW\*(C`\-D_REENTRANT\*(C'\fR in a threaded program, which, of course, isn't +defined by default. A valid, if stupid, implementation choice. +.PP +If you want to use libev in threaded environments you have to make sure +it's compiled with \f(CW\*(C`_REENTRANT\*(C'\fR defined. +.PP +\fIEvent port backend\fR +.IX Subsection "Event port backend" +.PP +The scalable event interface for Solaris is called \*(L"event +ports\*(R". Unfortunately, this mechanism is very buggy in all major +releases. If you run into high \s-1CPU\s0 usage, your program freezes or you get +a large number of spurious wakeups, make sure you have all the relevant +and latest kernel patches applied. No, I don't know which ones, but there +are multiple ones to apply, and afterwards, event ports actually work +great. +.PP +If you can't get it to work, you can try running the program by setting +the environment variable \f(CW\*(C`LIBEV_FLAGS=3\*(C'\fR to only allow \f(CW\*(C`poll\*(C'\fR and +\&\f(CW\*(C`select\*(C'\fR backends. +.SS "\s-1AIX POLL BUG\s0" +.IX Subsection "AIX POLL BUG" +\&\s-1AIX\s0 unfortunately has a broken \f(CW\*(C`poll.h\*(C'\fR header. Libev works around +this by trying to avoid the poll backend altogether (i.e. it's not even +compiled in), which normally isn't a big problem as \f(CW\*(C`select\*(C'\fR works fine +with large bitsets on \s-1AIX,\s0 and \s-1AIX\s0 is dead anyway. +.SS "\s-1WIN32 PLATFORM LIMITATIONS AND WORKAROUNDS\s0" +.IX Subsection "WIN32 PLATFORM LIMITATIONS AND WORKAROUNDS" +\fIGeneral issues\fR +.IX Subsection "General issues" +.PP +Win32 doesn't support any of the standards (e.g. \s-1POSIX\s0) that libev +requires, and its I/O model is fundamentally incompatible with the \s-1POSIX\s0 +model. Libev still offers limited functionality on this platform in +the form of the \f(CW\*(C`EVBACKEND_SELECT\*(C'\fR backend, and only supports socket +descriptors. This only applies when using Win32 natively, not when using +e.g. cygwin. Actually, it only applies to the microsofts own compilers, +as every compiler comes with a slightly differently broken/incompatible +environment. +.PP +Lifting these limitations would basically require the full +re-implementation of the I/O system. If you are into this kind of thing, +then note that glib does exactly that for you in a very portable way (note +also that glib is the slowest event library known to man). +.PP +There is no supported compilation method available on windows except +embedding it into other applications. +.PP +Sensible signal handling is officially unsupported by Microsoft \- libev +tries its best, but under most conditions, signals will simply not work. +.PP +Not a libev limitation but worth mentioning: windows apparently doesn't +accept large writes: instead of resulting in a partial write, windows will +either accept everything or return \f(CW\*(C`ENOBUFS\*(C'\fR if the buffer is too large, +so make sure you only write small amounts into your sockets (less than a +megabyte seems safe, but this apparently depends on the amount of memory +available). +.PP +Due to the many, low, and arbitrary limits on the win32 platform and +the abysmal performance of winsockets, using a large number of sockets +is not recommended (and not reasonable). If your program needs to use +more than a hundred or so sockets, then likely it needs to use a totally +different implementation for windows, as libev offers the \s-1POSIX\s0 readiness +notification model, which cannot be implemented efficiently on windows +(due to Microsoft monopoly games). +.PP +A typical way to use libev under windows is to embed it (see the embedding +section for details) and use the following \fIevwrap.h\fR header file instead +of \fIev.h\fR: +.PP +.Vb 2 +\& #define EV_STANDALONE /* keeps ev from requiring config.h */ +\& #define EV_SELECT_IS_WINSOCKET 1 /* configure libev for windows select */ +\& +\& #include "ev.h" +.Ve +.PP +And compile the following \fIevwrap.c\fR file into your project (make sure +you do \fInot\fR compile the \fIev.c\fR or any other embedded source files!): +.PP +.Vb 2 +\& #include "evwrap.h" +\& #include "ev.c" +.Ve +.PP +\fIThe winsocket \f(CI\*(C`select\*(C'\fI function\fR +.IX Subsection "The winsocket select function" +.PP +The winsocket \f(CW\*(C`select\*(C'\fR function doesn't follow \s-1POSIX\s0 in that it +requires socket \fIhandles\fR and not socket \fIfile descriptors\fR (it is +also extremely buggy). This makes select very inefficient, and also +requires a mapping from file descriptors to socket handles (the Microsoft +C runtime provides the function \f(CW\*(C`_open_osfhandle\*(C'\fR for this). See the +discussion of the \f(CW\*(C`EV_SELECT_USE_FD_SET\*(C'\fR, \f(CW\*(C`EV_SELECT_IS_WINSOCKET\*(C'\fR and +\&\f(CW\*(C`EV_FD_TO_WIN32_HANDLE\*(C'\fR preprocessor symbols for more info. +.PP +The configuration for a \*(L"naked\*(R" win32 using the Microsoft runtime +libraries and raw winsocket select is: +.PP +.Vb 2 +\& #define EV_USE_SELECT 1 +\& #define EV_SELECT_IS_WINSOCKET 1 /* forces EV_SELECT_USE_FD_SET, too */ +.Ve +.PP +Note that winsockets handling of fd sets is O(n), so you can easily get a +complexity in the O(nX) range when using win32. +.PP +\fILimited number of file descriptors\fR +.IX Subsection "Limited number of file descriptors" +.PP +Windows has numerous arbitrary (and low) limits on things. +.PP +Early versions of winsocket's select only supported waiting for a maximum +of \f(CW64\fR handles (probably owning to the fact that all windows kernels +can only wait for \f(CW64\fR things at the same time internally; Microsoft +recommends spawning a chain of threads and wait for 63 handles and the +previous thread in each. Sounds great!). +.PP +Newer versions support more handles, but you need to define \f(CW\*(C`FD_SETSIZE\*(C'\fR +to some high number (e.g. \f(CW2048\fR) before compiling the winsocket select +call (which might be in libev or elsewhere, for example, perl and many +other interpreters do their own select emulation on windows). +.PP +Another limit is the number of file descriptors in the Microsoft runtime +libraries, which by default is \f(CW64\fR (there must be a hidden \fI64\fR +fetish or something like this inside Microsoft). You can increase this +by calling \f(CW\*(C`_setmaxstdio\*(C'\fR, which can increase this limit to \f(CW2048\fR +(another arbitrary limit), but is broken in many versions of the Microsoft +runtime libraries. This might get you to about \f(CW512\fR or \f(CW2048\fR sockets +(depending on windows version and/or the phase of the moon). To get more, +you need to wrap all I/O functions and provide your own fd management, but +the cost of calling select (O(nX)) will likely make this unworkable. +.SS "\s-1PORTABILITY REQUIREMENTS\s0" +.IX Subsection "PORTABILITY REQUIREMENTS" +In addition to a working ISO-C implementation and of course the +backend-specific APIs, libev relies on a few additional extensions: +.ie n .IP """void (*)(ev_watcher_type *, int revents)"" must have compatible calling conventions regardless of ""ev_watcher_type *""." 4 +.el .IP "\f(CWvoid (*)(ev_watcher_type *, int revents)\fR must have compatible calling conventions regardless of \f(CWev_watcher_type *\fR." 4 +.IX Item "void (*)(ev_watcher_type *, int revents) must have compatible calling conventions regardless of ev_watcher_type *." +Libev assumes not only that all watcher pointers have the same internal +structure (guaranteed by \s-1POSIX\s0 but not by \s-1ISO C\s0 for example), but it also +assumes that the same (machine) code can be used to call any watcher +callback: The watcher callbacks have different type signatures, but libev +calls them using an \f(CW\*(C`ev_watcher *\*(C'\fR internally. +.IP "null pointers and integer zero are represented by 0 bytes" 4 +.IX Item "null pointers and integer zero are represented by 0 bytes" +Libev uses \f(CW\*(C`memset\*(C'\fR to initialise structs and arrays to \f(CW0\fR bytes, and +relies on this setting pointers and integers to null. +.IP "pointer accesses must be thread-atomic" 4 +.IX Item "pointer accesses must be thread-atomic" +Accessing a pointer value must be atomic, it must both be readable and +writable in one piece \- this is the case on all current architectures. +.ie n .IP """sig_atomic_t volatile"" must be thread-atomic as well" 4 +.el .IP "\f(CWsig_atomic_t volatile\fR must be thread-atomic as well" 4 +.IX Item "sig_atomic_t volatile must be thread-atomic as well" +The type \f(CW\*(C`sig_atomic_t volatile\*(C'\fR (or whatever is defined as +\&\f(CW\*(C`EV_ATOMIC_T\*(C'\fR) must be atomic with respect to accesses from different +threads. This is not part of the specification for \f(CW\*(C`sig_atomic_t\*(C'\fR, but is +believed to be sufficiently portable. +.ie n .IP """sigprocmask"" must work in a threaded environment" 4 +.el .IP "\f(CWsigprocmask\fR must work in a threaded environment" 4 +.IX Item "sigprocmask must work in a threaded environment" +Libev uses \f(CW\*(C`sigprocmask\*(C'\fR to temporarily block signals. This is not +allowed in a threaded program (\f(CW\*(C`pthread_sigmask\*(C'\fR has to be used). Typical +pthread implementations will either allow \f(CW\*(C`sigprocmask\*(C'\fR in the \*(L"main +thread\*(R" or will block signals process-wide, both behaviours would +be compatible with libev. Interaction between \f(CW\*(C`sigprocmask\*(C'\fR and +\&\f(CW\*(C`pthread_sigmask\*(C'\fR could complicate things, however. +.Sp +The most portable way to handle signals is to block signals in all threads +except the initial one, and run the signal handling loop in the initial +thread as well. +.ie n .IP """long"" must be large enough for common memory allocation sizes" 4 +.el .IP "\f(CWlong\fR must be large enough for common memory allocation sizes" 4 +.IX Item "long must be large enough for common memory allocation sizes" +To improve portability and simplify its \s-1API,\s0 libev uses \f(CW\*(C`long\*(C'\fR internally +instead of \f(CW\*(C`size_t\*(C'\fR when allocating its data structures. On non-POSIX +systems (Microsoft...) this might be unexpectedly low, but is still at +least 31 bits everywhere, which is enough for hundreds of millions of +watchers. +.ie n .IP """double"" must hold a time value in seconds with enough accuracy" 4 +.el .IP "\f(CWdouble\fR must hold a time value in seconds with enough accuracy" 4 +.IX Item "double must hold a time value in seconds with enough accuracy" +The type \f(CW\*(C`double\*(C'\fR is used to represent timestamps. It is required to +have at least 51 bits of mantissa (and 9 bits of exponent), which is +good enough for at least into the year 4000 with millisecond accuracy +(the design goal for libev). This requirement is overfulfilled by +implementations using \s-1IEEE 754,\s0 which is basically all existing ones. +.Sp +With \s-1IEEE 754\s0 doubles, you get microsecond accuracy until at least the +year 2255 (and millisecond accuracy till the year 287396 \- by then, libev +is either obsolete or somebody patched it to use \f(CW\*(C`long double\*(C'\fR or +something like that, just kidding). +.PP +If you know of other additional requirements drop me a note. +.SH "ALGORITHMIC COMPLEXITIES" +.IX Header "ALGORITHMIC COMPLEXITIES" +In this section the complexities of (many of) the algorithms used inside +libev will be documented. For complexity discussions about backends see +the documentation for \f(CW\*(C`ev_default_init\*(C'\fR. +.PP +All of the following are about amortised time: If an array needs to be +extended, libev needs to realloc and move the whole array, but this +happens asymptotically rarer with higher number of elements, so O(1) might +mean that libev does a lengthy realloc operation in rare cases, but on +average it is much faster and asymptotically approaches constant time. +.IP "Starting and stopping timer/periodic watchers: O(log skipped_other_timers)" 4 +.IX Item "Starting and stopping timer/periodic watchers: O(log skipped_other_timers)" +This means that, when you have a watcher that triggers in one hour and +there are 100 watchers that would trigger before that, then inserting will +have to skip roughly seven (\f(CW\*(C`ld 100\*(C'\fR) of these watchers. +.IP "Changing timer/periodic watchers (by autorepeat or calling again): O(log skipped_other_timers)" 4 +.IX Item "Changing timer/periodic watchers (by autorepeat or calling again): O(log skipped_other_timers)" +That means that changing a timer costs less than removing/adding them, +as only the relative motion in the event queue has to be paid for. +.IP "Starting io/check/prepare/idle/signal/child/fork/async watchers: O(1)" 4 +.IX Item "Starting io/check/prepare/idle/signal/child/fork/async watchers: O(1)" +These just add the watcher into an array or at the head of a list. +.IP "Stopping check/prepare/idle/fork/async watchers: O(1)" 4 +.IX Item "Stopping check/prepare/idle/fork/async watchers: O(1)" +.PD 0 +.IP "Stopping an io/signal/child watcher: O(number_of_watchers_for_this_(fd/signal/pid % \s-1EV_PID_HASHSIZE\s0))" 4 +.IX Item "Stopping an io/signal/child watcher: O(number_of_watchers_for_this_(fd/signal/pid % EV_PID_HASHSIZE))" +.PD +These watchers are stored in lists, so they need to be walked to find the +correct watcher to remove. The lists are usually short (you don't usually +have many watchers waiting for the same fd or signal: one is typical, two +is rare). +.IP "Finding the next timer in each loop iteration: O(1)" 4 +.IX Item "Finding the next timer in each loop iteration: O(1)" +By virtue of using a binary or 4\-heap, the next timer is always found at a +fixed position in the storage array. +.IP "Each change on a file descriptor per loop iteration: O(number_of_watchers_for_this_fd)" 4 +.IX Item "Each change on a file descriptor per loop iteration: O(number_of_watchers_for_this_fd)" +A change means an I/O watcher gets started or stopped, which requires +libev to recalculate its status (and possibly tell the kernel, depending +on backend and whether \f(CW\*(C`ev_io_set\*(C'\fR was used). +.IP "Activating one watcher (putting it into the pending state): O(1)" 4 +.IX Item "Activating one watcher (putting it into the pending state): O(1)" +.PD 0 +.IP "Priority handling: O(number_of_priorities)" 4 +.IX Item "Priority handling: O(number_of_priorities)" +.PD +Priorities are implemented by allocating some space for each +priority. When doing priority-based operations, libev usually has to +linearly search all the priorities, but starting/stopping and activating +watchers becomes O(1) with respect to priority handling. +.IP "Sending an ev_async: O(1)" 4 +.IX Item "Sending an ev_async: O(1)" +.PD 0 +.IP "Processing ev_async_send: O(number_of_async_watchers)" 4 +.IX Item "Processing ev_async_send: O(number_of_async_watchers)" +.IP "Processing signals: O(max_signal_number)" 4 +.IX Item "Processing signals: O(max_signal_number)" +.PD +Sending involves a system call \fIiff\fR there were no other \f(CW\*(C`ev_async_send\*(C'\fR +calls in the current loop iteration and the loop is currently +blocked. Checking for async and signal events involves iterating over all +running async watchers or all signal numbers. +.SH "PORTING FROM LIBEV 3.X TO 4.X" +.IX Header "PORTING FROM LIBEV 3.X TO 4.X" +The major version 4 introduced some incompatible changes to the \s-1API.\s0 +.PP +At the moment, the \f(CW\*(C`ev.h\*(C'\fR header file provides compatibility definitions +for all changes, so most programs should still compile. The compatibility +layer might be removed in later versions of libev, so better update to the +new \s-1API\s0 early than late. +.ie n .IP """EV_COMPAT3"" backwards compatibility mechanism" 4 +.el .IP "\f(CWEV_COMPAT3\fR backwards compatibility mechanism" 4 +.IX Item "EV_COMPAT3 backwards compatibility mechanism" +The backward compatibility mechanism can be controlled by +\&\f(CW\*(C`EV_COMPAT3\*(C'\fR. See \*(L"\s-1PREPROCESSOR SYMBOLS/MACROS\*(R"\s0 in the \*(L"\s-1EMBEDDING\*(R"\s0 +section. +.ie n .IP """ev_default_destroy"" and ""ev_default_fork"" have been removed" 4 +.el .IP "\f(CWev_default_destroy\fR and \f(CWev_default_fork\fR have been removed" 4 +.IX Item "ev_default_destroy and ev_default_fork have been removed" +These calls can be replaced easily by their \f(CW\*(C`ev_loop_xxx\*(C'\fR counterparts: +.Sp +.Vb 2 +\& ev_loop_destroy (EV_DEFAULT_UC); +\& ev_loop_fork (EV_DEFAULT); +.Ve +.IP "function/symbol renames" 4 +.IX Item "function/symbol renames" +A number of functions and symbols have been renamed: +.Sp +.Vb 3 +\& ev_loop => ev_run +\& EVLOOP_NONBLOCK => EVRUN_NOWAIT +\& EVLOOP_ONESHOT => EVRUN_ONCE +\& +\& ev_unloop => ev_break +\& EVUNLOOP_CANCEL => EVBREAK_CANCEL +\& EVUNLOOP_ONE => EVBREAK_ONE +\& EVUNLOOP_ALL => EVBREAK_ALL +\& +\& EV_TIMEOUT => EV_TIMER +\& +\& ev_loop_count => ev_iteration +\& ev_loop_depth => ev_depth +\& ev_loop_verify => ev_verify +.Ve +.Sp +Most functions working on \f(CW\*(C`struct ev_loop\*(C'\fR objects don't have an +\&\f(CW\*(C`ev_loop_\*(C'\fR prefix, so it was removed; \f(CW\*(C`ev_loop\*(C'\fR, \f(CW\*(C`ev_unloop\*(C'\fR and +associated constants have been renamed to not collide with the \f(CW\*(C`struct +ev_loop\*(C'\fR anymore and \f(CW\*(C`EV_TIMER\*(C'\fR now follows the same naming scheme +as all other watcher types. Note that \f(CW\*(C`ev_loop_fork\*(C'\fR is still called +\&\f(CW\*(C`ev_loop_fork\*(C'\fR because it would otherwise clash with the \f(CW\*(C`ev_fork\*(C'\fR +typedef. +.ie n .IP """EV_MINIMAL"" mechanism replaced by ""EV_FEATURES""" 4 +.el .IP "\f(CWEV_MINIMAL\fR mechanism replaced by \f(CWEV_FEATURES\fR" 4 +.IX Item "EV_MINIMAL mechanism replaced by EV_FEATURES" +The preprocessor symbol \f(CW\*(C`EV_MINIMAL\*(C'\fR has been replaced by a different +mechanism, \f(CW\*(C`EV_FEATURES\*(C'\fR. Programs using \f(CW\*(C`EV_MINIMAL\*(C'\fR usually compile +and work, but the library code will of course be larger. +.SH "GLOSSARY" +.IX Header "GLOSSARY" +.IP "active" 4 +.IX Item "active" +A watcher is active as long as it has been started and not yet stopped. +See \*(L"\s-1WATCHER STATES\*(R"\s0 for details. +.IP "application" 4 +.IX Item "application" +In this document, an application is whatever is using libev. +.IP "backend" 4 +.IX Item "backend" +The part of the code dealing with the operating system interfaces. +.IP "callback" 4 +.IX Item "callback" +The address of a function that is called when some event has been +detected. Callbacks are being passed the event loop, the watcher that +received the event, and the actual event bitset. +.IP "callback/watcher invocation" 4 +.IX Item "callback/watcher invocation" +The act of calling the callback associated with a watcher. +.IP "event" 4 +.IX Item "event" +A change of state of some external event, such as data now being available +for reading on a file descriptor, time having passed or simply not having +any other events happening anymore. +.Sp +In libev, events are represented as single bits (such as \f(CW\*(C`EV_READ\*(C'\fR or +\&\f(CW\*(C`EV_TIMER\*(C'\fR). +.IP "event library" 4 +.IX Item "event library" +A software package implementing an event model and loop. +.IP "event loop" 4 +.IX Item "event loop" +An entity that handles and processes external events and converts them +into callback invocations. +.IP "event model" 4 +.IX Item "event model" +The model used to describe how an event loop handles and processes +watchers and events. +.IP "pending" 4 +.IX Item "pending" +A watcher is pending as soon as the corresponding event has been +detected. See \*(L"\s-1WATCHER STATES\*(R"\s0 for details. +.IP "real time" 4 +.IX Item "real time" +The physical time that is observed. It is apparently strictly monotonic :) +.IP "wall-clock time" 4 +.IX Item "wall-clock time" +The time and date as shown on clocks. Unlike real time, it can actually +be wrong and jump forwards and backwards, e.g. when you adjust your +clock. +.IP "watcher" 4 +.IX Item "watcher" +A data structure that describes interest in certain events. Watchers need +to be started (attached to an event loop) before they can receive events. +.SH "AUTHOR" +.IX Header "AUTHOR" +Marc Lehmann , with repeated corrections by Mikael +Magnusson and Emanuele Giaquinta, and minor corrections by many others. diff --git a/libev/ev.c b/libev/ev.c new file mode 100644 index 0000000..fe03dac --- /dev/null +++ b/libev/ev.c @@ -0,0 +1,5144 @@ +/* + * libev event processing core, watcher management + * + * Copyright (c) 2007,2008,2009,2010,2011,2012,2013 Marc Alexander Lehmann + * All rights reserved. + * + * Redistribution and use in source and binary forms, with or without modifica- + * tion, are permitted provided that the following conditions are met: + * + * 1. Redistributions of source code must retain the above copyright notice, + * this list of conditions and the following disclaimer. + * + * 2. Redistributions in binary form must reproduce the above copyright + * notice, this list of conditions and the following disclaimer in the + * documentation and/or other materials provided with the distribution. + * + * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR IMPLIED + * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MER- + * CHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO + * EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPE- + * CIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, + * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; + * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, + * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTH- + * ERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED + * OF THE POSSIBILITY OF SUCH DAMAGE. + * + * Alternatively, the contents of this file may be used under the terms of + * the GNU General Public License ("GPL") version 2 or any later version, + * in which case the provisions of the GPL are applicable instead of + * the above. If you wish to allow the use of your version of this file + * only under the terms of the GPL and not to allow others to use your + * version of this file under the BSD license, indicate your decision + * by deleting the provisions above and replace them with the notice + * and other provisions required by the GPL. If you do not delete the + * provisions above, a recipient may use your version of this file under + * either the BSD or the GPL. + */ + +/* this big block deduces configuration from config.h */ +#ifndef EV_STANDALONE +# ifdef EV_CONFIG_H +# include EV_CONFIG_H +# else +# include "config.h" +# endif + +# if HAVE_FLOOR +# ifndef EV_USE_FLOOR +# define EV_USE_FLOOR 1 +# endif +# endif + +# if HAVE_CLOCK_SYSCALL +# ifndef EV_USE_CLOCK_SYSCALL +# define EV_USE_CLOCK_SYSCALL 1 +# ifndef EV_USE_REALTIME +# define EV_USE_REALTIME 0 +# endif +# ifndef EV_USE_MONOTONIC +# define EV_USE_MONOTONIC 1 +# endif +# endif +# elif !defined EV_USE_CLOCK_SYSCALL +# define EV_USE_CLOCK_SYSCALL 0 +# endif + +# if HAVE_CLOCK_GETTIME +# ifndef EV_USE_MONOTONIC +# define EV_USE_MONOTONIC 1 +# endif +# ifndef EV_USE_REALTIME +# define EV_USE_REALTIME 0 +# endif +# else +# ifndef EV_USE_MONOTONIC +# define EV_USE_MONOTONIC 0 +# endif +# ifndef EV_USE_REALTIME +# define EV_USE_REALTIME 0 +# endif +# endif + +# if HAVE_NANOSLEEP +# ifndef EV_USE_NANOSLEEP +# define EV_USE_NANOSLEEP EV_FEATURE_OS +# endif +# else +# undef EV_USE_NANOSLEEP +# define EV_USE_NANOSLEEP 0 +# endif + +# if HAVE_SELECT && HAVE_SYS_SELECT_H +# ifndef EV_USE_SELECT +# define EV_USE_SELECT EV_FEATURE_BACKENDS +# endif +# else +# undef EV_USE_SELECT +# define EV_USE_SELECT 0 +# endif + +# if HAVE_POLL && HAVE_POLL_H +# ifndef EV_USE_POLL +# define EV_USE_POLL EV_FEATURE_BACKENDS +# endif +# else +# undef EV_USE_POLL +# define EV_USE_POLL 0 +# endif + +# if HAVE_EPOLL_CTL && HAVE_SYS_EPOLL_H +# ifndef EV_USE_EPOLL +# define EV_USE_EPOLL EV_FEATURE_BACKENDS +# endif +# else +# undef EV_USE_EPOLL +# define EV_USE_EPOLL 0 +# endif + +# if HAVE_KQUEUE && HAVE_SYS_EVENT_H +# ifndef EV_USE_KQUEUE +# define EV_USE_KQUEUE EV_FEATURE_BACKENDS +# endif +# else +# undef EV_USE_KQUEUE +# define EV_USE_KQUEUE 0 +# endif + +# if HAVE_PORT_H && HAVE_PORT_CREATE +# ifndef EV_USE_PORT +# define EV_USE_PORT EV_FEATURE_BACKENDS +# endif +# else +# undef EV_USE_PORT +# define EV_USE_PORT 0 +# endif + +# if HAVE_INOTIFY_INIT && HAVE_SYS_INOTIFY_H +# ifndef EV_USE_INOTIFY +# define EV_USE_INOTIFY EV_FEATURE_OS +# endif +# else +# undef EV_USE_INOTIFY +# define EV_USE_INOTIFY 0 +# endif + +# if HAVE_SIGNALFD && HAVE_SYS_SIGNALFD_H +# ifndef EV_USE_SIGNALFD +# define EV_USE_SIGNALFD EV_FEATURE_OS +# endif +# else +# undef EV_USE_SIGNALFD +# define EV_USE_SIGNALFD 0 +# endif + +# if HAVE_EVENTFD +# ifndef EV_USE_EVENTFD +# define EV_USE_EVENTFD EV_FEATURE_OS +# endif +# else +# undef EV_USE_EVENTFD +# define EV_USE_EVENTFD 0 +# endif + +#endif + +#include +#include +#include +#include + +#include + +#include +#include +#include +#include +#include + +#include + +#ifdef EV_H +# include EV_H +#else +# include "ev.h" +#endif + +#if EV_NO_THREADS +# undef EV_NO_SMP +# define EV_NO_SMP 1 +# undef ECB_NO_THREADS +# define ECB_NO_THREADS 1 +#endif +#if EV_NO_SMP +# undef EV_NO_SMP +# define ECB_NO_SMP 1 +#endif + +#ifndef _WIN32 +# include +# include +# include +#else +# include +# define WIN32_LEAN_AND_MEAN +# include +# include +# ifndef EV_SELECT_IS_WINSOCKET +# define EV_SELECT_IS_WINSOCKET 1 +# endif +# undef EV_AVOID_STDIO +#endif + +/* OS X, in its infinite idiocy, actually HARDCODES + * a limit of 1024 into their select. Where people have brains, + * OS X engineers apparently have a vacuum. Or maybe they were + * ordered to have a vacuum, or they do anything for money. + * This might help. Or not. + */ +#define _DARWIN_UNLIMITED_SELECT 1 + +/* this block tries to deduce configuration from header-defined symbols and defaults */ + +/* try to deduce the maximum number of signals on this platform */ +#if defined EV_NSIG +/* use what's provided */ +#elif defined NSIG +# define EV_NSIG (NSIG) +#elif defined _NSIG +# define EV_NSIG (_NSIG) +#elif defined SIGMAX +# define EV_NSIG (SIGMAX+1) +#elif defined SIG_MAX +# define EV_NSIG (SIG_MAX+1) +#elif defined _SIG_MAX +# define EV_NSIG (_SIG_MAX+1) +#elif defined MAXSIG +# define EV_NSIG (MAXSIG+1) +#elif defined MAX_SIG +# define EV_NSIG (MAX_SIG+1) +#elif defined SIGARRAYSIZE +# define EV_NSIG (SIGARRAYSIZE) /* Assume ary[SIGARRAYSIZE] */ +#elif defined _sys_nsig +# define EV_NSIG (_sys_nsig) /* Solaris 2.5 */ +#else +# define EV_NSIG (8 * sizeof (sigset_t) + 1) +#endif + +#ifndef EV_USE_FLOOR +# define EV_USE_FLOOR 0 +#endif + +#ifndef EV_USE_CLOCK_SYSCALL +# if __linux && __GLIBC__ == 2 && __GLIBC_MINOR__ < 17 +# define EV_USE_CLOCK_SYSCALL EV_FEATURE_OS +# else +# define EV_USE_CLOCK_SYSCALL 0 +# endif +#endif + +#if !(_POSIX_TIMERS > 0) +# ifndef EV_USE_MONOTONIC +# define EV_USE_MONOTONIC 0 +# endif +# ifndef EV_USE_REALTIME +# define EV_USE_REALTIME 0 +# endif +#endif + +#ifndef EV_USE_MONOTONIC +# if defined _POSIX_MONOTONIC_CLOCK && _POSIX_MONOTONIC_CLOCK >= 0 +# define EV_USE_MONOTONIC EV_FEATURE_OS +# else +# define EV_USE_MONOTONIC 0 +# endif +#endif + +#ifndef EV_USE_REALTIME +# define EV_USE_REALTIME !EV_USE_CLOCK_SYSCALL +#endif + +#ifndef EV_USE_NANOSLEEP +# if _POSIX_C_SOURCE >= 199309L +# define EV_USE_NANOSLEEP EV_FEATURE_OS +# else +# define EV_USE_NANOSLEEP 0 +# endif +#endif + +#ifndef EV_USE_SELECT +# define EV_USE_SELECT EV_FEATURE_BACKENDS +#endif + +#ifndef EV_USE_POLL +# ifdef _WIN32 +# define EV_USE_POLL 0 +# else +# define EV_USE_POLL EV_FEATURE_BACKENDS +# endif +#endif + +#ifndef EV_USE_EPOLL +# if __linux && (__GLIBC__ > 2 || (__GLIBC__ == 2 && __GLIBC_MINOR__ >= 4)) +# define EV_USE_EPOLL EV_FEATURE_BACKENDS +# else +# define EV_USE_EPOLL 0 +# endif +#endif + +#ifndef EV_USE_KQUEUE +# define EV_USE_KQUEUE 0 +#endif + +#ifndef EV_USE_PORT +# define EV_USE_PORT 0 +#endif + +#ifndef EV_USE_INOTIFY +# if __linux && (__GLIBC__ > 2 || (__GLIBC__ == 2 && __GLIBC_MINOR__ >= 4)) +# define EV_USE_INOTIFY EV_FEATURE_OS +# else +# define EV_USE_INOTIFY 0 +# endif +#endif + +#ifndef EV_PID_HASHSIZE +# define EV_PID_HASHSIZE EV_FEATURE_DATA ? 16 : 1 +#endif + +#ifndef EV_INOTIFY_HASHSIZE +# define EV_INOTIFY_HASHSIZE EV_FEATURE_DATA ? 16 : 1 +#endif + +#ifndef EV_USE_EVENTFD +# if __linux && (__GLIBC__ > 2 || (__GLIBC__ == 2 && __GLIBC_MINOR__ >= 7)) +# define EV_USE_EVENTFD EV_FEATURE_OS +# else +# define EV_USE_EVENTFD 0 +# endif +#endif + +#ifndef EV_USE_SIGNALFD +# if __linux && (__GLIBC__ > 2 || (__GLIBC__ == 2 && __GLIBC_MINOR__ >= 7)) +# define EV_USE_SIGNALFD EV_FEATURE_OS +# else +# define EV_USE_SIGNALFD 0 +# endif +#endif + +#if 0 /* debugging */ +# define EV_VERIFY 3 +# define EV_USE_4HEAP 1 +# define EV_HEAP_CACHE_AT 1 +#endif + +#ifndef EV_VERIFY +# define EV_VERIFY (EV_FEATURE_API ? 1 : 0) +#endif + +#ifndef EV_USE_4HEAP +# define EV_USE_4HEAP EV_FEATURE_DATA +#endif + +#ifndef EV_HEAP_CACHE_AT +# define EV_HEAP_CACHE_AT EV_FEATURE_DATA +#endif + +#ifdef __ANDROID__ +/* supposedly, android doesn't typedef fd_mask */ +# undef EV_USE_SELECT +# define EV_USE_SELECT 0 +/* supposedly, we need to include syscall.h, not sys/syscall.h, so just disable */ +# undef EV_USE_CLOCK_SYSCALL +# define EV_USE_CLOCK_SYSCALL 0 +#endif + +/* aix's poll.h seems to cause lots of trouble */ +#ifdef _AIX +/* AIX has a completely broken poll.h header */ +# undef EV_USE_POLL +# define EV_USE_POLL 0 +#endif + +/* on linux, we can use a (slow) syscall to avoid a dependency on pthread, */ +/* which makes programs even slower. might work on other unices, too. */ +#if EV_USE_CLOCK_SYSCALL +# include +# ifdef SYS_clock_gettime +# define clock_gettime(id, ts) syscall (SYS_clock_gettime, (id), (ts)) +# undef EV_USE_MONOTONIC +# define EV_USE_MONOTONIC 1 +# else +# undef EV_USE_CLOCK_SYSCALL +# define EV_USE_CLOCK_SYSCALL 0 +# endif +#endif + +/* this block fixes any misconfiguration where we know we run into trouble otherwise */ + +#ifndef CLOCK_MONOTONIC +# undef EV_USE_MONOTONIC +# define EV_USE_MONOTONIC 0 +#endif + +#ifndef CLOCK_REALTIME +# undef EV_USE_REALTIME +# define EV_USE_REALTIME 0 +#endif + +#if !EV_STAT_ENABLE +# undef EV_USE_INOTIFY +# define EV_USE_INOTIFY 0 +#endif + +#if !EV_USE_NANOSLEEP +/* hp-ux has it in sys/time.h, which we unconditionally include above */ +# if !defined _WIN32 && !defined __hpux +# include +# endif +#endif + +#if EV_USE_INOTIFY +# include +# include +/* some very old inotify.h headers don't have IN_DONT_FOLLOW */ +# ifndef IN_DONT_FOLLOW +# undef EV_USE_INOTIFY +# define EV_USE_INOTIFY 0 +# endif +#endif + +#if EV_USE_EVENTFD +/* our minimum requirement is glibc 2.7 which has the stub, but not the header */ +# include +# ifndef EFD_NONBLOCK +# define EFD_NONBLOCK O_NONBLOCK +# endif +# ifndef EFD_CLOEXEC +# ifdef O_CLOEXEC +# define EFD_CLOEXEC O_CLOEXEC +# else +# define EFD_CLOEXEC 02000000 +# endif +# endif +EV_CPP(extern "C") int (eventfd) (unsigned int initval, int flags); +#endif + +#if EV_USE_SIGNALFD +/* our minimum requirement is glibc 2.7 which has the stub, but not the header */ +# include +# ifndef SFD_NONBLOCK +# define SFD_NONBLOCK O_NONBLOCK +# endif +# ifndef SFD_CLOEXEC +# ifdef O_CLOEXEC +# define SFD_CLOEXEC O_CLOEXEC +# else +# define SFD_CLOEXEC 02000000 +# endif +# endif +EV_CPP (extern "C") int signalfd (int fd, const sigset_t *mask, int flags); + +struct signalfd_siginfo +{ + uint32_t ssi_signo; + char pad[128 - sizeof (uint32_t)]; +}; +#endif + +/**/ + +#if EV_VERIFY >= 3 +# define EV_FREQUENT_CHECK ev_verify (EV_A) +#else +# define EV_FREQUENT_CHECK do { } while (0) +#endif + +/* + * This is used to work around floating point rounding problems. + * This value is good at least till the year 4000. + */ +#define MIN_INTERVAL 0.0001220703125 /* 1/2**13, good till 4000 */ +/*#define MIN_INTERVAL 0.00000095367431640625 /* 1/2**20, good till 2200 */ + +#define MIN_TIMEJUMP 1. /* minimum timejump that gets detected (if monotonic clock available) */ +#define MAX_BLOCKTIME 59.743 /* never wait longer than this time (to detect time jumps) */ + +#define EV_TV_SET(tv,t) do { tv.tv_sec = (long)t; tv.tv_usec = (long)((t - tv.tv_sec) * 1e6); } while (0) +#define EV_TS_SET(ts,t) do { ts.tv_sec = (long)t; ts.tv_nsec = (long)((t - ts.tv_sec) * 1e9); } while (0) + +/* the following is ecb.h embedded into libev - use update_ev_c to update from an external copy */ +/* ECB.H BEGIN */ +/* + * libecb - http://software.schmorp.de/pkg/libecb + * + * Copyright (©) 2009-2015 Marc Alexander Lehmann + * Copyright (©) 2011 Emanuele Giaquinta + * All rights reserved. + * + * Redistribution and use in source and binary forms, with or without modifica- + * tion, are permitted provided that the following conditions are met: + * + * 1. Redistributions of source code must retain the above copyright notice, + * this list of conditions and the following disclaimer. + * + * 2. Redistributions in binary form must reproduce the above copyright + * notice, this list of conditions and the following disclaimer in the + * documentation and/or other materials provided with the distribution. + * + * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR IMPLIED + * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MER- + * CHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO + * EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPE- + * CIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, + * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; + * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, + * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTH- + * ERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED + * OF THE POSSIBILITY OF SUCH DAMAGE. + * + * Alternatively, the contents of this file may be used under the terms of + * the GNU General Public License ("GPL") version 2 or any later version, + * in which case the provisions of the GPL are applicable instead of + * the above. If you wish to allow the use of your version of this file + * only under the terms of the GPL and not to allow others to use your + * version of this file under the BSD license, indicate your decision + * by deleting the provisions above and replace them with the notice + * and other provisions required by the GPL. If you do not delete the + * provisions above, a recipient may use your version of this file under + * either the BSD or the GPL. + */ + +#ifndef ECB_H +#define ECB_H + +/* 16 bits major, 16 bits minor */ +#define ECB_VERSION 0x00010005 + +#ifdef _WIN32 + typedef signed char int8_t; + typedef unsigned char uint8_t; + typedef signed short int16_t; + typedef unsigned short uint16_t; + typedef signed int int32_t; + typedef unsigned int uint32_t; + #if __GNUC__ + typedef signed long long int64_t; + typedef unsigned long long uint64_t; + #else /* _MSC_VER || __BORLANDC__ */ + typedef signed __int64 int64_t; + typedef unsigned __int64 uint64_t; + #endif + #ifdef _WIN64 + #define ECB_PTRSIZE 8 + typedef uint64_t uintptr_t; + typedef int64_t intptr_t; + #else + #define ECB_PTRSIZE 4 + typedef uint32_t uintptr_t; + typedef int32_t intptr_t; + #endif +#else + #include + #if (defined INTPTR_MAX ? INTPTR_MAX : ULONG_MAX) > 0xffffffffU + #define ECB_PTRSIZE 8 + #else + #define ECB_PTRSIZE 4 + #endif +#endif + +#define ECB_GCC_AMD64 (__amd64 || __amd64__ || __x86_64 || __x86_64__) +#define ECB_MSVC_AMD64 (_M_AMD64 || _M_X64) + +/* work around x32 idiocy by defining proper macros */ +#if ECB_GCC_AMD64 || ECB_MSVC_AMD64 + #if _ILP32 + #define ECB_AMD64_X32 1 + #else + #define ECB_AMD64 1 + #endif +#endif + +/* many compilers define _GNUC_ to some versions but then only implement + * what their idiot authors think are the "more important" extensions, + * causing enormous grief in return for some better fake benchmark numbers. + * or so. + * we try to detect these and simply assume they are not gcc - if they have + * an issue with that they should have done it right in the first place. + */ +#if !defined __GNUC_MINOR__ || defined __INTEL_COMPILER || defined __SUNPRO_C || defined __SUNPRO_CC || defined __llvm__ || defined __clang__ + #define ECB_GCC_VERSION(major,minor) 0 +#else + #define ECB_GCC_VERSION(major,minor) (__GNUC__ > (major) || (__GNUC__ == (major) && __GNUC_MINOR__ >= (minor))) +#endif + +#define ECB_CLANG_VERSION(major,minor) (__clang_major__ > (major) || (__clang_major__ == (major) && __clang_minor__ >= (minor))) + +#if __clang__ && defined __has_builtin + #define ECB_CLANG_BUILTIN(x) __has_builtin (x) +#else + #define ECB_CLANG_BUILTIN(x) 0 +#endif + +#if __clang__ && defined __has_extension + #define ECB_CLANG_EXTENSION(x) __has_extension (x) +#else + #define ECB_CLANG_EXTENSION(x) 0 +#endif + +#define ECB_CPP (__cplusplus+0) +#define ECB_CPP11 (__cplusplus >= 201103L) + +#if ECB_CPP + #define ECB_C 0 + #define ECB_STDC_VERSION 0 +#else + #define ECB_C 1 + #define ECB_STDC_VERSION __STDC_VERSION__ +#endif + +#define ECB_C99 (ECB_STDC_VERSION >= 199901L) +#define ECB_C11 (ECB_STDC_VERSION >= 201112L) + +#if ECB_CPP + #define ECB_EXTERN_C extern "C" + #define ECB_EXTERN_C_BEG ECB_EXTERN_C { + #define ECB_EXTERN_C_END } +#else + #define ECB_EXTERN_C extern + #define ECB_EXTERN_C_BEG + #define ECB_EXTERN_C_END +#endif + +/*****************************************************************************/ + +/* ECB_NO_THREADS - ecb is not used by multiple threads, ever */ +/* ECB_NO_SMP - ecb might be used in multiple threads, but only on a single cpu */ + +#if ECB_NO_THREADS + #define ECB_NO_SMP 1 +#endif + +#if ECB_NO_SMP + #define ECB_MEMORY_FENCE do { } while (0) +#endif + +/* http://www-01.ibm.com/support/knowledgecenter/SSGH3R_13.1.0/com.ibm.xlcpp131.aix.doc/compiler_ref/compiler_builtins.html */ +#if __xlC__ && ECB_CPP + #include +#endif + +#if 1400 <= _MSC_VER + #include /* fence functions _ReadBarrier, also bit search functions _BitScanReverse */ +#endif + +#ifndef ECB_MEMORY_FENCE + #if ECB_GCC_VERSION(2,5) || defined __INTEL_COMPILER || (__llvm__ && __GNUC__) || __SUNPRO_C >= 0x5110 || __SUNPRO_CC >= 0x5110 + #if __i386 || __i386__ + #define ECB_MEMORY_FENCE __asm__ __volatile__ ("lock; orb $0, -1(%%esp)" : : : "memory") + #define ECB_MEMORY_FENCE_ACQUIRE __asm__ __volatile__ ("" : : : "memory") + #define ECB_MEMORY_FENCE_RELEASE __asm__ __volatile__ ("") + #elif ECB_GCC_AMD64 + #define ECB_MEMORY_FENCE __asm__ __volatile__ ("mfence" : : : "memory") + #define ECB_MEMORY_FENCE_ACQUIRE __asm__ __volatile__ ("" : : : "memory") + #define ECB_MEMORY_FENCE_RELEASE __asm__ __volatile__ ("") + #elif __powerpc__ || __ppc__ || __powerpc64__ || __ppc64__ + #define ECB_MEMORY_FENCE __asm__ __volatile__ ("sync" : : : "memory") + #elif defined __ARM_ARCH_2__ \ + || defined __ARM_ARCH_3__ || defined __ARM_ARCH_3M__ \ + || defined __ARM_ARCH_4__ || defined __ARM_ARCH_4T__ \ + || defined __ARM_ARCH_5__ || defined __ARM_ARCH_5E__ \ + || defined __ARM_ARCH_5T__ || defined __ARM_ARCH_5TE__ \ + || defined __ARM_ARCH_5TEJ__ + /* should not need any, unless running old code on newer cpu - arm doesn't support that */ + #elif defined __ARM_ARCH_6__ || defined __ARM_ARCH_6J__ \ + || defined __ARM_ARCH_6K__ || defined __ARM_ARCH_6ZK__ \ + || defined __ARM_ARCH_6T2__ + #define ECB_MEMORY_FENCE __asm__ __volatile__ ("mcr p15,0,%0,c7,c10,5" : : "r" (0) : "memory") + #elif defined __ARM_ARCH_7__ || defined __ARM_ARCH_7A__ \ + || defined __ARM_ARCH_7R__ || defined __ARM_ARCH_7M__ + #define ECB_MEMORY_FENCE __asm__ __volatile__ ("dmb" : : : "memory") + #elif __aarch64__ + #define ECB_MEMORY_FENCE __asm__ __volatile__ ("dmb ish" : : : "memory") + #elif (__sparc || __sparc__) && !(__sparc_v8__ || defined __sparcv8) + #define ECB_MEMORY_FENCE __asm__ __volatile__ ("membar #LoadStore | #LoadLoad | #StoreStore | #StoreLoad" : : : "memory") + #define ECB_MEMORY_FENCE_ACQUIRE __asm__ __volatile__ ("membar #LoadStore | #LoadLoad" : : : "memory") + #define ECB_MEMORY_FENCE_RELEASE __asm__ __volatile__ ("membar #LoadStore | #StoreStore") + #elif defined __s390__ || defined __s390x__ + #define ECB_MEMORY_FENCE __asm__ __volatile__ ("bcr 15,0" : : : "memory") + #elif defined __mips__ + /* GNU/Linux emulates sync on mips1 architectures, so we force its use */ + /* anybody else who still uses mips1 is supposed to send in their version, with detection code. */ + #define ECB_MEMORY_FENCE __asm__ __volatile__ (".set mips2; sync; .set mips0" : : : "memory") + #elif defined __alpha__ + #define ECB_MEMORY_FENCE __asm__ __volatile__ ("mb" : : : "memory") + #elif defined __hppa__ + #define ECB_MEMORY_FENCE __asm__ __volatile__ ("" : : : "memory") + #define ECB_MEMORY_FENCE_RELEASE __asm__ __volatile__ ("") + #elif defined __ia64__ + #define ECB_MEMORY_FENCE __asm__ __volatile__ ("mf" : : : "memory") + #elif defined __m68k__ + #define ECB_MEMORY_FENCE __asm__ __volatile__ ("" : : : "memory") + #elif defined __m88k__ + #define ECB_MEMORY_FENCE __asm__ __volatile__ ("tb1 0,%%r0,128" : : : "memory") + #elif defined __sh__ + #define ECB_MEMORY_FENCE __asm__ __volatile__ ("" : : : "memory") + #endif + #endif +#endif + +#ifndef ECB_MEMORY_FENCE + #if ECB_GCC_VERSION(4,7) + /* see comment below (stdatomic.h) about the C11 memory model. */ + #define ECB_MEMORY_FENCE __atomic_thread_fence (__ATOMIC_SEQ_CST) + #define ECB_MEMORY_FENCE_ACQUIRE __atomic_thread_fence (__ATOMIC_ACQUIRE) + #define ECB_MEMORY_FENCE_RELEASE __atomic_thread_fence (__ATOMIC_RELEASE) + + #elif ECB_CLANG_EXTENSION(c_atomic) + /* see comment below (stdatomic.h) about the C11 memory model. */ + #define ECB_MEMORY_FENCE __c11_atomic_thread_fence (__ATOMIC_SEQ_CST) + #define ECB_MEMORY_FENCE_ACQUIRE __c11_atomic_thread_fence (__ATOMIC_ACQUIRE) + #define ECB_MEMORY_FENCE_RELEASE __c11_atomic_thread_fence (__ATOMIC_RELEASE) + + #elif ECB_GCC_VERSION(4,4) || defined __INTEL_COMPILER || defined __clang__ + #define ECB_MEMORY_FENCE __sync_synchronize () + #elif _MSC_VER >= 1500 /* VC++ 2008 */ + /* apparently, microsoft broke all the memory barrier stuff in Visual Studio 2008... */ + #pragma intrinsic(_ReadBarrier,_WriteBarrier,_ReadWriteBarrier) + #define ECB_MEMORY_FENCE _ReadWriteBarrier (); MemoryBarrier() + #define ECB_MEMORY_FENCE_ACQUIRE _ReadWriteBarrier (); MemoryBarrier() /* according to msdn, _ReadBarrier is not a load fence */ + #define ECB_MEMORY_FENCE_RELEASE _WriteBarrier (); MemoryBarrier() + #elif _MSC_VER >= 1400 /* VC++ 2005 */ + #pragma intrinsic(_ReadBarrier,_WriteBarrier,_ReadWriteBarrier) + #define ECB_MEMORY_FENCE _ReadWriteBarrier () + #define ECB_MEMORY_FENCE_ACQUIRE _ReadWriteBarrier () /* according to msdn, _ReadBarrier is not a load fence */ + #define ECB_MEMORY_FENCE_RELEASE _WriteBarrier () + #elif defined _WIN32 + #include + #define ECB_MEMORY_FENCE MemoryBarrier () /* actually just xchg on x86... scary */ + #elif __SUNPRO_C >= 0x5110 || __SUNPRO_CC >= 0x5110 + #include + #define ECB_MEMORY_FENCE __machine_rw_barrier () + #define ECB_MEMORY_FENCE_ACQUIRE __machine_r_barrier () + #define ECB_MEMORY_FENCE_RELEASE __machine_w_barrier () + #elif __xlC__ + #define ECB_MEMORY_FENCE __sync () + #endif +#endif + +#ifndef ECB_MEMORY_FENCE + #if ECB_C11 && !defined __STDC_NO_ATOMICS__ + /* we assume that these memory fences work on all variables/all memory accesses, */ + /* not just C11 atomics and atomic accesses */ + #include + /* Unfortunately, neither gcc 4.7 nor clang 3.1 generate any instructions for */ + /* any fence other than seq_cst, which isn't very efficient for us. */ + /* Why that is, we don't know - either the C11 memory model is quite useless */ + /* for most usages, or gcc and clang have a bug */ + /* I *currently* lean towards the latter, and inefficiently implement */ + /* all three of ecb's fences as a seq_cst fence */ + /* Update, gcc-4.8 generates mfence for all c++ fences, but nothing */ + /* for all __atomic_thread_fence's except seq_cst */ + #define ECB_MEMORY_FENCE atomic_thread_fence (memory_order_seq_cst) + #endif +#endif + +#ifndef ECB_MEMORY_FENCE + #if !ECB_AVOID_PTHREADS + /* + * if you get undefined symbol references to pthread_mutex_lock, + * or failure to find pthread.h, then you should implement + * the ECB_MEMORY_FENCE operations for your cpu/compiler + * OR provide pthread.h and link against the posix thread library + * of your system. + */ + #include + #define ECB_NEEDS_PTHREADS 1 + #define ECB_MEMORY_FENCE_NEEDS_PTHREADS 1 + + static pthread_mutex_t ecb_mf_lock = PTHREAD_MUTEX_INITIALIZER; + #define ECB_MEMORY_FENCE do { pthread_mutex_lock (&ecb_mf_lock); pthread_mutex_unlock (&ecb_mf_lock); } while (0) + #endif +#endif + +#if !defined ECB_MEMORY_FENCE_ACQUIRE && defined ECB_MEMORY_FENCE + #define ECB_MEMORY_FENCE_ACQUIRE ECB_MEMORY_FENCE +#endif + +#if !defined ECB_MEMORY_FENCE_RELEASE && defined ECB_MEMORY_FENCE + #define ECB_MEMORY_FENCE_RELEASE ECB_MEMORY_FENCE +#endif + +/*****************************************************************************/ + +#if ECB_CPP + #define ecb_inline static inline +#elif ECB_GCC_VERSION(2,5) + #define ecb_inline static __inline__ +#elif ECB_C99 + #define ecb_inline static inline +#else + #define ecb_inline static +#endif + +#if ECB_GCC_VERSION(3,3) + #define ecb_restrict __restrict__ +#elif ECB_C99 + #define ecb_restrict restrict +#else + #define ecb_restrict +#endif + +typedef int ecb_bool; + +#define ECB_CONCAT_(a, b) a ## b +#define ECB_CONCAT(a, b) ECB_CONCAT_(a, b) +#define ECB_STRINGIFY_(a) # a +#define ECB_STRINGIFY(a) ECB_STRINGIFY_(a) +#define ECB_STRINGIFY_EXPR(expr) ((expr), ECB_STRINGIFY_ (expr)) + +#define ecb_function_ ecb_inline + +#if ECB_GCC_VERSION(3,1) || ECB_CLANG_VERSION(2,8) + #define ecb_attribute(attrlist) __attribute__ (attrlist) +#else + #define ecb_attribute(attrlist) +#endif + +#if ECB_GCC_VERSION(3,1) || ECB_CLANG_BUILTIN(__builtin_constant_p) + #define ecb_is_constant(expr) __builtin_constant_p (expr) +#else + /* possible C11 impl for integral types + typedef struct ecb_is_constant_struct ecb_is_constant_struct; + #define ecb_is_constant(expr) _Generic ((1 ? (struct ecb_is_constant_struct *)0 : (void *)((expr) - (expr)), ecb_is_constant_struct *: 0, default: 1)) */ + + #define ecb_is_constant(expr) 0 +#endif + +#if ECB_GCC_VERSION(3,1) || ECB_CLANG_BUILTIN(__builtin_expect) + #define ecb_expect(expr,value) __builtin_expect ((expr),(value)) +#else + #define ecb_expect(expr,value) (expr) +#endif + +#if ECB_GCC_VERSION(3,1) || ECB_CLANG_BUILTIN(__builtin_prefetch) + #define ecb_prefetch(addr,rw,locality) __builtin_prefetch (addr, rw, locality) +#else + #define ecb_prefetch(addr,rw,locality) +#endif + +/* no emulation for ecb_decltype */ +#if ECB_CPP11 + // older implementations might have problems with decltype(x)::type, work around it + template struct ecb_decltype_t { typedef T type; }; + #define ecb_decltype(x) ecb_decltype_t::type +#elif ECB_GCC_VERSION(3,0) || ECB_CLANG_VERSION(2,8) + #define ecb_decltype(x) __typeof__ (x) +#endif + +#if _MSC_VER >= 1300 + #define ecb_deprecated __declspec (deprecated) +#else + #define ecb_deprecated ecb_attribute ((__deprecated__)) +#endif + +#if _MSC_VER >= 1500 + #define ecb_deprecated_message(msg) __declspec (deprecated (msg)) +#elif ECB_GCC_VERSION(4,5) + #define ecb_deprecated_message(msg) ecb_attribute ((__deprecated__ (msg)) +#else + #define ecb_deprecated_message(msg) ecb_deprecated +#endif + +#if _MSC_VER >= 1400 + #define ecb_noinline __declspec (noinline) +#else + #define ecb_noinline ecb_attribute ((__noinline__)) +#endif + +#define ecb_unused ecb_attribute ((__unused__)) +#define ecb_const ecb_attribute ((__const__)) +#define ecb_pure ecb_attribute ((__pure__)) + +#if ECB_C11 || __IBMC_NORETURN + /* http://www-01.ibm.com/support/knowledgecenter/SSGH3R_13.1.0/com.ibm.xlcpp131.aix.doc/language_ref/noreturn.html */ + #define ecb_noreturn _Noreturn +#elif ECB_CPP11 + #define ecb_noreturn [[noreturn]] +#elif _MSC_VER >= 1200 + /* http://msdn.microsoft.com/en-us/library/k6ktzx3s.aspx */ + #define ecb_noreturn __declspec (noreturn) +#else + #define ecb_noreturn ecb_attribute ((__noreturn__)) +#endif + +#if ECB_GCC_VERSION(4,3) + #define ecb_artificial ecb_attribute ((__artificial__)) + #define ecb_hot ecb_attribute ((__hot__)) + #define ecb_cold ecb_attribute ((__cold__)) +#else + #define ecb_artificial + #define ecb_hot + #define ecb_cold +#endif + +/* put around conditional expressions if you are very sure that the */ +/* expression is mostly true or mostly false. note that these return */ +/* booleans, not the expression. */ +#define ecb_expect_false(expr) ecb_expect (!!(expr), 0) +#define ecb_expect_true(expr) ecb_expect (!!(expr), 1) +/* for compatibility to the rest of the world */ +#define ecb_likely(expr) ecb_expect_true (expr) +#define ecb_unlikely(expr) ecb_expect_false (expr) + +/* count trailing zero bits and count # of one bits */ +#if ECB_GCC_VERSION(3,4) \ + || (ECB_CLANG_BUILTIN(__builtin_clz) && ECB_CLANG_BUILTIN(__builtin_clzll) \ + && ECB_CLANG_BUILTIN(__builtin_ctz) && ECB_CLANG_BUILTIN(__builtin_ctzll) \ + && ECB_CLANG_BUILTIN(__builtin_popcount)) + /* we assume int == 32 bit, long == 32 or 64 bit and long long == 64 bit */ + #define ecb_ld32(x) (__builtin_clz (x) ^ 31) + #define ecb_ld64(x) (__builtin_clzll (x) ^ 63) + #define ecb_ctz32(x) __builtin_ctz (x) + #define ecb_ctz64(x) __builtin_ctzll (x) + #define ecb_popcount32(x) __builtin_popcount (x) + /* no popcountll */ +#else + ecb_function_ ecb_const int ecb_ctz32 (uint32_t x); + ecb_function_ ecb_const int + ecb_ctz32 (uint32_t x) + { +#if 1400 <= _MSC_VER && (_M_IX86 || _M_X64 || _M_IA64 || _M_ARM) + unsigned long r; + _BitScanForward (&r, x); + return (int)r; +#else + int r = 0; + + x &= ~x + 1; /* this isolates the lowest bit */ + +#if ECB_branchless_on_i386 + r += !!(x & 0xaaaaaaaa) << 0; + r += !!(x & 0xcccccccc) << 1; + r += !!(x & 0xf0f0f0f0) << 2; + r += !!(x & 0xff00ff00) << 3; + r += !!(x & 0xffff0000) << 4; +#else + if (x & 0xaaaaaaaa) r += 1; + if (x & 0xcccccccc) r += 2; + if (x & 0xf0f0f0f0) r += 4; + if (x & 0xff00ff00) r += 8; + if (x & 0xffff0000) r += 16; +#endif + + return r; +#endif + } + + ecb_function_ ecb_const int ecb_ctz64 (uint64_t x); + ecb_function_ ecb_const int + ecb_ctz64 (uint64_t x) + { +#if 1400 <= _MSC_VER && (_M_X64 || _M_IA64 || _M_ARM) + unsigned long r; + _BitScanForward64 (&r, x); + return (int)r; +#else + int shift = x & 0xffffffff ? 0 : 32; + return ecb_ctz32 (x >> shift) + shift; +#endif + } + + ecb_function_ ecb_const int ecb_popcount32 (uint32_t x); + ecb_function_ ecb_const int + ecb_popcount32 (uint32_t x) + { + x -= (x >> 1) & 0x55555555; + x = ((x >> 2) & 0x33333333) + (x & 0x33333333); + x = ((x >> 4) + x) & 0x0f0f0f0f; + x *= 0x01010101; + + return x >> 24; + } + + ecb_function_ ecb_const int ecb_ld32 (uint32_t x); + ecb_function_ ecb_const int ecb_ld32 (uint32_t x) + { +#if 1400 <= _MSC_VER && (_M_IX86 || _M_X64 || _M_IA64 || _M_ARM) + unsigned long r; + _BitScanReverse (&r, x); + return (int)r; +#else + int r = 0; + + if (x >> 16) { x >>= 16; r += 16; } + if (x >> 8) { x >>= 8; r += 8; } + if (x >> 4) { x >>= 4; r += 4; } + if (x >> 2) { x >>= 2; r += 2; } + if (x >> 1) { r += 1; } + + return r; +#endif + } + + ecb_function_ ecb_const int ecb_ld64 (uint64_t x); + ecb_function_ ecb_const int ecb_ld64 (uint64_t x) + { +#if 1400 <= _MSC_VER && (_M_X64 || _M_IA64 || _M_ARM) + unsigned long r; + _BitScanReverse64 (&r, x); + return (int)r; +#else + int r = 0; + + if (x >> 32) { x >>= 32; r += 32; } + + return r + ecb_ld32 (x); +#endif + } +#endif + +ecb_function_ ecb_const ecb_bool ecb_is_pot32 (uint32_t x); +ecb_function_ ecb_const ecb_bool ecb_is_pot32 (uint32_t x) { return !(x & (x - 1)); } +ecb_function_ ecb_const ecb_bool ecb_is_pot64 (uint64_t x); +ecb_function_ ecb_const ecb_bool ecb_is_pot64 (uint64_t x) { return !(x & (x - 1)); } + +ecb_function_ ecb_const uint8_t ecb_bitrev8 (uint8_t x); +ecb_function_ ecb_const uint8_t ecb_bitrev8 (uint8_t x) +{ + return ( (x * 0x0802U & 0x22110U) + | (x * 0x8020U & 0x88440U)) * 0x10101U >> 16; +} + +ecb_function_ ecb_const uint16_t ecb_bitrev16 (uint16_t x); +ecb_function_ ecb_const uint16_t ecb_bitrev16 (uint16_t x) +{ + x = ((x >> 1) & 0x5555) | ((x & 0x5555) << 1); + x = ((x >> 2) & 0x3333) | ((x & 0x3333) << 2); + x = ((x >> 4) & 0x0f0f) | ((x & 0x0f0f) << 4); + x = ( x >> 8 ) | ( x << 8); + + return x; +} + +ecb_function_ ecb_const uint32_t ecb_bitrev32 (uint32_t x); +ecb_function_ ecb_const uint32_t ecb_bitrev32 (uint32_t x) +{ + x = ((x >> 1) & 0x55555555) | ((x & 0x55555555) << 1); + x = ((x >> 2) & 0x33333333) | ((x & 0x33333333) << 2); + x = ((x >> 4) & 0x0f0f0f0f) | ((x & 0x0f0f0f0f) << 4); + x = ((x >> 8) & 0x00ff00ff) | ((x & 0x00ff00ff) << 8); + x = ( x >> 16 ) | ( x << 16); + + return x; +} + +/* popcount64 is only available on 64 bit cpus as gcc builtin */ +/* so for this version we are lazy */ +ecb_function_ ecb_const int ecb_popcount64 (uint64_t x); +ecb_function_ ecb_const int +ecb_popcount64 (uint64_t x) +{ + return ecb_popcount32 (x) + ecb_popcount32 (x >> 32); +} + +ecb_inline ecb_const uint8_t ecb_rotl8 (uint8_t x, unsigned int count); +ecb_inline ecb_const uint8_t ecb_rotr8 (uint8_t x, unsigned int count); +ecb_inline ecb_const uint16_t ecb_rotl16 (uint16_t x, unsigned int count); +ecb_inline ecb_const uint16_t ecb_rotr16 (uint16_t x, unsigned int count); +ecb_inline ecb_const uint32_t ecb_rotl32 (uint32_t x, unsigned int count); +ecb_inline ecb_const uint32_t ecb_rotr32 (uint32_t x, unsigned int count); +ecb_inline ecb_const uint64_t ecb_rotl64 (uint64_t x, unsigned int count); +ecb_inline ecb_const uint64_t ecb_rotr64 (uint64_t x, unsigned int count); + +ecb_inline ecb_const uint8_t ecb_rotl8 (uint8_t x, unsigned int count) { return (x >> ( 8 - count)) | (x << count); } +ecb_inline ecb_const uint8_t ecb_rotr8 (uint8_t x, unsigned int count) { return (x << ( 8 - count)) | (x >> count); } +ecb_inline ecb_const uint16_t ecb_rotl16 (uint16_t x, unsigned int count) { return (x >> (16 - count)) | (x << count); } +ecb_inline ecb_const uint16_t ecb_rotr16 (uint16_t x, unsigned int count) { return (x << (16 - count)) | (x >> count); } +ecb_inline ecb_const uint32_t ecb_rotl32 (uint32_t x, unsigned int count) { return (x >> (32 - count)) | (x << count); } +ecb_inline ecb_const uint32_t ecb_rotr32 (uint32_t x, unsigned int count) { return (x << (32 - count)) | (x >> count); } +ecb_inline ecb_const uint64_t ecb_rotl64 (uint64_t x, unsigned int count) { return (x >> (64 - count)) | (x << count); } +ecb_inline ecb_const uint64_t ecb_rotr64 (uint64_t x, unsigned int count) { return (x << (64 - count)) | (x >> count); } + +#if ECB_GCC_VERSION(4,3) || (ECB_CLANG_BUILTIN(__builtin_bswap32) && ECB_CLANG_BUILTIN(__builtin_bswap64)) + #if ECB_GCC_VERSION(4,8) || ECB_CLANG_BUILTIN(__builtin_bswap16) + #define ecb_bswap16(x) __builtin_bswap16 (x) + #else + #define ecb_bswap16(x) (__builtin_bswap32 (x) >> 16) + #endif + #define ecb_bswap32(x) __builtin_bswap32 (x) + #define ecb_bswap64(x) __builtin_bswap64 (x) +#elif _MSC_VER + #include + #define ecb_bswap16(x) ((uint16_t)_byteswap_ushort ((uint16_t)(x))) + #define ecb_bswap32(x) ((uint32_t)_byteswap_ulong ((uint32_t)(x))) + #define ecb_bswap64(x) ((uint64_t)_byteswap_uint64 ((uint64_t)(x))) +#else + ecb_function_ ecb_const uint16_t ecb_bswap16 (uint16_t x); + ecb_function_ ecb_const uint16_t + ecb_bswap16 (uint16_t x) + { + return ecb_rotl16 (x, 8); + } + + ecb_function_ ecb_const uint32_t ecb_bswap32 (uint32_t x); + ecb_function_ ecb_const uint32_t + ecb_bswap32 (uint32_t x) + { + return (((uint32_t)ecb_bswap16 (x)) << 16) | ecb_bswap16 (x >> 16); + } + + ecb_function_ ecb_const uint64_t ecb_bswap64 (uint64_t x); + ecb_function_ ecb_const uint64_t + ecb_bswap64 (uint64_t x) + { + return (((uint64_t)ecb_bswap32 (x)) << 32) | ecb_bswap32 (x >> 32); + } +#endif + +#if ECB_GCC_VERSION(4,5) || ECB_CLANG_BUILTIN(__builtin_unreachable) + #define ecb_unreachable() __builtin_unreachable () +#else + /* this seems to work fine, but gcc always emits a warning for it :/ */ + ecb_inline ecb_noreturn void ecb_unreachable (void); + ecb_inline ecb_noreturn void ecb_unreachable (void) { } +#endif + +/* try to tell the compiler that some condition is definitely true */ +#define ecb_assume(cond) if (!(cond)) ecb_unreachable (); else 0 + +ecb_inline ecb_const uint32_t ecb_byteorder_helper (void); +ecb_inline ecb_const uint32_t +ecb_byteorder_helper (void) +{ + /* the union code still generates code under pressure in gcc, */ + /* but less than using pointers, and always seems to */ + /* successfully return a constant. */ + /* the reason why we have this horrible preprocessor mess */ + /* is to avoid it in all cases, at least on common architectures */ + /* or when using a recent enough gcc version (>= 4.6) */ +#if (defined __BYTE_ORDER__ && __BYTE_ORDER__ == __ORDER_LITTLE_ENDIAN__) \ + || ((__i386 || __i386__ || _M_IX86 || ECB_GCC_AMD64 || ECB_MSVC_AMD64) && !__VOS__) + #define ECB_LITTLE_ENDIAN 1 + return 0x44332211; +#elif (defined __BYTE_ORDER__ && __BYTE_ORDER__ == __ORDER_BIG_ENDIAN__) \ + || ((__AARCH64EB__ || __MIPSEB__ || __ARMEB__) && !__VOS__) + #define ECB_BIG_ENDIAN 1 + return 0x11223344; +#else + union + { + uint8_t c[4]; + uint32_t u; + } u = { 0x11, 0x22, 0x33, 0x44 }; + return u.u; +#endif +} + +ecb_inline ecb_const ecb_bool ecb_big_endian (void); +ecb_inline ecb_const ecb_bool ecb_big_endian (void) { return ecb_byteorder_helper () == 0x11223344; } +ecb_inline ecb_const ecb_bool ecb_little_endian (void); +ecb_inline ecb_const ecb_bool ecb_little_endian (void) { return ecb_byteorder_helper () == 0x44332211; } + +#if ECB_GCC_VERSION(3,0) || ECB_C99 + #define ecb_mod(m,n) ((m) % (n) + ((m) % (n) < 0 ? (n) : 0)) +#else + #define ecb_mod(m,n) ((m) < 0 ? ((n) - 1 - ((-1 - (m)) % (n))) : ((m) % (n))) +#endif + +#if ECB_CPP + template + static inline T ecb_div_rd (T val, T div) + { + return val < 0 ? - ((-val + div - 1) / div) : (val ) / div; + } + template + static inline T ecb_div_ru (T val, T div) + { + return val < 0 ? - ((-val ) / div) : (val + div - 1) / div; + } +#else + #define ecb_div_rd(val,div) ((val) < 0 ? - ((-(val) + (div) - 1) / (div)) : ((val) ) / (div)) + #define ecb_div_ru(val,div) ((val) < 0 ? - ((-(val) ) / (div)) : ((val) + (div) - 1) / (div)) +#endif + +#if ecb_cplusplus_does_not_suck + /* does not work for local types (http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2008/n2657.htm) */ + template + static inline int ecb_array_length (const T (&arr)[N]) + { + return N; + } +#else + #define ecb_array_length(name) (sizeof (name) / sizeof (name [0])) +#endif + +ecb_function_ ecb_const uint32_t ecb_binary16_to_binary32 (uint32_t x); +ecb_function_ ecb_const uint32_t +ecb_binary16_to_binary32 (uint32_t x) +{ + unsigned int s = (x & 0x8000) << (31 - 15); + int e = (x >> 10) & 0x001f; + unsigned int m = x & 0x03ff; + + if (ecb_expect_false (e == 31)) + /* infinity or NaN */ + e = 255 - (127 - 15); + else if (ecb_expect_false (!e)) + { + if (ecb_expect_true (!m)) + /* zero, handled by code below by forcing e to 0 */ + e = 0 - (127 - 15); + else + { + /* subnormal, renormalise */ + unsigned int s = 10 - ecb_ld32 (m); + + m = (m << s) & 0x3ff; /* mask implicit bit */ + e -= s - 1; + } + } + + /* e and m now are normalised, or zero, (or inf or nan) */ + e += 127 - 15; + + return s | (e << 23) | (m << (23 - 10)); +} + +ecb_function_ ecb_const uint16_t ecb_binary32_to_binary16 (uint32_t x); +ecb_function_ ecb_const uint16_t +ecb_binary32_to_binary16 (uint32_t x) +{ + unsigned int s = (x >> 16) & 0x00008000; /* sign bit, the easy part */ + unsigned int e = ((x >> 23) & 0x000000ff) - (127 - 15); /* the desired exponent */ + unsigned int m = x & 0x007fffff; + + x &= 0x7fffffff; + + /* if it's within range of binary16 normals, use fast path */ + if (ecb_expect_true (0x38800000 <= x && x <= 0x477fefff)) + { + /* mantissa round-to-even */ + m += 0x00000fff + ((m >> (23 - 10)) & 1); + + /* handle overflow */ + if (ecb_expect_false (m >= 0x00800000)) + { + m >>= 1; + e += 1; + } + + return s | (e << 10) | (m >> (23 - 10)); + } + + /* handle large numbers and infinity */ + if (ecb_expect_true (0x477fefff < x && x <= 0x7f800000)) + return s | 0x7c00; + + /* handle zero, subnormals and small numbers */ + if (ecb_expect_true (x < 0x38800000)) + { + /* zero */ + if (ecb_expect_true (!x)) + return s; + + /* handle subnormals */ + + /* too small, will be zero */ + if (e < (14 - 24)) /* might not be sharp, but is good enough */ + return s; + + m |= 0x00800000; /* make implicit bit explicit */ + + /* very tricky - we need to round to the nearest e (+10) bit value */ + { + unsigned int bits = 14 - e; + unsigned int half = (1 << (bits - 1)) - 1; + unsigned int even = (m >> bits) & 1; + + /* if this overflows, we will end up with a normalised number */ + m = (m + half + even) >> bits; + } + + return s | m; + } + + /* handle NaNs, preserve leftmost nan bits, but make sure we don't turn them into infinities */ + m >>= 13; + + return s | 0x7c00 | m | !m; +} + +/*******************************************************************************/ +/* floating point stuff, can be disabled by defining ECB_NO_LIBM */ + +/* basically, everything uses "ieee pure-endian" floating point numbers */ +/* the only noteworthy exception is ancient armle, which uses order 43218765 */ +#if 0 \ + || __i386 || __i386__ \ + || ECB_GCC_AMD64 \ + || __powerpc__ || __ppc__ || __powerpc64__ || __ppc64__ \ + || defined __s390__ || defined __s390x__ \ + || defined __mips__ \ + || defined __alpha__ \ + || defined __hppa__ \ + || defined __ia64__ \ + || defined __m68k__ \ + || defined __m88k__ \ + || defined __sh__ \ + || defined _M_IX86 || defined ECB_MSVC_AMD64 || defined _M_IA64 \ + || (defined __arm__ && (defined __ARM_EABI__ || defined __EABI__ || defined __VFP_FP__ || defined _WIN32_WCE || defined __ANDROID__)) \ + || defined __aarch64__ + #define ECB_STDFP 1 + #include /* for memcpy */ +#else + #define ECB_STDFP 0 +#endif + +#ifndef ECB_NO_LIBM + + #include /* for frexp*, ldexp*, INFINITY, NAN */ + + /* only the oldest of old doesn't have this one. solaris. */ + #ifdef INFINITY + #define ECB_INFINITY INFINITY + #else + #define ECB_INFINITY HUGE_VAL + #endif + + #ifdef NAN + #define ECB_NAN NAN + #else + #define ECB_NAN ECB_INFINITY + #endif + + #if ECB_C99 || _XOPEN_VERSION >= 600 || _POSIX_VERSION >= 200112L + #define ecb_ldexpf(x,e) ldexpf ((x), (e)) + #define ecb_frexpf(x,e) frexpf ((x), (e)) + #else + #define ecb_ldexpf(x,e) (float) ldexp ((double) (x), (e)) + #define ecb_frexpf(x,e) (float) frexp ((double) (x), (e)) + #endif + + /* convert a float to ieee single/binary32 */ + ecb_function_ ecb_const uint32_t ecb_float_to_binary32 (float x); + ecb_function_ ecb_const uint32_t + ecb_float_to_binary32 (float x) + { + uint32_t r; + + #if ECB_STDFP + memcpy (&r, &x, 4); + #else + /* slow emulation, works for anything but -0 */ + uint32_t m; + int e; + + if (x == 0e0f ) return 0x00000000U; + if (x > +3.40282346638528860e+38f) return 0x7f800000U; + if (x < -3.40282346638528860e+38f) return 0xff800000U; + if (x != x ) return 0x7fbfffffU; + + m = ecb_frexpf (x, &e) * 0x1000000U; + + r = m & 0x80000000U; + + if (r) + m = -m; + + if (e <= -126) + { + m &= 0xffffffU; + m >>= (-125 - e); + e = -126; + } + + r |= (e + 126) << 23; + r |= m & 0x7fffffU; + #endif + + return r; + } + + /* converts an ieee single/binary32 to a float */ + ecb_function_ ecb_const float ecb_binary32_to_float (uint32_t x); + ecb_function_ ecb_const float + ecb_binary32_to_float (uint32_t x) + { + float r; + + #if ECB_STDFP + memcpy (&r, &x, 4); + #else + /* emulation, only works for normals and subnormals and +0 */ + int neg = x >> 31; + int e = (x >> 23) & 0xffU; + + x &= 0x7fffffU; + + if (e) + x |= 0x800000U; + else + e = 1; + + /* we distrust ldexpf a bit and do the 2**-24 scaling by an extra multiply */ + r = ecb_ldexpf (x * (0.5f / 0x800000U), e - 126); + + r = neg ? -r : r; + #endif + + return r; + } + + /* convert a double to ieee double/binary64 */ + ecb_function_ ecb_const uint64_t ecb_double_to_binary64 (double x); + ecb_function_ ecb_const uint64_t + ecb_double_to_binary64 (double x) + { + uint64_t r; + + #if ECB_STDFP + memcpy (&r, &x, 8); + #else + /* slow emulation, works for anything but -0 */ + uint64_t m; + int e; + + if (x == 0e0 ) return 0x0000000000000000U; + if (x > +1.79769313486231470e+308) return 0x7ff0000000000000U; + if (x < -1.79769313486231470e+308) return 0xfff0000000000000U; + if (x != x ) return 0X7ff7ffffffffffffU; + + m = frexp (x, &e) * 0x20000000000000U; + + r = m & 0x8000000000000000;; + + if (r) + m = -m; + + if (e <= -1022) + { + m &= 0x1fffffffffffffU; + m >>= (-1021 - e); + e = -1022; + } + + r |= ((uint64_t)(e + 1022)) << 52; + r |= m & 0xfffffffffffffU; + #endif + + return r; + } + + /* converts an ieee double/binary64 to a double */ + ecb_function_ ecb_const double ecb_binary64_to_double (uint64_t x); + ecb_function_ ecb_const double + ecb_binary64_to_double (uint64_t x) + { + double r; + + #if ECB_STDFP + memcpy (&r, &x, 8); + #else + /* emulation, only works for normals and subnormals and +0 */ + int neg = x >> 63; + int e = (x >> 52) & 0x7ffU; + + x &= 0xfffffffffffffU; + + if (e) + x |= 0x10000000000000U; + else + e = 1; + + /* we distrust ldexp a bit and do the 2**-53 scaling by an extra multiply */ + r = ldexp (x * (0.5 / 0x10000000000000U), e - 1022); + + r = neg ? -r : r; + #endif + + return r; + } + + /* convert a float to ieee half/binary16 */ + ecb_function_ ecb_const uint16_t ecb_float_to_binary16 (float x); + ecb_function_ ecb_const uint16_t + ecb_float_to_binary16 (float x) + { + return ecb_binary32_to_binary16 (ecb_float_to_binary32 (x)); + } + + /* convert an ieee half/binary16 to float */ + ecb_function_ ecb_const float ecb_binary16_to_float (uint16_t x); + ecb_function_ ecb_const float + ecb_binary16_to_float (uint16_t x) + { + return ecb_binary32_to_float (ecb_binary16_to_binary32 (x)); + } + +#endif + +#endif + +/* ECB.H END */ + +#if ECB_MEMORY_FENCE_NEEDS_PTHREADS +/* if your architecture doesn't need memory fences, e.g. because it is + * single-cpu/core, or if you use libev in a project that doesn't use libev + * from multiple threads, then you can define ECB_AVOID_PTHREADS when compiling + * libev, in which cases the memory fences become nops. + * alternatively, you can remove this #error and link against libpthread, + * which will then provide the memory fences. + */ +# error "memory fences not defined for your architecture, please report" +#endif + +#ifndef ECB_MEMORY_FENCE +# define ECB_MEMORY_FENCE do { } while (0) +# define ECB_MEMORY_FENCE_ACQUIRE ECB_MEMORY_FENCE +# define ECB_MEMORY_FENCE_RELEASE ECB_MEMORY_FENCE +#endif + +#define expect_false(cond) ecb_expect_false (cond) +#define expect_true(cond) ecb_expect_true (cond) +#define noinline ecb_noinline + +#define inline_size ecb_inline + +#if EV_FEATURE_CODE +# define inline_speed ecb_inline +#else +# define inline_speed noinline static +#endif + +#define NUMPRI (EV_MAXPRI - EV_MINPRI + 1) + +#if EV_MINPRI == EV_MAXPRI +# define ABSPRI(w) (((W)w), 0) +#else +# define ABSPRI(w) (((W)w)->priority - EV_MINPRI) +#endif + +#define EMPTY /* required for microsofts broken pseudo-c compiler */ +#define EMPTY2(a,b) /* used to suppress some warnings */ + +typedef ev_watcher *W; +typedef ev_watcher_list *WL; +typedef ev_watcher_time *WT; + +#define ev_active(w) ((W)(w))->active +#define ev_at(w) ((WT)(w))->at + +#if EV_USE_REALTIME +/* sig_atomic_t is used to avoid per-thread variables or locking but still */ +/* giving it a reasonably high chance of working on typical architectures */ +static EV_ATOMIC_T have_realtime; /* did clock_gettime (CLOCK_REALTIME) work? */ +#endif + +#if EV_USE_MONOTONIC +static EV_ATOMIC_T have_monotonic; /* did clock_gettime (CLOCK_MONOTONIC) work? */ +#endif + +#ifndef EV_FD_TO_WIN32_HANDLE +# define EV_FD_TO_WIN32_HANDLE(fd) _get_osfhandle (fd) +#endif +#ifndef EV_WIN32_HANDLE_TO_FD +# define EV_WIN32_HANDLE_TO_FD(handle) _open_osfhandle (handle, 0) +#endif +#ifndef EV_WIN32_CLOSE_FD +# define EV_WIN32_CLOSE_FD(fd) close (fd) +#endif + +#ifdef _WIN32 +# include "ev_win32.c" +#endif + +/*****************************************************************************/ + +/* define a suitable floor function (only used by periodics atm) */ + +#if EV_USE_FLOOR +# include +# define ev_floor(v) floor (v) +#else + +#include + +/* a floor() replacement function, should be independent of ev_tstamp type */ +noinline +static ev_tstamp +ev_floor (ev_tstamp v) +{ + /* the choice of shift factor is not terribly important */ +#if FLT_RADIX != 2 /* assume FLT_RADIX == 10 */ + const ev_tstamp shift = sizeof (unsigned long) >= 8 ? 10000000000000000000. : 1000000000.; +#else + const ev_tstamp shift = sizeof (unsigned long) >= 8 ? 18446744073709551616. : 4294967296.; +#endif + + /* argument too large for an unsigned long? */ + if (expect_false (v >= shift)) + { + ev_tstamp f; + + if (v == v - 1.) + return v; /* very large number */ + + f = shift * ev_floor (v * (1. / shift)); + return f + ev_floor (v - f); + } + + /* special treatment for negative args? */ + if (expect_false (v < 0.)) + { + ev_tstamp f = -ev_floor (-v); + + return f - (f == v ? 0 : 1); + } + + /* fits into an unsigned long */ + return (unsigned long)v; +} + +#endif + +/*****************************************************************************/ + +#ifdef __linux +# include +#endif + +noinline ecb_cold +static unsigned int +ev_linux_version (void) +{ +#ifdef __linux + unsigned int v = 0; + struct utsname buf; + int i; + char *p = buf.release; + + if (uname (&buf)) + return 0; + + for (i = 3+1; --i; ) + { + unsigned int c = 0; + + for (;;) + { + if (*p >= '0' && *p <= '9') + c = c * 10 + *p++ - '0'; + else + { + p += *p == '.'; + break; + } + } + + v = (v << 8) | c; + } + + return v; +#else + return 0; +#endif +} + +/*****************************************************************************/ + +#if EV_AVOID_STDIO +noinline ecb_cold +static void +ev_printerr (const char *msg) +{ + write (STDERR_FILENO, msg, strlen (msg)); +} +#endif + +static void (*syserr_cb)(const char *msg) EV_THROW; + +ecb_cold +void +ev_set_syserr_cb (void (*cb)(const char *msg) EV_THROW) EV_THROW +{ + syserr_cb = cb; +} + +noinline ecb_cold +static void +ev_syserr (const char *msg) +{ + if (!msg) + msg = "(libev) system error"; + + if (syserr_cb) + syserr_cb (msg); + else + { +#if EV_AVOID_STDIO + ev_printerr (msg); + ev_printerr (": "); + ev_printerr (strerror (errno)); + ev_printerr ("\n"); +#else + perror (msg); +#endif + abort (); + } +} + +static void * +ev_realloc_emul (void *ptr, long size) EV_THROW +{ + /* some systems, notably openbsd and darwin, fail to properly + * implement realloc (x, 0) (as required by both ansi c-89 and + * the single unix specification, so work around them here. + * recently, also (at least) fedora and debian started breaking it, + * despite documenting it otherwise. + */ + + if (size) + return realloc (ptr, size); + + free (ptr); + return 0; +} + +static void *(*alloc)(void *ptr, long size) EV_THROW = ev_realloc_emul; + +ecb_cold +void +ev_set_allocator (void *(*cb)(void *ptr, long size) EV_THROW) EV_THROW +{ + alloc = cb; +} + +inline_speed void * +ev_realloc (void *ptr, long size) +{ + ptr = alloc (ptr, size); + + if (!ptr && size) + { +#if EV_AVOID_STDIO + ev_printerr ("(libev) memory allocation failed, aborting.\n"); +#else + fprintf (stderr, "(libev) cannot allocate %ld bytes, aborting.", size); +#endif + abort (); + } + + return ptr; +} + +#define ev_malloc(size) ev_realloc (0, (size)) +#define ev_free(ptr) ev_realloc ((ptr), 0) + +/*****************************************************************************/ + +/* set in reify when reification needed */ +#define EV_ANFD_REIFY 1 + +/* file descriptor info structure */ +typedef struct +{ + WL head; + unsigned char events; /* the events watched for */ + unsigned char reify; /* flag set when this ANFD needs reification (EV_ANFD_REIFY, EV__IOFDSET) */ + unsigned char emask; /* the epoll backend stores the actual kernel mask in here */ + unsigned char unused; +#if EV_USE_EPOLL + unsigned int egen; /* generation counter to counter epoll bugs */ +#endif +#if EV_SELECT_IS_WINSOCKET || EV_USE_IOCP + SOCKET handle; +#endif +#if EV_USE_IOCP + OVERLAPPED or, ow; +#endif +} ANFD; + +/* stores the pending event set for a given watcher */ +typedef struct +{ + W w; + int events; /* the pending event set for the given watcher */ +} ANPENDING; + +#if EV_USE_INOTIFY +/* hash table entry per inotify-id */ +typedef struct +{ + WL head; +} ANFS; +#endif + +/* Heap Entry */ +#if EV_HEAP_CACHE_AT + /* a heap element */ + typedef struct { + ev_tstamp at; + WT w; + } ANHE; + + #define ANHE_w(he) (he).w /* access watcher, read-write */ + #define ANHE_at(he) (he).at /* access cached at, read-only */ + #define ANHE_at_cache(he) (he).at = (he).w->at /* update at from watcher */ +#else + /* a heap element */ + typedef WT ANHE; + + #define ANHE_w(he) (he) + #define ANHE_at(he) (he)->at + #define ANHE_at_cache(he) +#endif + +#if EV_MULTIPLICITY + + struct ev_loop + { + ev_tstamp ev_rt_now; + #define ev_rt_now ((loop)->ev_rt_now) + #define VAR(name,decl) decl; + #include "ev_vars.h" + #undef VAR + }; + #include "ev_wrap.h" + + static struct ev_loop default_loop_struct; + EV_API_DECL struct ev_loop *ev_default_loop_ptr = 0; /* needs to be initialised to make it a definition despite extern */ + +#else + + EV_API_DECL ev_tstamp ev_rt_now = 0; /* needs to be initialised to make it a definition despite extern */ + #define VAR(name,decl) static decl; + #include "ev_vars.h" + #undef VAR + + static int ev_default_loop_ptr; + +#endif + +#if EV_FEATURE_API +# define EV_RELEASE_CB if (expect_false (release_cb)) release_cb (EV_A) +# define EV_ACQUIRE_CB if (expect_false (acquire_cb)) acquire_cb (EV_A) +# define EV_INVOKE_PENDING invoke_cb (EV_A) +#else +# define EV_RELEASE_CB (void)0 +# define EV_ACQUIRE_CB (void)0 +# define EV_INVOKE_PENDING ev_invoke_pending (EV_A) +#endif + +#define EVBREAK_RECURSE 0x80 + +/*****************************************************************************/ + +#ifndef EV_HAVE_EV_TIME +ev_tstamp +ev_time (void) EV_THROW +{ +#if EV_USE_REALTIME + if (expect_true (have_realtime)) + { + struct timespec ts; + clock_gettime (CLOCK_REALTIME, &ts); + return ts.tv_sec + ts.tv_nsec * 1e-9; + } +#endif + + struct timeval tv; + gettimeofday (&tv, 0); + return tv.tv_sec + tv.tv_usec * 1e-6; +} +#endif + +inline_size ev_tstamp +get_clock (void) +{ +#if EV_USE_MONOTONIC + if (expect_true (have_monotonic)) + { + struct timespec ts; + clock_gettime (CLOCK_MONOTONIC, &ts); + return ts.tv_sec + ts.tv_nsec * 1e-9; + } +#endif + + return ev_time (); +} + +#if EV_MULTIPLICITY +ev_tstamp +ev_now (EV_P) EV_THROW +{ + return ev_rt_now; +} +#endif + +void +ev_sleep (ev_tstamp delay) EV_THROW +{ + if (delay > 0.) + { +#if EV_USE_NANOSLEEP + struct timespec ts; + + EV_TS_SET (ts, delay); + nanosleep (&ts, 0); +#elif defined _WIN32 + Sleep ((unsigned long)(delay * 1e3)); +#else + struct timeval tv; + + /* here we rely on sys/time.h + sys/types.h + unistd.h providing select */ + /* something not guaranteed by newer posix versions, but guaranteed */ + /* by older ones */ + EV_TV_SET (tv, delay); + select (0, 0, 0, 0, &tv); +#endif + } +} + +/*****************************************************************************/ + +#define MALLOC_ROUND 4096 /* prefer to allocate in chunks of this size, must be 2**n and >> 4 longs */ + +/* find a suitable new size for the given array, */ +/* hopefully by rounding to a nice-to-malloc size */ +inline_size int +array_nextsize (int elem, int cur, int cnt) +{ + int ncur = cur + 1; + + do + ncur <<= 1; + while (cnt > ncur); + + /* if size is large, round to MALLOC_ROUND - 4 * longs to accommodate malloc overhead */ + if (elem * ncur > MALLOC_ROUND - sizeof (void *) * 4) + { + ncur *= elem; + ncur = (ncur + elem + (MALLOC_ROUND - 1) + sizeof (void *) * 4) & ~(MALLOC_ROUND - 1); + ncur = ncur - sizeof (void *) * 4; + ncur /= elem; + } + + return ncur; +} + +noinline ecb_cold +static void * +array_realloc (int elem, void *base, int *cur, int cnt) +{ + *cur = array_nextsize (elem, *cur, cnt); + return ev_realloc (base, elem * *cur); +} + +#define array_init_zero(base,count) \ + memset ((void *)(base), 0, sizeof (*(base)) * (count)) + +#define array_needsize(type,base,cur,cnt,init) \ + if (expect_false ((cnt) > (cur))) \ + { \ + ecb_unused int ocur_ = (cur); \ + (base) = (type *)array_realloc \ + (sizeof (type), (base), &(cur), (cnt)); \ + init ((base) + (ocur_), (cur) - ocur_); \ + } + +#if 0 +#define array_slim(type,stem) \ + if (stem ## max < array_roundsize (stem ## cnt >> 2)) \ + { \ + stem ## max = array_roundsize (stem ## cnt >> 1); \ + base = (type *)ev_realloc (base, sizeof (type) * (stem ## max));\ + fprintf (stderr, "slimmed down " # stem " to %d\n", stem ## max);/*D*/\ + } +#endif + +#define array_free(stem, idx) \ + ev_free (stem ## s idx); stem ## cnt idx = stem ## max idx = 0; stem ## s idx = 0 + +/*****************************************************************************/ + +/* dummy callback for pending events */ +noinline +static void +pendingcb (EV_P_ ev_prepare *w, int revents) +{ +} + +noinline +void +ev_feed_event (EV_P_ void *w, int revents) EV_THROW +{ + W w_ = (W)w; + int pri = ABSPRI (w_); + + if (expect_false (w_->pending)) + pendings [pri][w_->pending - 1].events |= revents; + else + { + w_->pending = ++pendingcnt [pri]; + array_needsize (ANPENDING, pendings [pri], pendingmax [pri], w_->pending, EMPTY2); + pendings [pri][w_->pending - 1].w = w_; + pendings [pri][w_->pending - 1].events = revents; + } + + pendingpri = NUMPRI - 1; +} + +inline_speed void +feed_reverse (EV_P_ W w) +{ + array_needsize (W, rfeeds, rfeedmax, rfeedcnt + 1, EMPTY2); + rfeeds [rfeedcnt++] = w; +} + +inline_size void +feed_reverse_done (EV_P_ int revents) +{ + do + ev_feed_event (EV_A_ rfeeds [--rfeedcnt], revents); + while (rfeedcnt); +} + +inline_speed void +queue_events (EV_P_ W *events, int eventcnt, int type) +{ + int i; + + for (i = 0; i < eventcnt; ++i) + ev_feed_event (EV_A_ events [i], type); +} + +/*****************************************************************************/ + +inline_speed void +fd_event_nocheck (EV_P_ int fd, int revents) +{ + ANFD *anfd = anfds + fd; + ev_io *w; + + for (w = (ev_io *)anfd->head; w; w = (ev_io *)((WL)w)->next) + { + int ev = w->events & revents; + + if (ev) + ev_feed_event (EV_A_ (W)w, ev); + } +} + +/* do not submit kernel events for fds that have reify set */ +/* because that means they changed while we were polling for new events */ +inline_speed void +fd_event (EV_P_ int fd, int revents) +{ + ANFD *anfd = anfds + fd; + + if (expect_true (!anfd->reify)) + fd_event_nocheck (EV_A_ fd, revents); +} + +void +ev_feed_fd_event (EV_P_ int fd, int revents) EV_THROW +{ + if (fd >= 0 && fd < anfdmax) + fd_event_nocheck (EV_A_ fd, revents); +} + +/* make sure the external fd watch events are in-sync */ +/* with the kernel/libev internal state */ +inline_size void +fd_reify (EV_P) +{ + int i; + +#if EV_SELECT_IS_WINSOCKET || EV_USE_IOCP + for (i = 0; i < fdchangecnt; ++i) + { + int fd = fdchanges [i]; + ANFD *anfd = anfds + fd; + + if (anfd->reify & EV__IOFDSET && anfd->head) + { + SOCKET handle = EV_FD_TO_WIN32_HANDLE (fd); + + if (handle != anfd->handle) + { + unsigned long arg; + + assert (("libev: only socket fds supported in this configuration", ioctlsocket (handle, FIONREAD, &arg) == 0)); + + /* handle changed, but fd didn't - we need to do it in two steps */ + backend_modify (EV_A_ fd, anfd->events, 0); + anfd->events = 0; + anfd->handle = handle; + } + } + } +#endif + + for (i = 0; i < fdchangecnt; ++i) + { + int fd = fdchanges [i]; + ANFD *anfd = anfds + fd; + ev_io *w; + + unsigned char o_events = anfd->events; + unsigned char o_reify = anfd->reify; + + anfd->reify = 0; + + /*if (expect_true (o_reify & EV_ANFD_REIFY)) probably a deoptimisation */ + { + anfd->events = 0; + + for (w = (ev_io *)anfd->head; w; w = (ev_io *)((WL)w)->next) + anfd->events |= (unsigned char)w->events; + + if (o_events != anfd->events) + o_reify = EV__IOFDSET; /* actually |= */ + } + + if (o_reify & EV__IOFDSET) + backend_modify (EV_A_ fd, o_events, anfd->events); + } + + fdchangecnt = 0; +} + +/* something about the given fd changed */ +inline_size +void +fd_change (EV_P_ int fd, int flags) +{ + unsigned char reify = anfds [fd].reify; + anfds [fd].reify |= flags; + + if (expect_true (!reify)) + { + ++fdchangecnt; + array_needsize (int, fdchanges, fdchangemax, fdchangecnt, EMPTY2); + fdchanges [fdchangecnt - 1] = fd; + } +} + +/* the given fd is invalid/unusable, so make sure it doesn't hurt us anymore */ +inline_speed ecb_cold void +fd_kill (EV_P_ int fd) +{ + ev_io *w; + + while ((w = (ev_io *)anfds [fd].head)) + { + ev_io_stop (EV_A_ w); + ev_feed_event (EV_A_ (W)w, EV_ERROR | EV_READ | EV_WRITE); + } +} + +/* check whether the given fd is actually valid, for error recovery */ +inline_size ecb_cold int +fd_valid (int fd) +{ +#ifdef _WIN32 + return EV_FD_TO_WIN32_HANDLE (fd) != -1; +#else + return fcntl (fd, F_GETFD) != -1; +#endif +} + +/* called on EBADF to verify fds */ +noinline ecb_cold +static void +fd_ebadf (EV_P) +{ + int fd; + + for (fd = 0; fd < anfdmax; ++fd) + if (anfds [fd].events) + if (!fd_valid (fd) && errno == EBADF) + fd_kill (EV_A_ fd); +} + +/* called on ENOMEM in select/poll to kill some fds and retry */ +noinline ecb_cold +static void +fd_enomem (EV_P) +{ + int fd; + + for (fd = anfdmax; fd--; ) + if (anfds [fd].events) + { + fd_kill (EV_A_ fd); + break; + } +} + +/* usually called after fork if backend needs to re-arm all fds from scratch */ +noinline +static void +fd_rearm_all (EV_P) +{ + int fd; + + for (fd = 0; fd < anfdmax; ++fd) + if (anfds [fd].events) + { + anfds [fd].events = 0; + anfds [fd].emask = 0; + fd_change (EV_A_ fd, EV__IOFDSET | EV_ANFD_REIFY); + } +} + +/* used to prepare libev internal fd's */ +/* this is not fork-safe */ +inline_speed void +fd_intern (int fd) +{ +#ifdef _WIN32 + unsigned long arg = 1; + ioctlsocket (EV_FD_TO_WIN32_HANDLE (fd), FIONBIO, &arg); +#else + fcntl (fd, F_SETFD, FD_CLOEXEC); + fcntl (fd, F_SETFL, O_NONBLOCK); +#endif +} + +/*****************************************************************************/ + +/* + * the heap functions want a real array index. array index 0 is guaranteed to not + * be in-use at any time. the first heap entry is at array [HEAP0]. DHEAP gives + * the branching factor of the d-tree. + */ + +/* + * at the moment we allow libev the luxury of two heaps, + * a small-code-size 2-heap one and a ~1.5kb larger 4-heap + * which is more cache-efficient. + * the difference is about 5% with 50000+ watchers. + */ +#if EV_USE_4HEAP + +#define DHEAP 4 +#define HEAP0 (DHEAP - 1) /* index of first element in heap */ +#define HPARENT(k) ((((k) - HEAP0 - 1) / DHEAP) + HEAP0) +#define UPHEAP_DONE(p,k) ((p) == (k)) + +/* away from the root */ +inline_speed void +downheap (ANHE *heap, int N, int k) +{ + ANHE he = heap [k]; + ANHE *E = heap + N + HEAP0; + + for (;;) + { + ev_tstamp minat; + ANHE *minpos; + ANHE *pos = heap + DHEAP * (k - HEAP0) + HEAP0 + 1; + + /* find minimum child */ + if (expect_true (pos + DHEAP - 1 < E)) + { + /* fast path */ (minpos = pos + 0), (minat = ANHE_at (*minpos)); + if ( ANHE_at (pos [1]) < minat) (minpos = pos + 1), (minat = ANHE_at (*minpos)); + if ( ANHE_at (pos [2]) < minat) (minpos = pos + 2), (minat = ANHE_at (*minpos)); + if ( ANHE_at (pos [3]) < minat) (minpos = pos + 3), (minat = ANHE_at (*minpos)); + } + else if (pos < E) + { + /* slow path */ (minpos = pos + 0), (minat = ANHE_at (*minpos)); + if (pos + 1 < E && ANHE_at (pos [1]) < minat) (minpos = pos + 1), (minat = ANHE_at (*minpos)); + if (pos + 2 < E && ANHE_at (pos [2]) < minat) (minpos = pos + 2), (minat = ANHE_at (*minpos)); + if (pos + 3 < E && ANHE_at (pos [3]) < minat) (minpos = pos + 3), (minat = ANHE_at (*minpos)); + } + else + break; + + if (ANHE_at (he) <= minat) + break; + + heap [k] = *minpos; + ev_active (ANHE_w (*minpos)) = k; + + k = minpos - heap; + } + + heap [k] = he; + ev_active (ANHE_w (he)) = k; +} + +#else /* 4HEAP */ + +#define HEAP0 1 +#define HPARENT(k) ((k) >> 1) +#define UPHEAP_DONE(p,k) (!(p)) + +/* away from the root */ +inline_speed void +downheap (ANHE *heap, int N, int k) +{ + ANHE he = heap [k]; + + for (;;) + { + int c = k << 1; + + if (c >= N + HEAP0) + break; + + c += c + 1 < N + HEAP0 && ANHE_at (heap [c]) > ANHE_at (heap [c + 1]) + ? 1 : 0; + + if (ANHE_at (he) <= ANHE_at (heap [c])) + break; + + heap [k] = heap [c]; + ev_active (ANHE_w (heap [k])) = k; + + k = c; + } + + heap [k] = he; + ev_active (ANHE_w (he)) = k; +} +#endif + +/* towards the root */ +inline_speed void +upheap (ANHE *heap, int k) +{ + ANHE he = heap [k]; + + for (;;) + { + int p = HPARENT (k); + + if (UPHEAP_DONE (p, k) || ANHE_at (heap [p]) <= ANHE_at (he)) + break; + + heap [k] = heap [p]; + ev_active (ANHE_w (heap [k])) = k; + k = p; + } + + heap [k] = he; + ev_active (ANHE_w (he)) = k; +} + +/* move an element suitably so it is in a correct place */ +inline_size void +adjustheap (ANHE *heap, int N, int k) +{ + if (k > HEAP0 && ANHE_at (heap [k]) <= ANHE_at (heap [HPARENT (k)])) + upheap (heap, k); + else + downheap (heap, N, k); +} + +/* rebuild the heap: this function is used only once and executed rarely */ +inline_size void +reheap (ANHE *heap, int N) +{ + int i; + + /* we don't use floyds algorithm, upheap is simpler and is more cache-efficient */ + /* also, this is easy to implement and correct for both 2-heaps and 4-heaps */ + for (i = 0; i < N; ++i) + upheap (heap, i + HEAP0); +} + +/*****************************************************************************/ + +/* associate signal watchers to a signal signal */ +typedef struct +{ + EV_ATOMIC_T pending; +#if EV_MULTIPLICITY + EV_P; +#endif + WL head; +} ANSIG; + +static ANSIG signals [EV_NSIG - 1]; + +/*****************************************************************************/ + +#if EV_SIGNAL_ENABLE || EV_ASYNC_ENABLE + +noinline ecb_cold +static void +evpipe_init (EV_P) +{ + if (!ev_is_active (&pipe_w)) + { + int fds [2]; + +# if EV_USE_EVENTFD + fds [0] = -1; + fds [1] = eventfd (0, EFD_NONBLOCK | EFD_CLOEXEC); + if (fds [1] < 0 && errno == EINVAL) + fds [1] = eventfd (0, 0); + + if (fds [1] < 0) +# endif + { + while (pipe (fds)) + ev_syserr ("(libev) error creating signal/async pipe"); + + fd_intern (fds [0]); + } + + evpipe [0] = fds [0]; + + if (evpipe [1] < 0) + evpipe [1] = fds [1]; /* first call, set write fd */ + else + { + /* on subsequent calls, do not change evpipe [1] */ + /* so that evpipe_write can always rely on its value. */ + /* this branch does not do anything sensible on windows, */ + /* so must not be executed on windows */ + + dup2 (fds [1], evpipe [1]); + close (fds [1]); + } + + fd_intern (evpipe [1]); + + ev_io_set (&pipe_w, evpipe [0] < 0 ? evpipe [1] : evpipe [0], EV_READ); + ev_io_start (EV_A_ &pipe_w); + ev_unref (EV_A); /* watcher should not keep loop alive */ + } +} + +inline_speed void +evpipe_write (EV_P_ EV_ATOMIC_T *flag) +{ + ECB_MEMORY_FENCE; /* push out the write before this function was called, acquire flag */ + + if (expect_true (*flag)) + return; + + *flag = 1; + ECB_MEMORY_FENCE_RELEASE; /* make sure flag is visible before the wakeup */ + + pipe_write_skipped = 1; + + ECB_MEMORY_FENCE; /* make sure pipe_write_skipped is visible before we check pipe_write_wanted */ + + if (pipe_write_wanted) + { + int old_errno; + + pipe_write_skipped = 0; + ECB_MEMORY_FENCE_RELEASE; + + old_errno = errno; /* save errno because write will clobber it */ + +#if EV_USE_EVENTFD + if (evpipe [0] < 0) + { + uint64_t counter = 1; + write (evpipe [1], &counter, sizeof (uint64_t)); + } + else +#endif + { +#ifdef _WIN32 + WSABUF buf; + DWORD sent; +// buf.buf=&buf; + buf.buf = (char *)&buf; + buf.len = 1; + WSASend (EV_FD_TO_WIN32_HANDLE (evpipe [1]), &buf, 1, &sent, 0, 0, 0); +#else + write (evpipe [1], &(evpipe [1]), 1); +#endif + } + + errno = old_errno; + } +} + +/* called whenever the libev signal pipe */ +/* got some events (signal, async) */ +static void +pipecb (EV_P_ ev_io *iow, int revents) +{ + int i; + + if (revents & EV_READ) + { +#if EV_USE_EVENTFD + if (evpipe [0] < 0) + { + uint64_t counter; + read (evpipe [1], &counter, sizeof (uint64_t)); + } + else +#endif + { + char dummy[4]; +#ifdef _WIN32 + WSABUF buf; + DWORD recvd; + DWORD flags = 0; + buf.buf = dummy; + buf.len = sizeof (dummy); + WSARecv (EV_FD_TO_WIN32_HANDLE (evpipe [0]), &buf, 1, &recvd, &flags, 0, 0); +#else + read (evpipe [0], &dummy, sizeof (dummy)); +#endif + } + } + + pipe_write_skipped = 0; + + ECB_MEMORY_FENCE; /* push out skipped, acquire flags */ + +#if EV_SIGNAL_ENABLE + if (sig_pending) + { + sig_pending = 0; + + ECB_MEMORY_FENCE; + + for (i = EV_NSIG - 1; i--; ) + if (expect_false (signals [i].pending)) + ev_feed_signal_event (EV_A_ i + 1); + } +#endif + +#if EV_ASYNC_ENABLE + if (async_pending) + { + async_pending = 0; + + ECB_MEMORY_FENCE; + + for (i = asynccnt; i--; ) + if (asyncs [i]->sent) + { + asyncs [i]->sent = 0; + ECB_MEMORY_FENCE_RELEASE; + ev_feed_event (EV_A_ asyncs [i], EV_ASYNC); + } + } +#endif +} + +/*****************************************************************************/ + +void +ev_feed_signal (int signum) EV_THROW +{ +#if EV_MULTIPLICITY + EV_P; + ECB_MEMORY_FENCE_ACQUIRE; + EV_A = signals [signum - 1].loop; + + if (!EV_A) + return; +#endif + + signals [signum - 1].pending = 1; + evpipe_write (EV_A_ &sig_pending); +} + +static void +ev_sighandler (int signum) +{ +#ifdef _WIN32 + signal (signum, ev_sighandler); +#endif + + ev_feed_signal (signum); +} + +noinline +void +ev_feed_signal_event (EV_P_ int signum) EV_THROW +{ + WL w; + + if (expect_false (signum <= 0 || signum >= EV_NSIG)) + return; + + --signum; + +#if EV_MULTIPLICITY + /* it is permissible to try to feed a signal to the wrong loop */ + /* or, likely more useful, feeding a signal nobody is waiting for */ + + if (expect_false (signals [signum].loop != EV_A)) + return; +#endif + + signals [signum].pending = 0; + ECB_MEMORY_FENCE_RELEASE; + + for (w = signals [signum].head; w; w = w->next) + ev_feed_event (EV_A_ (W)w, EV_SIGNAL); +} + +#if EV_USE_SIGNALFD +static void +sigfdcb (EV_P_ ev_io *iow, int revents) +{ + struct signalfd_siginfo si[2], *sip; /* these structs are big */ + + for (;;) + { + ssize_t res = read (sigfd, si, sizeof (si)); + + /* not ISO-C, as res might be -1, but works with SuS */ + for (sip = si; (char *)sip < (char *)si + res; ++sip) + ev_feed_signal_event (EV_A_ sip->ssi_signo); + + if (res < (ssize_t)sizeof (si)) + break; + } +} +#endif + +#endif + +/*****************************************************************************/ + +#if EV_CHILD_ENABLE +static WL childs [EV_PID_HASHSIZE]; + +static ev_signal childev; + +#ifndef WIFCONTINUED +# define WIFCONTINUED(status) 0 +#endif + +/* handle a single child status event */ +inline_speed void +child_reap (EV_P_ int chain, int pid, int status) +{ + ev_child *w; + int traced = WIFSTOPPED (status) || WIFCONTINUED (status); + + for (w = (ev_child *)childs [chain & ((EV_PID_HASHSIZE) - 1)]; w; w = (ev_child *)((WL)w)->next) + { + if ((w->pid == pid || !w->pid) + && (!traced || (w->flags & 1))) + { + ev_set_priority (w, EV_MAXPRI); /* need to do it *now*, this *must* be the same prio as the signal watcher itself */ + w->rpid = pid; + w->rstatus = status; + ev_feed_event (EV_A_ (W)w, EV_CHILD); + } + } +} + +#ifndef WCONTINUED +# define WCONTINUED 0 +#endif + +/* called on sigchld etc., calls waitpid */ +static void +childcb (EV_P_ ev_signal *sw, int revents) +{ + int pid, status; + + /* some systems define WCONTINUED but then fail to support it (linux 2.4) */ + if (0 >= (pid = waitpid (-1, &status, WNOHANG | WUNTRACED | WCONTINUED))) + if (!WCONTINUED + || errno != EINVAL + || 0 >= (pid = waitpid (-1, &status, WNOHANG | WUNTRACED))) + return; + + /* make sure we are called again until all children have been reaped */ + /* we need to do it this way so that the callback gets called before we continue */ + ev_feed_event (EV_A_ (W)sw, EV_SIGNAL); + + child_reap (EV_A_ pid, pid, status); + if ((EV_PID_HASHSIZE) > 1) + child_reap (EV_A_ 0, pid, status); /* this might trigger a watcher twice, but feed_event catches that */ +} + +#endif + +/*****************************************************************************/ + +#if EV_USE_IOCP +# include "ev_iocp.c" +#endif +#if EV_USE_PORT +# include "ev_port.c" +#endif +#if EV_USE_KQUEUE +# include "ev_kqueue.c" +#endif +#if EV_USE_EPOLL +# include "ev_epoll.c" +#endif +#if EV_USE_POLL +# include "ev_poll.c" +#endif +#if EV_USE_SELECT +# include "ev_select.c" +#endif + +ecb_cold int +ev_version_major (void) EV_THROW +{ + return EV_VERSION_MAJOR; +} + +ecb_cold int +ev_version_minor (void) EV_THROW +{ + return EV_VERSION_MINOR; +} + +/* return true if we are running with elevated privileges and should ignore env variables */ +inline_size ecb_cold int +enable_secure (void) +{ +#ifdef _WIN32 + return 0; +#else + return getuid () != geteuid () + || getgid () != getegid (); +#endif +} + +ecb_cold +unsigned int +ev_supported_backends (void) EV_THROW +{ + unsigned int flags = 0; + + if (EV_USE_PORT ) flags |= EVBACKEND_PORT; + if (EV_USE_KQUEUE) flags |= EVBACKEND_KQUEUE; + if (EV_USE_EPOLL ) flags |= EVBACKEND_EPOLL; + if (EV_USE_POLL ) flags |= EVBACKEND_POLL; + if (EV_USE_SELECT) flags |= EVBACKEND_SELECT; + + return flags; +} + +ecb_cold +unsigned int +ev_recommended_backends (void) EV_THROW +{ + unsigned int flags = ev_supported_backends (); + +#ifndef __NetBSD__ + /* kqueue is borked on everything but netbsd apparently */ + /* it usually doesn't work correctly on anything but sockets and pipes */ + flags &= ~EVBACKEND_KQUEUE; +#endif +#ifdef __APPLE__ + /* only select works correctly on that "unix-certified" platform */ + flags &= ~EVBACKEND_KQUEUE; /* horribly broken, even for sockets */ + flags &= ~EVBACKEND_POLL; /* poll is based on kqueue from 10.5 onwards */ +#endif +#ifdef __FreeBSD__ + flags &= ~EVBACKEND_POLL; /* poll return value is unusable (http://forums.freebsd.org/archive/index.php/t-10270.html) */ +#endif + + return flags; +} + +ecb_cold +unsigned int +ev_embeddable_backends (void) EV_THROW +{ + int flags = EVBACKEND_EPOLL | EVBACKEND_KQUEUE | EVBACKEND_PORT; + + /* epoll embeddability broken on all linux versions up to at least 2.6.23 */ + if (ev_linux_version () < 0x020620) /* disable it on linux < 2.6.32 */ + flags &= ~EVBACKEND_EPOLL; + + return flags; +} + +unsigned int +ev_backend (EV_P) EV_THROW +{ + return backend; +} + +#if EV_FEATURE_API +unsigned int +ev_iteration (EV_P) EV_THROW +{ + return loop_count; +} + +unsigned int +ev_depth (EV_P) EV_THROW +{ + return loop_depth; +} + +void +ev_set_io_collect_interval (EV_P_ ev_tstamp interval) EV_THROW +{ + io_blocktime = interval; +} + +void +ev_set_timeout_collect_interval (EV_P_ ev_tstamp interval) EV_THROW +{ + timeout_blocktime = interval; +} + +void +ev_set_userdata (EV_P_ void *data) EV_THROW +{ + userdata = data; +} + +void * +ev_userdata (EV_P) EV_THROW +{ + return userdata; +} + +void +ev_set_invoke_pending_cb (EV_P_ ev_loop_callback invoke_pending_cb) EV_THROW +{ + invoke_cb = invoke_pending_cb; +} + +void +ev_set_loop_release_cb (EV_P_ void (*release)(EV_P) EV_THROW, void (*acquire)(EV_P) EV_THROW) EV_THROW +{ + release_cb = release; + acquire_cb = acquire; +} +#endif + +/* initialise a loop structure, must be zero-initialised */ +noinline ecb_cold +static void +loop_init (EV_P_ unsigned int flags) EV_THROW +{ + if (!backend) + { + origflags = flags; + +#if EV_USE_REALTIME + if (!have_realtime) + { + struct timespec ts; + + if (!clock_gettime (CLOCK_REALTIME, &ts)) + have_realtime = 1; + } +#endif + +#if EV_USE_MONOTONIC + if (!have_monotonic) + { + struct timespec ts; + + if (!clock_gettime (CLOCK_MONOTONIC, &ts)) + have_monotonic = 1; + } +#endif + + /* pid check not overridable via env */ +#ifndef _WIN32 + if (flags & EVFLAG_FORKCHECK) + curpid = getpid (); +#endif + + if (!(flags & EVFLAG_NOENV) + && !enable_secure () + && getenv ("LIBEV_FLAGS")) + flags = atoi (getenv ("LIBEV_FLAGS")); + + ev_rt_now = ev_time (); + mn_now = get_clock (); + now_floor = mn_now; + rtmn_diff = ev_rt_now - mn_now; +#if EV_FEATURE_API + invoke_cb = ev_invoke_pending; +#endif + + io_blocktime = 0.; + timeout_blocktime = 0.; + backend = 0; + backend_fd = -1; + sig_pending = 0; +#if EV_ASYNC_ENABLE + async_pending = 0; +#endif + pipe_write_skipped = 0; + pipe_write_wanted = 0; + evpipe [0] = -1; + evpipe [1] = -1; +#if EV_USE_INOTIFY + fs_fd = flags & EVFLAG_NOINOTIFY ? -1 : -2; +#endif +#if EV_USE_SIGNALFD + sigfd = flags & EVFLAG_SIGNALFD ? -2 : -1; +#endif + + if (!(flags & EVBACKEND_MASK)) + flags |= ev_recommended_backends (); + +#if EV_USE_IOCP + if (!backend && (flags & EVBACKEND_IOCP )) backend = iocp_init (EV_A_ flags); +#endif +#if EV_USE_PORT + if (!backend && (flags & EVBACKEND_PORT )) backend = port_init (EV_A_ flags); +#endif +#if EV_USE_KQUEUE + if (!backend && (flags & EVBACKEND_KQUEUE)) backend = kqueue_init (EV_A_ flags); +#endif +#if EV_USE_EPOLL + if (!backend && (flags & EVBACKEND_EPOLL )) backend = epoll_init (EV_A_ flags); +#endif +#if EV_USE_POLL + if (!backend && (flags & EVBACKEND_POLL )) backend = poll_init (EV_A_ flags); +#endif +#if EV_USE_SELECT + if (!backend && (flags & EVBACKEND_SELECT)) backend = select_init (EV_A_ flags); +#endif + + ev_prepare_init (&pending_w, pendingcb); + +#if EV_SIGNAL_ENABLE || EV_ASYNC_ENABLE + ev_init (&pipe_w, pipecb); + ev_set_priority (&pipe_w, EV_MAXPRI); +#endif + } +} + +/* free up a loop structure */ +ecb_cold +void +ev_loop_destroy (EV_P) +{ + int i; + +#if EV_MULTIPLICITY + /* mimic free (0) */ + if (!EV_A) + return; +#endif + +#if EV_CLEANUP_ENABLE + /* queue cleanup watchers (and execute them) */ + if (expect_false (cleanupcnt)) + { + queue_events (EV_A_ (W *)cleanups, cleanupcnt, EV_CLEANUP); + EV_INVOKE_PENDING; + } +#endif + +#if EV_CHILD_ENABLE + if (ev_is_default_loop (EV_A) && ev_is_active (&childev)) + { + ev_ref (EV_A); /* child watcher */ + ev_signal_stop (EV_A_ &childev); + } +#endif + + if (ev_is_active (&pipe_w)) + { + /*ev_ref (EV_A);*/ + /*ev_io_stop (EV_A_ &pipe_w);*/ + + if (evpipe [0] >= 0) EV_WIN32_CLOSE_FD (evpipe [0]); + if (evpipe [1] >= 0) EV_WIN32_CLOSE_FD (evpipe [1]); + } + +#if EV_USE_SIGNALFD + if (ev_is_active (&sigfd_w)) + close (sigfd); +#endif + +#if EV_USE_INOTIFY + if (fs_fd >= 0) + close (fs_fd); +#endif + + if (backend_fd >= 0) + close (backend_fd); + +#if EV_USE_IOCP + if (backend == EVBACKEND_IOCP ) iocp_destroy (EV_A); +#endif +#if EV_USE_PORT + if (backend == EVBACKEND_PORT ) port_destroy (EV_A); +#endif +#if EV_USE_KQUEUE + if (backend == EVBACKEND_KQUEUE) kqueue_destroy (EV_A); +#endif +#if EV_USE_EPOLL + if (backend == EVBACKEND_EPOLL ) epoll_destroy (EV_A); +#endif +#if EV_USE_POLL + if (backend == EVBACKEND_POLL ) poll_destroy (EV_A); +#endif +#if EV_USE_SELECT + if (backend == EVBACKEND_SELECT) select_destroy (EV_A); +#endif + + for (i = NUMPRI; i--; ) + { + array_free (pending, [i]); +#if EV_IDLE_ENABLE + array_free (idle, [i]); +#endif + } + + ev_free (anfds); anfds = 0; anfdmax = 0; + + /* have to use the microsoft-never-gets-it-right macro */ + array_free (rfeed, EMPTY); + array_free (fdchange, EMPTY); + array_free (timer, EMPTY); +#if EV_PERIODIC_ENABLE + array_free (periodic, EMPTY); +#endif +#if EV_FORK_ENABLE + array_free (fork, EMPTY); +#endif +#if EV_CLEANUP_ENABLE + array_free (cleanup, EMPTY); +#endif + array_free (prepare, EMPTY); + array_free (check, EMPTY); +#if EV_ASYNC_ENABLE + array_free (async, EMPTY); +#endif + + backend = 0; + +#if EV_MULTIPLICITY + if (ev_is_default_loop (EV_A)) +#endif + ev_default_loop_ptr = 0; +#if EV_MULTIPLICITY + else + ev_free (EV_A); +#endif +} + +#if EV_USE_INOTIFY +inline_size void infy_fork (EV_P); +#endif + +inline_size void +loop_fork (EV_P) +{ +#if EV_USE_PORT + if (backend == EVBACKEND_PORT ) port_fork (EV_A); +#endif +#if EV_USE_KQUEUE + if (backend == EVBACKEND_KQUEUE) kqueue_fork (EV_A); +#endif +#if EV_USE_EPOLL + if (backend == EVBACKEND_EPOLL ) epoll_fork (EV_A); +#endif +#if EV_USE_INOTIFY + infy_fork (EV_A); +#endif + +#if EV_SIGNAL_ENABLE || EV_ASYNC_ENABLE + if (ev_is_active (&pipe_w) && postfork != 2) + { + /* pipe_write_wanted must be false now, so modifying fd vars should be safe */ + + ev_ref (EV_A); + ev_io_stop (EV_A_ &pipe_w); + + if (evpipe [0] >= 0) + EV_WIN32_CLOSE_FD (evpipe [0]); + + evpipe_init (EV_A); + /* iterate over everything, in case we missed something before */ + ev_feed_event (EV_A_ &pipe_w, EV_CUSTOM); + } +#endif + + postfork = 0; +} + +#if EV_MULTIPLICITY + +ecb_cold +struct ev_loop * +ev_loop_new (unsigned int flags) EV_THROW +{ + EV_P = (struct ev_loop *)ev_malloc (sizeof (struct ev_loop)); + + memset (EV_A, 0, sizeof (struct ev_loop)); + loop_init (EV_A_ flags); + + if (ev_backend (EV_A)) + return EV_A; + + ev_free (EV_A); + return 0; +} + +#endif /* multiplicity */ + +#if EV_VERIFY +noinline ecb_cold +static void +verify_watcher (EV_P_ W w) +{ + assert (("libev: watcher has invalid priority", ABSPRI (w) >= 0 && ABSPRI (w) < NUMPRI)); + + if (w->pending) + assert (("libev: pending watcher not on pending queue", pendings [ABSPRI (w)][w->pending - 1].w == w)); +} + +noinline ecb_cold +static void +verify_heap (EV_P_ ANHE *heap, int N) +{ + int i; + + for (i = HEAP0; i < N + HEAP0; ++i) + { + assert (("libev: active index mismatch in heap", ev_active (ANHE_w (heap [i])) == i)); + assert (("libev: heap condition violated", i == HEAP0 || ANHE_at (heap [HPARENT (i)]) <= ANHE_at (heap [i]))); + assert (("libev: heap at cache mismatch", ANHE_at (heap [i]) == ev_at (ANHE_w (heap [i])))); + + verify_watcher (EV_A_ (W)ANHE_w (heap [i])); + } +} + +noinline ecb_cold +static void +array_verify (EV_P_ W *ws, int cnt) +{ + while (cnt--) + { + assert (("libev: active index mismatch", ev_active (ws [cnt]) == cnt + 1)); + verify_watcher (EV_A_ ws [cnt]); + } +} +#endif + +#if EV_FEATURE_API +void ecb_cold +ev_verify (EV_P) EV_THROW +{ +#if EV_VERIFY + int i; + WL w, w2; + + assert (activecnt >= -1); + + assert (fdchangemax >= fdchangecnt); + for (i = 0; i < fdchangecnt; ++i) + assert (("libev: negative fd in fdchanges", fdchanges [i] >= 0)); + + assert (anfdmax >= 0); + for (i = 0; i < anfdmax; ++i) + { + int j = 0; + + for (w = w2 = anfds [i].head; w; w = w->next) + { + verify_watcher (EV_A_ (W)w); + + if (j++ & 1) + { + assert (("libev: io watcher list contains a loop", w != w2)); + w2 = w2->next; + } + + assert (("libev: inactive fd watcher on anfd list", ev_active (w) == 1)); + assert (("libev: fd mismatch between watcher and anfd", ((ev_io *)w)->fd == i)); + } + } + + assert (timermax >= timercnt); + verify_heap (EV_A_ timers, timercnt); + +#if EV_PERIODIC_ENABLE + assert (periodicmax >= periodiccnt); + verify_heap (EV_A_ periodics, periodiccnt); +#endif + + for (i = NUMPRI; i--; ) + { + assert (pendingmax [i] >= pendingcnt [i]); +#if EV_IDLE_ENABLE + assert (idleall >= 0); + assert (idlemax [i] >= idlecnt [i]); + array_verify (EV_A_ (W *)idles [i], idlecnt [i]); +#endif + } + +#if EV_FORK_ENABLE + assert (forkmax >= forkcnt); + array_verify (EV_A_ (W *)forks, forkcnt); +#endif + +#if EV_CLEANUP_ENABLE + assert (cleanupmax >= cleanupcnt); + array_verify (EV_A_ (W *)cleanups, cleanupcnt); +#endif + +#if EV_ASYNC_ENABLE + assert (asyncmax >= asynccnt); + array_verify (EV_A_ (W *)asyncs, asynccnt); +#endif + +#if EV_PREPARE_ENABLE + assert (preparemax >= preparecnt); + array_verify (EV_A_ (W *)prepares, preparecnt); +#endif + +#if EV_CHECK_ENABLE + assert (checkmax >= checkcnt); + array_verify (EV_A_ (W *)checks, checkcnt); +#endif + +# if 0 +#if EV_CHILD_ENABLE + for (w = (ev_child *)childs [chain & ((EV_PID_HASHSIZE) - 1)]; w; w = (ev_child *)((WL)w)->next) + for (signum = EV_NSIG; signum--; ) if (signals [signum].pending) +#endif +# endif +#endif +} +#endif + +#if EV_MULTIPLICITY +ecb_cold +struct ev_loop * +#else +int +#endif +ev_default_loop (unsigned int flags) EV_THROW +{ + if (!ev_default_loop_ptr) + { +#if EV_MULTIPLICITY + EV_P = ev_default_loop_ptr = &default_loop_struct; +#else + ev_default_loop_ptr = 1; +#endif + + loop_init (EV_A_ flags); + + if (ev_backend (EV_A)) + { +#if EV_CHILD_ENABLE + ev_signal_init (&childev, childcb, SIGCHLD); + ev_set_priority (&childev, EV_MAXPRI); + ev_signal_start (EV_A_ &childev); + ev_unref (EV_A); /* child watcher should not keep loop alive */ +#endif + } + else + ev_default_loop_ptr = 0; + } + + return ev_default_loop_ptr; +} + +void +ev_loop_fork (EV_P) EV_THROW +{ + postfork = 1; +} + +/*****************************************************************************/ + +void +ev_invoke (EV_P_ void *w, int revents) +{ + EV_CB_INVOKE ((W)w, revents); +} + +unsigned int +ev_pending_count (EV_P) EV_THROW +{ + int pri; + unsigned int count = 0; + + for (pri = NUMPRI; pri--; ) + count += pendingcnt [pri]; + + return count; +} + +noinline +void +ev_invoke_pending (EV_P) +{ + pendingpri = NUMPRI; + + while (pendingpri) /* pendingpri possibly gets modified in the inner loop */ + { + --pendingpri; + + while (pendingcnt [pendingpri]) + { + ANPENDING *p = pendings [pendingpri] + --pendingcnt [pendingpri]; + + p->w->pending = 0; + EV_CB_INVOKE (p->w, p->events); + EV_FREQUENT_CHECK; + } + } +} + +#if EV_IDLE_ENABLE +/* make idle watchers pending. this handles the "call-idle */ +/* only when higher priorities are idle" logic */ +inline_size void +idle_reify (EV_P) +{ + if (expect_false (idleall)) + { + int pri; + + for (pri = NUMPRI; pri--; ) + { + if (pendingcnt [pri]) + break; + + if (idlecnt [pri]) + { + queue_events (EV_A_ (W *)idles [pri], idlecnt [pri], EV_IDLE); + break; + } + } + } +} +#endif + +/* make timers pending */ +inline_size void +timers_reify (EV_P) +{ + EV_FREQUENT_CHECK; + + if (timercnt && ANHE_at (timers [HEAP0]) < mn_now) + { + do + { + ev_timer *w = (ev_timer *)ANHE_w (timers [HEAP0]); + + /*assert (("libev: inactive timer on timer heap detected", ev_is_active (w)));*/ + + /* first reschedule or stop timer */ + if (w->repeat) + { + ev_at (w) += w->repeat; + if (ev_at (w) < mn_now) + ev_at (w) = mn_now; + + assert (("libev: negative ev_timer repeat value found while processing timers", w->repeat > 0.)); + + ANHE_at_cache (timers [HEAP0]); + downheap (timers, timercnt, HEAP0); + } + else + ev_timer_stop (EV_A_ w); /* nonrepeating: stop timer */ + + EV_FREQUENT_CHECK; + feed_reverse (EV_A_ (W)w); + } + while (timercnt && ANHE_at (timers [HEAP0]) < mn_now); + + feed_reverse_done (EV_A_ EV_TIMER); + } +} + +#if EV_PERIODIC_ENABLE + +noinline +static void +periodic_recalc (EV_P_ ev_periodic *w) +{ + ev_tstamp interval = w->interval > MIN_INTERVAL ? w->interval : MIN_INTERVAL; + ev_tstamp at = w->offset + interval * ev_floor ((ev_rt_now - w->offset) / interval); + + /* the above almost always errs on the low side */ + while (at <= ev_rt_now) + { + ev_tstamp nat = at + w->interval; + + /* when resolution fails us, we use ev_rt_now */ + if (expect_false (nat == at)) + { + at = ev_rt_now; + break; + } + + at = nat; + } + + ev_at (w) = at; +} + +/* make periodics pending */ +inline_size void +periodics_reify (EV_P) +{ + EV_FREQUENT_CHECK; + + while (periodiccnt && ANHE_at (periodics [HEAP0]) < ev_rt_now) + { + do + { + ev_periodic *w = (ev_periodic *)ANHE_w (periodics [HEAP0]); + + /*assert (("libev: inactive timer on periodic heap detected", ev_is_active (w)));*/ + + /* first reschedule or stop timer */ + if (w->reschedule_cb) + { + ev_at (w) = w->reschedule_cb (w, ev_rt_now); + + assert (("libev: ev_periodic reschedule callback returned time in the past", ev_at (w) >= ev_rt_now)); + + ANHE_at_cache (periodics [HEAP0]); + downheap (periodics, periodiccnt, HEAP0); + } + else if (w->interval) + { + periodic_recalc (EV_A_ w); + ANHE_at_cache (periodics [HEAP0]); + downheap (periodics, periodiccnt, HEAP0); + } + else + ev_periodic_stop (EV_A_ w); /* nonrepeating: stop timer */ + + EV_FREQUENT_CHECK; + feed_reverse (EV_A_ (W)w); + } + while (periodiccnt && ANHE_at (periodics [HEAP0]) < ev_rt_now); + + feed_reverse_done (EV_A_ EV_PERIODIC); + } +} + +/* simply recalculate all periodics */ +/* TODO: maybe ensure that at least one event happens when jumping forward? */ +noinline ecb_cold +static void +periodics_reschedule (EV_P) +{ + int i; + + /* adjust periodics after time jump */ + for (i = HEAP0; i < periodiccnt + HEAP0; ++i) + { + ev_periodic *w = (ev_periodic *)ANHE_w (periodics [i]); + + if (w->reschedule_cb) + ev_at (w) = w->reschedule_cb (w, ev_rt_now); + else if (w->interval) + periodic_recalc (EV_A_ w); + + ANHE_at_cache (periodics [i]); + } + + reheap (periodics, periodiccnt); +} +#endif + +/* adjust all timers by a given offset */ +noinline ecb_cold +static void +timers_reschedule (EV_P_ ev_tstamp adjust) +{ + int i; + + for (i = 0; i < timercnt; ++i) + { + ANHE *he = timers + i + HEAP0; + ANHE_w (*he)->at += adjust; + ANHE_at_cache (*he); + } +} + +/* fetch new monotonic and realtime times from the kernel */ +/* also detect if there was a timejump, and act accordingly */ +inline_speed void +time_update (EV_P_ ev_tstamp max_block) +{ +#if EV_USE_MONOTONIC + if (expect_true (have_monotonic)) + { + int i; + ev_tstamp odiff = rtmn_diff; + + mn_now = get_clock (); + + /* only fetch the realtime clock every 0.5*MIN_TIMEJUMP seconds */ + /* interpolate in the meantime */ + if (expect_true (mn_now - now_floor < MIN_TIMEJUMP * .5)) + { + ev_rt_now = rtmn_diff + mn_now; + return; + } + + now_floor = mn_now; + ev_rt_now = ev_time (); + + /* loop a few times, before making important decisions. + * on the choice of "4": one iteration isn't enough, + * in case we get preempted during the calls to + * ev_time and get_clock. a second call is almost guaranteed + * to succeed in that case, though. and looping a few more times + * doesn't hurt either as we only do this on time-jumps or + * in the unlikely event of having been preempted here. + */ + for (i = 4; --i; ) + { + ev_tstamp diff; + rtmn_diff = ev_rt_now - mn_now; + + diff = odiff - rtmn_diff; + + if (expect_true ((diff < 0. ? -diff : diff) < MIN_TIMEJUMP)) + return; /* all is well */ + + ev_rt_now = ev_time (); + mn_now = get_clock (); + now_floor = mn_now; + } + + /* no timer adjustment, as the monotonic clock doesn't jump */ + /* timers_reschedule (EV_A_ rtmn_diff - odiff) */ +# if EV_PERIODIC_ENABLE + periodics_reschedule (EV_A); +# endif + } + else +#endif + { + ev_rt_now = ev_time (); + + if (expect_false (mn_now > ev_rt_now || ev_rt_now > mn_now + max_block + MIN_TIMEJUMP)) + { + /* adjust timers. this is easy, as the offset is the same for all of them */ + timers_reschedule (EV_A_ ev_rt_now - mn_now); +#if EV_PERIODIC_ENABLE + periodics_reschedule (EV_A); +#endif + } + + mn_now = ev_rt_now; + } +} + +int +ev_run (EV_P_ int flags) +{ +#if EV_FEATURE_API + ++loop_depth; +#endif + + assert (("libev: ev_loop recursion during release detected", loop_done != EVBREAK_RECURSE)); + + loop_done = EVBREAK_CANCEL; + + EV_INVOKE_PENDING; /* in case we recurse, ensure ordering stays nice and clean */ + + do + { +#if EV_VERIFY >= 2 + ev_verify (EV_A); +#endif + +#ifndef _WIN32 + if (expect_false (curpid)) /* penalise the forking check even more */ + if (expect_false (getpid () != curpid)) + { + curpid = getpid (); + postfork = 1; + } +#endif + +#if EV_FORK_ENABLE + /* we might have forked, so queue fork handlers */ + if (expect_false (postfork)) + if (forkcnt) + { + queue_events (EV_A_ (W *)forks, forkcnt, EV_FORK); + EV_INVOKE_PENDING; + } +#endif + +#if EV_PREPARE_ENABLE + /* queue prepare watchers (and execute them) */ + if (expect_false (preparecnt)) + { + queue_events (EV_A_ (W *)prepares, preparecnt, EV_PREPARE); + EV_INVOKE_PENDING; + } +#endif + + if (expect_false (loop_done)) + break; + + /* we might have forked, so reify kernel state if necessary */ + if (expect_false (postfork)) + loop_fork (EV_A); + + /* update fd-related kernel structures */ + fd_reify (EV_A); + + /* calculate blocking time */ + { + ev_tstamp waittime = 0.; + ev_tstamp sleeptime = 0.; + + /* remember old timestamp for io_blocktime calculation */ + ev_tstamp prev_mn_now = mn_now; + + /* update time to cancel out callback processing overhead */ + time_update (EV_A_ 1e100); + + /* from now on, we want a pipe-wake-up */ + pipe_write_wanted = 1; + + ECB_MEMORY_FENCE; /* make sure pipe_write_wanted is visible before we check for potential skips */ + + if (expect_true (!(flags & EVRUN_NOWAIT || idleall || !activecnt || pipe_write_skipped))) + { + waittime = MAX_BLOCKTIME; + + if (timercnt) + { + ev_tstamp to = ANHE_at (timers [HEAP0]) - mn_now; + if (waittime > to) waittime = to; + } + +#if EV_PERIODIC_ENABLE + if (periodiccnt) + { + ev_tstamp to = ANHE_at (periodics [HEAP0]) - ev_rt_now; + if (waittime > to) waittime = to; + } +#endif + + /* don't let timeouts decrease the waittime below timeout_blocktime */ + if (expect_false (waittime < timeout_blocktime)) + waittime = timeout_blocktime; + + /* at this point, we NEED to wait, so we have to ensure */ + /* to pass a minimum nonzero value to the backend */ + if (expect_false (waittime < backend_mintime)) + waittime = backend_mintime; + + /* extra check because io_blocktime is commonly 0 */ + if (expect_false (io_blocktime)) + { + sleeptime = io_blocktime - (mn_now - prev_mn_now); + + if (sleeptime > waittime - backend_mintime) + sleeptime = waittime - backend_mintime; + + if (expect_true (sleeptime > 0.)) + { + ev_sleep (sleeptime); + waittime -= sleeptime; + } + } + } + +#if EV_FEATURE_API + ++loop_count; +#endif + assert ((loop_done = EVBREAK_RECURSE, 1)); /* assert for side effect */ + backend_poll (EV_A_ waittime); + assert ((loop_done = EVBREAK_CANCEL, 1)); /* assert for side effect */ + + pipe_write_wanted = 0; /* just an optimisation, no fence needed */ + + ECB_MEMORY_FENCE_ACQUIRE; + if (pipe_write_skipped) + { + assert (("libev: pipe_w not active, but pipe not written", ev_is_active (&pipe_w))); + ev_feed_event (EV_A_ &pipe_w, EV_CUSTOM); + } + + + /* update ev_rt_now, do magic */ + time_update (EV_A_ waittime + sleeptime); + } + + /* queue pending timers and reschedule them */ + timers_reify (EV_A); /* relative timers called last */ +#if EV_PERIODIC_ENABLE + periodics_reify (EV_A); /* absolute timers called first */ +#endif + +#if EV_IDLE_ENABLE + /* queue idle watchers unless other events are pending */ + idle_reify (EV_A); +#endif + +#if EV_CHECK_ENABLE + /* queue check watchers, to be executed first */ + if (expect_false (checkcnt)) + queue_events (EV_A_ (W *)checks, checkcnt, EV_CHECK); +#endif + + EV_INVOKE_PENDING; + } + while (expect_true ( + activecnt + && !loop_done + && !(flags & (EVRUN_ONCE | EVRUN_NOWAIT)) + )); + + if (loop_done == EVBREAK_ONE) + loop_done = EVBREAK_CANCEL; + +#if EV_FEATURE_API + --loop_depth; +#endif + + return activecnt; +} + +void +ev_break (EV_P_ int how) EV_THROW +{ + loop_done = how; +} + +void +ev_ref (EV_P) EV_THROW +{ + ++activecnt; +} + +void +ev_unref (EV_P) EV_THROW +{ + --activecnt; +} + +void +ev_now_update (EV_P) EV_THROW +{ + time_update (EV_A_ 1e100); +} + +void +ev_suspend (EV_P) EV_THROW +{ + ev_now_update (EV_A); +} + +void +ev_resume (EV_P) EV_THROW +{ + ev_tstamp mn_prev = mn_now; + + ev_now_update (EV_A); + timers_reschedule (EV_A_ mn_now - mn_prev); +#if EV_PERIODIC_ENABLE + /* TODO: really do this? */ + periodics_reschedule (EV_A); +#endif +} + +/*****************************************************************************/ +/* singly-linked list management, used when the expected list length is short */ + +inline_size void +wlist_add (WL *head, WL elem) +{ + elem->next = *head; + *head = elem; +} + +inline_size void +wlist_del (WL *head, WL elem) +{ + while (*head) + { + if (expect_true (*head == elem)) + { + *head = elem->next; + break; + } + + head = &(*head)->next; + } +} + +/* internal, faster, version of ev_clear_pending */ +inline_speed void +clear_pending (EV_P_ W w) +{ + if (w->pending) + { + pendings [ABSPRI (w)][w->pending - 1].w = (W)&pending_w; + w->pending = 0; + } +} + +int +ev_clear_pending (EV_P_ void *w) EV_THROW +{ + W w_ = (W)w; + int pending = w_->pending; + + if (expect_true (pending)) + { + ANPENDING *p = pendings [ABSPRI (w_)] + pending - 1; + p->w = (W)&pending_w; + w_->pending = 0; + return p->events; + } + else + return 0; +} + +inline_size void +pri_adjust (EV_P_ W w) +{ + int pri = ev_priority (w); + pri = pri < EV_MINPRI ? EV_MINPRI : pri; + pri = pri > EV_MAXPRI ? EV_MAXPRI : pri; + ev_set_priority (w, pri); +} + +inline_speed void +ev_start (EV_P_ W w, int active) +{ + pri_adjust (EV_A_ w); + w->active = active; + ev_ref (EV_A); +} + +inline_size void +ev_stop (EV_P_ W w) +{ + ev_unref (EV_A); + w->active = 0; +} + +/*****************************************************************************/ + +noinline +void +ev_io_start (EV_P_ ev_io *w) EV_THROW +{ + int fd = w->fd; + + if (expect_false (ev_is_active (w))) + return; + + assert (("libev: ev_io_start called with negative fd", fd >= 0)); + assert (("libev: ev_io_start called with illegal event mask", !(w->events & ~(EV__IOFDSET | EV_READ | EV_WRITE)))); + + EV_FREQUENT_CHECK; + + ev_start (EV_A_ (W)w, 1); + array_needsize (ANFD, anfds, anfdmax, fd + 1, array_init_zero); + wlist_add (&anfds[fd].head, (WL)w); + + /* common bug, apparently */ + assert (("libev: ev_io_start called with corrupted watcher", ((WL)w)->next != (WL)w)); + + fd_change (EV_A_ fd, w->events & EV__IOFDSET | EV_ANFD_REIFY); + w->events &= ~EV__IOFDSET; + + EV_FREQUENT_CHECK; +} + +noinline +void +ev_io_stop (EV_P_ ev_io *w) EV_THROW +{ + clear_pending (EV_A_ (W)w); + if (expect_false (!ev_is_active (w))) + return; + + assert (("libev: ev_io_stop called with illegal fd (must stay constant after start!)", w->fd >= 0 && w->fd < anfdmax)); + + EV_FREQUENT_CHECK; + + wlist_del (&anfds[w->fd].head, (WL)w); + ev_stop (EV_A_ (W)w); + + fd_change (EV_A_ w->fd, EV_ANFD_REIFY); + + EV_FREQUENT_CHECK; +} + +noinline +void +ev_timer_start (EV_P_ ev_timer *w) EV_THROW +{ + if (expect_false (ev_is_active (w))) + return; + + ev_at (w) += mn_now; + + assert (("libev: ev_timer_start called with negative timer repeat value", w->repeat >= 0.)); + + EV_FREQUENT_CHECK; + + ++timercnt; + ev_start (EV_A_ (W)w, timercnt + HEAP0 - 1); + array_needsize (ANHE, timers, timermax, ev_active (w) + 1, EMPTY2); + ANHE_w (timers [ev_active (w)]) = (WT)w; + ANHE_at_cache (timers [ev_active (w)]); + upheap (timers, ev_active (w)); + + EV_FREQUENT_CHECK; + + /*assert (("libev: internal timer heap corruption", timers [ev_active (w)] == (WT)w));*/ +} + +noinline +void +ev_timer_stop (EV_P_ ev_timer *w) EV_THROW +{ + clear_pending (EV_A_ (W)w); + if (expect_false (!ev_is_active (w))) + return; + + EV_FREQUENT_CHECK; + + { + int active = ev_active (w); + + assert (("libev: internal timer heap corruption", ANHE_w (timers [active]) == (WT)w)); + + --timercnt; + + if (expect_true (active < timercnt + HEAP0)) + { + timers [active] = timers [timercnt + HEAP0]; + adjustheap (timers, timercnt, active); + } + } + + ev_at (w) -= mn_now; + + ev_stop (EV_A_ (W)w); + + EV_FREQUENT_CHECK; +} + +noinline +void +ev_timer_again (EV_P_ ev_timer *w) EV_THROW +{ + EV_FREQUENT_CHECK; + + clear_pending (EV_A_ (W)w); + + if (ev_is_active (w)) + { + if (w->repeat) + { + ev_at (w) = mn_now + w->repeat; + ANHE_at_cache (timers [ev_active (w)]); + adjustheap (timers, timercnt, ev_active (w)); + } + else + ev_timer_stop (EV_A_ w); + } + else if (w->repeat) + { + ev_at (w) = w->repeat; + ev_timer_start (EV_A_ w); + } + + EV_FREQUENT_CHECK; +} + +ev_tstamp +ev_timer_remaining (EV_P_ ev_timer *w) EV_THROW +{ + return ev_at (w) - (ev_is_active (w) ? mn_now : 0.); +} + +#if EV_PERIODIC_ENABLE +noinline +void +ev_periodic_start (EV_P_ ev_periodic *w) EV_THROW +{ + if (expect_false (ev_is_active (w))) + return; + + if (w->reschedule_cb) + ev_at (w) = w->reschedule_cb (w, ev_rt_now); + else if (w->interval) + { + assert (("libev: ev_periodic_start called with negative interval value", w->interval >= 0.)); + periodic_recalc (EV_A_ w); + } + else + ev_at (w) = w->offset; + + EV_FREQUENT_CHECK; + + ++periodiccnt; + ev_start (EV_A_ (W)w, periodiccnt + HEAP0 - 1); + array_needsize (ANHE, periodics, periodicmax, ev_active (w) + 1, EMPTY2); + ANHE_w (periodics [ev_active (w)]) = (WT)w; + ANHE_at_cache (periodics [ev_active (w)]); + upheap (periodics, ev_active (w)); + + EV_FREQUENT_CHECK; + + /*assert (("libev: internal periodic heap corruption", ANHE_w (periodics [ev_active (w)]) == (WT)w));*/ +} + +noinline +void +ev_periodic_stop (EV_P_ ev_periodic *w) EV_THROW +{ + clear_pending (EV_A_ (W)w); + if (expect_false (!ev_is_active (w))) + return; + + EV_FREQUENT_CHECK; + + { + int active = ev_active (w); + + assert (("libev: internal periodic heap corruption", ANHE_w (periodics [active]) == (WT)w)); + + --periodiccnt; + + if (expect_true (active < periodiccnt + HEAP0)) + { + periodics [active] = periodics [periodiccnt + HEAP0]; + adjustheap (periodics, periodiccnt, active); + } + } + + ev_stop (EV_A_ (W)w); + + EV_FREQUENT_CHECK; +} + +noinline +void +ev_periodic_again (EV_P_ ev_periodic *w) EV_THROW +{ + /* TODO: use adjustheap and recalculation */ + ev_periodic_stop (EV_A_ w); + ev_periodic_start (EV_A_ w); +} +#endif + +#ifndef SA_RESTART +# define SA_RESTART 0 +#endif + +#if EV_SIGNAL_ENABLE + +noinline +void +ev_signal_start (EV_P_ ev_signal *w) EV_THROW +{ + if (expect_false (ev_is_active (w))) + return; + + assert (("libev: ev_signal_start called with illegal signal number", w->signum > 0 && w->signum < EV_NSIG)); + +#if EV_MULTIPLICITY + assert (("libev: a signal must not be attached to two different loops", + !signals [w->signum - 1].loop || signals [w->signum - 1].loop == loop)); + + signals [w->signum - 1].loop = EV_A; + ECB_MEMORY_FENCE_RELEASE; +#endif + + EV_FREQUENT_CHECK; + +#if EV_USE_SIGNALFD + if (sigfd == -2) + { + sigfd = signalfd (-1, &sigfd_set, SFD_NONBLOCK | SFD_CLOEXEC); + if (sigfd < 0 && errno == EINVAL) + sigfd = signalfd (-1, &sigfd_set, 0); /* retry without flags */ + + if (sigfd >= 0) + { + fd_intern (sigfd); /* doing it twice will not hurt */ + + sigemptyset (&sigfd_set); + + ev_io_init (&sigfd_w, sigfdcb, sigfd, EV_READ); + ev_set_priority (&sigfd_w, EV_MAXPRI); + ev_io_start (EV_A_ &sigfd_w); + ev_unref (EV_A); /* signalfd watcher should not keep loop alive */ + } + } + + if (sigfd >= 0) + { + /* TODO: check .head */ + sigaddset (&sigfd_set, w->signum); + sigprocmask (SIG_BLOCK, &sigfd_set, 0); + + signalfd (sigfd, &sigfd_set, 0); + } +#endif + + ev_start (EV_A_ (W)w, 1); + wlist_add (&signals [w->signum - 1].head, (WL)w); + + if (!((WL)w)->next) +# if EV_USE_SIGNALFD + if (sigfd < 0) /*TODO*/ +# endif + { +# ifdef _WIN32 + evpipe_init (EV_A); + + signal (w->signum, ev_sighandler); +# else + struct sigaction sa; + + evpipe_init (EV_A); + + sa.sa_handler = ev_sighandler; + sigfillset (&sa.sa_mask); + sa.sa_flags = SA_RESTART; /* if restarting works we save one iteration */ + sigaction (w->signum, &sa, 0); + + if (origflags & EVFLAG_NOSIGMASK) + { + sigemptyset (&sa.sa_mask); + sigaddset (&sa.sa_mask, w->signum); + sigprocmask (SIG_UNBLOCK, &sa.sa_mask, 0); + } +#endif + } + + EV_FREQUENT_CHECK; +} + +noinline +void +ev_signal_stop (EV_P_ ev_signal *w) EV_THROW +{ + clear_pending (EV_A_ (W)w); + if (expect_false (!ev_is_active (w))) + return; + + EV_FREQUENT_CHECK; + + wlist_del (&signals [w->signum - 1].head, (WL)w); + ev_stop (EV_A_ (W)w); + + if (!signals [w->signum - 1].head) + { +#if EV_MULTIPLICITY + signals [w->signum - 1].loop = 0; /* unattach from signal */ +#endif +#if EV_USE_SIGNALFD + if (sigfd >= 0) + { + sigset_t ss; + + sigemptyset (&ss); + sigaddset (&ss, w->signum); + sigdelset (&sigfd_set, w->signum); + + signalfd (sigfd, &sigfd_set, 0); + sigprocmask (SIG_UNBLOCK, &ss, 0); + } + else +#endif + signal (w->signum, SIG_DFL); + } + + EV_FREQUENT_CHECK; +} + +#endif + +#if EV_CHILD_ENABLE + +void +ev_child_start (EV_P_ ev_child *w) EV_THROW +{ +#if EV_MULTIPLICITY + assert (("libev: child watchers are only supported in the default loop", loop == ev_default_loop_ptr)); +#endif + if (expect_false (ev_is_active (w))) + return; + + EV_FREQUENT_CHECK; + + ev_start (EV_A_ (W)w, 1); + wlist_add (&childs [w->pid & ((EV_PID_HASHSIZE) - 1)], (WL)w); + + EV_FREQUENT_CHECK; +} + +void +ev_child_stop (EV_P_ ev_child *w) EV_THROW +{ + clear_pending (EV_A_ (W)w); + if (expect_false (!ev_is_active (w))) + return; + + EV_FREQUENT_CHECK; + + wlist_del (&childs [w->pid & ((EV_PID_HASHSIZE) - 1)], (WL)w); + ev_stop (EV_A_ (W)w); + + EV_FREQUENT_CHECK; +} + +#endif + +#if EV_STAT_ENABLE + +# ifdef _WIN32 +# undef lstat +# define lstat(a,b) _stati64 (a,b) +# endif + +#define DEF_STAT_INTERVAL 5.0074891 +#define NFS_STAT_INTERVAL 30.1074891 /* for filesystems potentially failing inotify */ +#define MIN_STAT_INTERVAL 0.1074891 + +noinline static void stat_timer_cb (EV_P_ ev_timer *w_, int revents); + +#if EV_USE_INOTIFY + +/* the * 2 is to allow for alignment padding, which for some reason is >> 8 */ +# define EV_INOTIFY_BUFSIZE (sizeof (struct inotify_event) * 2 + NAME_MAX) + +noinline +static void +infy_add (EV_P_ ev_stat *w) +{ + w->wd = inotify_add_watch (fs_fd, w->path, + IN_ATTRIB | IN_DELETE_SELF | IN_MOVE_SELF | IN_MODIFY + | IN_CREATE | IN_DELETE | IN_MOVED_FROM | IN_MOVED_TO + | IN_DONT_FOLLOW | IN_MASK_ADD); + + if (w->wd >= 0) + { + struct statfs sfs; + + /* now local changes will be tracked by inotify, but remote changes won't */ + /* unless the filesystem is known to be local, we therefore still poll */ + /* also do poll on <2.6.25, but with normal frequency */ + + if (!fs_2625) + w->timer.repeat = w->interval ? w->interval : DEF_STAT_INTERVAL; + else if (!statfs (w->path, &sfs) + && (sfs.f_type == 0x1373 /* devfs */ + || sfs.f_type == 0x4006 /* fat */ + || sfs.f_type == 0x4d44 /* msdos */ + || sfs.f_type == 0xEF53 /* ext2/3 */ + || sfs.f_type == 0x72b6 /* jffs2 */ + || sfs.f_type == 0x858458f6 /* ramfs */ + || sfs.f_type == 0x5346544e /* ntfs */ + || sfs.f_type == 0x3153464a /* jfs */ + || sfs.f_type == 0x9123683e /* btrfs */ + || sfs.f_type == 0x52654973 /* reiser3 */ + || sfs.f_type == 0x01021994 /* tmpfs */ + || sfs.f_type == 0x58465342 /* xfs */)) + w->timer.repeat = 0.; /* filesystem is local, kernel new enough */ + else + w->timer.repeat = w->interval ? w->interval : NFS_STAT_INTERVAL; /* remote, use reduced frequency */ + } + else + { + /* can't use inotify, continue to stat */ + w->timer.repeat = w->interval ? w->interval : DEF_STAT_INTERVAL; + + /* if path is not there, monitor some parent directory for speedup hints */ + /* note that exceeding the hardcoded path limit is not a correctness issue, */ + /* but an efficiency issue only */ + if ((errno == ENOENT || errno == EACCES) && strlen (w->path) < 4096) + { + char path [4096]; + strcpy (path, w->path); + + do + { + int mask = IN_MASK_ADD | IN_DELETE_SELF | IN_MOVE_SELF + | (errno == EACCES ? IN_ATTRIB : IN_CREATE | IN_MOVED_TO); + + char *pend = strrchr (path, '/'); + + if (!pend || pend == path) + break; + + *pend = 0; + w->wd = inotify_add_watch (fs_fd, path, mask); + } + while (w->wd < 0 && (errno == ENOENT || errno == EACCES)); + } + } + + if (w->wd >= 0) + wlist_add (&fs_hash [w->wd & ((EV_INOTIFY_HASHSIZE) - 1)].head, (WL)w); + + /* now re-arm timer, if required */ + if (ev_is_active (&w->timer)) ev_ref (EV_A); + ev_timer_again (EV_A_ &w->timer); + if (ev_is_active (&w->timer)) ev_unref (EV_A); +} + +noinline +static void +infy_del (EV_P_ ev_stat *w) +{ + int slot; + int wd = w->wd; + + if (wd < 0) + return; + + w->wd = -2; + slot = wd & ((EV_INOTIFY_HASHSIZE) - 1); + wlist_del (&fs_hash [slot].head, (WL)w); + + /* remove this watcher, if others are watching it, they will rearm */ + inotify_rm_watch (fs_fd, wd); +} + +noinline +static void +infy_wd (EV_P_ int slot, int wd, struct inotify_event *ev) +{ + if (slot < 0) + /* overflow, need to check for all hash slots */ + for (slot = 0; slot < (EV_INOTIFY_HASHSIZE); ++slot) + infy_wd (EV_A_ slot, wd, ev); + else + { + WL w_; + + for (w_ = fs_hash [slot & ((EV_INOTIFY_HASHSIZE) - 1)].head; w_; ) + { + ev_stat *w = (ev_stat *)w_; + w_ = w_->next; /* lets us remove this watcher and all before it */ + + if (w->wd == wd || wd == -1) + { + if (ev->mask & (IN_IGNORED | IN_UNMOUNT | IN_DELETE_SELF)) + { + wlist_del (&fs_hash [slot & ((EV_INOTIFY_HASHSIZE) - 1)].head, (WL)w); + w->wd = -1; + infy_add (EV_A_ w); /* re-add, no matter what */ + } + + stat_timer_cb (EV_A_ &w->timer, 0); + } + } + } +} + +static void +infy_cb (EV_P_ ev_io *w, int revents) +{ + char buf [EV_INOTIFY_BUFSIZE]; + int ofs; + int len = read (fs_fd, buf, sizeof (buf)); + + for (ofs = 0; ofs < len; ) + { + struct inotify_event *ev = (struct inotify_event *)(buf + ofs); + infy_wd (EV_A_ ev->wd, ev->wd, ev); + ofs += sizeof (struct inotify_event) + ev->len; + } +} + +inline_size ecb_cold +void +ev_check_2625 (EV_P) +{ + /* kernels < 2.6.25 are borked + * http://www.ussg.indiana.edu/hypermail/linux/kernel/0711.3/1208.html + */ + if (ev_linux_version () < 0x020619) + return; + + fs_2625 = 1; +} + +inline_size int +infy_newfd (void) +{ +#if defined IN_CLOEXEC && defined IN_NONBLOCK + int fd = inotify_init1 (IN_CLOEXEC | IN_NONBLOCK); + if (fd >= 0) + return fd; +#endif + return inotify_init (); +} + +inline_size void +infy_init (EV_P) +{ + if (fs_fd != -2) + return; + + fs_fd = -1; + + ev_check_2625 (EV_A); + + fs_fd = infy_newfd (); + + if (fs_fd >= 0) + { + fd_intern (fs_fd); + ev_io_init (&fs_w, infy_cb, fs_fd, EV_READ); + ev_set_priority (&fs_w, EV_MAXPRI); + ev_io_start (EV_A_ &fs_w); + ev_unref (EV_A); + } +} + +inline_size void +infy_fork (EV_P) +{ + int slot; + + if (fs_fd < 0) + return; + + ev_ref (EV_A); + ev_io_stop (EV_A_ &fs_w); + close (fs_fd); + fs_fd = infy_newfd (); + + if (fs_fd >= 0) + { + fd_intern (fs_fd); + ev_io_set (&fs_w, fs_fd, EV_READ); + ev_io_start (EV_A_ &fs_w); + ev_unref (EV_A); + } + + for (slot = 0; slot < (EV_INOTIFY_HASHSIZE); ++slot) + { + WL w_ = fs_hash [slot].head; + fs_hash [slot].head = 0; + + while (w_) + { + ev_stat *w = (ev_stat *)w_; + w_ = w_->next; /* lets us add this watcher */ + + w->wd = -1; + + if (fs_fd >= 0) + infy_add (EV_A_ w); /* re-add, no matter what */ + else + { + w->timer.repeat = w->interval ? w->interval : DEF_STAT_INTERVAL; + if (ev_is_active (&w->timer)) ev_ref (EV_A); + ev_timer_again (EV_A_ &w->timer); + if (ev_is_active (&w->timer)) ev_unref (EV_A); + } + } + } +} + +#endif + +#ifdef _WIN32 +# define EV_LSTAT(p,b) _stati64 (p, b) +#else +# define EV_LSTAT(p,b) lstat (p, b) +#endif + +void +ev_stat_stat (EV_P_ ev_stat *w) EV_THROW +{ + if (lstat (w->path, &w->attr) < 0) + w->attr.st_nlink = 0; + else if (!w->attr.st_nlink) + w->attr.st_nlink = 1; +} + +noinline +static void +stat_timer_cb (EV_P_ ev_timer *w_, int revents) +{ + ev_stat *w = (ev_stat *)(((char *)w_) - offsetof (ev_stat, timer)); + + ev_statdata prev = w->attr; + ev_stat_stat (EV_A_ w); + + /* memcmp doesn't work on netbsd, they.... do stuff to their struct stat */ + if ( + prev.st_dev != w->attr.st_dev + || prev.st_ino != w->attr.st_ino + || prev.st_mode != w->attr.st_mode + || prev.st_nlink != w->attr.st_nlink + || prev.st_uid != w->attr.st_uid + || prev.st_gid != w->attr.st_gid + || prev.st_rdev != w->attr.st_rdev + || prev.st_size != w->attr.st_size + || prev.st_atime != w->attr.st_atime + || prev.st_mtime != w->attr.st_mtime + || prev.st_ctime != w->attr.st_ctime + ) { + /* we only update w->prev on actual differences */ + /* in case we test more often than invoke the callback, */ + /* to ensure that prev is always different to attr */ + w->prev = prev; + + #if EV_USE_INOTIFY + if (fs_fd >= 0) + { + infy_del (EV_A_ w); + infy_add (EV_A_ w); + ev_stat_stat (EV_A_ w); /* avoid race... */ + } + #endif + + ev_feed_event (EV_A_ w, EV_STAT); + } +} + +void +ev_stat_start (EV_P_ ev_stat *w) EV_THROW +{ + if (expect_false (ev_is_active (w))) + return; + + ev_stat_stat (EV_A_ w); + + if (w->interval < MIN_STAT_INTERVAL && w->interval) + w->interval = MIN_STAT_INTERVAL; + + ev_timer_init (&w->timer, stat_timer_cb, 0., w->interval ? w->interval : DEF_STAT_INTERVAL); + ev_set_priority (&w->timer, ev_priority (w)); + +#if EV_USE_INOTIFY + infy_init (EV_A); + + if (fs_fd >= 0) + infy_add (EV_A_ w); + else +#endif + { + ev_timer_again (EV_A_ &w->timer); + ev_unref (EV_A); + } + + ev_start (EV_A_ (W)w, 1); + + EV_FREQUENT_CHECK; +} + +void +ev_stat_stop (EV_P_ ev_stat *w) EV_THROW +{ + clear_pending (EV_A_ (W)w); + if (expect_false (!ev_is_active (w))) + return; + + EV_FREQUENT_CHECK; + +#if EV_USE_INOTIFY + infy_del (EV_A_ w); +#endif + + if (ev_is_active (&w->timer)) + { + ev_ref (EV_A); + ev_timer_stop (EV_A_ &w->timer); + } + + ev_stop (EV_A_ (W)w); + + EV_FREQUENT_CHECK; +} +#endif + +#if EV_IDLE_ENABLE +void +ev_idle_start (EV_P_ ev_idle *w) EV_THROW +{ + if (expect_false (ev_is_active (w))) + return; + + pri_adjust (EV_A_ (W)w); + + EV_FREQUENT_CHECK; + + { + int active = ++idlecnt [ABSPRI (w)]; + + ++idleall; + ev_start (EV_A_ (W)w, active); + + array_needsize (ev_idle *, idles [ABSPRI (w)], idlemax [ABSPRI (w)], active, EMPTY2); + idles [ABSPRI (w)][active - 1] = w; + } + + EV_FREQUENT_CHECK; +} + +void +ev_idle_stop (EV_P_ ev_idle *w) EV_THROW +{ + clear_pending (EV_A_ (W)w); + if (expect_false (!ev_is_active (w))) + return; + + EV_FREQUENT_CHECK; + + { + int active = ev_active (w); + + idles [ABSPRI (w)][active - 1] = idles [ABSPRI (w)][--idlecnt [ABSPRI (w)]]; + ev_active (idles [ABSPRI (w)][active - 1]) = active; + + ev_stop (EV_A_ (W)w); + --idleall; + } + + EV_FREQUENT_CHECK; +} +#endif + +#if EV_PREPARE_ENABLE +void +ev_prepare_start (EV_P_ ev_prepare *w) EV_THROW +{ + if (expect_false (ev_is_active (w))) + return; + + EV_FREQUENT_CHECK; + + ev_start (EV_A_ (W)w, ++preparecnt); + array_needsize (ev_prepare *, prepares, preparemax, preparecnt, EMPTY2); + prepares [preparecnt - 1] = w; + + EV_FREQUENT_CHECK; +} + +void +ev_prepare_stop (EV_P_ ev_prepare *w) EV_THROW +{ + clear_pending (EV_A_ (W)w); + if (expect_false (!ev_is_active (w))) + return; + + EV_FREQUENT_CHECK; + + { + int active = ev_active (w); + + prepares [active - 1] = prepares [--preparecnt]; + ev_active (prepares [active - 1]) = active; + } + + ev_stop (EV_A_ (W)w); + + EV_FREQUENT_CHECK; +} +#endif + +#if EV_CHECK_ENABLE +void +ev_check_start (EV_P_ ev_check *w) EV_THROW +{ + if (expect_false (ev_is_active (w))) + return; + + EV_FREQUENT_CHECK; + + ev_start (EV_A_ (W)w, ++checkcnt); + array_needsize (ev_check *, checks, checkmax, checkcnt, EMPTY2); + checks [checkcnt - 1] = w; + + EV_FREQUENT_CHECK; +} + +void +ev_check_stop (EV_P_ ev_check *w) EV_THROW +{ + clear_pending (EV_A_ (W)w); + if (expect_false (!ev_is_active (w))) + return; + + EV_FREQUENT_CHECK; + + { + int active = ev_active (w); + + checks [active - 1] = checks [--checkcnt]; + ev_active (checks [active - 1]) = active; + } + + ev_stop (EV_A_ (W)w); + + EV_FREQUENT_CHECK; +} +#endif + +#if EV_EMBED_ENABLE +noinline +void +ev_embed_sweep (EV_P_ ev_embed *w) EV_THROW +{ + ev_run (w->other, EVRUN_NOWAIT); +} + +static void +embed_io_cb (EV_P_ ev_io *io, int revents) +{ + ev_embed *w = (ev_embed *)(((char *)io) - offsetof (ev_embed, io)); + + if (ev_cb (w)) + ev_feed_event (EV_A_ (W)w, EV_EMBED); + else + ev_run (w->other, EVRUN_NOWAIT); +} + +static void +embed_prepare_cb (EV_P_ ev_prepare *prepare, int revents) +{ + ev_embed *w = (ev_embed *)(((char *)prepare) - offsetof (ev_embed, prepare)); + + { + EV_P = w->other; + + while (fdchangecnt) + { + fd_reify (EV_A); + ev_run (EV_A_ EVRUN_NOWAIT); + } + } +} + +static void +embed_fork_cb (EV_P_ ev_fork *fork_w, int revents) +{ + ev_embed *w = (ev_embed *)(((char *)fork_w) - offsetof (ev_embed, fork)); + + ev_embed_stop (EV_A_ w); + + { + EV_P = w->other; + + ev_loop_fork (EV_A); + ev_run (EV_A_ EVRUN_NOWAIT); + } + + ev_embed_start (EV_A_ w); +} + +#if 0 +static void +embed_idle_cb (EV_P_ ev_idle *idle, int revents) +{ + ev_idle_stop (EV_A_ idle); +} +#endif + +void +ev_embed_start (EV_P_ ev_embed *w) EV_THROW +{ + if (expect_false (ev_is_active (w))) + return; + + { + EV_P = w->other; + assert (("libev: loop to be embedded is not embeddable", backend & ev_embeddable_backends ())); + ev_io_init (&w->io, embed_io_cb, backend_fd, EV_READ); + } + + EV_FREQUENT_CHECK; + + ev_set_priority (&w->io, ev_priority (w)); + ev_io_start (EV_A_ &w->io); + + ev_prepare_init (&w->prepare, embed_prepare_cb); + ev_set_priority (&w->prepare, EV_MINPRI); + ev_prepare_start (EV_A_ &w->prepare); + + ev_fork_init (&w->fork, embed_fork_cb); + ev_fork_start (EV_A_ &w->fork); + + /*ev_idle_init (&w->idle, e,bed_idle_cb);*/ + + ev_start (EV_A_ (W)w, 1); + + EV_FREQUENT_CHECK; +} + +void +ev_embed_stop (EV_P_ ev_embed *w) EV_THROW +{ + clear_pending (EV_A_ (W)w); + if (expect_false (!ev_is_active (w))) + return; + + EV_FREQUENT_CHECK; + + ev_io_stop (EV_A_ &w->io); + ev_prepare_stop (EV_A_ &w->prepare); + ev_fork_stop (EV_A_ &w->fork); + + ev_stop (EV_A_ (W)w); + + EV_FREQUENT_CHECK; +} +#endif + +#if EV_FORK_ENABLE +void +ev_fork_start (EV_P_ ev_fork *w) EV_THROW +{ + if (expect_false (ev_is_active (w))) + return; + + EV_FREQUENT_CHECK; + + ev_start (EV_A_ (W)w, ++forkcnt); + array_needsize (ev_fork *, forks, forkmax, forkcnt, EMPTY2); + forks [forkcnt - 1] = w; + + EV_FREQUENT_CHECK; +} + +void +ev_fork_stop (EV_P_ ev_fork *w) EV_THROW +{ + clear_pending (EV_A_ (W)w); + if (expect_false (!ev_is_active (w))) + return; + + EV_FREQUENT_CHECK; + + { + int active = ev_active (w); + + forks [active - 1] = forks [--forkcnt]; + ev_active (forks [active - 1]) = active; + } + + ev_stop (EV_A_ (W)w); + + EV_FREQUENT_CHECK; +} +#endif + +#if EV_CLEANUP_ENABLE +void +ev_cleanup_start (EV_P_ ev_cleanup *w) EV_THROW +{ + if (expect_false (ev_is_active (w))) + return; + + EV_FREQUENT_CHECK; + + ev_start (EV_A_ (W)w, ++cleanupcnt); + array_needsize (ev_cleanup *, cleanups, cleanupmax, cleanupcnt, EMPTY2); + cleanups [cleanupcnt - 1] = w; + + /* cleanup watchers should never keep a refcount on the loop */ + ev_unref (EV_A); + EV_FREQUENT_CHECK; +} + +void +ev_cleanup_stop (EV_P_ ev_cleanup *w) EV_THROW +{ + clear_pending (EV_A_ (W)w); + if (expect_false (!ev_is_active (w))) + return; + + EV_FREQUENT_CHECK; + ev_ref (EV_A); + + { + int active = ev_active (w); + + cleanups [active - 1] = cleanups [--cleanupcnt]; + ev_active (cleanups [active - 1]) = active; + } + + ev_stop (EV_A_ (W)w); + + EV_FREQUENT_CHECK; +} +#endif + +#if EV_ASYNC_ENABLE +void +ev_async_start (EV_P_ ev_async *w) EV_THROW +{ + if (expect_false (ev_is_active (w))) + return; + + w->sent = 0; + + evpipe_init (EV_A); + + EV_FREQUENT_CHECK; + + ev_start (EV_A_ (W)w, ++asynccnt); + array_needsize (ev_async *, asyncs, asyncmax, asynccnt, EMPTY2); + asyncs [asynccnt - 1] = w; + + EV_FREQUENT_CHECK; +} + +void +ev_async_stop (EV_P_ ev_async *w) EV_THROW +{ + clear_pending (EV_A_ (W)w); + if (expect_false (!ev_is_active (w))) + return; + + EV_FREQUENT_CHECK; + + { + int active = ev_active (w); + + asyncs [active - 1] = asyncs [--asynccnt]; + ev_active (asyncs [active - 1]) = active; + } + + ev_stop (EV_A_ (W)w); + + EV_FREQUENT_CHECK; +} + +void +ev_async_send (EV_P_ ev_async *w) EV_THROW +{ + w->sent = 1; + evpipe_write (EV_A_ &async_pending); +} +#endif + +/*****************************************************************************/ + +struct ev_once +{ + ev_io io; + ev_timer to; + void (*cb)(int revents, void *arg); + void *arg; +}; + +static void +once_cb (EV_P_ struct ev_once *once, int revents) +{ + void (*cb)(int revents, void *arg) = once->cb; + void *arg = once->arg; + + ev_io_stop (EV_A_ &once->io); + ev_timer_stop (EV_A_ &once->to); + ev_free (once); + + cb (revents, arg); +} + +static void +once_cb_io (EV_P_ ev_io *w, int revents) +{ + struct ev_once *once = (struct ev_once *)(((char *)w) - offsetof (struct ev_once, io)); + + once_cb (EV_A_ once, revents | ev_clear_pending (EV_A_ &once->to)); +} + +static void +once_cb_to (EV_P_ ev_timer *w, int revents) +{ + struct ev_once *once = (struct ev_once *)(((char *)w) - offsetof (struct ev_once, to)); + + once_cb (EV_A_ once, revents | ev_clear_pending (EV_A_ &once->io)); +} + +void +ev_once (EV_P_ int fd, int events, ev_tstamp timeout, void (*cb)(int revents, void *arg), void *arg) EV_THROW +{ + struct ev_once *once = (struct ev_once *)ev_malloc (sizeof (struct ev_once)); + + if (expect_false (!once)) + { + cb (EV_ERROR | EV_READ | EV_WRITE | EV_TIMER, arg); + return; + } + + once->cb = cb; + once->arg = arg; + + ev_init (&once->io, once_cb_io); + if (fd >= 0) + { + ev_io_set (&once->io, fd, events); + ev_io_start (EV_A_ &once->io); + } + + ev_init (&once->to, once_cb_to); + if (timeout >= 0.) + { + ev_timer_set (&once->to, timeout, 0.); + ev_timer_start (EV_A_ &once->to); + } +} + +/*****************************************************************************/ + +#if EV_WALK_ENABLE +ecb_cold +void +ev_walk (EV_P_ int types, void (*cb)(EV_P_ int type, void *w)) EV_THROW +{ + int i, j; + ev_watcher_list *wl, *wn; + + if (types & (EV_IO | EV_EMBED)) + for (i = 0; i < anfdmax; ++i) + for (wl = anfds [i].head; wl; ) + { + wn = wl->next; + +#if EV_EMBED_ENABLE + if (ev_cb ((ev_io *)wl) == embed_io_cb) + { + if (types & EV_EMBED) + cb (EV_A_ EV_EMBED, ((char *)wl) - offsetof (struct ev_embed, io)); + } + else +#endif +#if EV_USE_INOTIFY + if (ev_cb ((ev_io *)wl) == infy_cb) + ; + else +#endif + if ((ev_io *)wl != &pipe_w) + if (types & EV_IO) + cb (EV_A_ EV_IO, wl); + + wl = wn; + } + + if (types & (EV_TIMER | EV_STAT)) + for (i = timercnt + HEAP0; i-- > HEAP0; ) +#if EV_STAT_ENABLE + /*TODO: timer is not always active*/ + if (ev_cb ((ev_timer *)ANHE_w (timers [i])) == stat_timer_cb) + { + if (types & EV_STAT) + cb (EV_A_ EV_STAT, ((char *)ANHE_w (timers [i])) - offsetof (struct ev_stat, timer)); + } + else +#endif + if (types & EV_TIMER) + cb (EV_A_ EV_TIMER, ANHE_w (timers [i])); + +#if EV_PERIODIC_ENABLE + if (types & EV_PERIODIC) + for (i = periodiccnt + HEAP0; i-- > HEAP0; ) + cb (EV_A_ EV_PERIODIC, ANHE_w (periodics [i])); +#endif + +#if EV_IDLE_ENABLE + if (types & EV_IDLE) + for (j = NUMPRI; j--; ) + for (i = idlecnt [j]; i--; ) + cb (EV_A_ EV_IDLE, idles [j][i]); +#endif + +#if EV_FORK_ENABLE + if (types & EV_FORK) + for (i = forkcnt; i--; ) + if (ev_cb (forks [i]) != embed_fork_cb) + cb (EV_A_ EV_FORK, forks [i]); +#endif + +#if EV_ASYNC_ENABLE + if (types & EV_ASYNC) + for (i = asynccnt; i--; ) + cb (EV_A_ EV_ASYNC, asyncs [i]); +#endif + +#if EV_PREPARE_ENABLE + if (types & EV_PREPARE) + for (i = preparecnt; i--; ) +# if EV_EMBED_ENABLE + if (ev_cb (prepares [i]) != embed_prepare_cb) +# endif + cb (EV_A_ EV_PREPARE, prepares [i]); +#endif + +#if EV_CHECK_ENABLE + if (types & EV_CHECK) + for (i = checkcnt; i--; ) + cb (EV_A_ EV_CHECK, checks [i]); +#endif + +#if EV_SIGNAL_ENABLE + if (types & EV_SIGNAL) + for (i = 0; i < EV_NSIG - 1; ++i) + for (wl = signals [i].head; wl; ) + { + wn = wl->next; + cb (EV_A_ EV_SIGNAL, wl); + wl = wn; + } +#endif + +#if EV_CHILD_ENABLE + if (types & EV_CHILD) + for (i = (EV_PID_HASHSIZE); i--; ) + for (wl = childs [i]; wl; ) + { + wn = wl->next; + cb (EV_A_ EV_CHILD, wl); + wl = wn; + } +#endif +/* EV_STAT 0x00001000 /* stat data changed */ +/* EV_EMBED 0x00010000 /* embedded event loop needs sweep */ +} +#endif + +#if EV_MULTIPLICITY + #include "ev_wrap.h" +#endif + diff --git a/libev/ev.h b/libev/ev.h new file mode 100644 index 0000000..db93777 --- /dev/null +++ b/libev/ev.h @@ -0,0 +1,854 @@ +/* + * libev native API header + * + * Copyright (c) 2007,2008,2009,2010,2011,2012,2015 Marc Alexander Lehmann + * All rights reserved. + * + * Redistribution and use in source and binary forms, with or without modifica- + * tion, are permitted provided that the following conditions are met: + * + * 1. Redistributions of source code must retain the above copyright notice, + * this list of conditions and the following disclaimer. + * + * 2. Redistributions in binary form must reproduce the above copyright + * notice, this list of conditions and the following disclaimer in the + * documentation and/or other materials provided with the distribution. + * + * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR IMPLIED + * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MER- + * CHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO + * EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPE- + * CIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, + * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; + * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, + * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTH- + * ERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED + * OF THE POSSIBILITY OF SUCH DAMAGE. + * + * Alternatively, the contents of this file may be used under the terms of + * the GNU General Public License ("GPL") version 2 or any later version, + * in which case the provisions of the GPL are applicable instead of + * the above. If you wish to allow the use of your version of this file + * only under the terms of the GPL and not to allow others to use your + * version of this file under the BSD license, indicate your decision + * by deleting the provisions above and replace them with the notice + * and other provisions required by the GPL. If you do not delete the + * provisions above, a recipient may use your version of this file under + * either the BSD or the GPL. + */ + +#ifndef EV_H_ +#define EV_H_ + +#ifdef __cplusplus +# define EV_CPP(x) x +# if __cplusplus >= 201103L +# define EV_THROW noexcept +# else +# define EV_THROW throw () +# endif +#else +# define EV_CPP(x) +# define EV_THROW +#endif + +EV_CPP(extern "C" {) + +/*****************************************************************************/ + +/* pre-4.0 compatibility */ +#ifndef EV_COMPAT3 +# define EV_COMPAT3 1 +#endif + +#ifndef EV_FEATURES +# if defined __OPTIMIZE_SIZE__ +# define EV_FEATURES 0x7c +# else +# define EV_FEATURES 0x7f +# endif +#endif + +#define EV_FEATURE_CODE ((EV_FEATURES) & 1) +#define EV_FEATURE_DATA ((EV_FEATURES) & 2) +#define EV_FEATURE_CONFIG ((EV_FEATURES) & 4) +#define EV_FEATURE_API ((EV_FEATURES) & 8) +#define EV_FEATURE_WATCHERS ((EV_FEATURES) & 16) +#define EV_FEATURE_BACKENDS ((EV_FEATURES) & 32) +#define EV_FEATURE_OS ((EV_FEATURES) & 64) + +/* these priorities are inclusive, higher priorities will be invoked earlier */ +#ifndef EV_MINPRI +# define EV_MINPRI (EV_FEATURE_CONFIG ? -2 : 0) +#endif +#ifndef EV_MAXPRI +# define EV_MAXPRI (EV_FEATURE_CONFIG ? +2 : 0) +#endif + +#ifndef EV_MULTIPLICITY +# define EV_MULTIPLICITY EV_FEATURE_CONFIG +#endif + +#ifndef EV_PERIODIC_ENABLE +# define EV_PERIODIC_ENABLE EV_FEATURE_WATCHERS +#endif + +#ifndef EV_STAT_ENABLE +# define EV_STAT_ENABLE EV_FEATURE_WATCHERS +#endif + +#ifndef EV_PREPARE_ENABLE +# define EV_PREPARE_ENABLE EV_FEATURE_WATCHERS +#endif + +#ifndef EV_CHECK_ENABLE +# define EV_CHECK_ENABLE EV_FEATURE_WATCHERS +#endif + +#ifndef EV_IDLE_ENABLE +# define EV_IDLE_ENABLE EV_FEATURE_WATCHERS +#endif + +#ifndef EV_FORK_ENABLE +# define EV_FORK_ENABLE EV_FEATURE_WATCHERS +#endif + +#ifndef EV_CLEANUP_ENABLE +# define EV_CLEANUP_ENABLE EV_FEATURE_WATCHERS +#endif + +#ifndef EV_SIGNAL_ENABLE +# define EV_SIGNAL_ENABLE EV_FEATURE_WATCHERS +#endif + +#ifndef EV_CHILD_ENABLE +# ifdef _WIN32 +# define EV_CHILD_ENABLE 0 +# else +# define EV_CHILD_ENABLE EV_FEATURE_WATCHERS +#endif +#endif + +#ifndef EV_ASYNC_ENABLE +# define EV_ASYNC_ENABLE EV_FEATURE_WATCHERS +#endif + +#ifndef EV_EMBED_ENABLE +# define EV_EMBED_ENABLE EV_FEATURE_WATCHERS +#endif + +#ifndef EV_WALK_ENABLE +# define EV_WALK_ENABLE 0 /* not yet */ +#endif + +/*****************************************************************************/ + +#if EV_CHILD_ENABLE && !EV_SIGNAL_ENABLE +# undef EV_SIGNAL_ENABLE +# define EV_SIGNAL_ENABLE 1 +#endif + +/*****************************************************************************/ + +typedef double ev_tstamp; + +#include /* for memmove */ + +#ifndef EV_ATOMIC_T +# include +# define EV_ATOMIC_T sig_atomic_t volatile +#endif + +#if EV_STAT_ENABLE +# ifdef _WIN32 +# include +# include +# endif +# include +#endif + +/* support multiple event loops? */ +#if EV_MULTIPLICITY +struct ev_loop; +# define EV_P struct ev_loop *loop /* a loop as sole parameter in a declaration */ +# define EV_P_ EV_P, /* a loop as first of multiple parameters */ +# define EV_A loop /* a loop as sole argument to a function call */ +# define EV_A_ EV_A, /* a loop as first of multiple arguments */ +# define EV_DEFAULT_UC ev_default_loop_uc_ () /* the default loop, if initialised, as sole arg */ +# define EV_DEFAULT_UC_ EV_DEFAULT_UC, /* the default loop as first of multiple arguments */ +# define EV_DEFAULT ev_default_loop (0) /* the default loop as sole arg */ +# define EV_DEFAULT_ EV_DEFAULT, /* the default loop as first of multiple arguments */ +#else +# define EV_P void +# define EV_P_ +# define EV_A +# define EV_A_ +# define EV_DEFAULT +# define EV_DEFAULT_ +# define EV_DEFAULT_UC +# define EV_DEFAULT_UC_ +# undef EV_EMBED_ENABLE +#endif + +/* EV_INLINE is used for functions in header files */ +#if __STDC_VERSION__ >= 199901L || __GNUC__ >= 3 +# define EV_INLINE static inline +#else +# define EV_INLINE static +#endif + +#ifdef EV_API_STATIC +# define EV_API_DECL static +#else +# define EV_API_DECL extern +#endif + +/* EV_PROTOTYPES can be used to switch of prototype declarations */ +#ifndef EV_PROTOTYPES +# define EV_PROTOTYPES 1 +#endif + +/*****************************************************************************/ + +#define EV_VERSION_MAJOR 4 +#define EV_VERSION_MINOR 24 + +/* eventmask, revents, events... */ +enum { + EV_UNDEF = (int)0xFFFFFFFF, /* guaranteed to be invalid */ + EV_NONE = 0x00, /* no events */ + EV_READ = 0x01, /* ev_io detected read will not block */ + EV_WRITE = 0x02, /* ev_io detected write will not block */ + EV__IOFDSET = 0x80, /* internal use only */ + EV_IO = EV_READ, /* alias for type-detection */ + EV_TIMER = 0x00000100, /* timer timed out */ +#if EV_COMPAT3 + EV_TIMEOUT = EV_TIMER, /* pre 4.0 API compatibility */ +#endif + EV_PERIODIC = 0x00000200, /* periodic timer timed out */ + EV_SIGNAL = 0x00000400, /* signal was received */ + EV_CHILD = 0x00000800, /* child/pid had status change */ + EV_STAT = 0x00001000, /* stat data changed */ + EV_IDLE = 0x00002000, /* event loop is idling */ + EV_PREPARE = 0x00004000, /* event loop about to poll */ + EV_CHECK = 0x00008000, /* event loop finished poll */ + EV_EMBED = 0x00010000, /* embedded event loop needs sweep */ + EV_FORK = 0x00020000, /* event loop resumed in child */ + EV_CLEANUP = 0x00040000, /* event loop resumed in child */ + EV_ASYNC = 0x00080000, /* async intra-loop signal */ + EV_CUSTOM = 0x01000000, /* for use by user code */ + EV_ERROR = (int)0x80000000 /* sent when an error occurs */ +}; + +/* can be used to add custom fields to all watchers, while losing binary compatibility */ +#ifndef EV_COMMON +# define EV_COMMON void *data; +#endif + +#ifndef EV_CB_DECLARE +# define EV_CB_DECLARE(type) void (*cb)(EV_P_ struct type *w, int revents); +#endif +#ifndef EV_CB_INVOKE +# define EV_CB_INVOKE(watcher,revents) (watcher)->cb (EV_A_ (watcher), (revents)) +#endif + +/* not official, do not use */ +#define EV_CB(type,name) void name (EV_P_ struct ev_ ## type *w, int revents) + +/* + * struct member types: + * private: you may look at them, but not change them, + * and they might not mean anything to you. + * ro: can be read anytime, but only changed when the watcher isn't active. + * rw: can be read and modified anytime, even when the watcher is active. + * + * some internal details that might be helpful for debugging: + * + * active is either 0, which means the watcher is not active, + * or the array index of the watcher (periodics, timers) + * or the array index + 1 (most other watchers) + * or simply 1 for watchers that aren't in some array. + * pending is either 0, in which case the watcher isn't, + * or the array index + 1 in the pendings array. + */ + +#if EV_MINPRI == EV_MAXPRI +# define EV_DECL_PRIORITY +#elif !defined (EV_DECL_PRIORITY) +# define EV_DECL_PRIORITY int priority; +#endif + +/* shared by all watchers */ +#define EV_WATCHER(type) \ + int active; /* private */ \ + int pending; /* private */ \ + EV_DECL_PRIORITY /* private */ \ + EV_COMMON /* rw */ \ + EV_CB_DECLARE (type) /* private */ + +#define EV_WATCHER_LIST(type) \ + EV_WATCHER (type) \ + struct ev_watcher_list *next; /* private */ + +#define EV_WATCHER_TIME(type) \ + EV_WATCHER (type) \ + ev_tstamp at; /* private */ + +/* base class, nothing to see here unless you subclass */ +typedef struct ev_watcher +{ + EV_WATCHER (ev_watcher) +} ev_watcher; + +/* base class, nothing to see here unless you subclass */ +typedef struct ev_watcher_list +{ + EV_WATCHER_LIST (ev_watcher_list) +} ev_watcher_list; + +/* base class, nothing to see here unless you subclass */ +typedef struct ev_watcher_time +{ + EV_WATCHER_TIME (ev_watcher_time) +} ev_watcher_time; + +/* invoked when fd is either EV_READable or EV_WRITEable */ +/* revent EV_READ, EV_WRITE */ +typedef struct ev_io +{ + EV_WATCHER_LIST (ev_io) + + int fd; /* ro */ + int events; /* ro */ +} ev_io; + +/* invoked after a specific time, repeatable (based on monotonic clock) */ +/* revent EV_TIMEOUT */ +typedef struct ev_timer +{ + EV_WATCHER_TIME (ev_timer) + + ev_tstamp repeat; /* rw */ +} ev_timer; + +/* invoked at some specific time, possibly repeating at regular intervals (based on UTC) */ +/* revent EV_PERIODIC */ +typedef struct ev_periodic +{ + EV_WATCHER_TIME (ev_periodic) + + ev_tstamp offset; /* rw */ + ev_tstamp interval; /* rw */ + ev_tstamp (*reschedule_cb)(struct ev_periodic *w, ev_tstamp now) EV_THROW; /* rw */ +} ev_periodic; + +/* invoked when the given signal has been received */ +/* revent EV_SIGNAL */ +typedef struct ev_signal +{ + EV_WATCHER_LIST (ev_signal) + + int signum; /* ro */ +} ev_signal; + +/* invoked when sigchld is received and waitpid indicates the given pid */ +/* revent EV_CHILD */ +/* does not support priorities */ +typedef struct ev_child +{ + EV_WATCHER_LIST (ev_child) + + int flags; /* private */ + int pid; /* ro */ + int rpid; /* rw, holds the received pid */ + int rstatus; /* rw, holds the exit status, use the macros from sys/wait.h */ +} ev_child; + +#if EV_STAT_ENABLE +/* st_nlink = 0 means missing file or other error */ +# ifdef _WIN32 +typedef struct _stati64 ev_statdata; +# else +typedef struct stat ev_statdata; +# endif + +/* invoked each time the stat data changes for a given path */ +/* revent EV_STAT */ +typedef struct ev_stat +{ + EV_WATCHER_LIST (ev_stat) + + ev_timer timer; /* private */ + ev_tstamp interval; /* ro */ + const char *path; /* ro */ + ev_statdata prev; /* ro */ + ev_statdata attr; /* ro */ + + int wd; /* wd for inotify, fd for kqueue */ +} ev_stat; +#endif + +#if EV_IDLE_ENABLE +/* invoked when the nothing else needs to be done, keeps the process from blocking */ +/* revent EV_IDLE */ +typedef struct ev_idle +{ + EV_WATCHER (ev_idle) +} ev_idle; +#endif + +/* invoked for each run of the mainloop, just before the blocking call */ +/* you can still change events in any way you like */ +/* revent EV_PREPARE */ +typedef struct ev_prepare +{ + EV_WATCHER (ev_prepare) +} ev_prepare; + +/* invoked for each run of the mainloop, just after the blocking call */ +/* revent EV_CHECK */ +typedef struct ev_check +{ + EV_WATCHER (ev_check) +} ev_check; + +#if EV_FORK_ENABLE +/* the callback gets invoked before check in the child process when a fork was detected */ +/* revent EV_FORK */ +typedef struct ev_fork +{ + EV_WATCHER (ev_fork) +} ev_fork; +#endif + +#if EV_CLEANUP_ENABLE +/* is invoked just before the loop gets destroyed */ +/* revent EV_CLEANUP */ +typedef struct ev_cleanup +{ + EV_WATCHER (ev_cleanup) +} ev_cleanup; +#endif + +#if EV_EMBED_ENABLE +/* used to embed an event loop inside another */ +/* the callback gets invoked when the event loop has handled events, and can be 0 */ +typedef struct ev_embed +{ + EV_WATCHER (ev_embed) + + struct ev_loop *other; /* ro */ + ev_io io; /* private */ + ev_prepare prepare; /* private */ + ev_check check; /* unused */ + ev_timer timer; /* unused */ + ev_periodic periodic; /* unused */ + ev_idle idle; /* unused */ + ev_fork fork; /* private */ +#if EV_CLEANUP_ENABLE + ev_cleanup cleanup; /* unused */ +#endif +} ev_embed; +#endif + +#if EV_ASYNC_ENABLE +/* invoked when somebody calls ev_async_send on the watcher */ +/* revent EV_ASYNC */ +typedef struct ev_async +{ + EV_WATCHER (ev_async) + + EV_ATOMIC_T sent; /* private */ +} ev_async; + +# define ev_async_pending(w) (+(w)->sent) +#endif + +/* the presence of this union forces similar struct layout */ +union ev_any_watcher +{ + struct ev_watcher w; + struct ev_watcher_list wl; + + struct ev_io io; + struct ev_timer timer; + struct ev_periodic periodic; + struct ev_signal signal; + struct ev_child child; +#if EV_STAT_ENABLE + struct ev_stat stat; +#endif +#if EV_IDLE_ENABLE + struct ev_idle idle; +#endif + struct ev_prepare prepare; + struct ev_check check; +#if EV_FORK_ENABLE + struct ev_fork fork; +#endif +#if EV_CLEANUP_ENABLE + struct ev_cleanup cleanup; +#endif +#if EV_EMBED_ENABLE + struct ev_embed embed; +#endif +#if EV_ASYNC_ENABLE + struct ev_async async; +#endif +}; + +/* flag bits for ev_default_loop and ev_loop_new */ +enum { + /* the default */ + EVFLAG_AUTO = 0x00000000U, /* not quite a mask */ + /* flag bits */ + EVFLAG_NOENV = 0x01000000U, /* do NOT consult environment */ + EVFLAG_FORKCHECK = 0x02000000U, /* check for a fork in each iteration */ + /* debugging/feature disable */ + EVFLAG_NOINOTIFY = 0x00100000U, /* do not attempt to use inotify */ +#if EV_COMPAT3 + EVFLAG_NOSIGFD = 0, /* compatibility to pre-3.9 */ +#endif + EVFLAG_SIGNALFD = 0x00200000U, /* attempt to use signalfd */ + EVFLAG_NOSIGMASK = 0x00400000U /* avoid modifying the signal mask */ +}; + +/* method bits to be ored together */ +enum { + EVBACKEND_SELECT = 0x00000001U, /* available just about anywhere */ + EVBACKEND_POLL = 0x00000002U, /* !win, !aix, broken on osx */ + EVBACKEND_EPOLL = 0x00000004U, /* linux */ + EVBACKEND_KQUEUE = 0x00000008U, /* bsd, broken on osx */ + EVBACKEND_DEVPOLL = 0x00000010U, /* solaris 8 */ /* NYI */ + EVBACKEND_PORT = 0x00000020U, /* solaris 10 */ + EVBACKEND_ALL = 0x0000003FU, /* all known backends */ + EVBACKEND_MASK = 0x0000FFFFU /* all future backends */ +}; + +#if EV_PROTOTYPES +EV_API_DECL int ev_version_major (void) EV_THROW; +EV_API_DECL int ev_version_minor (void) EV_THROW; + +EV_API_DECL unsigned int ev_supported_backends (void) EV_THROW; +EV_API_DECL unsigned int ev_recommended_backends (void) EV_THROW; +EV_API_DECL unsigned int ev_embeddable_backends (void) EV_THROW; + +EV_API_DECL ev_tstamp ev_time (void) EV_THROW; +EV_API_DECL void ev_sleep (ev_tstamp delay) EV_THROW; /* sleep for a while */ + +/* Sets the allocation function to use, works like realloc. + * It is used to allocate and free memory. + * If it returns zero when memory needs to be allocated, the library might abort + * or take some potentially destructive action. + * The default is your system realloc function. + */ +EV_API_DECL void ev_set_allocator (void *(*cb)(void *ptr, long size) EV_THROW) EV_THROW; + +/* set the callback function to call on a + * retryable syscall error + * (such as failed select, poll, epoll_wait) + */ +EV_API_DECL void ev_set_syserr_cb (void (*cb)(const char *msg) EV_THROW) EV_THROW; + +#if EV_MULTIPLICITY + +/* the default loop is the only one that handles signals and child watchers */ +/* you can call this as often as you like */ +EV_API_DECL struct ev_loop *ev_default_loop (unsigned int flags EV_CPP (= 0)) EV_THROW; + +#ifdef EV_API_STATIC +EV_API_DECL struct ev_loop *ev_default_loop_ptr; +#endif + +EV_INLINE struct ev_loop * +ev_default_loop_uc_ (void) EV_THROW +{ + extern struct ev_loop *ev_default_loop_ptr; + + return ev_default_loop_ptr; +} + +EV_INLINE int +ev_is_default_loop (EV_P) EV_THROW +{ + return EV_A == EV_DEFAULT_UC; +} + +/* create and destroy alternative loops that don't handle signals */ +EV_API_DECL struct ev_loop *ev_loop_new (unsigned int flags EV_CPP (= 0)) EV_THROW; + +EV_API_DECL ev_tstamp ev_now (EV_P) EV_THROW; /* time w.r.t. timers and the eventloop, updated after each poll */ + +#else + +EV_API_DECL int ev_default_loop (unsigned int flags EV_CPP (= 0)) EV_THROW; /* returns true when successful */ + +EV_API_DECL ev_tstamp ev_rt_now; + +EV_INLINE ev_tstamp +ev_now (void) EV_THROW +{ + return ev_rt_now; +} + +/* looks weird, but ev_is_default_loop (EV_A) still works if this exists */ +EV_INLINE int +ev_is_default_loop (void) EV_THROW +{ + return 1; +} + +#endif /* multiplicity */ + +/* destroy event loops, also works for the default loop */ +EV_API_DECL void ev_loop_destroy (EV_P); + +/* this needs to be called after fork, to duplicate the loop */ +/* when you want to re-use it in the child */ +/* you can call it in either the parent or the child */ +/* you can actually call it at any time, anywhere :) */ +EV_API_DECL void ev_loop_fork (EV_P) EV_THROW; + +EV_API_DECL unsigned int ev_backend (EV_P) EV_THROW; /* backend in use by loop */ + +EV_API_DECL void ev_now_update (EV_P) EV_THROW; /* update event loop time */ + +#if EV_WALK_ENABLE +/* walk (almost) all watchers in the loop of a given type, invoking the */ +/* callback on every such watcher. The callback might stop the watcher, */ +/* but do nothing else with the loop */ +EV_API_DECL void ev_walk (EV_P_ int types, void (*cb)(EV_P_ int type, void *w)) EV_THROW; +#endif + +#endif /* prototypes */ + +/* ev_run flags values */ +enum { + EVRUN_NOWAIT = 1, /* do not block/wait */ + EVRUN_ONCE = 2 /* block *once* only */ +}; + +/* ev_break how values */ +enum { + EVBREAK_CANCEL = 0, /* undo unloop */ + EVBREAK_ONE = 1, /* unloop once */ + EVBREAK_ALL = 2 /* unloop all loops */ +}; + +#if EV_PROTOTYPES +EV_API_DECL int ev_run (EV_P_ int flags EV_CPP (= 0)); +EV_API_DECL void ev_break (EV_P_ int how EV_CPP (= EVBREAK_ONE)) EV_THROW; /* break out of the loop */ + +/* + * ref/unref can be used to add or remove a refcount on the mainloop. every watcher + * keeps one reference. if you have a long-running watcher you never unregister that + * should not keep ev_loop from running, unref() after starting, and ref() before stopping. + */ +EV_API_DECL void ev_ref (EV_P) EV_THROW; +EV_API_DECL void ev_unref (EV_P) EV_THROW; + +/* + * convenience function, wait for a single event, without registering an event watcher + * if timeout is < 0, do wait indefinitely + */ +EV_API_DECL void ev_once (EV_P_ int fd, int events, ev_tstamp timeout, void (*cb)(int revents, void *arg), void *arg) EV_THROW; + +# if EV_FEATURE_API +EV_API_DECL unsigned int ev_iteration (EV_P) EV_THROW; /* number of loop iterations */ +EV_API_DECL unsigned int ev_depth (EV_P) EV_THROW; /* #ev_loop enters - #ev_loop leaves */ +EV_API_DECL void ev_verify (EV_P) EV_THROW; /* abort if loop data corrupted */ + +EV_API_DECL void ev_set_io_collect_interval (EV_P_ ev_tstamp interval) EV_THROW; /* sleep at least this time, default 0 */ +EV_API_DECL void ev_set_timeout_collect_interval (EV_P_ ev_tstamp interval) EV_THROW; /* sleep at least this time, default 0 */ + +/* advanced stuff for threading etc. support, see docs */ +EV_API_DECL void ev_set_userdata (EV_P_ void *data) EV_THROW; +EV_API_DECL void *ev_userdata (EV_P) EV_THROW; +typedef void (*ev_loop_callback)(EV_P); +EV_API_DECL void ev_set_invoke_pending_cb (EV_P_ ev_loop_callback invoke_pending_cb) EV_THROW; +/* C++ doesn't allow the use of the ev_loop_callback typedef here, so we need to spell it out */ +EV_API_DECL void ev_set_loop_release_cb (EV_P_ void (*release)(EV_P) EV_THROW, void (*acquire)(EV_P) EV_THROW) EV_THROW; + +EV_API_DECL unsigned int ev_pending_count (EV_P) EV_THROW; /* number of pending events, if any */ +EV_API_DECL void ev_invoke_pending (EV_P); /* invoke all pending watchers */ + +/* + * stop/start the timer handling. + */ +EV_API_DECL void ev_suspend (EV_P) EV_THROW; +EV_API_DECL void ev_resume (EV_P) EV_THROW; +#endif + +#endif + +/* these may evaluate ev multiple times, and the other arguments at most once */ +/* either use ev_init + ev_TYPE_set, or the ev_TYPE_init macro, below, to first initialise a watcher */ +#define ev_init(ev,cb_) do { \ + ((ev_watcher *)(void *)(ev))->active = \ + ((ev_watcher *)(void *)(ev))->pending = 0; \ + ev_set_priority ((ev), 0); \ + ev_set_cb ((ev), cb_); \ +} while (0) + +#define ev_io_set(ev,fd_,events_) do { (ev)->fd = (fd_); (ev)->events = (events_) | EV__IOFDSET; } while (0) +#define ev_timer_set(ev,after_,repeat_) do { ((ev_watcher_time *)(ev))->at = (after_); (ev)->repeat = (repeat_); } while (0) +#define ev_periodic_set(ev,ofs_,ival_,rcb_) do { (ev)->offset = (ofs_); (ev)->interval = (ival_); (ev)->reschedule_cb = (rcb_); } while (0) +#define ev_signal_set(ev,signum_) do { (ev)->signum = (signum_); } while (0) +#define ev_child_set(ev,pid_,trace_) do { (ev)->pid = (pid_); (ev)->flags = !!(trace_); } while (0) +#define ev_stat_set(ev,path_,interval_) do { (ev)->path = (path_); (ev)->interval = (interval_); (ev)->wd = -2; } while (0) +#define ev_idle_set(ev) /* nop, yes, this is a serious in-joke */ +#define ev_prepare_set(ev) /* nop, yes, this is a serious in-joke */ +#define ev_check_set(ev) /* nop, yes, this is a serious in-joke */ +#define ev_embed_set(ev,other_) do { (ev)->other = (other_); } while (0) +#define ev_fork_set(ev) /* nop, yes, this is a serious in-joke */ +#define ev_cleanup_set(ev) /* nop, yes, this is a serious in-joke */ +#define ev_async_set(ev) /* nop, yes, this is a serious in-joke */ + +#define ev_io_init(ev,cb,fd,events) do { ev_init ((ev), (cb)); ev_io_set ((ev),(fd),(events)); } while (0) +#define ev_timer_init(ev,cb,after,repeat) do { ev_init ((ev), (cb)); ev_timer_set ((ev),(after),(repeat)); } while (0) +#define ev_periodic_init(ev,cb,ofs,ival,rcb) do { ev_init ((ev), (cb)); ev_periodic_set ((ev),(ofs),(ival),(rcb)); } while (0) +#define ev_signal_init(ev,cb,signum) do { ev_init ((ev), (cb)); ev_signal_set ((ev), (signum)); } while (0) +#define ev_child_init(ev,cb,pid,trace) do { ev_init ((ev), (cb)); ev_child_set ((ev),(pid),(trace)); } while (0) +#define ev_stat_init(ev,cb,path,interval) do { ev_init ((ev), (cb)); ev_stat_set ((ev),(path),(interval)); } while (0) +#define ev_idle_init(ev,cb) do { ev_init ((ev), (cb)); ev_idle_set ((ev)); } while (0) +#define ev_prepare_init(ev,cb) do { ev_init ((ev), (cb)); ev_prepare_set ((ev)); } while (0) +#define ev_check_init(ev,cb) do { ev_init ((ev), (cb)); ev_check_set ((ev)); } while (0) +#define ev_embed_init(ev,cb,other) do { ev_init ((ev), (cb)); ev_embed_set ((ev),(other)); } while (0) +#define ev_fork_init(ev,cb) do { ev_init ((ev), (cb)); ev_fork_set ((ev)); } while (0) +#define ev_cleanup_init(ev,cb) do { ev_init ((ev), (cb)); ev_cleanup_set ((ev)); } while (0) +#define ev_async_init(ev,cb) do { ev_init ((ev), (cb)); ev_async_set ((ev)); } while (0) + +#define ev_is_pending(ev) (0 + ((ev_watcher *)(void *)(ev))->pending) /* ro, true when watcher is waiting for callback invocation */ +#define ev_is_active(ev) (0 + ((ev_watcher *)(void *)(ev))->active) /* ro, true when the watcher has been started */ + +#define ev_cb_(ev) (ev)->cb /* rw */ +#define ev_cb(ev) (memmove (&ev_cb_ (ev), &((ev_watcher *)(ev))->cb, sizeof (ev_cb_ (ev))), (ev)->cb) + +#if EV_MINPRI == EV_MAXPRI +# define ev_priority(ev) ((ev), EV_MINPRI) +# define ev_set_priority(ev,pri) ((ev), (pri)) +#else +# define ev_priority(ev) (+(((ev_watcher *)(void *)(ev))->priority)) +# define ev_set_priority(ev,pri) ( (ev_watcher *)(void *)(ev))->priority = (pri) +#endif + +#define ev_periodic_at(ev) (+((ev_watcher_time *)(ev))->at) + +#ifndef ev_set_cb +# define ev_set_cb(ev,cb_) (ev_cb_ (ev) = (cb_), memmove (&((ev_watcher *)(ev))->cb, &ev_cb_ (ev), sizeof (ev_cb_ (ev)))) +#endif + +/* stopping (enabling, adding) a watcher does nothing if it is already running */ +/* stopping (disabling, deleting) a watcher does nothing unless it's already running */ +#if EV_PROTOTYPES + +/* feeds an event into a watcher as if the event actually occurred */ +/* accepts any ev_watcher type */ +EV_API_DECL void ev_feed_event (EV_P_ void *w, int revents) EV_THROW; +EV_API_DECL void ev_feed_fd_event (EV_P_ int fd, int revents) EV_THROW; +#if EV_SIGNAL_ENABLE +EV_API_DECL void ev_feed_signal (int signum) EV_THROW; +EV_API_DECL void ev_feed_signal_event (EV_P_ int signum) EV_THROW; +#endif +EV_API_DECL void ev_invoke (EV_P_ void *w, int revents); +EV_API_DECL int ev_clear_pending (EV_P_ void *w) EV_THROW; + +EV_API_DECL void ev_io_start (EV_P_ ev_io *w) EV_THROW; +EV_API_DECL void ev_io_stop (EV_P_ ev_io *w) EV_THROW; + +EV_API_DECL void ev_timer_start (EV_P_ ev_timer *w) EV_THROW; +EV_API_DECL void ev_timer_stop (EV_P_ ev_timer *w) EV_THROW; +/* stops if active and no repeat, restarts if active and repeating, starts if inactive and repeating */ +EV_API_DECL void ev_timer_again (EV_P_ ev_timer *w) EV_THROW; +/* return remaining time */ +EV_API_DECL ev_tstamp ev_timer_remaining (EV_P_ ev_timer *w) EV_THROW; + +#if EV_PERIODIC_ENABLE +EV_API_DECL void ev_periodic_start (EV_P_ ev_periodic *w) EV_THROW; +EV_API_DECL void ev_periodic_stop (EV_P_ ev_periodic *w) EV_THROW; +EV_API_DECL void ev_periodic_again (EV_P_ ev_periodic *w) EV_THROW; +#endif + +/* only supported in the default loop */ +#if EV_SIGNAL_ENABLE +EV_API_DECL void ev_signal_start (EV_P_ ev_signal *w) EV_THROW; +EV_API_DECL void ev_signal_stop (EV_P_ ev_signal *w) EV_THROW; +#endif + +/* only supported in the default loop */ +# if EV_CHILD_ENABLE +EV_API_DECL void ev_child_start (EV_P_ ev_child *w) EV_THROW; +EV_API_DECL void ev_child_stop (EV_P_ ev_child *w) EV_THROW; +# endif + +# if EV_STAT_ENABLE +EV_API_DECL void ev_stat_start (EV_P_ ev_stat *w) EV_THROW; +EV_API_DECL void ev_stat_stop (EV_P_ ev_stat *w) EV_THROW; +EV_API_DECL void ev_stat_stat (EV_P_ ev_stat *w) EV_THROW; +# endif + +# if EV_IDLE_ENABLE +EV_API_DECL void ev_idle_start (EV_P_ ev_idle *w) EV_THROW; +EV_API_DECL void ev_idle_stop (EV_P_ ev_idle *w) EV_THROW; +# endif + +#if EV_PREPARE_ENABLE +EV_API_DECL void ev_prepare_start (EV_P_ ev_prepare *w) EV_THROW; +EV_API_DECL void ev_prepare_stop (EV_P_ ev_prepare *w) EV_THROW; +#endif + +#if EV_CHECK_ENABLE +EV_API_DECL void ev_check_start (EV_P_ ev_check *w) EV_THROW; +EV_API_DECL void ev_check_stop (EV_P_ ev_check *w) EV_THROW; +#endif + +# if EV_FORK_ENABLE +EV_API_DECL void ev_fork_start (EV_P_ ev_fork *w) EV_THROW; +EV_API_DECL void ev_fork_stop (EV_P_ ev_fork *w) EV_THROW; +# endif + +# if EV_CLEANUP_ENABLE +EV_API_DECL void ev_cleanup_start (EV_P_ ev_cleanup *w) EV_THROW; +EV_API_DECL void ev_cleanup_stop (EV_P_ ev_cleanup *w) EV_THROW; +# endif + +# if EV_EMBED_ENABLE +/* only supported when loop to be embedded is in fact embeddable */ +EV_API_DECL void ev_embed_start (EV_P_ ev_embed *w) EV_THROW; +EV_API_DECL void ev_embed_stop (EV_P_ ev_embed *w) EV_THROW; +EV_API_DECL void ev_embed_sweep (EV_P_ ev_embed *w) EV_THROW; +# endif + +# if EV_ASYNC_ENABLE +EV_API_DECL void ev_async_start (EV_P_ ev_async *w) EV_THROW; +EV_API_DECL void ev_async_stop (EV_P_ ev_async *w) EV_THROW; +EV_API_DECL void ev_async_send (EV_P_ ev_async *w) EV_THROW; +# endif + +#if EV_COMPAT3 + #define EVLOOP_NONBLOCK EVRUN_NOWAIT + #define EVLOOP_ONESHOT EVRUN_ONCE + #define EVUNLOOP_CANCEL EVBREAK_CANCEL + #define EVUNLOOP_ONE EVBREAK_ONE + #define EVUNLOOP_ALL EVBREAK_ALL + #if EV_PROTOTYPES + EV_INLINE void ev_loop (EV_P_ int flags) { ev_run (EV_A_ flags); } + EV_INLINE void ev_unloop (EV_P_ int how ) { ev_break (EV_A_ how ); } + EV_INLINE void ev_default_destroy (void) { ev_loop_destroy (EV_DEFAULT); } + EV_INLINE void ev_default_fork (void) { ev_loop_fork (EV_DEFAULT); } + #if EV_FEATURE_API + EV_INLINE unsigned int ev_loop_count (EV_P) { return ev_iteration (EV_A); } + EV_INLINE unsigned int ev_loop_depth (EV_P) { return ev_depth (EV_A); } + EV_INLINE void ev_loop_verify (EV_P) { ev_verify (EV_A); } + #endif + #endif +#else + typedef struct ev_loop ev_loop; +#endif + +#endif + +EV_CPP(}) + +#endif + diff --git a/libev/ev.pod b/libev/ev.pod new file mode 100644 index 0000000..429fe58 --- /dev/null +++ b/libev/ev.pod @@ -0,0 +1,5570 @@ +=encoding utf-8 + +=head1 NAME + +libev - a high performance full-featured event loop written in C + +=head1 SYNOPSIS + + #include + +=head2 EXAMPLE PROGRAM + + // a single header file is required + #include + + #include // for puts + + // every watcher type has its own typedef'd struct + // with the name ev_TYPE + ev_io stdin_watcher; + ev_timer timeout_watcher; + + // all watcher callbacks have a similar signature + // this callback is called when data is readable on stdin + static void + stdin_cb (EV_P_ ev_io *w, int revents) + { + puts ("stdin ready"); + // for one-shot events, one must manually stop the watcher + // with its corresponding stop function. + ev_io_stop (EV_A_ w); + + // this causes all nested ev_run's to stop iterating + ev_break (EV_A_ EVBREAK_ALL); + } + + // another callback, this time for a time-out + static void + timeout_cb (EV_P_ ev_timer *w, int revents) + { + puts ("timeout"); + // this causes the innermost ev_run to stop iterating + ev_break (EV_A_ EVBREAK_ONE); + } + + int + main (void) + { + // use the default event loop unless you have special needs + struct ev_loop *loop = EV_DEFAULT; + + // initialise an io watcher, then start it + // this one will watch for stdin to become readable + ev_io_init (&stdin_watcher, stdin_cb, /*STDIN_FILENO*/ 0, EV_READ); + ev_io_start (loop, &stdin_watcher); + + // initialise a timer watcher, then start it + // simple non-repeating 5.5 second timeout + ev_timer_init (&timeout_watcher, timeout_cb, 5.5, 0.); + ev_timer_start (loop, &timeout_watcher); + + // now wait for events to arrive + ev_run (loop, 0); + + // break was called, so exit + return 0; + } + +=head1 ABOUT THIS DOCUMENT + +This document documents the libev software package. + +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: L. + +While this document tries to be as complete as possible in documenting +libev, its usage and the rationale behind its design, it is not a tutorial +on event-based programming, nor will it introduce event-based programming +with libev. + +Familiarity with event based programming techniques in general is assumed +throughout this document. + +=head1 WHAT TO READ WHEN IN A HURRY + +This manual tries to be very detailed, but unfortunately, this also makes +it very long. If you just want to know the basics of libev, I suggest +reading L, then the L above and +look up the missing functions in L and the C and +C sections in L. + +=head1 ABOUT LIBEV + +Libev is an event loop: you register interest in certain events (such as a +file descriptor being readable or a timeout occurring), and it will manage +these event sources and provide your program with events. + +To do this, it must take more or less complete control over your process +(or thread) by executing the I handler, and will then +communicate events via a callback mechanism. + +You register interest in certain events by registering so-called I, which are relatively small C structures you initialise with the +details of the event, and then hand it over to libev by I the +watcher. + +=head2 FEATURES + +Libev supports C (files, many character devices...). + +Epoll is truly the train wreck among event poll mechanisms, a frankenpoll, +cobbled together in a hurry, no thought to design or interaction with +others. Oh, the pain, will it ever stop... + +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 I could point to a different +I now), so its best to avoid that. Also, C'ed +file descriptors might not work very well if you register events for both +file descriptors. + +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. + +All this means that, in practice, C can be as fast or +faster than epoll for maybe up to a hundred file descriptors, depending on +the usage. So sad. + +While nominally embeddable in other event loops, this feature is broken in +all kernel versions tested so far. + +This backend maps C and C in the same way as +C. + +=item C (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 API changes to existing programs. For this reason it's not being +"auto-detected" unless you explicitly specify it in the flags (i.e. using +C) or libev was compiled on a known-to-be-good (-enough) +system like NetBSD. + +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 C watchers for more info. + +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 C, it still adds up to +two event changes per incident. Support for C is very bad (you +might have to leak fd's on fork, but it's more sane than epoll) and it +drops fds silently in similarly hard-to-detect cases. + +This backend usually performs well under most conditions. + +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. C or C (but C is of course +also broken on OS X)) and, did I mention it, using it only for sockets. + +This backend maps C into an C kevent with +C, and C into an C kevent with +C. + +=item C (value 16, Solaris 8) + +This is not implemented yet (and might never be, unless you send me an +implementation). According to reports, C only supports sockets +and is not embeddable, which would limit the usefulness of this backend +immensely. + +=item C (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)). + +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 "slow" C or C backend +might perform better. + +On the positive side, this backend actually performed fully to +specification in all tests and is fully embeddable, which is a rare feat +among the OS-specific backends (I vastly prefer correctness over speed +hacks). + +On the negative side, the interface is I - so bizarre that +even sun itself gets it wrong in their code examples: The event polling +function sometimes returns events to the caller even though an error +occurred, but with no indication whether it has done so or not (yes, it's +even documented that way) - deadly for edge-triggered interfaces where you +absolutely have to know whether an event occurred or not because you have +to re-arm the watcher. + +Fortunately libev seems to be able to work around these idiocies. + +This backend maps C and C in the same way as +C. + +=item C + +Try all backends (even potentially broken ones that wouldn't be tried +with C). Since this is a mask, you can do stuff such as +C. + +It is definitely not recommended to use this flag, use whatever +C returns, or simply do not specify a backend +at all. + +=item C + +Not a backend at all, but a mask to select all backend bits from a +C value, in case you want to mask out any backends from a flags +value (e.g. when modifying the C environment variable). + +=back + +If one or more of the backend flags are or'ed into the flags value, +then only these backends will be tried (in the reverse order as listed +here). If none are specified, all backends in C will be tried. + +Example: Try to create a event loop that uses epoll and nothing else. + + struct ev_loop *epoller = ev_loop_new (EVBACKEND_EPOLL | EVFLAG_NOENV); + if (!epoller) + fatal ("no epoll found here, maybe it hides under your chair"); + +Example: Use whatever libev has to offer, but make sure that kqueue is +used if available. + + struct ev_loop *loop = ev_loop_new (ev_recommended_backends () | EVBACKEND_KQUEUE); + +=item ev_loop_destroy (loop) + +Destroys an event loop object (frees all memory and kernel state +etc.). None of the active event watchers will be stopped in the normal +sense, so e.g. C might still return true. It is your +responsibility to either stop all watchers cleanly yourself I +calling this function, or cope with the fact afterwards (which is usually +the easiest thing, you can just ignore the watchers and/or C them +for example). + +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. + +This function is normally used on loop objects allocated by +C, but it can also be used on the default loop returned by +C, in which case it is not thread-safe. + +Note that it is not advisable to call this function on the default loop +except in the rare occasion where you really need to free its resources. +If you need dynamically allocated loops it is better to use C +and C. + +=item ev_loop_fork (loop) + +This function sets a flag that causes subsequent C iterations +to reinitialise the kernel state for backends that have one. Despite +the name, you can call it anytime you are allowed to start or stop +watchers (except inside an C callback), but it makes most +sense after forking, in the child process. You I call it (or use +C) in the child before resuming or calling C. + +In addition, if you want to reuse a loop (via this function or +C), you I have to ignore C. + +Again, you I to call it on I loop that you want to re-use after +a fork, I. This is +because some kernel interfaces *cough* I *cough* do funny things +during fork. + +On the other hand, you only need to call this function in the child +process if and only if you want to use the event loop in the child. If +you just fork+exec or create a new loop in the child, you don't have to +call it at all (in fact, C is so badly broken that it makes a +difference, but libev will usually detect this case on its own and do a +costly reset of the backend). + +The function itself is quite fast and it's usually not a problem to call +it just in case after a fork. + +Example: Automate calling C on the default loop when +using pthreads. + + static void + post_fork_child (void) + { + ev_loop_fork (EV_DEFAULT); + } + + ... + pthread_atfork (0, 0, post_fork_child); + +=item int ev_is_default_loop (loop) + +Returns true when the given loop is, in fact, the default loop, and false +otherwise. + +=item unsigned int ev_iteration (loop) + +Returns the current iteration count for the event loop, which is identical +to the number of times libev did poll for new events. It starts at C<0> +and happily wraps around with enough iterations. + +This value can sometimes be useful as a generation counter of sorts (it +"ticks" the number of loop iterations), as it roughly corresponds with +C and C calls - and is incremented between the +prepare and check phases. + +=item unsigned int ev_depth (loop) + +Returns the number of times C was entered minus the number of +times C was exited normally, in other words, the recursion depth. + +Outside C, this number is zero. In a callback, this number is +C<1>, unless C was invoked recursively (or from another thread), +in which case it is higher. + +Leaving C abnormally (setjmp/longjmp, cancelling the thread, +throwing an exception etc.), doesn't count as "exit" - consider this +as a hint to avoid such ungentleman-like behaviour unless it's really +convenient, in which case it is fully supported. + +=item unsigned int ev_backend (loop) + +Returns one of the C flags indicating the event backend in +use. + +=item ev_tstamp ev_now (loop) + +Returns the current "event loop time", 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). + +=item ev_now_update (loop) + +Establishes the current time by querying the kernel, updating the time +returned by C in the progress. This is a costly operation and +is usually done automatically within C. + +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. + +See also L in the C section. + +=item ev_suspend (loop) + +=item ev_resume (loop) + +These two functions suspend and resume an event loop, for use when the +loop is not used for a while and timeouts should not be processed. + +A typical use case would be an interactive program such as a game: When +the user presses C<^Z> to suspend the game and resumes it an hour later it +would be best to handle timeouts as if no time had actually passed while +the program was suspended. This can be achieved by calling C +in your C handler, sending yourself a C and calling +C directly afterwards to resume timer processing. + +Effectively, all C watchers will be delayed by the time spend +between C and C, and all C watchers +will be rescheduled (that is, they will lose any events that would have +occurred while suspended). + +After calling C you B call I function on the +given loop other than C, and you B call C +without a previous call to C. + +Calling C/C has the side effect of updating the +event loop time (see C). + +=item bool ev_run (loop, int flags) + +Finally, this is it, the event handler. This function usually is called +after you have initialised all your watchers and you want to start +handling events. It will ask the operating system for any new events, call +the watcher callbacks, and then repeat the whole process indefinitely: This +is why event loops are called I. + +If the flags argument is specified as C<0>, it will keep handling events +until either no event watchers are active anymore or C was +called. + +The return value is false if there are no more active watchers (which +usually means "all jobs done" or "deadlock"), and true in all other cases +(which usually means " you should call C again"). + +Please note that an explicit C 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. + +This function is I exception-safe - you can break out of a +C call by calling C in a callback, throwing a C++ +exception and so on. This does not decrement the C value, nor +will it clear any outstanding C breaks. + +A flags value of C will look for new events, will handle +those events and any already outstanding ones, but will not wait and +block your process in case there are no events and will return after one +iteration of the loop. This is sometimes useful to poll and handle new +events while doing lengthy calculations, to keep the program responsive. + +A flags value of C 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. + +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 C"). However, a pair of C/C watchers is +usually a better approach for this kind of thing. + +Here are the gory details of what C does (this is for your +understanding, not a guarantee that things will work exactly like this in +future versions): + + - Increment loop depth. + - Reset the ev_break status. + - Before the first iteration, call any pending watchers. + LOOP: + - If EVFLAG_FORKCHECK was used, check for a fork. + - If a fork was detected (by any means), queue and call all fork watchers. + - Queue and call all prepare watchers. + - If ev_break was called, goto FINISH. + - If we have been forked, detach and recreate the kernel state + as to not disturb the other process. + - Update the kernel state with all outstanding changes. + - Update the "event loop time" (ev_now ()). + - Calculate for how long to sleep or block, if at all + (active idle watchers, EVRUN_NOWAIT or not having + any active watchers at all will result in not sleeping). + - Sleep if the I/O and timer collect interval say so. + - Increment loop iteration counter. + - Block the process, waiting for any events. + - Queue all outstanding I/O (fd) events. + - Update the "event loop time" (ev_now ()), and do time jump adjustments. + - Queue all expired timers. + - Queue all expired periodics. + - Queue all idle watchers with priority higher than that of pending events. + - Queue all check watchers. + - Call all queued watchers in reverse order (i.e. check watchers first). + Signals and child watchers are implemented as I/O watchers, and will + be handled here by queueing them when their watcher gets executed. + - If ev_break has been called, or EVRUN_ONCE or EVRUN_NOWAIT + were used, or there are no active watchers, goto FINISH, otherwise + continue with step LOOP. + FINISH: + - Reset the ev_break status iff it was EVBREAK_ONE. + - Decrement the loop depth. + - Return. + +Example: Queue some jobs and then loop until no events are outstanding +anymore. + + ... queue jobs here, make sure they register event watchers as long + ... as they still have work to do (even an idle watcher will do..) + ev_run (my_loop, 0); + ... jobs done or somebody called break. yeah! + +=item ev_break (loop, how) + +Can be used to make a call to C return early (but only after it +has processed all outstanding events). The C argument must be either +C, which will make the innermost C call return, or +C, which will make all nested C calls return. + +This "break state" will be cleared on the next call to C. + +It is safe to call C from outside any C calls, too, in +which case it will have no effect. + +=item ev_ref (loop) + +=item ev_unref (loop) + +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, C will not return on its own. + +This is useful when you have a watcher that you never intend to +unregister, but that nevertheless should not keep C from +returning. In such a case, call C after starting, and C +before stopping it. + +As an example, libev itself uses this for its internal signal pipe: It +is not visible to the libev user and should not keep C 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 I and I (but only if the watcher wasn't active before, or was active +before, respectively. Note also that libev might stop watchers itself +(e.g. non-repeating timers) in which case you have to C +in the callback). + +Example: Create a signal watcher, but keep it from keeping C +running when nothing else is active. + + ev_signal exitsig; + ev_signal_init (&exitsig, sig_cb, SIGINT); + ev_signal_start (loop, &exitsig); + ev_unref (loop); + +Example: For some weird reason, unregister the above signal handler again. + + ev_ref (loop); + ev_signal_stop (loop, &exitsig); + +=item ev_set_io_collect_interval (loop, ev_tstamp interval) + +=item ev_set_timeout_collect_interval (loop, ev_tstamp interval) + +These advanced functions influence the time that libev will spend waiting +for events. Both time intervals are by default C<0>, meaning that libev +will try to invoke timer/periodic callbacks and I/O callbacks with minimum +latency. + +Setting these to a higher value (the C I be >= C<0>) +allows libev to delay invocation of I/O and timer/periodic callbacks +to increase efficiency of loop iterations (or to increase power-saving +opportunities). + +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 CPU time to poll for new +events, especially with backends like C (or libev) on file descriptors +representing files, and expect it to become ready when their program +doesn't block on disk accesses (which can take a long time on their own). + +However, this cannot ever work in the "expected" way - you get a readiness +notification as soon as the kernel knows whether and how much data is +there, and in the case of open files, that's always the case, so you +always get a readiness notification instantly, and your read (or possibly +write) will still block on the disk I/O. + +Another way to view it is that in the case of sockets, pipes, character +devices and so on, there is another party (the sender) that delivers data +on its own, but in the case of files, there is no such thing: the disk +will not send data on its own, simply because it doesn't know what you +wish to read - you would first have to request some data. + +Since files are typically not-so-well supported by advanced notification +mechanism, libev tries hard to emulate POSIX behaviour with respect +to files, even though you should not use it. The reason for this is +convenience: sometimes you want to watch STDIN or STDOUT, which is +usually a tty, often a pipe, but also sometimes files or special devices +(for example, C on Linux works with F but not with +F), and even though the file might better be served with +asynchronous I/O instead of with non-blocking I/O, it is still useful when +it "just works" instead of freezing. + +So avoid file descriptors pointing to files when you know it (e.g. use +libeio), but use them when it is convenient, e.g. for STDIN/STDOUT, or +when you rarely read from a file instead of from a socket, and want to +reuse the same code path. + +=head3 The special problem of fork + +Some backends (epoll, kqueue) do not support C at all or exhibit +useless behaviour. Libev fully supports fork, but needs to be told about +it in the child if you want to continue to use it in the child. + +To support fork in your child processes, you have to call C after a fork in the child, enable C, or resort to +C or C. + +=head3 The special problem of SIGPIPE + +While not really specific to libev, it is easy to forget about C: +when writing to a pipe whose other end has been closed, your program gets +sent a SIGPIPE, which, by default, aborts your program. For most programs +this is sensible behaviour, for daemons, this is usually undesirable. + +So when you encounter spurious, unexplained daemon exits, make sure you +ignore SIGPIPE (and maybe make sure you log the exit status of your daemon +somewhere, as that would have given you a big clue). + +=head3 The special problem of accept()ing when you can't + +Many implementations of the POSIX C function (for example, +found in post-2004 Linux) have the peculiar behaviour of not removing a +connection from the pending queue in all error cases. + +For example, larger servers often run out of file descriptors (because +of resource limits), causing C to fail with C but not +rejecting the connection, leading to libev signalling readiness on +the next iteration again (the connection still exists after all), and +typically causing the program to loop at 100% CPU usage. + +Unfortunately, the set of errors that cause this issue differs between +operating systems, there is usually little the app can do to remedy the +situation, and no known thread-safe method of removing the connection to +cope with overload is known (to me). + +One of the easiest ways to handle this situation is to just ignore it +- when the program encounters an overload, it will just loop until the +situation is over. While this is a form of busy waiting, no OS offers an +event-based way to handle this situation, so it's the best one can do. + +A better way to handle the situation is to log any errors other than +C and C, making sure not to flood the log with such +messages, and continue as usual, which at least gives the user an idea of +what could be wrong ("raise the ulimit!"). For extra points one could stop +the C watcher on the listening fd "for a while", which reduces CPU +usage. + +If your program is single-threaded, then you could also keep a dummy file +descriptor for overload situations (e.g. by opening F), and +when you run into C or C, close it, run C, +close that fd, and create a new dummy fd. This will gracefully refuse +clients under typical overload conditions. + +The last way to handle it is to simply log the error and C, as +is often done with C failures, but this results in an easy +opportunity for a DoS attack. + +=head3 Watcher-Specific Functions + +=over 4 + +=item ev_io_init (ev_io *, callback, int fd, int events) + +=item ev_io_set (ev_io *, int fd, int events) + +Configures an C watcher. The C is the file descriptor to +receive events for and C is either C, C or +C, to express the desire to receive the given events. + +=item int fd [read-only] + +The file descriptor being watched. + +=item int events [read-only] + +The events being watched. + +=back + +=head3 Examples + +Example: Call C when STDIN_FILENO has become, well +readable, but only once. Since it is likely line-buffered, you could +attempt to read a whole line in the callback. + + static void + stdin_readable_cb (struct ev_loop *loop, ev_io *w, int revents) + { + ev_io_stop (loop, w); + .. read from stdin here (or from w->fd) and handle any I/O errors + } + + ... + struct ev_loop *loop = ev_default_init (0); + ev_io stdin_readable; + ev_io_init (&stdin_readable, stdin_readable_cb, STDIN_FILENO, EV_READ); + ev_io_start (loop, &stdin_readable); + ev_run (loop, 0); + + +=head2 C - 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. + +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. "Roughly" because +detecting time jumps is hard, and some inaccuracies are unavoidable (the +monotonic clock option helps a lot here). + +The callback is guaranteed to be invoked only I its timeout has +passed (not I, so on systems with very low-resolution clocks this +might introduce a small delay, see "the special problem of being too +early", below). If multiple timers become ready during the same loop +iteration then the ones with earlier time-out values are invoked before +ones of the same priority with later time-out values (but this is no +longer true when a callback calls C recursively). + +=head3 Be smart about timeouts + +Many real-world problems involve some kind of timeout, usually for error +recovery. A typical example is an HTTP request - if the other side hangs, +you want to raise some error after a while. + +What follows are some ways to handle this problem, from obvious and +inefficient to smart and efficient. + +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). + +=over 4 + +=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: + + ev_timer_init (timer, callback, 60., 0.); + ev_timer_start (loop, timer); + +Then, each time there is some activity, C it, initialise it +and start it again: + + ev_timer_stop (loop, timer); + ev_timer_set (timer, 60., 0.); + ev_timer_start (loop, timer); + +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. + +=item 2. Use a timer and re-start it with C inactivity. + +This is the easiest way, and involves using C instead of +C. + +To implement this, configure an C with a C value +of C<60> and then call C 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 C +the timer, and C will automatically restart it if need be. + +That means you can ignore both the C function and the +C argument to C, and only ever use the C +member and C. + +At start: + + ev_init (timer, callback); + timer->repeat = 60.; + ev_timer_again (loop, timer); + +Each time there is some activity: + + ev_timer_again (loop, timer); + +It is even possible to change the time-out on the fly, regardless of +whether the watcher is active or not: + + timer->repeat = 30.; + ev_timer_again (loop, timer); + +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. + +It is, however, even simpler than the "obvious" way to do it. + +=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. + +In this case, it would be more efficient to leave the C alone, +but remember the time of last activity, and check for a real timeout only +within the callback: + + ev_tstamp timeout = 60.; + ev_tstamp last_activity; // time of last activity + ev_timer timer; + + static void + callback (EV_P_ ev_timer *w, int revents) + { + // calculate when the timeout would happen + ev_tstamp after = last_activity - ev_now (EV_A) + timeout; + + // if negative, it means we the timeout already occurred + if (after < 0.) + { + // timeout occurred, take action + } + else + { + // callback was invoked, but there was some recent + // activity. simply restart the timer to time out + // after "after" seconds, which is the earliest time + // the timeout can occur. + ev_timer_set (w, after, 0.); + ev_timer_start (EV_A_ w); + } + } + +To summarise the callback: first calculate in how many seconds the +timeout will occur (by calculating the absolute time when it would occur, +C, and subtracting the current time, C from that). + +If this value is negative, then we are already past the timeout, i.e. we +timed out, and need to do whatever is needed in this case. + +Otherwise, we now the earliest time at which the timeout would trigger, +and simply start the timer with this timeout value. + +In other words, each time the callback is invoked it will check whether +the timeout occurred. If not, it will simply reschedule itself to check +again at the earliest time it could time out. Rinse. Repeat. + +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. + +To start the machinery, simply initialise the watcher and set +C to the current time (meaning there was some activity just +now), then call the callback, which will "do the right thing" and start +the timer: + + last_activity = ev_now (EV_A); + ev_init (&timer, callback); + callback (EV_A_ &timer, 0); + +When there is some activity, simply store the current time in +C, no libev calls at all: + + if (activity detected) + last_activity = ev_now (EV_A); + +When your timeout value changes, then the timeout can be changed by simply +providing a new value, stopping the timer and calling the callback, which +will again do the right thing (for example, time out immediately :). + + timeout = new_value; + ev_timer_stop (EV_A_ &timer); + callback (EV_A_ &timer, 0); + +This technique is slightly more complex, but in most cases where the +time-out is unlikely to be triggered, much more efficient. + +=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: + +When starting the timeout, calculate the timeout value and put the timeout +at the I of the list. + +Then use an C to fire when the timeout at the I of +the list is expected to fire (for example, using the technique #3). + +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 C if it was taken from the beginning of the list. + +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. + +=back + +So which method the best? + +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. + +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 :) + +=head3 The special problem of being too early + +If you ask a timer to call your callback after three seconds, then +you expect it to be invoked after three seconds - but of course, this +cannot be guaranteed to infinite precision. Less obviously, it cannot be +guaranteed to any precision by libev - imagine somebody suspending the +process with a STOP signal for a few hours for example. + +So, libev tries to invoke your callback as soon as possible I the +delay has occurred, but cannot guarantee this. + +A less obvious failure mode is calling your callback too early: many event +loops compare timestamps with a "elapsed delay >= requested delay", but +this can cause your callback to be invoked much earlier than you would +expect. + +To see why, imagine a system with a clock that only offers full second +resolution (think windows if you can't come up with a broken enough OS +yourself). If you schedule a one-second timer at the time 500.9, then the +event loop will schedule your timeout to elapse at a system time of 500 +(500.9 truncated to the resolution) + 1, or 501. + +If an event library looks at the timeout 0.1s later, it will see "501 >= +501" and invoke the callback 0.1s after it was started, even though a +one-second delay was requested - this is being "too early", despite best +intentions. + +This is the reason why libev will never invoke the callback if the elapsed +delay equals the requested delay, but only when the elapsed delay is +larger than the requested delay. In the example above, libev would only invoke +the callback at system time 502, or 1.1s after the timer was started. + +So, while libev cannot guarantee that your callback will be invoked +exactly when requested, it I and I guarantee that the requested +delay has actually elapsed, or in other words, it always errs on the "too +late" side of things. + +=head3 The special problem of time updates + +Establishing the current time is a costly operation (it usually takes +at least one system call): EV therefore updates its idea of the current +time only before and after C collects new events, which causes a +growing difference between C and C when handling +lots of events in one iteration. + +The relative timeouts are calculated relative to the C +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 I to base the +timeout on the current time, use something like the following to adjust +for it: + + ev_timer_set (&timer, after + (ev_time () - ev_now ()), 0.); + +If the event loop is suspended for a long time, you can also force an +update of the time returned by C by calling C, although that will push the event time of all outstanding events +further into the future. + +=head3 The special problem of unsynchronised clocks + +Modern systems have a variety of clocks - libev itself uses the normal +"wall clock" clock and, if available, the monotonic clock (to avoid time +jumps). + +Neither of these clocks is synchronised with each other or any other clock +on the system, so C might return a considerably different time +than C or C