+<p>in the file including <cite>ev.c</cite>, and:</p>
+<pre> #include "event.h"
+
+</pre>
+<p>in the files that want to use the libevent API. This also includes <cite>ev.h</cite>.</p>
+<p>You need the following additional files for this:</p>
+<pre> event.h
+ event.c
+
+</pre>
+
+</div>
+<h3 id="AUTOCONF_SUPPORT">AUTOCONF SUPPORT</h3>
+<div id="AUTOCONF_SUPPORT_CONTENT">
+<p>Instead of using <code>EV_STANDALONE=1</code> and providing your config in
+whatever way you want, you can also <code>m4_include([libev.m4])</code> in your
+<cite>configure.ac</cite> and leave <code>EV_STANDALONE</code> undefined. <cite>ev.c</cite> will then
+include <cite>config.h</cite> and configure itself accordingly.</p>
+<p>For this of course you need the m4 file:</p>
+<pre> libev.m4
+
+</pre>
+
+</div>
+<h2 id="PREPROCESSOR_SYMBOLS_MACROS">PREPROCESSOR SYMBOLS/MACROS</h2>
+<div id="PREPROCESSOR_SYMBOLS_MACROS_CONTENT">
+<p>Libev can be configured via a variety of preprocessor symbols you have to define
+before including any of its files. The default is not to build for multiplicity
+and only include the select backend.</p>
+<dl>
+ <dt>EV_STANDALONE</dt>
+ <dd>
+ <p>Must always be <code>1</code> if you do not use autoconf configuration, which
+keeps libev from including <cite>config.h</cite>, 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
+<cite>event.h</cite> that are not directly supported by the libev core alone.</p>
+ </dd>
+ <dt>EV_USE_MONOTONIC</dt>
+ <dd>
+ <p>If defined to be <code>1</code>, libev will try to detect the availability of the
+monotonic clock option at both compiletime 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, althoguh you have
+to make sure you link against any libraries where the <code>clock_gettime</code>
+function is hiding in (often <cite>-lrt</cite>).</p>
+ </dd>
+ <dt>EV_USE_REALTIME</dt>
+ <dd>
+ <p>If defined to be <code>1</code>, libev will try to detect the availability of the
+realtime clock option at compiletime (and assume its availability at
+runtime if successful). Otherwise no use of the realtime clock option will
+be attempted. This effectively replaces <code>gettimeofday</code> by <code>clock_get
+(CLOCK_REALTIME, ...)</code> and will not normally affect correctness. See tzhe note about libraries
+in the description of <code>EV_USE_MONOTONIC</code>, though.</p>
+ </dd>
+ <dt>EV_USE_SELECT</dt>
+ <dd>
+ <p>If undefined or defined to be <code>1</code>, libev will compile in support for the
+<code>select</code>(2) backend. No attempt at autodetection will be done: if no
+other method takes over, select will be it. Otherwise the select backend
+will not be compiled in.</p>
+ </dd>
+ <dt>EV_SELECT_USE_FD_SET</dt>
+ <dd>
+ <p>If defined to <code>1</code>, then the select backend will use the system <code>fd_set</code>
+structure. This is useful if libev doesn't compile due to a missing
+<code>NFDBITS</code> or <code>fd_mask</code> definition or it misguesses 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 <code>FD_SETSIZE</code> macro, set before compilation, might
+influence the size of the <code>fd_set</code> used.</p>
+ </dd>
+ <dt>EV_SELECT_IS_WINSOCKET</dt>
+ <dd>
+ <p>When defined to <code>1</code>, 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
+<code>_get_osfhandle</code> on the fd to convert it to an OS handle. Otherwise,
+it is assumed that all these functions actually work on fds, even
+on win32. Should not be defined on non-win32 platforms.</p>
+ </dd>
+ <dt>EV_USE_POLL</dt>
+ <dd>
+ <p>If defined to be <code>1</code>, libev will compile in support for the <code>poll</code>(2)
+backend. Otherwise it will be enabled on non-win32 platforms. It
+takes precedence over select.</p>
+ </dd>
+ <dt>EV_USE_EPOLL</dt>
+ <dd>
+ <p>If defined to be <code>1</code>, libev will compile in support for the Linux
+<code>epoll</code>(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.</p>
+ </dd>
+ <dt>EV_USE_KQUEUE</dt>
+ <dd>
+ <p>If defined to be <code>1</code>, libev will compile in support for the BSD style
+<code>kqueue</code>(2) backend. Its actual availability will be detected at runtime,
+otherwise another method will be used as fallback. This is the preferred
+backend for BSD 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.</p>
+ </dd>
+ <dt>EV_USE_PORT</dt>
+ <dd>
+ <p>If defined to be <code>1</code>, 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.</p>
+ </dd>
+ <dt>EV_USE_DEVPOLL</dt>
+ <dd>
+ <p>reserved for future expansion, works like the USE symbols above.</p>
+ </dd>
+ <dt>EV_USE_INOTIFY</dt>
+ <dd>
+ <p>If defined to be <code>1</code>, libev will compile in support for the Linux inotify
+interface to speed up <code>ev_stat</code> watchers. Its actual availability will
+be detected at runtime.</p>
+ </dd>
+ <dt>EV_H</dt>
+ <dd>
+ <p>The name of the <cite>ev.h</cite> header file used to include it. The default if
+undefined is <code><ev.h></code> in <cite>event.h</cite> and <code>"ev.h"</code> in <cite>ev.c</cite>. This
+can be used to virtually rename the <cite>ev.h</cite> header file in case of conflicts.</p>
+ </dd>
+ <dt>EV_CONFIG_H</dt>
+ <dd>
+ <p>If <code>EV_STANDALONE</code> isn't <code>1</code>, this variable can be used to override
+<cite>ev.c</cite>'s idea of where to find the <cite>config.h</cite> file, similarly to
+<code>EV_H</code>, above.</p>
+ </dd>
+ <dt>EV_EVENT_H</dt>
+ <dd>
+ <p>Similarly to <code>EV_H</code>, this macro can be used to override <cite>event.c</cite>'s idea
+of how the <cite>event.h</cite> header can be found.</p>
+ </dd>
+ <dt>EV_PROTOTYPES</dt>
+ <dd>
+ <p>If defined to be <code>0</code>, then <cite>ev.h</cite> 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.</p>
+ </dd>
+ <dt>EV_MULTIPLICITY</dt>
+ <dd>
+ <p>If undefined or defined to <code>1</code>, then all event-loop-specific functions
+will have the <code>struct ev_loop *</code> 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.</p>
+ </dd>
+ <dt>EV_MINPRI</dt>
+ <dt>EV_MAXPRI</dt>
+ <dd>
+ <p>The range of allowed priorities. <code>EV_MINPRI</code> must be smaller or equal to
+<code>EV_MAXPRI</code>, but otherwise there are no non-obvious limitations. You can
+provide for more priorities by overriding those symbols (usually defined
+to be <code>-2</code> and <code>2</code>, respectively).</p>
+ <p>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.</p>
+ <p>If your embedding app does not need any priorities, defining these both to
+<code>0</code> will save some memory and cpu.</p>
+ </dd>
+ <dt>EV_PERIODIC_ENABLE</dt>
+ <dd>
+ <p>If undefined or defined to be <code>1</code>, then periodic timers are supported. If
+defined to be <code>0</code>, then they are not. Disabling them saves a few kB of
+code.</p>
+ </dd>
+ <dt>EV_IDLE_ENABLE</dt>
+ <dd>
+ <p>If undefined or defined to be <code>1</code>, then idle watchers are supported. If
+defined to be <code>0</code>, then they are not. Disabling them saves a few kB of
+code.</p>
+ </dd>
+ <dt>EV_EMBED_ENABLE</dt>
+ <dd>
+ <p>If undefined or defined to be <code>1</code>, then embed watchers are supported. If
+defined to be <code>0</code>, then they are not.</p>
+ </dd>
+ <dt>EV_STAT_ENABLE</dt>
+ <dd>
+ <p>If undefined or defined to be <code>1</code>, then stat watchers are supported. If
+defined to be <code>0</code>, then they are not.</p>
+ </dd>
+ <dt>EV_FORK_ENABLE</dt>
+ <dd>
+ <p>If undefined or defined to be <code>1</code>, then fork watchers are supported. If
+defined to be <code>0</code>, then they are not.</p>
+ </dd>
+ <dt>EV_MINIMAL</dt>
+ <dd>
+ <p>If you need to shave off some kilobytes of code at the expense of some
+speed, define this symbol to <code>1</code>. Currently only used for gcc to override
+some inlining decisions, saves roughly 30% codesize of amd64.</p>
+ </dd>
+ <dt>EV_PID_HASHSIZE</dt>
+ <dd>
+ <p><code>ev_child</code> watchers use a small hash table to distribute workload by
+pid. The default size is <code>16</code> (or <code>1</code> with <code>EV_MINIMAL</code>), usually more
+than enough. If you need to manage thousands of children you might want to
+increase this value (<i>must</i> be a power of two).</p>
+ </dd>
+ <dt>EV_INOTIFY_HASHSIZE</dt>
+ <dd>
+ <p><code>ev_staz</code> watchers use a small hash table to distribute workload by
+inotify watch id. The default size is <code>16</code> (or <code>1</code> with <code>EV_MINIMAL</code>),
+usually more than enough. If you need to manage thousands of <code>ev_stat</code>
+watchers you might want to increase this value (<i>must</i> be a power of
+two).</p>
+ </dd>
+ <dt>EV_COMMON</dt>
+ <dd>
+ <p>By default, all watchers have a <code>void *data</code> member. By redefining
+this macro to a 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.</p>
+ <p>For example, the perl EV module uses something like this:</p>
+<pre> #define EV_COMMON \
+ SV *self; /* contains this struct */ \
+ SV *cb_sv, *fh /* note no trailing ";" */
+
+</pre>
+ </dd>
+ <dt>EV_CB_DECLARE (type)</dt>
+ <dt>EV_CB_INVOKE (watcher, revents)</dt>
+ <dt>ev_set_cb (ev, cb)</dt>
+ <dd>
+ <p>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 <cite>ev.v</cite> header file for
+their default definitions. One possible use for overriding these is to
+avoid the <code>struct ev_loop *</code> as first argument in all cases, or to use
+method calls instead of plain function calls in C++.</p>
+
+</div>
+<h2 id="EXAMPLES">EXAMPLES</h2>
+<div id="EXAMPLES_CONTENT">
+ <p>For a real-world example of a program the includes libev
+verbatim, you can have a look at the EV perl module
+(<a href="http://software.schmorp.de/pkg/EV.html">http://software.schmorp.de/pkg/EV.html</a>). It has the libev files in
+the <cite>libev/</cite> subdirectory and includes them in the <cite>EV/EVAPI.h</cite> (public
+interface) and <cite>EV.xs</cite> (implementation) files. Only the <cite>EV.xs</cite> file
+will be compiled. It is pretty complex because it provides its own header
+file.</p>
+ <p>The usage in rxvt-unicode is simpler. It has a <cite>ev_cpp.h</cite> header file
+that everybody includes and which overrides some configure choices:</p>
+<pre> #define EV_MINIMAL 1
+ #define EV_USE_POLL 0
+ #define EV_MULTIPLICITY 0
+ #define EV_PERIODIC_ENABLE 0
+ #define EV_STAT_ENABLE 0
+ #define EV_FORK_ENABLE 0
+ #define EV_CONFIG_H <config.h>
+ #define EV_MINPRI 0
+ #define EV_MAXPRI 0
+
+ #include "ev++.h"
+
+</pre>
+ <p>And a <cite>ev_cpp.C</cite> implementation file that contains libev proper and is compiled:</p>
+<pre> #include "ev_cpp.h"
+ #include "ev.c"
+
+
+
+
+</pre>
+
+</div>
+<h1 id="COMPLEXITIES">COMPLEXITIES</h1>
+<div id="COMPLEXITIES_CONTENT">
+ <p>In this section the complexities of (many of) the algorithms used inside
+libev will be explained. For complexity discussions about backends see the
+documentation for <code>ev_default_init</code>.</p>
+ <p>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 never with higher number of elements, so O(1) might
+mean it might do a lengthy realloc operation in rare cases, but on average
+it is much faster and asymptotically approaches constant time.</p>
+ <p>
+ <dl>
+ <dt>Starting and stopping timer/periodic watchers: O(log skipped_other_timers)</dt>
+ <dd>
+ <p>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 those 100 watchers.</p>
+ </dd>
+ <dt>Changing timer/periodic watchers (by autorepeat, again): O(log skipped_other_timers)</dt>
+ <dd>
+ <p>That means that for changing a timer costs less than removing/adding them
+as only the relative motion in the event queue has to be paid for.</p>
+ </dd>
+ <dt>Starting io/check/prepare/idle/signal/child watchers: O(1)</dt>
+ <dd>
+ <p>These just add the watcher into an array or at the head of a list.
+=item Stopping check/prepare/idle watchers: O(1)</p>
+ </dd>
+ <dt>Stopping an io/signal/child watcher: O(number_of_watchers_for_this_(fd/signal/pid % EV_PID_HASHSIZE))</dt>
+ <dd>
+ <p>These watchers are stored in lists then 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).</p>
+ </dd>
+ <dt>Finding the next timer per loop iteration: O(1)</dt>
+ <dt>Each change on a file descriptor per loop iteration: O(number_of_watchers_for_this_fd)</dt>
+ <dd>
+ <p>A change means an I/O watcher gets started or stopped, which requires
+libev to recalculate its status (and possibly tell the kernel).</p>
+ </dd>
+ <dt>Activating one watcher: O(1)</dt>
+ <dt>Priority handling: O(number_of_priorities)</dt>
+ <dd>
+ <p>Priorities are implemented by allocating some space for each
+priority. When doing priority-based operations, libev usually has to
+linearly search all the priorities.</p>
+ </dd>
+ </dl>
+ </p>
+
+
+
+
projects / software / libev.git / blobdiff