EV
view release on metacpan or search on metacpan
libev/ev.pod view on Meta::CPAN
=encoding utf-8
=head1 NAME
libev - a high performance full-featured event loop written in C
=head1 SYNOPSIS
#include <ev.h>
=head2 EXAMPLE PROGRAM
// a single header file is required
#include <ev.h>
#include <stdio.h> // 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;
}
=head1 ABOUT THIS DOCUMENT
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.
libev/ev.pod view on Meta::CPAN
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, C<epoll> 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).
The function itself is quite fast and it's usually not a problem to call
it just in case after a fork.
Example: Automate calling C<ev_loop_fork> on the default loop when
using pthreads.
static void
post_fork_child (void)
{
ev_loop_fork (EV_DEFAULT);
}
...
pthread_atfork (0, 0, post_fork_child);
=item int ev_is_default_loop (loop)
Returns true when the given loop is, in fact, the default loop, and false
otherwise.
=item unsigned int ev_iteration (loop)
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 C<0>
and happily wraps around with enough iterations.
This value can sometimes be useful as a generation counter of sorts (it
"ticks" the number of loop iterations), as it roughly corresponds with
C<ev_prepare> and C<ev_check> calls - and is incremented between the
prepare and check phases.
=item unsigned int ev_depth (loop)
Returns the number of times C<ev_run> was entered minus the number of
times C<ev_run> was exited normally, in other words, the recursion depth.
Outside C<ev_run>, this number is zero. In a callback, this number is
C<1>, unless C<ev_run> was invoked recursively (or from another thread),
in which case it is higher.
Leaving C<ev_run> 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.
=item unsigned int ev_backend (loop)
Returns one of the C<EVBACKEND_*> flags indicating the event backend in
use.
=item ev_tstamp ev_now (loop)
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).
=item ev_now_update (loop)
Establishes the current time by querying the kernel, updating the time
returned by C<ev_now ()> in the progress. This is a costly operation and
is usually done automatically within C<ev_run ()>.
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.
See also L</The special problem of time updates> in the C<ev_timer> section.
=item ev_suspend (loop)
=item ev_resume (loop)
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.
A typical use case would be an interactive program such as a game: When
the user presses C<^Z> 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 C<ev_suspend>
in your C<SIGTSTP> handler, sending yourself a C<SIGSTOP> and calling
C<ev_resume> directly afterwards to resume timer processing.
Effectively, all C<ev_timer> watchers will be delayed by the time spend
between C<ev_suspend> and C<ev_resume>, and all C<ev_periodic> watchers
will be rescheduled (that is, they will lose any events that would have
occurred while suspended).
After calling C<ev_suspend> you B<must not> call I<any> function on the
given loop other than C<ev_resume>, and you B<must not> call C<ev_resume>
without a previous call to C<ev_suspend>.
Calling C<ev_suspend>/C<ev_resume> has the side effect of updating the
event loop time (see C<ev_now_update>).
=item bool ev_run (loop, int flags)
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>.
If the flags argument is specified as C<0>, it will keep handling events
until either no event watchers are active anymore or C<ev_break> was
called.
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 C<ev_run> again").
Please note that an explicit C<ev_break> 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.
This function is I<mostly> exception-safe - you can break out of a
C<ev_run> call by calling C<longjmp> in a callback, throwing a C++
exception and so on. This does not decrement the C<ev_depth> value, nor
will it clear any outstanding C<EVBREAK_ONE> breaks.
A flags value of C<EVRUN_NOWAIT> 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.
A flags value of C<EVRUN_ONCE> 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.
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 C<ev_run>"). However, a pair of C<ev_prepare>/C<ev_check> watchers is
usually a better approach for this kind of thing.
Here are the gory details of what C<ev_run> does (this is for your
understanding, not a guarantee that things will work exactly like this in
future versions):
- 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.
libev/ev.pod view on Meta::CPAN
... 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!
=item ev_break (loop, how)
Can be used to make a call to C<ev_run> return early (but only after it
has processed all outstanding events). The C<how> argument must be either
C<EVBREAK_ONE>, which will make the innermost C<ev_run> call return, or
C<EVBREAK_ALL>, which will make all nested C<ev_run> calls return.
This "break state" will be cleared on the next call to C<ev_run>.
It is safe to call C<ev_break> from outside any C<ev_run> calls, too, in
which case it will have no effect.
=item ev_ref (loop)
=item ev_unref (loop)
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, C<ev_run> will not return on its own.
This is useful when you have a watcher that you never intend to
unregister, but that nevertheless should not keep C<ev_run> from
returning. In such a case, call C<ev_unref> after starting, and C<ev_ref>
before stopping it.
As an example, libev itself uses this for its internal signal pipe: It
is not visible to the libev user and should not keep C<ev_run> 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> and I<ref
before stop> (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 C<ev_ref>
in the callback).
Example: Create a signal watcher, but keep it from keeping C<ev_run>
running when nothing else is active.
ev_signal exitsig;
ev_signal_init (&exitsig, sig_cb, SIGINT);
ev_signal_start (loop, &exitsig);
ev_unref (loop);
Example: For some weird reason, unregister the above signal handler again.
ev_ref (loop);
ev_signal_stop (loop, &exitsig);
=item ev_set_io_collect_interval (loop, ev_tstamp interval)
=item ev_set_timeout_collect_interval (loop, ev_tstamp interval)
These advanced functions influence the time that libev will spend waiting
for events. Both time intervals are by default C<0>, meaning that libev
will try to invoke timer/periodic callbacks and I/O callbacks with minimum
latency.
Setting these to a higher value (the C<interval> I<must> be >= C<0>)
allows libev to delay invocation of I/O and timer/periodic callbacks
to increase efficiency of loop iterations (or to increase power-saving
opportunities).
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 CPU time to poll for new
events, especially with backends like C<select ()> which have a high
overhead for the actual polling but can deliver many events at once.
By setting a higher I<io collect interval> 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 C<ev_periodic> and
C<ev_timer>) will not be affected. Setting this to a non-null value will
introduce an additional C<ev_sleep ()> 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).
Likewise, by setting a higher I<timeout collect interval> you allow libev
to spend more time collecting timeouts, at the expense of increased
latency/jitter/inexactness (the watcher callback will be called
later). C<ev_io> watchers will not be affected. Setting this to a non-null
value will not introduce any overhead in libev.
Many (busy) programs can usually benefit by setting the I/O collect
interval to a value near C<0.1> 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 C<0.01>,
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).
Setting the I<timeout collect interval> 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 C<ev_periodic> watchers and make sure
they fire on, say, one-second boundaries only.
Example: we only need 0.1s timeout granularity, and we wish not to poll
more often than 100 times per second:
ev_set_timeout_collect_interval (EV_DEFAULT_UC_ 0.1);
ev_set_io_collect_interval (EV_DEFAULT_UC_ 0.01);
=item ev_invoke_pending (loop)
This call will simply invoke all pending watchers while resetting their
pending state. Normally, C<ev_run> 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 C<ev_invoke_pending> or C<ev_run> of course).
=item int ev_pending_count (loop)
Returns the number of pending watchers - zero indicates that no watchers
are pending.
=item ev_set_invoke_pending_cb (loop, void (*invoke_pending_cb)(EV_P))
This overrides the invoke pending functionality of the loop: Instead of
invoking all pending watchers when there are any, C<ev_run> will call
this callback instead. This is useful, for example, when you want to
invoke the actual watchers inside another context (another thread etc.).
If you want to reset the callback, use C<ev_invoke_pending> as new
callback.
=item ev_set_loop_release_cb (loop, void (*release)(EV_P) throw (), void (*acquire)(EV_P) throw ())
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.
However, C<ev_run> 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 C<ev_break> and C<ev_async_send>, another way is to set these
I<release> and I<acquire> callbacks on the loop.
When set, then C<release> will be called just before the thread is
suspended waiting for new events, and C<acquire> is called just
afterwards.
Ideally, C<release> will just call your mutex_unlock function, and
C<acquire> will just call the mutex_lock function again.
While event loop modifications are allowed between invocations of
C<release> and C<acquire> (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 C<ev_async> watcher to wake up C<ev_run> when you want it
to take note of any changes you made.
In theory, threads executing C<ev_run> will be async-cancel safe between
invocations of C<release> and C<acquire>.
See also the locking example in the C<THREADS> section later in this
document.
=item ev_set_userdata (loop, void *data)
=item void *ev_userdata (loop)
Set and retrieve a single C<void *> associated with a loop. When
C<ev_set_userdata> has never been called, then C<ev_userdata> returns
C<0>.
These two functions can be used to associate arbitrary data with a loop,
and are intended solely for the C<invoke_pending_cb>, C<release> and
C<acquire> callbacks described above, but of course can be (ab-)used for
any other purpose as well.
=item ev_verify (loop)
This function only does something when C<EV_VERIFY> 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 C<abort ()>.
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.
=back
=head1 ANATOMY OF A WATCHER
In the following description, uppercase C<TYPE> in names stands for the
watcher type, e.g. C<ev_TYPE_start> can mean C<ev_timer_start> for timer
watchers and C<ev_io_start> for I/O watchers.
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 STDIN to become readable, you would create an C<ev_io> watcher
for that:
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);
As you can see, you are responsible for allocating the memory for your
watcher structures (and it is I<usually> a bad idea to do this on the
stack).
Each watcher has an associated watcher structure (called C<struct ev_TYPE>
or simply C<ev_TYPE>, as typedefs are provided for all watcher structs).
Each watcher structure must be initialised by a call to C<ev_init (watcher
*, callback)>, 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).
Each watcher type further has its own C<< ev_TYPE_set (watcher *, ...) >>
macro to configure it, with arguments specific to the watcher type. There
is also a macro to combine initialisation and setting in one call: C<<
ev_TYPE_init (watcher *, callback, ...) >>.
To make the watcher actually watch out for events, you have to start it
with a watcher-specific start function (C<< ev_TYPE_start (loop, watcher
*) >>), and you can stop watching for events at any time by calling the
corresponding stop function (C<< ev_TYPE_stop (loop, watcher *) >>.
As long as your watcher is active (has been started but not stopped) you
must not touch the values stored in it except when explicitly documented
otherwise. Most specifically you must never reinitialise it or call its
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)>.
Example: Initialise an C<ev_io> watcher in two steps.
ev_io w;
ev_init (&w, my_cb);
ev_io_set (&w, STDIN_FILENO, EV_READ);
=item C<ev_TYPE_set> (ev_TYPE *watcher, [args])
This macro initialises the type-specific parts of a watcher. You need to
call C<ev_init> at least once before you call this macro, but you can
call C<ev_TYPE_set> 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 C<ev_init> macro).
Although some watcher types do not have type-specific arguments
(e.g. C<ev_prepare>) you still need to call its C<set> macro.
See C<ev_init>, above, for an example.
=item C<ev_TYPE_init> (ev_TYPE *watcher, callback, [args])
This convenience macro rolls both C<ev_init> and C<ev_TYPE_set> macro
calls into a single call. This is the most convenient method to initialise
a watcher. The same limitations apply, of course.
Example: Initialise and set an C<ev_io> watcher in one step.
ev_io_init (&w, my_cb, STDIN_FILENO, EV_READ);
=item C<ev_TYPE_start> (loop, ev_TYPE *watcher)
Starts (activates) the given watcher. Only active watchers will receive
events. If the watcher is already active nothing will happen.
Example: Start the C<ev_io> watcher that is being abused as example in this
libev/ev.pod view on Meta::CPAN
its callback is about to be invoked, so it is not normally pending inside
the watcher callback.
Generally, 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 pending but not active, it can be freely accessed (e.g.
by calling C<ev_TYPE_set>), 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.
Explicitly stopping a watcher will also clear the pending state
unconditionally, so it is safe to stop a watcher and then free it.
It is also possible to feed an event on a watcher that is not active (e.g.
via C<ev_feed_event>), in which case it becomes pending without being
active.
=item stopped
A watcher can be stopped implicitly by libev (in which case it might still
be pending), or explicitly by calling its C<ev_TYPE_stop> 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.
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 C<ev_TYPE_init>
it again).
=back
=head2 WATCHER PRIORITY MODELS
Many event loops support I<watcher priorities>, which are usually small
integers that influence the ordering of event callback invocation
between watchers in some way, all else being equal.
In libev, watcher priorities can be set using C<ev_set_priority>. See its
description for the more technical details such as the actual priority
range.
There are two common ways how these these priorities are being interpreted
by event loops:
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.
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.
Libev uses the second (only-for-ordering) model for all its watchers
except for idle watchers (which use the lock-out model).
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.
Static (ordering) priorities are most useful when you have two or more
watchers handling the same resource: a typical usage example is having an
C<ev_io> watcher to receive data, and an associated C<ev_timer> 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).
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.
For example, to emulate how many other event libraries handle priorities,
you can associate an C<ev_idle> 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.
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.
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:
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
libev/ev.pod view on Meta::CPAN
=item ev_idle_init (ev_idle *, callback)
Initialises and configures the idle watcher - it has no parameters of any
kind. There is a C<ev_idle_set> macro, but using it is utterly pointless,
believe me.
=back
=head3 Examples
Example: Dynamically allocate an C<ev_idle> watcher, start it, and in the
callback, free it. Also, use no error checking, as usual.
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);
=head2 C<ev_prepare> and C<ev_check> - customise your event loop!
Prepare and check watchers are often (but not always) used in pairs:
prepare watchers get invoked before the process blocks and check watchers
afterwards.
You I<must not> call C<ev_run> (or similar functions that enter the
current event loop) or C<ev_loop_fork> from either C<ev_prepare> or
C<ev_check> 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
C<ev_prepare>, blocking, C<ev_check> so if you have one watcher of each
kind they will always be called in pairs bracketing the blocking call.
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 C<XFlush ()> in an C<ev_prepare>
watcher).
This is done by examining in each prepare call which file descriptors
need to be watched by the other library, registering C<ev_io> watchers
for them and starting an C<ev_timer> 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?).
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).
When used for this purpose, it is recommended to give C<ev_check> watchers
highest (C<EV_MAXPRI>) priority, to ensure that they are being run before
any other watchers after the poll (this doesn't matter for C<ev_prepare>
watchers).
Also, C<ev_check> watchers (and C<ev_prepare> watchers, too) should not
activate ("feed") events into libev. While libev fully supports this, they
might get executed before other C<ev_check> watchers did their job. As
C<ev_check> watchers are often used to embed other (non-libev) event
loops those other event loops might be in an unusable state until their
C<ev_check> watcher ran (always remind yourself to coexist peacefully with
others).
=head3 Abusing an C<ev_check> watcher for its side-effect
C<ev_check> (and less often also C<ev_prepare>) 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.
Using an C<ev_check> 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 C<ev_check> watcher will not be invoked.
This is where C<ev_idle> watchers come in handy - all you need is a
single global idle watcher that is active as long as you have one active
C<ev_check> watcher. The C<ev_idle> watcher makes sure the event loop
will not sleep, and the C<ev_check> watcher makes sure a callback gets
invoked. Neither watcher alone can do that.
=head3 Watcher-Specific Functions and Data Members
=over 4
=item ev_prepare_init (ev_prepare *, callback)
=item ev_check_init (ev_check *, callback)
Initialises and configures the prepare or check watcher - they have no
parameters of any kind. There are C<ev_prepare_set> and C<ev_check_set>
macros, but using them is utterly, utterly, utterly and completely
pointless.
=back
=head3 Examples
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 C<EV::ADNS> that does this, which you could
use as a working example. Another Perl module named C<EV::Glib> embeds a
Glib main context into libev, and finally, C<Glib::EV> embeds EV into the
Glib event loop).
Method 1: Add IO 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 C<ev_clear_pending> explicitly, as
the callbacks for the IO/timeout watchers might not have been called yet.
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));
}
Method 2: This would be just like method 1, but you run C<adns_afterpoll>
in the prepare watcher and would dispose of the check watcher.
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.
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
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 EV. The C<Glib::EV> module uses
this approach, effectively embedding EV as a client into the horrible
libglib event loop.
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;
}
=head2 C<ev_embed> - when one backend isn't enough...
This is a rather advanced watcher type that lets you embed one event loop
into another (currently only C<ev_io> 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).
There are primarily two reasons you would want that: work around bugs and
prioritise I/O.
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 C<poll> and then
C<kevent>, but at least you can use both mechanisms for what they are
best: C<kqueue> for scalable sockets and C<poll> if you want it to work :)
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.
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 C<ev_embed_sweep (mainloop, watcher)> to make a single
sweep and invoke their callbacks (the callback doesn't need to invoke the
C<ev_embed_sweep> function directly, it could also start an idle watcher
to give the embedded loop strictly lower priority for example).
You can also set the callback to C<0>, in which case the embed watcher
will automatically execute the embedded loop sweep whenever necessary.
Fork detection will be handled transparently while the C<ev_embed> 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
C<ev_loop_fork> on the embedded loop.
Unfortunately, not all backends are embeddable: only the ones returned by
C<ev_embeddable_backends> are, which, unfortunately, does not include any
portable one.
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.
=head3 C<ev_embed> and fork
While the C<ev_embed> 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 C<ev_loop_fork ()>
as applicable.
=head3 Watcher-Specific Functions and Data Members
=over 4
=item ev_embed_init (ev_embed *, callback, struct ev_loop *embedded_loop)
=item ev_embed_set (ev_embed *, struct ev_loop *embedded_loop)
Configures the watcher to embed the given loop, which must be
embeddable. If the callback is C<0>, then C<ev_embed_sweep> 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).
=item ev_embed_sweep (loop, ev_embed *)
Make a single, non-blocking sweep over the embedded loop. This works
similarly to C<ev_run (embedded_loop, EVRUN_NOWAIT)>, but in the most
appropriate way for embedded loops.
=item struct ev_loop *other [read-only]
The embedded event loop.
=back
=head3 Examples
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 C<loop_hi>, while the embeddable loop is stored in
C<loop_lo> (which is C<loop_hi> in the case no embeddable loop can be
libev/ev.pod view on Meta::CPAN
returns.
Unlike C<ev_feed_event>, this call is safe to do from other threads,
signal or similar contexts (see the discussion of C<EV_ATOMIC_T> in the
embedding section below on what exactly this means).
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 C<ev_async> watchers are level-triggered: they are set on
C<ev_async_send>, reset when the event loop detects that).
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.
=item bool = ev_async_pending (ev_async *)
Returns a non-zero value when C<ev_async_send> has been called on the
watcher but the event has not yet been processed (or even noted) by the
event loop.
C<ev_async_send> 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. C<ev_async_pending> can be used to very
quickly check whether invoking the loop might be a good idea.
Not that this does I<not> 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.
=back
=head1 OTHER FUNCTIONS
There are some other functions of possible interest. Described. Here. Now.
=over 4
=item ev_once (loop, int fd, int events, ev_tstamp timeout, callback, arg)
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.
If C<fd> is less than 0, then no I/O watcher will be started and the
C<events> argument is being ignored. Otherwise, an C<ev_io> watcher for
the given C<fd> and C<events> set will be created and started.
If C<timeout> is less than 0, then no timeout watcher will be
started. Otherwise an C<ev_timer> watcher with after = C<timeout> (and
repeat = 0) will be started. C<0> is a valid timeout.
The callback has the type C<void (*cb)(int revents, void *arg)> and is
passed an C<revents> set like normal event callbacks (a combination of
C<EV_ERROR>, C<EV_READ>, C<EV_WRITE> or C<EV_TIMER>) and the C<arg>
value passed to C<ev_once>. Note that it is possible to receive I<both>
a timeout and an io event at the same time - you probably should give io
events precedence.
Example: wait up to ten seconds for data to appear on STDIN_FILENO.
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);
=item ev_feed_fd_event (loop, int fd, int revents)
Feed an event on the given fd, as if a file descriptor backend detected
the given events.
=item ev_feed_signal_event (loop, int signum)
Feed an event as if the given signal occurred. See also C<ev_feed_signal>,
which is async-safe.
=back
=head1 COMMON OR USEFUL IDIOMS (OR BOTH)
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.
=head2 ASSOCIATING CUSTOM DATA WITH A WATCHER
Each watcher has, by default, a C<void *data> 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:
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);
And since your callback will be called with a pointer to the watcher, you
can cast it back to your own type:
libev/ev.pod view on Meta::CPAN
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.
A common way around all these issues is to make sure that
C<start_new_request> I<always> returns before the callback is invoked. If
C<start_new_request> immediately knows the result, it can artificially
delay invoking the callback by using a C<prepare> or C<idle> watcher for
example, or more sneakily, by reusing an existing (stopped) watcher and
pushing it into the pending queue:
ev_set_cb (watcher, callback);
ev_feed_event (EV_A_ watcher, 0);
This way, C<start_new_request> can safely return before the callback is
invoked, while not delaying callback invocation too much.
=head2 MODEL/NESTED EVENT LOOP INVOCATIONS AND EXIT CONDITIONS
Often (especially in GUI toolkits) there are places where you have
I<modal> interaction, which is most easily implemented by recursively
invoking C<ev_run>.
This brings the problem of exiting - a callback might want to finish the
main C<ev_run> 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 C<ev_break> will not work.
The solution is to maintain "break this loop" variable for each C<ev_run>
invocation, and use a loop around C<ev_run> until the condition is
triggered, using C<EVRUN_ONCE>:
// 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);
To exit from any of these loops, just set the corresponding exit variable:
// 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;
=head2 THREAD LOCKING EXAMPLE
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.
For a real-world example, see the C<EV::Loop::Async> perl module,
which uses exactly this technique (which is suited for many high-level
languages).
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.
First, you need to associate some data with the event loop:
typedef struct {
pthread_mutex_t lock; /* global loop lock */
pthread_t tid;
pthread_cond_t invoke_cv;
ev_async async_w;
} 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);
}
The callback for the C<ev_async> 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:
static void
async_cb (EV_P_ ev_async *w, int revents)
{
// just used for the side effects
}
The C<l_release> and C<l_acquire> callbacks simply unlock/lock the mutex
protecting the loop data, respectively.
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);
}
The event loop thread first acquires the mutex, and then jumps straight
into C<ev_run>:
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;
}
Instead of invoking all pending watchers, the C<l_invoke> callback will
signal the main thread via some unspecified mechanism (signals? pipe
writes? C<Async::Interrupt>?) 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):
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);
}
}
Now, whenever the main thread gets told to invoke pending watchers, it
will grab the lock, call C<ev_invoke_pending> and then signal the loop
thread to continue:
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);
}
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
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 C<noexcept>
specification. If you have code that needs to be compiled as both C and
C++ you can use the C<EV_NOEXCEPT> macro for this:
static void
fatal_error (const char *msg) EV_NOEXCEPT
{
perror (msg);
abort ();
}
...
ev_set_syserr_cb (fatal_error);
The only API functions that can currently throw exceptions are C<ev_run>,
C<ev_invoke>, C<ev_invoke_pending> and C<ev_loop_destroy> (the latter
because it runs cleanup watchers).
Throwing exceptions in watcher callbacks is only supported if libev itself
is compiled with a C++ compiler or your C and C++ environments allow
throwing exceptions through C libraries (most do).
=head2 C++ API
Libev comes with some simplistic wrapper classes for C++ 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.
To use it,
#include <ev++.h>
This automatically includes F<ev.h> and puts all of its definitions (many
of them macros) into the global namespace. All C++ specific things are
put into the C<ev> namespace. It should support all the same embedding
options as F<ev.h>, most notably C<EV_MULTIPLICITY>.
Care has been taken to keep the overhead low. The only data member the C++
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 C<EV_MULTIPLICITY> when embedding libev).
Currently, functions, static and non-static member functions and classes
with C<operator ()> 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).
For all this to work, your C++ 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++.
Here is a list of things available in the C<ev> namespace:
=over 4
=item C<ev::READ>, C<ev::WRITE> etc.
These are just enum values with the same values as the C<EV_READ> etc.
macros from F<ev.h>.
=item C<ev::tstamp>, C<ev::now>
Aliases to the same types/functions as with the C<ev_> prefix.
=item C<ev::io>, C<ev::timer>, C<ev::periodic>, C<ev::idle>, C<ev::sig> etc.
For each C<ev_TYPE> watcher in F<ev.h> there is a corresponding class of
the same name in the C<ev> namespace, with the exception of C<ev_signal>
which is called C<ev::sig> to avoid clashes with the C<signal> macro
defined by many implementations.
All of those classes have these methods:
=over 4
=item ev::TYPE::TYPE ()
=item ev::TYPE::TYPE (loop)
=item ev::TYPE::~TYPE
The constructor (optionally) takes an event loop to associate the watcher
with. If it is omitted, it will use C<EV_DEFAULT>.
The constructor calls C<ev_init> for you, which means you have to call the
C<set> method before starting it.
It will not set a callback, however: You have to call the templated C<set>
method to set a callback before you can start the watcher.
(The reason why you have to use a method is a limitation in C++ which does
not allow explicit template arguments for constructors).
The destructor automatically stops the watcher if it is active.
=item w->set<class, &class::method> (object *)
This method sets the callback method to call. The method has to have a
signature of C<void (*)(ev_TYPE &, int)>, it receives the watcher as
first argument and the C<revents> as second. The object must be given as
parameter and is stored in the C<data> member of the watcher.
This method synthesizes efficient thunking code to call your method from
libev/ev.pod view on Meta::CPAN
libev. EV is developed together with libev. Apart from the EV core module,
there are additional modules that implement libev-compatible interfaces
to C<libadns> (C<EV::ADNS>, but C<AnyEvent::DNS> is preferred nowadays),
C<Net::SNMP> (C<Net::SNMP::EV>) and the C<libglib> event core (C<Glib::EV>
and C<EV::Glib>).
It can be found and installed via CPAN, its homepage is at
L<http://software.schmorp.de/pkg/EV>.
=item Python
Python bindings can be found at L<http://code.google.com/p/pyev/>. It
seems to be quite complete and well-documented.
=item Ruby
Tony Arcieri has written a ruby extension that offers access to a subset
of the libev API and adds file handle abstractions, asynchronous DNS and
more on top of it. It can be found via gem servers. Its homepage is at
L<http://rev.rubyforge.org/>.
Roger Pack reports that using the link order C<-lws2_32 -lmsvcrt-ruby-190>
makes rev work even on mingw.
=item Haskell
A haskell binding to libev is available at
L<http://hackage.haskell.org/cgi-bin/hackage-scripts/package/hlibev>.
=item D
Leandro Lucarella has written a D language binding (F<ev.d>) for libev, to
be found at L<http://www.llucax.com.ar/proj/ev.d/index.html>.
=item Ocaml
Erkki Seppala has written Ocaml bindings for libev, to be found at
L<http://modeemi.cs.tut.fi/~flux/software/ocaml-ev/>.
=item Lua
Brian Maher has written a partial interface to libev for lua (at the
time of this writing, only C<ev_io> and C<ev_timer>), to be found at
L<http://github.com/brimworks/lua-ev>.
=item Javascript
Node.js (L<http://nodejs.org>) uses libev as the underlying event library.
=item Others
There are others, and I stopped counting.
=back
=head1 MACRO MAGIC
Libev can be compiled with a variety of options, the most fundamental
of which is C<EV_MULTIPLICITY>. This option determines whether (most)
functions and callbacks have an initial C<struct ev_loop *> argument.
To make it easier to write programs that cope with either variant, the
following macros are defined:
=over 4
=item C<EV_A>, C<EV_A_>
This provides the loop I<argument> for functions, if one is required ("ev
loop argument"). The C<EV_A> form is used when this is the sole argument,
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
libev/ev.pod view on Meta::CPAN
power of two).
=item EV_USE_4HEAP
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 C<1>. The 4-heap uses more complicated (longer) code but has noticeably
faster performance with many (thousands) of watchers.
The default is C<1>, unless C<EV_FEATURES> overrides it, in which case it
will be C<0>.
=item EV_HEAP_CACHE_AT
Heaps are not very cache-efficient. To improve the cache-efficiency of the
timer and periodics heaps, libev can cache the timestamp (I<at>) within
the heap structure (selected by defining C<EV_HEAP_CACHE_AT> to C<1>),
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.
The default is C<1>, unless C<EV_FEATURES> overrides it, in which case it
will be C<0>.
=item EV_VERIFY
Controls how much internal verification (see C<ev_verify ()>) will
be done: If set to C<0>, no internal verification code will be compiled
in. If set to C<1>, then verification code will be compiled in, but not
called. If set to C<2>, then the internal verification code will be
called once per loop, which can slow down libev. If set to C<3>, then the
verification code will be called very frequently, which will slow down
libev considerably.
Verification errors are reported via C's C<assert> mechanism, so if you
disable that (e.g. by defining C<NDEBUG>) then no errors will be reported.
The default is C<1>, unless C<EV_FEATURES> overrides it, in which case it
will be C<0>.
=item EV_COMMON
By default, all watchers have a C<void *data> 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.
For example, the perl EV module uses something like this:
#define EV_COMMON \
SV *self; /* contains this struct */ \
SV *cb_sv, *fh /* note no trailing ";" */
=item EV_CB_DECLARE (type)
=item EV_CB_INVOKE (watcher, revents)
=item ev_set_cb (ev, cb)
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 F<ev.h> header file for
their default definitions. One possible use for overriding these is to
avoid the C<struct ev_loop *> as first argument in all cases, or to use
method calls instead of plain function calls in C++.
=back
=head2 EXPORTED API SYMBOLS
If you need to re-export the API (e.g. via a DLL) and you need a list of
exported symbols, you can use the provided F<Symbol.*> files which list
all public symbols, one per line:
Symbols.ev for libev proper
Symbols.event for the libevent emulation
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).
A sed command like this will create wrapper C<#define>'s that you need to
include before including F<ev.h>:
<Symbols.ev sed -e "s/.*/#define & myprefix_&/" >wrap.h
This would create a file F<wrap.h> which essentially looks like this:
#define ev_backend myprefix_ev_backend
#define ev_check_start myprefix_ev_check_start
#define ev_check_stop myprefix_ev_check_stop
...
=head2 EXAMPLES
For a real-world example of a program the includes libev
verbatim, you can have a look at the EV perl module
(L<http://software.schmorp.de/pkg/EV.html>). It has the libev files in
the F<libev/> subdirectory and includes them in the F<EV/EVAPI.h> (public
interface) and F<EV.xs> (implementation) files. Only the F<EV.xs> file
will be compiled. It is pretty complex because it provides its own header
file.
The usage in rxvt-unicode is simpler. It has a F<ev_cpp.h> header file
that everybody includes and which overrides some configure choices:
#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 <config.h>
#include "ev++.h"
And a F<ev_cpp.C> implementation file that contains libev proper and is compiled:
#include "ev_cpp.h"
#include "ev.c"
libev/ev.pod view on Meta::CPAN
parameter (C<ev_default_*> calls have an implicit default loop parameter,
of course): libev guarantees that different event loops share no data
structures that need any locking.
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).
Specifically to support threads (and signal handlers), libev implements
so-called C<ev_async> watchers, which allow some limited form of
concurrency on the same event loop, namely waking it up "from the
outside".
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:
=over 4
=item * most applications have a main thread: use the default libev loop
in that thread, or create a separate thread running only the default loop.
This helps integrating other libraries or software modules that use libev
themselves and don't care/know about threading.
=item * one loop per thread is usually a good model.
Doing this is almost never wrong, sometimes a better-performance model
exists, but it is always a good start.
=item * other models exist, such as the leader/follower pattern, where one
loop is handed through multiple threads in a kind of round-robin fashion.
Choosing a model is hard - look around, learn, know that usually you can do
better than you currently do :-)
=item * often you need to talk to some other thread which blocks in the
event loop.
C<ev_async> watchers can be used to wake them up from other threads safely
(or from signal contexts...).
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 C<ev_async> watcher from the default loop
watcher callback into the event loop interested in the signal.
=back
See also L</THREAD LOCKING EXAMPLE>.
=head3 COROUTINES
Libev is very accommodating to coroutines ("cooperative threads"):
libev fully supports nesting calls to its functions from different
coroutines (e.g. you can call C<ev_run> 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 C<ev_periodic> reschedule callbacks.
Care has been taken to ensure that libev does not keep local state inside
C<ev_run>, and other calls do not usually allow for coroutine switches as
they do not call any callbacks.
=head2 COMPILER WARNINGS
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.
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.
Another reason is that some compiler warnings require elaborate
workarounds, or other changes to the code that make it less clear and less
maintainable.
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.
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.
=head2 VALGRIND
Valgrind has a special section here because it is a popular tool that is
highly useful. Unfortunately, valgrind reports are very hard to interpret.
If you think you found a bug (memory leak, uninitialised data access etc.)
in libev, then check twice: If valgrind reports something like:
==2274== definitely lost: 0 bytes in 0 blocks.
==2274== possibly lost: 0 bytes in 0 blocks.
==2274== still reachable: 256 bytes in 1 blocks.
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.
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.
Keep in mind that valgrind is a very good tool, but only a tool. Don't
make it into some kind of religion.
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.
If you need, for some reason, empty reports from valgrind for your project
libev/ev.pod view on Meta::CPAN
#include "evwrap.h"
#include "ev.c"
=head3 The winsocket C<select> function
The winsocket C<select> function doesn't follow POSIX in that it
requires socket I<handles> and not socket I<file descriptors> (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 C<_open_osfhandle> for this). See the
discussion of the C<EV_SELECT_USE_FD_SET>, C<EV_SELECT_IS_WINSOCKET> and
C<EV_FD_TO_WIN32_HANDLE> preprocessor symbols for more info.
The configuration for a "naked" win32 using the Microsoft runtime
libraries and raw winsocket select is:
#define EV_USE_SELECT 1
#define EV_SELECT_IS_WINSOCKET 1 /* forces EV_SELECT_USE_FD_SET, too */
Note that winsockets handling of fd sets is O(n), so you can easily get a
complexity in the O(n²) range when using win32.
=head3 Limited number of file descriptors
Windows has numerous arbitrary (and low) limits on things.
Early versions of winsocket's select only supported waiting for a maximum
of C<64> handles (probably owning to the fact that all windows kernels
can only wait for C<64> 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!).
Newer versions support more handles, but you need to define C<FD_SETSIZE>
to some high number (e.g. C<2048>) 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).
Another limit is the number of file descriptors in the Microsoft runtime
libraries, which by default is C<64> (there must be a hidden I<64>
fetish or something like this inside Microsoft). You can increase this
by calling C<_setmaxstdio>, which can increase this limit to C<2048>
(another arbitrary limit), but is broken in many versions of the Microsoft
runtime libraries. This might get you to about C<512> or C<2048> 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(n²)) will likely make this unworkable.
=head2 PORTABILITY REQUIREMENTS
In addition to a working ISO-C implementation and of course the
backend-specific APIs, libev relies on a few additional extensions:
=over 4
=item C<void (*)(ev_watcher_type *, int revents)> must have compatible
calling conventions regardless of C<ev_watcher_type *>.
Libev assumes not only that all watcher pointers have the same internal
structure (guaranteed by POSIX but not by ISO C 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 C<ev_watcher *> internally.
=item null pointers and integer zero are represented by 0 bytes
Libev uses C<memset> to initialise structs and arrays to C<0> bytes, and
relies on this setting pointers and integers to null.
=item pointer accesses must be thread-atomic
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.
=item C<sig_atomic_t volatile> must be thread-atomic as well
The type C<sig_atomic_t volatile> (or whatever is defined as
C<EV_ATOMIC_T>) must be atomic with respect to accesses from different
threads. This is not part of the specification for C<sig_atomic_t>, but is
believed to be sufficiently portable.
=item C<sigprocmask> must work in a threaded environment
Libev uses C<sigprocmask> to temporarily block signals. This is not
allowed in a threaded program (C<pthread_sigmask> has to be used). Typical
pthread implementations will either allow C<sigprocmask> in the "main
thread" or will block signals process-wide, both behaviours would
be compatible with libev. Interaction between C<sigprocmask> and
C<pthread_sigmask> could complicate things, however.
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.
=item C<long> must be large enough for common memory allocation sizes
To improve portability and simplify its API, libev uses C<long> internally
instead of C<size_t> 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.
=item C<double> must hold a time value in seconds with enough accuracy
The type C<double> 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 IEEE 754, which is basically all existing ones.
With IEEE 754 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 C<long double> or
something like that, just kidding).
=back
If you know of other additional requirements drop me a note.
=head1 ALGORITHMIC COMPLEXITIES
( run in 0.561 second using v1.01-cache-2.11-cpan-39bf76dae61 )