[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.292 by sf-exg, Mon Mar 22 09:57:01 2010 UTC

…		…
345	useful to try out specific backends to test their performance, or to work	345	useful to try out specific backends to test their performance, or to work
346	around bugs.	346	around bugs.
347		347
348	=item C<EVFLAG_FORKCHECK>	348	=item C<EVFLAG_FORKCHECK>
349		349
350	Instead of calling C<ev_default_fork> or C<ev_loop_fork> manually after	350	Instead of calling C<ev_loop_fork> manually after a fork, you can also
351	a fork, you can also make libev check for a fork in each iteration by	351	make libev check for a fork in each iteration by enabling this flag.
352	enabling this flag.
353		352
354	This works by calling C<getpid ()> on every iteration of the loop,	353	This works by calling C<getpid ()> on every iteration of the loop,
355	and thus this might slow down your event loop if you do a lot of loop	354	and thus this might slow down your event loop if you do a lot of loop
356	iterations and little real work, but is usually not noticeable (on my	355	iterations and little real work, but is usually not noticeable (on my
357	GNU/Linux system for example, C<getpid> is actually a simple 5-insn sequence	356	GNU/Linux system for example, C<getpid> is actually a simple 5-insn sequence
…		…
567	ev_default_loop (ev_recommended_backends () \| EVBACKEND_KQUEUE);	566	ev_default_loop (ev_recommended_backends () \| EVBACKEND_KQUEUE);
568		567
569	=item struct ev_loop *ev_loop_new (unsigned int flags)	568	=item struct ev_loop *ev_loop_new (unsigned int flags)
570		569
571	Similar to C<ev_default_loop>, but always creates a new event loop that is	570	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	571	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		572
576	Note that this function I<is> thread-safe, and the recommended way to use	573	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	574	libev with threads is indeed to create one loop per thread, and using the
578	default loop in the "main" or "initial" thread.	575	default loop in the "main" or "initial" thread.
579		576
580	Example: Try to create a event loop that uses epoll and nothing else.	577	Example: Try to create a event loop that uses epoll and nothing else.
581		578
…		…
583	if (!epoller)	580	if (!epoller)
584	fatal ("no epoll found here, maybe it hides under your chair");	581	fatal ("no epoll found here, maybe it hides under your chair");
585		582
586	=item ev_default_destroy ()	583	=item ev_default_destroy ()
587		584
588	Destroys the default loop again (frees all memory and kernel state	585	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	586	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	587	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>	588	either stop all watchers cleanly yourself I<before> calling this function,
592	calling this function, or cope with the fact afterwards (which is usually	589	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	590	can just ignore the watchers and/or C<free ()> them for example).
594	for example).
595		591
596	Note that certain global state, such as signal state (and installed signal	592	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	593	handlers), will not be freed by this function, and related watchers (such
598	as signal and child watchers) would need to be stopped manually.	594	as signal and child watchers) would need to be stopped manually.
599		595
…		…
614	name, you can call it anytime, but it makes most sense after forking, in	610	name, you can call it anytime, but it makes most sense after forking, in
615	the child process (or both child and parent, but that again makes little	611	the child process (or both child and parent, but that again makes little
616	sense). You I<must> call it in the child before using any of the libev	612	sense). You I<must> call it in the child before using any of the libev
617	functions, and it will only take effect at the next C<ev_loop> iteration.	613	functions, and it will only take effect at the next C<ev_loop> iteration.
618		614
		615	Again, you I<have> to call it on I<any> loop that you want to re-use after
		616	a fork, I<even if you do not plan to use the loop in the parent>. This is
		617	because some kernel interfaces cough I<kqueue> cough do funny things
		618	during fork.
		619
619	On the other hand, you only need to call this function in the child	620	On the other hand, you only need to call this function in the child
620	process if and only if you want to use the event library in the child. If	621	process if and only if you want to use the event loop in the child. If you
621	you just fork+exec, you don't have to call it at all.	622	just fork+exec or create a new loop in the child, you don't have to call
		623	it at all.
622		624
623	The function itself is quite fast and it's usually not a problem to call	625	The function itself is quite fast and it's usually not a problem to call
624	it just in case after a fork. To make this easy, the function will fit in	626	it just in case after a fork. To make this easy, the function will fit in
625	quite nicely into a call to C<pthread_atfork>:	627	quite nicely into a call to C<pthread_atfork>:
626		628
…		…
628		630
629	=item ev_loop_fork (loop)	631	=item ev_loop_fork (loop)
630		632
631	Like C<ev_default_fork>, but acts on an event loop created by	633	Like C<ev_default_fork>, but acts on an event loop created by
632	C<ev_loop_new>. Yes, you have to call this on every allocated event loop	634	C<ev_loop_new>. Yes, you have to call this on every allocated event loop
633	after fork that you want to re-use in the child, and how you do this is	635	after fork that you want to re-use in the child, and how you keep track of
634	entirely your own problem.	636	them is entirely your own problem.
635		637
636	=item int ev_is_default_loop (loop)	638	=item int ev_is_default_loop (loop)
637		639
638	Returns true when the given loop is, in fact, the default loop, and false	640	Returns true when the given loop is, in fact, the default loop, and false
639	otherwise.	641	otherwise.
640		642
641	=item unsigned int ev_loop_count (loop)	643	=item unsigned int ev_iteration (loop)
642		644
643	Returns the count of loop iterations for the loop, which is identical to	645	Returns the current iteration count for the loop, which is identical to
644	the number of times libev did poll for new events. It starts at C<0> and	646	the number of times libev did poll for new events. It starts at C<0> and
645	happily wraps around with enough iterations.	647	happily wraps around with enough iterations.
646		648
647	This value can sometimes be useful as a generation counter of sorts (it	649	This value can sometimes be useful as a generation counter of sorts (it
648	"ticks" the number of loop iterations), as it roughly corresponds with	650	"ticks" the number of loop iterations), as it roughly corresponds with
649	C<ev_prepare> and C<ev_check> calls.	651	C<ev_prepare> and C<ev_check> calls - and is incremented between the
		652	prepare and check phases.
650		653
651	=item unsigned int ev_loop_depth (loop)	654	=item unsigned int ev_depth (loop)
652		655
653	Returns the number of times C<ev_loop> was entered minus the number of	656	Returns the number of times C<ev_loop> was entered minus the number of
654	times C<ev_loop> was exited, in other words, the recursion depth.	657	times C<ev_loop> was exited, in other words, the recursion depth.
655		658
656	Outside C<ev_loop>, this number is zero. In a callback, this number is	659	Outside C<ev_loop>, this number is zero. In a callback, this number is
657	C<1>, unless C<ev_loop> was invoked recursively (or from another thread),	660	C<1>, unless C<ev_loop> was invoked recursively (or from another thread),
658	in which case it is higher.	661	in which case it is higher.
659		662
660	Leaving C<ev_loop> abnormally (setjmp/longjmp, cancelling the thread	663	Leaving C<ev_loop> abnormally (setjmp/longjmp, cancelling the thread
661	etc.), doesn't count as exit.	664	etc.), doesn't count as "exit" - consider this as a hint to avoid such
		665	ungentleman behaviour unless it's really convenient.
662		666
663	=item unsigned int ev_backend (loop)	667	=item unsigned int ev_backend (loop)
664		668
665	Returns one of the C<EVBACKEND_*> flags indicating the event backend in	669	Returns one of the C<EVBACKEND_*> flags indicating the event backend in
666	use.	670	use.
…		…
1032	=item C<EV_WRITE>	1036	=item C<EV_WRITE>
1033		1037
1034	The file descriptor in the C<ev_io> watcher has become readable and/or	1038	The file descriptor in the C<ev_io> watcher has become readable and/or
1035	writable.	1039	writable.
1036		1040
1037	=item C<EV_TIMEOUT>	1041	=item C<EV_TIMER>
1038		1042
1039	The C<ev_timer> watcher has timed out.	1043	The C<ev_timer> watcher has timed out.
1040		1044
1041	=item C<EV_PERIODIC>	1045	=item C<EV_PERIODIC>
1042		1046
…		…
1541	somewhere, as that would have given you a big clue).	1545	somewhere, as that would have given you a big clue).
1542		1546
1543	=head3 The special problem of accept()ing when you can't	1547	=head3 The special problem of accept()ing when you can't
1544		1548
1545	Many implementations of the POSIX C<accept> function (for example,	1549	Many implementations of the POSIX C<accept> function (for example,
1546	found in port-2004 Linux) have the peculiar behaviour of not removing a	1550	found in post-2004 Linux) have the peculiar behaviour of not removing a
1547	connection from the pending queue in all error cases.	1551	connection from the pending queue in all error cases.
1548		1552
1549	For example, larger servers often run out of file descriptors (because	1553	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	1554	of resource limits), causing C<accept> to fail with C<ENFILE> but not
1551	rejecting the connection, leading to libev signalling readiness on	1555	rejecting the connection, leading to libev signalling readiness on
…		…
1764	to the current time (meaning we just have some activity :), then call the	1768	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:	1769	callback, which will "do the right thing" and start the timer:
1766		1770
1767	ev_init (timer, callback);	1771	ev_init (timer, callback);
1768	last_activity = ev_now (loop);	1772	last_activity = ev_now (loop);
1769	callback (loop, timer, EV_TIMEOUT);	1773	callback (loop, timer, EV_TIMER);
1770		1774
1771	And when there is some activity, simply store the current time in	1775	And when there is some activity, simply store the current time in
1772	C<last_activity>, no libev calls at all:	1776	C<last_activity>, no libev calls at all:
1773		1777
1774	last_actiivty = ev_now (loop);	1778	last_actiivty = ev_now (loop);
…		…
3179		3183
3180	If C<timeout> is less than 0, then no timeout watcher will be	3184	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	3185	started. Otherwise an C<ev_timer> watcher with after = C<timeout> (and
3182	repeat = 0) will be started. C<0> is a valid timeout.	3186	repeat = 0) will be started. C<0> is a valid timeout.
3183		3187
3184	The callback has the type C<void (cb)(int revents, void arg)> and gets	3188	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	3189	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>	3190	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>	3191	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	3192	a timeout and an io event at the same time - you probably should give io
3189	events precedence.	3193	events precedence.
3190		3194
3191	Example: wait up to ten seconds for data to appear on STDIN_FILENO.	3195	Example: wait up to ten seconds for data to appear on STDIN_FILENO.
3192		3196
3193	static void stdin_ready (int revents, void *arg)	3197	static void stdin_ready (int revents, void *arg)
3194	{	3198	{
3195	if (revents & EV_READ)	3199	if (revents & EV_READ)
3196	/* stdin might have data for us, joy! */;	3200	/* stdin might have data for us, joy! */;
3197	else if (revents & EV_TIMEOUT)	3201	else if (revents & EV_TIMER)
3198	/* doh, nothing entered */;	3202	/* doh, nothing entered */;
3199	}	3203	}
3200		3204
3201	ev_once (STDIN_FILENO, EV_READ, 10., stdin_ready, 0);	3205	ev_once (STDIN_FILENO, EV_READ, 10., stdin_ready, 0);
3202		3206
…		…
3660	define before including (or compiling) any of its files. The default in	3664	define before including (or compiling) any of its files. The default in
3661	the absence of autoconf is documented for every option.	3665	the absence of autoconf is documented for every option.
3662		3666
3663	Symbols marked with "(h)" do not change the ABI, and can have different	3667	Symbols marked with "(h)" do not change the ABI, and can have different
3664	values when compiling libev vs. including F<ev.h>, so it is permissible	3668	values when compiling libev vs. including F<ev.h>, so it is permissible
3665	to redefine them before including F<ev.h> without breakign compatibility	3669	to redefine them before including F<ev.h> without breaking compatibility
3666	to a compiled library. All other symbols change the ABI, which means all	3670	to a compiled library. All other symbols change the ABI, which means all
3667	users of libev and the libev code itself must be compiled with compatible	3671	users of libev and the libev code itself must be compiled with compatible
3668	settings.	3672	settings.
3669		3673
3670	=over 4	3674	=over 4
…		…
3891	If you need to shave off some kilobytes of code at the expense of some	3895	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	3896	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	3897	certain subsets of functionality. The default is to enable all features
3894	that can be enabled on the platform.	3898	that can be enabled on the platform.
3895		3899
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	3900	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	3901	with some broad features you want) and then selectively re-enable
3901	additional parts you want, for example if you want everything minimal,	3902	additional parts you want, for example if you want everything minimal,
3902	but multiple event loop support, async and child watchers and the poll	3903	but multiple event loop support, async and child watchers and the poll
3903	backend, use this:	3904	backend, use this:
…		…
3918	Use larger code to speed up some operations.	3919	Use larger code to speed up some operations.
3919		3920
3920	Currently this is used to override some inlining decisions (enlarging the roughly	3921	Currently this is used to override some inlining decisions (enlarging the roughly
3921	30% code size on amd64.	3922	30% code size on amd64.
3922		3923
3923	Also disables C<assert>'s in the code, unless you define C<NDEBUG>	3924	When optimising for size, use of compiler flags such as C<-Os> with
3924	explicitly to C<0>.	3925	gcc recommended, as well as C<-DNDEBUG>, as libev contains a number of
3925		3926	assertions.
3926	Use of compiler flags such as C<-Os> with gcc that optimise for size are
3927	recommended when disabling this feature.
3928		3927
3929	=item C<2> - faster/larger data structures	3928	=item C<2> - faster/larger data structures
3930		3929
3931	Replaces the small 2-heap for timer management by a faster 4-heap, larger	3930	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	3931	hash table sizes and so on. This will usually further increase codesize
…		…
3936	=item C<4> - full API configuration	3935	=item C<4> - full API configuration
3937		3936
3938	This enables priorities (sets C<EV_MAXPRI>=2 and C<EV_MINPRI>=-2), and	3937	This enables priorities (sets C<EV_MAXPRI>=2 and C<EV_MINPRI>=-2), and
3939	enables multiplicity (C<EV_MULTIPLICITY>=1).	3938	enables multiplicity (C<EV_MULTIPLICITY>=1).
3940		3939
		3940	=item C<8> - full API
		3941
3941	It also enables a lot of the "lesser used" core API functions. See C<ev.h>	3942	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	3943	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	feature, and do not complain if this subset changes over time.
3944		3945
3945	=item C<8> - enable all optional watcher types	3946	=item C<16> - enable all optional watcher types
3946		3947
3947	Enables all optional watcher types. If you want to selectively enable	3948	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	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	embed, async, child...) you can enable them manually by defining
3950	C<EV_watchertype_ENABLE> to C<1> instead.	3951	C<EV_watchertype_ENABLE> to C<1> instead.
3951		3952
3952	=item C<16> - enable all backends	3953	=item C<32> - enable all backends
3953		3954
3954	This enables all backends - without this feature, you need to enable at	3955	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	least one backend manually (C<EV_USE_SELECT> is a good choice).
3956		3957
3957	=item C<32> - enable OS-specific "helper" APIs	3958	=item C<64> - enable OS-specific "helper" APIs
3958		3959
3959	Enable inotify, eventfd, signalfd and similar OS-specific helper APIs by	3960	Enable inotify, eventfd, signalfd and similar OS-specific helper APIs by
3960	default.	3961	default.
3961		3962
3962	=back	3963	=back
3963		3964
3964	Compiling with C<gcc -Os -DEV_STANDALONE -DEV_USE_EPOLL=1 -DEV_FEATURES=0>	3965	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	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	3967	code/0.3Kb data on my GNU/Linux amd64 system, while still giving you I/O
3967	clock support.	3968	watchers, timers and monotonic clock support.
3968		3969
3969	With an intelligent-enough linker (gcc+binutils are intelligent enough	3970	With an intelligent-enough linker (gcc+binutils are intelligent enough
3970	when you use C<-Wl,--gc-sections -ffunction-sections>) functions unused by	3971	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	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.	3973	I/O watcher then might come out at only 5Kb.
…		…
4105	file.	4106	file.
4106		4107
4107	The usage in rxvt-unicode is simpler. It has a F<ev_cpp.h> header file	4108	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:	4109	that everybody includes and which overrides some configure choices:
4109		4110
4110	#define EV_FEATURES 0	4111	#define EV_FEATURES 8
4111	#define EV_USE_SELECT 1	4112	#define EV_USE_SELECT 1
		4113	#define EV_PREPARE_ENABLE 1
		4114	#define EV_IDLE_ENABLE 1
		4115	#define EV_SIGNAL_ENABLE 1
		4116	#define EV_CHILD_ENABLE 1
		4117	#define EV_USE_STDEXCEPT 0
4112	#define EV_CONFIG_H <config.h>	4118	#define EV_CONFIG_H <config.h>
4113		4119
4114	#include "ev++.h"	4120	#include "ev++.h"
4115		4121
4116	And a F<ev_cpp.C> implementation file that contains libev proper and is compiled:	4122	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.	4625	involves iterating over all running async watchers or all signal numbers.
4620		4626
4621	=back	4627	=back
4622		4628
4623		4629
		4630	=head1 PORTING FROM LIBEV 3.X TO 4.X
		4631
		4632	The major version 4 introduced some minor incompatible changes to the API.
		4633
		4634	At the moment, the C<ev.h> header file tries to implement superficial
		4635	compatibility, so most programs should still compile. Those might be
		4636	removed in later versions of libev, so better update early than late.
		4637
		4638	=over 4
		4639
		4640	=item C<ev_loop_count> renamed to C<ev_iteration>
		4641
		4642	=item C<ev_loop_depth> renamed to C<ev_depth>
		4643
		4644	=item C<ev_loop_verify> renamed to C<ev_verify>
		4645
		4646	Most functions working on C<struct ev_loop> objects don't have an
		4647	C<ev_loop_> prefix, so it was removed. Note that C<ev_loop_fork> is
		4648	still called C<ev_loop_fork> because it would otherwise clash with the
		4649	C<ev_fork> typedef.
		4650
		4651	=item C<EV_TIMEOUT> renamed to C<EV_TIMER> in C<revents>
		4652
		4653	This is a simple rename - all other watcher types use their name
		4654	as revents flag, and now C<ev_timer> does, too.
		4655
		4656	Both C<EV_TIMER> and C<EV_TIMEOUT> symbols were present in 3.x versions
		4657	and continue to be present for the forseeable future, so this is mostly a
		4658	documentation change.
		4659
		4660	=item C<EV_MINIMAL> mechanism replaced by C<EV_FEATURES>
		4661
		4662	The preprocessor symbol C<EV_MINIMAL> has been replaced by a different
		4663	mechanism, C<EV_FEATURES>. Programs using C<EV_MINIMAL> usually compile
		4664	and work, but the library code will of course be larger.
		4665
		4666	=back
		4667
		4668
4624	=head1 GLOSSARY	4669	=head1 GLOSSARY
4625		4670
4626	=over 4	4671	=over 4
4627		4672
4628	=item active	4673	=item active
…		…
4649	A change of state of some external event, such as data now being available	4694	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	4695	for reading on a file descriptor, time having passed or simply not having
4651	any other events happening anymore.	4696	any other events happening anymore.
4652		4697
4653	In libev, events are represented as single bits (such as C<EV_READ> or	4698	In libev, events are represented as single bits (such as C<EV_READ> or
4654	C<EV_TIMEOUT>).	4699	C<EV_TIMER>).
4655		4700
4656	=item event library	4701	=item event library
4657		4702
4658	A software package implementing an event model and loop.	4703	A software package implementing an event model and loop.
4659		4704

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.292 by sf-exg, Mon Mar 22 09:57: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.292 by sf-exg, Mon Mar 22 09:57:01 2010 UTC