[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.297 by root, Tue Jun 29 11:49:02 2010 UTC

…		…
124	this argument.	124	this argument.
125		125
126	=head2 TIME REPRESENTATION	126	=head2 TIME REPRESENTATION
127		127
128	Libev represents time as a single floating point number, representing	128	Libev represents time as a single floating point number, representing
129	the (fractional) number of seconds since the (POSIX) epoch (somewhere	129	the (fractional) number of seconds since the (POSIX) epoch (in practise
130	near the beginning of 1970, details are complicated, don't ask). This	130	somewhere near the beginning of 1970, details are complicated, don't
131	type is called C<ev_tstamp>, which is what you should use too. It usually	131	ask). This type is called C<ev_tstamp>, which is what you should use
132	aliases to the C<double> type in C. When you need to do any calculations	132	too. It usually aliases to the C<double> type in C. When you need to do
133	on it, you should treat it as some floating point value. Unlike the name	133	any calculations on it, you should treat it as some floating point value.
		134
134	component C<stamp> might indicate, it is also used for time differences	135	Unlike the name component C<stamp> might indicate, it is also used for
135	throughout libev.	136	time differences (e.g. delays) throughout libev.
136		137
137	=head1 ERROR HANDLING	138	=head1 ERROR HANDLING
138		139
139	Libev knows three classes of errors: operating system errors, usage errors	140	Libev knows three classes of errors: operating system errors, usage errors
140	and internal errors (bugs).	141	and internal errors (bugs).
…		…
191	as this indicates an incompatible change. Minor versions are usually	192	as this indicates an incompatible change. Minor versions are usually
192	compatible to older versions, so a larger minor version alone is usually	193	compatible to older versions, so a larger minor version alone is usually
193	not a problem.	194	not a problem.
194		195
195	Example: Make sure we haven't accidentally been linked against the wrong	196	Example: Make sure we haven't accidentally been linked against the wrong
196	version.	197	version (note, however, that this will not detect ABI mismatches :).
197		198
198	assert (("libev version mismatch",	199	assert (("libev version mismatch",
199	ev_version_major () == EV_VERSION_MAJOR	200	ev_version_major () == EV_VERSION_MAJOR
200	&& ev_version_minor () >= EV_VERSION_MINOR));	201	&& ev_version_minor () >= EV_VERSION_MINOR));
201		202
…		…
345	useful to try out specific backends to test their performance, or to work	346	useful to try out specific backends to test their performance, or to work
346	around bugs.	347	around bugs.
347		348
348	=item C<EVFLAG_FORKCHECK>	349	=item C<EVFLAG_FORKCHECK>
349		350
350	Instead of calling C<ev_default_fork> or C<ev_loop_fork> manually after	351	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	352	make libev check for a fork in each iteration by enabling this flag.
352	enabling this flag.
353		353
354	This works by calling C<getpid ()> on every iteration of the loop,	354	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	355	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	356	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	357	GNU/Linux system for example, C<getpid> is actually a simple 5-insn sequence
…		…
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
…		…
614	name, you can call it anytime, but it makes most sense after forking, in	611	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	612	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	613	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.	614	functions, and it will only take effect at the next C<ev_loop> iteration.
618		615
		616	Again, you I<have> to call it on I<any> loop that you want to re-use after
		617	a fork, I<even if you do not plan to use the loop in the parent>. This is
		618	because some kernel interfaces cough I<kqueue> cough do funny things
		619	during fork.
		620
619	On the other hand, you only need to call this function in the child	621	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	622	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.	623	just fork+exec or create a new loop in the child, you don't have to call
		624	it at all.
622		625
623	The function itself is quite fast and it's usually not a problem to call	626	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	627	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>:	628	quite nicely into a call to C<pthread_atfork>:
626		629
…		…
628		631
629	=item ev_loop_fork (loop)	632	=item ev_loop_fork (loop)
630		633
631	Like C<ev_default_fork>, but acts on an event loop created by	634	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	635	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	636	after fork that you want to re-use in the child, and how you keep track of
634	entirely your own problem.	637	them is entirely your own problem.
635		638
636	=item int ev_is_default_loop (loop)	639	=item int ev_is_default_loop (loop)
637		640
638	Returns true when the given loop is, in fact, the default loop, and false	641	Returns true when the given loop is, in fact, the default loop, and false
639	otherwise.	642	otherwise.
640		643
641	=item unsigned int ev_loop_count (loop)	644	=item unsigned int ev_iteration (loop)
642		645
643	Returns the count of loop iterations for the loop, which is identical to	646	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	647	the number of times libev did poll for new events. It starts at C<0> and
645	happily wraps around with enough iterations.	648	happily wraps around with enough iterations.
646		649
647	This value can sometimes be useful as a generation counter of sorts (it	650	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	651	"ticks" the number of loop iterations), as it roughly corresponds with
649	C<ev_prepare> and C<ev_check> calls.	652	C<ev_prepare> and C<ev_check> calls - and is incremented between the
		653	prepare and check phases.
650		654
651	=item unsigned int ev_loop_depth (loop)	655	=item unsigned int ev_depth (loop)
652		656
653	Returns the number of times C<ev_loop> was entered minus the number of	657	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.	658	times C<ev_loop> was exited, in other words, the recursion depth.
655		659
656	Outside C<ev_loop>, this number is zero. In a callback, this number is	660	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),	661	C<1>, unless C<ev_loop> was invoked recursively (or from another thread),
658	in which case it is higher.	662	in which case it is higher.
659		663
660	Leaving C<ev_loop> abnormally (setjmp/longjmp, cancelling the thread	664	Leaving C<ev_loop> abnormally (setjmp/longjmp, cancelling the thread
661	etc.), doesn't count as exit.	665	etc.), doesn't count as "exit" - consider this as a hint to avoid such
		666	ungentleman behaviour unless it's really convenient.
662		667
663	=item unsigned int ev_backend (loop)	668	=item unsigned int ev_backend (loop)
664		669
665	Returns one of the C<EVBACKEND_*> flags indicating the event backend in	670	Returns one of the C<EVBACKEND_*> flags indicating the event backend in
666	use.	671	use.
…		…
1032	=item C<EV_WRITE>	1037	=item C<EV_WRITE>
1033		1038
1034	The file descriptor in the C<ev_io> watcher has become readable and/or	1039	The file descriptor in the C<ev_io> watcher has become readable and/or
1035	writable.	1040	writable.
1036		1041
1037	=item C<EV_TIMEOUT>	1042	=item C<EV_TIMER>
1038		1043
1039	The C<ev_timer> watcher has timed out.	1044	The C<ev_timer> watcher has timed out.
1040		1045
1041	=item C<EV_PERIODIC>	1046	=item C<EV_PERIODIC>
1042		1047
…		…
1399	{	1404	{
1400	// stop the I/O watcher, we received the event, but	1405	// stop the I/O watcher, we received the event, but
1401	// are not yet ready to handle it.	1406	// are not yet ready to handle it.
1402	ev_io_stop (EV_A_ w);	1407	ev_io_stop (EV_A_ w);
1403		1408
1404	// start the idle watcher to ahndle the actual event.	1409	// start the idle watcher to handle the actual event.
1405	// it will not be executed as long as other watchers	1410	// it will not be executed as long as other watchers
1406	// with the default priority are receiving events.	1411	// with the default priority are receiving events.
1407	ev_idle_start (EV_A_ &idle);	1412	ev_idle_start (EV_A_ &idle);
1408	}	1413	}
1409		1414
…		…
1538		1543
1539	So when you encounter spurious, unexplained daemon exits, make sure you	1544	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	1545	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).	1546	somewhere, as that would have given you a big clue).
1542		1547
		1548	=head3 The special problem of accept()ing when you can't
		1549
		1550	Many implementations of the POSIX C<accept> function (for example,
		1551	found in post-2004 Linux) have the peculiar behaviour of not removing a
		1552	connection from the pending queue in all error cases.
		1553
		1554	For example, larger servers often run out of file descriptors (because
		1555	of resource limits), causing C<accept> to fail with C<ENFILE> but not
		1556	rejecting the connection, leading to libev signalling readiness on
		1557	the next iteration again (the connection still exists after all), and
		1558	typically causing the program to loop at 100% CPU usage.
		1559
		1560	Unfortunately, the set of errors that cause this issue differs between
		1561	operating systems, there is usually little the app can do to remedy the
		1562	situation, and no known thread-safe method of removing the connection to
		1563	cope with overload is known (to me).
		1564
		1565	One of the easiest ways to handle this situation is to just ignore it
		1566	- when the program encounters an overload, it will just loop until the
		1567	situation is over. While this is a form of busy waiting, no OS offers an
		1568	event-based way to handle this situation, so it's the best one can do.
		1569
		1570	A better way to handle the situation is to log any errors other than
		1571	C<EAGAIN> and C<EWOULDBLOCK>, making sure not to flood the log with such
		1572	messages, and continue as usual, which at least gives the user an idea of
		1573	what could be wrong ("raise the ulimit!"). For extra points one could stop
		1574	the C<ev_io> watcher on the listening fd "for a while", which reduces CPU
		1575	usage.
		1576
		1577	If your program is single-threaded, then you could also keep a dummy file
		1578	descriptor for overload situations (e.g. by opening F</dev/null>), and
		1579	when you run into C<ENFILE> or C<EMFILE>, close it, run C<accept>,
		1580	close that fd, and create a new dummy fd. This will gracefully refuse
		1581	clients under typical overload conditions.
		1582
		1583	The last way to handle it is to simply log the error and C<exit>, as
		1584	is often done with C<malloc> failures, but this results in an easy
		1585	opportunity for a DoS attack.
