[ViewVC] Diff of: cvs/libev/ev.3

Comparing libev/ev.3 (file contents):
Revision 1.71 by root, Mon Sep 29 03:31:14 2008 UTC vs.
Revision 1.72 by root, Tue Oct 21 20:06:52 2008 UTC

 .\}
 .rm #[ #] #H #V #F C
 .\" ========================================================================
 .\"
 .IX Title "LIBEV 3"
-.TH LIBEV 3 "2008-09-29" "libev-3.44" "libev - high performance full featured event loop"
+.TH LIBEV 3 "2008-10-21" "libev-3.45" "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
 .nh
 .SH "NAME"
 has processed all outstanding events). The \f(CW\*(C`how\*(C'\fR argument must be either
 \&\f(CW\*(C`EVUNLOOP_ONE\*(C'\fR, which will make the innermost \f(CW\*(C`ev_loop\*(C'\fR call return, or
 \&\f(CW\*(C`EVUNLOOP_ALL\*(C'\fR, which will make all nested \f(CW\*(C`ev_loop\*(C'\fR calls return.
 .Sp
 This \*(L"unloop state\*(R" will be cleared when entering \f(CW\*(C`ev_loop\*(C'\fR again.
+.Sp
+It is safe to call \f(CW\*(C`ev_unloop\*(C'\fR from otuside any \f(CW\*(C`ev_loop\*(C'\fR calls.
 .IP "ev_ref (loop)" 4
 .IX Item "ev_ref (loop)"
 .PD 0
 .IP "ev_unref (loop)" 4
 .IX Item "ev_unref (loop)"
 \&   ev_io_start (EV_DEFAULT_UC, &w);
 .Ve
 .ie n .IP """ev_TYPE_stop"" (loop *, ev_TYPE *watcher)" 4
 .el .IP "\f(CWev_TYPE_stop\fR (loop *, ev_TYPE *watcher)" 4
 .IX Item "ev_TYPE_stop (loop *, ev_TYPE *watcher)"
-Stops the given watcher again (if active) and clears the pending
+Stops the given watcher if active, and clears the pending status (whether
+the watcher was active or not).
+.Sp
-status. It is possible that stopped watchers are pending (for example,
+It is possible that stopped watchers are pending \- for example,
-non-repeating timers are being stopped when they become pending), but
+non-repeating timers are being stopped when they become pending \- but
-\&\f(CW\*(C`ev_TYPE_stop\*(C'\fR ensures that the watcher is neither active nor pending. If
+calling \f(CW\*(C`ev_TYPE_stop\*(C'\fR ensures that the watcher is neither active nor
-you want to free or reuse the memory used by the watcher it is therefore a
+pending. If you want to free or reuse the memory used by the watcher it is
-good idea to always call its \f(CW\*(C`ev_TYPE_stop\*(C'\fR function.
+therefore a good idea to always call its \f(CW\*(C`ev_TYPE_stop\*(C'\fR function.
 .IP "bool ev_is_active (ev_TYPE *watcher)" 4
 .IX Item "bool ev_is_active (ev_TYPE *watcher)"
 Returns a true value iff the watcher is active (i.e. it has been started
 and not yet been stopped). As long as a watcher is active you must not modify
 it.
 The signal the watcher watches out for.
 .PP
 \fIExamples\fR
 .IX Subsection "Examples"
 .PP
-Example: Try to exit cleanly on \s-1SIGINT\s0 and \s-1SIGTERM\s0.
+Example: Try to exit cleanly on \s-1SIGINT\s0.
 .PP
 .Vb 5
 \&   static void
 \&   sigint_cb (struct ev_loop *loop, struct ev_signal *w, int revents)
 \&   {
 \&     ev_unloop (loop, EVUNLOOP_ALL);
 \&   }
 \&
 \&   struct ev_signal signal_watcher;
 \&   ev_signal_init (&signal_watcher, sigint_cb, SIGINT);
-\&   ev_signal_start (loop, &sigint_cb);
+\&   ev_signal_start (loop, &signal_watcher);
 .Ve
 .ie n .Sh """ev_child"" \- watch out for process status changes"
 .el .Sh "\f(CWev_child\fP \- watch out for process status changes"
 .IX Subsection "ev_child - watch out for process status changes"
 Child watchers trigger when your process receives a \s-1SIGCHLD\s0 in response to
 default compilation environment.
 .PP
 \fIInotify and Kqueue\fR
 .IX Subsection "Inotify and Kqueue"
 .PP
-When \f(CW\*(C`inotify (7)\*(C'\fR support has been compiled into libev (generally only
+When \f(CW\*(C`inotify (7)\*(C'\fR support has been compiled into libev (generally
+only available with Linux 2.6.25 or above due to bugs in earlier
-available with Linux) and present at runtime, it will be used to speed up
+implementations) and present at runtime, it will be used to speed up
-change detection where possible. The inotify descriptor will be created lazily
+change detection where possible. The inotify descriptor will be created
-when the first \f(CW\*(C`ev_stat\*(C'\fR watcher is being started.
+lazily when the first \f(CW\*(C`ev_stat\*(C'\fR watcher is being started.
 .PP
 Inotify presence does not change the semantics of \f(CW\*(C`ev_stat\*(C'\fR watchers
 except that changes might be detected earlier, and in some cases, to avoid
 making regular \f(CW\*(C`stat\*(C'\fR calls. Even in the presence of inotify support
 there are many cases where libev has to resort to regular \f(CW\*(C`stat\*(C'\fR polling,
 queue. But at least I can tell you how to implement locking around your
 queue:
 .IP "queueing from a signal handler context" 4
 .IX Item "queueing from a signal handler context"
 To implement race-free queueing, you simply add to the queue in the signal
-handler but you block the signal handler in the watcher callback. Here is an example that does that for
+handler but you block the signal handler in the watcher callback. Here is
-some fictitious \s-1SIGUSR1\s0 handler:
+an example that does that for some fictitious \s-1SIGUSR1\s0 handler:
 .Sp
 .Vb 1
 \&   static ev_async mysig;
 \&
 \&   static void
 .IX Header "OTHER FUNCTIONS"
 There are some other functions of possible interest. Described. Here. Now.
 .IP "ev_once (loop, int fd, int events, ev_tstamp timeout, callback)" 4
 .IX Item "ev_once (loop, int fd, int events, ev_tstamp timeout, callback)"
 This function combines a simple timer and an I/O watcher, calls your
-callback on whichever event happens first and automatically stop both
+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.
 .Sp
-If \f(CW\*(C`fd\*(C'\fR is less than 0, then no I/O watcher will be started and events
+If \f(CW\*(C`fd\*(C'\fR is less than 0, then no I/O watcher will be started and the
-is being ignored. Otherwise, an \f(CW\*(C`ev_io\*(C'\fR watcher for the given \f(CW\*(C`fd\*(C'\fR and
+\&\f(CW\*(C`events\*(C'\fR argument is being ignored. Otherwise, an \f(CW\*(C`ev_io\*(C'\fR watcher for
-\&\f(CW\*(C`events\*(C'\fR set will be created and started.
+the given \f(CW\*(C`fd\*(C'\fR and \f(CW\*(C`events\*(C'\fR set will be created and started.
 .Sp
 If \f(CW\*(C`timeout\*(C'\fR is less than 0, then no timeout watcher will be
 started. Otherwise an \f(CW\*(C`ev_timer\*(C'\fR watcher with after = \f(CW\*(C`timeout\*(C'\fR (and
-repeat = 0) will be started. While \f(CW0\fR is a valid timeout, it is of
+repeat = 0) will be started. \f(CW0\fR is a valid timeout.
-dubious value.
 .Sp
 The callback has the type \f(CW\*(C`void (*cb)(int revents, void *arg)\*(C'\fR and gets
 passed an \f(CW\*(C`revents\*(C'\fR set like normal event callbacks (a combination of
 \&\f(CW\*(C`EV_ERROR\*(C'\fR, \f(CW\*(C`EV_READ\*(C'\fR, \f(CW\*(C`EV_WRITE\*(C'\fR or \f(CW\*(C`EV_TIMEOUT\*(C'\fR) and the \f(CW\*(C`arg\*(C'\fR
-value passed to \f(CW\*(C`ev_once\*(C'\fR:
+value passed to \f(CW\*(C`ev_once\*(C'\fR. Note that it is possible to receive \fIboth\fR
+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.
 .Sp
 .Vb 7
 \&   static void stdin_ready (int revents, void *arg)
 \&   {
+\&     if (revents & EV_READ)
+\&       /* stdin might have data for us, joy! */;
-\&     if (revents & EV_TIMEOUT)
+\&     else if (revents & EV_TIMEOUT)
 \&       /* doh, nothing entered */;
-\&     else if (revents & EV_READ)
-\&       /* stdin might have data for us, joy! */;
 \&   }
 \&
 \&   ev_once (STDIN_FILENO, EV_READ, 10., stdin_ready, 0);
 .Ve
 .IP "ev_feed_event (ev_loop *, watcher *, int revents)" 4
 .PP
 .Vb 2
 \&   #include "ev_cpp.h"
 \&   #include "ev.c"
 .Ve
-.SH "THREADS AND COROUTINES"
+.SH "INTERACTION WITH OTHER PROGRAMS OR LIBRARIES"
+.IX Header "INTERACTION WITH OTHER PROGRAMS OR LIBRARIES"
+.Sh "\s-1THREADS\s0 \s-1AND\s0 \s-1COROUTINES\s0"
-.IX Header "THREADS AND COROUTINES"
+.IX Subsection "THREADS AND COROUTINES"
-.Sh "\s-1THREADS\s0"
+\fI\s-1THREADS\s0\fR
 .IX Subsection "THREADS"
+.PP
 All libev functions are reentrant and thread-safe unless explicitly
-documented otherwise, but it uses no locking itself. This means that you
+documented otherwise, but libev implements no locking itself. This means
-can use as many loops as you want in parallel, as long as there are no
+that you can use as many loops as you want in parallel, as long as there
-concurrent calls into any libev function with the same loop parameter
+are no concurrent calls into any libev function with the same loop
-(\f(CW\*(C`ev_default_*\*(C'\fR calls have an implicit default loop parameter, of
+parameter (\f(CW\*(C`ev_default_*\*(C'\fR calls have an implicit default loop parameter,
-course): libev guarantees that different event loops share no data
+of course): libev guarantees that different event loops share no data
 structures that need any locking.
 .PP
 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
 .Sp
 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 \f(CW\*(C`ev_async\*(C'\fR watcher from the default loop
 watcher callback into the event loop interested in the signal.
-.Sh "\s-1COROUTINES\s0"
+.PP
+\fI\s-1COROUTINES\s0\fR
 .IX Subsection "COROUTINES"
+.PP
-Libev is much more accommodating to coroutines (\*(L"cooperative threads\*(R"):
+Libev is very accommodating to coroutines (\*(L"cooperative threads\*(R"):
-libev fully supports nesting calls to it's functions from different
+libev fully supports nesting calls to its functions from different
 coroutines (e.g. you can call \f(CW\*(C`ev_loop\*(C'\fR on the same loop from two
-different coroutines and switch freely between both coroutines running the
+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 \f(CW\*(C`ev_periodic\*(C'\fR reschedule callbacks.
 .PP
 Care has been taken to ensure that libev does not keep local state inside
-\&\f(CW\*(C`ev_loop\*(C'\fR, and other calls do not usually allow coroutine switches.
+\&\f(CW\*(C`ev_loop\*(C'\fR, and other calls do not usually allow for coroutine switches as
+they do not clal any callbacks.
+.Sh "\s-1COMPILER\s0 \s-1WARNINGS\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
+scared by this.
+.PP
+However, these are unavoidable for many reasons. For one, each compiler
+has different warnings, and each user has different tastes regarding
+warning options. \*(L"Warn-free\*(R" code therefore cannot be a goal except when
+targeting a specific compiler and compiler-version.
+.PP
+Another reason is that some compiler warnings require elaborate
+workarounds, or other changes to the code that make it less clear and less
+maintainable.
+.PP
+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 an extreme number of false positives. These have
+been fixed, but some people still insist on making code warn-free with
+such buggy versions.
+.PP
+While libev is written to generate as few warnings as possible,
+\&\*(L"warn-free\*(R" 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.
+.Sh "\s-1VALGRIND\s0"
+.IX Subsection "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.
+.PP
+If you think you found a bug (memory leak, uninitialised data access etc.)
+in libev, then check twice: If valgrind reports something like:
+.PP
+.Vb 3
+\&   ==2274==    definitely lost: 0 bytes in 0 blocks.
+\&   ==2274==      possibly lost: 0 bytes in 0 blocks.
+\&   ==2274==    still reachable: 256 bytes in 1 blocks.
+.Ve
+.PP
+Then there is no memory leak, just as memory accounted to global variables
+is not a memleak \- the memory is still being refernced, and didn't leak.
+.PP
+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.
+.PP
+Keep in mind that valgrind is a very good tool, but only a tool. Don't
+make it into some kind of religion.
+.PP
+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 \*(L"this is no bug\*(R" answer and take the chance
+of learning how to interpret valgrind properly.
+.PP
+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"
+.Sh "\s-1WIN32\s0 \s-1PLATFORM\s0 \s-1LIMITATIONS\s0 \s-1AND\s0 \s-1WORKAROUNDS\s0"
+.IX Subsection "WIN32 PLATFORM LIMITATIONS AND WORKAROUNDS"
+Win32 doesn't support any of the standards (e.g. \s-1POSIX\s0) that libev
+requires, and its I/O model is fundamentally incompatible with the \s-1POSIX\s0
+model. Libev still offers limited functionality on this platform in
+the form of the \f(CW\*(C`EVBACKEND_SELECT\*(C'\fR backend, and only supports socket
+descriptors. This only applies when using Win32 natively, not when using
+e.g. cygwin.
+.PP
+Lifting these limitations would basically require the full
+re-implementation of the I/O system. If you are into these kinds of
+things, then note that glib does exactly that for you in a very portable
+way (note also that glib is the slowest event library known to man).
+.PP
+There is no supported compilation method available on windows except
+embedding it into other applications.
+.PP
+Not a libev limitation but worth mentioning: windows apparently doesn't
+accept large writes: instead of resulting in a partial write, windows will
+either accept everything or return \f(CW\*(C`ENOBUFS\*(C'\fR if the buffer is too large,
+so make sure you only write small amounts into your sockets (less than a
+megabyte seems safe, but this apparently depends on the amount of memory
+available).
+.PP
+Due to the many, low, and arbitrary limits on the win32 platform and
+the abysmal performance of winsockets, using a large number of sockets
+is not recommended (and not reasonable). If your program needs to use
+more than a hundred or so sockets, then likely it needs to use a totally
+different implementation for windows, as libev offers the \s-1POSIX\s0 readiness
+notification model, which cannot be implemented efficiently on windows
+(Microsoft monopoly games).
+.PP
+A typical way to use libev under windows is to embed it (see the embedding
+section for details) and use the following \fIevwrap.h\fR header file instead
+of \fIev.h\fR:
+.PP
+.Vb 2
+\&   #define EV_STANDALONE              /* keeps ev from requiring config.h */
+\&   #define EV_SELECT_IS_WINSOCKET 1   /* configure libev for windows select */
+\&
+\&   #include "ev.h"
+.Ve
+.PP
+And compile the following \fIevwrap.c\fR file into your project (make sure
+you do \fInot\fR compile the \fIev.c\fR or any other embedded source files!):
+.PP
+.Vb 2
+\&   #include "evwrap.h"
+\&   #include "ev.c"
+.Ve
+.IP "The winsocket select function" 4
+.IX Item "The winsocket select function"
+The winsocket \f(CW\*(C`select\*(C'\fR function doesn't follow \s-1POSIX\s0 in that it
+requires socket \fIhandles\fR and not socket \fIfile descriptors\fR (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 \f(CW\*(C`_open_osfhandle\*(C'\fR for this). See the
+discussion of the \f(CW\*(C`EV_SELECT_USE_FD_SET\*(C'\fR, \f(CW\*(C`EV_SELECT_IS_WINSOCKET\*(C'\fR and
+\&\f(CW\*(C`EV_FD_TO_WIN32_HANDLE\*(C'\fR preprocessor symbols for more info.
+.Sp
+The configuration for a \*(L"naked\*(R" win32 using the Microsoft runtime
+libraries and raw winsocket select is:
+.Sp
+.Vb 2
+\&   #define EV_USE_SELECT 1
+\&   #define EV_SELECT_IS_WINSOCKET 1   /* forces EV_SELECT_USE_FD_SET, too */
+.Ve
+.Sp
+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.
+.IP "Limited number of file descriptors" 4
+.IX Item "Limited number of file descriptors"
+Windows has numerous arbitrary (and low) limits on things.
+.Sp
+Early versions of winsocket's select only supported waiting for a maximum
+of \f(CW64\fR handles (probably owning to the fact that all windows kernels
+can only wait for \f(CW64\fR things at the same time internally; Microsoft
+recommends spawning a chain of threads and wait for 63 handles and the
+previous thread in each. Great).
+.Sp
+Newer versions support more handles, but you need to define \f(CW\*(C`FD_SETSIZE\*(C'\fR
+to some high number (e.g. \f(CW2048\fR) before compiling the winsocket select
+call (which might be in libev or elsewhere, for example, perl does its own
+select emulation on windows).
+.Sp
+Another limit is the number of file descriptors in the Microsoft runtime
+libraries, which by default is \f(CW64\fR (there must be a hidden \fI64\fR fetish
+or something like this inside Microsoft). You can increase this by calling
+\&\f(CW\*(C`_setmaxstdio\*(C'\fR, which can increase this limit to \f(CW2048\fR (another
+arbitrary limit), but is broken in many versions of the Microsoft runtime
+libraries.
+.Sp
+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.
+.Sh "\s-1PORTABILITY\s0 \s-1REQUIREMENTS\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:
+.ie n .IP """void (*)(ev_watcher_type *, int revents)""\fR must have compatible calling conventions regardless of \f(CW""ev_watcher_type *""." 4
+.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
+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.
+.ie n .IP """sig_atomic_t volatile"" must be thread-atomic as well" 4
+.el .IP "\f(CWsig_atomic_t volatile\fR must be thread-atomic as well" 4
+.IX Item "sig_atomic_t volatile must be thread-atomic as well"
+The type \f(CW\*(C`sig_atomic_t volatile\*(C'\fR (or whatever is defined as
+\&\f(CW\*(C`EV_ATOMIC_T\*(C'\fR) must be atomic with respect to accesses from different
+threads. This is not part of the specification for \f(CW\*(C`sig_atomic_t\*(C'\fR, but is
+believed to be sufficiently portable.
+.ie n .IP """sigprocmask"" must work in a threaded environment" 4
+.el .IP "\f(CWsigprocmask\fR must work in a threaded environment" 4
+.IX Item "sigprocmask must work in a threaded environment"
+Libev uses \f(CW\*(C`sigprocmask\*(C'\fR to temporarily block signals. This is not
+allowed in a threaded program (\f(CW\*(C`pthread_sigmask\*(C'\fR has to be used). Typical
+pthread implementations will either allow \f(CW\*(C`sigprocmask\*(C'\fR in the \*(L"main
+thread\*(R" or will block signals process-wide, both behaviours would
+be compatible with libev. Interaction between \f(CW\*(C`sigprocmask\*(C'\fR and
+\&\f(CW\*(C`pthread_sigmask\*(C'\fR could complicate things, however.
+.Sp
+The most portable way to handle signals is to block signals in all threads
+except the initial one, and run the default loop in the initial 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
+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
+watchers.
+.ie n .IP """double"" must hold a time value in seconds with enough accuracy" 4
+.el .IP "\f(CWdouble\fR must hold a time value in seconds with enough accuracy" 4
+.IX Item "double must hold a time value in seconds with enough accuracy"
+The type \f(CW\*(C`double\*(C'\fR 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. This requirement is fulfilled by
+implementations implementing \s-1IEEE\s0 754 (basically all existing ones).
+.PP
+If you know of other additional requirements drop me a note.
-.SH "COMPLEXITIES"
+.SH "ALGORITHMIC COMPLEXITIES"
-.IX Header "COMPLEXITIES"
+.IX Header "ALGORITHMIC COMPLEXITIES"
 In this section the complexities of (many of) the algorithms used inside
-libev will be explained. For complexity discussions about backends see the
+libev will be documented. For complexity discussions about backends see
-documentation for \f(CW\*(C`ev_default_init\*(C'\fR.
+the documentation for \f(CW\*(C`ev_default_init\*(C'\fR.
 .PP
 All of the following are about amortised time: If an array needs to be
 extended, libev needs to realloc and move the whole array, but this
-happens asymptotically never with higher number of elements, so O(1) might
+happens asymptotically rarer with higher number of elements, so O(1) might
-mean it might do a lengthy realloc operation in rare cases, but on average
+mean that libev does a lengthy realloc operation in rare cases, but on
-it is much faster and asymptotically approaches constant time.
+average it is much faster and asymptotically approaches constant time.
 .IP "Starting and stopping timer/periodic watchers: O(log skipped_other_timers)" 4
 .IX Item "Starting and stopping timer/periodic watchers: O(log skipped_other_timers)"
 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
+there are 100 watchers that would trigger before that, then inserting will
 have to skip roughly seven (\f(CW\*(C`ld 100\*(C'\fR) of these watchers.
 .IP "Changing timer/periodic watchers (by autorepeat or calling again): O(log skipped_other_timers)" 4
 .IX Item "Changing timer/periodic watchers (by autorepeat or calling again): O(log skipped_other_timers)"
-That means that 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.
 .IP "Starting io/check/prepare/idle/signal/child/fork/async watchers: O(1)" 4
 .IX Item "Starting io/check/prepare/idle/signal/child/fork/async watchers: O(1)"
 These just add the watcher into an array or at the head of a list.
 .IP "Stopping check/prepare/idle/fork/async watchers: O(1)" 4
 .IX Item "Stopping check/prepare/idle/fork/async watchers: O(1)"
 .PD 0
 .IP "Stopping an io/signal/child watcher: O(number_of_watchers_for_this_(fd/signal/pid % \s-1EV_PID_HASHSIZE\s0))" 4
 .IX Item "Stopping an io/signal/child watcher: O(number_of_watchers_for_this_(fd/signal/pid % EV_PID_HASHSIZE))"
 .PD
-These watchers are stored in lists then need to be walked to find the
+These watchers are stored in lists, so they need to be walked to find the
 correct watcher to remove. The lists are usually short (you don't usually
-have many watchers waiting for the same fd or signal).
+have many watchers waiting for the same fd or signal: one is typical, two
+is rare).
 .IP "Finding the next timer in each loop iteration: O(1)" 4
 .IX Item "Finding the next timer in each loop iteration: O(1)"
 By virtue of using a binary or 4\-heap, the next timer is always found at a
 fixed position in the storage array.
 .IP "Each change on a file descriptor per loop iteration: O(number_of_watchers_for_this_fd)" 4
 .IX Item "Processing signals: O(max_signal_number)"
 .PD
 Sending involves a system call \fIiff\fR there were no other \f(CW\*(C`ev_async_send\*(C'\fR
 calls in the current loop iteration. Checking for async and signal events
 involves iterating over all running async watchers or all signal numbers.
-.SH "WIN32 PLATFORM LIMITATIONS AND WORKAROUNDS"
-.IX Header "WIN32 PLATFORM LIMITATIONS AND WORKAROUNDS"
-Win32 doesn't support any of the standards (e.g. \s-1POSIX\s0) that libev
-requires, and its I/O model is fundamentally incompatible with the \s-1POSIX\s0
-model. Libev still offers limited functionality on this platform in
-the form of the \f(CW\*(C`EVBACKEND_SELECT\*(C'\fR backend, and only supports socket
-descriptors. This only applies when using Win32 natively, not when using
-e.g. cygwin.
-.PP
-Lifting these limitations would basically require the full
-re-implementation of the I/O system. If you are into these kinds of
-things, then note that glib does exactly that for you in a very portable
-way (note also that glib is the slowest event library known to man).
-.PP
-There is no supported compilation method available on windows except
-embedding it into other applications.
-.PP
-Not a libev limitation but worth mentioning: windows apparently doesn't
-accept large writes: instead of resulting in a partial write, windows will
-either accept everything or return \f(CW\*(C`ENOBUFS\*(C'\fR if the buffer is too large,
-so make sure you only write small amounts into your sockets (less than a
-megabyte seems safe, but this apparently depends on the amount of memory
-available).
-.PP
-Due to the many, low, and arbitrary limits on the win32 platform and
-the abysmal performance of winsockets, using a large number of sockets
-is not recommended (and not reasonable). If your program needs to use
-more than a hundred or so sockets, then likely it needs to use a totally
-different implementation for windows, as libev offers the \s-1POSIX\s0 readiness
-notification model, which cannot be implemented efficiently on windows
-(Microsoft monopoly games).
-.PP
-A typical way to use libev under windows is to embed it (see the embedding
-section for details) and use the following \fIevwrap.h\fR header file instead
-of \fIev.h\fR:
-.PP
-.Vb 2
-\&   #define EV_STANDALONE              /* keeps ev from requiring config.h */
-\&   #define EV_SELECT_IS_WINSOCKET 1   /* configure libev for windows select */
-\&
-\&   #include "ev.h"
-.Ve
-.PP
-And compile the following \fIevwrap.c\fR file into your project (make sure
-you do \fInot\fR compile the \fIev.c\fR or any other embedded source files!):
-.PP
-.Vb 2
-\&   #include "evwrap.h"
-\&   #include "ev.c"
-.Ve
-.IP "The winsocket select function" 4
-.IX Item "The winsocket select function"
-The winsocket \f(CW\*(C`select\*(C'\fR function doesn't follow \s-1POSIX\s0 in that it
-requires socket \fIhandles\fR and not socket \fIfile descriptors\fR (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 \f(CW\*(C`_open_osfhandle\*(C'\fR for this). See the
-discussion of the \f(CW\*(C`EV_SELECT_USE_FD_SET\*(C'\fR, \f(CW\*(C`EV_SELECT_IS_WINSOCKET\*(C'\fR and
-\&\f(CW\*(C`EV_FD_TO_WIN32_HANDLE\*(C'\fR preprocessor symbols for more info.
-.Sp
-The configuration for a \*(L"naked\*(R" win32 using the Microsoft runtime
-libraries and raw winsocket select is:
-.Sp
-.Vb 2
-\&   #define EV_USE_SELECT 1
-\&   #define EV_SELECT_IS_WINSOCKET 1   /* forces EV_SELECT_USE_FD_SET, too */
-.Ve
-.Sp
-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.
-.IP "Limited number of file descriptors" 4
-.IX Item "Limited number of file descriptors"
-Windows has numerous arbitrary (and low) limits on things.
-.Sp
-Early versions of winsocket's select only supported waiting for a maximum
-of \f(CW64\fR handles (probably owning to the fact that all windows kernels
-can only wait for \f(CW64\fR things at the same time internally; Microsoft
-recommends spawning a chain of threads and wait for 63 handles and the
-previous thread in each. Great).
-.Sp
-Newer versions support more handles, but you need to define \f(CW\*(C`FD_SETSIZE\*(C'\fR
-to some high number (e.g. \f(CW2048\fR) before compiling the winsocket select
-call (which might be in libev or elsewhere, for example, perl does its own
-select emulation on windows).
-.Sp
-Another limit is the number of file descriptors in the Microsoft runtime
-libraries, which by default is \f(CW64\fR (there must be a hidden \fI64\fR fetish
-or something like this inside Microsoft). You can increase this by calling
-\&\f(CW\*(C`_setmaxstdio\*(C'\fR, which can increase this limit to \f(CW2048\fR (another
-arbitrary limit), but is broken in many versions of the Microsoft runtime
-libraries.
-.Sp
-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.
-.SH "PORTABILITY REQUIREMENTS"
-.IX Header "PORTABILITY REQUIREMENTS"
-In addition to a working ISO-C implementation, libev relies on a few
-additional extensions:
-.ie n .IP """void (*)(ev_watcher_type *, int revents)""\fR must have compatible calling conventions regardless of \f(CW""ev_watcher_type *""." 4
-.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
-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.
-.ie n .IP """sig_atomic_t volatile"" must be thread-atomic as well" 4
-.el .IP "\f(CWsig_atomic_t volatile\fR must be thread-atomic as well" 4
-.IX Item "sig_atomic_t volatile must be thread-atomic as well"
-The type \f(CW\*(C`sig_atomic_t volatile\*(C'\fR (or whatever is defined as
-\&\f(CW\*(C`EV_ATOMIC_T\*(C'\fR) must be atomic with respect to accesses from different
-threads. This is not part of the specification for \f(CW\*(C`sig_atomic_t\*(C'\fR, but is
-believed to be sufficiently portable.
-.ie n .IP """sigprocmask"" must work in a threaded environment" 4
-.el .IP "\f(CWsigprocmask\fR must work in a threaded environment" 4
-.IX Item "sigprocmask must work in a threaded environment"
-Libev uses \f(CW\*(C`sigprocmask\*(C'\fR to temporarily block signals. This is not
-allowed in a threaded program (\f(CW\*(C`pthread_sigmask\*(C'\fR has to be used). Typical
-pthread implementations will either allow \f(CW\*(C`sigprocmask\*(C'\fR in the \*(L"main
-thread\*(R" or will block signals process-wide, both behaviours would
-be compatible with libev. Interaction between \f(CW\*(C`sigprocmask\*(C'\fR and
-\&\f(CW\*(C`pthread_sigmask\*(C'\fR could complicate things, however.
-.Sp
-The most portable way to handle signals is to block signals in all threads
-except the initial one, and run the default loop in the initial 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 using libev, 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 watchers.
-.ie n .IP """double"" must hold a time value in seconds with enough accuracy" 4
-.el .IP "\f(CWdouble\fR must hold a time value in seconds with enough accuracy" 4
-.IX Item "double must hold a time value in seconds with enough accuracy"
-The type \f(CW\*(C`double\*(C'\fR 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. This requirement is fulfilled by
-implementations implementing \s-1IEEE\s0 754 (basically all existing ones).
-.PP
-If you know of other additional requirements drop me a note.
-.SH "COMPILER WARNINGS"
-.IX Header "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.
-.PP
-However, these are unavoidable for many reasons. For one, each compiler
-has different warnings, and each user has different tastes regarding
-warning options. \*(L"Warn-free\*(R" code therefore cannot be a goal except when
-targeting a specific compiler and compiler-version.
-.PP
-Another reason is that some compiler warnings require elaborate
-workarounds, or other changes to the code that make it less clear and less
-maintainable.
-.PP
-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).
-.PP
-While libev is written to generate as few warnings as possible,
-\&\*(L"warn-free\*(R" 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.
-.SH "VALGRIND"
-.IX Header "VALGRIND"
-Valgrind has a special section here because it is a popular tool that is
-highly useful, but valgrind reports are very hard to interpret.
-.PP
-If you think you found a bug (memory leak, uninitialised data access etc.)
-in libev, then check twice: If valgrind reports something like:
-.PP
-.Vb 3
-\&   ==2274==    definitely lost: 0 bytes in 0 blocks.
-\&   ==2274==      possibly lost: 0 bytes in 0 blocks.
-\&   ==2274==    still reachable: 256 bytes in 1 blocks.
-.Ve
-.PP
-Then there is no memory leak. Similarly, under some circumstances,
-valgrind might report kernel bugs as if it were a bug in libev, or it
-might be confused (it is a very good tool, but only a tool).
-.PP
-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. However, don't be annoyed when you get a brisk \*(L"this is
-no bug\*(R" answer and take the chance of learning how to interpret valgrind
-properly.
-.PP
-If you need, for some reason, empty reports from valgrind for your project
-I suggest using suppression lists.
 .SH "AUTHOR"
 .IX Header "AUTHOR"
 Marc Lehmann <libev@schmorp.de>.

Diff Legend

-–
+Removed lines
-+
+Added lines
-<
+Changed lines
->
+Changed lines

Comparing libev/ev.3 (file contents): Revision 1.71 by root, Mon Sep 29 03:31:14 2008 UTC vs. Revision 1.72 by root, Tue Oct 21 20:06:52 2008 UTC

Diff Legend

Comparing libev/ev.3 (file contents):
Revision 1.71 by root, Mon Sep 29 03:31:14 2008 UTC vs.
Revision 1.72 by root, Tue Oct 21 20:06:52 2008 UTC