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

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

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

Diff Legend

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

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

Diff Legend

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