[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.289 by root, Tue Mar 16 17:11:49 2010 UTC

…		…
1032	=item C<EV_WRITE>	1032	=item C<EV_WRITE>
1033		1033
1034	The file descriptor in the C<ev_io> watcher has become readable and/or	1034	The file descriptor in the C<ev_io> watcher has become readable and/or
1035	writable.	1035	writable.
1036		1036
1037	=item C<EV_TIMEOUT>	1037	=item C<EV_TIMER>
1038		1038
1039	The C<ev_timer> watcher has timed out.	1039	The C<ev_timer> watcher has timed out.
1040		1040
1041	=item C<EV_PERIODIC>	1041	=item C<EV_PERIODIC>
1042		1042
…		…
1764	to the current time (meaning we just have some activity :), then call the	1764	to the current time (meaning we just have some activity :), then call the
1765	callback, which will "do the right thing" and start the timer:	1765	callback, which will "do the right thing" and start the timer:
1766		1766
1767	ev_init (timer, callback);	1767	ev_init (timer, callback);
1768	last_activity = ev_now (loop);	1768	last_activity = ev_now (loop);
1769	callback (loop, timer, EV_TIMEOUT);	1769	callback (loop, timer, EV_TIMER);
1770		1770
1771	And when there is some activity, simply store the current time in	1771	And when there is some activity, simply store the current time in
1772	C<last_activity>, no libev calls at all:	1772	C<last_activity>, no libev calls at all:
1773		1773
1774	last_actiivty = ev_now (loop);	1774	last_actiivty = ev_now (loop);
…		…
3179		3179
3180	If C<timeout> is less than 0, then no timeout watcher will be	3180	If C<timeout> is less than 0, then no timeout watcher will be
3181	started. Otherwise an C<ev_timer> watcher with after = C<timeout> (and	3181	started. Otherwise an C<ev_timer> watcher with after = C<timeout> (and
3182	repeat = 0) will be started. C<0> is a valid timeout.	3182	repeat = 0) will be started. C<0> is a valid timeout.
3183		3183
3184	The callback has the type C<void (cb)(int revents, void arg)> and gets	3184	The callback has the type C<void (cb)(int revents, void arg)> and is
3185	passed an C<revents> set like normal event callbacks (a combination of	3185	passed an C<revents> set like normal event callbacks (a combination of
3186	C<EV_ERROR>, C<EV_READ>, C<EV_WRITE> or C<EV_TIMEOUT>) and the C<arg>	3186	C<EV_ERROR>, C<EV_READ>, C<EV_WRITE> or C<EV_TIMER>) and the C<arg>
3187	value passed to C<ev_once>. Note that it is possible to receive I<both>	3187	value passed to C<ev_once>. Note that it is possible to receive I<both>
3188	a timeout and an io event at the same time - you probably should give io	3188	a timeout and an io event at the same time - you probably should give io
3189	events precedence.	3189	events precedence.
3190		3190
3191	Example: wait up to ten seconds for data to appear on STDIN_FILENO.	3191	Example: wait up to ten seconds for data to appear on STDIN_FILENO.
3192		3192
3193	static void stdin_ready (int revents, void *arg)	3193	static void stdin_ready (int revents, void *arg)
3194	{	3194	{
3195	if (revents & EV_READ)	3195	if (revents & EV_READ)
3196	/* stdin might have data for us, joy! */;	3196	/* stdin might have data for us, joy! */;
3197	else if (revents & EV_TIMEOUT)	3197	else if (revents & EV_TIMER)
3198	/* doh, nothing entered */;	3198	/* doh, nothing entered */;
3199	}	3199	}
3200		3200
3201	ev_once (STDIN_FILENO, EV_READ, 10., stdin_ready, 0);	3201	ev_once (STDIN_FILENO, EV_READ, 10., stdin_ready, 0);
3202		3202
…		…
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	A typical way to use this symbol is to define it to C<0> (or to a bitset
3898	and setting C<EV_MAXPRI> == C<EV_MINPRI>. Also, disabling C<assert>	3897	with some broad features you want) and then selectively re-enable
3899	(C<-DNDEBUG>) will usually reduce code size a lot. Disabling inotify,	3898	additional parts you want, for example if you want everything minimal,
3900	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
3901	need (e.g. poll, epoll, kqueue, ports) will help further.	3900	backend, use this:
3902		3901
3903	Defining C<EV_MINIMAL> to C<2> will additionally reduce the core API to	3902	#define EV_FEATURES 0
3904	provide a bare-bones event library. See C<ev.h> for details on what parts
3905	of the API are still available, and do not complain if this subset changes
3906	over time.
3907
3908	This example set of settings reduces the compiled size of libev from
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	3903	#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	3904	#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	3905	#define EV_CHILD_ENABLE 1
3945	#define EV_ASYNC_ENABLE 0	3906	#define EV_ASYNC_ENABLE 1
3946	#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 code/2.8Kb data to 6.5Kb
		3963	code/0.3Kb data on my GNU/Linux amd64 system, while still giving you I/O
		3964	watchers, timers and monotonic 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.
3947		3970
3948	=item EV_AVOID_STDIO	3971	=item EV_AVOID_STDIO
3949		3972
3950	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
3951	functions (printf, scanf, perror etc.). This will increase the codesize	3974	functions (printf, scanf, perror etc.). This will increase the codesize
…		…
3966	statically allocates some 12-24 bytes per signal number.	3989	statically allocates some 12-24 bytes per signal number.
3967		3990
3968	=item EV_PID_HASHSIZE	3991	=item EV_PID_HASHSIZE
3969		3992
3970	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
3971	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),
3972	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
3973	increase this value (I<must> be a power of two).	3996	might want to increase this value (I<must> be a power of two).
3974		3997
3975	=item EV_INOTIFY_HASHSIZE	3998	=item EV_INOTIFY_HASHSIZE
3976		3999
3977	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
3978	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>
3979	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
3980	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
3981	two).	4004	power of two).
3982		4005
3983	=item EV_USE_4HEAP	4006	=item EV_USE_4HEAP
3984		4007
3985	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
3986	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
3987	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
3988	faster performance with many (thousands) of watchers.	4011	faster performance with many (thousands) of watchers.
3989		4012
3990	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
3991	(disabled).	4014	will be C<0>.
3992		4015
3993	=item EV_HEAP_CACHE_AT	4016	=item EV_HEAP_CACHE_AT
3994		4017
3995	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
3996	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
3997	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>),
3998	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,
3999	but avoids random read accesses on heap changes. This improves performance	4022	but avoids random read accesses on heap changes. This improves performance
4000	noticeably with many (hundreds) of watchers.	4023	noticeably with many (hundreds) of watchers.
4001		4024
4002	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
4003	(disabled).	4026	will be C<0>.
4004		4027
4005	=item EV_VERIFY	4028	=item EV_VERIFY
4006		4029
4007	Controls how much internal verification (see C<ev_loop_verify ()>) will	4030	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	4031	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	4033	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	4034	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	4035	verification code will be called very frequently, which will slow down
4013	libev considerably.	4036	libev considerably.
4014		4037
4015	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
4016	C<0>.	4039	will be C<0>.
4017		4040
4018	=item EV_COMMON	4041	=item EV_COMMON
4019		4042
4020	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
4021	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
…		…
4079	file.	4102	file.
4080		4103
4081	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
4082	that everybody includes and which overrides some configure choices:	4105	that everybody includes and which overrides some configure choices:
4083		4106
4084	#define EV_MINIMAL 1	4107	#define EV_FEATURES 8
4085	#define EV_USE_POLL 0	4108	#define EV_USE_SELECT 1
4086	#define EV_MULTIPLICITY 0
4087	#define EV_PERIODIC_ENABLE 0	4109	#define EV_PREPARE_ENABLE 1
		4110	#define EV_IDLE_ENABLE 1