1543		1586
1544	=head3 Watcher-Specific Functions	1587	=head3 Watcher-Specific Functions
1545		1588
1546	=over 4	1589	=over 4
1547		1590
…		…
1726	to the current time (meaning we just have some activity :), then call the	1769	to the current time (meaning we just have some activity :), then call the
1727	callback, which will "do the right thing" and start the timer:	1770	callback, which will "do the right thing" and start the timer:
1728		1771
1729	ev_init (timer, callback);	1772	ev_init (timer, callback);
1730	last_activity = ev_now (loop);	1773	last_activity = ev_now (loop);
1731	callback (loop, timer, EV_TIMEOUT);	1774	callback (loop, timer, EV_TIMER);
1732		1775
1733	And when there is some activity, simply store the current time in	1776	And when there is some activity, simply store the current time in
1734	C<last_activity>, no libev calls at all:	1777	C<last_activity>, no libev calls at all:
1735		1778
1736	last_actiivty = ev_now (loop);	1779	last_activity = ev_now (loop);
1737		1780
1738	This technique is slightly more complex, but in most cases where the	1781	This technique is slightly more complex, but in most cases where the
1739	time-out is unlikely to be triggered, much more efficient.	1782	time-out is unlikely to be triggered, much more efficient.
1740		1783
1741	Changing the timeout is trivial as well (if it isn't hard-coded in the	1784	Changing the timeout is trivial as well (if it isn't hard-coded in the
…		…
3141		3184
3142	If C<timeout> is less than 0, then no timeout watcher will be	3185	If C<timeout> is less than 0, then no timeout watcher will be
3143	started. Otherwise an C<ev_timer> watcher with after = C<timeout> (and	3186	started. Otherwise an C<ev_timer> watcher with after = C<timeout> (and
3144	repeat = 0) will be started. C<0> is a valid timeout.	3187	repeat = 0) will be started. C<0> is a valid timeout.
3145		3188
3146	The callback has the type C<void (cb)(int revents, void arg)> and gets	3189	The callback has the type C<void (cb)(int revents, void arg)> and is
3147	passed an C<revents> set like normal event callbacks (a combination of	3190	passed an C<revents> set like normal event callbacks (a combination of
3148	C<EV_ERROR>, C<EV_READ>, C<EV_WRITE> or C<EV_TIMEOUT>) and the C<arg>	3191	C<EV_ERROR>, C<EV_READ>, C<EV_WRITE> or C<EV_TIMER>) and the C<arg>
3149	value passed to C<ev_once>. Note that it is possible to receive I<both>	3192	value passed to C<ev_once>. Note that it is possible to receive I<both>
3150	a timeout and an io event at the same time - you probably should give io	3193	a timeout and an io event at the same time - you probably should give io
3151	events precedence.	3194	events precedence.
3152		3195
3153	Example: wait up to ten seconds for data to appear on STDIN_FILENO.	3196	Example: wait up to ten seconds for data to appear on STDIN_FILENO.
3154		3197
3155	static void stdin_ready (int revents, void *arg)	3198	static void stdin_ready (int revents, void *arg)
3156	{	3199	{
3157	if (revents & EV_READ)	3200	if (revents & EV_READ)
3158	/* stdin might have data for us, joy! */;	3201	/* stdin might have data for us, joy! */;
3159	else if (revents & EV_TIMEOUT)	3202	else if (revents & EV_TIMER)
3160	/* doh, nothing entered */;	3203	/* doh, nothing entered */;
3161	}	3204	}
3162		3205
3163	ev_once (STDIN_FILENO, EV_READ, 10., stdin_ready, 0);	3206	ev_once (STDIN_FILENO, EV_READ, 10., stdin_ready, 0);
3164		3207
…		…
3298	myclass obj;	3341	myclass obj;
3299	ev::io iow;	3342	ev::io iow;
3300	iow.set <myclass, &myclass::io_cb> (&obj);	3343	iow.set <myclass, &myclass::io_cb> (&obj);
3301		3344
3302	=item w->set (object *)	3345	=item w->set (object *)
3303
3304	This is an B<experimental> feature that might go away in a future version.
3305		3346
3306	This is a variation of a method callback - leaving out the method to call	3347	This is a variation of a method callback - leaving out the method to call
3307	will default the method to C<operator ()>, which makes it possible to use	3348	will default the method to C<operator ()>, which makes it possible to use
3308	functor objects without having to manually specify the C<operator ()> all	3349	functor objects without having to manually specify the C<operator ()> all
3309	the time. Incidentally, you can then also leave out the template argument	3350	the time. Incidentally, you can then also leave out the template argument
…		…
3622	define before including (or compiling) any of its files. The default in	3663	define before including (or compiling) any of its files. The default in
3623	the absence of autoconf is documented for every option.	3664	the absence of autoconf is documented for every option.
3624		3665
3625	Symbols marked with "(h)" do not change the ABI, and can have different	3666	Symbols marked with "(h)" do not change the ABI, and can have different
3626	values when compiling libev vs. including F<ev.h>, so it is permissible	3667	values when compiling libev vs. including F<ev.h>, so it is permissible
3627	to redefine them before including F<ev.h> without breakign compatibility	3668	to redefine them before including F<ev.h> without breaking compatibility
3628	to a compiled library. All other symbols change the ABI, which means all	3669	to a compiled library. All other symbols change the ABI, which means all
3629	users of libev and the libev code itself must be compiled with compatible	3670	users of libev and the libev code itself must be compiled with compatible
3630	settings.	3671	settings.
3631		3672
3632	=over 4	3673	=over 4
…		…
3838	fine.	3879	fine.
3839		3880
3840	If your embedding application does not need any priorities, defining these	3881	If your embedding application does not need any priorities, defining these
3841	both to C<0> will save some memory and CPU.	3882	both to C<0> will save some memory and CPU.
3842		3883
3843	=item EV_PERIODIC_ENABLE	3884	=item EV_PERIODIC_ENABLE, EV_IDLE_ENABLE, EV_EMBED_ENABLE, EV_STAT_ENABLE,
		3885	EV_PREPARE_ENABLE, EV_CHECK_ENABLE, EV_FORK_ENABLE, EV_SIGNAL_ENABLE,
		3886	EV_ASYNC_ENABLE, EV_CHILD_ENABLE.
3844		3887
3845	If undefined or defined to be C<1>, then periodic timers are supported. If	3888	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	3889	the respective watcher type is supported. If defined to be C<0>, then it
3847	code.	3890	is not. Disabling watcher types mainly saves codesize.
3848		3891
3849	=item EV_IDLE_ENABLE	3892	=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		3893
3888	If you need to shave off some kilobytes of code at the expense of some	3894	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	3895	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	3896	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	3897	that can be enabled on the platform.
3892	the default 4-heap.
3893		3898
3894	You can save even more by disabling watcher types you do not need	3899	A typical way to use this symbol is to define it to C<0> (or to a bitset
3895	and setting C<EV_MAXPRI> == C<EV_MINPRI>. Also, disabling C<assert>	3900	with some broad features you want) and then selectively re-enable
3896	(C<-DNDEBUG>) will usually reduce code size a lot. Disabling inotify,	3901	additional parts you want, for example if you want everything minimal,
3897	eventfd and signalfd will further help, and disabling backends one doesn't	3902	but multiple event loop support, async and child watchers and the poll
3898	need (e.g. poll, epoll, kqueue, ports) will help further.	3903	backend, use this:
3899		3904
3900	Defining C<EV_MINIMAL> to C<2> will additionally reduce the core API to	3905	#define EV_FEATURES 0
3901	provide a bare-bones event library. See C<ev.h> for details on what parts
3902	of the API are still available, and do not complain if this subset changes
3903	over time.
3904
3905	This example set of settings reduces the compiled size of libev from 24Kb
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	When optimising for size, use of compiler flags such as C<-Os> with
		3924	gcc recommended, as well as C<-DNDEBUG>, as libev contains a number of
		3925	assertions.
		3926
		3927	=item C<2> - faster/larger data structures
		3928
		3929	Replaces the small 2-heap for timer management by a faster 4-heap, larger
		3930	hash table sizes and so on. This will usually further increase codesize
		3931	and can additionally have an effect on the size of data structures at
		3932	runtime.
		3933
		3934	=item C<4> - full API configuration
		3935
		3936	This enables priorities (sets C<EV_MAXPRI>=2 and C<EV_MINPRI>=-2), and
		3937	enables multiplicity (C<EV_MULTIPLICITY>=1).
		3938
		3939	=item C<8> - full API
		3940
		3941	This enables a lot of the "lesser used" API functions. See C<ev.h> for
		3942	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<16> - 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<32> - 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<64> - 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 code/2.8Kb data to 6.5Kb
		3966	code/0.3Kb data on my GNU/Linux amd64 system, while still giving you I/O
		3967	watchers, timers and monotonic 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 8
4077	#define EV_USE_POLL 0	4111	#define EV_USE_SELECT 1
4078	#define EV_MULTIPLICITY 0
4079	#define EV_PERIODIC_ENABLE 0	4112	#define EV_PREPARE_ENABLE 1
		4113	#define EV_IDLE_ENABLE 1
4080	#define EV_STAT_ENABLE 0	4114	#define EV_SIGNAL_ENABLE 1
4081	#define EV_FORK_ENABLE 0	4115	#define EV_CHILD_ENABLE 1
		4116	#define EV_USE_STDEXCEPT 0
4082	#define EV_CONFIG_H <config.h>	4117	#define EV_CONFIG_H <config.h>
4083	#define EV_MINPRI 0
4084	#define EV_MAXPRI 0
4085		4118
4086	#include "ev++.h"	4119	#include "ev++.h"
4087		4120
4088	And a F<ev_cpp.C> implementation file that contains libev proper and is compiled:	4121	And a F<ev_cpp.C> implementation file that contains libev proper and is compiled:
4089		4122
…		…
4591	involves iterating over all running async watchers or all signal numbers.	4624	involves iterating over all running async watchers or all signal numbers.
4592		4625
4593	=back	4626	=back
4594		4627
4595		4628
		4629	=head1 PORTING FROM LIBEV 3.X TO 4.X
		4630
		4631	The major version 4 introduced some minor incompatible changes to the API.
		4632
		4633	At the moment, the C<ev.h> header file tries to implement superficial
		4634	compatibility, so most programs should still compile. Those might be
		4635	removed in later versions of libev, so better update early than late.
		4636
		4637	=over 4
		4638
		4639	=item C<ev_loop_count> renamed to C<ev_iteration>
		4640
		4641	=item C<ev_loop_depth> renamed to C<ev_depth>
		4642
		4643	=item C<ev_loop_verify> renamed to C<ev_verify>
		4644
		4645	Most functions working on C<struct ev_loop> objects don't have an
		4646	C<ev_loop_> prefix, so it was removed. Note that C<ev_loop_fork> is
		4647	still called C<ev_loop_fork> because it would otherwise clash with the
		4648	C<ev_fork> typedef.
		4649
		4650	=item C<EV_TIMEOUT> renamed to C<EV_TIMER> in C<revents>
		4651
		4652	This is a simple rename - all other watcher types use their name
		4653	as revents flag, and now C<ev_timer> does, too.
		4654
		4655	Both C<EV_TIMER> and C<EV_TIMEOUT> symbols were present in 3.x versions
		4656	and continue to be present for the forseeable future, so this is mostly a
		4657	documentation change.
		4658
		4659	=item C<EV_MINIMAL> mechanism replaced by C<EV_FEATURES>
		4660
		4661	The preprocessor symbol C<EV_MINIMAL> has been replaced by a different
		4662	mechanism, C<EV_FEATURES>. Programs using C<EV_MINIMAL> usually compile
		4663	and work, but the library code will of course be larger.
		4664
		4665	=back
		4666
		4667
4596	=head1 GLOSSARY	4668	=head1 GLOSSARY
4597		4669
4598	=over 4	4670	=over 4
4599		4671
4600	=item active	4672	=item active
…		…
4621	A change of state of some external event, such as data now being available	4693	A change of state of some external event, such as data now being available
4622	for reading on a file descriptor, time having passed or simply not having	4694	for reading on a file descriptor, time having passed or simply not having
4623	any other events happening anymore.	4695	any other events happening anymore.
4624		4696
4625	In libev, events are represented as single bits (such as C<EV_READ> or	4697	In libev, events are represented as single bits (such as C<EV_READ> or
4626	C<EV_TIMEOUT>).	4698	C<EV_TIMER>).
4627		4699
4628	=item event library	4700	=item event library
4629		4701
4630	A software package implementing an event model and loop.	4702	A software package implementing an event model and loop.
4631		4703

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.297 by root, Tue Jun 29 11:49:02 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.297 by root, Tue Jun 29 11:49:02 2010 UTC