+<h1 id="MACRO_MAGIC">MACRO MAGIC</h1>
+<div id="MACRO_MAGIC_CONTENT">
+<p>Libev can be compiled with a variety of options, the most fundemantal is
+<code>EV_MULTIPLICITY</code>. This option determines whether (most) functions and
+callbacks have an initial <code>struct ev_loop *</code> argument.</p>
+<p>To make it easier to write programs that cope with either variant, the
+following macros are defined:</p>
+<dl>
+ <dt><code>EV_A</code>, <code>EV_A_</code></dt>
+ <dd>
+ <p>This provides the loop <i>argument</i> for functions, if one is required ("ev
+loop argument"). The <code>EV_A</code> form is used when this is the sole argument,
+<code>EV_A_</code> is used when other arguments are following. Example:</p>
+<pre> ev_unref (EV_A);
+ ev_timer_add (EV_A_ watcher);
+ ev_loop (EV_A_ 0);
+
+</pre>
+ <p>It assumes the variable <code>loop</code> of type <code>struct ev_loop *</code> is in scope,
+which is often provided by the following macro.</p>
+ </dd>
+ <dt><code>EV_P</code>, <code>EV_P_</code></dt>
+ <dd>
+ <p>This provides the loop <i>parameter</i> for functions, if one is required ("ev
+loop parameter"). The <code>EV_P</code> form is used when this is the sole parameter,
+<code>EV_P_</code> is used when other parameters are following. Example:</p>
+<pre> // 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)
+
+</pre>
+ <p>It declares a parameter <code>loop</code> of type <code>struct ev_loop *</code>, quite
+suitable for use with <code>EV_A</code>.</p>
+ </dd>
+ <dt><code>EV_DEFAULT</code>, <code>EV_DEFAULT_</code></dt>
+ <dd>
+ <p>Similar to the other two macros, this gives you the value of the default
+loop, if multiple loops are supported ("ev loop default").</p>
+ </dd>
+</dl>
+<p>Example: Declare and initialise a check watcher, utilising the above
+macros so it will work regardless of whether multiple loops are supported
+or not.</p>
+<pre> static void
+ check_cb (EV_P_ ev_timer *w, int revents)
+ {
+ ev_check_stop (EV_A_ w);
+ }
+
+ ev_check check;
+ ev_check_init (&check, check_cb);
+ ev_check_start (EV_DEFAULT_ &check);
+ ev_loop (EV_DEFAULT_ 0);
+
+</pre>
+
+</div>
+<h1 id="EMBEDDING">EMBEDDING</h1>
+<div id="EMBEDDING_CONTENT">
+<p>Libev can (and often is) directly embedded into host
+applications. Examples of applications that embed it include the Deliantra
+Game Server, the EV perl module, the GNU Virtual Private Ethernet (gvpe)
+and rxvt-unicode.</p>
+<p>The goal is to enable you to just copy the neecssary 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).</p>
+
+</div>
+<h2 id="FILESETS">FILESETS</h2>
+<div id="FILESETS_CONTENT">
+<p>Depending on what features you need you need to include one or more sets of files
+in your app.</p>
+
+</div>
+<h3 id="CORE_EVENT_LOOP">CORE EVENT LOOP</h3>
+<div id="CORE_EVENT_LOOP_CONTENT">
+<p>To include only the libev core (all the <code>ev_*</code> functions), with manual
+configuration (no autoconf):</p>
+<pre> #define EV_STANDALONE 1
+ #include "ev.c"
+
+</pre>
+<p>This will automatically include <cite>ev.h</cite>, too, and should be done in a
+single C source file only to provide the function implementations. To use
+it, do the same for <cite>ev.h</cite> in all files wishing to use this API (best
+done by writing a wrapper around <cite>ev.h</cite> that you can include instead and
+where you can put other configuration options):</p>
+<pre> #define EV_STANDALONE 1
+ #include "ev.h"
+
+</pre>
+<p>Both header files and implementation files can be compiled with a C++
+compiler (at least, thats a stated goal, and breakage will be treated
+as a bug).</p>
+<p>You need the following files in your source tree, or in a directory
+in your include path (e.g. in libev/ when using -Ilibev):</p>
+<pre> ev.h
+ ev.c
+ ev_vars.h
+ ev_wrap.h
+
+ ev_win32.c required on win32 platforms only
+
+ ev_select.c only when select backend is enabled (which is enabled by default)
+ ev_poll.c only when poll backend is enabled (disabled by default)
+ ev_epoll.c only when the epoll backend is enabled (disabled by default)
+ ev_kqueue.c only when the kqueue backend is enabled (disabled by default)
+ ev_port.c only when the solaris port backend is enabled (disabled by default)
+
+</pre>
+<p><cite>ev.c</cite> includes the backend files directly when enabled, so you only need
+to compile this single file.</p>
+
+</div>
+<h3 id="LIBEVENT_COMPATIBILITY_API">LIBEVENT COMPATIBILITY API</h3>
+<div id="LIBEVENT_COMPATIBILITY_API_CONTENT">
+<p>To include the libevent compatibility API, also include:</p>
+<pre> #include "event.c"
+
+</pre>
+<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>
+
+
+
+
+
+</div>
+<h1 id="AUTHOR">AUTHOR</h1>
projects / software / libev.git / blobdiff