4088	#define EV_STAT_ENABLE 0	4111	#define EV_SIGNAL_ENABLE 1
4089	#define EV_FORK_ENABLE 0	4112	#define EV_CHILD_ENABLE 1
		4113	#define EV_USE_STDEXCEPT 0
4090	#define EV_CONFIG_H <config.h>	4114	#define EV_CONFIG_H <config.h>
4091	#define EV_MINPRI 0
4092	#define EV_MAXPRI 0
4093		4115
4094	#include "ev++.h"	4116	#include "ev++.h"
4095		4117
4096	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:
4097		4119
…		…
4599	involves iterating over all running async watchers or all signal numbers.	4621	involves iterating over all running async watchers or all signal numbers.
4600		4622
4601	=back	4623	=back
4602		4624
4603		4625
		4626	=head1 PORTING FROM 3.X TO 4.X
		4627
		4628	The major version 4 introduced some minor incompatible changes to the API.
		4629
		4630	=over 4
		4631
		4632	=item C<EV_TIMEOUT> replaced by C<EV_TIMER> in C<revents>
		4633
		4634	This is a simple rename - all other watcher types use their name
		4635	as revents flag, and now C<ev_timer> does, too.
		4636
		4637	Both C<EV_TIMER> and C<EV_TIMEOUT> symbols were present in 3.x versions
		4638	and continue to be present for the forseeable future, so this is mostly a
		4639	documentation change.
		4640
		4641	=item C<EV_MINIMAL> mechanism replaced by C<EV_FEATURES>
		4642
		4643	The preprocessor symbol C<EV_MINIMAL> has been replaced by a different
		4644	mechanism, C<EV_FEATURES>. Programs using C<EV_MINIMAL> usually compile
		4645	and work, but the library code will of course be larger.
		4646
		4647	=back
		4648
		4649
4604	=head1 GLOSSARY	4650	=head1 GLOSSARY
4605		4651
4606	=over 4	4652	=over 4
4607		4653
4608	=item active	4654	=item active
…		…
4629	A change of state of some external event, such as data now being available	4675	A change of state of some external event, such as data now being available
4630	for reading on a file descriptor, time having passed or simply not having	4676	for reading on a file descriptor, time having passed or simply not having
4631	any other events happening anymore.	4677	any other events happening anymore.
4632		4678
4633	In libev, events are represented as single bits (such as C<EV_READ> or	4679	In libev, events are represented as single bits (such as C<EV_READ> or
4634	C<EV_TIMEOUT>).	4680	C<EV_TIMER>).
4635		4681
4636	=item event library	4682	=item event library
4637		4683
4638	A software package implementing an event model and loop.	4684	A software package implementing an event model and loop.
4639		4685

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.289 by root, Tue Mar 16 17:11:49 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.289 by root, Tue Mar 16 17:11:49 2010 UTC