+
+
+
+
+</div>
+<h1 id="LIBEVENT_EMULATION">LIBEVENT EMULATION</h1><p><a href="#TOP" class="toplink">Top</a></p>
+<div id="LIBEVENT_EMULATION_CONTENT">
+<p>Libev offers a compatibility emulation layer for libevent. It cannot
+emulate the internals of libevent, so here are some usage hints:</p>
+<dl>
+ <dt>* Use it by including <event.h>, as usual.</dt>
+ <dt>* The following members are fully supported: ev_base, ev_callback,
+ev_arg, ev_fd, ev_res, ev_events.</dt>
+ <dt>* 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 API).</dt>
+ <dt>* 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.</dt>
+ <dt>* Other members are not supported.</dt>
+ <dt>* The libev emulation is <i>not</i> ABI compatible to libevent, you need
+to use the libev header file and library.</dt>
+</dl>
+
+</div>
+<h1 id="C_SUPPORT">C++ SUPPORT</h1><p><a href="#TOP" class="toplink">Top</a></p>
+<div id="C_SUPPORT_CONTENT">
+<p>Libev comes with some simplistic wrapper classes for C++ that mainly allow
+you to use some convinience methods to start/stop watchers and also change
+the callback model to a model using method callbacks on objects.</p>
+<p>To use it,</p>
+<pre> #include <ev++.h>
+
+</pre>
+<p>(it is not installed by default). This automatically includes <cite>ev.h</cite>
+and puts all of its definitions (many of them macros) into the global
+namespace. All C++ specific things are put into the <code>ev</code> namespace.</p>
+<p>It should support all the same embedding options as <cite>ev.h</cite>, most notably
+<code>EV_MULTIPLICITY</code>.</p>
+<p>Here is a list of things available in the <code>ev</code> namespace:</p>
+<dl>
+ <dt><code>ev::READ</code>, <code>ev::WRITE</code> etc.</dt>
+ <dd>
+ <p>These are just enum values with the same values as the <code>EV_READ</code> etc.
+macros from <cite>ev.h</cite>.</p>
+ </dd>
+ <dt><code>ev::tstamp</code>, <code>ev::now</code></dt>
+ <dd>
+ <p>Aliases to the same types/functions as with the <code>ev_</code> prefix.</p>
+ </dd>
+ <dt><code>ev::io</code>, <code>ev::timer</code>, <code>ev::periodic</code>, <code>ev::idle</code>, <code>ev::sig</code> etc.</dt>
+ <dd>
+ <p>For each <code>ev_TYPE</code> watcher in <cite>ev.h</cite> there is a corresponding class of
+the same name in the <code>ev</code> namespace, with the exception of <code>ev_signal</code>
+which is called <code>ev::sig</code> to avoid clashes with the <code>signal</code> macro
+defines by many implementations.</p>
+ <p>All of those classes have these methods:</p>
+ <p>
+ <dl>
+ <dt>ev::TYPE::TYPE (object *, object::method *)</dt>
+ <dt>ev::TYPE::TYPE (object *, object::method *, struct ev_loop *)</dt>
+ <dt>ev::TYPE::~TYPE</dt>
+ <dd>
+ <p>The constructor takes a pointer to an object and a method pointer to
+the event handler callback to call in this class. The constructor calls
+<code>ev_init</code> for you, which means you have to call the <code>set</code> method
+before starting it. If you do not specify a loop then the constructor
+automatically associates the default loop with this watcher.</p>
+ <p>The destructor automatically stops the watcher if it is active.</p>
+ </dd>
+ <dt>w->set (struct ev_loop *)</dt>
+ <dd>
+ <p>Associates a different <code>struct ev_loop</code> with this watcher. You can only
+do this when the watcher is inactive (and not pending either).</p>
+ </dd>
+ <dt>w->set ([args])</dt>
+ <dd>
+ <p>Basically the same as <code>ev_TYPE_set</code>, with the same args. Must be
+called at least once. Unlike the C counterpart, an active watcher gets
+automatically stopped and restarted.</p>
+ </dd>
+ <dt>w->start ()</dt>
+ <dd>
+ <p>Starts the watcher. Note that there is no <code>loop</code> argument as the
+constructor already takes the loop.</p>
+ </dd>
+ <dt>w->stop ()</dt>
+ <dd>
+ <p>Stops the watcher if it is active. Again, no <code>loop</code> argument.</p>
+ </dd>
+ <dt>w->again () <code>ev::timer</code>, <code>ev::periodic</code> only</dt>
+ <dd>
+ <p>For <code>ev::timer</code> and <code>ev::periodic</code>, this invokes the corresponding
+<code>ev_TYPE_again</code> function.</p>
+ </dd>
+ <dt>w->sweep () <code>ev::embed</code> only</dt>
+ <dd>
+ <p>Invokes <code>ev_embed_sweep</code>.</p>
+ </dd>
+ <dt>w->update () <code>ev::stat</code> only</dt>
+ <dd>
+ <p>Invokes <code>ev_stat_stat</code>.</p>
+ </dd>
+ </dl>
+ </p>
+ </dd>
+</dl>
+<p>Example: Define a class with an IO and idle watcher, start one of them in
+the constructor.</p>
+<pre> class myclass
+ {
+ ev_io io; void io_cb (ev::io &w, int revents);
+ ev_idle idle void idle_cb (ev::idle &w, int revents);
+
+ myclass ();
+ }
+
+ myclass::myclass (int fd)
+ : io (this, &myclass::io_cb),
+ idle (this, &myclass::idle_cb)
+ {
+ io.start (fd, ev::READ);
+ }
+
+
+
+
+</pre>
+
+</div>
+<h1 id="MACRO_MAGIC">MACRO MAGIC</h1><p><a href="#TOP" class="toplink">Top</a></p>
+<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 wether (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, working regardless of
+wether 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><p><a href="#TOP" class="toplink">Top</a></p>
+<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 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_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_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_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.</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 autoconf choices:</p>
+<pre> #define EV_USE_POLL 0
+ #define EV_MULTIPLICITY 0
+ #define EV_PERIODICS 0
+ #define EV_CONFIG_H <config.h>
+
+ #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><p><a href="#TOP" class="toplink">Top</a></p>
+<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>
+ <dl>
+ <dt>Starting and stopping timer/periodic watchers: O(log skipped_other_timers)</dt>
+ <dt>Changing timer/periodic watchers (by autorepeat, again): O(log skipped_other_timers)</dt>
+ <dt>Starting io/check/prepare/idle/signal/child watchers: O(1)</dt>
+ <dt>Stopping check/prepare/idle watchers: O(1)</dt>
+ <dt>Stopping an io/signal/child watcher: O(number_of_watchers_for_this_(fd/signal/pid % 16))</dt>
+ <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>
+ <dt>Activating one watcher: O(1)</dt>
+ </dl>
+ </p>
+
+
+
+
+
projects / software / libev.git / blobdiff