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

Comparing libev/ev.pod (file contents):
Revision 1.111 by root, Tue Dec 25 18:01:20 2007 UTC vs.
Revision 1.116 by root, Mon Dec 31 01:34:09 2007 UTC

…		…
551	usually a better approach for this kind of thing.	551	usually a better approach for this kind of thing.
552		552
553	Here are the gory details of what C<ev_loop> does:	553	Here are the gory details of what C<ev_loop> does:
554		554
555	- Before the first iteration, call any pending watchers.	555	- Before the first iteration, call any pending watchers.
556	* If there are no active watchers (reference count is zero), return.	556	* If EVFLAG_FORKCHECK was used, check for a fork.
557	- Queue all prepare watchers and then call all outstanding watchers.	557	- If a fork was detected, queue and call all fork watchers.
		558	- Queue and call all prepare watchers.
558	- If we have been forked, recreate the kernel state.	559	- If we have been forked, recreate the kernel state.
559	- Update the kernel state with all outstanding changes.	560	- Update the kernel state with all outstanding changes.
560	- Update the "event loop time".	561	- Update the "event loop time".
561	- Calculate for how long to block.	562	- Calculate for how long to sleep or block, if at all
		563	(active idle watchers, EVLOOP_NONBLOCK or not having
		564	any active watchers at all will result in not sleeping).
		565	- Sleep if the I/O and timer collect interval say so.
562	- Block the process, waiting for any events.	566	- Block the process, waiting for any events.
563	- Queue all outstanding I/O (fd) events.	567	- Queue all outstanding I/O (fd) events.
564	- Update the "event loop time" and do time jump handling.	568	- Update the "event loop time" and do time jump handling.
565	- Queue all outstanding timers.	569	- Queue all outstanding timers.
566	- Queue all outstanding periodics.	570	- Queue all outstanding periodics.
567	- If no events are pending now, queue all idle watchers.	571	- If no events are pending now, queue all idle watchers.
568	- Queue all check watchers.	572	- Queue all check watchers.
569	- Call all queued watchers in reverse order (i.e. check watchers first).	573	- Call all queued watchers in reverse order (i.e. check watchers first).
570	Signals and child watchers are implemented as I/O watchers, and will	574	Signals and child watchers are implemented as I/O watchers, and will
571	be handled here by queueing them when their watcher gets executed.	575	be handled here by queueing them when their watcher gets executed.
572	- If ev_unloop has been called or EVLOOP_ONESHOT or EVLOOP_NONBLOCK	576	- If ev_unloop has been called, or EVLOOP_ONESHOT or EVLOOP_NONBLOCK
573	were used, return, otherwise continue with step *.	577	were used, or there are no active watchers, return, otherwise
		578	continue with step *.
574		579
575	Example: Queue some jobs and then loop until no events are outsanding	580	Example: Queue some jobs and then loop until no events are outstanding
576	anymore.	581	anymore.
577		582
578	... queue jobs here, make sure they register event watchers as long	583	... queue jobs here, make sure they register event watchers as long
579	... as they still have work to do (even an idle watcher will do..)	584	... as they still have work to do (even an idle watcher will do..)
580	ev_loop (my_loop, 0);	585	ev_loop (my_loop, 0);
…		…
584		589
585	Can be used to make a call to C<ev_loop> return early (but only after it	590	Can be used to make a call to C<ev_loop> return early (but only after it
586	has processed all outstanding events). The C<how> argument must be either	591	has processed all outstanding events). The C<how> argument must be either
587	C<EVUNLOOP_ONE>, which will make the innermost C<ev_loop> call return, or	592	C<EVUNLOOP_ONE>, which will make the innermost C<ev_loop> call return, or
588	C<EVUNLOOP_ALL>, which will make all nested C<ev_loop> calls return.	593	C<EVUNLOOP_ALL>, which will make all nested C<ev_loop> calls return.
		594
		595	This "unloop state" will be cleared when entering C<ev_loop> again.
589		596
590	=item ev_ref (loop)	597	=item ev_ref (loop)
591		598
592	=item ev_unref (loop)	599	=item ev_unref (loop)
593		600
…		…
598	returning, ev_unref() after starting, and ev_ref() before stopping it. For	605	returning, ev_unref() after starting, and ev_ref() before stopping it. For
599	example, libev itself uses this for its internal signal pipe: It is not	606	example, libev itself uses this for its internal signal pipe: It is not
600	visible to the libev user and should not keep C<ev_loop> from exiting if	607	visible to the libev user and should not keep C<ev_loop> from exiting if
601	no event watchers registered by it are active. It is also an excellent	608	no event watchers registered by it are active. It is also an excellent
602	way to do this for generic recurring timers or from within third-party	609	way to do this for generic recurring timers or from within third-party
603	libraries. Just remember to I<unref after start> and I<ref before stop>.	610	libraries. Just remember to I<unref after start> and I<ref before stop>
		611	(but only if the watcher wasn't active before, or was active before,
		612	respectively).
604		613
605	Example: Create a signal watcher, but keep it from keeping C<ev_loop>	614	Example: Create a signal watcher, but keep it from keeping C<ev_loop>
606	running when nothing else is active.	615	running when nothing else is active.
607		616
608	struct ev_signal exitsig;	617	struct ev_signal exitsig;
…		…
2491	be used is the winsock select). This means that it will call	2500	be used is the winsock select). This means that it will call
2492	C<_get_osfhandle> on the fd to convert it to an OS handle. Otherwise,	2501	C<_get_osfhandle> on the fd to convert it to an OS handle. Otherwise,
2493	it is assumed that all these functions actually work on fds, even	2502	it is assumed that all these functions actually work on fds, even
2494	on win32. Should not be defined on non-win32 platforms.	2503	on win32. Should not be defined on non-win32 platforms.
2495		2504
		2505	=item EV_FD_TO_WIN32_HANDLE
		2506
		2507	If C<EV_SELECT_IS_WINSOCKET> is enabled, then libev needs a way to map
		2508	file descriptors to socket handles. When not defining this symbol (the
		2509	default), then libev will call C<_get_osfhandle>, which is usually
		2510	correct. In some cases, programs use their own file descriptor management,
		2511	in which case they can provide this function to map fds to socket handles.
		2512
2496	=item EV_USE_POLL	2513	=item EV_USE_POLL
2497		2514
2498	If defined to be C<1>, libev will compile in support for the C<poll>(2)	2515	If defined to be C<1>, libev will compile in support for the C<poll>(2)
2499	backend. Otherwise it will be enabled on non-win32 platforms. It	2516	backend. Otherwise it will be enabled on non-win32 platforms. It
2500	takes precedence over select.	2517	takes precedence over select.
…		…
2772	watchers becomes O(1) w.r.t. prioritiy handling.	2789	watchers becomes O(1) w.r.t. prioritiy handling.
2773		2790
2774	=back	2791	=back
2775		2792
2776		2793
		2794	=head1 Win32 platform limitations and workarounds
		2795
		2796	Win32 doesn't support any of the standards (e.g. POSIX) that libev
		2797	requires, and its I/O model is fundamentally incompatible with the POSIX
		2798	model. Libev still offers limited functionality on this platform in
		2799	the form of the C<EVBACKEND_SELECT> backend, and only supports socket
		2800	descriptors. This only applies when using Win32 natively, not when using
		2801	e.g. cygwin.
		2802
		2803	There is no supported compilation method available on windows except
		2804	embedding it into other applications.
		2805
		2806	Due to the many, low, and arbitrary limits on the win32 platform and the
		2807	abysmal performance of winsockets, using a large number of sockets is not
		2808	recommended (and not reasonable). If your program needs to use more than
		2809	a hundred or so sockets, then likely it needs to use a totally different
		2810	implementation for windows, as libev offers the POSIX model, which cannot
		2811	be implemented efficiently on windows (microsoft monopoly games).
		2812
		2813	=over 4
		2814
		2815	=item The winsocket select function
		2816
		2817	The winsocket C<select> function doesn't follow POSIX in that it requires
		2818	socket I<handles> and not socket I<file descriptors>. This makes select
		2819	very inefficient, and also requires a mapping from file descriptors
		2820	to socket handles. See the discussion of the C<EV_SELECT_USE_FD_SET>,
		2821	C<EV_SELECT_IS_WINSOCKET> and C<EV_FD_TO_WIN32_HANDLE> preprocessor
		2822	symbols for more info.
		2823
		2824	The configuration for a "naked" win32 using the microsoft runtime
		2825	libraries and raw winsocket select is:
		2826
		2827	#define EV_USE_SELECT 1
		2828	#define EV_SELECT_IS_WINSOCKET 1 /* forces EV_SELECT_USE_FD_SET, too */
		2829
		2830	Note that winsockets handling of fd sets is O(n), so you can easily get a
		2831	complexity in the O(n²) range when using win32.
		2832
		2833	=item Limited number of file descriptors
		2834
		2835	Windows has numerous arbitrary (and low) limits on things. Early versions
		2836	of winsocket's select only supported waiting for a max. of C<64> handles
		2837	(probably owning to the fact that all windows kernels can only wait for
		2838	C<64> things at the same time internally; microsoft recommends spawning a
		2839	chain of threads and wait for 63 handles and the previous thread in each).
		2840
		2841	Newer versions support more handles, but you need to define C<FD_SETSIZE>
		2842	to some high number (e.g. C<2048>) before compiling the winsocket select
		2843	call (which might be in libev or elsewhere, for example, perl does its own
		2844	select emulation on windows).
		2845
		2846	Another limit is the number of file descriptors in the microsoft runtime
		2847	libraries, which by default is C<64> (there must be a hidden I<64> fetish
		2848	or something like this inside microsoft). You can increase this by calling
		2849	C<_setmaxstdio>, which can increase this limit to C<2048> (another
		2850	arbitrary limit), but is broken in many versions of the microsoft runtime
		2851	libraries.
		2852
		2853	This might get you to about C<512> or C<2048> sockets (depending on
		2854	windows version and/or the phase of the moon). To get more, you need to
		2855	wrap all I/O functions and provide your own fd management, but the cost of
		2856	calling select (O(n²)) will likely make this unworkable.
		2857
		2858	=back
		2859
		2860
2777	=head1 AUTHOR	2861	=head1 AUTHOR
2778		2862
2779	Marc Lehmann <libev@schmorp.de>.	2863	Marc Lehmann <libev@schmorp.de>.
2780		2864

Diff Legend

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

Comparing libev/ev.pod (file contents): Revision 1.111 by root, Tue Dec 25 18:01:20 2007 UTC vs. Revision 1.116 by root, Mon Dec 31 01:34:09 2007 UTC

Diff Legend

Comparing libev/ev.pod (file contents):
Revision 1.111 by root, Tue Dec 25 18:01:20 2007 UTC vs.
Revision 1.116 by root, Mon Dec 31 01:34:09 2007 UTC