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

Comparing libev/ev.pod (file contents):
Revision 1.282 by root, Wed Mar 10 08:19:39 2010 UTC vs.
Revision 1.285 by root, Tue Mar 16 00:20:17 2010 UTC

…		…
1538		1538
1539	So when you encounter spurious, unexplained daemon exits, make sure you	1539	So when you encounter spurious, unexplained daemon exits, make sure you
1540	ignore SIGPIPE (and maybe make sure you log the exit status of your daemon	1540	ignore SIGPIPE (and maybe make sure you log the exit status of your daemon
1541	somewhere, as that would have given you a big clue).	1541	somewhere, as that would have given you a big clue).
1542		1542
		1543	=head3 The special problem of accept()ing when you can't
		1544
		1545	Many implementations of the POSIX C<accept> function (for example,
		1546	found in port-2004 Linux) have the peculiar behaviour of not removing a
		1547	connection from the pending queue in all error cases.
		1548
		1549	For example, larger servers often run out of file descriptors (because
		1550	of resource limits), causing C<accept> to fail with C<ENFILE> but not
		1551	rejecting the connection, leading to libev signalling readiness on
		1552	the next iteration again (the connection still exists after all), and
		1553	typically causing the program to loop at 100% CPU usage.
		1554
		1555	Unfortunately, the set of errors that cause this issue differs between
		1556	operating systems, there is usually little the app can do to remedy the
		1557	situation, and no known thread-safe method of removing the connection to
		1558	cope with overload is known (to me).
		1559
		1560	One 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
		1562	situation is over. While this is a form of busy waiting, no OS offers an
		1563	event-based way to handle this situation, so it's the best one can do.
		1564
		1565	A better way to handle the situation is to log any errors other than
		1566	C<EAGAIN> and C<EWOULDBLOCK>, making sure not to flood the log with such
		1567	messages, and continue as usual, which at least gives the user an idea of
		1568	what could be wrong ("raise the ulimit!"). For extra points one could stop
		1569	the C<ev_io> watcher on the listening fd "for a while", which reduces CPU
		1570	usage.
		1571
		1572	If your program is single-threaded, then you could also keep a dummy file
		1573	descriptor for overload situations (e.g. by opening F</dev/null>), and
		1574	when you run into C<ENFILE> or C<EMFILE>, close it, run C<accept>,
		1575	close that fd, and create a new dummy fd. This will gracefully refuse
		1576	clients under typical overload conditions.
		1577
		1578	The last way to handle it is to simply log the error and C<exit>, as
		1579	is often done with C<malloc> failures, but this results in an easy
		1580	opportunity 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
…		…
3838	fine.	3876	fine.
3839		3877
3840	If your embedding application does not need any priorities, defining these	3878	If your embedding application does not need any priorities, defining these
3841	both to C<0> will save some memory and CPU.	3879	both to C<0> will save some memory and CPU.
3842		3880
3843	=item EV_PERIODIC_ENABLE	3881	=item EV_PERIODIC_ENABLE, EV_IDLE_ENABLE, EV_EMBED_ENABLE, EV_STAT_ENABLE,
		3882	EV_PREPARE_ENABLE, EV_CHECK_ENABLE, EV_FORK_ENABLE, EV_SIGNAL_ENABLE,
		3883	EV_ASYNC_ENABLE, EV_CHILD_ENABLE.
