mirrors
/
libev
mirror of /home/gitosis/repositories/libev.git
1
0
Fork 0
Code Releases Activity

*** empty log message ***

This commit is contained in:
Marc Alexander Lehmann 2013-10-29 12:13:37 +00:00
parent af7db5f5d8
commit f1a1cebaf2
4 changed files with 109 additions and 99 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
Changes
View File

@ -16,6 +16,8 @@ TODO: document portbaility requirements for atomic pointer access
TODO: glibc >=2.17 do not need -lrt for clock_xxx
- mark event pipe fd as cloexec after a fork (analyzed by Sami Farin).
- (ecb) support m68k, m88k and sh (patch by Miod Vallat).
- use a reasonable fallback for EV_NSIG instead of erroring out
when we can't detect the signal set size.
4.15 Fri Mar 1 12:04:50 CET 2013
- destroying a non-default loop would stop the global waitpid

199
ev.3
View File

@ -1,4 +1,4 @@
.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.20)
.\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28)
.\"
.\" Standard preamble:
.\" ========================================================================
@ -38,6 +38,8 @@
. ds PI \(*p
. ds L" ``
. ds R" ''
. ds C`
. ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
@ -48,17 +50,24 @@
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD. Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.ie \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
. nr % 0
. rr F
.\}
.el \{\
. de IX
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
. if \nF \{
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear. Run. Save yourself. No user-serviceable parts.
@ -124,7 +133,7 @@
.\" ========================================================================
.\"
.IX Title "LIBEV 3"
.TH LIBEV 3 "2013-06-07" "libev-4.15" "libev - high performance full featured event loop"
.TH LIBEV 3 "2013-10-29" "libev-4.15" "libev - high performance full featured event loop"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
@ -136,7 +145,7 @@ libev \- a high performance full\-featured event loop written in C
.Vb 1
\& #include <ev.h>
.Ve
.SS "\s-1EXAMPLE\s0 \s-1PROGRAM\s0"
.SS "\s-1EXAMPLE PROGRAM\s0"
.IX Subsection "EXAMPLE PROGRAM"
.Vb 2
\& // a single header file is required
@ -214,9 +223,9 @@ throughout this document.
.IX Header "WHAT TO READ WHEN IN A HURRY"
This manual tries to be very detailed, but unfortunately, this also makes
it very long. If you just want to know the basics of libev, I suggest
reading \*(L"\s-1ANATOMY\s0 \s-1OF\s0 A \s-1WATCHER\s0\*(R", then the \*(L"\s-1EXAMPLE\s0 \s-1PROGRAM\s0\*(R" above and
look up the missing functions in \*(L"\s-1GLOBAL\s0 \s-1FUNCTIONS\s0\*(R" and the \f(CW\*(C`ev_io\*(C'\fR and
\&\f(CW\*(C`ev_timer\*(C'\fR sections in \*(L"\s-1WATCHER\s0 \s-1TYPES\s0\*(R".
reading \*(L"\s-1ANATOMY OF A WATCHER\*(R"\s0, then the \*(L"\s-1EXAMPLE PROGRAM\*(R"\s0 above and
look up the missing functions in \*(L"\s-1GLOBAL FUNCTIONS\*(R"\s0 and the \f(CW\*(C`ev_io\*(C'\fR and
\&\f(CW\*(C`ev_timer\*(C'\fR sections in \*(L"\s-1WATCHER TYPES\*(R"\s0.
.SH "ABOUT LIBEV"
.IX Header "ABOUT LIBEV"
Libev is an event loop: you register interest in certain events (such as a
@ -257,7 +266,7 @@ more info about various configuration options please have a look at
for multiple event loops, then all functions taking an initial argument of
name \f(CW\*(C`loop\*(C'\fR (which is always of type \f(CW\*(C`struct ev_loop *\*(C'\fR) will not have
this argument.
.SS "\s-1TIME\s0 \s-1REPRESENTATION\s0"
.SS "\s-1TIME REPRESENTATION\s0"
.IX Subsection "TIME REPRESENTATION"
Libev represents time as a single floating point number, representing
the (fractional) number of seconds since the (\s-1POSIX\s0) epoch (in practice
@ -576,7 +585,7 @@ It's also required by \s-1POSIX\s0 in a threaded program, as libev calls
This flag's behaviour will become the default in future versions of libev.
.ie n .IP """EVBACKEND_SELECT"" (value 1, portable select backend)" 4
.el .IP "\f(CWEVBACKEND_SELECT\fR (value 1, portable select backend)" 4
.IX Item "EVBACKEND_SELECT (value 1, portable select backend)"
.IX Item "EVBACKEND_SELECT (value 1, portable select backend)"
This is your standard \fIselect\fR\|(2) backend. Not \fIcompletely\fR 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
@ -595,7 +604,7 @@ This backend maps \f(CW\*(C`EV_READ\*(C'\fR to the \f(CW\*(C`readfds\*(C'\fR set
\&\f(CW\*(C`exceptfds\*(C'\fR set on that platform).
.ie n .IP """EVBACKEND_POLL"" (value 2, poll backend, available everywhere except on windows)" 4
.el .IP "\f(CWEVBACKEND_POLL\fR (value 2, poll backend, available everywhere except on windows)" 4
.IX Item "EVBACKEND_POLL (value 2, poll backend, available everywhere except on windows)"
.IX Item "EVBACKEND_POLL (value 2, poll backend, available everywhere except on windows)"
And this is your standard \fIpoll\fR\|(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
@ -607,7 +616,7 @@ This backend maps \f(CW\*(C`EV_READ\*(C'\fR to \f(CW\*(C`POLLIN | POLLERR | POLL
\&\f(CW\*(C`EV_WRITE\*(C'\fR to \f(CW\*(C`POLLOUT | POLLERR | POLLHUP\*(C'\fR.
.ie n .IP """EVBACKEND_EPOLL"" (value 4, Linux)" 4
.el .IP "\f(CWEVBACKEND_EPOLL\fR (value 4, Linux)" 4
.IX Item "EVBACKEND_EPOLL (value 4, Linux)"
.IX Item "EVBACKEND_EPOLL (value 4, Linux)"
Use the linux-specific \fIepoll\fR\|(7) interface (for both pre\- and post\-2.6.9
kernels).
.Sp
@ -670,7 +679,7 @@ This backend maps \f(CW\*(C`EV_READ\*(C'\fR and \f(CW\*(C`EV_WRITE\*(C'\fR in th
\&\f(CW\*(C`EVBACKEND_POLL\*(C'\fR.
.ie n .IP """EVBACKEND_KQUEUE"" (value 8, most \s-1BSD\s0 clones)" 4
.el .IP "\f(CWEVBACKEND_KQUEUE\fR (value 8, most \s-1BSD\s0 clones)" 4
.IX Item "EVBACKEND_KQUEUE (value 8, most BSD clones)"
.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 reliably
with anything but sockets and pipes, except on Darwin, where of course
@ -700,7 +709,7 @@ 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. \f(CW\*(C`EVBACKEND_SELECT\*(C'\fR or \f(CW\*(C`EVBACKEND_POLL\*(C'\fR (but \f(CW\*(C`poll\*(C'\fR is of course
also broken on \s-1OS\s0 X)) and, did I mention it, using it only for sockets.
also broken on \s-1OS X\s0)) and, did I mention it, using it only for sockets.
.Sp
This backend maps \f(CW\*(C`EV_READ\*(C'\fR into an \f(CW\*(C`EVFILT_READ\*(C'\fR kevent with
\&\f(CW\*(C`NOTE_EOF\*(C'\fR, and \f(CW\*(C`EV_WRITE\*(C'\fR into an \f(CW\*(C`EVFILT_WRITE\*(C'\fR kevent with
@ -714,7 +723,7 @@ and is not embeddable, which would limit the usefulness of this backend
immensely.
.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)"
.IX Item "EVBACKEND_PORT (value 32, Solaris 10)"
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
@ -809,7 +818,7 @@ name, you can call it anytime, but it makes most sense after forking, in
the child process. You \fImust\fR call it (or use \f(CW\*(C`EVFLAG_FORKCHECK\*(C'\fR) in the
child before resuming or calling \f(CW\*(C`ev_run\*(C'\fR.
.Sp
Again, you \fIhave\fR to call it on \fIany\fR loop that you want to re-use after
Again, you \fIhave\fR to call it on \fIany\fR loop that you want to re-use after
a fork, \fIeven if you do not plan to use the loop in the parent\fR. This is
because some kernel interfaces *cough* \fIkqueue\fR *cough* do funny things
during fork.
@ -1356,7 +1365,7 @@ callbacks is well-written it can just attempt the operation and cope with
the error from \fIread()\fR or \fIwrite()\fR. This will not work in multi-threaded
programs, though, as the fd could already be closed and reused for another
thing, so beware.
.SS "\s-1GENERIC\s0 \s-1WATCHER\s0 \s-1FUNCTIONS\s0"
.SS "\s-1GENERIC WATCHER FUNCTIONS\s0"
.IX Subsection "GENERIC WATCHER FUNCTIONS"
.ie n .IP """ev_init"" (ev_TYPE *watcher, callback)" 4
.el .IP "\f(CWev_init\fR (ev_TYPE *watcher, callback)" 4
@ -1474,7 +1483,7 @@ or might not have been clamped to the valid range.
The default priority used by watchers when no priority has been set is
always \f(CW0\fR, which is supposed to not be too high and not be too low :).
.Sp
See \*(L"\s-1WATCHER\s0 \s-1PRIORITY\s0 \s-1MODELS\s0\*(R", below, for a more thorough treatment of
See \*(L"\s-1WATCHER PRIORITY MODELS\*(R"\s0, below, for a more thorough treatment of
priorities.
.IP "ev_invoke (loop, ev_TYPE *watcher, int revents)" 4
.IX Item "ev_invoke (loop, ev_TYPE *watcher, int revents)"
@ -1504,9 +1513,9 @@ not started in the first place.
See also \f(CW\*(C`ev_feed_fd_event\*(C'\fR and \f(CW\*(C`ev_feed_signal_event\*(C'\fR for related
functions that do not need a watcher.
.PP
See also the \*(L"\s-1ASSOCIATING\s0 \s-1CUSTOM\s0 \s-1DATA\s0 \s-1WITH\s0 A \s-1WATCHER\s0\*(R" and \*(L"\s-1BUILDING\s0 \s-1YOUR\s0
\&\s-1OWN\s0 \s-1COMPOSITE\s0 \s-1WATCHERS\s0\*(R" idioms.
.SS "\s-1WATCHER\s0 \s-1STATES\s0"
See also the \*(L"\s-1ASSOCIATING CUSTOM DATA WITH A WATCHER\*(R"\s0 and \*(L"\s-1BUILDING YOUR
OWN COMPOSITE WATCHERS\*(R"\s0 idioms.
.SS "\s-1WATCHER STATES\s0"
.IX Subsection "WATCHER STATES"
There are various watcher states mentioned throughout this manual \-
active, pending and so on. In this section these states and the rules to
@ -1559,7 +1568,7 @@ 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 \f(CW\*(C`ev_TYPE_init\*(C'\fR
it again).
.SS "\s-1WATCHER\s0 \s-1PRIORITY\s0 \s-1MODELS\s0"
.SS "\s-1WATCHER PRIORITY MODELS\s0"
.IX Subsection "WATCHER PRIORITY MODELS"
Many event loops support \fIwatcher priorities\fR, which are usually small
integers that influence the ordering of event callback invocation
@ -1767,7 +1776,7 @@ wish to read \- you would first have to request some data.
Since files are typically not-so-well supported by advanced notification
mechanism, libev tries hard to emulate \s-1POSIX\s0 behaviour with respect
to files, even though you should not use it. The reason for this is
convenience: sometimes you want to watch \s-1STDIN\s0 or \s-1STDOUT\s0, which is
convenience: sometimes you want to watch \s-1STDIN\s0 or \s-1STDOUT,\s0 which is
usually a tty, often a pipe, but also sometimes files or special devices
(for example, \f(CW\*(C`epoll\*(C'\fR on Linux works with \fI/dev/random\fR but not with
\&\fI/dev/urandom\fR), and even though the file might better be served with
@ -1775,7 +1784,7 @@ asynchronous I/O instead of with non-blocking I/O, it is still useful when
it \*(L"just works\*(R" instead of freezing.
.PP
So avoid file descriptors pointing to files when you know it (e.g. use
libeio), but use them when it is convenient, e.g. for \s-1STDIN/STDOUT\s0, or
libeio), but use them when it is convenient, e.g. for \s-1STDIN/STDOUT,\s0 or
when you rarely read from a file instead of from a socket, and want to
reuse the same code path.
.PP
@ -1795,17 +1804,17 @@ To support fork in your child processes, you have to call \f(CW\*(C`ev_loop_fork
.PP
While not really specific to libev, it is easy to forget about \f(CW\*(C`SIGPIPE\*(C'\fR:
when writing to a pipe whose other end has been closed, your program gets
sent a \s-1SIGPIPE\s0, which, by default, aborts your program. For most programs
sent a \s-1SIGPIPE,\s0 which, by default, aborts your program. For most programs
this is sensible behaviour, for daemons, this is usually undesirable.
.PP
So when you encounter spurious, unexplained daemon exits, make sure you
ignore \s-1SIGPIPE\s0 (and maybe make sure you log the exit status of your daemon
ignore \s-1SIGPIPE \s0(and maybe make sure you log the exit status of your daemon
somewhere, as that would have given you a big clue).
.PP
\fIThe special problem of \fIaccept()\fIing when you can't\fR
.IX Subsection "The special problem of accept()ing when you can't"
.PP
Many implementations of the \s-1POSIX\s0 \f(CW\*(C`accept\*(C'\fR function (for example,
Many implementations of the \s-1POSIX \s0\f(CW\*(C`accept\*(C'\fR function (for example,
found in post\-2004 Linux) have the peculiar behaviour of not removing a
connection from the pending queue in all error cases.
.PP
@ -2420,7 +2429,7 @@ ignored. Instead, each time the periodic watcher gets scheduled, the
reschedule callback will be called with the watcher as first, and the
current time as second argument.
.Sp
\&\s-1NOTE:\s0 \fIThis callback \s-1MUST\s0 \s-1NOT\s0 stop or destroy any periodic watcher, ever,
\&\s-1NOTE: \s0\fIThis callback \s-1MUST NOT\s0 stop or destroy any periodic watcher, ever,
or make \s-1ANY\s0 other event loop modifications whatsoever, unless explicitly
allowed by documentation here\fR.
.Sp
@ -2444,7 +2453,7 @@ It must return the next time to trigger, based on the passed time value
will usually be called just before the callback will be triggered, but
might be called at other times, too.
.Sp
\&\s-1NOTE:\s0 \fIThis callback must always return a time that is higher than or
\&\s-1NOTE: \s0\fIThis callback must always return a time that is higher than or
equal to the passed \f(CI\*(C`now\*(C'\fI value\fR.
.Sp
This can be used to create very complex timers, such as a timer that
@ -2579,7 +2588,7 @@ to install a fork handler with \f(CW\*(C`pthread_atfork\*(C'\fR that resets it.
catch fork calls done by libraries (such as the libc) as well.
.PP
In current versions of libev, the signal will not be blocked indefinitely
unless you use the \f(CW\*(C`signalfd\*(C'\fR \s-1API\s0 (\f(CW\*(C`EV_SIGNALFD\*(C'\fR). While this reduces
unless you use the \f(CW\*(C`signalfd\*(C'\fR \s-1API \s0(\f(CW\*(C`EV_SIGNALFD\*(C'\fR). While this reduces
the window of opportunity for problems, it will not go away, as libev
\&\fIhas\fR to modify the signal mask, at least temporarily.
.PP
@ -2619,7 +2628,7 @@ The signal the watcher watches out for.
\fIExamples\fR
.IX Subsection "Examples"
.PP
Example: Try to exit cleanly on \s-1SIGINT\s0.
Example: Try to exit cleanly on \s-1SIGINT.\s0
.PP
.Vb 5
\& static void
@ -2786,7 +2795,7 @@ support disabled by default, you get the 32 bit version of the stat
structure. When using the library from programs that change the \s-1ABI\s0 to
use 64 bit file offsets the programs will fail. In that case you have to
compile libev with the same flags to get binary compatibility. This is
obviously the case with any flags that change the \s-1ABI\s0, but the problem is
obviously the case with any flags that change the \s-1ABI,\s0 but the problem is
most noticeably displayed with ev_stat and large file support.
.PP
The solution for this is to lobby your distribution maker to make large
@ -3227,7 +3236,7 @@ callbacks, and only destroy/create the watchers in the prepare watcher.
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 \s-1EV\s0. The \f(CW\*(C`Glib::EV\*(C'\fR module uses
main loop is now no longer controllable by \s-1EV.\s0 The \f(CW\*(C`Glib::EV\*(C'\fR module uses
this approach, effectively embedding \s-1EV\s0 as a client into the horrible
libglib event loop.
.PP
@ -3654,7 +3663,7 @@ value passed to \f(CW\*(C`ev_once\*(C'\fR. Note that it is possible to receive \
a timeout and an io event at the same time \- you probably should give io
events precedence.
.Sp
Example: wait up to ten seconds for data to appear on \s-1STDIN_FILENO\s0.
Example: wait up to ten seconds for data to appear on \s-1STDIN_FILENO.\s0
.Sp
.Vb 7
\& static void stdin_ready (int revents, void *arg)
@ -3680,7 +3689,7 @@ which is async-safe.
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.
.SS "\s-1ASSOCIATING\s0 \s-1CUSTOM\s0 \s-1DATA\s0 \s-1WITH\s0 A \s-1WATCHER\s0"
.SS "\s-1ASSOCIATING CUSTOM DATA WITH A WATCHER\s0"
.IX Subsection "ASSOCIATING CUSTOM DATA WITH A WATCHER"
Each watcher has, by default, a \f(CW\*(C`void *data\*(C'\fR member that you can read
or modify at any time: libev will completely ignore it. This can be used
@ -3716,7 +3725,7 @@ can cast it back to your own type:
.PP
More interesting and less C\-conformant ways of casting your callback
function type instead have been omitted.
.SS "\s-1BUILDING\s0 \s-1YOUR\s0 \s-1OWN\s0 \s-1COMPOSITE\s0 \s-1WATCHERS\s0"
.SS "\s-1BUILDING YOUR OWN COMPOSITE WATCHERS\s0"
.IX Subsection "BUILDING YOUR OWN COMPOSITE WATCHERS"
Another common scenario is to use some data structure with multiple
embedded watchers, in effect creating your own watcher that combines
@ -3754,7 +3763,7 @@ real programmers):
\& (((char *)w) \- offsetof (struct my_biggy, t2));
\& }
.Ve
.SS "\s-1AVOIDING\s0 \s-1FINISHING\s0 \s-1BEFORE\s0 \s-1RETURNING\s0"
.SS "\s-1AVOIDING FINISHING BEFORE RETURNING\s0"
.IX Subsection "AVOIDING FINISHING BEFORE RETURNING"
Often you have structures like this in event-based programs:
.PP
@ -3797,7 +3806,7 @@ pushing it into the pending queue:
.PP
This way, \f(CW\*(C`start_new_request\*(C'\fR can safely return before the callback is
invoked, while not delaying callback invocation too much.
.SS "\s-1MODEL/NESTED\s0 \s-1EVENT\s0 \s-1LOOP\s0 \s-1INVOCATIONS\s0 \s-1AND\s0 \s-1EXIT\s0 \s-1CONDITIONS\s0"
.SS "\s-1MODEL/NESTED EVENT LOOP INVOCATIONS AND EXIT CONDITIONS\s0"
.IX Subsection "MODEL/NESTED EVENT LOOP INVOCATIONS AND EXIT CONDITIONS"
Often (especially in \s-1GUI\s0 toolkits) there are places where you have
\&\fImodal\fR interaction, which is most easily implemented by recursively
@ -3839,7 +3848,7 @@ To exit from any of these loops, just set the corresponding exit variable:
\& // exit both
\& exit_main_loop = exit_nested_loop = 1;
.Ve
.SS "\s-1THREAD\s0 \s-1LOCKING\s0 \s-1EXAMPLE\s0"
.SS "\s-1THREAD LOCKING EXAMPLE\s0"
.IX Subsection "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
@ -3990,7 +3999,7 @@ Note that sending the \f(CW\*(C`ev_async\*(C'\fR watcher is required because oth
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.
.SS "\s-1THREADS\s0, \s-1COROUTINES\s0, \s-1CONTINUATIONS\s0, \s-1QUEUES\s0... \s-1INSTEAD\s0 \s-1OF\s0 \s-1CALLBACKS\s0"
.SS "\s-1THREADS, COROUTINES, CONTINUATIONS, QUEUES... INSTEAD OF CALLBACKS\s0"
.IX Subsection "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
@ -4036,7 +4045,7 @@ 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.
.PP
To embed libev, see \*(L"\s-1EMBEDDING\s0\*(R", but in short, it's easiest to create two
To embed libev, see \*(L"\s-1EMBEDDING\*(R"\s0, but in short, it's easiest to create two
files, \fImy_ev.h\fR and \fImy_ev.c\fR that include the respective libev files:
.PP
.Vb 4
@ -4341,7 +4350,7 @@ to \f(CW\*(C`libadns\*(C'\fR (\f(CW\*(C`EV::ADNS\*(C'\fR, but \f(CW\*(C`AnyEvent
\&\f(CW\*(C`Net::SNMP\*(C'\fR (\f(CW\*(C`Net::SNMP::EV\*(C'\fR) and the \f(CW\*(C`libglib\*(C'\fR event core (\f(CW\*(C`Glib::EV\*(C'\fR
and \f(CW\*(C`EV::Glib\*(C'\fR).
.Sp
It can be found and installed via \s-1CPAN\s0, its homepage is at
It can be found and installed via \s-1CPAN,\s0 its homepage is at
<http://software.schmorp.de/pkg/EV>.
.IP "Python" 4
.IX Item "Python"
@ -4359,7 +4368,7 @@ makes rev work even on mingw.
.IP "Haskell" 4
.IX Item "Haskell"
A haskell binding to libev is available at
http://hackage.haskell.org/cgi\-bin/hackage\-scripts/package/hlibev <http://hackage.haskell.org/cgi-bin/hackage-scripts/package/hlibev>.
<http://hackage.haskell.org/cgi\-bin/hackage\-scripts/package/hlibev>.
.IP "D" 4
.IX Item "D"
Leandro Lucarella has written a D language binding (\fIev.d\fR) for libev, to
@ -4367,12 +4376,12 @@ be found at <http://www.llucax.com.ar/proj/ev.d/index.html>.
.IP "Ocaml" 4
.IX Item "Ocaml"
Erkki Seppala has written Ocaml bindings for libev, to be found at
http://modeemi.cs.tut.fi/~flux/software/ocaml\-ev/ <http://modeemi.cs.tut.fi/~flux/software/ocaml-ev/>.
<http://modeemi.cs.tut.fi/~flux/software/ocaml\-ev/>.
.IP "Lua" 4
.IX Item "Lua"
Brian Maher has written a partial interface to libev for lua (at the
time of this writing, only \f(CW\*(C`ev_io\*(C'\fR and \f(CW\*(C`ev_timer\*(C'\fR), to be found at
http://github.com/brimworks/lua\-ev <http://github.com/brimworks/lua-ev>.
<http://github.com/brimworks/lua\-ev>.
.IP "Javascript" 4
.IX Item "Javascript"
Node.js (<http://nodejs.org>) uses libev as the underlying event library.
@ -4471,7 +4480,7 @@ libev somewhere in your source tree).
Depending on what features you need you need to include one or more sets of files
in your application.
.PP
\fI\s-1CORE\s0 \s-1EVENT\s0 \s-1LOOP\s0\fR
\fI\s-1CORE EVENT LOOP\s0\fR
.IX Subsection "CORE EVENT LOOP"
.PP
To include only the libev core (all the \f(CW\*(C`ev_*\*(C'\fR functions), with manual
@ -4484,7 +4493,7 @@ configuration (no autoconf):
.PP
This will automatically include \fIev.h\fR, too, and should be done in a
single C source file only to provide the function implementations. To use
it, do the same for \fIev.h\fR in all files wishing to use this \s-1API\s0 (best
it, do the same for \fIev.h\fR in all files wishing to use this \s-1API \s0(best
done by writing a wrapper around \fIev.h\fR that you can include instead and
where you can put other configuration options):
.PP
@ -4518,10 +4527,10 @@ in your include path (e.g. in libev/ when using \-Ilibev):
\&\fIev.c\fR includes the backend files directly when enabled, so you only need
to compile this single file.
.PP
\fI\s-1LIBEVENT\s0 \s-1COMPATIBILITY\s0 \s-1API\s0\fR
\fI\s-1LIBEVENT COMPATIBILITY API\s0\fR
.IX Subsection "LIBEVENT COMPATIBILITY API"
.PP
To include the libevent compatibility \s-1API\s0, also include:
To include the libevent compatibility \s-1API,\s0 also include:
.PP
.Vb 1
\& #include "event.c"
@ -4533,7 +4542,7 @@ in the file including \fIev.c\fR, and:
\& #include "event.h"
.Ve
.PP
in the files that want to use the libevent \s-1API\s0. This also includes \fIev.h\fR.
in the files that want to use the libevent \s-1API.\s0 This also includes \fIev.h\fR.
.PP
You need the following additional files for this:
.PP
@ -4542,7 +4551,7 @@ You need the following additional files for this:
\& event.c
.Ve
.PP
\fI\s-1AUTOCONF\s0 \s-1SUPPORT\s0\fR
\fI\s-1AUTOCONF SUPPORT\s0\fR
.IX Subsection "AUTOCONF SUPPORT"
.PP
Instead of using \f(CW\*(C`EV_STANDALONE=1\*(C'\fR and providing your configuration in
@ -4555,19 +4564,19 @@ For this of course you need the m4 file:
.Vb 1
\& libev.m4
.Ve
.SS "\s-1PREPROCESSOR\s0 \s-1SYMBOLS/MACROS\s0"
.SS "\s-1PREPROCESSOR SYMBOLS/MACROS\s0"
.IX Subsection "PREPROCESSOR SYMBOLS/MACROS"
Libev can be configured via a variety of preprocessor symbols you have to
define before including (or compiling) any of its files. The default in
the absence of autoconf is documented for every option.
.PP
Symbols marked with \*(L"(h)\*(R" do not change the \s-1ABI\s0, and can have different
Symbols marked with \*(L"(h)\*(R" do not change the \s-1ABI,\s0 and can have different
values when compiling libev vs. including \fIev.h\fR, so it is permissible
to redefine them before including \fIev.h\fR without breaking compatibility
to a compiled library. All other symbols change the \s-1ABI\s0, which means all
to a compiled library. All other symbols change the \s-1ABI,\s0 which means all
users of libev and the libev code itself must be compiled with compatible
settings.
.IP "\s-1EV_COMPAT3\s0 (h)" 4
.IP "\s-1EV_COMPAT3 \s0(h)" 4
.IX Item "EV_COMPAT3 (h)"
Backwards compatibility is a major concern for libev. This is why this
release of libev comes with wrappers for the functions and symbols that
@ -4582,7 +4591,7 @@ typedef in that case.
In some future version, the default for \f(CW\*(C`EV_COMPAT3\*(C'\fR will become \f(CW0\fR,
and in some even more future version the compatibility code will be
removed completely.
.IP "\s-1EV_STANDALONE\s0 (h)" 4
.IP "\s-1EV_STANDALONE \s0(h)" 4
.IX Item "EV_STANDALONE (h)"
Must always be \f(CW1\fR if you do not use autoconf configuration, which
keeps libev from including \fIconfig.h\fR, and it also defines dummy
@ -4750,21 +4759,21 @@ watchers.
.Sp
In the absence of this define, libev will use \f(CW\*(C`sig_atomic_t volatile\*(C'\fR
(from \fIsignal.h\fR), which is usually good enough on most platforms.
.IP "\s-1EV_H\s0 (h)" 4
.IP "\s-1EV_H \s0(h)" 4
.IX Item "EV_H (h)"
The name of the \fIev.h\fR header file used to include it. The default if
undefined is \f(CW"ev.h"\fR in \fIevent.h\fR, \fIev.c\fR and \fIev++.h\fR. This can be
used to virtually rename the \fIev.h\fR header file in case of conflicts.
.IP "\s-1EV_CONFIG_H\s0 (h)" 4
.IP "\s-1EV_CONFIG_H \s0(h)" 4
.IX Item "EV_CONFIG_H (h)"
If \f(CW\*(C`EV_STANDALONE\*(C'\fR isn't \f(CW1\fR, this variable can be used to override
\&\fIev.c\fR's idea of where to find the \fIconfig.h\fR file, similarly to
\&\f(CW\*(C`EV_H\*(C'\fR, above.
.IP "\s-1EV_EVENT_H\s0 (h)" 4
.IP "\s-1EV_EVENT_H \s0(h)" 4
.IX Item "EV_EVENT_H (h)"
Similarly to \f(CW\*(C`EV_H\*(C'\fR, this macro can be used to override \fIevent.c\fR's idea
of how the \fIevent.h\fR header can be found, the default is \f(CW"event.h"\fR.
.IP "\s-1EV_PROTOTYPES\s0 (h)" 4
.IP "\s-1EV_PROTOTYPES \s0(h)" 4
.IX Item "EV_PROTOTYPES (h)"
If defined to be \f(CW0\fR, then \fIev.h\fR will not define any function
prototypes, but still define all the structs and other symbols. This is
@ -4798,8 +4807,8 @@ and time, so using the defaults of five priorities (\-2 .. +2) is usually
fine.
.Sp
If your embedding application does not need any priorities, defining these
both to \f(CW0\fR will save some memory and \s-1CPU\s0.
.IP "\s-1EV_PERIODIC_ENABLE\s0, \s-1EV_IDLE_ENABLE\s0, \s-1EV_EMBED_ENABLE\s0, \s-1EV_STAT_ENABLE\s0, \s-1EV_PREPARE_ENABLE\s0, \s-1EV_CHECK_ENABLE\s0, \s-1EV_FORK_ENABLE\s0, \s-1EV_SIGNAL_ENABLE\s0, \s-1EV_ASYNC_ENABLE\s0, \s-1EV_CHILD_ENABLE\s0." 4
both to \f(CW0\fR will save some memory and \s-1CPU.\s0
.IP "\s-1EV_PERIODIC_ENABLE, EV_IDLE_ENABLE, EV_EMBED_ENABLE, EV_STAT_ENABLE, EV_PREPARE_ENABLE, EV_CHECK_ENABLE, EV_FORK_ENABLE, EV_SIGNAL_ENABLE, EV_ASYNC_ENABLE, EV_CHILD_ENABLE.\s0" 4
.IX Item "EV_PERIODIC_ENABLE, EV_IDLE_ENABLE, EV_EMBED_ENABLE, EV_STAT_ENABLE, EV_PREPARE_ENABLE, EV_CHECK_ENABLE, EV_FORK_ENABLE, EV_SIGNAL_ENABLE, EV_ASYNC_ENABLE, EV_CHILD_ENABLE."
If undefined or defined to be \f(CW1\fR (and the platform supports it), then
the respective watcher type is supported. If defined to be \f(CW0\fR, then it
@ -4983,10 +4992,10 @@ For example, the perl \s-1EV\s0 module uses something like this:
\& SV *self; /* contains this struct */ \e
\& SV *cb_sv, *fh /* note no trailing ";" */
.Ve
.IP "\s-1EV_CB_DECLARE\s0 (type)" 4
.IP "\s-1EV_CB_DECLARE \s0(type)" 4
.IX Item "EV_CB_DECLARE (type)"
.PD 0
.IP "\s-1EV_CB_INVOKE\s0 (watcher, revents)" 4
.IP "\s-1EV_CB_INVOKE \s0(watcher, revents)" 4
.IX Item "EV_CB_INVOKE (watcher, revents)"
.IP "ev_set_cb (ev, cb)" 4
.IX Item "ev_set_cb (ev, cb)"
@ -4997,9 +5006,9 @@ 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+.
.SS "\s-1EXPORTED\s0 \s-1API\s0 \s-1SYMBOLS\s0"
.SS "\s-1EXPORTED API SYMBOLS\s0"
.IX Subsection "EXPORTED API SYMBOLS"
If you need to re-export the \s-1API\s0 (e.g. via a \s-1DLL\s0) and you need a list of
If you need to re-export the \s-1API \s0(e.g. via a \s-1DLL\s0) and you need a list of
exported symbols, you can use the provided \fISymbol.*\fR files which list
all public symbols, one per line:
.PP
@ -5061,7 +5070,7 @@ And a \fIev_cpp.C\fR implementation file that contains libev proper and is compi
.Ve
.SH "INTERACTION WITH OTHER PROGRAMS, LIBRARIES OR THE ENVIRONMENT"
.IX Header "INTERACTION WITH OTHER PROGRAMS, LIBRARIES OR THE ENVIRONMENT"
.SS "\s-1THREADS\s0 \s-1AND\s0 \s-1COROUTINES\s0"
.SS "\s-1THREADS AND COROUTINES\s0"
.IX Subsection "THREADS AND COROUTINES"
\fI\s-1THREADS\s0\fR
.IX Subsection "THREADS"
@ -5117,7 +5126,7 @@ work in the default loop by registering the signal watcher with the
default loop and triggering an \f(CW\*(C`ev_async\*(C'\fR watcher from the default loop
watcher callback into the event loop interested in the signal.
.PP
See also \*(L"\s-1THREAD\s0 \s-1LOCKING\s0 \s-1EXAMPLE\s0\*(R".
See also \*(L"\s-1THREAD LOCKING EXAMPLE\*(R"\s0.
.PP
\fI\s-1COROUTINES\s0\fR
.IX Subsection "COROUTINES"
@ -5132,7 +5141,7 @@ that you must not do this from \f(CW\*(C`ev_periodic\*(C'\fR reschedule callback
Care has been taken to ensure that libev does not keep local state inside
\&\f(CW\*(C`ev_run\*(C'\fR, and other calls do not usually allow for coroutine switches as
they do not call any callbacks.
.SS "\s-1COMPILER\s0 \s-1WARNINGS\s0"
.SS "\s-1COMPILER WARNINGS\s0"
.IX Subsection "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
@ -5194,7 +5203,7 @@ If you need, for some reason, empty reports from valgrind for your project
I suggest using suppression lists.
.SH "PORTABILITY NOTES"
.IX Header "PORTABILITY NOTES"
.SS "\s-1GNU/LINUX\s0 32 \s-1BIT\s0 \s-1LIMITATIONS\s0"
.SS "\s-1GNU/LINUX 32 BIT LIMITATIONS\s0"
.IX Subsection "GNU/LINUX 32 BIT LIMITATIONS"
GNU/Linux is the only common platform that supports 64 bit file/large file
interfaces but \fIdisables\fR them by default.
@ -5203,13 +5212,13 @@ That means that libev compiled in the default environment doesn't support
files larger than 2GiB or so, which mainly affects \f(CW\*(C`ev_stat\*(C'\fR watchers.
.PP
Unfortunately, many programs try to work around this GNU/Linux issue
by enabling the large file \s-1API\s0, which makes them incompatible with the
by enabling the large file \s-1API,\s0 which makes them incompatible with the
standard libev compiled for their system.
.PP
Likewise, libev cannot enable the large file \s-1API\s0 itself as this would
suddenly make it incompatible to the default compile time environment,
i.e. all programs not using special compile switches.
.SS "\s-1OS/X\s0 \s-1AND\s0 \s-1DARWIN\s0 \s-1BUGS\s0"
.SS "\s-1OS/X AND DARWIN BUGS\s0"
.IX Subsection "OS/X AND DARWIN BUGS"
The whole thing is a bug if you ask me \- basically any system interface
you touch is broken, whether it is locales, poll, kqueue or even the
@ -5241,14 +5250,14 @@ a loop.
.IX Subsection "select is buggy"
.PP
All that's left is \f(CW\*(C`select\*(C'\fR, and of course Apple found a way to fuck this
one up as well: On \s-1OS/X\s0, \f(CW\*(C`select\*(C'\fR actively limits the number of file
one up as well: On \s-1OS/X, \s0\f(CW\*(C`select\*(C'\fR actively limits the number of file
descriptors you can pass in to 1024 \- your program suddenly crashes when
you use more.
.PP
There is an undocumented \*(L"workaround\*(R" for this \- defining
\&\f(CW\*(C`_DARWIN_UNLIMITED_SELECT\*(C'\fR, which libev tries to use, so select \fIshould\fR
work on \s-1OS/X\s0.
.SS "\s-1SOLARIS\s0 \s-1PROBLEMS\s0 \s-1AND\s0 \s-1WORKAROUNDS\s0"
work on \s-1OS/X.\s0
.SS "\s-1SOLARIS PROBLEMS AND WORKAROUNDS\s0"
.IX Subsection "SOLARIS PROBLEMS AND WORKAROUNDS"
\fI\f(CI\*(C`errno\*(C'\fI reentrancy\fR
.IX Subsection "errno reentrancy"
@ -5275,13 +5284,13 @@ great.
If you can't get it to work, you can try running the program by setting
the environment variable \f(CW\*(C`LIBEV_FLAGS=3\*(C'\fR to only allow \f(CW\*(C`poll\*(C'\fR and
\&\f(CW\*(C`select\*(C'\fR backends.
.SS "\s-1AIX\s0 \s-1POLL\s0 \s-1BUG\s0"
.SS "\s-1AIX POLL BUG\s0"
.IX Subsection "AIX POLL BUG"
\&\s-1AIX\s0 unfortunately has a broken \f(CW\*(C`poll.h\*(C'\fR header. Libev works around
this by trying to avoid the poll backend altogether (i.e. it's not even
compiled in), which normally isn't a big problem as \f(CW\*(C`select\*(C'\fR works fine
with large bitsets on \s-1AIX\s0, and \s-1AIX\s0 is dead anyway.
.SS "\s-1WIN32\s0 \s-1PLATFORM\s0 \s-1LIMITATIONS\s0 \s-1AND\s0 \s-1WORKAROUNDS\s0"
with large bitsets on \s-1AIX,\s0 and \s-1AIX\s0 is dead anyway.
.SS "\s-1WIN32 PLATFORM LIMITATIONS AND WORKAROUNDS\s0"
.IX Subsection "WIN32 PLATFORM LIMITATIONS AND WORKAROUNDS"
\fIGeneral issues\fR
.IX Subsection "General issues"
@ -5360,7 +5369,7 @@ libraries and raw winsocket select is:
.Ve
.PP
Note that winsockets handling of fd sets is O(n), so you can easily get a
complexity in the O(nA\*^X) range when using win32.
complexity in the O(nX) range when using win32.
.PP
\fILimited number of file descriptors\fR
.IX Subsection "Limited number of file descriptors"
@ -5386,8 +5395,8 @@ by calling \f(CW\*(C`_setmaxstdio\*(C'\fR, which can increase this limit to \f(C
runtime libraries. This might get you to about \f(CW512\fR or \f(CW2048\fR 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(nA\*^X)) will likely make this unworkable.
.SS "\s-1PORTABILITY\s0 \s-1REQUIREMENTS\s0"
the cost of calling select (O(nX)) will likely make this unworkable.
.SS "\s-1PORTABILITY REQUIREMENTS\s0"
.IX Subsection "PORTABILITY REQUIREMENTS"
In addition to a working ISO-C implementation and of course the
backend-specific APIs, libev relies on a few additional extensions:
@ -5395,7 +5404,7 @@ backend-specific APIs, libev relies on a few additional extensions:
.el .IP "\f(CWvoid (*)(ev_watcher_type *, int revents)\fR must have compatible calling conventions regardless of \f(CWev_watcher_type *\fR." 4
.IX Item "void (*)(ev_watcher_type *, int revents) must have compatible calling conventions regardless of ev_watcher_type *."
Libev assumes not only that all watcher pointers have the same internal
structure (guaranteed by \s-1POSIX\s0 but not by \s-1ISO\s0 C for example), but it also
structure (guaranteed by \s-1POSIX\s0 but not by \s-1ISO C\s0 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 \f(CW\*(C`ev_watcher *\*(C'\fR internally.
@ -5426,7 +5435,7 @@ thread as well.
.ie n .IP """long"" must be large enough for common memory allocation sizes" 4
.el .IP "\f(CWlong\fR must be large enough for common memory allocation sizes" 4
.IX Item "long must be large enough for common memory allocation sizes"
To improve portability and simplify its \s-1API\s0, libev uses \f(CW\*(C`long\*(C'\fR internally
To improve portability and simplify its \s-1API,\s0 libev uses \f(CW\*(C`long\*(C'\fR internally
instead of \f(CW\*(C`size_t\*(C'\fR 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
@ -5438,9 +5447,9 @@ The type \f(CW\*(C`double\*(C'\fR is used to represent timestamps. It is require
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 \s-1IEEE\s0 754, which is basically all existing ones.
implementations using \s-1IEEE 754,\s0 which is basically all existing ones.
.Sp
With \s-1IEEE\s0 754 doubles, you get microsecond accuracy until at least the
With \s-1IEEE 754\s0 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 \f(CW\*(C`long double\*(C'\fR or
something like that, just kidding).
@ -5512,7 +5521,7 @@ blocked. Checking for async and signal events involves iterating over all
running async watchers or all signal numbers.
.SH "PORTING FROM LIBEV 3.X TO 4.X"
.IX Header "PORTING FROM LIBEV 3.X TO 4.X"
The major version 4 introduced some incompatible changes to the \s-1API\s0.
The major version 4 introduced some incompatible changes to the \s-1API.\s0
.PP
At the moment, the \f(CW\*(C`ev.h\*(C'\fR header file provides compatibility definitions
for all changes, so most programs should still compile. The compatibility
@ -5522,7 +5531,7 @@ new \s-1API\s0 early than late.
.el .IP "\f(CWEV_COMPAT3\fR backwards compatibility mechanism" 4
.IX Item "EV_COMPAT3 backwards compatibility mechanism"
The backward compatibility mechanism can be controlled by
\&\f(CW\*(C`EV_COMPAT3\*(C'\fR. See \*(L"\s-1PREPROCESSOR\s0 \s-1SYMBOLS/MACROS\s0\*(R" in the \*(L"\s-1EMBEDDING\s0\*(R"
\&\f(CW\*(C`EV_COMPAT3\*(C'\fR. See \*(L"\s-1PREPROCESSOR SYMBOLS/MACROS\*(R"\s0 in the \*(L"\s-1EMBEDDING\*(R"\s0
section.
.ie n .IP """ev_default_destroy"" and ""ev_default_fork"" have been removed" 4
.el .IP "\f(CWev_default_destroy\fR and \f(CWev_default_fork\fR have been removed" 4
@ -5572,7 +5581,7 @@ and work, but the library code will of course be larger.
.IP "active" 4
.IX Item "active"
A watcher is active as long as it has been started and not yet stopped.
See \*(L"\s-1WATCHER\s0 \s-1STATES\s0\*(R" for details.
See \*(L"\s-1WATCHER STATES\*(R"\s0 for details.
.IP "application" 4
.IX Item "application"
In this document, an application is whatever is using libev.
@ -5609,7 +5618,7 @@ watchers and events.
.IP "pending" 4
.IX Item "pending"
A watcher is pending as soon as the corresponding event has been
detected. See \*(L"\s-1WATCHER\s0 \s-1STATES\s0\*(R" for details.
detected. See \*(L"\s-1WATCHER STATES\*(R"\s0 for details.
.IP "real time" 4
.IX Item "real time"
The physical time that is observed. It is apparently strictly monotonic :)

5
ev.c
View File

@ -243,10 +243,7 @@
#elif defined _sys_nsig
# define EV_NSIG (_sys_nsig) /* Solaris 2.5 */
#else
# error "unable to find value for NSIG, please report"
/* to make it compile regardless, just remove the above line, */
/* but consider reporting it, too! :) */
# define EV_NSIG 65
# define EV_NSIG (8 * sizeof (sigset_t) + 1)
#endif
#ifndef EV_USE_FLOOR

2
ev.pod
View File

@ -1,3 +1,5 @@
=encoding utf-8
=head1 NAME
libev - a high performance full-featured event loop written in C