#include <ev.h>
-=head1 EXAMPLE PROGRAM
+=head2 EXAMPLE PROGRAM
#include <ev.h>
details of the event, and then hand it over to libev by I<starting> the
watcher.
-=head1 FEATURES
+=head2 FEATURES
Libev supports C<select>, C<poll>, the Linux-specific C<epoll>, the
BSD-specific C<kqueue> and the Solaris-specific event port mechanisms
L<benchmark|http://libev.schmorp.de/bench.html> comparing it to libevent
for example).
-=head1 CONVENTIONS
+=head2 CONVENTIONS
Libev is very configurable. In this manual the default configuration will
be described, which supports multiple event loops. For more info about
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.
-=head1 TIME REPRESENTATION
+=head2 TIME REPRESENTATION
Libev represents time as a single floating point number, representing the
(fractional) number of seconds since the (POSIX) epoch (somewhere near
This is your standard select(2) backend. Not I<completely> standard, as
libev tries to roll its own fd_set with no limits on the number of fds,
but if that fails, expect a fairly low limit on the number of fds when
-using this backend. It doesn't scale too well (O(highest_fd)), but its usually
-the fastest backend for a low number of fds.
+using this backend. It doesn't scale too well (O(highest_fd)), but its
+usually the fastest backend for a low number of (low-numbered :) fds.
+
+To get good performance out of this backend you need a high amount of
+parallelity (most of the file descriptors should be busy). If you are
+writing a server, you should C<accept ()> in a loop to accept as many
+connections as possible during one iteration. You might also want to have
+a look at C<ev_set_io_collect_interval ()> to increase the amount of
+readyness notifications you get per iteration.
=item C<EVBACKEND_POLL> (value 2, poll backend, available everywhere except on windows)
-And this is your standard poll(2) backend. It's more complicated than
-select, but handles sparse fds better and has no artificial limit on the
-number of fds you can use (except it will slow down considerably with a
-lot of inactive fds). It scales similarly to select, i.e. O(total_fds).
+And this is your standard poll(2) backend. It's more complicated
+than select, but handles sparse fds better and has no artificial
+limit on the number of fds you can use (except it will slow down
+considerably with a lot of inactive fds). It scales similarly to select,
+i.e. O(total_fds). See the entry for C<EVBACKEND_SELECT>, above, for
+performance tips.
=item C<EVBACKEND_EPOLL> (value 4, Linux)
epoll scales either O(1) or O(active_fds). The epoll design has a number
of shortcomings, such as silently dropping events in some hard-to-detect
cases and rewiring a syscall per fd change, no fork support and bad
-support for dup:
+support for dup.
While stopping, setting and starting an I/O watcher in the same iteration
will result in some caching, there is still a syscall per such incident
need to use non-blocking I/O or other means to avoid blocking when no data
(or space) is available.
+Best performance from this backend is achieved by not unregistering all
+watchers for a file descriptor until it has been closed, if possible, i.e.
+keep at least one watcher active per fd at all times.
+
+While nominally embeddeble in other event loops, this feature is broken in
+all kernel versions tested so far.
+
=item C<EVBACKEND_KQUEUE> (value 8, most BSD clones)
Kqueue deserves special mention, as at the time of this writing, it
two event changes per incident, support for C<fork ()> is very bad and it
drops fds silently in similarly hard-to-detect cases.
+This backend usually performs well under most conditions.
+
+While nominally embeddable in other event loops, this doesn't work
+everywhere, so you might need to test for this. And since it is broken
+almost everywhere, you should only use it when you have a lot of sockets
+(for which it usually works), by embedding it into another event loop
+(e.g. C<EVBACKEND_SELECT> or C<EVBACKEND_POLL>) and using it only for
+sockets.
+
=item C<EVBACKEND_DEVPOLL> (value 16, Solaris 8)
-This is not implemented yet (and might never be).
+This is not implemented yet (and might never be, unless you send me an
+implementation). According to reports, C</dev/poll> only supports sockets
+and is not embeddable, which would limit the usefulness of this backend
+immensely.
=item C<EVBACKEND_PORT> (value 32, Solaris 10)
notifications, so you need to use non-blocking I/O or other means to avoid
blocking when no data (or space) is available.
+While this backend scales well, it requires one system call per active
+file descriptor per loop iteration. For small and medium numbers of file
+descriptors a "slow" C<EVBACKEND_SELECT> or C<EVBACKEND_POLL> backend
+might perform better.
+
=item C<EVBACKEND_ALL>
Try all backends (even potentially broken ones that wouldn't be tried
with C<EVFLAG_AUTO>). Since this is a mask, you can do stuff such as
C<EVBACKEND_ALL & ~EVBACKEND_KQUEUE>.
+It is definitely not recommended to use this flag.
+
=back
If one or more of these are ored into the flags value, then only these
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 be not affected. Setting this to a non-null bvalue will
+C<ev_timer>) will be not affected. Setting this to a non-null value will
introduce an additional C<ev_sleep ()> call into most loop iterations.
Likewise, by setting a higher I<timeout collect interval> you allow libev
=head3 The special problem of dup'ed file descriptors
Some backends (e.g. epoll), cannot register events for file descriptors,
-but only events for the underlying file descriptions. That menas when you
+but only events for the underlying file descriptions. That means when you
have C<dup ()>'ed file descriptors and register events for them, only one
file descriptor might actually receive events.
-There is no workaorund possible except not registering events
-for potentially C<dup ()>'ed file descriptors or to resort to
+There is no workaround possible except not registering events
+for potentially C<dup ()>'ed file descriptors, or to resort to
C<EVBACKEND_SELECT> or C<EVBACKEND_POLL>.
=head3 The special problem of fork
=item EV_INOTIFY_HASHSIZE
-C<ev_staz> watchers use a small hash table to distribute workload by
+C<ev_stat> watchers use a small hash table to distribute workload by
inotify watch id. The default size is C<16> (or C<1> with C<EV_MINIMAL>),
usually more than enough. If you need to manage thousands of C<ev_stat>
watchers you might want to increase this value (I<must> be a power of
This means that, when you have a watcher that triggers in one hour and
there are 100 watchers that would trigger before that then inserting will
-have to skip those 100 watchers.
+have to skip roughly seven (C<ld 100>) of these watchers.
-=item Changing timer/periodic watchers (by autorepeat, again): O(log skipped_other_timers)
+=item Changing timer/periodic watchers (by autorepeat or calling again): O(log skipped_other_timers)
-That means that for changing a timer costs less than removing/adding them
+That means that changing a timer costs less than removing/adding them
as only the relative motion in the event queue has to be paid for.
=item Starting io/check/prepare/idle/signal/child watchers: O(1)
These just add the watcher into an array or at the head of a list.
+
=item Stopping check/prepare/idle watchers: O(1)
=item Stopping an io/signal/child watcher: O(number_of_watchers_for_this_(fd/signal/pid % EV_PID_HASHSIZE))
correct watcher to remove. The lists are usually short (you don't usually
have many watchers waiting for the same fd or signal).
-=item Finding the next timer per loop iteration: O(1)
+=item Finding the next timer in each loop iteration: O(1)
+
+By virtue of using a binary heap, the next timer is always found at the
+beginning of 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).
+libev to recalculate its status (and possibly tell the kernel, depending
+on backend and wether C<ev_io_set> was used).
-=item Activating one watcher: O(1)
+=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.
+linearly search all the priorities, but starting/stopping and activating
+watchers becomes O(1) w.r.t. prioritiy handling.
=back