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

Comparing libev/ev.pod (file contents):
Revision 1.199 by root, Thu Oct 23 07:18:21 2008 UTC vs.
Revision 1.205 by root, Mon Oct 27 12:20:32 2008 UTC

…		…
10		10
11	// a single header file is required	11	// a single header file is required
12	#include <ev.h>	12	#include <ev.h>
13		13
14	// every watcher type has its own typedef'd struct	14	// every watcher type has its own typedef'd struct
15	// with the name ev_<type>	15	// with the name ev_TYPE
16	ev_io stdin_watcher;	16	ev_io stdin_watcher;
17	ev_timer timeout_watcher;	17	ev_timer timeout_watcher;
18		18
19	// all watcher callbacks have a similar signature	19	// all watcher callbacks have a similar signature
20	// this callback is called when data is readable on stdin	20	// this callback is called when data is readable on stdin
…		…
276		276
277	=back	277	=back
278		278
279	=head1 FUNCTIONS CONTROLLING THE EVENT LOOP	279	=head1 FUNCTIONS CONTROLLING THE EVENT LOOP
280		280
281	An event loop is described by a C<ev_loop *>. The library knows two	281	An event loop is described by a C<struct ev_loop *> (the C<struct>
282	types of such loops, the I<default> loop, which supports signals and child	282	is I<not> optional in this case, as there is also an C<ev_loop>
283	events, and dynamically created loops which do not.	283	I<function>).
		284
		285	The library knows two types of such loops, the I<default> loop, which
		286	supports signals and child events, and dynamically created loops which do
		287	not.
284		288
285	=over 4	289	=over 4
286		290
287	=item struct ev_loop *ev_default_loop (unsigned int flags)	291	=item struct ev_loop *ev_default_loop (unsigned int flags)
288		292
…		…
380	=item C<EVBACKEND_EPOLL> (value 4, Linux)	384	=item C<EVBACKEND_EPOLL> (value 4, Linux)
381		385
382	For few fds, this backend is a bit little slower than poll and select,	386	For few fds, this backend is a bit little slower than poll and select,
383	but it scales phenomenally better. While poll and select usually scale	387	but it scales phenomenally better. While poll and select usually scale
384	like O(total_fds) where n is the total number of fds (or the highest fd),	388	like O(total_fds) where n is the total number of fds (or the highest fd),
385	epoll scales either O(1) or O(active_fds). The epoll design has a number	389	epoll scales either O(1) or O(active_fds).
386	of shortcomings, such as silently dropping events in some hard-to-detect	390
387	cases and requiring a system call per fd change, no fork support and bad	391	The epoll syscalls are the most misdesigned of the more advanced
388	support for dup.	392	event mechanisms: probelsm include silently dropping events in some
		393	hard-to-detect cases, requiring a system call per fd change, no fork
		394	support, problems with dup and so on.
		395
		396	Epoll is also notoriously buggy - embedding epoll fds should work, but
		397	of course doesn't, and epoll just loves to report events for totally
		398	I<different> file descriptors (even already closed ones, so one cannot
		399	even remove them from the set) than registered in the set (especially
		400	on SMP systems). Libev tries to counter these spurious notifications by
		401	employing an additional generation counter and comparing that against the
		402	events to filter out spurious ones.
