ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/libev/ev.pod
(Generate patch)

Comparing libev/ev.pod (file contents):
Revision 1.280 by sf-exg, Tue Feb 16 12:17:57 2010 UTC vs.
Revision 1.284 by root, Sun Mar 14 21:05:52 2010 UTC

… …
1538 1538
1539So when you encounter spurious, unexplained daemon exits, make sure you 1539So when you encounter spurious, unexplained daemon exits, make sure you
1540ignore SIGPIPE (and maybe make sure you log the exit status of your daemon 1540ignore SIGPIPE (and maybe make sure you log the exit status of your daemon
1541somewhere, as that would have given you a big clue). 1541somewhere, as that would have given you a big clue).
1542 1542
1543=head3 The special problem of accept()ing when you can't
1544
1545Many implementations of the POSIX C<accept> function (for example,
1546found in port-2004 Linux) have the peculiar behaviour of not removing a
1547connection from the pending queue in all error cases.
1548
1549For example, larger servers often run out of file descriptors (because
1550of resource limits), causing C<accept> to fail with C<ENFILE> but not
1551rejecting the connection, leading to libev signalling readiness on
1552the next iteration again (the connection still exists after all), and
1553typically causing the program to loop at 100% CPU usage.
1554
1555Unfortunately, the set of errors that cause this issue differs between
1556operating systems, there is usually little the app can do to remedy the
1557situation, and no known thread-safe method of removing the connection to
1558cope with overload is known (to me).
1559
1560One of the easiest ways to handle this situation is to just ignore it
1561- when the program encounters an overload, it will just loop until the
1562situation is over. While this is a form of busy waiting, no OS offers an
1563event-based way to handle this situation, so it's the best one can do.
1564
1565A better way to handle the situation is to log any errors other than
1566C<EAGAIN> and C<EWOULDBLOCK>, making sure not to flood the log with such
1567messages, and continue as usual, which at least gives the user an idea of
1568what could be wrong ("raise the ulimit!"). For extra points one could stop
1569the C<ev_io> watcher on the listening fd "for a while", which reduces CPU
1570usage.
1571
1572If your program is single-threaded, then you could also keep a dummy file
1573descriptor for overload situations (e.g. by opening F</dev/null>), and
1574when you run into C<ENFILE> or C<EMFILE>, close it, run C<accept>,
1575close that fd, and create a new dummy fd. This will gracefully refuse
1576clients under typical overload conditions.
1577
1578The last way to handle it is to simply log the error and C<exit>, as
1579is often done with C<malloc> failures, but this results in an easy
1580opportunity for a DoS attack.
1543 1581
1544=head3 Watcher-Specific Functions 1582=head3 Watcher-Specific Functions
1545 1583
1546=over 4 1584=over 4
1547 1585
… …
3617 libev.m4 3655 libev.m4
3618 3656
3619=head2 PREPROCESSOR SYMBOLS/MACROS 3657=head2 PREPROCESSOR SYMBOLS/MACROS
3620 3658
3621Libev can be configured via a variety of preprocessor symbols you have to 3659Libev can be configured via a variety of preprocessor symbols you have to
3622define before including any of its files. The default in the absence of 3660define before including (or compiling) any of its files. The default in
3623autoconf is documented for every option. 3661the absence of autoconf is documented for every option.
3662
3663Symbols marked with "(h)" do not change the ABI, and can have different
3664values when compiling libev vs. including F<ev.h>, so it is permissible
3665to redefine them before including F<ev.h> without breakign compatibility
3666to a compiled library. All other symbols change the ABI, which means all
3667users of libev and the libev code itself must be compiled with compatible
3668settings.
3624 3669
3625=over 4 3670=over 4
3626 3671
3627=item EV_STANDALONE 3672=item EV_STANDALONE (h)
3628 3673
3629Must always be C<1> if you do not use autoconf configuration, which 3674Must always be C<1> if you do not use autoconf configuration, which
3630keeps libev from including F<config.h>, and it also defines dummy 3675keeps libev from including F<config.h>, and it also defines dummy
3631implementations for some libevent functions (such as logging, which is not 3676implementations for some libevent functions (such as logging, which is not
3632supported). It will also not define any of the structs usually found in 3677supported). It will also not define any of the structs usually found in
… …
3782as well as for signal and thread safety in C<ev_async> watchers. 3827as well as for signal and thread safety in C<ev_async> watchers.
3783 3828
3784In the absence of this define, libev will use C<sig_atomic_t volatile> 3829In the absence of this define, libev will use C<sig_atomic_t volatile>
3785(from F<signal.h>), which is usually good enough on most platforms. 3830(from F<signal.h>), which is usually good enough on most platforms.
3786 3831
3787=item EV_H 3832=item EV_H (h)
3788 3833
3789The name of the F<ev.h> header file used to include it. The default if 3834The name of the F<ev.h> header file used to include it. The default if
3790undefined is C<"ev.h"> in F<event.h>, F<ev.c> and F<ev++.h>. This can be 3835undefined is C<"ev.h"> in F<event.h>, F<ev.c> and F<ev++.h>. This can be
3791used to virtually rename the F<ev.h> header file in case of conflicts. 3836used to virtually rename the F<ev.h> header file in case of conflicts.
3792 3837
3793=item EV_CONFIG_H 3838=item EV_CONFIG_H (h)
3794 3839
3795If C<EV_STANDALONE> isn't C<1>, this variable can be used to override 3840If C<EV_STANDALONE> isn't C<1>, this variable can be used to override
3796F<ev.c>'s idea of where to find the F<config.h> file, similarly to 3841F<ev.c>'s idea of where to find the F<config.h> file, similarly to
3797C<EV_H>, above. 3842C<EV_H>, above.
3798 3843
3799=item EV_EVENT_H 3844=item EV_EVENT_H (h)
3800 3845
3801Similarly to C<EV_H>, this macro can be used to override F<event.c>'s idea 3846Similarly to C<EV_H>, this macro can be used to override F<event.c>'s idea
3802of how the F<event.h> header can be found, the default is C<"event.h">. 3847of how the F<event.h> header can be found, the default is C<"event.h">.
3803 3848
3804=item EV_PROTOTYPES 3849=item EV_PROTOTYPES (h)
3805 3850
3806If defined to be C<0>, then F<ev.h> will not define any function 3851If defined to be C<0>, then F<ev.h> will not define any function
3807prototypes, but still define all the structs and other symbols. This is 3852prototypes, but still define all the structs and other symbols. This is
3808occasionally useful if you want to provide your own wrapper functions 3853occasionally useful if you want to provide your own wrapper functions
3809around libev functions. 3854around libev functions.
… …
3831fine. 3876fine.
3832 3877
3833If your embedding application does not need any priorities, defining these 3878If your embedding application does not need any priorities, defining these
3834both to C<0> will save some memory and CPU. 3879both to C<0> will save some memory and CPU.
3835 3880
3836=item EV_PERIODIC_ENABLE 3881=item EV_PERIODIC_ENABLE, EV_IDLE_ENABLE, EV_EMBED_ENABLE, EV_STAT_ENABLE,
3882EV_PREPARE_ENABLE, EV_CHECK_ENABLE, EV_FORK_ENABLE, EV_SIGNAL_ENABLE,
3883EV_ASYNC_ENABLE, EV_CHILD_ENABLE.
3837 3884
3838If undefined or defined to be C<1>, then periodic timers are supported. If 3885If undefined or defined to be C<1> (and the platform supports it), then
3839defined to be C<0>, then they are not. Disabling them saves a few kB of 3886the respective watcher type is supported. If defined to be C<0>, then it
3840code. 3887is not. Disabling watcher types mainly saves codesize.
3841
3842=item EV_IDLE_ENABLE
3843
3844If undefined or defined to be C<1>, then idle watchers are supported. If
3845defined to be C<0>, then they are not. Disabling them saves a few kB of
3846code.
3847
3848=item EV_EMBED_ENABLE
3849
3850If undefined or defined to be C<1>, then embed watchers are supported. If
3851defined to be C<0>, then they are not. Embed watchers rely on most other
3852watcher types, which therefore must not be disabled.
3853
3854=item EV_STAT_ENABLE
3855
3856If undefined or defined to be C<1>, then stat watchers are supported. If
3857defined to be C<0>, then they are not.
3858
3859=item EV_FORK_ENABLE
3860
3861If undefined or defined to be C<1>, then fork watchers are supported. If
3862defined to be C<0>, then they are not.
3863
3864=item EV_ASYNC_ENABLE
3865
3866If undefined or defined to be C<1>, then async watchers are supported. If
3867defined to be C<0>, then they are not.
3868 3888
3869=item EV_MINIMAL 3889=item EV_MINIMAL
3870 3890
3871If you need to shave off some kilobytes of code at the expense of some 3891If you need to shave off some kilobytes of code at the expense of some
3872speed (but with the full API), define this symbol to C<1>. Currently this 3892speed (but with the full API), define this symbol to C<1>. Currently this
… …
3874on amd64. It also selects a much smaller 2-heap for timer management over 3894on amd64. It also selects a much smaller 2-heap for timer management over
3875the default 4-heap. 3895the default 4-heap.
3876 3896
3877You can save even more by disabling watcher types you do not need 3897You can save even more by disabling watcher types you do not need
3878and setting C<EV_MAXPRI> == C<EV_MINPRI>. Also, disabling C<assert> 3898and setting C<EV_MAXPRI> == C<EV_MINPRI>. Also, disabling C<assert>
3879(C<-DNDEBUG>) will usually reduce code size a lot. 3899(C<-DNDEBUG>) will usually reduce code size a lot. Disabling inotify,
3900eventfd and signalfd will further help, and disabling backends one doesn't
3901need (e.g. poll, epoll, kqueue, ports) will help further.
3880 3902
3881Defining C<EV_MINIMAL> to C<2> will additionally reduce the core API to 3903Defining C<EV_MINIMAL> to C<2> will additionally reduce the core API to
3882provide a bare-bones event library. See C<ev.h> for details on what parts 3904provide a bare-bones event library. See C<ev.h> for details on what parts
3883of the API are still available, and do not complain if this subset changes 3905of the API are still available, and do not complain if this subset changes
3884over time. 3906over time.
3907
3908This example set of settings reduces the compiled size of libev from
390923.9Kb to 7.7Kb on my GNU/Linux amd64 system (and leaves little
3910in - there is also an effect on the amount of memory used). With
3911an intelligent-enough linker (gcc+binutils do this when you use
3912C<-Wl,--gc-sections -ffunction-sections>) further unused functions might
3913be left out as well automatically - a binary starting a timer and an I/O
3914watcher then might come out at only 5Kb.
3915
3916 // tuning and API changes
3917 #define EV_MINIMAL 2
3918 #define EV_MULTIPLICITY 0
3919 #define EV_MINPRI 0
3920 #define EV_MAXPRI 0
3921
3922 // OS-specific backends
3923 #define EV_USE_INOTIFY 0
3924 #define EV_USE_EVENTFD 0
3925 #define EV_USE_SIGNALFD 0
3926 #define EV_USE_REALTIME 0
3927 #define EV_USE_MONOTONIC 0
3928 #define EV_USE_CLOCK_SYSCALL 0
3929
3930 // disable all backends except select
3931 #define EV_USE_POLL 0
3932 #define EV_USE_PORT 0
3933 #define EV_USE_KQUEUE 0
3934 #define EV_USE_EPOLL 0
3935
3936 // disable all watcher types that cna be disabled
3937 #define EV_STAT_ENABLE 0
3938 #define EV_PERIODIC_ENABLE 0
3939 #define EV_IDLE_ENABLE 0
3940 #define EV_CHECK_ENABLE 0
3941 #define EV_PREPARE_ENABLE 0
3942 #define EV_FORK_ENABLE 0
3943 #define EV_SIGNAL_ENABLE 0
3944 #define EV_CHILD_ENABLE 0
3945 #define EV_ASYNC_ENABLE 0
3946 #define EV_EMBED_ENABLE 0
3947
3948=item EV_AVOID_STDIO
3949
3950If this is set to C<1> at compiletime, then libev will avoid using stdio
3951functions (printf, scanf, perror etc.). This will increase the codesize
3952somewhat, but if your program doesn't otherwise depend on stdio and your
3953libc allows it, this avoids linking in the stdio library which is quite
3954big.
3955
3956Note that error messages might become less precise when this option is
3957enabled.
3885 3958
3886=item EV_NSIG 3959=item EV_NSIG
3887 3960
3888The highest supported signal number, +1 (or, the number of 3961The highest supported signal number, +1 (or, the number of
3889signals): Normally, libev tries to deduce the maximum number of signals 3962signals): Normally, libev tries to deduce the maximum number of signals

Diff Legend

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