8486 lines
261 KiB
HTML
8486 lines
261 KiB
HTML
|
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
<HTML><HEAD><TITLE>Man page of LIBEV</TITLE>
|
|
</HEAD><BODY>
|
|
<H1>LIBEV</H1>
|
|
Section: libev - high performance full featured event loop (3)<BR>Updated: 2019-12-23<BR><A HREF="#index">Index</A>
|
|
<A HREF="/cgi-bin/man/man2html">Return to Main Contents</A><HR>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<A NAME="lbAB"> </A>
|
|
<H2>NAME</H2>
|
|
|
|
libev - a high performance full-featured event loop written in C
|
|
<A NAME="lbAC"> </A>
|
|
<H2>SYNOPSIS</H2>
|
|
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
#include <<A HREF="file:///usr/include/ev.h">ev.h</A>>
|
|
|
|
</PRE>
|
|
|
|
|
|
<A NAME="lbAD"> </A>
|
|
<H3><FONT SIZE="-1">EXAMPLE PROGRAM</FONT></H3>
|
|
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
// a single header file is required
|
|
#include <<A HREF="file:///usr/include/ev.h">ev.h</A>>
|
|
|
|
#include <<A HREF="file:///usr/include/stdio.h">stdio.h</A>> // 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;
|
|
}
|
|
|
|
</PRE>
|
|
|
|
|
|
<A NAME="lbAE"> </A>
|
|
<H2>ABOUT THIS DOCUMENT</H2>
|
|
|
|
|
|
|
|
This document documents the libev software package.
|
|
<P>
|
|
|
|
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: <<A HREF="http://pod.tst.eu/http://cvs.schmorp.de/libev/ev.pod">http://pod.tst.eu/http://cvs.schmorp.de/libev/ev.pod</A>>.
|
|
<P>
|
|
|
|
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.
|
|
<P>
|
|
|
|
Familiarity with event based programming techniques in general is assumed
|
|
throughout this document.
|
|
<A NAME="lbAF"> </A>
|
|
<H2>WHAT TO READ WHEN IN A HURRY</H2>
|
|
|
|
|
|
|
|
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 ``<FONT SIZE="-1">ANATOMY OF A WATCHER''</FONT>, then the ``<FONT SIZE="-1">EXAMPLE PROGRAM''</FONT> above and
|
|
look up the missing functions in ``<FONT SIZE="-1">GLOBAL FUNCTIONS''</FONT> and the <TT>"ev_io"</TT> and
|
|
<TT>"ev_timer"</TT> sections in ``<FONT SIZE="-1">WATCHER TYPES''</FONT>.
|
|
<A NAME="lbAG"> </A>
|
|
<H2>ABOUT LIBEV</H2>
|
|
|
|
|
|
|
|
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.
|
|
<P>
|
|
|
|
To do this, it must take more or less complete control over your process
|
|
(or thread) by executing the <I>event loop</I> handler, and will then
|
|
communicate events via a callback mechanism.
|
|
<P>
|
|
|
|
You register interest in certain events by registering so-called <I>event
|
|
watchers</I>, which are relatively small C structures you initialise with the
|
|
details of the event, and then hand it over to libev by <I>starting</I> the
|
|
watcher.
|
|
<A NAME="lbAH"> </A>
|
|
<H3><FONT SIZE="-1">FEATURES</FONT></H3>
|
|
|
|
|
|
|
|
Libev supports <TT>"select"</TT>, <TT>"poll"</TT>, the Linux-specific aio and <TT>"epoll"</TT>
|
|
interfaces, the BSD-specific <TT>"kqueue"</TT> and the Solaris-specific event port
|
|
mechanisms for file descriptor events (<TT>"ev_io"</TT>), the Linux <TT>"inotify"</TT>
|
|
interface (for <TT>"ev_stat"</TT>), Linux eventfd/signalfd (for faster and cleaner
|
|
inter-thread wakeup (<TT>"ev_async"</TT>)/signal handling (<TT>"ev_signal"</TT>)) relative
|
|
timers (<TT>"ev_timer"</TT>), absolute timers with customised rescheduling
|
|
(<TT>"ev_periodic"</TT>), synchronous signals (<TT>"ev_signal"</TT>), process status
|
|
change events (<TT>"ev_child"</TT>), and event watchers dealing with the event
|
|
loop mechanism itself (<TT>"ev_idle"</TT>, <TT>"ev_embed"</TT>, <TT>"ev_prepare"</TT> and
|
|
<TT>"ev_check"</TT> watchers) as well as file watchers (<TT>"ev_stat"</TT>) and even
|
|
limited support for fork events (<TT>"ev_fork"</TT>).
|
|
<P>
|
|
|
|
It also is quite fast (see this
|
|
benchmark <<A HREF="http://libev.schmorp.de/bench.html">http://libev.schmorp.de/bench.html</A>> comparing it to libevent
|
|
for example).
|
|
<A NAME="lbAI"> </A>
|
|
<H3><FONT SIZE="-1">CONVENTIONS</FONT></H3>
|
|
|
|
|
|
|
|
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
|
|
<B></B><FONT SIZE="-1"><B>EMBED</B></FONT><B></B> section in this manual. If libev was configured without support
|
|
for multiple event loops, then all functions taking an initial argument of
|
|
name <TT>"loop"</TT> (which is always of type <TT>"struct ev_loop *"</TT>) will not have
|
|
this argument.
|
|
<A NAME="lbAJ"> </A>
|
|
<H3><FONT SIZE="-1">TIME REPRESENTATION</FONT></H3>
|
|
|
|
|
|
|
|
Libev represents time as a single floating point number, representing
|
|
the (fractional) number of seconds since the (<FONT SIZE="-1">POSIX</FONT>) epoch (in practice
|
|
somewhere near the beginning of 1970, details are complicated, don't
|
|
ask). This type is called <TT>"ev_tstamp"</TT>, which is what you should use
|
|
too. It usually aliases to the <TT>"double"</TT> type in C. When you need to do
|
|
any calculations on it, you should treat it as some floating point value.
|
|
<P>
|
|
|
|
Unlike the name component <TT>"stamp"</TT> might indicate, it is also used for
|
|
time differences (e.g. delays) throughout libev.
|
|
<A NAME="lbAK"> </A>
|
|
<H2>ERROR HANDLING</H2>
|
|
|
|
|
|
|
|
Libev knows three classes of errors: operating system errors, usage errors
|
|
and internal errors (bugs).
|
|
<P>
|
|
|
|
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 <TT>"ev_set_syserr_cb"</TT>, which is supposed to fix the problem or
|
|
abort. The default is to print a diagnostic message and to call <TT>"abort
|
|
()"</TT>.
|
|
<P>
|
|
|
|
When libev detects a usage error such as a negative timer interval, then
|
|
it will print a diagnostic message and abort (via the <TT>"assert"</TT> mechanism,
|
|
so <TT>"NDEBUG"</TT> will disable this checking): these are programming errors in
|
|
the libev caller and need to be fixed there.
|
|
<P>
|
|
|
|
Via the <TT>"EV_FREQUENT"</TT> macro you can compile in and/or enable extensive
|
|
consistency checking code inside libev that can be used to check for
|
|
internal inconsistencies, suually caused by application bugs.
|
|
<P>
|
|
|
|
Libev also has a few internal error-checking <TT>"assert"</TT>ions. These do not
|
|
trigger under normal circumstances, as they indicate either a bug in libev
|
|
or worse.
|
|
<A NAME="lbAL"> </A>
|
|
<H2>GLOBAL FUNCTIONS</H2>
|
|
|
|
|
|
|
|
These functions can be called anytime, even before initialising the
|
|
library in any way.
|
|
<DL COMPACT>
|
|
<DT id="1">ev_tstamp ev_time ()<DD>
|
|
|
|
|
|
Returns the current time as libev would use it. Please note that the
|
|
<TT>"ev_now"</TT> function is usually faster and also often returns the timestamp
|
|
you actually want to know. Also interesting is the combination of
|
|
<TT>"ev_now_update"</TT> and <TT>"ev_now"</TT>.
|
|
<DT id="2">ev_sleep (ev_tstamp interval)<DD>
|
|
|
|
|
|
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 <TT>"interval <= 0"</TT>.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Basically this is a sub-second-resolution <TT>"sleep ()"</TT>.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
The range of the <TT>"interval"</TT> is limited - libev only guarantees to work
|
|
with sleep times of up to one day (<TT>"interval <= 86400"</TT>).
|
|
<DT id="3">int ev_version_major ()<DD>
|
|
|
|
|
|
|
|
<DT id="4">int ev_version_minor ()<DD>
|
|
|
|
|
|
|
|
You can find out the major and minor <FONT SIZE="-1">ABI</FONT> version numbers of the library
|
|
you linked against by calling the functions <TT>"ev_version_major"</TT> and
|
|
<TT>"ev_version_minor"</TT>. If you want, you can compare against the global
|
|
symbols <TT>"EV_VERSION_MAJOR"</TT> and <TT>"EV_VERSION_MINOR"</TT>, which specify the
|
|
version of the library your program was compiled against.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
These version numbers refer to the <FONT SIZE="-1">ABI</FONT> version of the library, not the
|
|
release version.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
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.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Example: Make sure we haven't accidentally been linked against the wrong
|
|
version (note, however, that this will not detect other <FONT SIZE="-1">ABI</FONT> mismatches,
|
|
such as <FONT SIZE="-1">LFS</FONT> or reentrancy).
|
|
|
|
|
|
<P>
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
assert (("libev version mismatch",
|
|
ev_version_major () == EV_VERSION_MAJOR
|
|
&& ev_version_minor () >= EV_VERSION_MINOR));
|
|
|
|
</PRE>
|
|
|
|
|
|
<DT id="5">unsigned int ev_supported_backends ()<DD>
|
|
|
|
|
|
Return the set of all backends (i.e. their corresponding <TT>"EV_BACKEND_*"</TT>
|
|
value) compiled into this binary of libev (independent of their
|
|
availability on the system you are running on). See <TT>"ev_default_loop"</TT> for
|
|
a description of the set values.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
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
|
|
|
|
|
|
<P>
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
assert (("sorry, no epoll, no sex",
|
|
ev_supported_backends () & EVBACKEND_EPOLL));
|
|
|
|
</PRE>
|
|
|
|
|
|
<DT id="6">unsigned int ev_recommended_backends ()<DD>
|
|
|
|
|
|
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
|
|
<TT>"ev_supported_backends"</TT>, 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.
|
|
<DT id="7">unsigned int ev_embeddable_backends ()<DD>
|
|
|
|
|
|
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 <TT>"ev_embeddable_backends ()
|
|
& ev_supported_backends ()"</TT>, likewise for recommended ones.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
See the description of <TT>"ev_embed"</TT> watchers for more info.
|
|
<DT id="8">ev_set_allocator (void *(*cb)(void *ptr, long size) throw ())<DD>
|
|
|
|
|
|
Sets the allocation function to use (the prototype is similar - the
|
|
semantics are identical to the <TT>"realloc"</TT> 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 (<TT>"size != 0"</TT>), the library might abort
|
|
or take some potentially destructive action.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Since some systems (at least OpenBSD and Darwin) fail to implement
|
|
correct <TT>"realloc"</TT> semantics, libev will use a wrapper around the system
|
|
<TT>"realloc"</TT> and <TT>"free"</TT> functions by default.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
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.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Example: The following is the <TT>"realloc"</TT> function that libev itself uses
|
|
which should work with <TT>"realloc"</TT> and <TT>"free"</TT> functions of all kinds and
|
|
is probably a good basis for your own implementation.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
static void *
|
|
ev_realloc_emul (void *ptr, long size) EV_NOEXCEPT
|
|
{
|
|
if (size)
|
|
return realloc (ptr, size);
|
|
|
|
free (ptr);
|
|
return 0;
|
|
}
|
|
|
|
</PRE>
|
|
|
|
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Example: Replace the libev allocator with one that waits a bit and then
|
|
retries.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
static void *
|
|
persistent_realloc (void *ptr, size_t size)
|
|
{
|
|
if (!size)
|
|
{
|
|
free (ptr);
|
|
return 0;
|
|
}
|
|
|
|
for (;;)
|
|
{
|
|
void *newptr = realloc (ptr, size);
|
|
|
|
if (newptr)
|
|
return newptr;
|
|
|
|
sleep (60);
|
|
}
|
|
}
|
|
|
|
...
|
|
ev_set_allocator (persistent_realloc);
|
|
|
|
</PRE>
|
|
|
|
|
|
<DT id="9">ev_set_syserr_cb (void (*cb)(const char *msg) throw ())<DD>
|
|
|
|
|
|
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).
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Example: This is basically the same thing that libev does internally, too.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
static void
|
|
fatal_error (const char *msg)
|
|
{
|
|
perror (msg);
|
|
abort ();
|
|
}
|
|
|
|
...
|
|
ev_set_syserr_cb (fatal_error);
|
|
|
|
</PRE>
|
|
|
|
|
|
<DT id="10">ev_feed_signal (int signum)<DD>
|
|
|
|
|
|
This function can be used to ``simulate'' a signal receive. It is completely
|
|
safe to call this function at any time, from any context, including signal
|
|
handlers or random threads.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
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 <TT>"EVFLAG_NOSIGMASK"</TT> when
|
|
creating any loops), and in one thread, use <TT>"sigwait"</TT> or any other
|
|
mechanism to wait for signals, then ``deliver'' them to libev by calling
|
|
<TT>"ev_feed_signal"</TT>.
|
|
</DL>
|
|
<A NAME="lbAM"> </A>
|
|
<H2>FUNCTIONS CONTROLLING EVENT LOOPS</H2>
|
|
|
|
|
|
|
|
An event loop is described by a <TT>"struct ev_loop *"</TT> (the <TT>"struct"</TT> is
|
|
<I>not</I> optional in this case unless libev 3 compatibility is disabled, as
|
|
libev 3 had an <TT>"ev_loop"</TT> function colliding with the struct name).
|
|
<P>
|
|
|
|
The library knows two types of such loops, the <I>default</I> loop, which
|
|
supports child process events, and dynamically created event loops which
|
|
do not.
|
|
<DL COMPACT>
|
|
<DT id="11">struct ev_loop *ev_default_loop (unsigned int flags)<DD>
|
|
|
|
|
|
This returns the ``default'' event loop object, which is what you should
|
|
normally use when you just need ``the event loop''. Event loop objects and
|
|
the <TT>"flags"</TT> parameter are described in more detail in the entry for
|
|
<TT>"ev_loop_new"</TT>.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
If the default loop is already initialised then this function simply
|
|
returns it (and ignores the flags. If that is troubling you, check
|
|
<TT>"ev_backend ()"</TT> afterwards). Otherwise it will create it with the given
|
|
flags, which should almost always be <TT>0</TT>, unless the caller is also the
|
|
one calling <TT>"ev_run"</TT> or otherwise qualifies as ``the main program''.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
If you don't know what event loop to use, use the one returned from this
|
|
function (or via the <TT>"EV_DEFAULT"</TT> macro).
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Note that this function is <I>not</I> 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).
|
|
|
|
|
|
<P>
|
|
|
|
|
|
The default loop is the only loop that can handle <TT>"ev_child"</TT> watchers,
|
|
and to do this, it always registers a handler for <TT>"SIGCHLD"</TT>. If this is
|
|
a problem for your application you can either create a dynamic loop with
|
|
<TT>"ev_loop_new"</TT> which doesn't do that, or you can simply overwrite the
|
|
<TT>"SIGCHLD"</TT> signal handler <I>after</I> calling <TT>"ev_default_init"</TT>.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Example: This is the most typical usage.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
if (!ev_default_loop (0))
|
|
fatal ("could not initialise libev, bad $LIBEV_FLAGS in environment?");
|
|
|
|
</PRE>
|
|
|
|
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Example: Restrict libev to the select and poll backends, and do not allow
|
|
environment settings to be taken into account:
|
|
|
|
|
|
<P>
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
ev_default_loop (EVBACKEND_POLL | EVBACKEND_SELECT | EVFLAG_NOENV);
|
|
|
|
</PRE>
|
|
|
|
|
|
<DT id="12">struct ev_loop *ev_loop_new (unsigned int flags)<DD>
|
|
|
|
|
|
This will create and initialise a new event loop object. If the loop
|
|
could not be initialised, returns false.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
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 ``main'' or ``initial'' thread.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
The flags argument can be used to specify special behaviour or specific
|
|
backends to use, and is usually specified as <TT>0</TT> (or <TT>"EVFLAG_AUTO"</TT>).
|
|
|
|
|
|
<P>
|
|
|
|
|
|
The following flags are supported:
|
|
<DL COMPACT><DT id="13"><DD>
|
|
<DL COMPACT>
|
|
<DT id="14">"EVFLAG_AUTO"<DD>
|
|
|
|
|
|
|
|
|
|
The default flags value. Use this if you have no clue (it's the right
|
|
thing, believe me).
|
|
<DT id="15">"EVFLAG_NOENV"<DD>
|
|
|
|
|
|
|
|
|
|
If this flag bit is or'ed into the flag value (or the program runs setuid
|
|
or setgid) then libev will <I>not</I> look at the environment variable
|
|
<TT>"LIBEV_FLAGS"</TT>. 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).
|
|
<DT id="16">"EVFLAG_FORKCHECK"<DD>
|
|
|
|
|
|
|
|
|
|
Instead of calling <TT>"ev_loop_fork"</TT> manually after a fork, you can also
|
|
make libev check for a fork in each iteration by enabling this flag.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
This works by calling <TT>"getpid ()"</TT> 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, <TT>"getpid"</TT> is actually a simple 5-insn
|
|
sequence without a system call and thus <I>very</I> fast, but my GNU/Linux
|
|
system also has <TT>"pthread_atfork"</TT> which is even faster). (Update: glibc
|
|
versions 2.25 apparently removed the <TT>"getpid"</TT> optimisation again).
|
|
|
|
|
|
<P>
|
|
|
|
|
|
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 <TT>"SIGPIPE"</TT>) when you use this flag.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
This flag setting cannot be overridden or specified in the <TT>"LIBEV_FLAGS"</TT>
|
|
environment variable.
|
|
<DT id="17">"EVFLAG_NOINOTIFY"<DD>
|
|
|
|
|
|
|
|
|
|
When this flag is specified, then libev will not attempt to use the
|
|
<I>inotify</I> <FONT SIZE="-1">API</FONT> for its <TT>"ev_stat"</TT> watchers. Apart from debugging and
|
|
testing, this flag can be useful to conserve inotify file descriptors, as
|
|
otherwise each loop using <TT>"ev_stat"</TT> watchers consumes one inotify handle.
|
|
<DT id="18">"EVFLAG_SIGNALFD"<DD>
|
|
|
|
|
|
|
|
|
|
When this flag is specified, then libev will attempt to use the
|
|
<I>signalfd</I> <FONT SIZE="-1">API</FONT> for its <TT>"ev_signal"</TT> (and <TT>"ev_child"</TT>) watchers. This <FONT SIZE="-1">API</FONT>
|
|
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.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
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.
|
|
<DT id="19">"EVFLAG_NOSIGMASK"<DD>
|
|
|
|
|
|
|
|
|
|
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.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
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.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
It's also required by <FONT SIZE="-1">POSIX</FONT> in a threaded program, as libev calls
|
|
<TT>"sigprocmask"</TT>, whose behaviour is officially unspecified.
|
|
<DT id="20">"EVFLAG_NOTIMERFD"<DD>
|
|
|
|
|
|
|
|
|
|
When this flag is specified, the libev will avoid using a <TT>"timerfd"</TT> to
|
|
detect time jumps. It will still be able to detect time jumps, but takes
|
|
longer and has a lower accuracy in doing so, but saves a file descriptor
|
|
per loop.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
The current implementation only tries to use a <TT>"timerfd"</TT> when the first
|
|
<TT>"ev_periodic"</TT> watcher is started and falls back on other methods if it
|
|
cannot be created, but this behaviour might change in the future.
|
|
<DT id="21">"EVBACKEND_SELECT" (value 1, portable select backend)<DD>
|
|
|
|
|
|
|
|
|
|
This is your standard <B><A HREF="/cgi-bin/man/man2html?2+select">select</A></B>(2) backend. Not <I>completely</I> 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.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
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 <TT>"accept ()"</TT> in a loop to accept as many
|
|
connections as possible during one iteration. You might also want to have
|
|
a look at <TT>"ev_set_io_collect_interval ()"</TT> to increase the amount of
|
|
readiness notifications you get per iteration.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
This backend maps <TT>"EV_READ"</TT> to the <TT>"readfds"</TT> set and <TT>"EV_WRITE"</TT> to the
|
|
<TT>"writefds"</TT> set (and to work around Microsoft Windows bugs, also onto the
|
|
<TT>"exceptfds"</TT> set on that platform).
|
|
<DT id="22">"EVBACKEND_POLL" (value 2, poll backend, available everywhere except on windows)<DD>
|
|
|
|
|
|
|
|
|
|
And this is your standard <B><A HREF="/cgi-bin/man/man2html?2+poll">poll</A></B>(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 <TT>"EVBACKEND_SELECT"</TT>, above, for
|
|
performance tips.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
This backend maps <TT>"EV_READ"</TT> to <TT>"POLLIN | POLLERR | POLLHUP"</TT>, and
|
|
<TT>"EV_WRITE"</TT> to <TT>"POLLOUT | POLLERR | POLLHUP"</TT>.
|
|
<DT id="23">"EVBACKEND_EPOLL" (value 4, Linux)<DD>
|
|
|
|
|
|
|
|
|
|
Use the Linux-specific <B><A HREF="/cgi-bin/man/man2html?7+epoll">epoll</A></B>(7) interface (for both pre- and post-2.6.9
|
|
kernels).
|
|
|
|
|
|
<P>
|
|
|
|
|
|
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 <A HREF="/cgi-bin/man/man2html?1+O">O</A>(1) or O(active_fds).
|
|
|
|
|
|
<P>
|
|
|
|
|
|
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 <I>both</I> 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.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Epoll is also notoriously buggy - embedding epoll fds <I>should</I> work,
|
|
but of course <I>doesn't</I>, and epoll just loves to report events for
|
|
totally <I>different</I> file descriptors (even already closed ones, so
|
|
one cannot even remove them from the set) than registered in the set
|
|
(especially on <FONT SIZE="-1">SMP</FONT> 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 <TT>"select"</TT> (files, many character devices...).
|
|
|
|
|
|
<P>
|
|
|
|
|
|
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...
|
|
|
|
|
|
<P>
|
|
|
|
|
|
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>file descriptor</I> could point to a different
|
|
<I>file description</I> now), so its best to avoid that. Also, <TT>"dup ()"</TT>'ed
|
|
file descriptors might not work very well if you register events for both
|
|
file descriptors.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
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.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
All this means that, in practice, <TT>"EVBACKEND_SELECT"</TT> can be as fast or
|
|
faster than epoll for maybe up to a hundred file descriptors, depending on
|
|
the usage. So sad.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
While nominally embeddable in other event loops, this feature is broken in
|
|
a lot of kernel revisions, but probably(!) works in current versions.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
This backend maps <TT>"EV_READ"</TT> and <TT>"EV_WRITE"</TT> in the same way as
|
|
<TT>"EVBACKEND_POLL"</TT>.
|
|
<DT id="24">"EVBACKEND_LINUXAIO" (value 64, Linux)<DD>
|
|
|
|
|
|
|
|
|
|
Use the Linux-specific Linux <FONT SIZE="-1">AIO</FONT> (<I>not</I> <TT><A HREF="/cgi-bin/man/man2html?7+aio">aio</A>(7)</TT> but <TT><A HREF="/cgi-bin/man/man2html?2+io_submit">io_submit</A>(2)</TT>) event interface available in post-4.18 kernels (but libev
|
|
only tries to use it in 4.19+).
|
|
|
|
|
|
<P>
|
|
|
|
|
|
This is another Linux train wreck of an event interface.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
If this backend works for you (as of this writing, it was very
|
|
experimental), it is the best event interface available on Linux and might
|
|
be well worth enabling it - if it isn't available in your kernel this will
|
|
be detected and this backend will be skipped.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
This backend can batch oneshot requests and supports a user-space ring
|
|
buffer to receive events. It also doesn't suffer from most of the design
|
|
problems of epoll (such as not being able to remove event sources from
|
|
the epoll set), and generally sounds too good to be true. Because, this
|
|
being the Linux kernel, of course it suffers from a whole new set of
|
|
limitations, forcing you to fall back to epoll, inheriting all its design
|
|
issues.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
For one, it is not easily embeddable (but probably could be done using
|
|
an event fd at some extra overhead). It also is subject to a system wide
|
|
limit that can be configured in <I>/proc/sys/fs/aio-max-nr</I>. If no <FONT SIZE="-1">AIO</FONT>
|
|
requests are left, this backend will be skipped during initialisation, and
|
|
will switch to epoll when the loop is active.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Most problematic in practice, however, is that not all file descriptors
|
|
work with it. For example, in Linux 5.1, <FONT SIZE="-1">TCP</FONT> sockets, pipes, event fds,
|
|
files, <I>/dev/null</I> and many others are supported, but ttys do not work
|
|
properly (a known bug that the kernel developers don't care about, see
|
|
<<A HREF="https://lore.kernel.org/patchwork/patch/1047453/">https://lore.kernel.org/patchwork/patch/1047453/</A>>), so this is not
|
|
(yet?) a generic event polling interface.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Overall, it seems the Linux developers just don't want it to have a
|
|
generic event handling mechanism other than <TT>"select"</TT> or <TT>"poll"</TT>.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
To work around all these problem, the current version of libev uses its
|
|
epoll backend as a fallback for file descriptor types that do not work. Or
|
|
falls back completely to epoll if the kernel acts up.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
This backend maps <TT>"EV_READ"</TT> and <TT>"EV_WRITE"</TT> in the same way as
|
|
<TT>"EVBACKEND_POLL"</TT>.
|
|
<DT id="25">"EVBACKEND_KQUEUE" (value 8, most <FONT SIZE="-1">BSD</FONT> clones)<DD>
|
|
|
|
|
|
|
|
|
|
Kqueue deserves special mention, as at the time this backend was
|
|
implemented, 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 be (and mostly have been)
|
|
fixed without <FONT SIZE="-1">API</FONT> changes to existing programs. For this reason it's not
|
|
being ``auto-detected'' on all platforms unless you explicitly specify it
|
|
in the flags (i.e. using <TT>"EVBACKEND_KQUEUE"</TT>) or libev was compiled on a
|
|
known-to-be-good (-enough) system like NetBSD.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
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 <TT>"ev_embed"</TT> watchers for more info.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
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 <TT>"EVBACKEND_EPOLL"</TT>, it still adds up to
|
|
two event changes per incident. Support for <TT>"fork ()"</TT> is very bad (you
|
|
might have to leak fds on fork, but it's more sane than epoll) and it
|
|
drops fds silently in similarly hard-to-detect cases.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
This backend usually performs well under most conditions.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
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. <TT>"EVBACKEND_SELECT"</TT> or <TT>"EVBACKEND_POLL"</TT> (but <TT>"poll"</TT> is of course
|
|
also broken on <FONT SIZE="-1">OS X</FONT>)) and, did I mention it, using it only for sockets.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
This backend maps <TT>"EV_READ"</TT> into an <TT>"EVFILT_READ"</TT> kevent with
|
|
<TT>"NOTE_EOF"</TT>, and <TT>"EV_WRITE"</TT> into an <TT>"EVFILT_WRITE"</TT> kevent with
|
|
<TT>"NOTE_EOF"</TT>.
|
|
<DT id="26">"EVBACKEND_DEVPOLL" (value 16, Solaris 8)<DD>
|
|
|
|
|
|
|
|
|
|
This is not implemented yet (and might never be, unless you send me an
|
|
implementation). According to reports, <TT>"/dev/poll"</TT> only supports sockets
|
|
and is not embeddable, which would limit the usefulness of this backend
|
|
immensely.
|
|
<DT id="27">"EVBACKEND_PORT" (value 32, Solaris 10)<DD>
|
|
|
|
|
|
|
|
|
|
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)).
|
|
|
|
|
|
<P>
|
|
|
|
|
|
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'' <TT>"EVBACKEND_SELECT"</TT> or <TT>"EVBACKEND_POLL"</TT> backend
|
|
might perform better.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
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).
|
|
|
|
|
|
<P>
|
|
|
|
|
|
On the negative side, the interface is <I>bizarre</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.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Fortunately libev seems to be able to work around these idiocies.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
This backend maps <TT>"EV_READ"</TT> and <TT>"EV_WRITE"</TT> in the same way as
|
|
<TT>"EVBACKEND_POLL"</TT>.
|
|
<DT id="28">"EVBACKEND_ALL"<DD>
|
|
|
|
|
|
|
|
|
|
Try all backends (even potentially broken ones that wouldn't be tried
|
|
with <TT>"EVFLAG_AUTO"</TT>). Since this is a mask, you can do stuff such as
|
|
<TT>"EVBACKEND_ALL & ~EVBACKEND_KQUEUE"</TT>.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
It is definitely not recommended to use this flag, use whatever
|
|
<TT>"ev_recommended_backends ()"</TT> returns, or simply do not specify a backend
|
|
at all.
|
|
<DT id="29">"EVBACKEND_MASK"<DD>
|
|
|
|
|
|
|
|
|
|
Not a backend at all, but a mask to select all backend bits from a
|
|
<TT>"flags"</TT> value, in case you want to mask out any backends from a flags
|
|
value (e.g. when modifying the <TT>"LIBEV_FLAGS"</TT> environment variable).
|
|
</DL>
|
|
</DL>
|
|
|
|
<DL COMPACT><DT id="30"><DD>
|
|
|
|
|
|
<P>
|
|
|
|
|
|
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 <TT>"ev_recommended_backends
|
|
()"</TT> will be tried.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Example: Try to create a event loop that uses epoll and nothing else.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
struct ev_loop *epoller = ev_loop_new (EVBACKEND_EPOLL | EVFLAG_NOENV);
|
|
if (!epoller)
|
|
fatal ("no epoll found here, maybe it hides under your chair");
|
|
|
|
</PRE>
|
|
|
|
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Example: Use whatever libev has to offer, but make sure that kqueue is
|
|
used if available.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
struct ev_loop *loop = ev_loop_new (ev_recommended_backends () | EVBACKEND_KQUEUE);
|
|
|
|
</PRE>
|
|
|
|
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Example: Similarly, on linux, you mgiht want to take advantage of the
|
|
linux aio backend if possible, but fall back to something else if that
|
|
isn't available.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
struct ev_loop *loop = ev_loop_new (ev_recommended_backends () | EVBACKEND_LINUXAIO);
|
|
|
|
</PRE>
|
|
|
|
|
|
</DL>
|
|
|
|
<DT id="31">ev_loop_destroy (loop)<DD>
|
|
|
|
|
|
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. <TT>"ev_is_active"</TT> might still return true. It is your
|
|
responsibility to either stop all watchers cleanly yourself <I>before</I>
|
|
calling this function, or cope with the fact afterwards (which is usually
|
|
the easiest thing, you can just ignore the watchers and/or <TT>"free ()"</TT> them
|
|
for example).
|
|
|
|
|
|
<P>
|
|
|
|
|
|
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.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
This function is normally used on loop objects allocated by
|
|
<TT>"ev_loop_new"</TT>, but it can also be used on the default loop returned by
|
|
<TT>"ev_default_loop"</TT>, in which case it is not thread-safe.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
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 <TT>"ev_loop_new"</TT>
|
|
and <TT>"ev_loop_destroy"</TT>.
|
|
<DT id="32">ev_loop_fork (loop)<DD>
|
|
|
|
|
|
This function sets a flag that causes subsequent <TT>"ev_run"</TT> 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 <TT>"ev_prepare"</TT> callback), but it makes most
|
|
sense after forking, in the child process. You <I>must</I> call it (or use
|
|
<TT>"EVFLAG_FORKCHECK"</TT>) in the child before resuming or calling <TT>"ev_run"</TT>.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
In addition, if you want to reuse a loop (via this function or
|
|
<TT>"EVFLAG_FORKCHECK"</TT>), you <I>also</I> have to ignore <TT>"SIGPIPE"</TT>.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Again, you <I>have</I> to call it on <I>any</I> loop that you want to re-use after
|
|
a fork, <I>even if you do not plan to use the loop in the parent</I>. This is
|
|
because some kernel interfaces *cough* <I>kqueue</I> *cough* do funny things
|
|
during fork.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
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, <TT>"epoll"</TT> 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).
|
|
|
|
|
|
<P>
|
|
|
|
|
|
The function itself is quite fast and it's usually not a problem to call
|
|
it just in case after a fork.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Example: Automate calling <TT>"ev_loop_fork"</TT> on the default loop when
|
|
using pthreads.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
static void
|
|
post_fork_child (void)
|
|
{
|
|
ev_loop_fork (EV_DEFAULT);
|
|
}
|
|
|
|
...
|
|
pthread_atfork (0, 0, post_fork_child);
|
|
|
|
</PRE>
|
|
|
|
|
|
<DT id="33">int ev_is_default_loop (loop)<DD>
|
|
|
|
|
|
Returns true when the given loop is, in fact, the default loop, and false
|
|
otherwise.
|
|
<DT id="34">unsigned int ev_iteration (loop)<DD>
|
|
|
|
|
|
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 <TT>0</TT>
|
|
and happily wraps around with enough iterations.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
This value can sometimes be useful as a generation counter of sorts (it
|
|
``ticks'' the number of loop iterations), as it roughly corresponds with
|
|
<TT>"ev_prepare"</TT> and <TT>"ev_check"</TT> calls - and is incremented between the
|
|
prepare and check phases.
|
|
<DT id="35">unsigned int ev_depth (loop)<DD>
|
|
|
|
|
|
Returns the number of times <TT>"ev_run"</TT> was entered minus the number of
|
|
times <TT>"ev_run"</TT> was exited normally, in other words, the recursion depth.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Outside <TT>"ev_run"</TT>, this number is zero. In a callback, this number is
|
|
<TT>1</TT>, unless <TT>"ev_run"</TT> was invoked recursively (or from another thread),
|
|
in which case it is higher.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Leaving <TT>"ev_run"</TT> 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.
|
|
<DT id="36">unsigned int ev_backend (loop)<DD>
|
|
|
|
|
|
Returns one of the <TT>"EVBACKEND_*"</TT> flags indicating the event backend in
|
|
use.
|
|
<DT id="37">ev_tstamp ev_now (loop)<DD>
|
|
|
|
|
|
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).
|
|
<DT id="38">ev_now_update (loop)<DD>
|
|
|
|
|
|
Establishes the current time by querying the kernel, updating the time
|
|
returned by <TT>"ev_now ()"</TT> in the progress. This is a costly operation and
|
|
is usually done automatically within <TT>"ev_run ()"</TT>.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
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.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
See also ``The special problem of time updates'' in the <TT>"ev_timer"</TT> section.
|
|
<DT id="39">ev_suspend (loop)<DD>
|
|
|
|
|
|
|
|
<DT id="40">ev_resume (loop)<DD>
|
|
|
|
|
|
|
|
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.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
A typical use case would be an interactive program such as a game: When
|
|
the user presses <TT>"^Z"</TT> 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 <TT>"ev_suspend"</TT>
|
|
in your <TT>"SIGTSTP"</TT> handler, sending yourself a <TT>"SIGSTOP"</TT> and calling
|
|
<TT>"ev_resume"</TT> directly afterwards to resume timer processing.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Effectively, all <TT>"ev_timer"</TT> watchers will be delayed by the time spend
|
|
between <TT>"ev_suspend"</TT> and <TT>"ev_resume"</TT>, and all <TT>"ev_periodic"</TT> watchers
|
|
will be rescheduled (that is, they will lose any events that would have
|
|
occurred while suspended).
|
|
|
|
|
|
<P>
|
|
|
|
|
|
After calling <TT>"ev_suspend"</TT> you <B>must not</B> call <I>any</I> function on the
|
|
given loop other than <TT>"ev_resume"</TT>, and you <B>must not</B> call <TT>"ev_resume"</TT>
|
|
without a previous call to <TT>"ev_suspend"</TT>.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Calling <TT>"ev_suspend"</TT>/<TT>"ev_resume"</TT> has the side effect of updating the
|
|
event loop time (see <TT>"ev_now_update"</TT>).
|
|
<DT id="41">bool ev_run (loop, int flags)<DD>
|
|
|
|
|
|
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>loops</I>.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
If the flags argument is specified as <TT>0</TT>, it will keep handling events
|
|
until either no event watchers are active anymore or <TT>"ev_break"</TT> was
|
|
called.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
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 <TT>"ev_run"</TT> again").
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Please note that an explicit <TT>"ev_break"</TT> 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.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
This function is <I>mostly</I> exception-safe - you can break out of a
|
|
<TT>"ev_run"</TT> call by calling <TT>"longjmp"</TT> in a callback, throwing a C<FONT SIZE="-2">++</FONT>
|
|
exception and so on. This does not decrement the <TT>"ev_depth"</TT> value, nor
|
|
will it clear any outstanding <TT>"EVBREAK_ONE"</TT> breaks.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
A flags value of <TT>"EVRUN_NOWAIT"</TT> 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.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
A flags value of <TT>"EVRUN_ONCE"</TT> 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.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
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 <TT>"ev_run"</TT>"). However, a pair of <TT>"ev_prepare"</TT>/<TT>"ev_check"</TT> watchers is
|
|
usually a better approach for this kind of thing.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Here are the gory details of what <TT>"ev_run"</TT> does (this is for your
|
|
understanding, not a guarantee that things will work exactly like this in
|
|
future versions):
|
|
|
|
|
|
<P>
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
- 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.
|
|
|
|
</PRE>
|
|
|
|
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Example: Queue some jobs and then loop until no events are outstanding
|
|
anymore.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
... 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!
|
|
|
|
</PRE>
|
|
|
|
|
|
<DT id="42">ev_break (loop, how)<DD>
|
|
|
|
|
|
Can be used to make a call to <TT>"ev_run"</TT> return early (but only after it
|
|
has processed all outstanding events). The <TT>"how"</TT> argument must be either
|
|
<TT>"EVBREAK_ONE"</TT>, which will make the innermost <TT>"ev_run"</TT> call return, or
|
|
<TT>"EVBREAK_ALL"</TT>, which will make all nested <TT>"ev_run"</TT> calls return.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
This ``break state'' will be cleared on the next call to <TT>"ev_run"</TT>.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
It is safe to call <TT>"ev_break"</TT> from outside any <TT>"ev_run"</TT> calls, too, in
|
|
which case it will have no effect.
|
|
<DT id="43">ev_ref (loop)<DD>
|
|
|
|
|
|
|
|
<DT id="44">ev_unref (loop)<DD>
|
|
|
|
|
|
|
|
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, <TT>"ev_run"</TT> will not return on its own.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
This is useful when you have a watcher that you never intend to
|
|
unregister, but that nevertheless should not keep <TT>"ev_run"</TT> from
|
|
returning. In such a case, call <TT>"ev_unref"</TT> after starting, and <TT>"ev_ref"</TT>
|
|
before stopping it.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
As an example, libev itself uses this for its internal signal pipe: It
|
|
is not visible to the libev user and should not keep <TT>"ev_run"</TT> 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>unref after start</I> and <I>ref
|
|
before stop</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 <TT>"ev_ref"</TT>
|
|
in the callback).
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Example: Create a signal watcher, but keep it from keeping <TT>"ev_run"</TT>
|
|
running when nothing else is active.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
ev_signal exitsig;
|
|
ev_signal_init (&exitsig, sig_cb, SIGINT);
|
|
ev_signal_start (loop, &exitsig);
|
|
ev_unref (loop);
|
|
|
|
</PRE>
|
|
|
|
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Example: For some weird reason, unregister the above signal handler again.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
ev_ref (loop);
|
|
ev_signal_stop (loop, &exitsig);
|
|
|
|
</PRE>
|
|
|
|
|
|
<DT id="45">ev_set_io_collect_interval (loop, ev_tstamp interval)<DD>
|
|
|
|
|
|
|
|
<DT id="46">ev_set_timeout_collect_interval (loop, ev_tstamp interval)<DD>
|
|
|
|
|
|
|
|
These advanced functions influence the time that libev will spend waiting
|
|
for events. Both time intervals are by default <TT>0</TT>, meaning that libev
|
|
will try to invoke timer/periodic callbacks and I/O callbacks with minimum
|
|
latency.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Setting these to a higher value (the <TT>"interval"</TT> <I>must</I> be >= <TT>0</TT>)
|
|
allows libev to delay invocation of I/O and timer/periodic callbacks
|
|
to increase efficiency of loop iterations (or to increase power-saving
|
|
opportunities).
|
|
|
|
|
|
<P>
|
|
|
|
|
|
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 <FONT SIZE="-1">CPU</FONT> time to poll for new
|
|
events, especially with backends like <TT>"select ()"</TT> which have a high
|
|
overhead for the actual polling but can deliver many events at once.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
By setting a higher <I>io collect interval</I> 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 <TT>"ev_periodic"</TT> and
|
|
<TT>"ev_timer"</TT>) will not be affected. Setting this to a non-null value will
|
|
introduce an additional <TT>"ev_sleep ()"</TT> 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).
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Likewise, by setting a higher <I>timeout collect interval</I> you allow libev
|
|
to spend more time collecting timeouts, at the expense of increased
|
|
latency/jitter/inexactness (the watcher callback will be called
|
|
later). <TT>"ev_io"</TT> watchers will not be affected. Setting this to a non-null
|
|
value will not introduce any overhead in libev.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Many (busy) programs can usually benefit by setting the I/O collect
|
|
interval to a value near <TT>0.1</TT> 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 <TT>0.01</TT>,
|
|
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).
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Setting the <I>timeout collect interval</I> can improve the opportunity for
|
|
saving power, as the program will ``bundle'' timer callback invocations that
|
|
are ``near'' 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 <TT>"ev_periodic"</TT> watchers and make sure
|
|
they fire on, say, one-second boundaries only.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Example: we only need 0.1s timeout granularity, and we wish not to poll
|
|
more often than 100 times per second:
|
|
|
|
|
|
<P>
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
ev_set_timeout_collect_interval (EV_DEFAULT_UC_ 0.1);
|
|
ev_set_io_collect_interval (EV_DEFAULT_UC_ 0.01);
|
|
|
|
</PRE>
|
|
|
|
|
|
<DT id="47">ev_invoke_pending (loop)<DD>
|
|
|
|
|
|
This call will simply invoke all pending watchers while resetting their
|
|
pending state. Normally, <TT>"ev_run"</TT> 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 <TT>"ev_invoke_pending"</TT> or <TT>"ev_run"</TT> of course).
|
|
<DT id="48">int ev_pending_count (loop)<DD>
|
|
|
|
|
|
Returns the number of pending watchers - zero indicates that no watchers
|
|
are pending.
|
|
<DT id="49">ev_set_invoke_pending_cb (loop, void (*invoke_pending_cb)(<FONT SIZE="-1">EV_P</FONT>))<DD>
|
|
|
|
|
|
This overrides the invoke pending functionality of the loop: Instead of
|
|
invoking all pending watchers when there are any, <TT>"ev_run"</TT> will call
|
|
this callback instead. This is useful, for example, when you want to
|
|
invoke the actual watchers inside another context (another thread etc.).
|
|
|
|
|
|
<P>
|
|
|
|
|
|
If you want to reset the callback, use <TT>"ev_invoke_pending"</TT> as new
|
|
callback.
|
|
<DT id="50">ev_set_loop_release_cb (loop, void (*release)(<FONT SIZE="-1">EV_P</FONT>) throw (), void (*acquire)(<FONT SIZE="-1">EV_P</FONT>) throw ())<DD>
|
|
|
|
|
|
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.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
However, <TT>"ev_run"</TT> 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 <TT>"ev_break"</TT> and <TT>"ev_async_send"</TT>, another way is to set these
|
|
<I>release</I> and <I>acquire</I> callbacks on the loop.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
When set, then <TT>"release"</TT> will be called just before the thread is
|
|
suspended waiting for new events, and <TT>"acquire"</TT> is called just
|
|
afterwards.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Ideally, <TT>"release"</TT> will just call your mutex_unlock function, and
|
|
<TT>"acquire"</TT> will just call the mutex_lock function again.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
While event loop modifications are allowed between invocations of
|
|
<TT>"release"</TT> and <TT>"acquire"</TT> (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 <TT>"ev_async"</TT> watcher to wake up <TT>"ev_run"</TT> when you want it
|
|
to take note of any changes you made.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
In theory, threads executing <TT>"ev_run"</TT> will be async-cancel safe between
|
|
invocations of <TT>"release"</TT> and <TT>"acquire"</TT>.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
See also the locking example in the <TT>"THREADS"</TT> section later in this
|
|
document.
|
|
<DT id="51">ev_set_userdata (loop, void *data)<DD>
|
|
|
|
|
|
|
|
<DT id="52">void *ev_userdata (loop)<DD>
|
|
|
|
|
|
|
|
Set and retrieve a single <TT>"void *"</TT> associated with a loop. When
|
|
<TT>"ev_set_userdata"</TT> has never been called, then <TT>"ev_userdata"</TT> returns
|
|
<TT>0</TT>.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
These two functions can be used to associate arbitrary data with a loop,
|
|
and are intended solely for the <TT>"invoke_pending_cb"</TT>, <TT>"release"</TT> and
|
|
<TT>"acquire"</TT> callbacks described above, but of course can be (ab-)used for
|
|
any other purpose as well.
|
|
<DT id="53">ev_verify (loop)<DD>
|
|
|
|
|
|
This function only does something when <TT>"EV_VERIFY"</TT> 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 <TT>"abort ()"</TT>.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
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.
|
|
</DL>
|
|
<A NAME="lbAN"> </A>
|
|
<H2>ANATOMY OF A WATCHER</H2>
|
|
|
|
|
|
|
|
In the following description, uppercase <TT>"TYPE"</TT> in names stands for the
|
|
watcher type, e.g. <TT>"ev_TYPE_start"</TT> can mean <TT>"ev_timer_start"</TT> for timer
|
|
watchers and <TT>"ev_io_start"</TT> for I/O watchers.
|
|
<P>
|
|
|
|
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 <FONT SIZE="-1">STDIN</FONT> to become readable, you would create an <TT>"ev_io"</TT> watcher
|
|
for that:
|
|
<P>
|
|
|
|
|
|
|
|
<PRE>
|
|
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);
|
|
|
|
</PRE>
|
|
|
|
|
|
<P>
|
|
|
|
As you can see, you are responsible for allocating the memory for your
|
|
watcher structures (and it is <I>usually</I> a bad idea to do this on the
|
|
stack).
|
|
<P>
|
|
|
|
Each watcher has an associated watcher structure (called <TT>"struct ev_TYPE"</TT>
|
|
or simply <TT>"ev_TYPE"</TT>, as typedefs are provided for all watcher structs).
|
|
<P>
|
|
|
|
Each watcher structure must be initialised by a call to <TT>"ev_init (watcher
|
|
*, callback)"</TT>, 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).
|
|
<P>
|
|
|
|
Each watcher type further has its own <TT>"ev_TYPE_set (watcher *, ...)"</TT>
|
|
macro to configure it, with arguments specific to the watcher type. There
|
|
is also a macro to combine initialisation and setting in one call: <TT>"ev_TYPE_init (watcher *, callback, ...)"</TT>.
|
|
<P>
|
|
|
|
To make the watcher actually watch out for events, you have to start it
|
|
with a watcher-specific start function (<TT>"ev_TYPE_start (loop, watcher
|
|
*)"</TT>), and you can stop watching for events at any time by calling the
|
|
corresponding stop function (<TT>"ev_TYPE_stop (loop, watcher *)"</TT>.
|
|
<P>
|
|
|
|
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 <TT>"ev_TYPE_set"</TT> macro.
|
|
<P>
|
|
|
|
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.
|
|
<P>
|
|
|
|
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:
|
|
<DL COMPACT>
|
|
<DT id="54">"EV_READ"<DD>
|
|
|
|
|
|
|
|
|
|
|
|
<DT id="55">"EV_WRITE"<DD>
|
|
|
|
|
|
|
|
|
|
|
|
The file descriptor in the <TT>"ev_io"</TT> watcher has become readable and/or
|
|
writable.
|
|
<DT id="56">"EV_TIMER"<DD>
|
|
|
|
|
|
|
|
|
|
The <TT>"ev_timer"</TT> watcher has timed out.
|
|
<DT id="57">"EV_PERIODIC"<DD>
|
|
|
|
|
|
|
|
|
|
The <TT>"ev_periodic"</TT> watcher has timed out.
|
|
<DT id="58">"EV_SIGNAL"<DD>
|
|
|
|
|
|
|
|
|
|
The signal specified in the <TT>"ev_signal"</TT> watcher has been received by a thread.
|
|
<DT id="59">"EV_CHILD"<DD>
|
|
|
|
|
|
|
|
|
|
The pid specified in the <TT>"ev_child"</TT> watcher has received a status change.
|
|
<DT id="60">"EV_STAT"<DD>
|
|
|
|
|
|
|
|
|
|
The path specified in the <TT>"ev_stat"</TT> watcher changed its attributes somehow.
|
|
<DT id="61">"EV_IDLE"<DD>
|
|
|
|
|
|
|
|
|
|
The <TT>"ev_idle"</TT> watcher has determined that you have nothing better to do.
|
|
<DT id="62">"EV_PREPARE"<DD>
|
|
|
|
|
|
|
|
|
|
|
|
<DT id="63">"EV_CHECK"<DD>
|
|
|
|
|
|
|
|
|
|
|
|
All <TT>"ev_prepare"</TT> watchers are invoked just <I>before</I> <TT>"ev_run"</TT> starts to
|
|
gather new events, and all <TT>"ev_check"</TT> watchers are queued (not invoked)
|
|
just after <TT>"ev_run"</TT> has gathered them, but before it queues any callbacks
|
|
for any received events. That means <TT>"ev_prepare"</TT> watchers are the last
|
|
watchers invoked before the event loop sleeps or polls for new events, and
|
|
<TT>"ev_check"</TT> watchers will be invoked before any other watchers of the same
|
|
or lower priority within an event loop iteration.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
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
|
|
<TT>"ev_prepare"</TT> watcher might start an idle watcher to keep <TT>"ev_run"</TT> from
|
|
blocking).
|
|
<DT id="64">"EV_EMBED"<DD>
|
|
|
|
|
|
|
|
|
|
The embedded event loop specified in the <TT>"ev_embed"</TT> watcher needs attention.
|
|
<DT id="65">"EV_FORK"<DD>
|
|
|
|
|
|
|
|
|
|
The event loop has been resumed in the child process after fork (see
|
|
<TT>"ev_fork"</TT>).
|
|
<DT id="66">"EV_CLEANUP"<DD>
|
|
|
|
|
|
|
|
|
|
The event loop is about to be destroyed (see <TT>"ev_cleanup"</TT>).
|
|
<DT id="67">"EV_ASYNC"<DD>
|
|
|
|
|
|
|
|
|
|
The given async watcher has been asynchronously notified (see <TT>"ev_async"</TT>).
|
|
<DT id="68">"EV_CUSTOM"<DD>
|
|
|
|
|
|
|
|
|
|
Not ever sent (or otherwise used) by libev itself, but can be freely used
|
|
by libev users to signal watchers (e.g. via <TT>"ev_feed_event"</TT>).
|
|
<DT id="69">"EV_ERROR"<DD>
|
|
|
|
|
|
|
|
|
|
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.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
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.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Libev will usually signal a few ``dummy'' 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 <B>read()</B> or <B>write()</B>. This will not work in multi-threaded
|
|
programs, though, as the fd could already be closed and reused for another
|
|
thing, so beware.
|
|
</DL>
|
|
<A NAME="lbAO"> </A>
|
|
<H3><FONT SIZE="-1">GENERIC WATCHER FUNCTIONS</FONT></H3>
|
|
|
|
|
|
|
|
<DL COMPACT>
|
|
<DT id="70">"ev_init" (ev_TYPE *watcher, callback)<DD>
|
|
|
|
|
|
|
|
|
|
This macro initialises the generic portion of a watcher. The contents
|
|
of the watcher object can be arbitrary (so <TT>"malloc"</TT> will do). Only
|
|
the generic parts of the watcher are initialised, you <I>need</I> to call
|
|
the type-specific <TT>"ev_TYPE_set"</TT> macro afterwards to initialise the
|
|
type-specific parts. For each type there is also a <TT>"ev_TYPE_init"</TT> macro
|
|
which rolls both calls into one.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
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.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
The callback is always of type <TT>"void (*)(struct ev_loop *loop, ev_TYPE *watcher,
|
|
int revents)"</TT>.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Example: Initialise an <TT>"ev_io"</TT> watcher in two steps.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
ev_io w;
|
|
ev_init (&w, my_cb);
|
|
ev_io_set (&w, STDIN_FILENO, EV_READ);
|
|
|
|
</PRE>
|
|
|
|
|
|
<DT id="71">"ev_TYPE_set" (ev_TYPE *watcher, [args])<DD>
|
|
|
|
|
|
|
|
|
|
This macro initialises the type-specific parts of a watcher. You need to
|
|
call <TT>"ev_init"</TT> at least once before you call this macro, but you can
|
|
call <TT>"ev_TYPE_set"</TT> 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 <TT>"ev_init"</TT> macro).
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Although some watcher types do not have type-specific arguments
|
|
(e.g. <TT>"ev_prepare"</TT>) you still need to call its <TT>"set"</TT> macro.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
See <TT>"ev_init"</TT>, above, for an example.
|
|
<DT id="72">"ev_TYPE_init" (ev_TYPE *watcher, callback, [args])<DD>
|
|
|
|
|
|
|
|
|
|
This convenience macro rolls both <TT>"ev_init"</TT> and <TT>"ev_TYPE_set"</TT> macro
|
|
calls into a single call. This is the most convenient method to initialise
|
|
a watcher. The same limitations apply, of course.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Example: Initialise and set an <TT>"ev_io"</TT> watcher in one step.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
ev_io_init (&w, my_cb, STDIN_FILENO, EV_READ);
|
|
|
|
</PRE>
|
|
|
|
|
|
<DT id="73">"ev_TYPE_start" (loop, ev_TYPE *watcher)<DD>
|
|
|
|
|
|
|
|
|
|
Starts (activates) the given watcher. Only active watchers will receive
|
|
events. If the watcher is already active nothing will happen.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Example: Start the <TT>"ev_io"</TT> watcher that is being abused as example in this
|
|
whole section.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
ev_io_start (EV_DEFAULT_UC, &w);
|
|
|
|
</PRE>
|
|
|
|
|
|
<DT id="74">"ev_TYPE_stop" (loop, ev_TYPE *watcher)<DD>
|
|
|
|
|
|
|
|
|
|
Stops the given watcher if active, and clears the pending status (whether
|
|
the watcher was active or not).
|
|
|
|
|
|
<P>
|
|
|
|
|
|
It is possible that stopped watchers are pending - for example,
|
|
non-repeating timers are being stopped when they become pending - but
|
|
calling <TT>"ev_TYPE_stop"</TT> 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 <TT>"ev_TYPE_stop"</TT> function.
|
|
<DT id="75">bool ev_is_active (ev_TYPE *watcher)<DD>
|
|
|
|
|
|
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.
|
|
<DT id="76">bool ev_is_pending (ev_TYPE *watcher)<DD>
|
|
|
|
|
|
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
|
|
<TT>"ev_TYPE_set"</TT> is safe), you must not change its priority, and you must
|
|
make sure the watcher is available to libev (e.g. you cannot <TT>"free ()"</TT>
|
|
it).
|
|
<DT id="77">callback ev_cb (ev_TYPE *watcher)<DD>
|
|
|
|
|
|
Returns the callback currently set on the watcher.
|
|
<DT id="78">ev_set_cb (ev_TYPE *watcher, callback)<DD>
|
|
|
|
|
|
Change the callback. You can change the callback at virtually any time
|
|
(modulo threads).
|
|
<DT id="79">ev_set_priority (ev_TYPE *watcher, int priority)<DD>
|
|
|
|
|
|
|
|
<DT id="80">int ev_priority (ev_TYPE *watcher)<DD>
|
|
|
|
|
|
|
|
Set and query the priority of the watcher. The priority is a small
|
|
integer between <TT>"EV_MAXPRI"</TT> (default: <TT>2</TT>) and <TT>"EV_MINPRI"</TT>
|
|
(default: <TT>"-2"</TT>). Pending watchers with higher priority will be invoked
|
|
before watchers with lower priority, but priority will not keep watchers
|
|
from being executed (except for <TT>"ev_idle"</TT> watchers).
|
|
|
|
|
|
<P>
|
|
|
|
|
|
If you need to suppress invocation when higher priority events are pending
|
|
you need to look at <TT>"ev_idle"</TT> watchers, which provide this functionality.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
You <I>must not</I> change the priority of a watcher as long as it is active or
|
|
pending.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Setting a priority outside the range of <TT>"EV_MINPRI"</TT> to <TT>"EV_MAXPRI"</TT> 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.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
The default priority used by watchers when no priority has been set is
|
|
always <TT>0</TT>, which is supposed to not be too high and not be too low :).
|
|
|
|
|
|
<P>
|
|
|
|
|
|
See ``<FONT SIZE="-1">WATCHER PRIORITY MODELS''</FONT>, below, for a more thorough treatment of
|
|
priorities.
|
|
<DT id="81">ev_invoke (loop, ev_TYPE *watcher, int revents)<DD>
|
|
|
|
|
|
Invoke the <TT>"watcher"</TT> with the given <TT>"loop"</TT> and <TT>"revents"</TT>. Neither
|
|
<TT>"loop"</TT> nor <TT>"revents"</TT> need to be valid as long as the watcher callback
|
|
can deal with that fact, as both are simply passed through to the
|
|
callback.
|
|
<DT id="82">int ev_clear_pending (loop, ev_TYPE *watcher)<DD>
|
|
|
|
|
|
If the watcher is pending, this function clears its pending status and
|
|
returns its <TT>"revents"</TT> bitset (as if its callback was invoked). If the
|
|
watcher isn't pending it does nothing and returns <TT>0</TT>.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Sometimes it can be useful to ``poll'' a watcher instead of waiting for its
|
|
callback to be invoked, which can be accomplished with this function.
|
|
<DT id="83">ev_feed_event (loop, ev_TYPE *watcher, int revents)<DD>
|
|
|
|
|
|
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.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Stopping the watcher, letting libev invoke it, or calling
|
|
<TT>"ev_clear_pending"</TT> will clear the pending event, even if the watcher was
|
|
not started in the first place.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
See also <TT>"ev_feed_fd_event"</TT> and <TT>"ev_feed_signal_event"</TT> for related
|
|
functions that do not need a watcher.
|
|
</DL>
|
|
<P>
|
|
|
|
See also the ``<FONT SIZE="-1">ASSOCIATING CUSTOM DATA WITH A WATCHER''</FONT> and ``<FONT SIZE="-1">BUILDING YOUR
|
|
OWN COMPOSITE WATCHERS''</FONT> idioms.
|
|
<A NAME="lbAP"> </A>
|
|
<H3><FONT SIZE="-1">WATCHER STATES</FONT></H3>
|
|
|
|
|
|
|
|
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 ``the right thing''.
|
|
<DL COMPACT>
|
|
<DT id="84">initialised<DD>
|
|
|
|
|
|
Before a watcher can be registered with the event loop it has to be
|
|
initialised. This can be done with a call to <TT>"ev_TYPE_init"</TT>, or calls to
|
|
<TT>"ev_init"</TT> followed by the watcher-specific <TT>"ev_TYPE_set"</TT> function.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
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
|
|
<TT>"ev_TYPE_init"</TT> again.
|
|
<DT id="85">started/running/active<DD>
|
|
|
|
|
|
Once a watcher has been started with a call to <TT>"ev_TYPE_start"</TT> 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.
|
|
<DT id="86">pending<DD>
|
|
|
|
|
|
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.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
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 <TT>"ev_TYPE_set"</TT>),
|
|
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.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
It is also possible to feed an event on a watcher that is not active (e.g.
|
|
via <TT>"ev_feed_event"</TT>), in which case it becomes pending without being
|
|
active.
|
|
<DT id="87">stopped<DD>
|
|
|
|
|
|
A watcher can be stopped implicitly by libev (in which case it might still
|
|
be pending), or explicitly by calling its <TT>"ev_TYPE_stop"</TT> 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.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
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 <TT>"ev_TYPE_init"</TT>
|
|
it again).
|
|
</DL>
|
|
<A NAME="lbAQ"> </A>
|
|
<H3><FONT SIZE="-1">WATCHER PRIORITY MODELS</FONT></H3>
|
|
|
|
|
|
|
|
Many event loops support <I>watcher priorities</I>, which are usually small
|
|
integers that influence the ordering of event callback invocation
|
|
between watchers in some way, all else being equal.
|
|
<P>
|
|
|
|
In libev, watcher priorities can be set using <TT>"ev_set_priority"</TT>. See its
|
|
description for the more technical details such as the actual priority
|
|
range.
|
|
<P>
|
|
|
|
There are two common ways how these these priorities are being interpreted
|
|
by event loops:
|
|
<P>
|
|
|
|
In the more common lock-out model, higher priorities ``lock out'' invocation
|
|
of lower priority watchers, which means as long as higher priority
|
|
watchers receive events, lower priority watchers are not being invoked.
|
|
<P>
|
|
|
|
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.
|
|
<P>
|
|
|
|
Libev uses the second (only-for-ordering) model for all its watchers
|
|
except for idle watchers (which use the lock-out model).
|
|
<P>
|
|
|
|
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.
|
|
<P>
|
|
|
|
Static (ordering) priorities are most useful when you have two or more
|
|
watchers handling the same resource: a typical usage example is having an
|
|
<TT>"ev_io"</TT> watcher to receive data, and an associated <TT>"ev_timer"</TT> 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).
|
|
<P>
|
|
|
|
Since idle watchers use the ``lock-out'' 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 ``lock-out'' model when
|
|
required.
|
|
<P>
|
|
|
|
For example, to emulate how many other event libraries handle priorities,
|
|
you can associate an <TT>"ev_idle"</TT> 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.
|
|
<P>
|
|
|
|
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.
|
|
<P>
|
|
|
|
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:
|
|
<P>
|
|
|
|
|
|
|
|
<PRE>
|
|
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);
|
|
|
|
</PRE>
|
|
|
|
|
|
<P>
|
|
|
|
In the ``real'' 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.
|
|
<A NAME="lbAR"> </A>
|
|
<H2>WATCHER TYPES</H2>
|
|
|
|
|
|
|
|
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.
|
|
<P>
|
|
|
|
Members are additionally marked with either <I>[read-only]</I>, 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 <I>[read-write]</I>, 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.
|
|
<A NAME="lbAS"> </A>
|
|
<H3>ev_io - is this file descriptor readable or writable?</H3>
|
|
|
|
|
|
|
|
|
|
|
|
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.
|
|
<P>
|
|
|
|
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).
|
|
<P>
|
|
|
|
Another thing you have to watch out for is that it is quite easy to
|
|
receive ``spurious'' readiness notifications, that is, your callback might
|
|
be called with <TT>"EV_READ"</TT> but a subsequent <TT>"read"</TT>(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 <TT>"read"</TT>(2) returning <TT>"EAGAIN"</TT> is far
|
|
preferable to a program hanging until some data arrives.
|
|
<P>
|
|
|
|
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 <TT>"SIGALRM"</TT> and an interval timer, just to be sure you won't block
|
|
indefinitely.
|
|
<P>
|
|
|
|
But really, best use non-blocking mode.
|
|
<P>
|
|
|
|
<I>The special problem of disappearing file descriptors</I>
|
|
|
|
|
|
<P>
|
|
|
|
Some backends (e.g. kqueue, epoll, linuxaio) need to be told about closing
|
|
a file descriptor (either due to calling <TT>"close"</TT> explicitly or any other
|
|
means, such as <TT>"dup2"</TT>). 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.
|
|
<P>
|
|
|
|
To avoid having to explicitly tell libev about such cases, libev follows
|
|
the following policy: Each time <TT>"ev_io_set"</TT> 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 <I>have</I> to call <TT>"ev_io_set"</TT> (or <TT>"ev_io_init"</TT>) when you change the
|
|
descriptor even if the file descriptor number itself did not change.
|
|
<P>
|
|
|
|
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.
|
|
<P>
|
|
|
|
<I>The special problem of dup'ed file descriptors</I>
|
|
|
|
|
|
<P>
|
|
|
|
Some backends (e.g. epoll), cannot register events for file descriptors,
|
|
but only events for the underlying file descriptions. That means when you
|
|
have <TT>"dup ()"</TT>'ed file descriptors or weirder constellations, and register
|
|
events for them, only one file descriptor might actually receive events.
|
|
<P>
|
|
|
|
There is no workaround possible except not registering events
|
|
for potentially <TT>"dup ()"</TT>'ed file descriptors, or to resort to
|
|
<TT>"EVBACKEND_SELECT"</TT> or <TT>"EVBACKEND_POLL"</TT>.
|
|
<P>
|
|
|
|
<I>The special problem of files</I>
|
|
|
|
|
|
<P>
|
|
|
|
Many people try to use <TT>"select"</TT> (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).
|
|
<P>
|
|
|
|
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.
|
|
<P>
|
|
|
|
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.
|
|
<P>
|
|
|
|
Since files are typically not-so-well supported by advanced notification
|
|
mechanism, libev tries hard to emulate <FONT SIZE="-1">POSIX</FONT> behaviour with respect
|
|
to files, even though you should not use it. The reason for this is
|
|
convenience: sometimes you want to watch <FONT SIZE="-1">STDIN</FONT> or <FONT SIZE="-1">STDOUT,</FONT> which is
|
|
usually a tty, often a pipe, but also sometimes files or special devices
|
|
(for example, <TT>"epoll"</TT> on Linux works with <I>/dev/random</I> but not with
|
|
<I>/dev/urandom</I>), 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.
|
|
<P>
|
|
|
|
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 <FONT SIZE="-1">STDIN/STDOUT,</FONT> or
|
|
when you rarely read from a file instead of from a socket, and want to
|
|
reuse the same code path.
|
|
<P>
|
|
|
|
<I>The special problem of fork</I>
|
|
|
|
|
|
<P>
|
|
|
|
Some backends (epoll, kqueue, linuxaio, iouring) do not support <TT>"fork ()"</TT>
|
|
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.
|
|
<P>
|
|
|
|
To support fork in your child processes, you have to call <TT>"ev_loop_fork
|
|
()"</TT> after a fork in the child, enable <TT>"EVFLAG_FORKCHECK"</TT>, or resort to
|
|
<TT>"EVBACKEND_SELECT"</TT> or <TT>"EVBACKEND_POLL"</TT>.
|
|
<P>
|
|
|
|
<I>The special problem of </I><FONT SIZE="-1"><I>SIGPIPE</I></FONT><I></I>
|
|
|
|
|
|
<P>
|
|
|
|
While not really specific to libev, it is easy to forget about <TT>"SIGPIPE"</TT>:
|
|
when writing to a pipe whose other end has been closed, your program gets
|
|
sent a <FONT SIZE="-1">SIGPIPE,</FONT> which, by default, aborts your program. For most programs
|
|
this is sensible behaviour, for daemons, this is usually undesirable.
|
|
<P>
|
|
|
|
So when you encounter spurious, unexplained daemon exits, make sure you
|
|
ignore <FONT SIZE="-1">SIGPIPE</FONT> (and maybe make sure you log the exit status of your daemon
|
|
somewhere, as that would have given you a big clue).
|
|
<P>
|
|
|
|
<I>The special problem of </I>accept()<I>ing when you can't</I>
|
|
|
|
|
|
<P>
|
|
|
|
Many implementations of the <FONT SIZE="-1">POSIX</FONT> <TT>"accept"</TT> 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.
|
|
<P>
|
|
|
|
For example, larger servers often run out of file descriptors (because
|
|
of resource limits), causing <TT>"accept"</TT> to fail with <TT>"ENFILE"</TT> 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% <FONT SIZE="-1">CPU</FONT> usage.
|
|
<P>
|
|
|
|
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).
|
|
<P>
|
|
|
|
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 <FONT SIZE="-1">OS</FONT> offers an
|
|
event-based way to handle this situation, so it's the best one can do.
|
|
<P>
|
|
|
|
A better way to handle the situation is to log any errors other than
|
|
<TT>"EAGAIN"</TT> and <TT>"EWOULDBLOCK"</TT>, 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 <TT>"ev_io"</TT> watcher on the listening fd ``for a while'', which reduces <FONT SIZE="-1">CPU</FONT>
|
|
usage.
|
|
<P>
|
|
|
|
If your program is single-threaded, then you could also keep a dummy file
|
|
descriptor for overload situations (e.g. by opening <I>/dev/null</I>), and
|
|
when you run into <TT>"ENFILE"</TT> or <TT>"EMFILE"</TT>, close it, run <TT>"accept"</TT>,
|
|
close that fd, and create a new dummy fd. This will gracefully refuse
|
|
clients under typical overload conditions.
|
|
<P>
|
|
|
|
The last way to handle it is to simply log the error and <TT>"exit"</TT>, as
|
|
is often done with <TT>"malloc"</TT> failures, but this results in an easy
|
|
opportunity for a DoS attack.
|
|
<P>
|
|
|
|
<I>Watcher-Specific Functions</I>
|
|
|
|
|
|
<DL COMPACT>
|
|
<DT id="88">ev_io_init (ev_io *, callback, int fd, int events)<DD>
|
|
|
|
|
|
|
|
<DT id="89">ev_io_set (ev_io *, int fd, int events)<DD>
|
|
|
|
|
|
|
|
Configures an <TT>"ev_io"</TT> watcher. The <TT>"fd"</TT> is the file descriptor to
|
|
receive events for and <TT>"events"</TT> is either <TT>"EV_READ"</TT>, <TT>"EV_WRITE"</TT> or
|
|
<TT>"EV_READ | EV_WRITE"</TT>, to express the desire to receive the given events.
|
|
<DT id="90">int fd [read-only]<DD>
|
|
|
|
|
|
The file descriptor being watched.
|
|
<DT id="91">int events [read-only]<DD>
|
|
|
|
|
|
The events being watched.
|
|
</DL>
|
|
<P>
|
|
|
|
<I>Examples</I>
|
|
|
|
|
|
<P>
|
|
|
|
Example: Call <TT>"stdin_readable_cb"</TT> when <FONT SIZE="-1">STDIN_FILENO</FONT> has become, well
|
|
readable, but only once. Since it is likely line-buffered, you could
|
|
attempt to read a whole line in the callback.
|
|
<P>
|
|
|
|
|
|
|
|
<PRE>
|
|
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);
|
|
|
|
</PRE>
|
|
|
|
|
|
<A NAME="lbAT"> </A>
|
|
<H3>ev_timer - relative and optionally repeating timeouts</H3>
|
|
|
|
|
|
|
|
|
|
|
|
Timer watchers are simple relative timers that generate an event after a
|
|
given time, and optionally repeating in regular intervals after that.
|
|
<P>
|
|
|
|
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).
|
|
<P>
|
|
|
|
The callback is guaranteed to be invoked only <I>after</I> its timeout has
|
|
passed (not <I>at</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 <TT>"ev_run"</TT> recursively).
|
|
<P>
|
|
|
|
<I>Be smart about timeouts</I>
|
|
|
|
|
|
<P>
|
|
|
|
Many real-world problems involve some kind of timeout, usually for error
|
|
recovery. A typical example is an <FONT SIZE="-1">HTTP</FONT> request - if the other side hangs,
|
|
you want to raise some error after a while.
|
|
<P>
|
|
|
|
What follows are some ways to handle this problem, from obvious and
|
|
inefficient to smart and efficient.
|
|
<P>
|
|
|
|
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).
|
|
<DL COMPACT>
|
|
<DT id="92">1. Use a timer and stop, reinitialise and start it on activity.<DD>
|
|
|
|
|
|
This is the most obvious, but not the most simple way: In the beginning,
|
|
start the watcher:
|
|
|
|
|
|
<P>
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
ev_timer_init (timer, callback, 60., 0.);
|
|
ev_timer_start (loop, timer);
|
|
|
|
</PRE>
|
|
|
|
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Then, each time there is some activity, <TT>"ev_timer_stop"</TT> it, initialise it
|
|
and start it again:
|
|
|
|
|
|
<P>
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
ev_timer_stop (loop, timer);
|
|
ev_timer_set (timer, 60., 0.);
|
|
ev_timer_start (loop, timer);
|
|
|
|
</PRE>
|
|
|
|
|
|
|
|
|
|
<P>
|
|
|
|
|
|
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.
|
|
<DT id="93">2. Use a timer and re-start it with "ev_timer_again" inactivity.<DD>
|
|
|
|
|
|
|
|
|
|
This is the easiest way, and involves using <TT>"ev_timer_again"</TT> instead of
|
|
<TT>"ev_timer_start"</TT>.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
To implement this, configure an <TT>"ev_timer"</TT> with a <TT>"repeat"</TT> value
|
|
of <TT>60</TT> and then call <TT>"ev_timer_again"</TT> 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 <TT>"ev_timer_stop"</TT>
|
|
the timer, and <TT>"ev_timer_again"</TT> will automatically restart it if need be.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
That means you can ignore both the <TT>"ev_timer_start"</TT> function and the
|
|
<TT>"after"</TT> argument to <TT>"ev_timer_set"</TT>, and only ever use the <TT>"repeat"</TT>
|
|
member and <TT>"ev_timer_again"</TT>.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
At start:
|
|
|
|
|
|
<P>
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
ev_init (timer, callback);
|
|
timer->repeat = 60.;
|
|
ev_timer_again (loop, timer);
|
|
|
|
</PRE>
|
|
|
|
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Each time there is some activity:
|
|
|
|
|
|
<P>
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
ev_timer_again (loop, timer);
|
|
|
|
</PRE>
|
|
|
|
|
|
|
|
|
|
<P>
|
|
|
|
|
|
It is even possible to change the time-out on the fly, regardless of
|
|
whether the watcher is active or not:
|
|
|
|
|
|
<P>
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
timer->repeat = 30.;
|
|
ev_timer_again (loop, timer);
|
|
|
|
</PRE>
|
|
|
|
|
|
|
|
|
|
<P>
|
|
|
|
|
|
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.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
It is, however, even simpler than the ``obvious'' way to do it.
|
|
<DT id="94">3. Let the timer time out, but then re-arm it as required.<DD>
|
|
|
|
|
|
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.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
In this case, it would be more efficient to leave the <TT>"ev_timer"</TT> alone,
|
|
but remember the time of last activity, and check for a real timeout only
|
|
within the callback:
|
|
|
|
|
|
<P>
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
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);
|
|
}
|
|
}
|
|
|
|
</PRE>
|
|
|
|
|
|
|
|
|
|
<P>
|
|
|
|
|
|
To summarise the callback: first calculate in how many seconds the
|
|
timeout will occur (by calculating the absolute time when it would occur,
|
|
<TT>"last_activity + timeout"</TT>, and subtracting the current time, <TT>"ev_now
|
|
(EV_A)"</TT> from that).
|
|
|
|
|
|
<P>
|
|
|
|
|
|
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.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Otherwise, we now the earliest time at which the timeout would trigger,
|
|
and simply start the timer with this timeout value.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
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.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
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.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
To start the machinery, simply initialise the watcher and set
|
|
<TT>"last_activity"</TT> 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:
|
|
|
|
|
|
<P>
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
last_activity = ev_now (EV_A);
|
|
ev_init (&timer, callback);
|
|
callback (EV_A_ &timer, 0);
|
|
|
|
</PRE>
|
|
|
|
|
|
|
|
|
|
<P>
|
|
|
|
|
|
When there is some activity, simply store the current time in
|
|
<TT>"last_activity"</TT>, no libev calls at all:
|
|
|
|
|
|
<P>
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
if (activity detected)
|
|
last_activity = ev_now (EV_A);
|
|
|
|
</PRE>
|
|
|
|
|
|
|
|
|
|
<P>
|
|
|
|
|
|
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 :).
|
|
|
|
|
|
<P>
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
timeout = new_value;
|
|
ev_timer_stop (EV_A_ &timer);
|
|
callback (EV_A_ &timer, 0);
|
|
|
|
</PRE>
|
|
|
|
|
|
|
|
|
|
<P>
|
|
|
|
|
|
This technique is slightly more complex, but in most cases where the
|
|
time-out is unlikely to be triggered, much more efficient.
|
|
<DT id="95">4. Wee, just use a double-linked list for your timeouts.<DD>
|
|
|
|
|
|
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:
|
|
|
|
|
|
<P>
|
|
|
|
|
|
When starting the timeout, calculate the timeout value and put the timeout
|
|
at the <I>end</I> of the list.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Then use an <TT>"ev_timer"</TT> to fire when the timeout at the <I>beginning</I> of
|
|
the list is expected to fire (for example, using the technique #3).
|
|
|
|
|
|
<P>
|
|
|
|
|
|
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 <TT>"ev_timer"</TT> if it was taken from the beginning of the list.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
This way, one can manage an unlimited number of timeouts in <A HREF="/cgi-bin/man/man2html?1+O">O</A>(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.
|
|
</DL>
|
|
<P>
|
|
|
|
So which method the best?
|
|
<P>
|
|
|
|
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.
|
|
<P>
|
|
|
|
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 :)
|
|
<P>
|
|
|
|
<I>The special problem of being too early</I>
|
|
|
|
|
|
<P>
|
|
|
|
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 <FONT SIZE="-1">STOP</FONT> signal for a few hours for example.
|
|
<P>
|
|
|
|
So, libev tries to invoke your callback as soon as possible <I>after</I> the
|
|
delay has occurred, but cannot guarantee this.
|
|
<P>
|
|
|
|
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.
|
|
<P>
|
|
|
|
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 <FONT SIZE="-1">OS</FONT>
|
|
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.
|
|
<P>
|
|
|
|
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.
|
|
<P>
|
|
|
|
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.
|
|
<P>
|
|
|
|
So, while libev cannot guarantee that your callback will be invoked
|
|
exactly when requested, it <I>can</I> and <I>does</I> guarantee that the requested
|
|
delay has actually elapsed, or in other words, it always errs on the ``too
|
|
late'' side of things.
|
|
<P>
|
|
|
|
<I>The special problem of time updates</I>
|
|
|
|
|
|
<P>
|
|
|
|
Establishing the current time is a costly operation (it usually takes
|
|
at least one system call): <FONT SIZE="-1">EV</FONT> therefore updates its idea of the current
|
|
time only before and after <TT>"ev_run"</TT> collects new events, which causes a
|
|
growing difference between <TT>"ev_now ()"</TT> and <TT>"ev_time ()"</TT> when handling
|
|
lots of events in one iteration.
|
|
<P>
|
|
|
|
The relative timeouts are calculated relative to the <TT>"ev_now ()"</TT>
|
|
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>need</I> to base the
|
|
timeout on the current time, use something like the following to adjust
|
|
for it:
|
|
<P>
|
|
|
|
|
|
|
|
<PRE>
|
|
ev_timer_set (&timer, after + (ev_time () - ev_now ()), 0.);
|
|
|
|
</PRE>
|
|
|
|
|
|
<P>
|
|
|
|
If the event loop is suspended for a long time, you can also force an
|
|
update of the time returned by <TT>"ev_now ()"</TT> by calling <TT>"ev_now_update
|
|
()"</TT>, although that will push the event time of all outstanding events
|
|
further into the future.
|
|
<P>
|
|
|
|
<I>The special problem of unsynchronised clocks</I>
|
|
|
|
|
|
<P>
|
|
|
|
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).
|
|
<P>
|
|
|
|
Neither of these clocks is synchronised with each other or any other clock
|
|
on the system, so <TT>"ev_time ()"</TT> might return a considerably different time
|
|
than <TT>"gettimeofday ()"</TT> or <TT>"time ()"</TT>. On a GNU/Linux system, for example,
|
|
a call to <TT>"gettimeofday"</TT> might return a second count that is one higher
|
|
than a directly following call to <TT>"time"</TT>.
|
|
<P>
|
|
|
|
The moral of this is to only compare libev-related timestamps with
|
|
<TT>"ev_time ()"</TT> and <TT>"ev_now ()"</TT>, at least if you want better precision than
|
|
a second or so.
|
|
<P>
|
|
|
|
One more problem arises due to this lack of synchronisation: if libev uses
|
|
the system monotonic clock and you compare timestamps from <TT>"ev_time"</TT>
|
|
or <TT>"ev_now"</TT> from when you started your timer and when your callback is
|
|
invoked, you will find that sometimes the callback is a bit ``early''.
|
|
<P>
|
|
|
|
This is because <TT>"ev_timer"</TT>s work in real time, not wall clock time, so
|
|
libev makes sure your callback is not invoked before the delay happened,
|
|
<I>measured according to the real time</I>, not the system clock.
|
|
<P>
|
|
|
|
If your timeouts are based on a physical timescale (e.g. ``time out this
|
|
connection after 100 seconds'') then this shouldn't bother you as it is
|
|
exactly the right behaviour.
|
|
<P>
|
|
|
|
If you want to compare wall clock/system timestamps to your timers, then
|
|
you need to use <TT>"ev_periodic"</TT>s, as these are based on the wall clock
|
|
time, where your comparisons will always generate correct results.
|
|
<P>
|
|
|
|
<I>The special problems of suspended animation</I>
|
|
|
|
|
|
<P>
|
|
|
|
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?
|
|
<P>
|
|
|
|
Some quick tests made with a Linux 2.6.28 indicate that a suspend freezes
|
|
all processes, while the clocks (<TT>"times"</TT>, <TT>"CLOCK_MONOTONIC"</TT>) 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 <TT>"ev_timer"</TT> 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.
|
|
<P>
|
|
|
|
I would not be surprised to see different behaviour in different between
|
|
operating systems, <FONT SIZE="-1">OS</FONT> versions or even different hardware.
|
|
<P>
|
|
|
|
The other form of suspend (job control, or sending a <FONT SIZE="-1">SIGSTOP</FONT>) 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 <TT>"ev_timer"</TT>s 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.
|
|
<P>
|
|
|
|
It might be beneficial for this latter case to call <TT>"ev_suspend"</TT>
|
|
and <TT>"ev_resume"</TT> in code that handles <TT>"SIGTSTP"</TT>, to at least get
|
|
deterministic behaviour in this case (you can do nothing against
|
|
<TT>"SIGSTOP"</TT>).
|
|
<P>
|
|
|
|
<I>Watcher-Specific Functions and Data Members</I>
|
|
|
|
|
|
<DL COMPACT>
|
|
<DT id="96">ev_timer_init (ev_timer *, callback, ev_tstamp after, ev_tstamp repeat)<DD>
|
|
|
|
|
|
|
|
<DT id="97">ev_timer_set (ev_timer *, ev_tstamp after, ev_tstamp repeat)<DD>
|
|
|
|
|
|
|
|
Configure the timer to trigger after <TT>"after"</TT> seconds (fractional and
|
|
negative values are supported). If <TT>"repeat"</TT> is <TT>0.</TT>, 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 <TT>"repeat"</TT>
|
|
seconds later, again, and again, until stopped manually.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
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.
|
|
<DT id="98">ev_timer_again (loop, ev_timer *)<DD>
|
|
|
|
|
|
This will act as if the timer timed out, and restarts it again if it is
|
|
repeating. It basically works like calling <TT>"ev_timer_stop"</TT>, updating the
|
|
timeout to the <TT>"repeat"</TT> value and calling <TT>"ev_timer_start"</TT>.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
The exact semantics are as in the following rules, all of which will be
|
|
applied to the watcher:
|
|
<DL COMPACT><DT id="99"><DD>
|
|
<DL COMPACT>
|
|
<DT id="100">If the timer is pending, the pending status is always cleared.<DD>
|
|
|
|
|
|
|
|
<DT id="101">If the timer is started but non-repeating, stop it (as if it timed out, without invoking it).<DD>
|
|
|
|
|
|
<DT id="102">If the timer is repeating, make the "repeat" value the new timeout and start the timer, if necessary.<DD>
|
|
|
|
|
|
|
|
|
|
</DL>
|
|
</DL>
|
|
|
|
<DL COMPACT><DT id="103"><DD>
|
|
|
|
|
|
|
|
<P>
|
|
|
|
|
|
This sounds a bit complicated, see ``Be smart about timeouts'', above, for a
|
|
usage example.
|
|
</DL>
|
|
|
|
<DT id="104">ev_tstamp ev_timer_remaining (loop, ev_timer *)<DD>
|
|
|
|
|
|
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.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
That is, after an <TT>"ev_timer_set (w, 5, 7)"</TT>, <TT>"ev_timer_remaining"</TT> returns
|
|
<TT>5</TT>. When the timer is started and one second passes, <TT>"ev_timer_remaining"</TT>
|
|
will return <TT>4</TT>. When the timer expires and is restarted, it will return
|
|
roughly <TT>7</TT> (likely slightly less as callback invocation takes some time,
|
|
too), and so on.
|
|
<DT id="105">ev_tstamp repeat [read-write]<DD>
|
|
|
|
|
|
The current <TT>"repeat"</TT> value. Will be used each time the watcher times out
|
|
or <TT>"ev_timer_again"</TT> is called, and determines the next timeout (if any),
|
|
which is also when any modifications are taken into account.
|
|
</DL>
|
|
<P>
|
|
|
|
<I>Examples</I>
|
|
|
|
|
|
<P>
|
|
|
|
Example: Create a timer that fires after 60 seconds.
|
|
<P>
|
|
|
|
|
|
|
|
<PRE>
|
|
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);
|
|
|
|
</PRE>
|
|
|
|
|
|
<P>
|
|
|
|
Example: Create a timeout timer that times out after 10 seconds of
|
|
inactivity.
|
|
<P>
|
|
|
|
|
|
|
|
<PRE>
|
|
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);
|
|
|
|
</PRE>
|
|
|
|
|
|
<A NAME="lbAU"> </A>
|
|
<H3>ev_periodic - to cron or not to cron?</H3>
|
|
|
|
|
|
|
|
|
|
|
|
Periodic watchers are also timers of a kind, but they are very versatile
|
|
(and unfortunately a bit complex).
|
|
<P>
|
|
|
|
Unlike <TT>"ev_timer"</TT>, 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).
|
|
<P>
|
|
|
|
You can tell a periodic watcher to trigger after some specific point
|
|
in time: for example, if you tell a periodic watcher to trigger ``in 10
|
|
seconds'' (by specifying e.g. <TT>"ev_now () + 10."</TT>, 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
|
|
<TT>"ev_timer"</TT>, which would still trigger roughly 10 seconds after starting
|
|
it, as it uses a relative timeout).
|
|
<P>
|
|
|
|
<TT>"ev_periodic"</TT> watchers can also be used to implement vastly more complex
|
|
timers, such as triggering an event on each ``midnight, local time'', or
|
|
other complicated rules. This cannot easily be done with <TT>"ev_timer"</TT>
|
|
watchers, as those cannot react to time jumps.
|
|
<P>
|
|
|
|
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 <TT>"ev_run"</TT> recursively).
|
|
<P>
|
|
|
|
<I>Watcher-Specific Functions and Data Members</I>
|
|
|
|
|
|
<DL COMPACT>
|
|
<DT id="106">ev_periodic_init (ev_periodic *, callback, ev_tstamp offset, ev_tstamp interval, reschedule_cb)<DD>
|
|
|
|
|
|
|
|
<DT id="107">ev_periodic_set (ev_periodic *, ev_tstamp offset, ev_tstamp interval, reschedule_cb)<DD>
|
|
|
|
|
|
|
|
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:
|
|
<DL COMPACT><DT id="108"><DD>
|
|
<DL COMPACT>
|
|
<DT id="109">•<DD>
|
|
absolute timer (offset = absolute time, interval = 0, reschedule_cb = 0)
|
|
|
|
|
|
<P>
|
|
|
|
|
|
In this configuration the watcher triggers an event after the wall clock
|
|
time <TT>"offset"</TT> 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.
|
|
<DT id="110">•<DD>
|
|
repeating interval timer (offset = offset within interval, interval > 0, reschedule_cb = 0)
|
|
|
|
|
|
<P>
|
|
|
|
|
|
In this mode the watcher will always be scheduled to time out at the next
|
|
<TT>"offset + N * interval"</TT> time (for some integer N, which can also be
|
|
negative) and then repeat, regardless of any time jumps. The <TT>"offset"</TT>
|
|
argument is merely an offset into the <TT>"interval"</TT> periods.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
This can be used to create timers that do not drift with respect to the
|
|
system clock, for example, here is an <TT>"ev_periodic"</TT> that triggers each
|
|
hour, on the hour (with respect to <FONT SIZE="-1">UTC</FONT>):
|
|
|
|
|
|
<P>
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
ev_periodic_set (&periodic, 0., 3600., 0);
|
|
|
|
</PRE>
|
|
|
|
|
|
|
|
|
|
<P>
|
|
|
|
|
|
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 (<FONT SIZE="-1">UTC</FONT>), or more correctly, when the system time is evenly divisible
|
|
by 3600.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Another way to think about it (for the mathematically inclined) is that
|
|
<TT>"ev_periodic"</TT> will try to run the callback in this mode at the next possible
|
|
time where <TT>"time = offset (mod interval)"</TT>, regardless of any time jumps.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
The <TT>"interval"</TT> <I></I><FONT SIZE="-1"><I>MUST</I></FONT><I></I> be positive, and for numerical stability, the
|
|
interval value should be higher than <TT>"1/8192"</TT> (which is around 100
|
|
microseconds) and <TT>"offset"</TT> should be higher than <TT>0</TT> 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, <TT>0</TT> or something between
|
|
<TT>0</TT> and <TT>"interval"</TT>, which is also the recommended range.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Note also that there is an upper limit to how often a timer can fire (<FONT SIZE="-1">CPU</FONT>
|
|
speed for example), so if <TT>"interval"</TT> is very small then timing stability
|
|
will of course deteriorate. Libev itself tries to be exact to be about one
|
|
millisecond (if the <FONT SIZE="-1">OS</FONT> supports it and the machine is fast enough).
|
|
<DT id="111">•<DD>
|
|
manual reschedule mode (offset ignored, interval ignored, reschedule_cb = callback)
|
|
|
|
|
|
<P>
|
|
|
|
|
|
In this mode the values for <TT>"interval"</TT> and <TT>"offset"</TT> 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.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
<FONT SIZE="-1">NOTE:</FONT> <I>This callback </I><FONT SIZE="-1"><I>MUST NOT</I></FONT><I> stop or destroy any periodic watcher, ever,
|
|
or make </I><FONT SIZE="-1"><I>ANY</I></FONT><I> other event loop modifications whatsoever, unless explicitly
|
|
allowed by documentation here</I>.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
If you need to stop it, return <TT>"now + 1e30"</TT> (or so, fudge fudge) and stop
|
|
it afterwards (e.g. by starting an <TT>"ev_prepare"</TT> watcher, which is the
|
|
only event loop modification you are allowed to do).
|
|
|
|
|
|
<P>
|
|
|
|
|
|
The callback prototype is <TT>"ev_tstamp (*reschedule_cb)(ev_periodic
|
|
*w, ev_tstamp now)"</TT>, e.g.:
|
|
|
|
|
|
<P>
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
static ev_tstamp
|
|
my_rescheduler (ev_periodic *w, ev_tstamp now)
|
|
{
|
|
return now + 60.;
|
|
}
|
|
|
|
</PRE>
|
|
|
|
|
|
|
|
|
|
<P>
|
|
|
|
|
|
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.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
<FONT SIZE="-1">NOTE:</FONT> <I>This callback must always return a time that is higher than or
|
|
equal to the passed </I>"now"<I> value</I>.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
This can be used to create very complex timers, such as a timer that
|
|
triggers on ``next midnight, local time''. To do this, you would calculate
|
|
the next midnight after <TT>"now"</TT> and return the timestamp value for
|
|
this. Here is a (completely untested, no error checking) example on how to
|
|
do this:
|
|
|
|
|
|
<P>
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
#include <<A HREF="file:///usr/include/time.h">time.h</A>>
|
|
|
|
static ev_tstamp
|
|
my_rescheduler (ev_periodic *w, ev_tstamp now)
|
|
{
|
|
time_t tnow = (time_t)now;
|
|
struct tm tm;
|
|
localtime_r (&tnow, &tm);
|
|
|
|
tm.tm_sec = tm.tm_min = tm.tm_hour = 0; // midnight current day
|
|
++tm.tm_mday; // midnight next day
|
|
|
|
return mktime (&tm);
|
|
}
|
|
|
|
</PRE>
|
|
|
|
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Note: this code might run into trouble on days that have more then two
|
|
midnights (beginning and end).
|
|
</DL>
|
|
</DL>
|
|
|
|
<DL COMPACT><DT id="112"><DD>
|
|
</DL>
|
|
|
|
<DT id="113">ev_periodic_again (loop, ev_periodic *)<DD>
|
|
|
|
|
|
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).
|
|
<DT id="114">ev_tstamp ev_periodic_at (ev_periodic *)<DD>
|
|
|
|
|
|
When active, returns the absolute time that the watcher is supposed
|
|
to trigger next. This is not the same as the <TT>"offset"</TT> argument to
|
|
<TT>"ev_periodic_set"</TT>, but indeed works even in interval and manual
|
|
rescheduling modes.
|
|
<DT id="115">ev_tstamp offset [read-write]<DD>
|
|
|
|
|
|
When repeating, this contains the offset value, otherwise this is the
|
|
absolute point in time (the <TT>"offset"</TT> value passed to <TT>"ev_periodic_set"</TT>,
|
|
although libev might modify this value for better numerical stability).
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Can be modified any time, but changes only take effect when the periodic
|
|
timer fires or <TT>"ev_periodic_again"</TT> is being called.
|
|
<DT id="116">ev_tstamp interval [read-write]<DD>
|
|
|
|
|
|
The current interval value. Can be modified any time, but changes only
|
|
take effect when the periodic timer fires or <TT>"ev_periodic_again"</TT> is being
|
|
called.
|
|
<DT id="117">ev_tstamp (*reschedule_cb)(ev_periodic *w, ev_tstamp now) [read-write]<DD>
|
|
|
|
|
|
The current reschedule callback, or <TT>0</TT>, if this functionality is
|
|
switched off. Can be changed any time, but changes only take effect when
|
|
the periodic timer fires or <TT>"ev_periodic_again"</TT> is being called.
|
|
</DL>
|
|
<P>
|
|
|
|
<I>Examples</I>
|
|
|
|
|
|
<P>
|
|
|
|
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.
|
|
<P>
|
|
|
|
|
|
|
|
<PRE>
|
|
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);
|
|
|
|
</PRE>
|
|
|
|
|
|
<P>
|
|
|
|
Example: The same as above, but use a reschedule callback to do it:
|
|
<P>
|
|
|
|
|
|
|
|
<PRE>
|
|
#include <<A HREF="file:///usr/include/math.h">math.h</A>>
|
|
|
|
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);
|
|
|
|
</PRE>
|
|
|
|
|
|
<P>
|
|
|
|
Example: Call a callback every hour, starting now:
|
|
<P>
|
|
|
|
|
|
|
|
<PRE>
|
|
ev_periodic hourly_tick;
|
|
ev_periodic_init (&hourly_tick, clock_cb,
|
|
fmod (ev_now (loop), 3600.), 3600., 0);
|
|
ev_periodic_start (loop, &hourly_tick);
|
|
|
|
</PRE>
|
|
|
|
|
|
<A NAME="lbAV"> </A>
|
|
<H3>ev_signal - signal me when a signal gets signalled!</H3>
|
|
|
|
|
|
|
|
|
|
|
|
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.
|
|
<P>
|
|
|
|
If you want signals to be delivered truly asynchronously, just use
|
|
<TT>"sigaction"</TT> as you would do without libev and forget about sharing
|
|
the signal. You can even use <TT>"ev_async"</TT> from a signal handler to
|
|
synchronously wake up an event loop.
|
|
<P>
|
|
|
|
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 <TT>"SIGINT"</TT> in your
|
|
default loop and for <TT>"SIGIO"</TT> in another loop, but you cannot watch for
|
|
<TT>"SIGINT"</TT> in both the default loop and another loop at the same time. At
|
|
the moment, <TT>"SIGCHLD"</TT> is permanently tied to the default loop.
|
|
<P>
|
|
|
|
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.
|
|
<P>
|
|
|
|
If possible and supported, libev will install its handlers with
|
|
<TT>"SA_RESTART"</TT> (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 <TT>"ev_check"</TT> watcher
|
|
and unblock them in an <TT>"ev_prepare"</TT> watcher.
|
|
<P>
|
|
|
|
<I>The special problem of inheritance over fork/execve/pthread_create</I>
|
|
|
|
|
|
<P>
|
|
|
|
Both the signal mask (<TT>"sigprocmask"</TT>) and the signal disposition
|
|
(<TT>"sigaction"</TT>) 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 <TT>"EVFLAG_NOSIGMASK"</TT>).
|
|
<P>
|
|
|
|
While this does not matter for the signal disposition (libev never
|
|
sets signals to <TT>"SIG_IGN"</TT>, so handlers will be reset to <TT>"SIG_DFL"</TT> on
|
|
<TT>"execve"</TT>), this matters for the signal mask: many programs do not expect
|
|
certain signals to be blocked.
|
|
<P>
|
|
|
|
This means that before calling <TT>"exec"</TT> (from the child) you should reset
|
|
the signal mask to whatever ``default'' you expect (all clear is a good
|
|
choice usually).
|
|
<P>
|
|
|
|
The simplest way to ensure that the signal mask is reset in the child is
|
|
to install a fork handler with <TT>"pthread_atfork"</TT> that resets it. That will
|
|
catch fork calls done by libraries (such as the libc) as well.
|
|
<P>
|
|
|
|
In current versions of libev, the signal will not be blocked indefinitely
|
|
unless you use the <TT>"signalfd"</TT> <FONT SIZE="-1">API</FONT> (<TT>"EV_SIGNALFD"</TT>). While this reduces
|
|
the window of opportunity for problems, it will not go away, as libev
|
|
<I>has</I> to modify the signal mask, at least temporarily.
|
|
<P>
|
|
|
|
So I can't stress this enough: <I>If you do not reset your signal mask when
|
|
you expect it to be empty, you have a race condition in your code</I>. This
|
|
is not a libev-specific thing, this is true for most event libraries.
|
|
<P>
|
|
|
|
<I>The special problem of threads signal handling</I>
|
|
|
|
|
|
<P>
|
|
|
|
<FONT SIZE="-1">POSIX</FONT> 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.
|
|
<P>
|
|
|
|
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 <TT>"EVFLAG_NOSIGMASK"</TT> when creating
|
|
loops. Then designate one thread as ``signal receiver thread'' which handles
|
|
these signals. You can pass on any signals that libev might be interested
|
|
in by calling <TT>"ev_feed_signal"</TT>.
|
|
<P>
|
|
|
|
<I>Watcher-Specific Functions and Data Members</I>
|
|
|
|
|
|
<DL COMPACT>
|
|
<DT id="118">ev_signal_init (ev_signal *, callback, int signum)<DD>
|
|
|
|
|
|
|
|
<DT id="119">ev_signal_set (ev_signal *, int signum)<DD>
|
|
|
|
|
|
|
|
Configures the watcher to trigger on the given signal number (usually one
|
|
of the <TT>"SIGxxx"</TT> constants).
|
|
<DT id="120">int signum [read-only]<DD>
|
|
|
|
|
|
The signal the watcher watches out for.
|
|
</DL>
|
|
<P>
|
|
|
|
<I>Examples</I>
|
|
|
|
|
|
<P>
|
|
|
|
Example: Try to exit cleanly on <FONT SIZE="-1">SIGINT.</FONT>
|
|
<P>
|
|
|
|
|
|
|
|
<PRE>
|
|
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);
|
|
|
|
</PRE>
|
|
|
|
|
|
<A NAME="lbAW"> </A>
|
|
<H3>ev_child - watch out for process status changes</H3>
|
|
|
|
|
|
|
|
|
|
|
|
Child watchers trigger when your process receives a <FONT SIZE="-1">SIGCHLD</FONT> 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 <I>after</I> 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.
|
|
<P>
|
|
|
|
Only the default event loop is capable of handling signals, and therefore
|
|
you can only register child watchers in the default event loop.
|
|
<P>
|
|
|
|
Due to some design glitches inside libev, child watchers will always be
|
|
handled at maximum priority (their priority is set to <TT>"EV_MAXPRI"</TT> by
|
|
libev)
|
|
<P>
|
|
|
|
<I>Process Interaction</I>
|
|
|
|
|
|
<P>
|
|
|
|
Libev grabs <TT>"SIGCHLD"</TT> 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 <TT>"SIGCHLD"</TT> 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.
|
|
<P>
|
|
|
|
<I>Overriding the Built-In Processing</I>
|
|
|
|
|
|
<P>
|
|
|
|
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
|
|
<TT>"SIGCHLD"</TT> 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 <TT>"ev_child"</TT> watchers freely.
|
|
<P>
|
|
|
|
<I>Stopping the Child Watcher</I>
|
|
|
|
|
|
<P>
|
|
|
|
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 <TT>"ev_child_stop"</TT> twice is not a
|
|
problem).
|
|
<P>
|
|
|
|
<I>Watcher-Specific Functions and Data Members</I>
|
|
|
|
|
|
<DL COMPACT>
|
|
<DT id="121">ev_child_init (ev_child *, callback, int pid, int trace)<DD>
|
|
|
|
|
|
|
|
<DT id="122">ev_child_set (ev_child *, int pid, int trace)<DD>
|
|
|
|
|
|
|
|
Configures the watcher to wait for status changes of process <TT>"pid"</TT> (or
|
|
<I>any</I> process if <TT>"pid"</TT> is specified as <TT>0</TT>). The callback can look
|
|
at the <TT>"rstatus"</TT> member of the <TT>"ev_child"</TT> watcher structure to see
|
|
the status word (use the macros from <TT>"sys/wait.h"</TT> and see your systems
|
|
<TT>"waitpid"</TT> documentation). The <TT>"rpid"</TT> member contains the pid of the
|
|
process causing the status change. <TT>"trace"</TT> must be either <TT>0</TT> (only
|
|
activate the watcher when the process terminates) or <TT>1</TT> (additionally
|
|
activate the watcher when the process is stopped or continued).
|
|
<DT id="123">int pid [read-only]<DD>
|
|
|
|
|
|
The process id this watcher watches out for, or <TT>0</TT>, meaning any process id.
|
|
<DT id="124">int rpid [read-write]<DD>
|
|
|
|
|
|
The process id that detected a status change.
|
|
<DT id="125">int rstatus [read-write]<DD>
|
|
|
|
|
|
The process exit/trace status caused by <TT>"rpid"</TT> (see your systems
|
|
<TT>"waitpid"</TT> and <TT>"sys/wait.h"</TT> documentation for details).
|
|
</DL>
|
|
<P>
|
|
|
|
<I>Examples</I>
|
|
|
|
|
|
<P>
|
|
|
|
Example: <TT>"fork()"</TT> a new process and install a child handler to wait for
|
|
its completion.
|
|
<P>
|
|
|
|
|
|
|
|
<PRE>
|
|
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\n", 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);
|
|
}
|
|
|
|
</PRE>
|
|
|
|
|
|
<A NAME="lbAX"> </A>
|
|
<H3>ev_stat - did the file attributes just change?</H3>
|
|
|
|
|
|
|
|
|
|
|
|
This watches a file system path for attribute changes. That is, it calls
|
|
<TT>"stat"</TT> on that path in regular intervals (or when the <FONT SIZE="-1">OS</FONT> says it changed)
|
|
and sees if it changed compared to the last time, invoking the callback
|
|
if it did. Starting the watcher <TT>"stat"</TT>'s the file, so only changes that
|
|
happen after the watcher has been started will be reported.
|
|
<P>
|
|
|
|
The path does not need to exist: changing from ``path exists'' to ``path does
|
|
not exist'' is a status change like any other. The condition ``path does not
|
|
exist'' (or more correctly ``path cannot be stat'ed'') is signified by the
|
|
<TT>"st_nlink"</TT> 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.
|
|
<P>
|
|
|
|
The path <I>must not</I> end in a slash or contain special components such as
|
|
<TT>"."</TT> or <TT>".."</TT>. The path <I>should</I> be absolute: If it is relative and
|
|
your working directory changes, then the behaviour is undefined.
|
|
<P>
|
|
|
|
Since there is no portable change notification interface available, the
|
|
portable implementation simply calls <TT><A HREF="/cgi-bin/man/man2html?2+stat">stat</A>(2)</TT> 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 <TT>0</TT> (highly
|
|
recommended!) then a <I>suitable, unspecified default</I> 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 <TT>0.1</TT>, but that's usually overkill.
|
|
<P>
|
|
|
|
This watcher type is not meant for massive numbers of stat watchers,
|
|
as even with OS-supported change notifications, this can be
|
|
resource-intensive.
|
|
<P>
|
|
|
|
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 <TT>"ev_stat"</TT> semantics with kqueue, except as a hint).
|
|
<P>
|
|
|
|
<I></I><FONT SIZE="-1"><I>ABI</I></FONT><I> Issues (Largefile Support)</I>
|
|
|
|
|
|
<P>
|
|
|
|
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 <FONT SIZE="-1">ABI</FONT> 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 <FONT SIZE="-1">ABI,</FONT> but the problem is
|
|
most noticeably displayed with ev_stat and large file support.
|
|
<P>
|
|
|
|
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.
|
|
<P>
|
|
|
|
<I>Inotify and Kqueue</I>
|
|
|
|
|
|
<P>
|
|
|
|
When <TT>"inotify (7)"</TT> 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 <TT>"ev_stat"</TT>
|
|
watcher is being started.
|
|
<P>
|
|
|
|
Inotify presence does not change the semantics of <TT>"ev_stat"</TT> watchers
|
|
except that changes might be detected earlier, and in some cases, to avoid
|
|
making regular <TT>"stat"</TT> calls. Even in the presence of inotify support
|
|
there are many cases where libev has to resort to regular <TT>"stat"</TT> 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.
|
|
<P>
|
|
|
|
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.
|
|
<P>
|
|
|
|
<I></I>"stat ()"<I> is a synchronous operation</I>
|
|
|
|
|
|
<P>
|
|
|
|
Libev doesn't normally do any kind of I/O itself, and so is not blocking
|
|
the process. The exception are <TT>"ev_stat"</TT> watchers - those call <TT>"stat
|
|
()"</TT>, which is a synchronous operation.
|
|
<P>
|
|
|
|
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).
|
|
<P>
|
|
|
|
For networked file systems, calling <TT>"stat ()"</TT> can block an indefinite
|
|
time due to network issues, and even under good conditions, a stat call
|
|
often takes multiple milliseconds.
|
|
<P>
|
|
|
|
Therefore, it is best to avoid using <TT>"ev_stat"</TT> watchers on networked
|
|
paths, although this is fully supported by libev.
|
|
<P>
|
|
|
|
<I>The special problem of stat time resolution</I>
|
|
|
|
|
|
<P>
|
|
|
|
The <TT>"stat ()"</TT> 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.
|
|
<P>
|
|
|
|
That means that, if the time is the only thing that changes, you can
|
|
easily miss updates: on the first update, <TT>"ev_stat"</TT> detects a change and
|
|
calls your callback, which does something. When there is another update
|
|
within the same second, <TT>"ev_stat"</TT> will be unable to detect unless the
|
|
stat data does change in other ways (e.g. file size).
|
|
<P>
|
|
|
|
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 <TT>"ev_timer"</TT> (e.g. <TT>"ev_timer_set (w, 0., 1.02);
|
|
ev_timer_again (loop, w)"</TT>).
|
|
<P>
|
|
|
|
The <TT>.02</TT> 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
|
|
<TT>"gettimeofday"</TT> might return a timestamp with a full second later than
|
|
a subsequent <TT>"time"</TT> call - if the equivalent of <TT>"time ()"</TT> 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).
|
|
<P>
|
|
|
|
<I>Watcher-Specific Functions and Data Members</I>
|
|
|
|
|
|
<DL COMPACT>
|
|
<DT id="126">ev_stat_init (ev_stat *, callback, const char *path, ev_tstamp interval)<DD>
|
|
|
|
|
|
|
|
<DT id="127">ev_stat_set (ev_stat *, const char *path, ev_tstamp interval)<DD>
|
|
|
|
|
|
|
|
Configures the watcher to wait for status changes of the given
|
|
<TT>"path"</TT>. The <TT>"interval"</TT> is a hint on how quickly a change is expected to
|
|
be detected and should normally be specified as <TT>0</TT> to let libev choose
|
|
a suitable value. The memory pointed to by <TT>"path"</TT> must point to the same
|
|
path for as long as the watcher is active.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
The callback will receive an <TT>"EV_STAT"</TT> event when a change was detected,
|
|
relative to the attributes at the time the watcher was started (or the
|
|
last change was detected).
|
|
<DT id="128">ev_stat_stat (loop, ev_stat *)<DD>
|
|
|
|
|
|
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.
|
|
<DT id="129">ev_statdata attr [read-only]<DD>
|
|
|
|
|
|
The most-recently detected attributes of the file. Although the type is
|
|
<TT>"ev_statdata"</TT>, this is usually the (or one of the) <TT>"struct stat"</TT> types
|
|
suitable for your system, but you can only rely on the POSIX-standardised
|
|
members to be present. If the <TT>"st_nlink"</TT> member is <TT>0</TT>, then there was
|
|
some error while <TT>"stat"</TT>ing the file.
|
|
<DT id="130">ev_statdata prev [read-only]<DD>
|
|
|
|
|
|
The previous attributes of the file. The callback gets invoked whenever
|
|
<TT>"prev"</TT> != <TT>"attr"</TT>, or, more precisely, one or more of these members
|
|
differ: <TT>"st_dev"</TT>, <TT>"st_ino"</TT>, <TT>"st_mode"</TT>, <TT>"st_nlink"</TT>, <TT>"st_uid"</TT>,
|
|
<TT>"st_gid"</TT>, <TT>"st_rdev"</TT>, <TT>"st_size"</TT>, <TT>"st_atime"</TT>, <TT>"st_mtime"</TT>, <TT>"st_ctime"</TT>.
|
|
<DT id="131">ev_tstamp interval [read-only]<DD>
|
|
|
|
|
|
The specified interval.
|
|
<DT id="132">const char *path [read-only]<DD>
|
|
|
|
|
|
The file system path that is being watched.
|
|
</DL>
|
|
<P>
|
|
|
|
<I>Examples</I>
|
|
|
|
|
|
<P>
|
|
|
|
Example: Watch <TT>"/etc/passwd"</TT> for attribute changes.
|
|
<P>
|
|
|
|
|
|
|
|
<PRE>
|
|
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\n", (long)w->attr.st_size);
|
|
printf ("passwd current atime %ld\n", (long)w->attr.st_mtime);
|
|
printf ("passwd current mtime %ld\n", (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\n");
|
|
}
|
|
|
|
...
|
|
ev_stat passwd;
|
|
|
|
ev_stat_init (&passwd, passwd_cb, "/etc/passwd", 0.);
|
|
ev_stat_start (loop, &passwd);
|
|
|
|
</PRE>
|
|
|
|
|
|
<P>
|
|
|
|
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 <TT>"ev_stat"</TT> callback invocation <I>and</I> on
|
|
<TT>"ev_timer"</TT> callback invocation).
|
|
<P>
|
|
|
|
|
|
|
|
<PRE>
|
|
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's 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);
|
|
|
|
</PRE>
|
|
|
|
|
|
<A NAME="lbAY"> </A>
|
|
<H3>ev_idle - when you've got nothing better to do...</H3>
|
|
|
|
|
|
|
|
|
|
|
|
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 ``events'').
|
|
<P>
|
|
|
|
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.
|
|
<P>
|
|
|
|
The most noteworthy effect is that as long as any idle watchers are
|
|
active, the process will not block when waiting for new events.
|
|
<P>
|
|
|
|
Apart from keeping your process non-blocking (which is a useful
|
|
effect on its own sometimes), idle watchers are a good place to do
|
|
``pseudo-background processing'', or delay processing stuff to after the
|
|
event loop has handled all outstanding events.
|
|
<P>
|
|
|
|
<I>Abusing an </I>"ev_idle"<I> watcher for its side-effect</I>
|
|
|
|
|
|
<P>
|
|
|
|
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.
|
|
<P>
|
|
|
|
This mode of operation can be useful together with an <TT>"ev_check"</TT> watcher,
|
|
to do something on each event loop iteration - for example to balance load
|
|
between different connections.
|
|
<P>
|
|
|
|
See ``Abusing an ev_check watcher for its side-effect'' for a longer
|
|
example.
|
|
<P>
|
|
|
|
<I>Watcher-Specific Functions and Data Members</I>
|
|
|
|
|
|
<DL COMPACT>
|
|
<DT id="133">ev_idle_init (ev_idle *, callback)<DD>
|
|
|
|
|
|
Initialises and configures the idle watcher - it has no parameters of any
|
|
kind. There is a <TT>"ev_idle_set"</TT> macro, but using it is utterly pointless,
|
|
believe me.
|
|
</DL>
|
|
<P>
|
|
|
|
<I>Examples</I>
|
|
|
|
|
|
<P>
|
|
|
|
Example: Dynamically allocate an <TT>"ev_idle"</TT> watcher, start it, and in the
|
|
callback, free it. Also, use no error checking, as usual.
|
|
<P>
|
|
|
|
|
|
|
|
<PRE>
|
|
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);
|
|
|
|
</PRE>
|
|
|
|
|
|
<A NAME="lbAZ"> </A>
|
|
<H3>ev_prepare and ev_check - customise your event loop!</H3>
|
|
|
|
|
|
|
|
|
|
|
|
Prepare and check watchers are often (but not always) used in pairs:
|
|
prepare watchers get invoked before the process blocks and check watchers
|
|
afterwards.
|
|
<P>
|
|
|
|
You <I>must not</I> call <TT>"ev_run"</TT> (or similar functions that enter the
|
|
current event loop) or <TT>"ev_loop_fork"</TT> from either <TT>"ev_prepare"</TT> or
|
|
<TT>"ev_check"</TT> 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
|
|
<TT>"ev_prepare"</TT>, blocking, <TT>"ev_check"</TT> so if you have one watcher of each
|
|
kind they will always be called in pairs bracketing the blocking call.
|
|
<P>
|
|
|
|
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 <TT>"XFlush ()"</TT> in an <TT>"ev_prepare"</TT>
|
|
watcher).
|
|
<P>
|
|
|
|
This is done by examining in each prepare call which file descriptors
|
|
need to be watched by the other library, registering <TT>"ev_io"</TT> watchers
|
|
for them and starting an <TT>"ev_timer"</TT> 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?).
|
|
<P>
|
|
|
|
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).
|
|
<P>
|
|
|
|
When used for this purpose, it is recommended to give <TT>"ev_check"</TT> watchers
|
|
highest (<TT>"EV_MAXPRI"</TT>) priority, to ensure that they are being run before
|
|
any other watchers after the poll (this doesn't matter for <TT>"ev_prepare"</TT>
|
|
watchers).
|
|
<P>
|
|
|
|
Also, <TT>"ev_check"</TT> watchers (and <TT>"ev_prepare"</TT> watchers, too) should not
|
|
activate (``feed'') events into libev. While libev fully supports this, they
|
|
might get executed before other <TT>"ev_check"</TT> watchers did their job. As
|
|
<TT>"ev_check"</TT> watchers are often used to embed other (non-libev) event
|
|
loops those other event loops might be in an unusable state until their
|
|
<TT>"ev_check"</TT> watcher ran (always remind yourself to coexist peacefully with
|
|
others).
|
|
<P>
|
|
|
|
<I>Abusing an </I>"ev_check"<I> watcher for its side-effect</I>
|
|
|
|
|
|
<P>
|
|
|
|
<TT>"ev_check"</TT> (and less often also <TT>"ev_prepare"</TT>) 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.
|
|
<P>
|
|
|
|
Using an <TT>"ev_check"</TT> 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 <TT>"ev_check"</TT> watcher will not be invoked.
|
|
<P>
|
|
|
|
This is where <TT>"ev_idle"</TT> watchers come in handy - all you need is a
|
|
single global idle watcher that is active as long as you have one active
|
|
<TT>"ev_check"</TT> watcher. The <TT>"ev_idle"</TT> watcher makes sure the event loop
|
|
will not sleep, and the <TT>"ev_check"</TT> watcher makes sure a callback gets
|
|
invoked. Neither watcher alone can do that.
|
|
<P>
|
|
|
|
<I>Watcher-Specific Functions and Data Members</I>
|
|
|
|
|
|
<DL COMPACT>
|
|
<DT id="134">ev_prepare_init (ev_prepare *, callback)<DD>
|
|
|
|
|
|
|
|
<DT id="135">ev_check_init (ev_check *, callback)<DD>
|
|
|
|
|
|
|
|
Initialises and configures the prepare or check watcher - they have no
|
|
parameters of any kind. There are <TT>"ev_prepare_set"</TT> and <TT>"ev_check_set"</TT>
|
|
macros, but using them is utterly, utterly, utterly and completely
|
|
pointless.
|
|
</DL>
|
|
<P>
|
|
|
|
<I>Examples</I>
|
|
|
|
|
|
<P>
|
|
|
|
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 <TT>"EV::ADNS"</TT> that does this, which you could
|
|
use as a working example. Another Perl module named <TT>"EV::Glib"</TT> embeds a
|
|
Glib main context into libev, and finally, <TT>"Glib::EV"</TT> embeds <FONT SIZE="-1">EV</FONT> into the
|
|
Glib event loop).
|
|
<P>
|
|
|
|
Method 1: Add <FONT SIZE="-1">IO</FONT> 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 <TT>"ev_clear_pending"</TT> explicitly, as
|
|
the callbacks for the IO/timeout watchers might not have been called yet.
|
|
<P>
|
|
|
|
|
|
|
|
<PRE>
|
|
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't 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));
|
|
}
|
|
|
|
</PRE>
|
|
|
|
|
|
<P>
|
|
|
|
Method 2: This would be just like method 1, but you run <TT>"adns_afterpoll"</TT>
|
|
in the prepare watcher and would dispose of the check watcher.
|
|
<P>
|
|
|
|
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.
|
|
<P>
|
|
|
|
|
|
|
|
<PRE>
|
|
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
|
|
|
|
</PRE>
|
|
|
|
|
|
<P>
|
|
|
|
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 <FONT SIZE="-1">EV.</FONT> The <TT>"Glib::EV"</TT> module uses
|
|
this approach, effectively embedding <FONT SIZE="-1">EV</FONT> as a client into the horrible
|
|
libglib event loop.
|
|
<P>
|
|
|
|
|
|
|
|
<PRE>
|
|
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;
|
|
}
|
|
|
|
</PRE>
|
|
|
|
|
|
<A NAME="lbBA"> </A>
|
|
<H3>ev_embed - when one backend isn't enough...</H3>
|
|
|
|
|
|
|
|
|
|
|
|
This is a rather advanced watcher type that lets you embed one event loop
|
|
into another (currently only <TT>"ev_io"</TT> 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).
|
|
<P>
|
|
|
|
There are primarily two reasons you would want that: work around bugs and
|
|
prioritise I/O.
|
|
<P>
|
|
|
|
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 <TT>"poll"</TT> and then
|
|
<TT>"kevent"</TT>, but at least you can use both mechanisms for what they are
|
|
best: <TT>"kqueue"</TT> for scalable sockets and <TT>"poll"</TT> if you want it to work :)
|
|
<P>
|
|
|
|
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.
|
|
<P>
|
|
|
|
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 <TT>"ev_embed_sweep (mainloop, watcher)"</TT> to make a single
|
|
sweep and invoke their callbacks (the callback doesn't need to invoke the
|
|
<TT>"ev_embed_sweep"</TT> function directly, it could also start an idle watcher
|
|
to give the embedded loop strictly lower priority for example).
|
|
<P>
|
|
|
|
You can also set the callback to <TT>0</TT>, in which case the embed watcher
|
|
will automatically execute the embedded loop sweep whenever necessary.
|
|
<P>
|
|
|
|
Fork detection will be handled transparently while the <TT>"ev_embed"</TT> 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
|
|
<TT>"ev_loop_fork"</TT> on the embedded loop.
|
|
<P>
|
|
|
|
Unfortunately, not all backends are embeddable: only the ones returned by
|
|
<TT>"ev_embeddable_backends"</TT> are, which, unfortunately, does not include any
|
|
portable one.
|
|
<P>
|
|
|
|
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.
|
|
<P>
|
|
|
|
<I></I>"ev_embed"<I> and fork</I>
|
|
|
|
|
|
<P>
|
|
|
|
While the <TT>"ev_embed"</TT> 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 <TT>"ev_loop_fork ()"</TT>
|
|
as applicable.
|
|
<P>
|
|
|
|
<I>Watcher-Specific Functions and Data Members</I>
|
|
|
|
|
|
<DL COMPACT>
|
|
<DT id="136">ev_embed_init (ev_embed *, callback, struct ev_loop *embedded_loop)<DD>
|
|
|
|
|
|
|
|
<DT id="137">ev_embed_set (ev_embed *, struct ev_loop *embedded_loop)<DD>
|
|
|
|
|
|
|
|
Configures the watcher to embed the given loop, which must be
|
|
embeddable. If the callback is <TT>0</TT>, then <TT>"ev_embed_sweep"</TT> 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).
|
|
<DT id="138">ev_embed_sweep (loop, ev_embed *)<DD>
|
|
|
|
|
|
Make a single, non-blocking sweep over the embedded loop. This works
|
|
similarly to <TT>"ev_run (embedded_loop, EVRUN_NOWAIT)"</TT>, but in the most
|
|
appropriate way for embedded loops.
|
|
<DT id="139">struct ev_loop *other [read-only]<DD>
|
|
|
|
|
|
The embedded event loop.
|
|
</DL>
|
|
<P>
|
|
|
|
<I>Examples</I>
|
|
|
|
|
|
<P>
|
|
|
|
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 <TT>"loop_hi"</TT>, while the embeddable loop is stored in
|
|
<TT>"loop_lo"</TT> (which is <TT>"loop_hi"</TT> in the case no embeddable loop can be
|
|
used).
|
|
<P>
|
|
|
|
|
|
|
|
<PRE>
|
|
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;
|
|
|
|
</PRE>
|
|
|
|
|
|
<P>
|
|
|
|
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
|
|
<TT>"loop_socket"</TT>. (One might optionally use <TT>"EVFLAG_NOENV"</TT>, too).
|
|
<P>
|
|
|
|
|
|
|
|
<PRE>
|
|
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
|
|
|
|
</PRE>
|
|
|
|
|
|
<A NAME="lbBB"> </A>
|
|
<H3>ev_fork - the audacity to resume the event loop after a fork</H3>
|
|
|
|
|
|
|
|
|
|
|
|
Fork watchers are called when a <TT>"fork ()"</TT> was detected (usually because
|
|
whoever is a good citizen cared to tell libev about it by calling
|
|
<TT>"ev_loop_fork"</TT>). The invocation is done before the event loop blocks next
|
|
and before <TT>"ev_check"</TT> watchers are being called, and only in the child
|
|
after the fork. If whoever good citizen calling <TT>"ev_default_fork"</TT> cheats
|
|
and calls it in the wrong process, the fork handlers will be invoked, too,
|
|
of course.
|
|
<P>
|
|
|
|
<I>The special problem of life after fork - how is it possible?</I>
|
|
|
|
|
|
<P>
|
|
|
|
Most uses of <TT>"fork ()"</TT> consist of forking, then some simple calls to set
|
|
up/change the process environment, followed by a call to <TT>"exec()"</TT>. This
|
|
sequence should be handled by libev without any problems.
|
|
<P>
|
|
|
|
This changes when the application actually wants to do event handling
|
|
in the child, or both parent in child, in effect ``continuing'' after the
|
|
fork.
|
|
<P>
|
|
|
|
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 <I>either</I> the parent <I>or</I> the child process continues.
|
|
<P>
|
|
|
|
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.
|
|
<P>
|
|
|
|
The cleanest and most efficient way to achieve that with libev is to
|
|
simply create a new event loop, which of course will be ``empty'', 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).
|
|
<P>
|
|
|
|
When this is not possible, or you want to use the default loop for
|
|
other reasons, then in the process that wants to start ``fresh'', call
|
|
<TT>"ev_loop_destroy (EV_DEFAULT)"</TT> followed by <TT>"ev_default_loop (...)"</TT>.
|
|
Destroying the default loop will ``orphan'' (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.
|
|
<P>
|
|
|
|
<I>Watcher-Specific Functions and Data Members</I>
|
|
|
|
|
|
<DL COMPACT>
|
|
<DT id="140">ev_fork_init (ev_fork *, callback)<DD>
|
|
|
|
|
|
Initialises and configures the fork watcher - it has no parameters of any
|
|
kind. There is a <TT>"ev_fork_set"</TT> macro, but using it is utterly pointless,
|
|
really.
|
|
</DL>
|
|
<A NAME="lbBC"> </A>
|
|
<H3>ev_cleanup - even the best things end</H3>
|
|
|
|
|
|
|
|
|
|
|
|
Cleanup watchers are called just before the event loop is being destroyed
|
|
by a call to <TT>"ev_loop_destroy"</TT>.
|
|
<P>
|
|
|
|
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.
|
|
<P>
|
|
|
|
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 <TT>"ev_cleanup_start"</TT>.
|
|
<P>
|
|
|
|
<I>Watcher-Specific Functions and Data Members</I>
|
|
|
|
|
|
<DL COMPACT>
|
|
<DT id="141">ev_cleanup_init (ev_cleanup *, callback)<DD>
|
|
|
|
|
|
Initialises and configures the cleanup watcher - it has no parameters of
|
|
any kind. There is a <TT>"ev_cleanup_set"</TT> macro, but using it is utterly
|
|
pointless, I assure you.
|
|
</DL>
|
|
<P>
|
|
|
|
Example: Register an atexit handler to destroy the default loop, so any
|
|
cleanup functions are called.
|
|
<P>
|
|
|
|
|
|
|
|
<PRE>
|
|
static void
|
|
program_exits (void)
|
|
{
|
|
ev_loop_destroy (EV_DEFAULT_UC);
|
|
}
|
|
|
|
...
|
|
atexit (program_exits);
|
|
|
|
</PRE>
|
|
|
|
|
|
<A NAME="lbBD"> </A>
|
|
<H3>ev_async - how to wake up an event loop</H3>
|
|
|
|
|
|
|
|
|
|
|
|
In general, you cannot use an <TT>"ev_loop"</TT> 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).
|
|
<P>
|
|
|
|
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 <TT>"ev_async"</TT>
|
|
watchers do: as long as the <TT>"ev_async"</TT> watcher is active, you can signal
|
|
it by calling <TT>"ev_async_send"</TT>, which is thread- and signal safe.
|
|
<P>
|
|
|
|
This functionality is very similar to <TT>"ev_signal"</TT> 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
|
|
<TT>"ev_async_send"</TT> calls). In fact, you could use signal watchers as a kind
|
|
of ``global async watchers'' by using a watcher on an otherwise unused
|
|
signal, and <TT>"ev_feed_signal"</TT> to signal this watcher from another thread,
|
|
even without knowing which loop owns the signal.
|
|
<P>
|
|
|
|
<I>Queueing</I>
|
|
|
|
|
|
<P>
|
|
|
|
<TT>"ev_async"</TT> 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.
|
|
<P>
|
|
|
|
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:
|
|
<DL COMPACT>
|
|
<DT id="142">queueing from a signal handler context<DD>
|
|
|
|
|
|
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 <FONT SIZE="-1">SIGUSR1</FONT> handler:
|
|
|
|
|
|
<P>
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
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);
|
|
}
|
|
|
|
</PRE>
|
|
|
|
|
|
|
|
|
|
<P>
|
|
|
|
|
|
(Note: pthreads in theory requires you to use <TT>"pthread_setmask"</TT>
|
|
instead of <TT>"sigprocmask"</TT> when you use threads, but libev doesn't do it
|
|
either...).
|
|
<DT id="143">queueing from a thread context<DD>
|
|
|
|
|
|
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:
|
|
|
|
|
|
<P>
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
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);
|
|
}
|
|
|
|
</PRE>
|
|
|
|
|
|
</DL>
|
|
<P>
|
|
|
|
<I>Watcher-Specific Functions and Data Members</I>
|
|
|
|
|
|
<DL COMPACT>
|
|
<DT id="144">ev_async_init (ev_async *, callback)<DD>
|
|
|
|
|
|
Initialises and configures the async watcher - it has no parameters of any
|
|
kind. There is a <TT>"ev_async_set"</TT> macro, but using it is utterly pointless,
|
|
trust me.
|
|
<DT id="145">ev_async_send (loop, ev_async *)<DD>
|
|
|
|
|
|
Sends/signals/activates the given <TT>"ev_async"</TT> watcher, that is, feeds
|
|
an <TT>"EV_ASYNC"</TT> event on the watcher into the event loop, and instantly
|
|
returns.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Unlike <TT>"ev_feed_event"</TT>, this call is safe to do from other threads,
|
|
signal or similar contexts (see the discussion of <TT>"EV_ATOMIC_T"</TT> in the
|
|
embedding section below on what exactly this means).
|
|
|
|
|
|
<P>
|
|
|
|
|
|
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 <TT>"ev_async"</TT> watchers are level-triggered: they are set on
|
|
<TT>"ev_async_send"</TT>, reset when the event loop detects that).
|
|
|
|
|
|
<P>
|
|
|
|
|
|
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.
|
|
<DT id="146">bool = ev_async_pending (ev_async *)<DD>
|
|
|
|
|
|
Returns a non-zero value when <TT>"ev_async_send"</TT> has been called on the
|
|
watcher but the event has not yet been processed (or even noted) by the
|
|
event loop.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
<TT>"ev_async_send"</TT> 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. <TT>"ev_async_pending"</TT> can be used to very
|
|
quickly check whether invoking the loop might be a good idea.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Not that this does <I>not</I> 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.
|
|
</DL>
|
|
<A NAME="lbBE"> </A>
|
|
<H2>OTHER FUNCTIONS</H2>
|
|
|
|
|
|
|
|
There are some other functions of possible interest. Described. Here. Now.
|
|
<DL COMPACT>
|
|
<DT id="147">ev_once (loop, int fd, int events, ev_tstamp timeout, callback, arg)<DD>
|
|
|
|
|
|
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.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
If <TT>"fd"</TT> is less than 0, then no I/O watcher will be started and the
|
|
<TT>"events"</TT> argument is being ignored. Otherwise, an <TT>"ev_io"</TT> watcher for
|
|
the given <TT>"fd"</TT> and <TT>"events"</TT> set will be created and started.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
If <TT>"timeout"</TT> is less than 0, then no timeout watcher will be
|
|
started. Otherwise an <TT>"ev_timer"</TT> watcher with after = <TT>"timeout"</TT> (and
|
|
repeat = 0) will be started. <TT>0</TT> is a valid timeout.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
The callback has the type <TT>"void (*cb)(int revents, void *arg)"</TT> and is
|
|
passed an <TT>"revents"</TT> set like normal event callbacks (a combination of
|
|
<TT>"EV_ERROR"</TT>, <TT>"EV_READ"</TT>, <TT>"EV_WRITE"</TT> or <TT>"EV_TIMER"</TT>) and the <TT>"arg"</TT>
|
|
value passed to <TT>"ev_once"</TT>. Note that it is possible to receive <I>both</I>
|
|
a timeout and an io event at the same time - you probably should give io
|
|
events precedence.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Example: wait up to ten seconds for data to appear on <FONT SIZE="-1">STDIN_FILENO.</FONT>
|
|
|
|
|
|
<P>
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
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);
|
|
|
|
</PRE>
|
|
|
|
|
|
<DT id="148">ev_feed_fd_event (loop, int fd, int revents)<DD>
|
|
|
|
|
|
Feed an event on the given fd, as if a file descriptor backend detected
|
|
the given events.
|
|
<DT id="149">ev_feed_signal_event (loop, int signum)<DD>
|
|
|
|
|
|
Feed an event as if the given signal occurred. See also <TT>"ev_feed_signal"</TT>,
|
|
which is async-safe.
|
|
</DL>
|
|
<A NAME="lbBF"> </A>
|
|
<H2>COMMON OR USEFUL IDIOMS (OR BOTH)</H2>
|
|
|
|
|
|
|
|
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.
|
|
<A NAME="lbBG"> </A>
|
|
<H3><FONT SIZE="-1">ASSOCIATING CUSTOM DATA WITH A WATCHER</FONT></H3>
|
|
|
|
|
|
|
|
Each watcher has, by default, a <TT>"void *data"</TT> 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 ``subclass'' the watcher type and provide your own
|
|
data:
|
|
<P>
|
|
|
|
|
|
|
|
<PRE>
|
|
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);
|
|
|
|
</PRE>
|
|
|
|
|
|
<P>
|
|
|
|
And since your callback will be called with a pointer to the watcher, you
|
|
can cast it back to your own type:
|
|
<P>
|
|
|
|
|
|
|
|
<PRE>
|
|
static void my_cb (struct ev_loop *loop, ev_io *w_, int revents)
|
|
{
|
|
struct my_io *w = (struct my_io *)w_;
|
|
...
|
|
}
|
|
|
|
</PRE>
|
|
|
|
|
|
<P>
|
|
|
|
More interesting and less C-conformant ways of casting your callback
|
|
function type instead have been omitted.
|
|
<A NAME="lbBH"> </A>
|
|
<H3><FONT SIZE="-1">BUILDING YOUR OWN COMPOSITE WATCHERS</FONT></H3>
|
|
|
|
|
|
|
|
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 ``super-watcher'':
|
|
<P>
|
|
|
|
|
|
|
|
<PRE>
|
|
struct my_biggy
|
|
{
|
|
int some_data;
|
|
ev_timer t1;
|
|
ev_timer t2;
|
|
}
|
|
|
|
</PRE>
|
|
|
|
|
|
<P>
|
|
|
|
In this case getting the pointer to <TT>"my_biggy"</TT> is a bit more
|
|
complicated: Either you store the address of your <TT>"my_biggy"</TT> struct in
|
|
the <TT>"data"</TT> member of the watcher (for woozies or C<FONT SIZE="-2">++</FONT> coders), or you need
|
|
to use some pointer arithmetic using <TT>"offsetof"</TT> inside your watchers (for
|
|
real programmers):
|
|
<P>
|
|
|
|
|
|
|
|
<PRE>
|
|
#include <<A HREF="file:///usr/include/stddef.h">stddef.h</A>>
|
|
|
|
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));
|
|
}
|
|
|
|
</PRE>
|
|
|
|
|
|
<A NAME="lbBI"> </A>
|
|
<H3><FONT SIZE="-1">AVOIDING FINISHING BEFORE RETURNING</FONT></H3>
|
|
|
|
|
|
|
|
Often you have structures like this in event-based programs:
|
|
<P>
|
|
|
|
|
|
|
|
<PRE>
|
|
callback ()
|
|
{
|
|
free (request);
|
|
}
|
|
|
|
request = start_new_request (..., callback);
|
|
|
|
</PRE>
|
|
|
|
|
|
<P>
|
|
|
|
The intent is to start some ``lengthy'' operation. The <TT>"request"</TT> could be
|
|
used to cancel the operation, or do other things with it.
|
|
<P>
|
|
|
|
It's not uncommon to have code paths in <TT>"start_new_request"</TT> 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.
|
|
<P>
|
|
|
|
The problem here is that this will happen <I>before</I> <TT>"start_new_request"</TT>
|
|
has returned, so <TT>"request"</TT> is not set.
|
|
<P>
|
|
|
|
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.
|
|
<P>
|
|
|
|
A common way around all these issues is to make sure that
|
|
<TT>"start_new_request"</TT> <I>always</I> returns before the callback is invoked. If
|
|
<TT>"start_new_request"</TT> immediately knows the result, it can artificially
|
|
delay invoking the callback by using a <TT>"prepare"</TT> or <TT>"idle"</TT> watcher for
|
|
example, or more sneakily, by reusing an existing (stopped) watcher and
|
|
pushing it into the pending queue:
|
|
<P>
|
|
|
|
|
|
|
|
<PRE>
|
|
ev_set_cb (watcher, callback);
|
|
ev_feed_event (EV_A_ watcher, 0);
|
|
|
|
</PRE>
|
|
|
|
|
|
<P>
|
|
|
|
This way, <TT>"start_new_request"</TT> can safely return before the callback is
|
|
invoked, while not delaying callback invocation too much.
|
|
<A NAME="lbBJ"> </A>
|
|
<H3><FONT SIZE="-1">MODEL/NESTED EVENT LOOP INVOCATIONS AND EXIT CONDITIONS</FONT></H3>
|
|
|
|
|
|
|
|
Often (especially in <FONT SIZE="-1">GUI</FONT> toolkits) there are places where you have
|
|
<I>modal</I> interaction, which is most easily implemented by recursively
|
|
invoking <TT>"ev_run"</TT>.
|
|
<P>
|
|
|
|
This brings the problem of exiting - a callback might want to finish the
|
|
main <TT>"ev_run"</TT> call, but not the nested one (e.g. user clicked ``Quit'', but
|
|
a modal ``Are you sure?'' dialog is still waiting), or just the nested one
|
|
and not the main one (e.g. user clocked ``Ok'' in a modal dialog), or some
|
|
other combination: In these cases, a simple <TT>"ev_break"</TT> will not work.
|
|
<P>
|
|
|
|
The solution is to maintain ``break this loop'' variable for each <TT>"ev_run"</TT>
|
|
invocation, and use a loop around <TT>"ev_run"</TT> until the condition is
|
|
triggered, using <TT>"EVRUN_ONCE"</TT>:
|
|
<P>
|
|
|
|
|
|
|
|
<PRE>
|
|
// 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);
|
|
|
|
</PRE>
|
|
|
|
|
|
<P>
|
|
|
|
To exit from any of these loops, just set the corresponding exit variable:
|
|
<P>
|
|
|
|
|
|
|
|
<PRE>
|
|
// 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;
|
|
|
|
</PRE>
|
|
|
|
|
|
<A NAME="lbBK"> </A>
|
|
<H3><FONT SIZE="-1">THREAD LOCKING EXAMPLE</FONT></H3>
|
|
|
|
|
|
|
|
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.
|
|
<P>
|
|
|
|
For a real-world example, see the <TT>"EV::Loop::Async"</TT> perl module,
|
|
which uses exactly this technique (which is suited for many high-level
|
|
languages).
|
|
<P>
|
|
|
|
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.
|
|
<P>
|
|
|
|
First, you need to associate some data with the event loop:
|
|
<P>
|
|
|
|
|
|
|
|
<PRE>
|
|
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);
|
|
}
|
|
|
|
</PRE>
|
|
|
|
|
|
<P>
|
|
|
|
The callback for the <TT>"ev_async"</TT> 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:
|
|
<P>
|
|
|
|
|
|
|
|
<PRE>
|
|
static void
|
|
async_cb (EV_P_ ev_async *w, int revents)
|
|
{
|
|
// just used for the side effects
|
|
}
|
|
|
|
</PRE>
|
|
|
|
|
|
<P>
|
|
|
|
The <TT>"l_release"</TT> and <TT>"l_acquire"</TT> callbacks simply unlock/lock the mutex
|
|
protecting the loop data, respectively.
|
|
<P>
|
|
|
|
|
|
|
|
<PRE>
|
|
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);
|
|
}
|
|
|
|
</PRE>
|
|
|
|
|
|
<P>
|
|
|
|
The event loop thread first acquires the mutex, and then jumps straight
|
|
into <TT>"ev_run"</TT>:
|
|
<P>
|
|
|
|
|
|
|
|
<PRE>
|
|
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;
|
|
}
|
|
|
|
</PRE>
|
|
|
|
|
|
<P>
|
|
|
|
Instead of invoking all pending watchers, the <TT>"l_invoke"</TT> callback will
|
|
signal the main thread via some unspecified mechanism (signals? pipe
|
|
writes? <TT>"Async::Interrupt"</TT>?) 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):
|
|
<P>
|
|
|
|
|
|
|
|
<PRE>
|
|
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);
|
|
}
|
|
}
|
|
|
|
</PRE>
|
|
|
|
|
|
<P>
|
|
|
|
Now, whenever the main thread gets told to invoke pending watchers, it
|
|
will grab the lock, call <TT>"ev_invoke_pending"</TT> and then signal the loop
|
|
thread to continue:
|
|
<P>
|
|
|
|
|
|
|
|
<PRE>
|
|
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);
|
|
}
|
|
|
|
</PRE>
|
|
|
|
|
|
<P>
|
|
|
|
Whenever you want to start/stop a watcher or do other modifications to an
|
|
event loop, you will now have to lock:
|
|
<P>
|
|
|
|
|
|
|
|
<PRE>
|
|
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);
|
|
|
|
</PRE>
|
|
|
|
|
|
<P>
|
|
|
|
Note that sending the <TT>"ev_async"</TT> 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.
|
|
<A NAME="lbBL"> </A>
|
|
<H3><FONT SIZE="-1">THREADS, COROUTINES, CONTINUATIONS, QUEUES... INSTEAD OF CALLBACKS</FONT></H3>
|
|
|
|
|
|
|
|
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.
|
|
<P>
|
|
|
|
Imagine you have coroutines that you can switch to using a function
|
|
<TT>"switch_to (coro)"</TT>, that libev runs in a coroutine called <TT>"libev_coro"</TT>
|
|
and that due to some magic, the currently active coroutine is stored in a
|
|
global called <TT>"current_coro"</TT>. Then you can build your own ``wait for libev
|
|
event'' primitive by changing <TT>"EV_CB_DECLARE"</TT> and <TT>"EV_CB_INVOKE"</TT> (note
|
|
the differing <TT>";"</TT> conventions):
|
|
<P>
|
|
|
|
|
|
|
|
<PRE>
|
|
#define EV_CB_DECLARE(type) struct my_coro *cb;
|
|
#define EV_CB_INVOKE(watcher) switch_to ((watcher)->cb)
|
|
|
|
</PRE>
|
|
|
|
|
|
<P>
|
|
|
|
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.
|
|
<P>
|
|
|
|
A coroutine might now wait for an event with a function called
|
|
<TT>"wait_for_event"</TT>. (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):
|
|
<P>
|
|
|
|
|
|
|
|
<PRE>
|
|
void
|
|
wait_for_event (ev_watcher *w)
|
|
{
|
|
ev_set_cb (w, current_coro);
|
|
switch_to (libev_coro);
|
|
}
|
|
|
|
</PRE>
|
|
|
|
|
|
<P>
|
|
|
|
That basically suspends the coroutine inside <TT>"wait_for_event"</TT> and
|
|
continues the libev coroutine, which, when appropriate, switches back to
|
|
this or any other coroutine.
|
|
<P>
|
|
|
|
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.
|
|
<P>
|
|
|
|
To embed libev, see ``<FONT SIZE="-1">EMBEDDING''</FONT>, but in short, it's easiest to create two
|
|
files, <I>my_ev.h</I> and <I>my_ev.c</I> that include the respective libev files:
|
|
<P>
|
|
|
|
|
|
|
|
<PRE>
|
|
// 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"
|
|
|
|
</PRE>
|
|
|
|
|
|
<P>
|
|
|
|
And then use <I>my_ev.h</I> when you would normally use <I>ev.h</I>, and compile
|
|
<I>my_ev.c</I> into your project. When properly specifying include paths, you
|
|
can even use <I>ev.h</I> as header file name directly.
|
|
<A NAME="lbBM"> </A>
|
|
<H2>LIBEVENT EMULATION</H2>
|
|
|
|
|
|
|
|
Libev offers a compatibility emulation layer for libevent. It cannot
|
|
emulate the internals of libevent, so here are some usage hints:
|
|
<DL COMPACT>
|
|
<DT id="150">•<DD>
|
|
Only the libevent-1.4.1-beta <FONT SIZE="-1">API</FONT> is being emulated.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
This was the newest libevent version available when libev was implemented,
|
|
and is still mostly unchanged in 2010.
|
|
<DT id="151">•<DD>
|
|
Use it by including <<A HREF="file:///usr/include/event.h">event.h</A>>, as usual.
|
|
<DT id="152">•<DD>
|
|
The following members are fully supported: ev_base, ev_callback,
|
|
ev_arg, ev_fd, ev_res, ev_events.
|
|
<DT id="153">•<DD>
|
|
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 <FONT SIZE="-1">API</FONT>).
|
|
<DT id="154">•<DD>
|
|
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 id="155">•<DD>
|
|
In libevent, the last base created gets the signals, in libev, the
|
|
base that registered the signal gets the signals.
|
|
<DT id="156">•<DD>
|
|
Other members are not supported.
|
|
<DT id="157">•<DD>
|
|
The libev emulation is <I>not</I> <FONT SIZE="-1">ABI</FONT> compatible to libevent, you need
|
|
to use the libev header file and library.
|
|
</DL>
|
|
<A NAME="lbBN"> </A>
|
|
<H2>C<FONT SIZE="-2">++</FONT> SUPPORT</H2>
|
|
|
|
|
|
|
|
<A NAME="lbBO"> </A>
|
|
<H3>C <FONT SIZE="-1">API</FONT></H3>
|
|
|
|
|
|
|
|
The normal C <FONT SIZE="-1">API</FONT> should work fine when used from C<FONT SIZE="-2">++</FONT>: both ev.h and the
|
|
libev sources can be compiled as C<FONT SIZE="-2">++</FONT>. Therefore, code that uses the C <FONT SIZE="-1">API</FONT>
|
|
will work fine.
|
|
<P>
|
|
|
|
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 <TT>"noexcept"</TT>
|
|
specification. If you have code that needs to be compiled as both C and
|
|
C<FONT SIZE="-2">++</FONT> you can use the <TT>"EV_NOEXCEPT"</TT> macro for this:
|
|
<P>
|
|
|
|
|
|
|
|
<PRE>
|
|
static void
|
|
fatal_error (const char *msg) EV_NOEXCEPT
|
|
{
|
|
perror (msg);
|
|
abort ();
|
|
}
|
|
|
|
...
|
|
ev_set_syserr_cb (fatal_error);
|
|
|
|
</PRE>
|
|
|
|
|
|
<P>
|
|
|
|
The only <FONT SIZE="-1">API</FONT> functions that can currently throw exceptions are <TT>"ev_run"</TT>,
|
|
<TT>"ev_invoke"</TT>, <TT>"ev_invoke_pending"</TT> and <TT>"ev_loop_destroy"</TT> (the latter
|
|
because it runs cleanup watchers).
|
|
<P>
|
|
|
|
Throwing exceptions in watcher callbacks is only supported if libev itself
|
|
is compiled with a C<FONT SIZE="-2">++</FONT> compiler or your C and C<FONT SIZE="-2">++</FONT> environments allow
|
|
throwing exceptions through C libraries (most do).
|
|
<A NAME="lbBP"> </A>
|
|
<H3>C<FONT SIZE="-2">++</FONT> <FONT SIZE="-1">API</FONT></H3>
|
|
|
|
|
|
|
|
Libev comes with some simplistic wrapper classes for C<FONT SIZE="-2">++</FONT> 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.
|
|
<P>
|
|
|
|
To use it,
|
|
<P>
|
|
|
|
|
|
|
|
<PRE>
|
|
#include <<A HREF="file:///usr/include/ev++.h">ev++.h</A>>
|
|
|
|
</PRE>
|
|
|
|
|
|
<P>
|
|
|
|
This automatically includes <I>ev.h</I> and puts all of its definitions (many
|
|
of them macros) into the global namespace. All C<FONT SIZE="-2">++</FONT> specific things are
|
|
put into the <TT>"ev"</TT> namespace. It should support all the same embedding
|
|
options as <I>ev.h</I>, most notably <TT>"EV_MULTIPLICITY"</TT>.
|
|
<P>
|
|
|
|
Care has been taken to keep the overhead low. The only data member the C<FONT SIZE="-2">++</FONT>
|
|
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 <TT>"EV_MULTIPLICITY"</TT> when embedding libev).
|
|
<P>
|
|
|
|
Currently, functions, static and non-static member functions and classes
|
|
with <TT>"operator ()"</TT> 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).
|
|
<P>
|
|
|
|
For all this to work, your C<FONT SIZE="-2">++</FONT> 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<FONT SIZE="-2">++</FONT>.
|
|
<P>
|
|
|
|
Here is a list of things available in the <TT>"ev"</TT> namespace:
|
|
<DL COMPACT>
|
|
<DT id="158">"ev::READ", "ev::WRITE" etc.<DD>
|
|
|
|
|
|
|
|
|
|
These are just enum values with the same values as the <TT>"EV_READ"</TT> etc.
|
|
macros from <I>ev.h</I>.
|
|
<DT id="159">"ev::tstamp", "ev::now"<DD>
|
|
|
|
|
|
|
|
|
|
Aliases to the same types/functions as with the <TT>"ev_"</TT> prefix.
|
|
<DT id="160">"ev::io", "ev::timer", "ev::periodic", "ev::idle", "ev::sig" etc.<DD>
|
|
|
|
|
|
|
|
|
|
For each <TT>"ev_TYPE"</TT> watcher in <I>ev.h</I> there is a corresponding class of
|
|
the same name in the <TT>"ev"</TT> namespace, with the exception of <TT>"ev_signal"</TT>
|
|
which is called <TT>"ev::sig"</TT> to avoid clashes with the <TT>"signal"</TT> macro
|
|
defined by many implementations.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
All of those classes have these methods:
|
|
<DL COMPACT><DT id="161"><DD>
|
|
<DL COMPACT>
|
|
<DT id="162">ev::TYPE::TYPE ()<DD>
|
|
|
|
|
|
|
|
<DT id="163">ev::TYPE::TYPE (loop)<DD>
|
|
|
|
|
|
<DT id="164">ev::TYPE::~TYPE<DD>
|
|
|
|
|
|
|
|
The constructor (optionally) takes an event loop to associate the watcher
|
|
with. If it is omitted, it will use <TT>"EV_DEFAULT"</TT>.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
The constructor calls <TT>"ev_init"</TT> for you, which means you have to call the
|
|
<TT>"set"</TT> method before starting it.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
It will not set a callback, however: You have to call the templated <TT>"set"</TT>
|
|
method to set a callback before you can start the watcher.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
(The reason why you have to use a method is a limitation in C<FONT SIZE="-2">++</FONT> which does
|
|
not allow explicit template arguments for constructors).
|
|
|
|
|
|
<P>
|
|
|
|
|
|
The destructor automatically stops the watcher if it is active.
|
|
<DT id="165">w->set<class, &class::method> (object *)<DD>
|
|
|
|
|
|
This method sets the callback method to call. The method has to have a
|
|
signature of <TT>"void (*)(ev_TYPE &, int)"</TT>, it receives the watcher as
|
|
first argument and the <TT>"revents"</TT> as second. The object must be given as
|
|
parameter and is stored in the <TT>"data"</TT> member of the watcher.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
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 <TT>"set"</TT> 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.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Example: simple class declaration and watcher initialisation
|
|
|
|
|
|
<P>
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
struct myclass
|
|
{
|
|
void io_cb (ev::io &w, int revents) { }
|
|
}
|
|
|
|
myclass obj;
|
|
ev::io iow;
|
|
iow.set <myclass, &myclass::io_cb> (&obj);
|
|
|
|
</PRE>
|
|
|
|
|
|
<DT id="166">w->set (object *)<DD>
|
|
|
|
|
|
This is a variation of a method callback - leaving out the method to call
|
|
will default the method to <TT>"operator ()"</TT>, which makes it possible to use
|
|
functor objects without having to manually specify the <TT>"operator ()"</TT> all
|
|
the time. Incidentally, you can then also leave out the template argument
|
|
list.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
The <TT>"operator ()"</TT> method prototype must be <TT>"void operator ()(watcher &w,
|
|
int revents)"</TT>.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
See the method-<TT>"set"</TT> above for more details.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Example: use a functor object as callback.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
struct myfunctor
|
|
{
|
|
void operator() (ev::io &w, int revents)
|
|
{
|
|
...
|
|
}
|
|
}
|
|
|
|
myfunctor f;
|
|
|
|
ev::io w;
|
|
w.set (&f);
|
|
|
|
</PRE>
|
|
|
|
|
|
<DT id="167">w->set<function> (void *data = 0)<DD>
|
|
|
|
|
|
Also sets a callback, but uses a static method or plain function as
|
|
callback. The optional <TT>"data"</TT> argument will be stored in the watcher's
|
|
<TT>"data"</TT> member and is free for you to use.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
The prototype of the <TT>"function"</TT> must be <TT>"void (*)(ev::TYPE &w, int)"</TT>.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
See the method-<TT>"set"</TT> above for more details.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Example: Use a plain function as callback.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
static void io_cb (ev::io &w, int revents) { }
|
|
iow.set <io_cb> ();
|
|
|
|
</PRE>
|
|
|
|
|
|
<DT id="168">w->set (loop)<DD>
|
|
|
|
|
|
Associates a different <TT>"struct ev_loop"</TT> with this watcher. You can only
|
|
do this when the watcher is inactive (and not pending either).
|
|
<DT id="169">w->set ([arguments])<DD>
|
|
|
|
|
|
Basically the same as <TT>"ev_TYPE_set"</TT> (except for <TT>"ev::embed"</TT> 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.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
For <TT>"ev::embed"</TT> watchers this method is called <TT>"set_embed"</TT>, to avoid
|
|
clashing with the <TT>"set (loop)"</TT> method.
|
|
<DT id="170">w->start ()<DD>
|
|
|
|
|
|
Starts the watcher. Note that there is no <TT>"loop"</TT> argument, as the
|
|
constructor already stores the event loop.
|
|
<DT id="171">w->start ([arguments])<DD>
|
|
|
|
|
|
Instead of calling <TT>"set"</TT> and <TT>"start"</TT> methods separately, it is often
|
|
convenient to wrap them in one call. Uses the same type of arguments as
|
|
the configure <TT>"set"</TT> method of the watcher.
|
|
<DT id="172">w->stop ()<DD>
|
|
|
|
|
|
Stops the watcher if it is active. Again, no <TT>"loop"</TT> argument.
|
|
<DT id="173">w->again () ("ev::timer", "ev::periodic" only)<DD>
|
|
|
|
|
|
|
|
|
|
For <TT>"ev::timer"</TT> and <TT>"ev::periodic"</TT>, this invokes the corresponding
|
|
<TT>"ev_TYPE_again"</TT> function.
|
|
<DT id="174">w->sweep () ("ev::embed" only)<DD>
|
|
|
|
|
|
|
|
|
|
Invokes <TT>"ev_embed_sweep"</TT>.
|
|
<DT id="175">w->update () ("ev::stat" only)<DD>
|
|
|
|
|
|
|
|
|
|
Invokes <TT>"ev_stat_stat"</TT>.
|
|
</DL>
|
|
</DL>
|
|
|
|
<DL COMPACT><DT id="176"><DD>
|
|
</DL>
|
|
|
|
</DL>
|
|
<P>
|
|
|
|
Example: Define a class with two I/O and idle watchers, start the I/O
|
|
watchers in the constructor.
|
|
<P>
|
|
|
|
|
|
|
|
<PRE>
|
|
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 <myclass, &myclass::io_cb > (this);
|
|
io2 .set <myclass, &myclass::io2_cb > (this);
|
|
idle.set <myclass, &myclass::idle_cb> (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
|
|
}
|
|
};
|
|
|
|
</PRE>
|
|
|
|
|
|
<A NAME="lbBQ"> </A>
|
|
<H2>OTHER LANGUAGE BINDINGS</H2>
|
|
|
|
|
|
|
|
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.
|
|
<DL COMPACT>
|
|
<DT id="177">Perl<DD>
|
|
|
|
|
|
The <FONT SIZE="-1">EV</FONT> module implements the full libev <FONT SIZE="-1">API</FONT> and is actually used to test
|
|
libev. <FONT SIZE="-1">EV</FONT> is developed together with libev. Apart from the <FONT SIZE="-1">EV</FONT> core module,
|
|
there are additional modules that implement libev-compatible interfaces
|
|
to <TT>"libadns"</TT> (<TT>"EV::ADNS"</TT>, but <TT>"AnyEvent::DNS"</TT> is preferred nowadays),
|
|
<TT>"Net::SNMP"</TT> (<TT>"Net::SNMP::EV"</TT>) and the <TT>"libglib"</TT> event core (<TT>"Glib::EV"</TT>
|
|
and <TT>"EV::Glib"</TT>).
|
|
|
|
|
|
<P>
|
|
|
|
|
|
It can be found and installed via <FONT SIZE="-1">CPAN,</FONT> its homepage is at
|
|
<<A HREF="http://software.schmorp.de/pkg/EV">http://software.schmorp.de/pkg/EV</A>>.
|
|
<DT id="178">Python<DD>
|
|
|
|
|
|
Python bindings can be found at <<A HREF="http://code.google.com/p/pyev/">http://code.google.com/p/pyev/</A>>. It
|
|
seems to be quite complete and well-documented.
|
|
<DT id="179">Ruby<DD>
|
|
|
|
|
|
Tony Arcieri has written a ruby extension that offers access to a subset
|
|
of the libev <FONT SIZE="-1">API</FONT> and adds file handle abstractions, asynchronous <FONT SIZE="-1">DNS</FONT> and
|
|
more on top of it. It can be found via gem servers. Its homepage is at
|
|
<<A HREF="http://rev.rubyforge.org/">http://rev.rubyforge.org/</A>>.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Roger Pack reports that using the link order <TT>"-lws2_32 -lmsvcrt-ruby-190"</TT>
|
|
makes rev work even on mingw.
|
|
<DT id="180">Haskell<DD>
|
|
|
|
|
|
A haskell binding to libev is available at
|
|
<<A HREF="http://hackage.haskell.org/cgi-bin/hackage-scripts/package/hlibev">http://hackage.haskell.org/cgi-bin/hackage-scripts/package/hlibev</A>>.
|
|
<DT id="181">D<DD>
|
|
|
|
|
|
Leandro Lucarella has written a D language binding (<I>ev.d</I>) for libev, to
|
|
be found at <<A HREF="http://www.llucax.com.ar/proj/ev.d/index.html">http://www.llucax.com.ar/proj/ev.d/index.html</A>>.
|
|
<DT id="182">Ocaml<DD>
|
|
|
|
|
|
Erkki Seppala has written Ocaml bindings for libev, to be found at
|
|
<<A HREF="http://modeemi.cs.tut.fi/~flux/software/ocaml-ev/">http://modeemi.cs.tut.fi/~flux/software/ocaml-ev/</A>>.
|
|
<DT id="183">Lua<DD>
|
|
|
|
|
|
Brian Maher has written a partial interface to libev for lua (at the
|
|
time of this writing, only <TT>"ev_io"</TT> and <TT>"ev_timer"</TT>), to be found at
|
|
<<A HREF="http://github.com/brimworks/lua-ev">http://github.com/brimworks/lua-ev</A>>.
|
|
<DT id="184">Javascript<DD>
|
|
|
|
|
|
Node.js (<<A HREF="http://nodejs.org">http://nodejs.org</A>>) uses libev as the underlying event library.
|
|
<DT id="185">Others<DD>
|
|
|
|
|
|
There are others, and I stopped counting.
|
|
</DL>
|
|
<A NAME="lbBR"> </A>
|
|
<H2>MACRO MAGIC</H2>
|
|
|
|
|
|
|
|
Libev can be compiled with a variety of options, the most fundamental
|
|
of which is <TT>"EV_MULTIPLICITY"</TT>. This option determines whether (most)
|
|
functions and callbacks have an initial <TT>"struct ev_loop *"</TT> argument.
|
|
<P>
|
|
|
|
To make it easier to write programs that cope with either variant, the
|
|
following macros are defined:
|
|
<DL COMPACT>
|
|
<DT id="186">"EV_A", "EV_A_"<DD>
|
|
|
|
|
|
|
|
|
|
This provides the loop <I>argument</I> for functions, if one is required (``ev
|
|
loop argument''). The <TT>"EV_A"</TT> form is used when this is the sole argument,
|
|
<TT>"EV_A_"</TT> is used when other arguments are following. Example:
|
|
|
|
|
|
<P>
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
ev_unref (EV_A);
|
|
ev_timer_add (EV_A_ watcher);
|
|
ev_run (EV_A_ 0);
|
|
|
|
</PRE>
|
|
|
|
|
|
|
|
|
|
<P>
|
|
|
|
|
|
It assumes the variable <TT>"loop"</TT> of type <TT>"struct ev_loop *"</TT> is in scope,
|
|
which is often provided by the following macro.
|
|
<DT id="187">"EV_P", "EV_P_"<DD>
|
|
|
|
|
|
|
|
|
|
This provides the loop <I>parameter</I> for functions, if one is required (``ev
|
|
loop parameter''). The <TT>"EV_P"</TT> form is used when this is the sole parameter,
|
|
<TT>"EV_P_"</TT> 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 <TT>"loop"</TT> of type <TT>"struct ev_loop *"</TT>, quite
|
|
suitable for use with <TT>"EV_A"</TT>.
|
|
<DT id="188">"EV_DEFAULT", "EV_DEFAULT_"<DD>
|
|
|
|
|
|
|
|
|
|
Similar to the other two macros, this gives you the value of the default
|
|
loop, if multiple loops are supported (``ev loop default''). The default loop
|
|
will be initialised if it isn't already initialised.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
For non-multiplicity builds, these macros do nothing, so you always have
|
|
to initialise the loop somewhere.
|
|
<DT id="189">"EV_DEFAULT_UC", "EV_DEFAULT_UC_"<DD>
|
|
|
|
|
|
|
|
|
|
Usage identical to <TT>"EV_DEFAULT"</TT> and <TT>"EV_DEFAULT_"</TT>, but requires that the
|
|
default loop has been initialised (<TT>"UC"</TT> == unchecked). Their behaviour
|
|
is undefined when the default loop has not been initialised by a previous
|
|
execution of <TT>"EV_DEFAULT"</TT>, <TT>"EV_DEFAULT_"</TT> or <TT>"ev_default_init (...)"</TT>.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
It is often prudent to use <TT>"EV_DEFAULT"</TT> when initialising the first
|
|
watcher in a function but use <TT>"EV_DEFAULT_UC"</TT> afterwards.
|
|
</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_run (EV_DEFAULT_ 0);
|
|
|
|
</PRE>
|
|
|
|
|
|
<A NAME="lbBS"> </A>
|
|
<H2>EMBEDDING</H2>
|
|
|
|
|
|
|
|
Libev can (and often is) directly embedded into host
|
|
applications. Examples of applications that embed it include the Deliantra
|
|
Game Server, the <FONT SIZE="-1">EV</FONT> perl module, the <FONT SIZE="-1">GNU</FONT> Virtual Private Ethernet (gvpe)
|
|
and rxvt-unicode.
|
|
<P>
|
|
|
|
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).
|
|
<A NAME="lbBT"> </A>
|
|
<H3><FONT SIZE="-1">FILESETS</FONT></H3>
|
|
|
|
|
|
|
|
Depending on what features you need you need to include one or more sets of files
|
|
in your application.
|
|
<P>
|
|
|
|
<I></I><FONT SIZE="-1"><I>CORE EVENT LOOP</I></FONT><I></I>
|
|
|
|
|
|
<P>
|
|
|
|
To include only the libev core (all the <TT>"ev_*"</TT> functions), with manual
|
|
configuration (no autoconf):
|
|
<P>
|
|
|
|
|
|
|
|
<PRE>
|
|
#define EV_STANDALONE 1
|
|
#include "ev.c"
|
|
|
|
</PRE>
|
|
|
|
|
|
<P>
|
|
|
|
This will automatically include <I>ev.h</I>, too, and should be done in a
|
|
single C source file only to provide the function implementations. To use
|
|
it, do the same for <I>ev.h</I> in all files wishing to use this <FONT SIZE="-1">API</FONT> (best
|
|
done by writing a wrapper around <I>ev.h</I> 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<FONT SIZE="-2">++</FONT>
|
|
compiler (at least, that's a stated goal, and breakage will be treated
|
|
as a bug).
|
|
<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
|
|
ev_poll.c only when poll backend is enabled
|
|
ev_epoll.c only when the epoll backend is enabled
|
|
ev_linuxaio.c only when the linux aio backend is enabled
|
|
ev_iouring.c only when the linux io_uring backend is enabled
|
|
ev_kqueue.c only when the kqueue backend is enabled
|
|
ev_port.c only when the solaris port backend is enabled
|
|
|
|
</PRE>
|
|
|
|
|
|
<P>
|
|
|
|
<I>ev.c</I> includes the backend files directly when enabled, so you only need
|
|
to compile this single file.
|
|
<P>
|
|
|
|
<I></I><FONT SIZE="-1"><I>LIBEVENT COMPATIBILITY API</I></FONT><I></I>
|
|
|
|
|
|
<P>
|
|
|
|
To include the libevent compatibility <FONT SIZE="-1">API,</FONT> also include:
|
|
<P>
|
|
|
|
|
|
|
|
<PRE>
|
|
#include "event.c"
|
|
|
|
</PRE>
|
|
|
|
|
|
<P>
|
|
|
|
in the file including <I>ev.c</I>, and:
|
|
<P>
|
|
|
|
|
|
|
|
<PRE>
|
|
#include "event.h"
|
|
|
|
</PRE>
|
|
|
|
|
|
<P>
|
|
|
|
in the files that want to use the libevent <FONT SIZE="-1">API.</FONT> This also includes <I>ev.h</I>.
|
|
<P>
|
|
|
|
You need the following additional files for this:
|
|
<P>
|
|
|
|
|
|
|
|
<PRE>
|
|
event.h
|
|
event.c
|
|
|
|
</PRE>
|
|
|
|
|
|
<P>
|
|
|
|
<I></I><FONT SIZE="-1"><I>AUTOCONF SUPPORT</I></FONT><I></I>
|
|
|
|
|
|
<P>
|
|
|
|
Instead of using <TT>"EV_STANDALONE=1"</TT> and providing your configuration in
|
|
whatever way you want, you can also <TT>"m4_include([libev.m4])"</TT> in your
|
|
<I>configure.ac</I> and leave <TT>"EV_STANDALONE"</TT> undefined. <I>ev.c</I> will then
|
|
include <I>config.h</I> and configure itself accordingly.
|
|
<P>
|
|
|
|
For this of course you need the m4 file:
|
|
<P>
|
|
|
|
|
|
|
|
<PRE>
|
|
libev.m4
|
|
|
|
</PRE>
|
|
|
|
|
|
<A NAME="lbBU"> </A>
|
|
<H3><FONT SIZE="-1">PREPROCESSOR SYMBOLS/MACROS</FONT></H3>
|
|
|
|
|
|
|
|
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.
|
|
<P>
|
|
|
|
Symbols marked with ``(h)'' do not change the <FONT SIZE="-1">ABI,</FONT> and can have different
|
|
values when compiling libev vs. including <I>ev.h</I>, so it is permissible
|
|
to redefine them before including <I>ev.h</I> without breaking compatibility
|
|
to a compiled library. All other symbols change the <FONT SIZE="-1">ABI,</FONT> which means all
|
|
users of libev and the libev code itself must be compiled with compatible
|
|
settings.
|
|
<DL COMPACT>
|
|
<DT id="190"><FONT SIZE="-1">EV_COMPAT3</FONT> (h)<DD>
|
|
|
|
|
|
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.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
You can disable these wrappers (to test compatibility with future
|
|
versions) by defining <TT>"EV_COMPAT3"</TT> to <TT>0</TT> when compiling your
|
|
sources. This has the additional advantage that you can drop the <TT>"struct"</TT>
|
|
from <TT>"struct ev_loop"</TT> declarations, as libev will provide an <TT>"ev_loop"</TT>
|
|
typedef in that case.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
In some future version, the default for <TT>"EV_COMPAT3"</TT> will become <TT>0</TT>,
|
|
and in some even more future version the compatibility code will be
|
|
removed completely.
|
|
<DT id="191"><FONT SIZE="-1">EV_STANDALONE</FONT> (h)<DD>
|
|
|
|
|
|
Must always be <TT>1</TT> if you do not use autoconf configuration, which
|
|
keeps libev from including <I>config.h</I>, 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
|
|
<I>event.h</I> that are not directly supported by the libev core alone.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
In standalone mode, libev will still try to automatically deduce the
|
|
configuration, but has to be more conservative.
|
|
<DT id="192"><FONT SIZE="-1">EV_USE_FLOOR</FONT><DD>
|
|
|
|
|
|
If defined to be <TT>1</TT>, libev will use the <TT>"floor ()"</TT> 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 <TT>"floor"</TT>
|
|
function is not available will fail, so the safe default is to not enable
|
|
this.
|
|
<DT id="193"><FONT SIZE="-1">EV_USE_MONOTONIC</FONT><DD>
|
|
|
|
|
|
If defined to be <TT>1</TT>, 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 <TT>"clock_gettime"</TT>
|
|
function is hiding in (often <I>-lrt</I>). See also <TT>"EV_USE_CLOCK_SYSCALL"</TT>.
|
|
<DT id="194"><FONT SIZE="-1">EV_USE_REALTIME</FONT><DD>
|
|
|
|
|
|
If defined to be <TT>1</TT>, 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 <TT>"gettimeofday"</TT>
|
|
by <TT>"clock_get (CLOCK_REALTIME, ...)"</TT> and will not normally affect
|
|
correctness. See the note about libraries in the description of
|
|
<TT>"EV_USE_MONOTONIC"</TT>, though. Defaults to the opposite value of
|
|
<TT>"EV_USE_CLOCK_SYSCALL"</TT>.
|
|
<DT id="195"><FONT SIZE="-1">EV_USE_CLOCK_SYSCALL</FONT><DD>
|
|
|
|
|
|
If defined to be <TT>1</TT>, libev will try to use a direct syscall instead
|
|
of calling the system-provided <TT>"clock_gettime"</TT> function. This option
|
|
exists because on GNU/Linux, <TT>"clock_gettime"</TT> is in <TT>"librt"</TT>, but <TT>"librt"</TT>
|
|
unconditionally pulls in <TT>"libpthread"</TT>, 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 <TT>1</TT> on GNU/Linux with glibc 2.x or
|
|
higher, as it simplifies linking (no need for <TT>"-lrt"</TT>).
|
|
<DT id="196"><FONT SIZE="-1">EV_USE_NANOSLEEP</FONT><DD>
|
|
|
|
|
|
If defined to be <TT>1</TT>, libev will assume that <TT>"nanosleep ()"</TT> is available
|
|
and will use it for delays. Otherwise it will use <TT>"select ()"</TT>.
|
|
<DT id="197"><FONT SIZE="-1">EV_USE_EVENTFD</FONT><DD>
|
|
|
|
|
|
If defined to be <TT>1</TT>, then libev will assume that <TT>"eventfd ()"</TT> is
|
|
available and will probe for kernel support at runtime. This will improve
|
|
<TT>"ev_signal"</TT> and <TT>"ev_async"</TT> performance and reduce resource consumption.
|
|
If undefined, it will be enabled if the headers indicate GNU/Linux + Glibc
|
|
2.7 or newer, otherwise disabled.
|
|
<DT id="198"><FONT SIZE="-1">EV_USE_SIGNALFD</FONT><DD>
|
|
|
|
|
|
If defined to be <TT>1</TT>, then libev will assume that <TT>"signalfd ()"</TT> is
|
|
available and will probe for kernel support at runtime. This enables
|
|
the use of <FONT SIZE="-1">EVFLAG_SIGNALFD</FONT> for faster and simpler signal handling. If
|
|
undefined, it will be enabled if the headers indicate GNU/Linux + Glibc
|
|
2.7 or newer, otherwise disabled.
|
|
<DT id="199"><FONT SIZE="-1">EV_USE_TIMERFD</FONT><DD>
|
|
|
|
|
|
If defined to be <TT>1</TT>, then libev will assume that <TT>"timerfd ()"</TT> is
|
|
available and will probe for kernel support at runtime. This allows
|
|
libev to detect time jumps accurately. If undefined, it will be enabled
|
|
if the headers indicate GNU/Linux + Glibc 2.8 or newer and define
|
|
<TT>"TFD_TIMER_CANCEL_ON_SET"</TT>, otherwise disabled.
|
|
<DT id="200"><FONT SIZE="-1">EV_USE_EVENTFD</FONT><DD>
|
|
|
|
|
|
If defined to be <TT>1</TT>, then libev will assume that <TT>"eventfd ()"</TT> is
|
|
available and will probe for kernel support at runtime. This will improve
|
|
<TT>"ev_signal"</TT> and <TT>"ev_async"</TT> performance and reduce resource consumption.
|
|
If undefined, it will be enabled if the headers indicate GNU/Linux + Glibc
|
|
2.7 or newer, otherwise disabled.
|
|
<DT id="201"><FONT SIZE="-1">EV_USE_SELECT</FONT><DD>
|
|
|
|
|
|
If undefined or defined to be <TT>1</TT>, libev will compile in support for the
|
|
<TT>"select"</TT>(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.
|
|
<DT id="202"><FONT SIZE="-1">EV_SELECT_USE_FD_SET</FONT><DD>
|
|
|
|
|
|
If defined to <TT>1</TT>, then the select backend will use the system <TT>"fd_set"</TT>
|
|
structure. This is useful if libev doesn't compile due to a missing
|
|
<TT>"NFDBITS"</TT> or <TT>"fd_mask"</TT> 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 <TT>"FD_SETSIZE"</TT> macro, set before compilation,
|
|
configures the maximum size of the <TT>"fd_set"</TT>.
|
|
<DT id="203"><FONT SIZE="-1">EV_SELECT_IS_WINSOCKET</FONT><DD>
|
|
|
|
|
|
When defined to <TT>1</TT>, 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
|
|
<TT>"_get_osfhandle"</TT> on the fd to convert it to an <FONT SIZE="-1">OS</FONT> handle. Otherwise,
|
|
it is assumed that all these functions actually work on fds, even
|
|
on win32. Should not be defined on non-win32 platforms.
|
|
<DT id="204"><FONT SIZE="-1">EV_FD_TO_WIN32_HANDLE</FONT>(fd)<DD>
|
|
|
|
|
|
If <TT>"EV_SELECT_IS_WINSOCKET"</TT> 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 <TT>"_get_osfhandle"</TT>, 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.
|
|
<DT id="205"><FONT SIZE="-1">EV_WIN32_HANDLE_TO_FD</FONT>(handle)<DD>
|
|
|
|
|
|
If <TT>"EV_SELECT_IS_WINSOCKET"</TT> then libev maps handles to file descriptors
|
|
using the standard <TT>"_open_osfhandle"</TT> 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.
|
|
<DT id="206"><FONT SIZE="-1">EV_WIN32_CLOSE_FD</FONT>(fd)<DD>
|
|
|
|
|
|
If programs implement their own fd to handle mapping on win32, then this
|
|
macro can be used to override the <TT>"close"</TT> function, useful to unregister
|
|
file descriptors again. Note that the replacement function has to close
|
|
the underlying <FONT SIZE="-1">OS</FONT> handle.
|
|
<DT id="207"><FONT SIZE="-1">EV_USE_WSASOCKET</FONT><DD>
|
|
|
|
|
|
If defined to be <TT>1</TT>, libev will use <TT>"WSASocket"</TT> to create its internal
|
|
communication socket, which works better in some environments. Otherwise,
|
|
the normal <TT>"socket"</TT> function will be used, which works better in other
|
|
environments.
|
|
<DT id="208"><FONT SIZE="-1">EV_USE_POLL</FONT><DD>
|
|
|
|
|
|
If defined to be <TT>1</TT>, libev will compile in support for the <TT>"poll"</TT>(2)
|
|
backend. Otherwise it will be enabled on non-win32 platforms. It
|
|
takes precedence over select.
|
|
<DT id="209"><FONT SIZE="-1">EV_USE_EPOLL</FONT><DD>
|
|
|
|
|
|
If defined to be <TT>1</TT>, libev will compile in support for the Linux
|
|
<TT>"epoll"</TT>(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.
|
|
<DT id="210"><FONT SIZE="-1">EV_USE_LINUXAIO</FONT><DD>
|
|
|
|
|
|
If defined to be <TT>1</TT>, libev will compile in support for the Linux aio
|
|
backend (<TT>"EV_USE_EPOLL"</TT> must also be enabled). If undefined, it will be
|
|
enabled on linux, otherwise disabled.
|
|
<DT id="211"><FONT SIZE="-1">EV_USE_IOURING</FONT><DD>
|
|
|
|
|
|
If defined to be <TT>1</TT>, libev will compile in support for the Linux
|
|
io_uring backend (<TT>"EV_USE_EPOLL"</TT> must also be enabled). Due to it's
|
|
current limitations it has to be requested explicitly. If undefined, it
|
|
will be enabled on linux, otherwise disabled.
|
|
<DT id="212"><FONT SIZE="-1">EV_USE_KQUEUE</FONT><DD>
|
|
|
|
|
|
If defined to be <TT>1</TT>, libev will compile in support for the <FONT SIZE="-1">BSD</FONT> style
|
|
<TT>"kqueue"</TT>(2) backend. Its actual availability will be detected at runtime,
|
|
otherwise another method will be used as fallback. This is the preferred
|
|
backend for <FONT SIZE="-1">BSD</FONT> 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.
|
|
<DT id="213"><FONT SIZE="-1">EV_USE_PORT</FONT><DD>
|
|
|
|
|
|
If defined to be <TT>1</TT>, 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.
|
|
<DT id="214"><FONT SIZE="-1">EV_USE_DEVPOLL</FONT><DD>
|
|
|
|
|
|
Reserved for future expansion, works like the <FONT SIZE="-1">USE</FONT> symbols above.
|
|
<DT id="215"><FONT SIZE="-1">EV_USE_INOTIFY</FONT><DD>
|
|
|
|
|
|
If defined to be <TT>1</TT>, libev will compile in support for the Linux inotify
|
|
interface to speed up <TT>"ev_stat"</TT> 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.
|
|
<DT id="216"><FONT SIZE="-1">EV_NO_SMP</FONT><DD>
|
|
|
|
|
|
If defined to be <TT>1</TT>, 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.
|
|
<DT id="217"><FONT SIZE="-1">EV_NO_THREADS</FONT><DD>
|
|
|
|
|
|
If defined to be <TT>1</TT>, libev will assume that it will never be called from
|
|
different threads (that includes signal handlers), which is a stronger
|
|
assumption than <TT>"EV_NO_SMP"</TT>, above. This reduces dependencies and makes
|
|
libev faster.
|
|
<DT id="218"><FONT SIZE="-1">EV_ATOMIC_T</FONT><DD>
|
|
|
|
|
|
Libev requires an integer type (suitable for storing <TT>0</TT> or <TT>1</TT>) 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 ``locking'' as well as for signal and thread safety in <TT>"ev_async"</TT>
|
|
watchers.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
In the absence of this define, libev will use <TT>"sig_atomic_t volatile"</TT>
|
|
(from <I>signal.h</I>), which is usually good enough on most platforms.
|
|
<DT id="219"><FONT SIZE="-1">EV_H</FONT> (h)<DD>
|
|
|
|
|
|
The name of the <I>ev.h</I> header file used to include it. The default if
|
|
undefined is <TT>"ev.h"</TT> in <I>event.h</I>, <I>ev.c</I> and <I>ev++.h</I>. This can be
|
|
used to virtually rename the <I>ev.h</I> header file in case of conflicts.
|
|
<DT id="220"><FONT SIZE="-1">EV_CONFIG_H</FONT> (h)<DD>
|
|
|
|
|
|
If <TT>"EV_STANDALONE"</TT> isn't <TT>1</TT>, this variable can be used to override
|
|
<I>ev.c</I>'s idea of where to find the <I>config.h</I> file, similarly to
|
|
<TT>"EV_H"</TT>, above.
|
|
<DT id="221"><FONT SIZE="-1">EV_EVENT_H</FONT> (h)<DD>
|
|
|
|
|
|
Similarly to <TT>"EV_H"</TT>, this macro can be used to override <I>event.c</I>'s idea
|
|
of how the <I>event.h</I> header can be found, the default is <TT>"event.h"</TT>.
|
|
<DT id="222"><FONT SIZE="-1">EV_PROTOTYPES</FONT> (h)<DD>
|
|
|
|
|
|
If defined to be <TT>0</TT>, then <I>ev.h</I> 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.
|
|
<DT id="223"><FONT SIZE="-1">EV_MULTIPLICITY</FONT><DD>
|
|
|
|
|
|
If undefined or defined to <TT>1</TT>, then all event-loop-specific functions
|
|
will have the <TT>"struct ev_loop *"</TT> 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>
|
|
|
|
|
|
Note that <TT>"EV_DEFAULT"</TT> and <TT>"EV_DEFAULT_"</TT> will no longer provide a
|
|
default loop when multiplicity is switched off - you always have to
|
|
initialise the loop manually in this case.
|
|
<DT id="224"><FONT SIZE="-1">EV_MINPRI</FONT><DD>
|
|
|
|
|
|
|
|
<DT id="225"><FONT SIZE="-1">EV_MAXPRI</FONT><DD>
|
|
|
|
|
|
|
|
The range of allowed priorities. <TT>"EV_MINPRI"</TT> must be smaller or equal to
|
|
<TT>"EV_MAXPRI"</TT>, but otherwise there are no non-obvious limitations. You can
|
|
provide for more priorities by overriding those symbols (usually defined
|
|
to be <TT>"-2"</TT> and <TT>2</TT>, respectively).
|
|
|
|
|
|
<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>
|
|
|
|
|
|
If your embedding application does not need any priorities, defining these
|
|
both to <TT>0</TT> will save some memory and <FONT SIZE="-1">CPU.</FONT>
|
|
<DT id="226"><FONT SIZE="-1">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.</FONT><DD>
|
|
|
|
|
|
If undefined or defined to be <TT>1</TT> (and the platform supports it), then
|
|
the respective watcher type is supported. If defined to be <TT>0</TT>, then it
|
|
is not. Disabling watcher types mainly saves code size.
|
|
<DT id="227"><FONT SIZE="-1">EV_FEATURES</FONT><DD>
|
|
|
|
|
|
If you need to shave off some kilobytes of code at the expense of some
|
|
speed (but with the full <FONT SIZE="-1">API</FONT>), 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.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
A typical way to use this symbol is to define it to <TT>0</TT> (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:
|
|
|
|
|
|
<P>
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
#define EV_FEATURES 0
|
|
#define EV_MULTIPLICITY 1
|
|
#define EV_USE_POLL 1
|
|
#define EV_CHILD_ENABLE 1
|
|
#define EV_ASYNC_ENABLE 1
|
|
|
|
</PRE>
|
|
|
|
|
|
|
|
|
|
<P>
|
|
|
|
|
|
The actual value is a bitset, it can be a combination of the following
|
|
values (by default, all of these are enabled):
|
|
<DL COMPACT><DT id="228"><DD>
|
|
<DL COMPACT>
|
|
<DT id="229">1 - faster/larger code<DD>
|
|
|
|
|
|
|
|
|
|
Use larger code to speed up some operations.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Currently this is used to override some inlining decisions (enlarging the
|
|
code size by roughly 30% on amd64).
|
|
|
|
|
|
<P>
|
|
|
|
|
|
When optimising for size, use of compiler flags such as <TT>"-Os"</TT> with
|
|
gcc is recommended, as well as <TT>"-DNDEBUG"</TT>, as libev contains a number of
|
|
assertions.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
The default is off when <TT>"__OPTIMIZE_SIZE__"</TT> is defined by your compiler
|
|
(e.g. gcc with <TT>"-Os"</TT>).
|
|
<DT id="230">2 - faster/larger data structures<DD>
|
|
|
|
|
|
|
|
|
|
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.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
The default is off when <TT>"__OPTIMIZE_SIZE__"</TT> is defined by your compiler
|
|
(e.g. gcc with <TT>"-Os"</TT>).
|
|
<DT id="231">4 - full <FONT SIZE="-1">API</FONT> configuration<DD>
|
|
|
|
|
|
|
|
|
|
This enables priorities (sets <TT>"EV_MAXPRI"</TT>=2 and <TT>"EV_MINPRI"</TT>=-2), and
|
|
enables multiplicity (<TT>"EV_MULTIPLICITY"</TT>=1).
|
|
<DT id="232">8 - full <FONT SIZE="-1">API</FONT><DD>
|
|
|
|
|
|
|
|
|
|
This enables a lot of the ``lesser used'' <FONT SIZE="-1">API</FONT> functions. See <TT>"ev.h"</TT> for
|
|
details on which parts of the <FONT SIZE="-1">API</FONT> are still available without this
|
|
feature, and do not complain if this subset changes over time.
|
|
<DT id="233">16 - enable all optional watcher types<DD>
|
|
|
|
|
|
|
|
|
|
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
|
|
<TT>"EV_watchertype_ENABLE"</TT> to <TT>1</TT> instead.
|
|
<DT id="234">32 - enable all backends<DD>
|
|
|
|
|
|
|
|
|
|
This enables all backends - without this feature, you need to enable at
|
|
least one backend manually (<TT>"EV_USE_SELECT"</TT> is a good choice).
|
|
<DT id="235">64 - enable OS-specific "helper" APIs<DD>
|
|
|
|
|
|
|
|
|
|
Enable inotify, eventfd, signalfd and similar OS-specific helper APIs by
|
|
default.
|
|
</DL>
|
|
</DL>
|
|
|
|
<DL COMPACT><DT id="236"><DD>
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Compiling with <TT>"gcc -Os -DEV_STANDALONE -DEV_USE_EPOLL=1 -DEV_FEATURES=0"</TT>
|
|
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.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
With an intelligent-enough linker (gcc+binutils are intelligent enough
|
|
when you use <TT>"-Wl,--gc-sections -ffunction-sections"</TT>) 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.
|
|
</DL>
|
|
|
|
<DT id="237"><FONT SIZE="-1">EV_API_STATIC</FONT><DD>
|
|
|
|
|
|
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.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
To use this, define <TT>"EV_API_STATIC"</TT> and include <I>ev.c</I> in the file that
|
|
wants to use libev.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
This option only works when libev is compiled with a C compiler, as C<FONT SIZE="-2">++</FONT>
|
|
doesn't support the required declaration syntax.
|
|
<DT id="238"><FONT SIZE="-1">EV_AVOID_STDIO</FONT><DD>
|
|
|
|
|
|
If this is set to <TT>1</TT> 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.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Note that error messages might become less precise when this option is
|
|
enabled.
|
|
<DT id="239"><FONT SIZE="-1">EV_NSIG</FONT><DD>
|
|
|
|
|
|
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 (<TT>32</TT> should be
|
|
good for about any system in existence) can save some memory, as libev
|
|
statically allocates some 12-24 bytes per signal number.
|
|
<DT id="240"><FONT SIZE="-1">EV_PID_HASHSIZE</FONT><DD>
|
|
|
|
|
|
<TT>"ev_child"</TT> watchers use a small hash table to distribute workload by
|
|
pid. The default size is <TT>16</TT> (or <TT>1</TT> with <TT>"EV_FEATURES"</TT> disabled),
|
|
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).
|
|
<DT id="241"><FONT SIZE="-1">EV_INOTIFY_HASHSIZE</FONT><DD>
|
|
|
|
|
|
<TT>"ev_stat"</TT> watchers use a small hash table to distribute workload by
|
|
inotify watch id. The default size is <TT>16</TT> (or <TT>1</TT> with <TT>"EV_FEATURES"</TT>
|
|
disabled), usually more than enough. If you need to manage thousands of
|
|
<TT>"ev_stat"</TT> watchers you might want to increase this value (<I>must</I> be a
|
|
power of two).
|
|
<DT id="242"><FONT SIZE="-1">EV_USE_4HEAP</FONT><DD>
|
|
|
|
|
|
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 <TT>1</TT>. The 4-heap uses more complicated (longer) code but has noticeably
|
|
faster performance with many (thousands) of watchers.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
The default is <TT>1</TT>, unless <TT>"EV_FEATURES"</TT> overrides it, in which case it
|
|
will be <TT>0</TT>.
|
|
<DT id="243"><FONT SIZE="-1">EV_HEAP_CACHE_AT</FONT><DD>
|
|
|
|
|
|
Heaps are not very cache-efficient. To improve the cache-efficiency of the
|
|
timer and periodics heaps, libev can cache the timestamp (<I>at</I>) within
|
|
the heap structure (selected by defining <TT>"EV_HEAP_CACHE_AT"</TT> to <TT>1</TT>),
|
|
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.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
The default is <TT>1</TT>, unless <TT>"EV_FEATURES"</TT> overrides it, in which case it
|
|
will be <TT>0</TT>.
|
|
<DT id="244"><FONT SIZE="-1">EV_VERIFY</FONT><DD>
|
|
|
|
|
|
Controls how much internal verification (see <TT>"ev_verify ()"</TT>) will
|
|
be done: If set to <TT>0</TT>, no internal verification code will be compiled
|
|
in. If set to <TT>1</TT>, then verification code will be compiled in, but not
|
|
called. If set to <TT>2</TT>, then the internal verification code will be
|
|
called once per loop, which can slow down libev. If set to <TT>3</TT>, then the
|
|
verification code will be called very frequently, which will slow down
|
|
libev considerably.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Verification errors are reported via C's <TT>"assert"</TT> mechanism, so if you
|
|
disable that (e.g. by defining <TT>"NDEBUG"</TT>) then no errors will be reported.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
The default is <TT>1</TT>, unless <TT>"EV_FEATURES"</TT> overrides it, in which case it
|
|
will be <TT>0</TT>.
|
|
<DT id="245"><FONT SIZE="-1">EV_COMMON</FONT><DD>
|
|
|
|
|
|
By default, all watchers have a <TT>"void *data"</TT> 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.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
For example, the perl <FONT SIZE="-1">EV</FONT> module uses something like this:
|
|
|
|
|
|
<P>
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
#define EV_COMMON \
|
|
SV *self; /* contains this struct */ \
|
|
SV *cb_sv, *fh /* note no trailing ";" */
|
|
|
|
</PRE>
|
|
|
|
|
|
<DT id="246"><FONT SIZE="-1">EV_CB_DECLARE</FONT> (type)<DD>
|
|
|
|
|
|
|
|
<DT id="247"><FONT SIZE="-1">EV_CB_INVOKE</FONT> (watcher, revents)<DD>
|
|
|
|
|
|
<DT id="248">ev_set_cb (ev, cb)<DD>
|
|
|
|
|
|
|
|
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 <I>ev.h</I> header file for
|
|
their default definitions. One possible use for overriding these is to
|
|
avoid the <TT>"struct ev_loop *"</TT> as first argument in all cases, or to use
|
|
method calls instead of plain function calls in C<FONT SIZE="-2">++</FONT>.
|
|
</DL>
|
|
<A NAME="lbBV"> </A>
|
|
<H3><FONT SIZE="-1">EXPORTED API SYMBOLS</FONT></H3>
|
|
|
|
|
|
|
|
If you need to re-export the <FONT SIZE="-1">API</FONT> (e.g. via a <FONT SIZE="-1">DLL</FONT>) and you need a list of
|
|
exported symbols, you can use the provided <I>Symbol.*</I> files which list
|
|
all public symbols, one per line:
|
|
<P>
|
|
|
|
|
|
|
|
<PRE>
|
|
Symbols.ev for libev proper
|
|
Symbols.event for the libevent emulation
|
|
|
|
</PRE>
|
|
|
|
|
|
<P>
|
|
|
|
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).
|
|
<P>
|
|
|
|
A sed command like this will create wrapper <TT>"#define"</TT>'s that you need to
|
|
include before including <I>ev.h</I>:
|
|
<P>
|
|
|
|
|
|
|
|
<PRE>
|
|
<Symbols.ev sed -e "s/.*/#define & myprefix_&/" >wrap.h
|
|
|
|
</PRE>
|
|
|
|
|
|
<P>
|
|
|
|
This would create a file <I>wrap.h</I> which essentially looks like this:
|
|
<P>
|
|
|
|
|
|
|
|
<PRE>
|
|
#define ev_backend myprefix_ev_backend
|
|
#define ev_check_start myprefix_ev_check_start
|
|
#define ev_check_stop myprefix_ev_check_stop
|
|
...
|
|
|
|
</PRE>
|
|
|
|
|
|
<A NAME="lbBW"> </A>
|
|
<H3><FONT SIZE="-1">EXAMPLES</FONT></H3>
|
|
|
|
|
|
|
|
For a real-world example of a program the includes libev
|
|
verbatim, you can have a look at the <FONT SIZE="-1">EV</FONT> 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 <I>libev/</I> subdirectory and includes them in the <I></I><FONT SIZE="-1"><I>EV/EVAPI</I></FONT><I>.h</I> (public
|
|
interface) and <I></I><FONT SIZE="-1"><I>EV</I></FONT><I>.xs</I> (implementation) files. Only the <I></I><FONT SIZE="-1"><I>EV</I></FONT><I>.xs</I> file
|
|
will be compiled. It is pretty complex because it provides its own header
|
|
file.
|
|
<P>
|
|
|
|
The usage in rxvt-unicode is simpler. It has a <I>ev_cpp.h</I> header file
|
|
that everybody includes and which overrides some configure choices:
|
|
<P>
|
|
|
|
|
|
|
|
<PRE>
|
|
#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 <<A HREF="file:///usr/include/config.h">config.h</A>>
|
|
|
|
#include "ev++.h"
|
|
|
|
</PRE>
|
|
|
|
|
|
<P>
|
|
|
|
And a <I>ev_cpp.C</I> implementation file that contains libev proper and is compiled:
|
|
<P>
|
|
|
|
|
|
|
|
<PRE>
|
|
#include "ev_cpp.h"
|
|
#include "ev.c"
|
|
|
|
</PRE>
|
|
|
|
|
|
<A NAME="lbBX"> </A>
|
|
<H2>INTERACTION WITH OTHER PROGRAMS, LIBRARIES OR THE ENVIRONMENT</H2>
|
|
|
|
|
|
|
|
<A NAME="lbBY"> </A>
|
|
<H3><FONT SIZE="-1">THREADS AND COROUTINES</FONT></H3>
|
|
|
|
|
|
|
|
<I></I><FONT SIZE="-1"><I>THREADS</I></FONT><I></I>
|
|
|
|
|
|
<P>
|
|
|
|
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 (<TT>"ev_default_*"</TT> calls have an implicit default loop parameter,
|
|
of course): libev guarantees that different event loops share no data
|
|
structures that need any locking.
|
|
<P>
|
|
|
|
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).
|
|
<P>
|
|
|
|
Specifically to support threads (and signal handlers), libev implements
|
|
so-called <TT>"ev_async"</TT> watchers, which allow some limited form of
|
|
concurrency on the same event loop, namely waking it up ``from the
|
|
outside''.
|
|
<P>
|
|
|
|
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:
|
|
<DL COMPACT>
|
|
<DT id="249">•<DD>
|
|
most applications have a main thread: use the default libev loop
|
|
in that thread, or create a separate thread running only the default loop.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
This helps integrating other libraries or software modules that use libev
|
|
themselves and don't care/know about threading.
|
|
<DT id="250">•<DD>
|
|
one loop per thread is usually a good model.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Doing this is almost never wrong, sometimes a better-performance model
|
|
exists, but it is always a good start.
|
|
<DT id="251">•<DD>
|
|
other models exist, such as the leader/follower pattern, where one
|
|
loop is handed through multiple threads in a kind of round-robin fashion.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Choosing a model is hard - look around, learn, know that usually you can do
|
|
better than you currently do :-)
|
|
<DT id="252">•<DD>
|
|
often you need to talk to some other thread which blocks in the
|
|
event loop.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
<TT>"ev_async"</TT> watchers can be used to wake them up from other threads safely
|
|
(or from signal contexts...).
|
|
|
|
|
|
<P>
|
|
|
|
|
|
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 <TT>"ev_async"</TT> watcher from the default loop
|
|
watcher callback into the event loop interested in the signal.
|
|
</DL>
|
|
<P>
|
|
|
|
See also ``<FONT SIZE="-1">THREAD LOCKING EXAMPLE''</FONT>.
|
|
<P>
|
|
|
|
<I></I><FONT SIZE="-1"><I>COROUTINES</I></FONT><I></I>
|
|
|
|
|
|
<P>
|
|
|
|
Libev is very accommodating to coroutines (``cooperative threads''):
|
|
libev fully supports nesting calls to its functions from different
|
|
coroutines (e.g. you can call <TT>"ev_run"</TT> 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 <TT>"ev_periodic"</TT> reschedule callbacks.
|
|
<P>
|
|
|
|
Care has been taken to ensure that libev does not keep local state inside
|
|
<TT>"ev_run"</TT>, and other calls do not usually allow for coroutine switches as
|
|
they do not call any callbacks.
|
|
<A NAME="lbBZ"> </A>
|
|
<H3><FONT SIZE="-1">COMPILER WARNINGS</FONT></H3>
|
|
|
|
|
|
|
|
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.
|
|
<P>
|
|
|
|
However, these are unavoidable for many reasons. For one, each compiler
|
|
has different warnings, and each user has different tastes regarding
|
|
warning options. ``Warn-free'' code therefore cannot be a goal except when
|
|
targeting a specific compiler and compiler-version.
|
|
<P>
|
|
|
|
Another reason is that some compiler warnings require elaborate
|
|
workarounds, or other changes to the code that make it less clear and less
|
|
maintainable.
|
|
<P>
|
|
|
|
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.
|
|
<P>
|
|
|
|
While libev is written to generate as few warnings as possible,
|
|
``warn-free'' 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.
|
|
<A NAME="lbCA"> </A>
|
|
<H3><FONT SIZE="-1">VALGRIND</FONT></H3>
|
|
|
|
|
|
|
|
Valgrind has a special section here because it is a popular tool that is
|
|
highly useful. Unfortunately, valgrind reports are very hard to interpret.
|
|
<P>
|
|
|
|
If you think you found a bug (memory leak, uninitialised data access etc.)
|
|
in libev, then check twice: If valgrind reports something like:
|
|
<P>
|
|
|
|
|
|
|
|
<PRE>
|
|
==2274== definitely lost: 0 bytes in 0 blocks.
|
|
==2274== possibly lost: 0 bytes in 0 blocks.
|
|
==2274== still reachable: 256 bytes in 1 blocks.
|
|
|
|
</PRE>
|
|
|
|
|
|
<P>
|
|
|
|
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.
|
|
<P>
|
|
|
|
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.
|
|
<P>
|
|
|
|
Keep in mind that valgrind is a very good tool, but only a tool. Don't
|
|
make it into some kind of religion.
|
|
<P>
|
|
|
|
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 ``this is no bug'' answer and take the chance
|
|
of learning how to interpret valgrind properly.
|
|
<P>
|
|
|
|
If you need, for some reason, empty reports from valgrind for your project
|
|
I suggest using suppression lists.
|
|
<A NAME="lbCB"> </A>
|
|
<H2>PORTABILITY NOTES</H2>
|
|
|
|
|
|
|
|
<A NAME="lbCC"> </A>
|
|
<H3><FONT SIZE="-1">GNU/LINUX 32 BIT LIMITATIONS</FONT></H3>
|
|
|
|
|
|
|
|
GNU/Linux is the only common platform that supports 64 bit file/large file
|
|
interfaces but <I>disables</I> them by default.
|
|
<P>
|
|
|
|
That means that libev compiled in the default environment doesn't support
|
|
files larger than 2GiB or so, which mainly affects <TT>"ev_stat"</TT> watchers.
|
|
<P>
|
|
|
|
Unfortunately, many programs try to work around this GNU/Linux issue
|
|
by enabling the large file <FONT SIZE="-1">API,</FONT> which makes them incompatible with the
|
|
standard libev compiled for their system.
|
|
<P>
|
|
|
|
Likewise, libev cannot enable the large file <FONT SIZE="-1">API</FONT> itself as this would
|
|
suddenly make it incompatible to the default compile time environment,
|
|
i.e. all programs not using special compile switches.
|
|
<A NAME="lbCD"> </A>
|
|
<H3><FONT SIZE="-1">OS/X AND DARWIN BUGS</FONT></H3>
|
|
|
|
|
|
|
|
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.
|
|
<P>
|
|
|
|
<I></I>"kqueue"<I> is buggy</I>
|
|
|
|
|
|
<P>
|
|
|
|
The kqueue syscall is broken in all known versions - most versions support
|
|
only sockets, many support pipes.
|
|
<P>
|
|
|
|
Libev tries to work around this by not using <TT>"kqueue"</TT> 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.
|
|
<P>
|
|
|
|
<I></I>"poll"<I> is buggy</I>
|
|
|
|
|
|
<P>
|
|
|
|
Instead of fixing <TT>"kqueue"</TT>, Apple replaced their (working) <TT>"poll"</TT>
|
|
implementation by something calling <TT>"kqueue"</TT> internally around the 10.5.6
|
|
release, so now <TT>"kqueue"</TT> <I>and</I> <TT>"poll"</TT> are broken.
|
|
<P>
|
|
|
|
Libev tries to work around this by not using <TT>"poll"</TT> by default on
|
|
this rotten platform, but of course you can still ask for it when creating
|
|
a loop.
|
|
<P>
|
|
|
|
<I></I>"select"<I> is buggy</I>
|
|
|
|
|
|
<P>
|
|
|
|
All that's left is <TT>"select"</TT>, and of course Apple found a way to fuck this
|
|
one up as well: On <FONT SIZE="-1">OS/X,</FONT> <TT>"select"</TT> actively limits the number of file
|
|
descriptors you can pass in to 1024 - your program suddenly crashes when
|
|
you use more.
|
|
<P>
|
|
|
|
There is an undocumented ``workaround'' for this - defining
|
|
<TT>"_DARWIN_UNLIMITED_SELECT"</TT>, which libev tries to use, so select <I>should</I>
|
|
work on <FONT SIZE="-1">OS/X.</FONT>
|
|
<A NAME="lbCE"> </A>
|
|
<H3><FONT SIZE="-1">SOLARIS PROBLEMS AND WORKAROUNDS</FONT></H3>
|
|
|
|
|
|
|
|
<I></I>"errno"<I> reentrancy</I>
|
|
|
|
|
|
<P>
|
|
|
|
The default compile environment on Solaris is unfortunately so
|
|
thread-unsafe that you can't even use components/libraries compiled
|
|
without <TT>"-D_REENTRANT"</TT> in a threaded program, which, of course, isn't
|
|
defined by default. A valid, if stupid, implementation choice.
|
|
<P>
|
|
|
|
If you want to use libev in threaded environments you have to make sure
|
|
it's compiled with <TT>"_REENTRANT"</TT> defined.
|
|
<P>
|
|
|
|
<I>Event port backend</I>
|
|
|
|
|
|
<P>
|
|
|
|
The scalable event interface for Solaris is called ``event
|
|
ports''. Unfortunately, this mechanism is very buggy in all major
|
|
releases. If you run into high <FONT SIZE="-1">CPU</FONT> 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.
|
|
<P>
|
|
|
|
If you can't get it to work, you can try running the program by setting
|
|
the environment variable <TT>"LIBEV_FLAGS=3"</TT> to only allow <TT>"poll"</TT> and
|
|
<TT>"select"</TT> backends.
|
|
<A NAME="lbCF"> </A>
|
|
<H3><FONT SIZE="-1">AIX POLL BUG</FONT></H3>
|
|
|
|
|
|
|
|
<FONT SIZE="-1">AIX</FONT> unfortunately has a broken <TT>"poll.h"</TT> 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 <TT>"select"</TT> works fine
|
|
with large bitsets on <FONT SIZE="-1">AIX,</FONT> and <FONT SIZE="-1">AIX</FONT> is dead anyway.
|
|
<A NAME="lbCG"> </A>
|
|
<H3><FONT SIZE="-1">WIN32 PLATFORM LIMITATIONS AND WORKAROUNDS</FONT></H3>
|
|
|
|
|
|
|
|
<I>General issues</I>
|
|
|
|
|
|
<P>
|
|
|
|
Win32 doesn't support any of the standards (e.g. <FONT SIZE="-1">POSIX</FONT>) that libev
|
|
requires, and its I/O model is fundamentally incompatible with the <FONT SIZE="-1">POSIX</FONT>
|
|
model. Libev still offers limited functionality on this platform in
|
|
the form of the <TT>"EVBACKEND_SELECT"</TT> 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.
|
|
<P>
|
|
|
|
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).
|
|
<P>
|
|
|
|
There is no supported compilation method available on windows except
|
|
embedding it into other applications.
|
|
<P>
|
|
|
|
Sensible signal handling is officially unsupported by Microsoft - libev
|
|
tries its best, but under most conditions, signals will simply not work.
|
|
<P>
|
|
|
|
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 <TT>"ENOBUFS"</TT> 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).
|
|
<P>
|
|
|
|
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 <FONT SIZE="-1">POSIX</FONT> readiness
|
|
notification model, which cannot be implemented efficiently on windows
|
|
(due to Microsoft monopoly games).
|
|
<P>
|
|
|
|
A typical way to use libev under windows is to embed it (see the embedding
|
|
section for details) and use the following <I>evwrap.h</I> header file instead
|
|
of <I>ev.h</I>:
|
|
<P>
|
|
|
|
|
|
|
|
<PRE>
|
|
#define EV_STANDALONE /* keeps ev from requiring config.h */
|
|
#define EV_SELECT_IS_WINSOCKET 1 /* configure libev for windows select */
|
|
|
|
#include "ev.h"
|
|
|
|
</PRE>
|
|
|
|
|
|
<P>
|
|
|
|
And compile the following <I>evwrap.c</I> file into your project (make sure
|
|
you do <I>not</I> compile the <I>ev.c</I> or any other embedded source files!):
|
|
<P>
|
|
|
|
|
|
|
|
<PRE>
|
|
#include "evwrap.h"
|
|
#include "ev.c"
|
|
|
|
</PRE>
|
|
|
|
|
|
<P>
|
|
|
|
<I>The winsocket </I>"select"<I> function</I>
|
|
|
|
|
|
<P>
|
|
|
|
The winsocket <TT>"select"</TT> function doesn't follow <FONT SIZE="-1">POSIX</FONT> in that it
|
|
requires socket <I>handles</I> and not socket <I>file descriptors</I> (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 <TT>"_open_osfhandle"</TT> for this). See the
|
|
discussion of the <TT>"EV_SELECT_USE_FD_SET"</TT>, <TT>"EV_SELECT_IS_WINSOCKET"</TT> and
|
|
<TT>"EV_FD_TO_WIN32_HANDLE"</TT> preprocessor symbols for more info.
|
|
<P>
|
|
|
|
The configuration for a ``naked'' win32 using the Microsoft runtime
|
|
libraries and raw winsocket select is:
|
|
<P>
|
|
|
|
|
|
|
|
<PRE>
|
|
#define EV_USE_SELECT 1
|
|
#define EV_SELECT_IS_WINSOCKET 1 /* forces EV_SELECT_USE_FD_SET, too */
|
|
|
|
</PRE>
|
|
|
|
|
|
<P>
|
|
|
|
Note that winsockets handling of fd sets is <A HREF="/cgi-bin/man/man2html?n+O">O</A>(n), so you can easily get a
|
|
complexity in the O(nX) range when using win32.
|
|
<P>
|
|
|
|
<I>Limited number of file descriptors</I>
|
|
|
|
|
|
<P>
|
|
|
|
Windows has numerous arbitrary (and low) limits on things.
|
|
<P>
|
|
|
|
Early versions of winsocket's select only supported waiting for a maximum
|
|
of <TT>64</TT> handles (probably owning to the fact that all windows kernels
|
|
can only wait for <TT>64</TT> 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!).
|
|
<P>
|
|
|
|
Newer versions support more handles, but you need to define <TT>"FD_SETSIZE"</TT>
|
|
to some high number (e.g. <TT>2048</TT>) 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).
|
|
<P>
|
|
|
|
Another limit is the number of file descriptors in the Microsoft runtime
|
|
libraries, which by default is <TT>64</TT> (there must be a hidden <I>64</I>
|
|
fetish or something like this inside Microsoft). You can increase this
|
|
by calling <TT>"_setmaxstdio"</TT>, which can increase this limit to <TT>2048</TT>
|
|
(another arbitrary limit), but is broken in many versions of the Microsoft
|
|
runtime libraries. This might get you to about <TT>512</TT> or <TT>2048</TT> 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.
|
|
<A NAME="lbCH"> </A>
|
|
<H3><FONT SIZE="-1">PORTABILITY REQUIREMENTS</FONT></H3>
|
|
|
|
|
|
|
|
In addition to a working ISO-C implementation and of course the
|
|
backend-specific APIs, libev relies on a few additional extensions:
|
|
<DL COMPACT>
|
|
<DT id="253">"void (*)(ev_watcher_type *, int revents)" must have compatible calling conventions regardless of "ev_watcher_type *".<DD>
|
|
|
|
|
|
|
|
|
|
Libev assumes not only that all watcher pointers have the same internal
|
|
structure (guaranteed by <FONT SIZE="-1">POSIX</FONT> but not by <FONT SIZE="-1">ISO C</FONT> 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 <TT>"ev_watcher *"</TT> internally.
|
|
<DT id="254">null pointers and integer zero are represented by 0 bytes<DD>
|
|
|
|
|
|
Libev uses <TT>"memset"</TT> to initialise structs and arrays to <TT>0</TT> bytes, and
|
|
relies on this setting pointers and integers to null.
|
|
<DT id="255">pointer accesses must be thread-atomic<DD>
|
|
|
|
|
|
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.
|
|
<DT id="256">"sig_atomic_t volatile" must be thread-atomic as well<DD>
|
|
|
|
|
|
|
|
|
|
The type <TT>"sig_atomic_t volatile"</TT> (or whatever is defined as
|
|
<TT>"EV_ATOMIC_T"</TT>) must be atomic with respect to accesses from different
|
|
threads. This is not part of the specification for <TT>"sig_atomic_t"</TT>, but is
|
|
believed to be sufficiently portable.
|
|
<DT id="257">"sigprocmask" must work in a threaded environment<DD>
|
|
|
|
|
|
|
|
|
|
Libev uses <TT>"sigprocmask"</TT> to temporarily block signals. This is not
|
|
allowed in a threaded program (<TT>"pthread_sigmask"</TT> has to be used). Typical
|
|
pthread implementations will either allow <TT>"sigprocmask"</TT> in the ``main
|
|
thread'' or will block signals process-wide, both behaviours would
|
|
be compatible with libev. Interaction between <TT>"sigprocmask"</TT> and
|
|
<TT>"pthread_sigmask"</TT> could complicate things, however.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
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.
|
|
<DT id="258">"long" must be large enough for common memory allocation sizes<DD>
|
|
|
|
|
|
|
|
|
|
To improve portability and simplify its <FONT SIZE="-1">API,</FONT> libev uses <TT>"long"</TT> internally
|
|
instead of <TT>"size_t"</TT> 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.
|
|
<DT id="259">"double" must hold a time value in seconds with enough accuracy<DD>
|
|
|
|
|
|
|
|
|
|
The type <TT>"double"</TT> 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 <FONT SIZE="-1">IEEE 754,</FONT> which is basically all existing ones.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
With <FONT SIZE="-1">IEEE 754</FONT> 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 <TT>"long double"</TT> or
|
|
something like that, just kidding).
|
|
</DL>
|
|
<P>
|
|
|
|
If you know of other additional requirements drop me a note.
|
|
<A NAME="lbCI"> </A>
|
|
<H2>ALGORITHMIC COMPLEXITIES</H2>
|
|
|
|
|
|
|
|
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 <TT>"ev_default_init"</TT>.
|
|
<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 rarer with higher number of elements, so <A HREF="/cgi-bin/man/man2html?1+O">O</A>(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.
|
|
<DL COMPACT>
|
|
<DT id="260">Starting and stopping timer/periodic watchers: O(log skipped_other_timers)<DD>
|
|
|
|
|
|
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 (<TT>"ld 100"</TT>) of these watchers.
|
|
<DT id="261">Changing timer/periodic watchers (by autorepeat or calling again): O(log skipped_other_timers)<DD>
|
|
|
|
|
|
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.
|
|
<DT id="262">Starting io/check/prepare/idle/signal/child/fork/async watchers: <A HREF="/cgi-bin/man/man2html?1+O">O</A>(1)<DD>
|
|
|
|
|
|
These just add the watcher into an array or at the head of a list.
|
|
<DT id="263">Stopping check/prepare/idle/fork/async watchers: <A HREF="/cgi-bin/man/man2html?1+O">O</A>(1)<DD>
|
|
|
|
|
|
|
|
<DT id="264">Stopping an io/signal/child watcher: O(number_of_watchers_for_this_(fd/signal/pid % <FONT SIZE="-1">EV_PID_HASHSIZE</FONT>))<DD>
|
|
|
|
|
|
|
|
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).
|
|
<DT id="265">Finding the next timer in each loop iteration: <A HREF="/cgi-bin/man/man2html?1+O">O</A>(1)<DD>
|
|
|
|
|
|
By virtue of using a binary or 4-heap, the next timer is always found at a
|
|
fixed position in the storage array.
|
|
<DT id="266">Each change on a file descriptor per loop iteration: O(number_of_watchers_for_this_fd)<DD>
|
|
|
|
|
|
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 <TT>"ev_io_set"</TT> was used).
|
|
<DT id="267">Activating one watcher (putting it into the pending state): <A HREF="/cgi-bin/man/man2html?1+O">O</A>(1)<DD>
|
|
|
|
|
|
|
|
<DT id="268">Priority handling: O(number_of_priorities)<DD>
|
|
|
|
|
|
|
|
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 <A HREF="/cgi-bin/man/man2html?1+O">O</A>(1) with respect to priority handling.
|
|
<DT id="269">Sending an ev_async: <A HREF="/cgi-bin/man/man2html?1+O">O</A>(1)<DD>
|
|
|
|
|
|
|
|
<DT id="270">Processing ev_async_send: O(number_of_async_watchers)<DD>
|
|
|
|
|
|
<DT id="271">Processing signals: O(max_signal_number)<DD>
|
|
|
|
|
|
|
|
Sending involves a system call <I>iff</I> there were no other <TT>"ev_async_send"</TT>
|
|
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.
|
|
</DL>
|
|
<A NAME="lbCJ"> </A>
|
|
<H2>PORTING FROM LIBEV 3.X TO 4.X</H2>
|
|
|
|
|
|
|
|
The major version 4 introduced some incompatible changes to the <FONT SIZE="-1">API.</FONT>
|
|
<P>
|
|
|
|
At the moment, the <TT>"ev.h"</TT> 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 <FONT SIZE="-1">API</FONT> early than late.
|
|
<DL COMPACT>
|
|
<DT id="272">"EV_COMPAT3" backwards compatibility mechanism<DD>
|
|
|
|
|
|
|
|
|
|
The backward compatibility mechanism can be controlled by
|
|
<TT>"EV_COMPAT3"</TT>. See ``<FONT SIZE="-1">PREPROCESSOR SYMBOLS/MACROS''</FONT> in the ``<FONT SIZE="-1">EMBEDDING''</FONT>
|
|
section.
|
|
<DT id="273">"ev_default_destroy" and "ev_default_fork" have been removed<DD>
|
|
|
|
|
|
|
|
|
|
These calls can be replaced easily by their <TT>"ev_loop_xxx"</TT> counterparts:
|
|
|
|
|
|
<P>
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
ev_loop_destroy (EV_DEFAULT_UC);
|
|
ev_loop_fork (EV_DEFAULT);
|
|
|
|
</PRE>
|
|
|
|
|
|
<DT id="274">function/symbol renames<DD>
|
|
|
|
|
|
A number of functions and symbols have been renamed:
|
|
|
|
|
|
<P>
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
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
|
|
|
|
</PRE>
|
|
|
|
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Most functions working on <TT>"struct ev_loop"</TT> objects don't have an
|
|
<TT>"ev_loop_"</TT> prefix, so it was removed; <TT>"ev_loop"</TT>, <TT>"ev_unloop"</TT> and
|
|
associated constants have been renamed to not collide with the <TT>"struct
|
|
ev_loop"</TT> anymore and <TT>"EV_TIMER"</TT> now follows the same naming scheme
|
|
as all other watcher types. Note that <TT>"ev_loop_fork"</TT> is still called
|
|
<TT>"ev_loop_fork"</TT> because it would otherwise clash with the <TT>"ev_fork"</TT>
|
|
typedef.
|
|
<DT id="275">"EV_MINIMAL" mechanism replaced by "EV_FEATURES"<DD>
|
|
|
|
|
|
|
|
|
|
The preprocessor symbol <TT>"EV_MINIMAL"</TT> has been replaced by a different
|
|
mechanism, <TT>"EV_FEATURES"</TT>. Programs using <TT>"EV_MINIMAL"</TT> usually compile
|
|
and work, but the library code will of course be larger.
|
|
</DL>
|
|
<A NAME="lbCK"> </A>
|
|
<H2>GLOSSARY</H2>
|
|
|
|
|
|
|
|
<DL COMPACT>
|
|
<DT id="276">active<DD>
|
|
|
|
|
|
A watcher is active as long as it has been started and not yet stopped.
|
|
See ``<FONT SIZE="-1">WATCHER STATES''</FONT> for details.
|
|
<DT id="277">application<DD>
|
|
|
|
|
|
In this document, an application is whatever is using libev.
|
|
<DT id="278">backend<DD>
|
|
|
|
|
|
The part of the code dealing with the operating system interfaces.
|
|
<DT id="279">callback<DD>
|
|
|
|
|
|
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.
|
|
<DT id="280">callback/watcher invocation<DD>
|
|
|
|
|
|
The act of calling the callback associated with a watcher.
|
|
<DT id="281">event<DD>
|
|
|
|
|
|
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.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
In libev, events are represented as single bits (such as <TT>"EV_READ"</TT> or
|
|
<TT>"EV_TIMER"</TT>).
|
|
<DT id="282">event library<DD>
|
|
|
|
|
|
A software package implementing an event model and loop.
|
|
<DT id="283">event loop<DD>
|
|
|
|
|
|
An entity that handles and processes external events and converts them
|
|
into callback invocations.
|
|
<DT id="284">event model<DD>
|
|
|
|
|
|
The model used to describe how an event loop handles and processes
|
|
watchers and events.
|
|
<DT id="285">pending<DD>
|
|
|
|
|
|
A watcher is pending as soon as the corresponding event has been
|
|
detected. See ``<FONT SIZE="-1">WATCHER STATES''</FONT> for details.
|
|
<DT id="286">real time<DD>
|
|
|
|
|
|
The physical time that is observed. It is apparently strictly monotonic :)
|
|
<DT id="287">wall-clock time<DD>
|
|
|
|
|
|
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.
|
|
<DT id="288">watcher<DD>
|
|
|
|
|
|
A data structure that describes interest in certain events. Watchers need
|
|
to be started (attached to an event loop) before they can receive events.
|
|
</DL>
|
|
<A NAME="lbCL"> </A>
|
|
<H2>AUTHOR</H2>
|
|
|
|
|
|
|
|
Marc Lehmann <<A HREF="mailto:libev@schmorp.de">libev@schmorp.de</A>>, with repeated corrections by Mikael
|
|
Magnusson and Emanuele Giaquinta, and minor corrections by many others.
|
|
<P>
|
|
|
|
<HR>
|
|
<A NAME="index"> </A><H2>Index</H2>
|
|
<DL>
|
|
<DT id="289"><A HREF="#lbAB">NAME</A><DD>
|
|
<DT id="290"><A HREF="#lbAC">SYNOPSIS</A><DD>
|
|
<DL>
|
|
<DT id="291"><A HREF="#lbAD"><FONT SIZE="-1">EXAMPLE PROGRAM</FONT></A><DD>
|
|
</DL>
|
|
<DT id="292"><A HREF="#lbAE">ABOUT THIS DOCUMENT</A><DD>
|
|
<DT id="293"><A HREF="#lbAF">WHAT TO READ WHEN IN A HURRY</A><DD>
|
|
<DT id="294"><A HREF="#lbAG">ABOUT LIBEV</A><DD>
|
|
<DL>
|
|
<DT id="295"><A HREF="#lbAH"><FONT SIZE="-1">FEATURES</FONT></A><DD>
|
|
<DT id="296"><A HREF="#lbAI"><FONT SIZE="-1">CONVENTIONS</FONT></A><DD>
|
|
<DT id="297"><A HREF="#lbAJ"><FONT SIZE="-1">TIME REPRESENTATION</FONT></A><DD>
|
|
</DL>
|
|
<DT id="298"><A HREF="#lbAK">ERROR HANDLING</A><DD>
|
|
<DT id="299"><A HREF="#lbAL">GLOBAL FUNCTIONS</A><DD>
|
|
<DT id="300"><A HREF="#lbAM">FUNCTIONS CONTROLLING EVENT LOOPS</A><DD>
|
|
<DT id="301"><A HREF="#lbAN">ANATOMY OF A WATCHER</A><DD>
|
|
<DL>
|
|
<DT id="302"><A HREF="#lbAO"><FONT SIZE="-1">GENERIC WATCHER FUNCTIONS</FONT></A><DD>
|
|
<DT id="303"><A HREF="#lbAP"><FONT SIZE="-1">WATCHER STATES</FONT></A><DD>
|
|
<DT id="304"><A HREF="#lbAQ"><FONT SIZE="-1">WATCHER PRIORITY MODELS</FONT></A><DD>
|
|
</DL>
|
|
<DT id="305"><A HREF="#lbAR">WATCHER TYPES</A><DD>
|
|
<DL>
|
|
<DT id="306"><A HREF="#lbAS">ev_io - is this file descriptor readable or writable?</A><DD>
|
|
<DT id="307"><A HREF="#lbAT">ev_timer - relative and optionally repeating timeouts</A><DD>
|
|
<DT id="308"><A HREF="#lbAU">ev_periodic - to cron or not to cron?</A><DD>
|
|
<DT id="309"><A HREF="#lbAV">ev_signal - signal me when a signal gets signalled!</A><DD>
|
|
<DT id="310"><A HREF="#lbAW">ev_child - watch out for process status changes</A><DD>
|
|
<DT id="311"><A HREF="#lbAX">ev_stat - did the file attributes just change?</A><DD>
|
|
<DT id="312"><A HREF="#lbAY">ev_idle - when you've got nothing better to do...</A><DD>
|
|
<DT id="313"><A HREF="#lbAZ">ev_prepare and ev_check - customise your event loop!</A><DD>
|
|
<DT id="314"><A HREF="#lbBA">ev_embed - when one backend isn't enough...</A><DD>
|
|
<DT id="315"><A HREF="#lbBB">ev_fork - the audacity to resume the event loop after a fork</A><DD>
|
|
<DT id="316"><A HREF="#lbBC">ev_cleanup - even the best things end</A><DD>
|
|
<DT id="317"><A HREF="#lbBD">ev_async - how to wake up an event loop</A><DD>
|
|
</DL>
|
|
<DT id="318"><A HREF="#lbBE">OTHER FUNCTIONS</A><DD>
|
|
<DT id="319"><A HREF="#lbBF">COMMON OR USEFUL IDIOMS (OR BOTH)</A><DD>
|
|
<DL>
|
|
<DT id="320"><A HREF="#lbBG"><FONT SIZE="-1">ASSOCIATING CUSTOM DATA WITH A WATCHER</FONT></A><DD>
|
|
<DT id="321"><A HREF="#lbBH"><FONT SIZE="-1">BUILDING YOUR OWN COMPOSITE WATCHERS</FONT></A><DD>
|
|
<DT id="322"><A HREF="#lbBI"><FONT SIZE="-1">AVOIDING FINISHING BEFORE RETURNING</FONT></A><DD>
|
|
<DT id="323"><A HREF="#lbBJ"><FONT SIZE="-1">MODEL/NESTED EVENT LOOP INVOCATIONS AND EXIT CONDITIONS</FONT></A><DD>
|
|
<DT id="324"><A HREF="#lbBK"><FONT SIZE="-1">THREAD LOCKING EXAMPLE</FONT></A><DD>
|
|
<DT id="325"><A HREF="#lbBL"><FONT SIZE="-1">THREADS, COROUTINES, CONTINUATIONS, QUEUES... INSTEAD OF CALLBACKS</FONT></A><DD>
|
|
</DL>
|
|
<DT id="326"><A HREF="#lbBM">LIBEVENT EMULATION</A><DD>
|
|
<DT id="327"><A HREF="#lbBN">C<FONT SIZE="-2">++</FONT> SUPPORT</A><DD>
|
|
<DL>
|
|
<DT id="328"><A HREF="#lbBO">C <FONT SIZE="-1">API</FONT></A><DD>
|
|
<DT id="329"><A HREF="#lbBP">C<FONT SIZE="-2">++</FONT> <FONT SIZE="-1">API</FONT></A><DD>
|
|
</DL>
|
|
<DT id="330"><A HREF="#lbBQ">OTHER LANGUAGE BINDINGS</A><DD>
|
|
<DT id="331"><A HREF="#lbBR">MACRO MAGIC</A><DD>
|
|
<DT id="332"><A HREF="#lbBS">EMBEDDING</A><DD>
|
|
<DL>
|
|
<DT id="333"><A HREF="#lbBT"><FONT SIZE="-1">FILESETS</FONT></A><DD>
|
|
<DT id="334"><A HREF="#lbBU"><FONT SIZE="-1">PREPROCESSOR SYMBOLS/MACROS</FONT></A><DD>
|
|
<DT id="335"><A HREF="#lbBV"><FONT SIZE="-1">EXPORTED API SYMBOLS</FONT></A><DD>
|
|
<DT id="336"><A HREF="#lbBW"><FONT SIZE="-1">EXAMPLES</FONT></A><DD>
|
|
</DL>
|
|
<DT id="337"><A HREF="#lbBX">INTERACTION WITH OTHER PROGRAMS, LIBRARIES OR THE ENVIRONMENT</A><DD>
|
|
<DL>
|
|
<DT id="338"><A HREF="#lbBY"><FONT SIZE="-1">THREADS AND COROUTINES</FONT></A><DD>
|
|
<DT id="339"><A HREF="#lbBZ"><FONT SIZE="-1">COMPILER WARNINGS</FONT></A><DD>
|
|
<DT id="340"><A HREF="#lbCA"><FONT SIZE="-1">VALGRIND</FONT></A><DD>
|
|
</DL>
|
|
<DT id="341"><A HREF="#lbCB">PORTABILITY NOTES</A><DD>
|
|
<DL>
|
|
<DT id="342"><A HREF="#lbCC"><FONT SIZE="-1">GNU/LINUX 32 BIT LIMITATIONS</FONT></A><DD>
|
|
<DT id="343"><A HREF="#lbCD"><FONT SIZE="-1">OS/X AND DARWIN BUGS</FONT></A><DD>
|
|
<DT id="344"><A HREF="#lbCE"><FONT SIZE="-1">SOLARIS PROBLEMS AND WORKAROUNDS</FONT></A><DD>
|
|
<DT id="345"><A HREF="#lbCF"><FONT SIZE="-1">AIX POLL BUG</FONT></A><DD>
|
|
<DT id="346"><A HREF="#lbCG"><FONT SIZE="-1">WIN32 PLATFORM LIMITATIONS AND WORKAROUNDS</FONT></A><DD>
|
|
<DT id="347"><A HREF="#lbCH"><FONT SIZE="-1">PORTABILITY REQUIREMENTS</FONT></A><DD>
|
|
</DL>
|
|
<DT id="348"><A HREF="#lbCI">ALGORITHMIC COMPLEXITIES</A><DD>
|
|
<DT id="349"><A HREF="#lbCJ">PORTING FROM LIBEV 3.X TO 4.X</A><DD>
|
|
<DT id="350"><A HREF="#lbCK">GLOSSARY</A><DD>
|
|
<DT id="351"><A HREF="#lbCL">AUTHOR</A><DD>
|
|
</DL>
|
|
<HR>
|
|
This document was created by
|
|
<A HREF="/cgi-bin/man/man2html">man2html</A>,
|
|
using the manual pages.<BR>
|
|
Time: 00:05:39 GMT, March 31, 2021
|
|
</BODY>
|
|
</HTML>
|