|
|
|
|
@ -129,7 +129,7 @@
|
|
|
|
|
.\" ========================================================================
|
|
|
|
|
.\"
|
|
|
|
|
.IX Title "EV 1"
|
|
|
|
|
.TH EV 1 "2007-12-19" "perl v5.8.8" "User Contributed Perl Documentation"
|
|
|
|
|
.TH EV 1 "2007-12-21" "perl v5.8.8" "User Contributed Perl Documentation"
|
|
|
|
|
.SH "NAME"
|
|
|
|
|
libev \- a high performance full\-featured event loop written in C
|
|
|
|
|
.SH "SYNOPSIS"
|
|
|
|
|
@ -203,7 +203,7 @@ web page you might find easier to navigate when reading it for the first
|
|
|
|
|
time: <http://cvs.schmorp.de/libev/ev.html>.
|
|
|
|
|
.PP
|
|
|
|
|
Libev is an event loop: you register interest in certain events (such as a
|
|
|
|
|
file descriptor being readable or a timeout occuring), and it will manage
|
|
|
|
|
file descriptor being readable or a timeout occurring), and it will manage
|
|
|
|
|
these event sources and provide your program with events.
|
|
|
|
|
.PP
|
|
|
|
|
To do this, it must take more or less complete control over your process
|
|
|
|
|
@ -461,15 +461,18 @@ lot of inactive fds). It scales similarly to select, i.e. O(total_fds).
|
|
|
|
|
.el .IP "\f(CWEVBACKEND_EPOLL\fR (value 4, Linux)" 4
|
|
|
|
|
.IX Item "EVBACKEND_EPOLL (value 4, Linux)"
|
|
|
|
|
For few fds, this backend is a bit little slower than poll and select,
|
|
|
|
|
but it scales phenomenally better. While poll and select usually scale like
|
|
|
|
|
O(total_fds) where n is the total number of fds (or the highest fd), epoll scales
|
|
|
|
|
either O(1) or O(active_fds).
|
|
|
|
|
.Sp
|
|
|
|
|
While stopping and starting an I/O watcher in the same iteration will
|
|
|
|
|
result in some caching, there is still a syscall per such incident
|
|
|
|
|
but it scales phenomenally better. While poll and select usually scale
|
|
|
|
|
like O(total_fds) where n is the total number of fds (or the highest fd),
|
|
|
|
|
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 rewuiring a syscall per fd change, no fork support and bad
|
|
|
|
|
support for dup:
|
|
|
|
|
.Sp
|
|
|
|
|
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
|
|
|
|
|
(because the fd could point to a different file description now), so its
|
|
|
|
|
best to avoid that. Also, \fIdup()\fRed file descriptors might not work very
|
|
|
|
|
well if you register events for both fds.
|
|
|
|
|
best to avoid that. Also, \f(CW\*(C`dup ()\*(C'\fR'ed file descriptors might not work
|
|
|
|
|
very well if you register events for both fds.
|
|
|
|
|
.Sp
|
|
|
|
|
Please note that epoll sometimes generates spurious notifications, so you
|
|
|
|
|
need to use non-blocking I/O or other means to avoid blocking when no data
|
|
|
|
|
@ -478,17 +481,20 @@ need to use non-blocking I/O or other means to avoid blocking when no data
|
|
|
|
|
.el .IP "\f(CWEVBACKEND_KQUEUE\fR (value 8, most \s-1BSD\s0 clones)" 4
|
|
|
|
|
.IX Item "EVBACKEND_KQUEUE (value 8, most BSD clones)"
|
|
|
|
|
Kqueue deserves special mention, as at the time of this writing, it
|
|
|
|
|
was broken on all BSDs except NetBSD (usually it doesn't work with
|
|
|
|
|
anything but sockets and pipes, except on Darwin, where of course its
|
|
|
|
|
completely useless). For this reason its not being \*(L"autodetected\*(R"
|
|
|
|
|
was broken on \fIall\fR BSDs (usually it doesn't work with anything but
|
|
|
|
|
sockets and pipes, except on Darwin, where of course it's completely
|
|
|
|
|
useless. On NetBSD, it seems to work for all the \s-1FD\s0 types I tested, so it
|
|
|
|
|
is used by default there). For this reason it's not being \*(L"autodetected\*(R"
|
|
|
|
|
unless you explicitly specify it explicitly in the flags (i.e. using
|
|
|
|
|
\&\f(CW\*(C`EVBACKEND_KQUEUE\*(C'\fR).
|
|
|
|
|
\&\f(CW\*(C`EVBACKEND_KQUEUE\*(C'\fR) or libev was compiled on a known-to-be-good (\-enough)
|
|
|
|
|
system like NetBSD.
|
|
|
|
|
.Sp
|
|
|
|
|
It scales in the same way as the epoll backend, but the interface to the
|
|
|
|
|
kernel is more efficient (which says nothing about its actual speed, of
|
|
|
|
|
course). While starting and stopping an I/O watcher does not cause an
|
|
|
|
|
extra syscall as with epoll, it still adds up to four event changes per
|
|
|
|
|
incident, so its best to avoid that.
|
|
|
|
|
kernel is more efficient (which says nothing about its actual speed,
|
|
|
|
|
of course). While stopping, setting and starting an I/O watcher does
|
|
|
|
|
never cause an extra syscall as with epoll, it still adds up to two event
|
|
|
|
|
changes per incident, support for \f(CW\*(C`fork ()\*(C'\fR is very bad and it drops fds
|
|
|
|
|
silently in similarly hard-to-detetc cases.
|
|
|
|
|
.ie n .IP """EVBACKEND_DEVPOLL"" (value 16, Solaris 8)" 4
|
|
|
|
|
.el .IP "\f(CWEVBACKEND_DEVPOLL\fR (value 16, Solaris 8)" 4
|
|
|
|
|
.IX Item "EVBACKEND_DEVPOLL (value 16, Solaris 8)"
|
|
|
|
|
@ -496,10 +502,10 @@ This is not implemented yet (and might never be).
|
|
|
|
|
.ie n .IP """EVBACKEND_PORT"" (value 32, Solaris 10)" 4
|
|
|
|
|
.el .IP "\f(CWEVBACKEND_PORT\fR (value 32, Solaris 10)" 4
|
|
|
|
|
.IX Item "EVBACKEND_PORT (value 32, Solaris 10)"
|
|
|
|
|
This uses the Solaris 10 port mechanism. As with everything on Solaris,
|
|
|
|
|
This uses the Solaris 10 event port mechanism. As with everything on Solaris,
|
|
|
|
|
it's really slow, but it still scales very well (O(active_fds)).
|
|
|
|
|
.Sp
|
|
|
|
|
Please note that solaris ports can result in a lot of spurious
|
|
|
|
|
Please note that solaris event ports can deliver a lot of spurious
|
|
|
|
|
notifications, so you need to use non-blocking I/O or other means to avoid
|
|
|
|
|
blocking when no data (or space) is available.
|
|
|
|
|
.ie n .IP """EVBACKEND_ALL""" 4
|
|
|
|
|
@ -562,7 +568,7 @@ calling this function, or cope with the fact afterwards (which is usually
|
|
|
|
|
the easiest thing, you can just ignore the watchers and/or \f(CW\*(C`free ()\*(C'\fR them
|
|
|
|
|
for example).
|
|
|
|
|
.Sp
|
|
|
|
|
Not that certain global state, such as signal state, will not be freed by
|
|
|
|
|
Note that certain global state, such as signal state, will not be freed by
|
|
|
|
|
this function, and related watchers (such as signal and child watchers)
|
|
|
|
|
would need to be stopped manually.
|
|
|
|
|
.Sp
|
|
|
|
|
@ -620,7 +626,7 @@ Returns the current \*(L"event loop time\*(R", 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 occuring (or more correctly, libev finding out about it).
|
|
|
|
|
event occurring (or more correctly, libev finding out about it).
|
|
|
|
|
.IP "ev_loop (loop, int flags)" 4
|
|
|
|
|
.IX Item "ev_loop (loop, int flags)"
|
|
|
|
|
Finally, this is it, the event handler. This function usually is called
|
|
|
|
|
@ -1082,7 +1088,7 @@ its own, so its quite safe to use).
|
|
|
|
|
\fIThe special problem of disappearing file descriptors\fR
|
|
|
|
|
.IX Subsection "The special problem of disappearing file descriptors"
|
|
|
|
|
.PP
|
|
|
|
|
Some backends (e.g kqueue, epoll) need to be told about closing a file
|
|
|
|
|
Some backends (e.g. kqueue, epoll) need to be told about closing a file
|
|
|
|
|
descriptor (either by calling \f(CW\*(C`close\*(C'\fR explicitly or by any other means,
|
|
|
|
|
such as \f(CW\*(C`dup\*(C'\fR). The reason is that you register interest in some file
|
|
|
|
|
descriptor, but when it goes away, the operating system will silently drop
|
|
|
|
|
@ -1101,6 +1107,30 @@ This is how one would do it normally anyway, the important point is that
|
|
|
|
|
the libev application should not optimise around libev but should leave
|
|
|
|
|
optimisations to libev.
|
|
|
|
|
.PP
|
|
|
|
|
\fIThs special problem of dup'ed file descriptors\fR
|
|
|
|
|
.IX Subsection "Ths special problem of dup'ed file descriptors"
|
|
|
|
|
.PP
|
|
|
|
|
Some backends (e.g. epoll), cannot register events for file descriptors,
|
|
|
|
|
but only events for the underlying file descriptions. That menas when you
|
|
|
|
|
have \f(CW\*(C`dup ()\*(C'\fR'ed file descriptors and register events for them, only one
|
|
|
|
|
file descriptor might actually receive events.
|
|
|
|
|
.PP
|
|
|
|
|
There is no workaorund possible except not registering events
|
|
|
|
|
for potentially \f(CW\*(C`dup ()\*(C'\fR'ed file descriptors or to resort to
|
|
|
|
|
\&\f(CW\*(C`EVBACKEND_SELECT\*(C'\fR or \f(CW\*(C`EVBACKEND_POLL\*(C'\fR.
|
|
|
|
|
.PP
|
|
|
|
|
\fIThe special problem of fork\fR
|
|
|
|
|
.IX Subsection "The special problem of fork"
|
|
|
|
|
.PP
|
|
|
|
|
Some backends (epoll, kqueue) do not support \f(CW\*(C`fork ()\*(C'\fR at all or exhibit
|
|
|
|
|
useless behaviour. Libev fully supports fork, but needs to be told about
|
|
|
|
|
it in the child.
|
|
|
|
|
.PP
|
|
|
|
|
To support fork in your programs, you either have to call
|
|
|
|
|
\&\f(CW\*(C`ev_default_fork ()\*(C'\fR or \f(CW\*(C`ev_loop_fork ()\*(C'\fR after a fork in the child,
|
|
|
|
|
enable \f(CW\*(C`EVFLAG_FORKCHECK\*(C'\fR, or resort to \f(CW\*(C`EVBACKEND_SELECT\*(C'\fR or
|
|
|
|
|
\&\f(CW\*(C`EVBACKEND_POLL\*(C'\fR.
|
|
|
|
|
.PP
|
|
|
|
|
\fIWatcher-Specific Functions\fR
|
|
|
|
|
.IX Subsection "Watcher-Specific Functions"
|
|
|
|
|
.IP "ev_io_init (ev_io *, callback, int fd, int events)" 4
|
|
|
|
|
@ -1908,7 +1938,7 @@ this.
|
|
|
|
|
This is a rather advanced watcher type that lets you embed one event loop
|
|
|
|
|
into another (currently only \f(CW\*(C`ev_io\*(C'\fR 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).
|
|
|
|
|
fashion and must not be used). (See portability notes, below).
|
|
|
|
|
.PP
|
|
|
|
|
There are primarily two reasons you would want that: work around bugs and
|
|
|
|
|
prioritise I/O.
|
|
|
|
|
@ -1978,6 +2008,21 @@ create it, and if that fails, use the normal loop for everything:
|
|
|
|
|
\& else
|
|
|
|
|
\& loop_lo = loop_hi;
|
|
|
|
|
.Ve
|
|
|
|
|
.Sh "Portability notes"
|
|
|
|
|
.IX Subsection "Portability notes"
|
|
|
|
|
Kqueue is nominally embeddable, but this is broken on all BSDs that I
|
|
|
|
|
tried, in various ways. Usually the embedded event loop will simply never
|
|
|
|
|
receive events, sometimes it will only trigger a few times, sometimes in a
|
|
|
|
|
loop. Epoll is also nominally embeddable, but many Linux kernel versions
|
|
|
|
|
will always eport the epoll fd as ready, even when no events are pending.
|
|
|
|
|
.PP
|
|
|
|
|
While libev allows embedding these backends (they are contained in
|
|
|
|
|
\&\f(CW\*(C`ev_embeddable_backends ()\*(C'\fR), take extreme care that it will actually
|
|
|
|
|
work.
|
|
|
|
|
.PP
|
|
|
|
|
When in doubt, create a dynamic event loop forced to use sockets (this
|
|
|
|
|
usually works) and possibly another thread and a pipe or so to report to
|
|
|
|
|
your main event loop.
|
|
|
|
|
.PP
|
|
|
|
|
\fIWatcher-Specific Functions and Data Members\fR
|
|
|
|
|
.IX Subsection "Watcher-Specific Functions and Data Members"
|
|
|
|
|
@ -1997,8 +2042,8 @@ if you do not want thta, you need to temporarily stop the embed watcher).
|
|
|
|
|
Make a single, non-blocking sweep over the embedded loop. This works
|
|
|
|
|
similarly to \f(CW\*(C`ev_loop (embedded_loop, EVLOOP_NONBLOCK)\*(C'\fR, but in the most
|
|
|
|
|
apropriate way for embedded loops.
|
|
|
|
|
.IP "struct ev_loop *loop [read\-only]" 4
|
|
|
|
|
.IX Item "struct ev_loop *loop [read-only]"
|
|
|
|
|
.IP "struct ev_loop *other [read\-only]" 4
|
|
|
|
|
.IX Item "struct ev_loop *other [read-only]"
|
|
|
|
|
The embedded event loop.
|
|
|
|
|
.ie n .Sh """ev_fork"" \- the audacity to resume the event loop after a fork"
|
|
|
|
|
.el .Sh "\f(CWev_fork\fP \- the audacity to resume the event loop after a fork"
|
|
|
|
|
@ -2332,7 +2377,7 @@ applications. Examples of applications that embed it include the Deliantra
|
|
|
|
|
Game Server, the \s-1EV\s0 perl module, the \s-1GNU\s0 Virtual Private Ethernet (gvpe)
|
|
|
|
|
and rxvt\-unicode.
|
|
|
|
|
.PP
|
|
|
|
|
The goal is to enable you to just copy the neecssary files into your
|
|
|
|
|
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).
|
|
|
|
|
@ -2447,7 +2492,7 @@ If defined to be \f(CW1\fR, libev will try to detect the availability of the
|
|
|
|
|
monotonic clock option at both compiletime and runtime. Otherwise no use
|
|
|
|
|
of the monotonic clock option will be attempted. If you enable this, you
|
|
|
|
|
usually have to link against librt or something similar. Enabling it when
|
|
|
|
|
the functionality isn't available is safe, though, althoguh you have
|
|
|
|
|
the functionality isn't available is safe, though, although you have
|
|
|
|
|
to make sure you link against any libraries where the \f(CW\*(C`clock_gettime\*(C'\fR
|
|
|
|
|
function is hiding in (often \fI\-lrt\fR).
|
|
|
|
|
.IP "\s-1EV_USE_REALTIME\s0" 4
|
|
|
|
|
@ -2456,8 +2501,8 @@ If defined to be \f(CW1\fR, libev will try to detect the availability of the
|
|
|
|
|
realtime clock option at compiletime (and assume its availability at
|
|
|
|
|
runtime if successful). Otherwise no use of the realtime clock option will
|
|
|
|
|
be attempted. This effectively replaces \f(CW\*(C`gettimeofday\*(C'\fR by \f(CW\*(C`clock_get
|
|
|
|
|
(CLOCK_REALTIME, ...)\*(C'\fR and will not normally affect correctness. See tzhe note about libraries
|
|
|
|
|
in the description of \f(CW\*(C`EV_USE_MONOTONIC\*(C'\fR, though.
|
|
|
|
|
(CLOCK_REALTIME, ...)\*(C'\fR and will not normally affect correctness. See the
|
|
|
|
|
note about libraries in the description of \f(CW\*(C`EV_USE_MONOTONIC\*(C'\fR, though.
|
|
|
|
|
.IP "\s-1EV_USE_SELECT\s0" 4
|
|
|
|
|
.IX Item "EV_USE_SELECT"
|
|
|
|
|
If undefined or defined to be \f(CW1\fR, libev will compile in support for the
|
|
|
|
|
@ -2627,7 +2672,7 @@ For example, the perl \s-1EV\s0 module uses something like this:
|
|
|
|
|
.PD
|
|
|
|
|
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 \fIev.v\fR header file for
|
|
|
|
|
definition and a statement, respectively. See the \fIev.h\fR header file for
|
|
|
|
|
their default definitions. One possible use for overriding these is to
|
|
|
|
|
avoid the \f(CW\*(C`struct ev_loop *\*(C'\fR as first argument in all cases, or to use
|
|
|
|
|
method calls instead of plain function calls in \*(C+.
|
|
|
|
|
@ -2646,7 +2691,7 @@ 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 inconvinient to avoid this).
|
|
|
|
|
.Sp
|
|
|
|
|
A sed comamnd like this will create wrapper \f(CW\*(C`#define\*(C'\fR's that you need to
|
|
|
|
|
A sed command like this will create wrapper \f(CW\*(C`#define\*(C'\fR's that you need to
|
|
|
|
|
include before including \fIev.h\fR:
|
|
|
|
|
.Sp
|
|
|
|
|
.Vb 1
|
|
|
|
|
|
Marc Alexander Lehmann
15 years ago