3844		3884
3845	If undefined or defined to be C<1>, then periodic timers are supported. If	3885	If undefined or defined to be C<1> (and the platform supports it), then
3846	defined to be C<0>, then they are not. Disabling them saves a few kB of	3886	the respective watcher type is supported. If defined to be C<0>, then it
3847	code.	3887	is not. Disabling watcher types mainly saves codesize.
3848		3888
3849	=item EV_IDLE_ENABLE	3889	=item EV_FEATURES
3850
3851	If undefined or defined to be C<1>, then idle watchers are supported. If
3852	defined to be C<0>, then they are not. Disabling them saves a few kB of
3853	code.
3854
3855	=item EV_EMBED_ENABLE
3856
3857	If undefined or defined to be C<1>, then embed watchers are supported. If
3858	defined to be C<0>, then they are not. Embed watchers rely on most other
3859	watcher types, which therefore must not be disabled.
3860
3861	=item EV_STAT_ENABLE
3862
3863	If undefined or defined to be C<1>, then stat watchers are supported. If
3864	defined to be C<0>, then they are not.
3865
3866	=item EV_FORK_ENABLE
3867
3868	If undefined or defined to be C<1>, then fork watchers are supported. If
3869	defined to be C<0>, then they are not.
3870
3871	=item EV_SIGNAL_ENABLE
3872
3873	If undefined or defined to be C<1>, then signal watchers are supported. If
3874	defined to be C<0>, then they are not.
3875
3876	=item EV_ASYNC_ENABLE
3877
3878	If undefined or defined to be C<1>, then async watchers are supported. If
3879	defined to be C<0>, then they are not.
3880
3881	=item EV_CHILD_ENABLE
3882
3883	If undefined or defined to be C<1> (and C<_WIN32> is not defined), then
3884	child watchers are supported. If defined to be C<0>, then they are not.
3885
3886	=item EV_MINIMAL
3887		3890
3888	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
3889	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
3890	is used to override some inlining decisions, saves roughly 30% code size	3893	certain subsets of functionality. The default is to enable all features
3891	on amd64. It also selects a much smaller 2-heap for timer management over	3894	that can be enabled on the platform.
3892	the default 4-heap.
3893		3895
3894	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
3895	and setting C<EV_MAXPRI> == C<EV_MINPRI>. Also, disabling C<assert>	3897	using this symbol makes sense mostly when embedding libev.
3896	(C<-DNDEBUG>) will usually reduce code size a lot. Disabling inotify,
3897	eventfd and signalfd will further help, and disabling backends one doesn't
3898	need (e.g. poll, epoll, kqueue, ports) will help further.
3899		3898
3900	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
3901	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
3902	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,
3903	over time.	3902	but multiple event loop support, async and child watchers and the poll
		3903	backend, use this:
3904		3904
3905	This example set of settings reduces the compiled size of libev from 24Kb	3905	#define EV_FEATURES 0
3906	to 8Kb on my GNU/Linux amd64 system (and leaves little in - there is also
3907	an effect on the amount of memory used). With an intelligent-enough linker
3908	further unused functions might be left out as well automatically.
3909
3910	// tuning and API changes
3911	#define EV_MINIMAL 2
3912	#define EV_MULTIPLICITY 0	3906	#define EV_MULTIPLICITY 1
3913	#define EV_MINPRI 0
3914	#define EV_MAXPRI 0
3915
3916	// OS-specific backends
3917	#define EV_USE_INOTIFY 0
3918	#define EV_USE_EVENTFD 0
3919	#define EV_USE_SIGNALFD 0
3920	#define EV_USE_REALTIME 0
3921	#define EV_USE_MONOTONIC 0
3922	#define EV_USE_CLOCK_SYSCALL 0
3923
3924	// disable all backends except select
3925	#define EV_USE_POLL 0	3907	#define EV_USE_POLL 1
3926	#define EV_USE_PORT 0
3927	#define EV_USE_KQUEUE 0
3928	#define EV_USE_EPOLL 0
3929
3930	// disable all watcher types that cna be disabled
3931	#define EV_STAT_ENABLE 0
3932	#define EV_PERIODIC_ENABLE 0
3933	#define EV_IDLE_ENABLE 0
3934	#define EV_FORK_ENABLE 0
3935	#define EV_SIGNAL_ENABLE 0
3936	#define EV_CHILD_ENABLE 0	3908	#define EV_CHILD_ENABLE 1
3937	#define EV_ASYNC_ENABLE 0	3909	#define EV_ASYNC_ENABLE 1
3938	#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	Also disables C<assert>'s in the code, unless you define C<NDEBUG>
		3924	explicitly to C<0>.
		3925
		3926	Use of compiler flags such as C<-Os> with gcc that optimise for size are
		3927	recommended when disabling this feature.
		3928
		3929	=item C<2> - faster/larger data structures
		3930
		3931	Replaces the small 2-heap for timer management by a faster 4-heap, larger
		3932	hash table sizes and so on. This will usually further increase codesize
		3933	and can additionally have an effect on the size of data structures at
		3934	runtime.
		3935
		3936	=item C<4> - full API configuration
		3937
		3938	This enables priorities (sets C<EV_MAXPRI>=2 and C<EV_MINPRI>=-2), and
		3939	enables multiplicity (C<EV_MULTIPLICITY>=1).
		3940
		3941	It also enables a lot of the "lesser used" core API functions. See C<ev.h>
		3942	for details on which parts of the API are still available without this
		3943	feature, and do not complain if this subset changes over time.
		3944
		3945	=item C<8> - enable all optional watcher types
		3946
		3947	Enables all optional watcher types. If you want to selectively enable
		3948	only some watcher types other than I/O and timers (e.g. prepare,
		3949	embed, async, child...) you can enable them manually by defining
		3950	C<EV_watchertype_ENABLE> to C<1> instead.
		3951
		3952	=item C<16> - enable all backends
		3953
		3954	This enables all backends - without this feature, you need to enable at
		3955	least one backend manually (C<EV_USE_SELECT> is a good choice).
		3956
		3957	=item C<32> - enable OS-specific "helper" APIs
		3958
		3959	Enable inotify, eventfd, signalfd and similar OS-specific helper APIs by
		3960	default.
		3961
		3962	=back
		3963
		3964	Compiling with C<gcc -Os -DEV_STANDALONE -DEV_USE_EPOLL=1 -DEV_FEATURES=0>
		3965	reduces the compiled size of libev from 24.7Kb to 6.5Kb on my GNU/Linux
		3966	amd64 system, while still giving you I/O watchers, timers and monotonic
		3967	clock support.
		3968
		3969	With an intelligent-enough linker (gcc+binutils are intelligent enough
		3970	when you use C<-Wl,--gc-sections -ffunction-sections>) functions unused by
		3971	your program might be left out as well - a binary starting a timer and an
		3972	I/O watcher then might come out at only 5Kb.
