[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.115 by root, Mon Dec 31 01:32:59 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
…		…
2491	be used is the winsock select). This means that it will call	2498	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,	2499	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	2500	it is assumed that all these functions actually work on fds, even
2494	on win32. Should not be defined on non-win32 platforms.	2501	on win32. Should not be defined on non-win32 platforms.
2495		2502
		2503	=item EV_FD_TO_WIN32_HANDLE
		2504
		2505	If C<EV_SELECT_IS_WINSOCKET> is enabled, then libev needs a way to map
		2506	file descriptors to socket handles. When not defining this symbol (the
		2507	default), then libev will call C<_get_osfhandle>, which is usually
		2508	correct. In some cases, programs use their own file descriptor management,
		2509	in which case they can provide this function to map fds to socket handles.
		2510
2496	=item EV_USE_POLL	2511	=item EV_USE_POLL
2497		2512
2498	If defined to be C<1>, libev will compile in support for the C<poll>(2)	2513	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	2514	backend. Otherwise it will be enabled on non-win32 platforms. It
2500	takes precedence over select.	2515	takes precedence over select.
…		…
2772	watchers becomes O(1) w.r.t. prioritiy handling.	2787	watchers becomes O(1) w.r.t. prioritiy handling.
2773		2788
2774	=back	2789	=back
2775		2790
2776		2791
		2792	=head1 Win32 platform limitations and workarounds
		2793
		2794	Win32 doesn't support any of the standards (e.g. POSIX) that libev
		2795	requires, and its I/O model is fundamentally incompatible with the POSIX
		2796	model. Libev still offers limited functionality on this platform in
		2797	the form of the C<EVBACKEND_SELECT> backend, and only supports socket
		2798	descriptors. This only applies when using Win32 natively, not when using
		2799	e.g. cygwin.
		2800
		2801	There is no supported compilation method available on windows except
		2802	embedding it into other applications.
		2803
		2804	Due to the many, low, and arbitrary limits on the win32 platform and the
		2805	abysmal performance of winsockets, using a large number of sockets is not
		2806	recommended (and not reasonable). If your program needs to use more than
		2807	a hundred or so sockets, then likely it needs to use a totally different
		2808	implementation for windows, as libev offers the POSIX model, which cannot
		2809	be implemented efficiently on windows (microsoft monopoly games).
		2810
		2811	=over 4
		2812
		2813	=item The winsocket select function
		2814
		2815	The winsocket C<select> function doesn't follow POSIX in that it requires
		2816	socket I<handles> and not socket I<file descriptors>. This makes select
		2817	very inefficient, and also requires a mapping from file descriptors
		2818	to socket handles. See the discussion of the C<EV_SELECT_USE_FD_SET>,
		2819	C<EV_SELECT_IS_WINSOCKET> and C<EV_FD_TO_WIN32_HANDLE> preprocessor
		2820	symbols for more info.
		2821
		2822	The configuration for a "naked" win32 using the microsoft runtime
		2823	libraries and raw winsocket select is:
		2824
		2825	#define EV_USE_SELECT 1
		2826	#define EV_SELECT_IS_WINSOCKET 1 /* forces EV_SELECT_USE_FD_SET, too */
		2827
		2828	Note that winsockets handling of fd sets is O(n), so you can easily get a
		2829	complexity in the O(n²) range when using win32.
		2830
		2831	=item Limited number of file descriptors
		2832
		2833	Windows has numerous arbitrary (and low) limits on things. Early versions
		2834	of winsocket's select only supported waiting for a max. of C<64> handles
		2835	(probably owning to the fact that all windows kernels can only wait for
		2836	C<64> things at the same time internally; microsoft recommends spawning a
		2837	chain of threads and wait for 63 handles and the previous thread in each).
		2838
		2839	Newer versions support more handles, but you need to define C<FD_SETSIZE>
		2840	to some high number (e.g. C<2048>) before compiling the winsocket select
		2841	call (which might be in libev or elsewhere, for example, perl does its own
		2842	select emulation on windows).
		2843
		2844	Another limit is the number of file descriptors in the microsoft runtime
		2845	libraries, which by default is C<64> (there must be a hidden I<64> fetish
		2846	or something like this inside microsoft). You can increase this by calling
		2847	C<_setmaxstdio>, which can increase this limit to C<2048> (another
		2848	arbitrary limit), but is broken in many versions of the microsoft runtime
		2849	libraries.
		2850
		2851	This might get you to about C<512> or C<2048> sockets (depending on
		2852	windows version and/or the phase of the moon). To get more, you need to
		2853	wrap all I/O functions and provide your own fd management, but the cost of
		2854	calling select (O(n²)) will likely make this unworkable.
		2855
		2856	=back
		2857
		2858
2777	=head1 AUTHOR	2859	=head1 AUTHOR
2778		2860
2779	Marc Lehmann <libev@schmorp.de>.	2861	Marc Lehmann <libev@schmorp.de>.
2780		2862

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.115 by root, Mon Dec 31 01:32:59 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.115 by root, Mon Dec 31 01:32:59 2007 UTC