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

Comparing libev/ev.pod (file contents):
Revision 1.284 by root, Sun Mar 14 21:05:52 2010 UTC vs.
Revision 1.285 by root, Tue Mar 16 00:20:17 2010 UTC

3884 3884
3885If 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
3886the 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
3887is not. Disabling watcher types mainly saves codesize. 3887is not. Disabling watcher types mainly saves codesize.
3888 3888
3889=item EV_MINIMAL 3889=item EV_FEATURES
3890 3890
3891If 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
3892speed (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
3893is used to override some inlining decisions, saves roughly 30% code size 3893certain subsets of functionality. The default is to enable all features
3894on amd64. It also selects a much smaller 2-heap for timer management over 3894that can be enabled on the platform.
3895the default 4-heap.
3896 3895
3897You can save even more by disabling watcher types you do not need 3896Note that using autoconf will usually override most of the features, so
3898and setting C<EV_MAXPRI> == C<EV_MINPRI>. Also, disabling C<assert> 3897using this symbol makes sense mostly when embedding libev.
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.
3902 3898
3903Defining 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
3904provide 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
3905of the API are still available, and do not complain if this subset changes 3901additional parts you want, for example if you want everything minimal,
3906over time. 3902but multiple event loop support, async and child watchers and the poll
3903backend, use this:
3907 3904
3908This example set of settings reduces the compiled size of libev from 3905 #define EV_FEATURES 0
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 3906 #define EV_MULTIPLICITY 1
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 3907 #define EV_USE_POLL 1
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 3908 #define EV_CHILD_ENABLE 1
3945 #define EV_ASYNC_ENABLE 0 3909 #define EV_ASYNC_ENABLE 1
3946 #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.
3947 3973
3948=item EV_AVOID_STDIO 3974=item EV_AVOID_STDIO
3949 3975
3950If 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
3951functions (printf, scanf, perror etc.). This will increase the codesize 3977functions (printf, scanf, perror etc.). This will increase the codesize
3966statically allocates some 12-24 bytes per signal number. 3992statically allocates some 12-24 bytes per signal number.
3967 3993
3968=item EV_PID_HASHSIZE 3994=item EV_PID_HASHSIZE
3969 3995
3970C<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
3971pid. 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),
3972than 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
3973increase this value (I<must> be a power of two). 3999might want to increase this value (I<must> be a power of two).
3974 4000
3975=item EV_INOTIFY_HASHSIZE 4001=item EV_INOTIFY_HASHSIZE
3976 4002
3977C<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
3978inotify 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>
3979usually 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
3980watchers 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
3981two). 4007power of two).
3982 4008
3983=item EV_USE_4HEAP 4009=item EV_USE_4HEAP
3984 4010
3985Heaps 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
3986timer 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
3987to 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
3988faster performance with many (thousands) of watchers. 4014faster performance with many (thousands) of watchers.
3989 4015
3990The 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
3991(disabled). 4017will be C<0>.
3992 4018
3993=item EV_HEAP_CACHE_AT 4019=item EV_HEAP_CACHE_AT
3994 4020
3995Heaps 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
3996timer and periodics heaps, libev can cache the timestamp (I<at>) within 4022timer and periodics heaps, libev can cache the timestamp (I<at>) within
3997the 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>),
3998which 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,
3999but avoids random read accesses on heap changes. This improves performance 4025but avoids random read accesses on heap changes. This improves performance
4000noticeably with many (hundreds) of watchers. 4026noticeably with many (hundreds) of watchers.
4001 4027
4002The 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
4003(disabled). 4029will be C<0>.
4004 4030
4005=item EV_VERIFY 4031=item EV_VERIFY
4006 4032
4007Controls how much internal verification (see C<ev_loop_verify ()>) will 4033Controls how much internal verification (see C<ev_loop_verify ()>) will
4008be 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
4010called. 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
4011called 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
4012verification code will be called very frequently, which will slow down 4038verification code will be called very frequently, which will slow down
4013libev considerably. 4039libev considerably.
4014 4040
4015The 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
4016C<0>. 4042will be C<0>.
4017 4043
4018=item EV_COMMON 4044=item EV_COMMON
4019 4045
4020By default, all watchers have a C<void *data> member. By redefining 4046By default, all watchers have a C<void *data> member. By redefining
4021this 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
4079file. 4105file.
4080 4106
4081The 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
4082that everybody includes and which overrides some configure choices: 4108that everybody includes and which overrides some configure choices:
4083 4109
4084 #define EV_MINIMAL 1 4110 #define EV_FEATURES 0
4085 #define EV_USE_POLL 0 4111 #define EV_USE_SELECT 1
4086 #define EV_MULTIPLICITY 0
4087 #define EV_PERIODIC_ENABLE 0
4088 #define EV_STAT_ENABLE 0
4089 #define EV_FORK_ENABLE 0
4090 #define EV_CONFIG_H <config.h> 4112 #define EV_CONFIG_H <config.h>
4091 #define EV_MINPRI 0
4092 #define EV_MAXPRI 0
4093 4113
4094 #include "ev++.h" 4114 #include "ev++.h"
4095 4115
4096And 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:
4097 4117

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines