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

Comparing libev/ev.pod (file contents):
Revision 1.285 by root, Tue Mar 16 00:20:17 2010 UTC vs.
Revision 1.290 by root, Tue Mar 16 18:03:01 2010 UTC

…		…
567	ev_default_loop (ev_recommended_backends () \| EVBACKEND_KQUEUE);	567	ev_default_loop (ev_recommended_backends () \| EVBACKEND_KQUEUE);
568		568
569	=item struct ev_loop *ev_loop_new (unsigned int flags)	569	=item struct ev_loop *ev_loop_new (unsigned int flags)
570		570
571	Similar to C<ev_default_loop>, but always creates a new event loop that is	571	Similar to C<ev_default_loop>, but always creates a new event loop that is
572	always distinct from the default loop. Unlike the default loop, it cannot	572	always distinct from the default loop.
573	handle signal and child watchers, and attempts to do so will be greeted by
574	undefined behaviour (or a failed assertion if assertions are enabled).
575		573
576	Note that this function I<is> thread-safe, and the recommended way to use	574	Note that this function I<is> thread-safe, and one common way to use
577	libev with threads is indeed to create one loop per thread, and using the	575	libev with threads is indeed to create one loop per thread, and using the
578	default loop in the "main" or "initial" thread.	576	default loop in the "main" or "initial" thread.
579		577
580	Example: Try to create a event loop that uses epoll and nothing else.	578	Example: Try to create a event loop that uses epoll and nothing else.
581		579
…		…
583	if (!epoller)	581	if (!epoller)
584	fatal ("no epoll found here, maybe it hides under your chair");	582	fatal ("no epoll found here, maybe it hides under your chair");
585		583
586	=item ev_default_destroy ()	584	=item ev_default_destroy ()
587		585
588	Destroys the default loop again (frees all memory and kernel state	586	Destroys the default loop (frees all memory and kernel state etc.). None
589	etc.). None of the active event watchers will be stopped in the normal	587	of the active event watchers will be stopped in the normal sense, so
590	sense, so e.g. C<ev_is_active> might still return true. It is your	588	e.g. C<ev_is_active> might still return true. It is your responsibility to
591	responsibility to either stop all watchers cleanly yourself I<before>	589	either stop all watchers cleanly yourself I<before> calling this function,
592	calling this function, or cope with the fact afterwards (which is usually	590	or cope with the fact afterwards (which is usually the easiest thing, you
593	the easiest thing, you can just ignore the watchers and/or C<free ()> them	591	can just ignore the watchers and/or C<free ()> them for example).
594	for example).
595		592
596	Note that certain global state, such as signal state (and installed signal	593	Note that certain global state, such as signal state (and installed signal
597	handlers), will not be freed by this function, and related watchers (such	594	handlers), will not be freed by this function, and related watchers (such
598	as signal and child watchers) would need to be stopped manually.	595	as signal and child watchers) would need to be stopped manually.
599		596
…		…
1032	=item C<EV_WRITE>	1029	=item C<EV_WRITE>
1033		1030
1034	The file descriptor in the C<ev_io> watcher has become readable and/or	1031	The file descriptor in the C<ev_io> watcher has become readable and/or
1035	writable.	1032	writable.
1036		1033
1037	=item C<EV_TIMEOUT>	1034	=item C<EV_TIMER>
1038		1035
1039	The C<ev_timer> watcher has timed out.	1036	The C<ev_timer> watcher has timed out.
1040		1037
1041	=item C<EV_PERIODIC>	1038	=item C<EV_PERIODIC>
1042		1039
…		…
1764	to the current time (meaning we just have some activity :), then call the	1761	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:	1762	callback, which will "do the right thing" and start the timer:
1766		1763
1767	ev_init (timer, callback);	1764	ev_init (timer, callback);
1768	last_activity = ev_now (loop);	1765	last_activity = ev_now (loop);
1769	callback (loop, timer, EV_TIMEOUT);	1766	callback (loop, timer, EV_TIMER);
1770		1767
1771	And when there is some activity, simply store the current time in	1768	And when there is some activity, simply store the current time in
1772	C<last_activity>, no libev calls at all:	1769	C<last_activity>, no libev calls at all:
1773		1770
1774	last_actiivty = ev_now (loop);	1771	last_actiivty = ev_now (loop);
…		…
3179		3176
3180	If C<timeout> is less than 0, then no timeout watcher will be	3177	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	3178	started. Otherwise an C<ev_timer> watcher with after = C<timeout> (and
3182	repeat = 0) will be started. C<0> is a valid timeout.	3179	repeat = 0) will be started. C<0> is a valid timeout.
3183		3180
3184	The callback has the type C<void (cb)(int revents, void arg)> and gets	3181	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	3182	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>	3183	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>	3184	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	3185	a timeout and an io event at the same time - you probably should give io
3189	events precedence.	3186	events precedence.
3190		3187
3191	Example: wait up to ten seconds for data to appear on STDIN_FILENO.	3188	Example: wait up to ten seconds for data to appear on STDIN_FILENO.
3192		3189
3193	static void stdin_ready (int revents, void *arg)	3190	static void stdin_ready (int revents, void *arg)
3194	{	3191	{
3195	if (revents & EV_READ)	3192	if (revents & EV_READ)
3196	/* stdin might have data for us, joy! */;	3193	/* stdin might have data for us, joy! */;
3197	else if (revents & EV_TIMEOUT)	3194	else if (revents & EV_TIMER)
3198	/* doh, nothing entered */;	3195	/* doh, nothing entered */;
3199	}	3196	}
3200		3197
3201	ev_once (STDIN_FILENO, EV_READ, 10., stdin_ready, 0);	3198	ev_once (STDIN_FILENO, EV_READ, 10., stdin_ready, 0);
3202		3199
…		…
3891	If you need to shave off some kilobytes of code at the expense of some	3888	If you need to shave off some kilobytes of code at the expense of some
3892	speed (but with the full API), you can define this symbol to request	3889	speed (but with the full API), you can define this symbol to request
3893	certain subsets of functionality. The default is to enable all features	3890	certain subsets of functionality. The default is to enable all features
3894	that can be enabled on the platform.	3891	that can be enabled on the platform.
3895		3892
3896	Note that using autoconf will usually override most of the features, so
3897	using this symbol makes sense mostly when embedding libev.
3898
3899	A typical way to use this symbol is to define it to C<0> (or to a bitset	3893	A typical way to use this symbol is to define it to C<0> (or to a bitset
3900	with some broad features you want) and then selectively re-enable	3894	with some broad features you want) and then selectively re-enable
3901	additional parts you want, for example if you want everything minimal,	3895	additional parts you want, for example if you want everything minimal,
3902	but multiple event loop support, async and child watchers and the poll	3896	but multiple event loop support, async and child watchers and the poll
3903	backend, use this:	3897	backend, use this:
…		…
3918	Use larger code to speed up some operations.	3912	Use larger code to speed up some operations.
3919		3913
3920	Currently this is used to override some inlining decisions (enlarging the roughly	3914	Currently this is used to override some inlining decisions (enlarging the roughly
3921	30% code size on amd64.	3915	30% code size on amd64.
3922		3916
3923	Also disables C<assert>'s in the code, unless you define C<NDEBUG>	3917	When optimising for size, use of compiler flags such as C<-Os> with
3924	explicitly to C<0>.	3918	gcc recommended, as well as C<-DNDEBUG>, as libev contains a number of
3925		3919	assertions.
3926	Use of compiler flags such as C<-Os> with gcc that optimise for size are
3927	recommended when disabling this feature.
3928		3920
3929	=item C<2> - faster/larger data structures	3921	=item C<2> - faster/larger data structures
3930		3922
3931	Replaces the small 2-heap for timer management by a faster 4-heap, larger	3923	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	3924	hash table sizes and so on. This will usually further increase codesize
…		…
3936	=item C<4> - full API configuration	3928	=item C<4> - full API configuration
3937		3929
3938	This enables priorities (sets C<EV_MAXPRI>=2 and C<EV_MINPRI>=-2), and	3930	This enables priorities (sets C<EV_MAXPRI>=2 and C<EV_MINPRI>=-2), and
3939	enables multiplicity (C<EV_MULTIPLICITY>=1).	3931	enables multiplicity (C<EV_MULTIPLICITY>=1).
3940		3932
		3933	=item C<8> - full API
		3934
3941	It also enables a lot of the "lesser used" core API functions. See C<ev.h>	3935	This enables a lot of the "lesser used" API functions. See C<ev.h> for
3942	for details on which parts of the API are still available without this	3936	details on which parts of the API are still available without this
3943	feature, and do not complain if this subset changes over time.	3937	feature, and do not complain if this subset changes over time.
3944		3938
3945	=item C<8> - enable all optional watcher types	3939	=item C<16> - enable all optional watcher types
3946		3940
3947	Enables all optional watcher types. If you want to selectively enable	3941	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,	3942	only some watcher types other than I/O and timers (e.g. prepare,
3949	embed, async, child...) you can enable them manually by defining	3943	embed, async, child...) you can enable them manually by defining
3950	C<EV_watchertype_ENABLE> to C<1> instead.	3944	C<EV_watchertype_ENABLE> to C<1> instead.
3951		3945
3952	=item C<16> - enable all backends	3946	=item C<32> - enable all backends
3953		3947
3954	This enables all backends - without this feature, you need to enable at	3948	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).	3949	least one backend manually (C<EV_USE_SELECT> is a good choice).
3956		3950
3957	=item C<32> - enable OS-specific "helper" APIs	3951	=item C<64> - enable OS-specific "helper" APIs
3958		3952
3959	Enable inotify, eventfd, signalfd and similar OS-specific helper APIs by	3953	Enable inotify, eventfd, signalfd and similar OS-specific helper APIs by
3960	default.	3954	default.
3961		3955
3962	=back	3956	=back
3963		3957
3964	Compiling with C<gcc -Os -DEV_STANDALONE -DEV_USE_EPOLL=1 -DEV_FEATURES=0>	3958	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	3959	reduces the compiled size of libev from 24.7Kb code/2.8Kb data to 6.5Kb
3966	amd64 system, while still giving you I/O watchers, timers and monotonic	3960	code/0.3Kb data on my GNU/Linux amd64 system, while still giving you I/O
3967	clock support.	3961	watchers, timers and monotonic clock support.
3968		3962
3969	With an intelligent-enough linker (gcc+binutils are intelligent enough	3963	With an intelligent-enough linker (gcc+binutils are intelligent enough
3970	when you use C<-Wl,--gc-sections -ffunction-sections>) functions unused by	3964	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	3965	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.	3966	I/O watcher then might come out at only 5Kb.
…		…
4105	file.	4099	file.
4106		4100
4107	The usage in rxvt-unicode is simpler. It has a F<ev_cpp.h> header file	4101	The usage in rxvt-unicode is simpler. It has a F<ev_cpp.h> header file
4108	that everybody includes and which overrides some configure choices:	4102	that everybody includes and which overrides some configure choices:
4109		4103
4110	#define EV_FEATURES 0	4104	#define EV_FEATURES 8
4111	#define EV_USE_SELECT 1	4105	#define EV_USE_SELECT 1
		4106	#define EV_PREPARE_ENABLE 1
		4107	#define EV_IDLE_ENABLE 1
		4108	#define EV_SIGNAL_ENABLE 1
		4109	#define EV_CHILD_ENABLE 1
		4110	#define EV_USE_STDEXCEPT 0
4112	#define EV_CONFIG_H <config.h>	4111	#define EV_CONFIG_H <config.h>
4113		4112
4114	#include "ev++.h"	4113	#include "ev++.h"
4115		4114
4116	And a F<ev_cpp.C> implementation file that contains libev proper and is compiled:	4115	And a F<ev_cpp.C> implementation file that contains libev proper and is compiled:
…		…
4619	involves iterating over all running async watchers or all signal numbers.	4618	involves iterating over all running async watchers or all signal numbers.
4620		4619
4621	=back	4620	=back
4622		4621
4623		4622
		4623	=head1 PORTING FROM 3.X TO 4.X
		4624
		4625	The major version 4 introduced some minor incompatible changes to the API.
		4626
		4627	=over 4
		4628
		4629	=item C<EV_TIMEOUT> replaced by C<EV_TIMER> in C<revents>
		4630
		4631	This is a simple rename - all other watcher types use their name
		4632	as revents flag, and now C<ev_timer> does, too.
		4633
		4634	Both C<EV_TIMER> and C<EV_TIMEOUT> symbols were present in 3.x versions
		4635	and continue to be present for the forseeable future, so this is mostly a
		4636	documentation change.
		4637
		4638	=item C<EV_MINIMAL> mechanism replaced by C<EV_FEATURES>
		4639
		4640	The preprocessor symbol C<EV_MINIMAL> has been replaced by a different
		4641	mechanism, C<EV_FEATURES>. Programs using C<EV_MINIMAL> usually compile
		4642	and work, but the library code will of course be larger.
		4643
		4644	=back
		4645
		4646
4624	=head1 GLOSSARY	4647	=head1 GLOSSARY
4625		4648
4626	=over 4	4649	=over 4
4627		4650
4628	=item active	4651	=item active
…		…
4649	A change of state of some external event, such as data now being available	4672	A change of state of some external event, such as data now being available
4650	for reading on a file descriptor, time having passed or simply not having	4673	for reading on a file descriptor, time having passed or simply not having
4651	any other events happening anymore.	4674	any other events happening anymore.
4652		4675
4653	In libev, events are represented as single bits (such as C<EV_READ> or	4676	In libev, events are represented as single bits (such as C<EV_READ> or
4654	C<EV_TIMEOUT>).	4677	C<EV_TIMER>).
4655		4678
4656	=item event library	4679	=item event library
4657		4680
4658	A software package implementing an event model and loop.	4681	A software package implementing an event model and loop.
4659		4682

Diff Legend

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

Comparing libev/ev.pod (file contents): Revision 1.285 by root, Tue Mar 16 00:20:17 2010 UTC vs. Revision 1.290 by root, Tue Mar 16 18:03:01 2010 UTC

Diff Legend

Comparing libev/ev.pod (file contents):
Revision 1.285 by root, Tue Mar 16 00:20:17 2010 UTC vs.
Revision 1.290 by root, Tue Mar 16 18:03:01 2010 UTC