389		403
390	While stopping, setting and starting an I/O watcher in the same iteration	404	While stopping, setting and starting an I/O watcher in the same iteration
391	will result in some caching, there is still a system call per such incident	405	will result in some caching, there is still a system call per such incident
392	(because the fd could point to a different file description now), so its	406	(because the fd could point to a different file description now), so its
393	best to avoid that. Also, C<dup ()>'ed file descriptors might not work	407	best to avoid that. Also, C<dup ()>'ed file descriptors might not work
394	very well if you register events for both fds.	408	very well if you register events for both fds.
395
396	Please note that epoll sometimes generates spurious notifications, so you
397	need to use non-blocking I/O or other means to avoid blocking when no data
398	(or space) is available.
399		409
400	Best performance from this backend is achieved by not unregistering all	410	Best performance from this backend is achieved by not unregistering all
401	watchers for a file descriptor until it has been closed, if possible,	411	watchers for a file descriptor until it has been closed, if possible,
402	i.e. keep at least one watcher active per fd at all times. Stopping and	412	i.e. keep at least one watcher active per fd at all times. Stopping and
403	starting a watcher (without re-setting it) also usually doesn't cause	413	starting a watcher (without re-setting it) also usually doesn't cause
…		…
527	responsibility to either stop all watchers cleanly yourself I<before>	537	responsibility to either stop all watchers cleanly yourself I<before>
528	calling this function, or cope with the fact afterwards (which is usually	538	calling this function, or cope with the fact afterwards (which is usually
529	the easiest thing, you can just ignore the watchers and/or C<free ()> them	539	the easiest thing, you can just ignore the watchers and/or C<free ()> them
530	for example).	540	for example).
531		541
532	Note that certain global state, such as signal state, will not be freed by	542	Note that certain global state, such as signal state (and installed signal
533	this function, and related watchers (such as signal and child watchers)	543	handlers), will not be freed by this function, and related watchers (such
534	would need to be stopped manually.	544	as signal and child watchers) would need to be stopped manually.
535		545
536	In general it is not advisable to call this function except in the	546	In general it is not advisable to call this function except in the
537	rare occasion where you really need to free e.g. the signal handling	547	rare occasion where you really need to free e.g. the signal handling
538	pipe fds. If you need dynamically allocated loops it is better to use	548	pipe fds. If you need dynamically allocated loops it is better to use
539	C<ev_loop_new> and C<ev_loop_destroy>).	549	C<ev_loop_new> and C<ev_loop_destroy>).
…		…
768	they fire on, say, one-second boundaries only.	778	they fire on, say, one-second boundaries only.
769		779
770	=item ev_loop_verify (loop)	780	=item ev_loop_verify (loop)
771		781
772	This function only does something when C<EV_VERIFY> support has been	782	This function only does something when C<EV_VERIFY> support has been
773	compiled in. which is the default for non-minimal builds. It tries to go	783	compiled in, which is the default for non-minimal builds. It tries to go
774	through all internal structures and checks them for validity. If anything	784	through all internal structures and checks them for validity. If anything
775	is found to be inconsistent, it will print an error message to standard	785	is found to be inconsistent, it will print an error message to standard
776	error and call C<abort ()>.	786	error and call C<abort ()>.
777		787
778	This can be used to catch bugs inside libev itself: under normal	788	This can be used to catch bugs inside libev itself: under normal
…		…
781		791
782	=back	792	=back
783		793
784		794
785	=head1 ANATOMY OF A WATCHER	795	=head1 ANATOMY OF A WATCHER
		796
		797	In the following description, uppercase C<TYPE> in names stands for the
		798	watcher type, e.g. C<ev_TYPE_start> can mean C<ev_timer_start> for timer
		799	watchers and C<ev_io_start> for I/O watchers.
786		800
787	A watcher is a structure that you create and register to record your	801	A watcher is a structure that you create and register to record your
788	interest in some event. For instance, if you want to wait for STDIN to	802	interest in some event. For instance, if you want to wait for STDIN to
789	become readable, you would create an C<ev_io> watcher for that:	803	become readable, you would create an C<ev_io> watcher for that:
790		804
…		…
793	ev_io_stop (w);	807	ev_io_stop (w);
794	ev_unloop (loop, EVUNLOOP_ALL);	808	ev_unloop (loop, EVUNLOOP_ALL);
795	}	809	}
796		810
797	struct ev_loop *loop = ev_default_loop (0);	811	struct ev_loop *loop = ev_default_loop (0);
		812
798	ev_io stdin_watcher;	813	ev_io stdin_watcher;
		814
799	ev_init (&stdin_watcher, my_cb);	815	ev_init (&stdin_watcher, my_cb);
800	ev_io_set (&stdin_watcher, STDIN_FILENO, EV_READ);	816	ev_io_set (&stdin_watcher, STDIN_FILENO, EV_READ);
801	ev_io_start (loop, &stdin_watcher);	817	ev_io_start (loop, &stdin_watcher);
		818