3939		3973
3940	=item EV_AVOID_STDIO	3974	=item EV_AVOID_STDIO
3941		3975
3942	If this is set to C<1> at compiletime, then libev will avoid using stdio	3976	If this is set to C<1> at compiletime, then libev will avoid using stdio
3943	functions (printf, scanf, perror etc.). This will increase the codesize	3977	functions (printf, scanf, perror etc.). This will increase the codesize
…		…
3958	statically allocates some 12-24 bytes per signal number.	3992	statically allocates some 12-24 bytes per signal number.
3959		3993
3960	=item EV_PID_HASHSIZE	3994	=item EV_PID_HASHSIZE
3961		3995
3962	C<ev_child> watchers use a small hash table to distribute workload by	3996	C<ev_child> watchers use a small hash table to distribute workload by
3963	pid. The default size is C<16> (or C<1> with C<EV_MINIMAL>), usually more	3997	pid. The default size is C<16> (or C<1> with C<EV_FEATURES> disabled),
3964	than enough. If you need to manage thousands of children you might want to	3998	usually more than enough. If you need to manage thousands of children you
3965	increase this value (I<must> be a power of two).	3999	might want to increase this value (I<must> be a power of two).
3966		4000
3967	=item EV_INOTIFY_HASHSIZE	4001	=item EV_INOTIFY_HASHSIZE
3968		4002
3969	C<ev_stat> watchers use a small hash table to distribute workload by	4003	C<ev_stat> watchers use a small hash table to distribute workload by
3970	inotify watch id. The default size is C<16> (or C<1> with C<EV_MINIMAL>),	4004	inotify watch id. The default size is C<16> (or C<1> with C<EV_FEATURES>
3971	usually more than enough. If you need to manage thousands of C<ev_stat>	4005	disabled), usually more than enough. If you need to manage thousands of
3972	watchers you might want to increase this value (I<must> be a power of	4006	C<ev_stat> watchers you might want to increase this value (I<must> be a
3973	two).	4007	power of two).
3974		4008
3975	=item EV_USE_4HEAP	4009	=item EV_USE_4HEAP
3976		4010
3977	Heaps are not very cache-efficient. To improve the cache-efficiency of the	4011	Heaps are not very cache-efficient. To improve the cache-efficiency of the
3978	timer and periodics heaps, libev uses a 4-heap when this symbol is defined	4012	timer and periodics heaps, libev uses a 4-heap when this symbol is defined
3979	to C<1>. The 4-heap uses more complicated (longer) code but has noticeably	4013	to C<1>. The 4-heap uses more complicated (longer) code but has noticeably
3980	faster performance with many (thousands) of watchers.	4014	faster performance with many (thousands) of watchers.
3981		4015
3982	The default is C<1> unless C<EV_MINIMAL> is set in which case it is C<0>	4016	The default is C<1>, unless C<EV_FEATURES> overrides it, in which case it
3983	(disabled).	4017	will be C<0>.
3984		4018
3985	=item EV_HEAP_CACHE_AT	4019	=item EV_HEAP_CACHE_AT
3986		4020
3987	Heaps are not very cache-efficient. To improve the cache-efficiency of the	4021	Heaps are not very cache-efficient. To improve the cache-efficiency of the
3988	timer and periodics heaps, libev can cache the timestamp (I<at>) within	4022	timer and periodics heaps, libev can cache the timestamp (I<at>) within
3989	the heap structure (selected by defining C<EV_HEAP_CACHE_AT> to C<1>),	4023	the heap structure (selected by defining C<EV_HEAP_CACHE_AT> to C<1>),
3990	which uses 8-12 bytes more per watcher and a few hundred bytes more code,	4024	which uses 8-12 bytes more per watcher and a few hundred bytes more code,
3991	but avoids random read accesses on heap changes. This improves performance	4025	but avoids random read accesses on heap changes. This improves performance
3992	noticeably with many (hundreds) of watchers.	4026	noticeably with many (hundreds) of watchers.
3993		4027
3994	The default is C<1> unless C<EV_MINIMAL> is set in which case it is C<0>	4028	The default is C<1>, unless C<EV_FEATURES> overrides it, in which case it
3995	(disabled).	4029	will be C<0>.
3996		4030
3997	=item EV_VERIFY	4031	=item EV_VERIFY
3998		4032
3999	Controls how much internal verification (see C<ev_loop_verify ()>) will	4033	Controls how much internal verification (see C<ev_loop_verify ()>) will
4000	be done: If set to C<0>, no internal verification code will be compiled	4034	be done: If set to C<0>, no internal verification code will be compiled
…		…
4002	called. If set to C<2>, then the internal verification code will be	4036	called. If set to C<2>, then the internal verification code will be
4003	called once per loop, which can slow down libev. If set to C<3>, then the	4037	called once per loop, which can slow down libev. If set to C<3>, then the
4004	verification code will be called very frequently, which will slow down	4038	verification code will be called very frequently, which will slow down
4005	libev considerably.	4039	libev considerably.
4006		4040
4007	The default is C<1>, unless C<EV_MINIMAL> is set, in which case it will be	4041	The default is C<1>, unless C<EV_FEATURES> overrides it, in which case it
4008	C<0>.	4042	will be C<0>.
4009		4043
4010	=item EV_COMMON	4044	=item EV_COMMON
4011		4045
4012	By default, all watchers have a C<void *data> member. By redefining	4046	By default, all watchers have a C<void *data> member. By redefining
4013	this macro to a something else you can include more and other types of	4047	this macro to a something else you can include more and other types of
…		…
4071	file.	4105	file.
4072		4106
4073	The usage in rxvt-unicode is simpler. It has a F<ev_cpp.h> header file	4107	The usage in rxvt-unicode is simpler. It has a F<ev_cpp.h> header file
4074	that everybody includes and which overrides some configure choices:	4108	that everybody includes and which overrides some configure choices:
4075		4109
4076	#define EV_MINIMAL 1	4110	#define EV_FEATURES 0
4077	#define EV_USE_POLL 0	4111	#define EV_USE_SELECT 1
4078	#define EV_MULTIPLICITY 0
4079	#define EV_PERIODIC_ENABLE 0
4080	#define EV_STAT_ENABLE 0
4081	#define EV_FORK_ENABLE 0
4082	#define EV_CONFIG_H <config.h>	4112	#define EV_CONFIG_H <config.h>
4083	#define EV_MINPRI 0
4084	#define EV_MAXPRI 0
4085		4113
4086	#include "ev++.h"	4114	#include "ev++.h"
4087		4115
4088	And a F<ev_cpp.C> implementation file that contains libev proper and is compiled:	4116	And a F<ev_cpp.C> implementation file that contains libev proper and is compiled:
4089		4117

Diff Legend

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

Comparing libev/ev.pod (file contents): Revision 1.282 by root, Wed Mar 10 08:19:39 2010 UTC vs. Revision 1.285 by root, Tue Mar 16 00:20:17 2010 UTC

Diff Legend

Comparing libev/ev.pod (file contents):
Revision 1.282 by root, Wed Mar 10 08:19:39 2010 UTC vs.
Revision 1.285 by root, Tue Mar 16 00:20:17 2010 UTC