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

Comparing libev/ev.pod (file contents):
Revision 1.277 by root, Thu Dec 31 06:50:17 2009 UTC vs.
Revision 1.284 by root, Sun Mar 14 21:05:52 2010 UTC

 =item C<EVFLAG_SIGNALFD>
 When this flag is specified, then libev will attempt to use the
 I<signalfd> API for it's C<ev_signal> (and C<ev_child>) watchers. This API
-delivers signals synchronously, which makes is both faster and might make
+delivers signals synchronously, which makes it both faster and might make
-it possible to get the queued signal data.
+it possible to get the queued signal data. It can also simplify signal
+handling with threads, as long as you properly block signals in your
+threads that are not interested in handling them.
 Signalfd will not be used by default as this changes your signal mask, and
 there are a lot of shoddy libraries and programs (glib's threadpool for
 example) that can't properly initialise their signal masks.
 So when you encounter spurious, unexplained daemon exits, make sure you
 ignore SIGPIPE (and maybe make sure you log the exit status of your daemon
 somewhere, as that would have given you a big clue).
+=head3 The special problem of accept()ing when you can't
+Many implementations of the POSIX C<accept> function (for example,
+found in port-2004 Linux) have the peculiar behaviour of not removing a
+connection from the pending queue in all error cases.
+For example, larger servers often run out of file descriptors (because
+of resource limits), causing C<accept> to fail with C<ENFILE> but not
+rejecting the connection, leading to libev signalling readiness on
+the next iteration again (the connection still exists after all), and
+typically causing the program to loop at 100% CPU usage.
+Unfortunately, the set of errors that cause this issue differs between
+operating systems, there is usually little the app can do to remedy the
+situation, and no known thread-safe method of removing the connection to
+cope with overload is known (to me).
+One of the easiest ways to handle this situation is to just ignore it
+- when the program encounters an overload, it will just loop until the
+situation is over. While this is a form of busy waiting, no OS offers an
+event-based way to handle this situation, so it's the best one can do.
+A better way to handle the situation is to log any errors other than
+C<EAGAIN> and C<EWOULDBLOCK>, making sure not to flood the log with such
+messages, and continue as usual, which at least gives the user an idea of
+what could be wrong ("raise the ulimit!"). For extra points one could stop
+the C<ev_io> watcher on the listening fd "for a while", which reduces CPU
+usage.
+If your program is single-threaded, then you could also keep a dummy file
+descriptor for overload situations (e.g. by opening F</dev/null>), and
+when you run into C<ENFILE> or C<EMFILE>, close it, run C<accept>,
+close that fd, and create a new dummy fd. This will gracefully refuse
+clients under typical overload conditions.
+The last way to handle it is to simply log the error and C<exit>, as
+is often done with C<malloc> failures, but this results in an easy
+opportunity for a DoS attack.
 =head3 Watcher-Specific Functions
 =over 4
 Returns the remaining time until a timer fires. If the timer is active,
 then this time is relative to the current event loop time, otherwise it's
 the timeout value currently configured.
 That is, after an C<ev_timer_set (w, 5, 7)>, C<ev_timer_remaining> returns
-C<5>. When the timer is started and one second passes, C<ev_timer_remain>
+C<5>. When the timer is started and one second passes, C<ev_timer_remaining>
 will return C<4>. When the timer expires and is restarted, it will return
 roughly C<7> (likely slightly less as callback invocation takes some time,
 too), and so on.
 =item ev_tstamp repeat [read-write]
 In current versions of libev, the signal will not be blocked indefinitely
 unless you use the C<signalfd> API (C<EV_SIGNALFD>). While this reduces
 the window of opportunity for problems, it will not go away, as libev
 I<has> to modify the signal mask, at least temporarily.
