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

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

Diff Legend

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

Comparing libev/ev.pod (file contents): Revision 1.283 by root, Wed Mar 10 09:18:25 2010 UTC vs. Revision 1.287 by root, Tue Mar 16 00:43:22 2010 UTC

Diff Legend

Comparing libev/ev.pod (file contents):
Revision 1.283 by root, Wed Mar 10 09:18:25 2010 UTC vs.
Revision 1.287 by root, Tue Mar 16 00:43:22 2010 UTC