rough EV_FEATURES implementation

1 files changed, 97 insertions, 77 deletions

diff --git a/ev.pod b/ev.pod
index bc2c752..e5a1391 100644
--- a/ev.pod
+++ b/ev.pod
@@ -3886,64 +3886,90 @@ If undefined or defined to be C<1> (and the platform supports it), then
 the respective watcher type is supported. If defined to be C<0>, then it
 is not. Disabling watcher types mainly saves codesize.
 
-=item EV_MINIMAL
+=item EV_FEATURES
 
 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
-is used to override some inlining decisions, saves roughly 30% code size
-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. 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
+speed (but with the full API), you can define this symbol to request
+certain subsets of functionality. The default is to enable all features
+that can be enabled on the platform.
+
+Note that using autoconf will usually override most of the features, so
+using this symbol makes sense mostly when embedding libev.
+
+A typical way to use this symbol is to define it to C<0> (or to a bitset
+with some broad features you want) and then selectively re-enable
+additional parts you want, for example if you want everything minimal,
+but multiple event loop support, async and child watchers and the poll
+backend, use this:
+
+   #define EV_FEATURES 0
+   #define EV_MULTIPLICITY 1
+   #define EV_USE_POLL 1
+   #define EV_CHILD_ENABLE 1
+   #define EV_ASYNC_ENABLE 1
+
+The actual value is a bitset, it can be a combination of the following
+values:
+
+=over 4
+
+=item C<1> - faster/larger code
+
+Use larger code to speed up some operations.
+
+Currently this is used to override some inlining decisions (enlarging the  roughly
+30% code size on amd64.
+
+Also disables C<assert>'s in the code, unless you define C<NDEBUG>
+explicitly to C<0>.
+
+Use of compiler flags such as C<-Os> with gcc that optimise for size are
+recommended when disabling this feature.
+
+=item C<2> - faster/larger data structures
+
+Replaces the small 2-heap for timer management by a faster 4-heap, larger
+hash table sizes and so on. This will usually further increase codesize
+and can additionally have an effect on the size of data structures at
+runtime.
+
+=item C<4> - full API configuration
+
+This enables priorities (sets C<EV_MAXPRI>=2 and C<EV_MINPRI>=-2), and
+enables multiplicity (C<EV_MULTIPLICITY>=1).
+
+It also enables a lot of the "lesser used" core API functions. See C<ev.h>
+for details on which parts of the API are still available without this
+feature, and do not complain if this subset changes over time.
+
+=item C<8> - enable all optional watcher types
+
+Enables all optional watcher types.  If you want to selectively enable
+only some watcher types other than I/O and timers (e.g. prepare,
+embed, async, child...) you can enable them manually by defining
+C<EV_watchertype_ENABLE> to C<1> instead.
+
+=item C<16> - enable all backends
+
+This enables all backends - without this feature, you need to enable at
+least one backend manually (C<EV_USE_SELECT> is a good choice).
+
+=item C<32> - enable OS-specific "helper" APIs
+
+Enable inotify, eventfd, signalfd and similar OS-specific helper APIs by
+default.
+
+=back
+
+Compiling with C<gcc -Os -DEV_STANDALONE -DEV_USE_EPOLL=1 -DEV_FEATURES=0>
+reduces the compiled size of libev from 24.7Kb to 6.5Kb on my GNU/Linux
+amd64 system, while still giving you I/O watchers, timers and monotonic
+clock support.
+
+With an intelligent-enough linker (gcc+binutils are intelligent enough
+when you use C<-Wl,--gc-sections -ffunction-sections>) functions unused by
+your program might be left out as well - a binary starting a timer and an
+I/O watcher then might come out at only 5Kb.
 
 =item EV_AVOID_STDIO
 
@@ -3968,17 +3994,17 @@ statically allocates some 12-24 bytes per signal number.
 =item EV_PID_HASHSIZE
 
 C<ev_child> watchers use a small hash table to distribute workload by
-pid. The default size is C<16> (or C<1> with C<EV_MINIMAL>), usually more
-than enough. If you need to manage thousands of children you might want to
-increase this value (I<must> be a power of two).
+pid. The default size is C<16> (or C<1> with C<EV_FEATURES> disabled),
+usually more than enough. If you need to manage thousands of children you
+might want to increase this value (I<must> be a power of two).
 
 =item EV_INOTIFY_HASHSIZE
 
 C<ev_stat> watchers use a small hash table to distribute workload by
-inotify watch id. The default size is C<16> (or C<1> with C<EV_MINIMAL>),
-usually more than enough. If you need to manage thousands of C<ev_stat>
-watchers you might want to increase this value (I<must> be a power of
-two).
+inotify watch id. The default size is C<16> (or C<1> with C<EV_FEATURES>
+disabled), usually more than enough. If you need to manage thousands of
+C<ev_stat> watchers you might want to increase this value (I<must> be a
+power of two).
 
 =item EV_USE_4HEAP
 
@@ -3987,8 +4013,8 @@ timer and periodics heaps, libev uses a 4-heap when this symbol is defined
 to C<1>. The 4-heap uses more complicated (longer) code but has noticeably
 faster performance with many (thousands) of watchers.
 
-The default is C<1> unless C<EV_MINIMAL> is set in which case it is C<0>
-(disabled).
+The default is C<1>, unless C<EV_FEATURES> overrides it, in which case it
+will be C<0>.
 
 =item EV_HEAP_CACHE_AT
 
@@ -3999,8 +4025,8 @@ which uses 8-12 bytes more per watcher and a few hundred bytes more code,
 but avoids random read accesses on heap changes. This improves performance
 noticeably with many (hundreds) of watchers.
 
-The default is C<1> unless C<EV_MINIMAL> is set in which case it is C<0>
-(disabled).
+The default is C<1>, unless C<EV_FEATURES> overrides it, in which case it
+will be C<0>.
 
 =item EV_VERIFY
 
@@ -4012,8 +4038,8 @@ called once per loop, which can slow down libev. If set to C<3>, then the
 verification code will be called very frequently, which will slow down
 libev considerably.
 
-The default is C<1>, unless C<EV_MINIMAL> is set, in which case it will be
-C<0>.
+The default is C<1>, unless C<EV_FEATURES> overrides it, in which case it
+will be C<0>.
 
 =item EV_COMMON
 
@@ -4081,15 +4107,9 @@ file.
 The usage in rxvt-unicode is simpler. It has a F<ev_cpp.h> header file
 that everybody includes and which overrides some configure choices:
 
-   #define EV_MINIMAL 1
-   #define EV_USE_POLL 0
-   #define EV_MULTIPLICITY 0
-   #define EV_PERIODIC_ENABLE 0
-   #define EV_STAT_ENABLE 0
-   #define EV_FORK_ENABLE 0
+   #define EV_FEATURES 0
+   #define EV_USE_SELECT 1
    #define EV_CONFIG_H <config.h>
-   #define EV_MINPRI 0
-   #define EV_MAXPRI 0
 
    #include "ev++.h"