-So I can't stress this enough I<if you do not reset your signal mask
+So I can't stress this enough: I<If you do not reset your signal mask when
-when you expect it to be empty, you have a race condition in your
+you expect it to be empty, you have a race condition in your code>. This
-program>. This is not a libev-specific thing, this is true for most event
+is not a libev-specific thing, this is true for most event libraries.
-libraries.
 =head3 Watcher-Specific Functions and Data Members
 =over 4
 Erkki Seppala has written Ocaml bindings for libev, to be found at
 L<http://modeemi.cs.tut.fi/~flux/software/ocaml-ev/>.
 =item Lua
-Brian Maher has written a partial interface to libev
+Brian Maher has written a partial interface to libev for lua (at the
-for lua (only C<ev_io> and C<ev_timer>), to be found at
+time of this writing, only C<ev_io> and C<ev_timer>), to be found at
 L<http://github.com/brimworks/lua-ev>.
 =back
    libev.m4
 =head2 PREPROCESSOR SYMBOLS/MACROS
 Libev can be configured via a variety of preprocessor symbols you have to
-define before including any of its files. The default in the absence of
+define before including (or compiling) any of its files. The default in
-autoconf is documented for every option.
+the absence of autoconf is documented for every option.
+Symbols marked with "(h)" do not change the ABI, and can have different
+values when compiling libev vs. including F<ev.h>, so it is permissible
+to redefine them before including F<ev.h> without breakign compatibility
+to a compiled library. All other symbols change the ABI, which means all
+users of libev and the libev code itself must be compiled with compatible
+settings.
 =over 4
-=item EV_STANDALONE
+=item EV_STANDALONE (h)
 Must always be C<1> if you do not use autoconf configuration, which
 keeps libev from including F<config.h>, and it also defines dummy
 implementations for some libevent functions (such as logging, which is not
 supported). It will also not define any of the structs usually found in
 as well as for signal and thread safety in C<ev_async> watchers.
 In the absence of this define, libev will use C<sig_atomic_t volatile>
 (from F<signal.h>), which is usually good enough on most platforms.
-=item EV_H
+=item EV_H (h)
 The name of the F<ev.h> header file used to include it. The default if
 undefined is C<"ev.h"> in F<event.h>, F<ev.c> and F<ev++.h>. This can be
 used to virtually rename the F<ev.h> header file in case of conflicts.
-=item EV_CONFIG_H
+=item EV_CONFIG_H (h)
 If C<EV_STANDALONE> isn't C<1>, this variable can be used to override
 F<ev.c>'s idea of where to find the F<config.h> file, similarly to
 C<EV_H>, above.
-=item EV_EVENT_H
+=item EV_EVENT_H (h)
 Similarly to C<EV_H>, this macro can be used to override F<event.c>'s idea
 of how the F<event.h> header can be found, the default is C<"event.h">.
-=item EV_PROTOTYPES
+=item EV_PROTOTYPES (h)
 If defined to be C<0>, then F<ev.h> will not define any function
 prototypes, but still define all the structs and other symbols. This is
 occasionally useful if you want to provide your own wrapper functions
 around libev functions.
 fine.
 If your embedding application does not need any priorities, defining these
 both to C<0> will save some memory and CPU.
-=item EV_PERIODIC_ENABLE
+=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 C<1>, then periodic timers are supported. If
+If undefined or defined to be C<1> (and the platform supports it), then
-defined to be C<0>, then they are not. Disabling them saves a few kB of
+the respective watcher type is supported. If defined to be C<0>, then it
-code.
+is not. Disabling watcher types mainly saves codesize.
-=item EV_IDLE_ENABLE
-If undefined or defined to be C<1>, then idle watchers are supported. If
-defined to be C<0>, then they are not. Disabling them saves a few kB of
-code.
-=item EV_EMBED_ENABLE
-If undefined or defined to be C<1>, then embed watchers are supported. If
-defined to be C<0>, then they are not. Embed watchers rely on most other
-watcher types, which therefore must not be disabled.
-=item EV_STAT_ENABLE
-If undefined or defined to be C<1>, then stat watchers are supported. If
-defined to be C<0>, then they are not.
-=item EV_FORK_ENABLE
-If undefined or defined to be C<1>, then fork watchers are supported. If
-defined to be C<0>, then they are not.
-=item EV_ASYNC_ENABLE
-If undefined or defined to be C<1>, then async watchers are supported. If
-defined to be C<0>, then they are not.
 =item EV_MINIMAL
 If you need to shave off some kilobytes of code at the expense of some
 speed (but with the full API), define this symbol to C<1>. Currently this
 on amd64. It also selects a much smaller 2-heap for timer management over
 the default 4-heap.
 You can save even more by disabling watcher types you do not need
 and setting C<EV_MAXPRI> == C<EV_MINPRI>. Also, disabling C<assert>
-(C<-DNDEBUG>) will usually reduce code size a lot.
+(C<-DNDEBUG>) will usually reduce code size a lot. Disabling inotify,
+eventfd and signalfd will further help, and disabling backends one doesn't
+need (e.g. poll, epoll, kqueue, ports) will help further.
 Defining C<EV_MINIMAL> to C<2> will additionally reduce the core API to
 provide a bare-bones event library. See C<ev.h> for details on what parts
 of the API are still available, and do not complain if this subset changes
 over time.
+This example set of settings reduces the compiled size of libev from
+23.9Kb to 7.7Kb on my GNU/Linux amd64 system (and leaves little
+in - there is also an effect on the amount of memory used). With
+an intelligent-enough linker (gcc+binutils do this when you use
+C<-Wl,--gc-sections -ffunction-sections>) further unused functions might
+be left out as well automatically - a binary starting a timer and an I/O
+watcher then might come out at only 5Kb.
+   // tuning and API changes
+   #define EV_MINIMAL 2
+   #define EV_MULTIPLICITY 0
+   #define EV_MINPRI 0
+   #define EV_MAXPRI 0
+   // OS-specific backends
+   #define EV_USE_INOTIFY 0
+   #define EV_USE_EVENTFD 0
+   #define EV_USE_SIGNALFD 0
+   #define EV_USE_REALTIME 0
+   #define EV_USE_MONOTONIC 0
+   #define EV_USE_CLOCK_SYSCALL 0
+   // disable all backends except select
+   #define EV_USE_POLL 0
+   #define EV_USE_PORT 0
+   #define EV_USE_KQUEUE 0
+   #define EV_USE_EPOLL 0
+   // disable all watcher types that cna be disabled
+   #define EV_STAT_ENABLE 0
+   #define EV_PERIODIC_ENABLE 0
+   #define EV_IDLE_ENABLE 0
+   #define EV_CHECK_ENABLE 0
+   #define EV_PREPARE_ENABLE 0
+   #define EV_FORK_ENABLE 0
+   #define EV_SIGNAL_ENABLE 0
+   #define EV_CHILD_ENABLE 0
+   #define EV_ASYNC_ENABLE 0
+   #define EV_EMBED_ENABLE 0
+=item EV_AVOID_STDIO
+If this is set to C<1> at compiletime, then libev will avoid using stdio
+functions (printf, scanf, perror etc.). This will increase the codesize
+somewhat, but if your program doesn't otherwise depend on stdio and your
+libc allows it, this avoids linking in the stdio library which is quite
+big.
+Note that error messages might become less precise when this option is
+enabled.
 =item EV_NSIG
 The highest supported signal number, +1 (or, the number of
 signals): Normally, libev tries to deduce the maximum number of signals

Diff Legend

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

Comparing libev/ev.pod (file contents): Revision 1.277 by root, Thu Dec 31 06:50:17 2009 UTC vs. Revision 1.284 by root, Sun Mar 14 21:05:52 2010 UTC

Diff Legend

Comparing libev/ev.pod (file contents):
Revision 1.277 by root, Thu Dec 31 06:50:17 2009 UTC vs.
Revision 1.284 by root, Sun Mar 14 21:05:52 2010 UTC