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

Comparing libev/ev.pod (file contents):
Revision 1.283 by root, Wed Mar 10 09:18:25 2010 UTC vs.
Revision 1.285 by root, Tue Mar 16 00:20:17 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
3846 3884
3847If undefined or defined to be C<1> (and the platform supports it), then 3885If undefined or defined to be C<1> (and the platform supports it), then
3848the respective watcher type is supported. If defined to be C<0>, then it 3886the respective watcher type is supported. If defined to be C<0>, then it
3849is not. Disabling watcher types mainly saves codesize. 3887is not. Disabling watcher types mainly saves codesize.
3850 3888
3851=item EV_MINIMAL 3889=item EV_FEATURES
3852 3890
3853If 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
3854speed (but with the full API), define this symbol to C<1>. Currently this 3892speed (but with the full API), you can define this symbol to request
3855is used to override some inlining decisions, saves roughly 30% code size 3893certain subsets of functionality. The default is to enable all features
3856on amd64. It also selects a much smaller 2-heap for timer management over 3894that can be enabled on the platform.
3857the default 4-heap.
3858 3895
3859You can save even more by disabling watcher types you do not need 3896Note that using autoconf will usually override most of the features, so
3860and setting C<EV_MAXPRI> == C<EV_MINPRI>. Also, disabling C<assert> 3897using this symbol makes sense mostly when embedding libev.
3861(C<-DNDEBUG>) will usually reduce code size a lot. Disabling inotify,
3862eventfd and signalfd will further help, and disabling backends one doesn't
3863need (e.g. poll, epoll, kqueue, ports) will help further.
3864 3898
3865Defining C<EV_MINIMAL> to C<2> will additionally reduce the core API to 3899A typical way to use this symbol is to define it to C<0> (or to a bitset
3866provide a bare-bones event library. See C<ev.h> for details on what parts 3900with some broad features you want) and then selectively re-enable
3867of the API are still available, and do not complain if this subset changes 3901additional parts you want, for example if you want everything minimal,
3868over time. 3902but multiple event loop support, async and child watchers and the poll
3903backend, use this:
3869 3904
3870This example set of settings reduces the compiled size of libev from 3905 #define EV_FEATURES 0
387123.9Kb to 7.7Kb on my GNU/Linux amd64 system (and leaves little
3872in - there is also an effect on the amount of memory used). With
3873an intelligent-enough linker (gcc+binutils do this when you use
3874C<-Wl,--gc-sections -ffunction-sections>) further unused functions might
3875be left out as well automatically - a binary starting a timer and an I/O
3876watcher then might come out at only 5Kb.
3877
3878 // tuning and API changes
3879 #define EV_MINIMAL 2
3880 #define EV_MULTIPLICITY 0 3906 #define EV_MULTIPLICITY 1
3881 #define EV_MINPRI 0
3882 #define EV_MAXPRI 0
3883
3884 // OS-specific backends
3885 #define EV_USE_INOTIFY 0
3886 #define EV_USE_EVENTFD 0
3887 #define EV_USE_SIGNALFD 0
3888 #define EV_USE_REALTIME 0
3889 #define EV_USE_MONOTONIC 0
3890 #define EV_USE_CLOCK_SYSCALL 0
3891
3892 // disable all backends except select
3893 #define EV_USE_POLL 0 3907 #define EV_USE_POLL 1
3894 #define EV_USE_PORT 0
3895 #define EV_USE_KQUEUE 0
3896 #define EV_USE_EPOLL 0
3897
3898 // disable all watcher types that cna be disabled
3899 #define EV_STAT_ENABLE 0
3900 #define EV_PERIODIC_ENABLE 0
3901 #define EV_IDLE_ENABLE 0
3902 #define EV_CHECK_ENABLE 0
3903 #define EV_PREPARE_ENABLE 0
3904 #define EV_FORK_ENABLE 0
3905 #define EV_SIGNAL_ENABLE 0
3906 #define EV_CHILD_ENABLE 0 3908 #define EV_CHILD_ENABLE 1
3907 #define EV_ASYNC_ENABLE 0 3909 #define EV_ASYNC_ENABLE 1
3908 #define EV_EMBED_ENABLE 0 3910
3911The actual value is a bitset, it can be a combination of the following
3912values:
3913
3914=over 4
3915
3916=item C<1> - faster/larger code
3917
3918Use larger code to speed up some operations.
3919
3920Currently this is used to override some inlining decisions (enlarging the roughly
392130% code size on amd64.
3922
3923Also disables C<assert>'s in the code, unless you define C<NDEBUG>
3924explicitly to C<0>.
3925
3926Use of compiler flags such as C<-Os> with gcc that optimise for size are
3927recommended when disabling this feature.
3928
3929=item C<2> - faster/larger data structures
3930
3931Replaces the small 2-heap for timer management by a faster 4-heap, larger
3932hash table sizes and so on. This will usually further increase codesize
3933and can additionally have an effect on the size of data structures at
3934runtime.
3935
3936=item C<4> - full API configuration
3937
3938This enables priorities (sets C<EV_MAXPRI>=2 and C<EV_MINPRI>=-2), and
3939enables multiplicity (C<EV_MULTIPLICITY>=1).
3940
3941It also enables a lot of the "lesser used" core API functions. See C<ev.h>
3942for details on which parts of the API are still available without this
3943feature, and do not complain if this subset changes over time.
3944
3945=item C<8> - enable all optional watcher types
3946
3947Enables all optional watcher types. If you want to selectively enable
3948only some watcher types other than I/O and timers (e.g. prepare,
3949embed, async, child...) you can enable them manually by defining
3950C<EV_watchertype_ENABLE> to C<1> instead.
3951
3952=item C<16> - enable all backends
3953
3954This enables all backends - without this feature, you need to enable at
3955least one backend manually (C<EV_USE_SELECT> is a good choice).
3956
3957=item C<32> - enable OS-specific "helper" APIs
3958
3959Enable inotify, eventfd, signalfd and similar OS-specific helper APIs by
3960default.
3961
3962=back
3963
3964Compiling with C<gcc -Os -DEV_STANDALONE -DEV_USE_EPOLL=1 -DEV_FEATURES=0>
3965reduces the compiled size of libev from 24.7Kb to 6.5Kb on my GNU/Linux
3966amd64 system, while still giving you I/O watchers, timers and monotonic
3967clock support.
3968
3969With an intelligent-enough linker (gcc+binutils are intelligent enough
3970when you use C<-Wl,--gc-sections -ffunction-sections>) functions unused by
3971your program might be left out as well - a binary starting a timer and an
3972I/O watcher then might come out at only 5Kb.
3909 3973
3910=item EV_AVOID_STDIO 3974=item EV_AVOID_STDIO
3911 3975
3912If this is set to C<1> at compiletime, then libev will avoid using stdio 3976If this is set to C<1> at compiletime, then libev will avoid using stdio
3913functions (printf, scanf, perror etc.). This will increase the codesize 3977functions (printf, scanf, perror etc.). This will increase the codesize
3928statically allocates some 12-24 bytes per signal number. 3992statically allocates some 12-24 bytes per signal number.
3929 3993
3930=item EV_PID_HASHSIZE 3994=item EV_PID_HASHSIZE
3931 3995
3932C<ev_child> watchers use a small hash table to distribute workload by 3996C<ev_child> watchers use a small hash table to distribute workload by
3933pid. The default size is C<16> (or C<1> with C<EV_MINIMAL>), usually more 3997pid. The default size is C<16> (or C<1> with C<EV_FEATURES> disabled),
3934than enough. If you need to manage thousands of children you might want to 3998usually more than enough. If you need to manage thousands of children you
3935increase this value (I<must> be a power of two). 3999might want to increase this value (I<must> be a power of two).
3936 4000
3937=item EV_INOTIFY_HASHSIZE 4001=item EV_INOTIFY_HASHSIZE
3938 4002
3939C<ev_stat> watchers use a small hash table to distribute workload by 4003C<ev_stat> watchers use a small hash table to distribute workload by
3940inotify watch id. The default size is C<16> (or C<1> with C<EV_MINIMAL>), 4004inotify watch id. The default size is C<16> (or C<1> with C<EV_FEATURES>
3941usually more than enough. If you need to manage thousands of C<ev_stat> 4005disabled), usually more than enough. If you need to manage thousands of
3942watchers you might want to increase this value (I<must> be a power of 4006C<ev_stat> watchers you might want to increase this value (I<must> be a
3943two). 4007power of two).
3944 4008
3945=item EV_USE_4HEAP 4009=item EV_USE_4HEAP
3946 4010
3947Heaps are not very cache-efficient. To improve the cache-efficiency of the 4011Heaps are not very cache-efficient. To improve the cache-efficiency of the
3948timer and periodics heaps, libev uses a 4-heap when this symbol is defined 4012timer and periodics heaps, libev uses a 4-heap when this symbol is defined
3949to C<1>. The 4-heap uses more complicated (longer) code but has noticeably 4013to C<1>. The 4-heap uses more complicated (longer) code but has noticeably
3950faster performance with many (thousands) of watchers. 4014faster performance with many (thousands) of watchers.
3951 4015
3952The default is C<1> unless C<EV_MINIMAL> is set in which case it is C<0> 4016The default is C<1>, unless C<EV_FEATURES> overrides it, in which case it
3953(disabled). 4017will be C<0>.
3954 4018
3955=item EV_HEAP_CACHE_AT 4019=item EV_HEAP_CACHE_AT
3956 4020
3957Heaps are not very cache-efficient. To improve the cache-efficiency of the 4021Heaps are not very cache-efficient. To improve the cache-efficiency of the
3958timer and periodics heaps, libev can cache the timestamp (I<at>) within 4022timer and periodics heaps, libev can cache the timestamp (I<at>) within
3959the heap structure (selected by defining C<EV_HEAP_CACHE_AT> to C<1>), 4023the heap structure (selected by defining C<EV_HEAP_CACHE_AT> to C<1>),
3960which uses 8-12 bytes more per watcher and a few hundred bytes more code, 4024which uses 8-12 bytes more per watcher and a few hundred bytes more code,
3961but avoids random read accesses on heap changes. This improves performance 4025but avoids random read accesses on heap changes. This improves performance
3962noticeably with many (hundreds) of watchers. 4026noticeably with many (hundreds) of watchers.
3963 4027
3964The default is C<1> unless C<EV_MINIMAL> is set in which case it is C<0> 4028The default is C<1>, unless C<EV_FEATURES> overrides it, in which case it
3965(disabled). 4029will be C<0>.
3966 4030
3967=item EV_VERIFY 4031=item EV_VERIFY
3968 4032
3969Controls how much internal verification (see C<ev_loop_verify ()>) will 4033Controls how much internal verification (see C<ev_loop_verify ()>) will
3970be done: If set to C<0>, no internal verification code will be compiled 4034be done: If set to C<0>, no internal verification code will be compiled
3972called. If set to C<2>, then the internal verification code will be 4036called. If set to C<2>, then the internal verification code will be
3973called once per loop, which can slow down libev. If set to C<3>, then the 4037called once per loop, which can slow down libev. If set to C<3>, then the
3974verification code will be called very frequently, which will slow down 4038verification code will be called very frequently, which will slow down
3975libev considerably. 4039libev considerably.
3976 4040
3977The default is C<1>, unless C<EV_MINIMAL> is set, in which case it will be 4041The default is C<1>, unless C<EV_FEATURES> overrides it, in which case it
3978C<0>. 4042will be C<0>.
3979 4043
3980=item EV_COMMON 4044=item EV_COMMON
3981 4045
3982By default, all watchers have a C<void *data> member. By redefining 4046By default, all watchers have a C<void *data> member. By redefining
3983this macro to a something else you can include more and other types of 4047this macro to a something else you can include more and other types of
4041file. 4105file.
4042 4106
4043The usage in rxvt-unicode is simpler. It has a F<ev_cpp.h> header file 4107The usage in rxvt-unicode is simpler. It has a F<ev_cpp.h> header file
4044that everybody includes and which overrides some configure choices: 4108that everybody includes and which overrides some configure choices:
4045 4109
4046 #define EV_MINIMAL 1 4110 #define EV_FEATURES 0
4047 #define EV_USE_POLL 0 4111 #define EV_USE_SELECT 1
4048 #define EV_MULTIPLICITY 0
4049 #define EV_PERIODIC_ENABLE 0
4050 #define EV_STAT_ENABLE 0
4051 #define EV_FORK_ENABLE 0
4052 #define EV_CONFIG_H <config.h> 4112 #define EV_CONFIG_H <config.h>
4053 #define EV_MINPRI 0
4054 #define EV_MAXPRI 0
4055 4113
4056 #include "ev++.h" 4114 #include "ev++.h"
4057 4115
4058And a F<ev_cpp.C> implementation file that contains libev proper and is compiled: 4116And a F<ev_cpp.C> implementation file that contains libev proper and is compiled:
4059 4117

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines