EV
view release on metacpan or search on metacpan
libev/ev.pod view on Meta::CPAN
This document documents the libev software package.
The newest version of this document is also available as an html-formatted
web page you might find easier to navigate when reading it for the first
time: L<http://pod.tst.eu/http://cvs.schmorp.de/libev/ev.pod>.
While this document tries to be as complete as possible in documenting
libev, its usage and the rationale behind its design, it is not a tutorial
on event-based programming, nor will it introduce event-based programming
with libev.
Familiarity with event based programming techniques in general is assumed
throughout this document.
=head1 WHAT TO READ WHEN IN A HURRY
This manual tries to be very detailed, but unfortunately, this also makes
it very long. If you just want to know the basics of libev, I suggest
reading L</ANATOMY OF A WATCHER>, then the L</EXAMPLE PROGRAM> above and
look up the missing functions in L</GLOBAL FUNCTIONS> and the C<ev_io> and
C<ev_timer> sections in L</WATCHER TYPES>.
=head1 ABOUT LIBEV
Libev is an event loop: you register interest in certain events (such as a
file descriptor being readable or a timeout occurring), and it will manage
these event sources and provide your program with events.
To do this, it must take more or less complete control over your process
(or thread) by executing the I<event loop> handler, and will then
communicate events via a callback mechanism.
You register interest in certain events by registering so-called I<event
watchers>, which are relatively small C structures you initialise with the
details of the event, and then hand it over to libev by I<starting> the
watcher.
=head2 FEATURES
Libev supports C<select>, C<poll>, the Linux-specific aio and C<epoll>
interfaces, the BSD-specific C<kqueue> and the Solaris-specific event port
mechanisms for file descriptor events (C<ev_io>), the Linux C<inotify>
interface (for C<ev_stat>), Linux eventfd/signalfd (for faster and cleaner
inter-thread wakeup (C<ev_async>)/signal handling (C<ev_signal>)) relative
timers (C<ev_timer>), absolute timers with customised rescheduling
(C<ev_periodic>), synchronous signals (C<ev_signal>), process status
change events (C<ev_child>), and event watchers dealing with the event
loop mechanism itself (C<ev_idle>, C<ev_embed>, C<ev_prepare> and
C<ev_check> watchers) as well as file watchers (C<ev_stat>) and even
limited support for fork events (C<ev_fork>).
It also is quite fast (see this
L<benchmark|http://libev.schmorp.de/bench.html> comparing it to libevent
for example).
=head2 CONVENTIONS
Libev is very configurable. In this manual the default (and most common)
configuration will be described, which supports multiple event loops. For
more info about various configuration options please have a look at
B<EMBED> section in this manual. If libev was configured without support
for multiple event loops, then all functions taking an initial argument of
name C<loop> (which is always of type C<struct ev_loop *>) will not have
this argument.
=head2 TIME REPRESENTATION
Libev represents time as a single floating point number, representing
the (fractional) number of seconds since the (POSIX) epoch (in practice
somewhere near the beginning of 1970, details are complicated, don't
ask). This type is called C<ev_tstamp>, which is what you should use
too. It usually aliases to the C<double> type in C. When you need to do
any calculations on it, you should treat it as some floating point value.
Unlike the name component C<stamp> might indicate, it is also used for
time differences (e.g. delays) throughout libev.
=head1 ERROR HANDLING
Libev knows three classes of errors: operating system errors, usage errors
and internal errors (bugs).
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 C<ev_set_syserr_cb>, which is supposed to fix the problem or
abort. The default is to print a diagnostic message and to call C<abort
()>.
When libev detects a usage error such as a negative timer interval, then
it will print a diagnostic message and abort (via the C<assert> mechanism,
so C<NDEBUG> will disable this checking): these are programming errors in
the libev caller and need to be fixed there.
Via the C<EV_FREQUENT> 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.
Libev also has a few internal error-checking C<assert>ions. These do not
trigger under normal circumstances, as they indicate either a bug in libev
or worse.
=head1 GLOBAL FUNCTIONS
These functions can be called anytime, even before initialising the
library in any way.
=over 4
=item ev_tstamp ev_time ()
Returns the current time as libev would use it. Please note that the
C<ev_now> function is usually faster and also often returns the timestamp
you actually want to know. Also interesting is the combination of
C<ev_now_update> and C<ev_now>.
=item ev_sleep (ev_tstamp interval)
Sleep for the given interval: The current thread will be blocked
until either it is interrupted or the given time interval has
passed (approximately - it might return a bit earlier even if not
libev/ev.pod view on Meta::CPAN
C<ev_TYPE_set> macro.
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.
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:
=over 4
=item C<EV_READ>
=item C<EV_WRITE>
The file descriptor in the C<ev_io> watcher has become readable and/or
writable.
=item C<EV_TIMER>
The C<ev_timer> watcher has timed out.
=item C<EV_PERIODIC>
The C<ev_periodic> watcher has timed out.
=item C<EV_SIGNAL>
The signal specified in the C<ev_signal> watcher has been received by a thread.
=item C<EV_CHILD>
The pid specified in the C<ev_child> watcher has received a status change.
=item C<EV_STAT>
The path specified in the C<ev_stat> watcher changed its attributes somehow.
=item C<EV_IDLE>
The C<ev_idle> watcher has determined that you have nothing better to do.
=item C<EV_PREPARE>
=item C<EV_CHECK>
All C<ev_prepare> watchers are invoked just I<before> C<ev_run> starts to
gather new events, and all C<ev_check> watchers are queued (not invoked)
just after C<ev_run> has gathered them, but before it queues any callbacks
for any received events. That means C<ev_prepare> watchers are the last
watchers invoked before the event loop sleeps or polls for new events, and
C<ev_check> watchers will be invoked before any other watchers of the same
or lower priority within an event loop iteration.
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
C<ev_prepare> watcher might start an idle watcher to keep C<ev_run> from
blocking).
=item C<EV_EMBED>
The embedded event loop specified in the C<ev_embed> watcher needs attention.
=item C<EV_FORK>
The event loop has been resumed in the child process after fork (see
C<ev_fork>).
=item C<EV_CLEANUP>
The event loop is about to be destroyed (see C<ev_cleanup>).
=item C<EV_ASYNC>
The given async watcher has been asynchronously notified (see C<ev_async>).
=item C<EV_CUSTOM>
Not ever sent (or otherwise used) by libev itself, but can be freely used
by libev users to signal watchers (e.g. via C<ev_feed_event>).
=item C<EV_ERROR>
An unspecified error has occurred, the watcher has been stopped. This might
happen because the watcher could not be properly started because libev
ran out of memory, a file descriptor was found to be closed or any other
problem. Libev considers these application bugs.
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.
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 read() or write(). This will not work in multi-threaded
programs, though, as the fd could already be closed and reused for another
thing, so beware.
=back
=head2 GENERIC WATCHER FUNCTIONS
=over 4
=item C<ev_init> (ev_TYPE *watcher, callback)
This macro initialises the generic portion of a watcher. The contents
of the watcher object can be arbitrary (so C<malloc> will do). Only
the generic parts of the watcher are initialised, you I<need> to call
the type-specific C<ev_TYPE_set> macro afterwards to initialise the
type-specific parts. For each type there is also a C<ev_TYPE_init> macro
which rolls both calls into one.
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.
The callback is always of type C<void (*)(struct ev_loop *loop, ev_TYPE *watcher,
int revents)>.
libev/ev.pod view on Meta::CPAN
Whenever you want to start/stop a watcher or do other modifications to an
event loop, you will now have to lock:
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);
Note that sending the C<ev_async> 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.
=head2 THREADS, COROUTINES, CONTINUATIONS, QUEUES... INSTEAD OF CALLBACKS
While the overhead of a callback that e.g. schedules a thread is small, it
is still an overhead. If you embed libev, and your main usage is with some
kind of threads or coroutines, you might want to customise libev so that
doesn't need callbacks anymore.
Imagine you have coroutines that you can switch to using a function
C<switch_to (coro)>, that libev runs in a coroutine called C<libev_coro>
and that due to some magic, the currently active coroutine is stored in a
global called C<current_coro>. Then you can build your own "wait for libev
event" primitive by changing C<EV_CB_DECLARE> and C<EV_CB_INVOKE> (note
the differing C<;> conventions):
#define EV_CB_DECLARE(type) struct my_coro *cb;
#define EV_CB_INVOKE(watcher) switch_to ((watcher)->cb)
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.
A coroutine might now wait for an event with a function called
C<wait_for_event>. (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):
void
wait_for_event (ev_watcher *w)
{
ev_set_cb (w, current_coro);
switch_to (libev_coro);
}
That basically suspends the coroutine inside C<wait_for_event> and
continues the libev coroutine, which, when appropriate, switches back to
this or any other coroutine.
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.
To embed libev, see L</EMBEDDING>, but in short, it's easiest to create two
files, F<my_ev.h> and F<my_ev.c> that include the respective libev files:
// 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"
And then use F<my_ev.h> when you would normally use F<ev.h>, and compile
F<my_ev.c> into your project. When properly specifying include paths, you
can even use F<ev.h> as header file name directly.
=head1 LIBEVENT EMULATION
Libev offers a compatibility emulation layer for libevent. It cannot
emulate the internals of libevent, so here are some usage hints:
=over 4
=item * Only the libevent-1.4.1-beta API is being emulated.
This was the newest libevent version available when libev was implemented,
and is still mostly unchanged in 2010.
=item * Use it by including <event.h>, as usual.
=item * The following members are fully supported: ev_base, ev_callback,
ev_arg, ev_fd, ev_res, ev_events.
=item * Avoid using ev_flags and the EVLIST_*-macros, while it is
maintained by libev, it does not work exactly the same way as in libevent (consider
it a private API).
=item * 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.
=item * In libevent, the last base created gets the signals, in libev, the
base that registered the signal gets the signals.
=item * Other members are not supported.
=item * The libev emulation is I<not> ABI compatible to libevent, you need
to use the libev header file and library.
=back
=head1 C++ SUPPORT
=head2 C API
The normal C API should work fine when used from C++: both ev.h and the
libev sources can be compiled as C++. Therefore, code that uses the C API
will work fine.
Proper exception specifications might have to be added to callbacks passed
libev/ev.pod view on Meta::CPAN
C<EV_A_> is used when other arguments are following. Example:
ev_unref (EV_A);
ev_timer_add (EV_A_ watcher);
ev_run (EV_A_ 0);
It assumes the variable C<loop> of type C<struct ev_loop *> is in scope,
which is often provided by the following macro.
=item C<EV_P>, C<EV_P_>
This provides the loop I<parameter> for functions, if one is required ("ev
loop parameter"). The C<EV_P> form is used when this is the sole parameter,
C<EV_P_> is used when other parameters are following. Example:
// 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)
It declares a parameter C<loop> of type C<struct ev_loop *>, quite
suitable for use with C<EV_A>.
=item C<EV_DEFAULT>, C<EV_DEFAULT_>
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.
For non-multiplicity builds, these macros do nothing, so you always have
to initialise the loop somewhere.
=item C<EV_DEFAULT_UC>, C<EV_DEFAULT_UC_>
Usage identical to C<EV_DEFAULT> and C<EV_DEFAULT_>, but requires that the
default loop has been initialised (C<UC> == unchecked). Their behaviour
is undefined when the default loop has not been initialised by a previous
execution of C<EV_DEFAULT>, C<EV_DEFAULT_> or C<ev_default_init (...)>.
It is often prudent to use C<EV_DEFAULT> when initialising the first
watcher in a function but use C<EV_DEFAULT_UC> afterwards.
=back
Example: Declare and initialise a check watcher, utilising the above
macros so it will work regardless of whether multiple loops are supported
or not.
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);
=head1 EMBEDDING
Libev can (and often is) directly embedded into host
applications. Examples of applications that embed it include the Deliantra
Game Server, the EV perl module, the GNU Virtual Private Ethernet (gvpe)
and rxvt-unicode.
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).
=head2 FILESETS
Depending on what features you need you need to include one or more sets of files
in your application.
=head3 CORE EVENT LOOP
To include only the libev core (all the C<ev_*> functions), with manual
configuration (no autoconf):
#define EV_STANDALONE 1
#include "ev.c"
This will automatically include F<ev.h>, too, and should be done in a
single C source file only to provide the function implementations. To use
it, do the same for F<ev.h> in all files wishing to use this API (best
done by writing a wrapper around F<ev.h> that you can include instead and
where you can put other configuration options):
#define EV_STANDALONE 1
#include "ev.h"
Both header files and implementation files can be compiled with a C++
compiler (at least, that's a stated goal, and breakage will be treated
as a bug).
You need the following files in your source tree, or in a directory
in your include path (e.g. in libev/ when using -Ilibev):
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
F<ev.c> includes the backend files directly when enabled, so you only need
to compile this single file.
=head3 LIBEVENT COMPATIBILITY API
libev/ev.pod view on Meta::CPAN
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 C<ev_async>
watchers.
In the absence of this define, libev will use C<sig_atomic_t volatile>
(from F<signal.h>), which is usually good enough on most platforms.
=item EV_H (h)
The name of the F<ev.h> header file used to include it. The default if
undefined is C<"ev.h"> in F<event.h>, F<ev.c> and F<ev++.h>. This can be
used to virtually rename the F<ev.h> header file in case of conflicts.
=item EV_CONFIG_H (h)
If C<EV_STANDALONE> isn't C<1>, this variable can be used to override
F<ev.c>'s idea of where to find the F<config.h> file, similarly to
C<EV_H>, above.
=item EV_EVENT_H (h)
Similarly to C<EV_H>, this macro can be used to override F<event.c>'s idea
of how the F<event.h> header can be found, the default is C<"event.h">.
=item EV_PROTOTYPES (h)
If defined to be C<0>, then F<ev.h> 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.
=item EV_MULTIPLICITY
If undefined or defined to C<1>, then all event-loop-specific functions
will have the C<struct ev_loop *> 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.
Note that C<EV_DEFAULT> and C<EV_DEFAULT_> will no longer provide a
default loop when multiplicity is switched off - you always have to
initialise the loop manually in this case.
=item EV_MINPRI
=item EV_MAXPRI
The range of allowed priorities. C<EV_MINPRI> must be smaller or equal to
C<EV_MAXPRI>, but otherwise there are no non-obvious limitations. You can
provide for more priorities by overriding those symbols (usually defined
to be C<-2> and C<2>, respectively).
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.
If your embedding application does not need any priorities, defining these
both to C<0> will save some memory and CPU.
=item EV_PERIODIC_ENABLE, EV_IDLE_ENABLE, EV_EMBED_ENABLE, EV_STAT_ENABLE,
EV_PREPARE_ENABLE, EV_CHECK_ENABLE, EV_FORK_ENABLE, EV_SIGNAL_ENABLE,
EV_ASYNC_ENABLE, EV_CHILD_ENABLE.
If undefined or defined to be C<1> (and the platform supports it), then
the respective watcher type is supported. If defined to be C<0>, then it
is not. Disabling watcher types mainly saves code size.
=item EV_FEATURES
If you need to shave off some kilobytes of code at the expense of some
speed (but with the full API), 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.
A typical way to use this symbol is to define it to C<0> (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:
#define EV_FEATURES 0
#define EV_MULTIPLICITY 1
#define EV_USE_POLL 1
#define EV_CHILD_ENABLE 1
#define EV_ASYNC_ENABLE 1
The actual value is a bitset, it can be a combination of the following
values (by default, all of these are enabled):
=over 4
=item C<1> - faster/larger code
Use larger code to speed up some operations.
Currently this is used to override some inlining decisions (enlarging the
code size by roughly 30% on amd64).
When optimising for size, use of compiler flags such as C<-Os> with
gcc is recommended, as well as C<-DNDEBUG>, as libev contains a number of
assertions.
The default is off when C<__OPTIMIZE_SIZE__> is defined by your compiler
(e.g. gcc with C<-Os>).
=item C<2> - faster/larger data structures
Replaces the small 2-heap for timer management by a faster 4-heap, larger
hash table sizes and so on. This will usually further increase code size
and can additionally have an effect on the size of data structures at
runtime.
The default is off when C<__OPTIMIZE_SIZE__> is defined by your compiler
(e.g. gcc with C<-Os>).
=item C<4> - full API configuration
This enables priorities (sets C<EV_MAXPRI>=2 and C<EV_MINPRI>=-2), and
enables multiplicity (C<EV_MULTIPLICITY>=1).
libev/ev.pod view on Meta::CPAN
These just add the watcher into an array or at the head of a list.
=item Stopping check/prepare/idle/fork/async watchers: O(1)
=item Stopping an io/signal/child watcher: O(number_of_watchers_for_this_(fd/signal/pid % EV_PID_HASHSIZE))
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).
=item Finding the next timer in each loop iteration: O(1)
By virtue of using a binary or 4-heap, the next timer is always found at a
fixed position in the storage array.
=item Each change on a file descriptor per loop iteration: O(number_of_watchers_for_this_fd)
A change means an I/O watcher gets started or stopped, which requires
libev to recalculate its status (and possibly tell the kernel, depending
on backend and whether C<ev_io_set> was used).
=item Activating one watcher (putting it into the pending state): O(1)
=item Priority handling: O(number_of_priorities)
Priorities are implemented by allocating some space for each
priority. When doing priority-based operations, libev usually has to
linearly search all the priorities, but starting/stopping and activating
watchers becomes O(1) with respect to priority handling.
=item Sending an ev_async: O(1)
=item Processing ev_async_send: O(number_of_async_watchers)
=item Processing signals: O(max_signal_number)
Sending involves a system call I<iff> there were no other C<ev_async_send>
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.
=back
=head1 PORTING FROM LIBEV 3.X TO 4.X
The major version 4 introduced some incompatible changes to the API.
At the moment, the C<ev.h> 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 API early than late.
=over 4
=item C<EV_COMPAT3> backwards compatibility mechanism
The backward compatibility mechanism can be controlled by
C<EV_COMPAT3>. See L</"PREPROCESSOR SYMBOLS/MACROS"> in the L</EMBEDDING>
section.
=item C<ev_default_destroy> and C<ev_default_fork> have been removed
These calls can be replaced easily by their C<ev_loop_xxx> counterparts:
ev_loop_destroy (EV_DEFAULT_UC);
ev_loop_fork (EV_DEFAULT);
=item function/symbol renames
A number of functions and symbols have been renamed:
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
Most functions working on C<struct ev_loop> objects don't have an
C<ev_loop_> prefix, so it was removed; C<ev_loop>, C<ev_unloop> and
associated constants have been renamed to not collide with the C<struct
ev_loop> anymore and C<EV_TIMER> now follows the same naming scheme
as all other watcher types. Note that C<ev_loop_fork> is still called
C<ev_loop_fork> because it would otherwise clash with the C<ev_fork>
typedef.
=item C<EV_MINIMAL> mechanism replaced by C<EV_FEATURES>
The preprocessor symbol C<EV_MINIMAL> has been replaced by a different
mechanism, C<EV_FEATURES>. Programs using C<EV_MINIMAL> usually compile
and work, but the library code will of course be larger.
=back
=head1 GLOSSARY
=over 4
=item active
A watcher is active as long as it has been started and not yet stopped.
See L</WATCHER STATES> for details.
=item application
In this document, an application is whatever is using libev.
=item backend
( run in 1.406 second using v1.01-cache-2.11-cpan-71847e10f99 )