802	ev_loop (loop, 0);	819	ev_loop (loop, 0);
803		820
804	As you can see, you are responsible for allocating the memory for your	821	As you can see, you are responsible for allocating the memory for your
805	watcher structures (and it is usually a bad idea to do this on the stack,	822	watcher structures (and it is I<usually> a bad idea to do this on the
806	although this can sometimes be quite valid).	823	stack).
		824
		825	Each watcher has an associated watcher structure (called C<struct ev_TYPE>
		826	or simply C<ev_TYPE>, as typedefs are provided for all watcher structs).
807		827
808	Each watcher structure must be initialised by a call to C<ev_init	828	Each watcher structure must be initialised by a call to C<ev_init
809	(watcher *, callback)>, which expects a callback to be provided. This	829	(watcher *, callback)>, which expects a callback to be provided. This
810	callback gets invoked each time the event occurs (or, in the case of I/O	830	callback gets invoked each time the event occurs (or, in the case of I/O
811	watchers, each time the event loop detects that the file descriptor given	831	watchers, each time the event loop detects that the file descriptor given
812	is readable and/or writable).	832	is readable and/or writable).
813		833
814	Each watcher type has its own C<< ev_<type>_set (watcher *, ...) >> macro	834	Each watcher type further has its own C<< ev_TYPE_set (watcher *, ...) >>
815	with arguments specific to this watcher type. There is also a macro	835	macro to configure it, with arguments specific to the watcher type. There
816	to combine initialisation and setting in one call: C<< ev_<type>_init	836	is also a macro to combine initialisation and setting in one call: C<<
817	(watcher *, callback, ...) >>.	837	ev_TYPE_init (watcher *, callback, ...) >>.
818		838
819	To make the watcher actually watch out for events, you have to start it	839	To make the watcher actually watch out for events, you have to start it
820	with a watcher-specific start function (C<< ev_<type>_start (loop, watcher	840	with a watcher-specific start function (C<< ev_TYPE_start (loop, watcher
821	*) >>), and you can stop watching for events at any time by calling the	841	*) >>), and you can stop watching for events at any time by calling the
822	corresponding stop function (C<< ev_<type>_stop (loop, watcher *) >>.	842	corresponding stop function (C<< ev_TYPE_stop (loop, watcher *) >>.
823		843
824	As long as your watcher is active (has been started but not stopped) you	844	As long as your watcher is active (has been started but not stopped) you
825	must not touch the values stored in it. Most specifically you must never	845	must not touch the values stored in it. Most specifically you must never
826	reinitialise it or call its C<set> macro.	846	reinitialise it or call its C<ev_TYPE_set> macro.
827		847
828	Each and every callback receives the event loop pointer as first, the	848	Each and every callback receives the event loop pointer as first, the
829	registered watcher structure as second, and a bitset of received events as	849	registered watcher structure as second, and a bitset of received events as
830	third argument.	850	third argument.
831		851
…		…
912		932
913	=back	933	=back
914		934
915	=head2 GENERIC WATCHER FUNCTIONS	935	=head2 GENERIC WATCHER FUNCTIONS
916		936
917	In the following description, C<TYPE> stands for the watcher type,
918	e.g. C<timer> for C<ev_timer> watchers and C<io> for C<ev_io> watchers.
919
920	=over 4	937	=over 4
921		938
922	=item C<ev_init> (ev_TYPE *watcher, callback)	939	=item C<ev_init> (ev_TYPE *watcher, callback)
923		940
924	This macro initialises the generic portion of a watcher. The contents	941	This macro initialises the generic portion of a watcher. The contents
…		…
1032	The default priority used by watchers when no priority has been set is	1049	The default priority used by watchers when no priority has been set is
1033	always C<0>, which is supposed to not be too high and not be too low :).	1050	always C<0>, which is supposed to not be too high and not be too low :).
1034		1051
1035	Setting a priority outside the range of C<EV_MINPRI> to C<EV_MAXPRI> is	1052	Setting a priority outside the range of C<EV_MINPRI> to C<EV_MAXPRI> is
1036	fine, as long as you do not mind that the priority value you query might	1053	fine, as long as you do not mind that the priority value you query might
1037	or might not have been adjusted to be within valid range.	1054	or might not have been clamped to the valid range.
1038		1055
1039	=item ev_invoke (loop, ev_TYPE *watcher, int revents)	1056	=item ev_invoke (loop, ev_TYPE *watcher, int revents)
1040		1057
1041	Invoke the C<watcher> with the given C<loop> and C<revents>. Neither	1058	Invoke the C<watcher> with the given C<loop> and C<revents>. Neither
1042	C<loop> nor C<revents> need to be valid as long as the watcher callback	1059	C<loop> nor C<revents> need to be valid as long as the watcher callback
…		…
1426		1443
1427	Changing the timeout is trivial as well (if it isn't hard-coded in the	1444	Changing the timeout is trivial as well (if it isn't hard-coded in the
1428	callback :) - just change the timeout and invoke the callback, which will	1445	callback :) - just change the timeout and invoke the callback, which will
1429	fix things for you.	1446	fix things for you.
1430		1447
1431	=item 4. Whee, use a double-linked list for your timeouts.	1448	=item 4. Wee, just use a double-linked list for your timeouts.
1432		1449
1433	If there is not one request, but many thousands, all employing some kind	1450	If there is not one request, but many thousands (millions...), all
1434	of timeout with the same timeout value, then one can do even better:	1451	employing some kind of timeout with the same timeout value, then one can
		1452	do even better:
1435		1453
1436	When starting the timeout, calculate the timeout value and put the timeout	1454	When starting the timeout, calculate the timeout value and put the timeout
1437	at the I<end> of the list.	1455	at the I<end> of the list.
1438		1456
1439	Then use an C<ev_timer> to fire when the timeout at the I<beginning> of	1457	Then use an C<ev_timer> to fire when the timeout at the I<beginning> of
…		…
1448	complication, and having to use a constant timeout. The constant timeout	1466	complication, and having to use a constant timeout. The constant timeout
1449	ensures that the list stays sorted.	1467	ensures that the list stays sorted.
1450		1468
1451	=back	1469	=back
1452		1470
1453	So what method is the best?	1471	So which method the best?
1454		1472
1455	The method #2 is a simple no-brain-required solution that is adequate in	1473	Method #2 is a simple no-brain-required solution that is adequate in most
1456	most situations. Method #3 requires a bit more thinking, but handles many	1474	situations. Method #3 requires a bit more thinking, but handles many cases
1457	cases better, and isn't very complicated either. In most case, choosing	1475	better, and isn't very complicated either. In most case, choosing either
1458	either one is fine.	1476	one is fine, with #3 being better in typical situations.
1459		1477
1460	Method #1 is almost always a bad idea, and buys you nothing. Method #4 is	1478	Method #1 is almost always a bad idea, and buys you nothing. Method #4 is
1461	rather complicated, but extremely efficient, something that really pays	1479	rather complicated, but extremely efficient, something that really pays
1462	off after the first or so million of active timers, i.e. it's usually	1480	off after the first million or so of active timers, i.e. it's usually
1463	overkill :)	1481	overkill :)
1464		1482
1465	=head3 The special problem of time updates	1483	=head3 The special problem of time updates
1466		1484
1467	Establishing the current time is a costly operation (it usually takes at	1485	Establishing the current time is a costly operation (it usually takes at
…		…
2946	=item D	2964	=item D
2947		2965
2948	Leandro Lucarella has written a D language binding (F<ev.d>) for libev, to	2966	Leandro Lucarella has written a D language binding (F<ev.d>) for libev, to
2949	be found at L<http://proj.llucax.com.ar/wiki/evd>.	2967	be found at L<http://proj.llucax.com.ar/wiki/evd>.
2950		2968
		2969	=item Ocaml
		2970
		2971	Erkki Seppala has written Ocaml bindings for libev, to be found at
		2972	L<http://modeemi.cs.tut.fi/~flux/software/ocaml-ev/>.
		2973
2951	=back	2974	=back
2952		2975
2953		2976
2954	=head1 MACRO MAGIC	2977	=head1 MACRO MAGIC
2955		2978

Diff Legend

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

Comparing libev/ev.pod (file contents): Revision 1.199 by root, Thu Oct 23 07:18:21 2008 UTC vs. Revision 1.205 by root, Mon Oct 27 12:20:32 2008 UTC

Diff Legend

Comparing libev/ev.pod (file contents):
Revision 1.199 by root, Thu Oct 23 07:18:21 2008 UTC vs.
Revision 1.205 by root, Mon Oct 27 12:20:32 2008 UTC