[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.126 by root, Fri Feb 1 13:46:26 2008 UTC

…		…
260	flags. If that is troubling you, check C<ev_backend ()> afterwards).	260	flags. If that is troubling you, check C<ev_backend ()> afterwards).
261		261
262	If you don't know what event loop to use, use the one returned from this	262	If you don't know what event loop to use, use the one returned from this
263	function.	263	function.
264		264
		265	The default loop is the only loop that can handle C<ev_signal> and
		266	C<ev_child> watchers, and to do this, it always registers a handler
		267	for C<SIGCHLD>. If this is a problem for your app you can either
		268	create a dynamic loop with C<ev_loop_new> that doesn't do that, or you
		269	can simply overwrite the C<SIGCHLD> signal handler I<after> calling
		270	C<ev_default_init>.
		271
265	The flags argument can be used to specify special behaviour or specific	272	The flags argument can be used to specify special behaviour or specific
266	backends to use, and is usually specified as C<0> (or C<EVFLAG_AUTO>).	273	backends to use, and is usually specified as C<0> (or C<EVFLAG_AUTO>).
267		274
268	The following flags are supported:	275	The following flags are supported:
269		276
…		…
403	While this backend scales well, it requires one system call per active	410	While this backend scales well, it requires one system call per active
404	file descriptor per loop iteration. For small and medium numbers of file	411	file descriptor per loop iteration. For small and medium numbers of file
405	descriptors a "slow" C<EVBACKEND_SELECT> or C<EVBACKEND_POLL> backend	412	descriptors a "slow" C<EVBACKEND_SELECT> or C<EVBACKEND_POLL> backend
406	might perform better.	413	might perform better.
407		414
		415	On the positive side, ignoring the spurious readyness notifications, this
		416	backend actually performed to specification in all tests and is fully
		417	embeddable, which is a rare feat among the OS-specific backends.
		418
408	=item C<EVBACKEND_ALL>	419	=item C<EVBACKEND_ALL>
409		420
410	Try all backends (even potentially broken ones that wouldn't be tried	421	Try all backends (even potentially broken ones that wouldn't be tried
411	with C<EVFLAG_AUTO>). Since this is a mask, you can do stuff such as	422	with C<EVFLAG_AUTO>). Since this is a mask, you can do stuff such as
412	C<EVBACKEND_ALL & ~EVBACKEND_KQUEUE>.	423	C<EVBACKEND_ALL & ~EVBACKEND_KQUEUE>.
…		…
414	It is definitely not recommended to use this flag.	425	It is definitely not recommended to use this flag.
415		426
416	=back	427	=back
417		428
418	If one or more of these are ored into the flags value, then only these	429	If one or more of these are ored into the flags value, then only these
419	backends will be tried (in the reverse order as given here). If none are	430	backends will be tried (in the reverse order as listed here). If none are
420	specified, most compiled-in backend will be tried, usually in reverse	431	specified, all backends in C<ev_recommended_backends ()> will be tried.
421	order of their flag values :)
422		432
423	The most typical usage is like this:	433	The most typical usage is like this:
424		434
425	if (!ev_default_loop (0))	435	if (!ev_default_loop (0))
426	fatal ("could not initialise libev, bad $LIBEV_FLAGS in environment?");	436	fatal ("could not initialise libev, bad $LIBEV_FLAGS in environment?");
…		…
473	Like C<ev_default_destroy>, but destroys an event loop created by an	483	Like C<ev_default_destroy>, but destroys an event loop created by an
474	earlier call to C<ev_loop_new>.	484	earlier call to C<ev_loop_new>.
475		485
476	=item ev_default_fork ()	486	=item ev_default_fork ()
477		487
		488	This function sets a flag that causes subsequent C<ev_loop> iterations
478	This function reinitialises the kernel state for backends that have	489	to reinitialise the kernel state for backends that have one. Despite the
479	one. Despite the name, you can call it anytime, but it makes most sense	490	name, you can call it anytime, but it makes most sense after forking, in
480	after forking, in either the parent or child process (or both, but that	491	the child process (or both child and parent, but that again makes little
481	again makes little sense).	492	sense). You I<must> call it in the child before using any of the libev
		493	functions, and it will only take effect at the next C<ev_loop> iteration.
482		494
483	You I<must> call this function in the child process after forking if and	495	On the other hand, you only need to call this function in the child
484	only if you want to use the event library in both processes. If you just	496	process if and only if you want to use the event library in the child. If
485	fork+exec, you don't have to call it.	497	you just fork+exec, you don't have to call it at all.
486		498
487	The function itself is quite fast and it's usually not a problem to call	499	The function itself is quite fast and it's usually not a problem to call
488	it just in case after a fork. To make this easy, the function will fit in	500	it just in case after a fork. To make this easy, the function will fit in
489	quite nicely into a call to C<pthread_atfork>:	501	quite nicely into a call to C<pthread_atfork>:
490		502
491	pthread_atfork (0, 0, ev_default_fork);	503	pthread_atfork (0, 0, ev_default_fork);
492
493	At the moment, C<EVBACKEND_SELECT> and C<EVBACKEND_POLL> are safe to use
494	without calling this function, so if you force one of those backends you
495	do not need to care.
496		504
497	=item ev_loop_fork (loop)	505	=item ev_loop_fork (loop)
498		506
499	Like C<ev_default_fork>, but acts on an event loop created by	507	Like C<ev_default_fork>, but acts on an event loop created by
500	C<ev_loop_new>. Yes, you have to call this on every allocated event loop	508	C<ev_loop_new>. Yes, you have to call this on every allocated event loop
…		…
551	usually a better approach for this kind of thing.	559	usually a better approach for this kind of thing.
552		560
553	Here are the gory details of what C<ev_loop> does:	561	Here are the gory details of what C<ev_loop> does:
554		562
555	- Before the first iteration, call any pending watchers.	563	- Before the first iteration, call any pending watchers.
556	* If there are no active watchers (reference count is zero), return.	564	* If EVFLAG_FORKCHECK was used, check for a fork.
557	- Queue all prepare watchers and then call all outstanding watchers.	565	- If a fork was detected, queue and call all fork watchers.
		566	- Queue and call all prepare watchers.
558	- If we have been forked, recreate the kernel state.	567	- If we have been forked, recreate the kernel state.
559	- Update the kernel state with all outstanding changes.	568	- Update the kernel state with all outstanding changes.
560	- Update the "event loop time".	569	- Update the "event loop time".
561	- Calculate for how long to block.	570	- Calculate for how long to sleep or block, if at all
		571	(active idle watchers, EVLOOP_NONBLOCK or not having
		572	any active watchers at all will result in not sleeping).
		573	- Sleep if the I/O and timer collect interval say so.
562	- Block the process, waiting for any events.	574	- Block the process, waiting for any events.
563	- Queue all outstanding I/O (fd) events.	575	- Queue all outstanding I/O (fd) events.
564	- Update the "event loop time" and do time jump handling.	576	- Update the "event loop time" and do time jump handling.
565	- Queue all outstanding timers.	577	- Queue all outstanding timers.
566	- Queue all outstanding periodics.	578	- Queue all outstanding periodics.
567	- If no events are pending now, queue all idle watchers.	579	- If no events are pending now, queue all idle watchers.
568	- Queue all check watchers.	580	- Queue all check watchers.
569	- Call all queued watchers in reverse order (i.e. check watchers first).	581	- 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	582	Signals and child watchers are implemented as I/O watchers, and will
571	be handled here by queueing them when their watcher gets executed.	583	be handled here by queueing them when their watcher gets executed.
572	- If ev_unloop has been called or EVLOOP_ONESHOT or EVLOOP_NONBLOCK	584	- If ev_unloop has been called, or EVLOOP_ONESHOT or EVLOOP_NONBLOCK
573	were used, return, otherwise continue with step *.	585	were used, or there are no active watchers, return, otherwise
		586	continue with step *.
574		587
575	Example: Queue some jobs and then loop until no events are outsanding	588	Example: Queue some jobs and then loop until no events are outstanding
576	anymore.	589	anymore.
577		590
578	... queue jobs here, make sure they register event watchers as long	591	... 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..)	592	... as they still have work to do (even an idle watcher will do..)
580	ev_loop (my_loop, 0);	593	ev_loop (my_loop, 0);
…		…
584		597
585	Can be used to make a call to C<ev_loop> return early (but only after it	598	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	599	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	600	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.	601	C<EVUNLOOP_ALL>, which will make all nested C<ev_loop> calls return.
		602
		603	This "unloop state" will be cleared when entering C<ev_loop> again.
589		604
590	=item ev_ref (loop)	605	=item ev_ref (loop)
591		606
592	=item ev_unref (loop)	607	=item ev_unref (loop)
593		608
…		…
598	returning, ev_unref() after starting, and ev_ref() before stopping it. For	613	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	614	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	615	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	616	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	617	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>.	618	libraries. Just remember to I<unref after start> and I<ref before stop>
		619	(but only if the watcher wasn't active before, or was active before,
		620	respectively).
604		621
605	Example: Create a signal watcher, but keep it from keeping C<ev_loop>	622	Example: Create a signal watcher, but keep it from keeping C<ev_loop>
606	running when nothing else is active.	623	running when nothing else is active.
607		624
608	struct ev_signal exitsig;	625	struct ev_signal exitsig;
…		…
756		773
757	=item C<EV_FORK>	774	=item C<EV_FORK>
758		775
759	The event loop has been resumed in the child process after fork (see	776	The event loop has been resumed in the child process after fork (see
760	C<ev_fork>).	777	C<ev_fork>).
		778
		779	=item C<EV_ASYNC>
		780
		781	The given async watcher has been asynchronously notified (see C<ev_async>).
761		782
762	=item C<EV_ERROR>	783	=item C<EV_ERROR>
763		784
764	An unspecified error has occured, the watcher has been stopped. This might	785	An unspecified error has occured, the watcher has been stopped. This might
765	happen because the watcher could not be properly started because libev	786	happen because the watcher could not be properly started because libev
…		…
1421		1442
1422	=head3 Watcher-Specific Functions and Data Members	1443	=head3 Watcher-Specific Functions and Data Members
1423		1444
1424	=over 4	1445	=over 4
1425		1446
1426	=item ev_child_init (ev_child *, callback, int pid)	1447	=item ev_child_init (ev_child *, callback, int pid, int trace)
1427		1448
1428	=item ev_child_set (ev_child *, int pid)	1449	=item ev_child_set (ev_child *, int pid, int trace)
1429		1450
1430	Configures the watcher to wait for status changes of process C<pid> (or	1451	Configures the watcher to wait for status changes of process C<pid> (or
1431	I<any> process if C<pid> is specified as C<0>). The callback can look	1452	I<any> process if C<pid> is specified as C<0>). The callback can look
1432	at the C<rstatus> member of the C<ev_child> watcher structure to see	1453	at the C<rstatus> member of the C<ev_child> watcher structure to see
1433	the status word (use the macros from C<sys/wait.h> and see your systems	1454	the status word (use the macros from C<sys/wait.h> and see your systems
1434	C<waitpid> documentation). The C<rpid> member contains the pid of the	1455	C<waitpid> documentation). The C<rpid> member contains the pid of the
1435	process causing the status change.	1456	process causing the status change. C<trace> must be either C<0> (only
		1457	activate the watcher when the process terminates) or C<1> (additionally
		1458	activate the watcher when the process is stopped or continued).
1436		1459
1437	=item int pid [read-only]	1460	=item int pid [read-only]
1438		1461
1439	The process id this watcher watches out for, or C<0>, meaning any process id.	1462	The process id this watcher watches out for, or C<0>, meaning any process id.
1440		1463
…		…
1676	static void	1699	static void
1677	idle_cb (struct ev_loop loop, struct ev_idle w, int revents)	1700	idle_cb (struct ev_loop loop, struct ev_idle w, int revents)
1678	{	1701	{
1679	free (w);	1702	free (w);
1680	// now do something you wanted to do when the program has	1703	// now do something you wanted to do when the program has
1681	// no longer asnything immediate to do.	1704	// no longer anything immediate to do.
1682	}	1705	}
1683		1706
1684	struct ev_idle *idle_watcher = malloc (sizeof (struct ev_idle));	1707	struct ev_idle *idle_watcher = malloc (sizeof (struct ev_idle));
1685	ev_idle_init (idle_watcher, idle_cb);	1708	ev_idle_init (idle_watcher, idle_cb);
1686	ev_idle_start (loop, idle_cb);	1709	ev_idle_start (loop, idle_cb);
…		…
2027	believe me.	2050	believe me.
2028		2051
2029	=back	2052	=back
2030		2053
2031		2054
		2055	=head2 C<ev_async> - how to wake up another event loop
		2056
		2057	In general, you cannot use an C<ev_loop> from multiple threads or other
		2058	asynchronous sources such as signal handlers (as opposed to multiple event
		2059	loops - those are of course safe to use in different threads).
		2060
		2061	Sometimes, however, you need to wake up another event loop you do not
		2062	control, for example because it belongs to another thread. This is what
		2063	C<ev_async> watchers do: as long as the C<ev_async> watcher is active, you
		2064	can signal it by calling C<ev_async_send>, which is thread- and signal
		2065	safe.
		2066
		2067	This functionality is very similar to C<ev_signal> watchers, as signals,
		2068	too, are asynchronous in nature, and signals, too, will be compressed
		2069	(i.e. the number of callback invocations may be less than the number of
		2070	C<ev_async_sent> calls).
		2071
		2072	Unlike C<ev_signal> watchers, C<ev_async> works with any event loop, not
		2073	just the default loop.
		2074
		2075	=head3 Queueing
		2076
		2077	C<ev_async> does not support queueing of data in any way. The reason
		2078	is that the author does not know of a simple (or any) algorithm for a
		2079	multiple-writer-single-reader queue that works in all cases and doesn't
		2080	need elaborate support such as pthreads.
		2081
		2082	That means that if you want to queue data, you have to provide your own
		2083	queue. And here is how you would implement locking:
		2084
		2085	=over 4
		2086
		2087	=item queueing from a signal handler context
		2088
		2089	To implement race-free queueing, you simply add to the queue in the signal
		2090	handler but you block the signal handler in the watcher callback. Here is an example that does that for
		2091	some fictitiuous SIGUSR1 handler:
		2092
		2093	static ev_async mysig;
		2094
		2095	static void
		2096	sigusr1_handler (void)
		2097	{
		2098	sometype data;
		2099
		2100	// no locking etc.
		2101	queue_put (data);
		2102	ev_async_send (DEFAULT_ &mysig);
		2103	}
		2104
		2105	static void
		2106	mysig_cb (EV_P_ ev_async *w, int revents)
		2107	{
		2108	sometype data;
		2109	sigset_t block, prev;
		2110
		2111	sigemptyset (&block);
		2112	sigaddset (&block, SIGUSR1);
		2113	sigprocmask (SIG_BLOCK, &block, &prev);
		2114
		2115	while (queue_get (&data))
		2116	process (data);
		2117
		2118	if (sigismember (&prev, SIGUSR1)
		2119	sigprocmask (SIG_UNBLOCK, &block, 0);
		2120	}
		2121
		2122	(Note: pthreads in theory requires you to use C<pthread_setmask>
		2123	instead of C<sigprocmask> when you use threads, but libev doesn't do it
		2124	either...).
		2125
		2126	=item queueing from a thread context
		2127
		2128	The strategy for threads is different, as you cannot (easily) block
		2129	threads but you can easily preempt them, so to queue safely you need to
		2130	emply a traditional mutex lock, such as in this pthread example:
		2131
		2132	static ev_async mysig;
		2133	static pthread_mutex_t mymutex = PTHREAD_MUTEX_INITIALIZER;
		2134
		2135	static void
		2136	otherthread (void)
		2137	{
		2138	// only need to lock the actual queueing operation
		2139	pthread_mutex_lock (&mymutex);
		2140	queue_put (data);
		2141	pthread_mutex_unlock (&mymutex);
		2142
		2143	ev_async_send (DEFAULT_ &mysig);
		2144	}
		2145
		2146	static void
		2147	mysig_cb (EV_P_ ev_async *w, int revents)
		2148	{
		2149	pthread_mutex_lock (&mymutex);
		2150
		2151	while (queue_get (&data))
		2152	process (data);
		2153
		2154	pthread_mutex_unlock (&mymutex);
		2155	}
		2156
		2157	=back
		2158
		2159
		2160	=head3 Watcher-Specific Functions and Data Members
		2161
		2162	=over 4
		2163
		2164	=item ev_async_init (ev_async *, callback)
		2165
		2166	Initialises and configures the async watcher - it has no parameters of any
		2167	kind. There is a C<ev_asynd_set> macro, but using it is utterly pointless,
		2168	believe me.
		2169
		2170	=item ev_async_send (loop, ev_async *)
		2171
		2172	Sends/signals/activates the given C<ev_async> watcher, that is, feeds
		2173	an C<EV_ASYNC> event on the watcher into the event loop. Unlike
		2174	C<ev_feed_event>, this call is safe to do in other threads, signal or
		2175	similar contexts (see the dicusssion of C<EV_ATOMIC_T> in the embedding
		2176	section below on what exactly this means).
		2177
		2178	This call incurs the overhead of a syscall only once per loop iteration,
		2179	so while the overhead might be noticable, it doesn't apply to repeated
		2180	calls to C<ev_async_send>.
		2181
		2182	=back
		2183
		2184
2032	=head1 OTHER FUNCTIONS	2185	=head1 OTHER FUNCTIONS
2033		2186
2034	There are some other functions of possible interest. Described. Here. Now.	2187	There are some other functions of possible interest. Described. Here. Now.
2035		2188
2036	=over 4	2189	=over 4
…		…
2263	Example: Define a class with an IO and idle watcher, start one of them in	2416	Example: Define a class with an IO and idle watcher, start one of them in
2264	the constructor.	2417	the constructor.
2265		2418
2266	class myclass	2419	class myclass
2267	{	2420	{
2268	ev_io io; void io_cb (ev::io &w, int revents);	2421	ev::io io; void io_cb (ev::io &w, int revents);
2269	ev_idle idle void idle_cb (ev::idle &w, int revents);	2422	ev:idle idle void idle_cb (ev::idle &w, int revents);
2270		2423
2271	myclass ();	2424	myclass (int fd)
2272	}
2273
2274	myclass::myclass (int fd)
2275	{	2425	{
2276	io .set <myclass, &myclass::io_cb > (this);	2426	io .set <myclass, &myclass::io_cb > (this);
2277	idle.set <myclass, &myclass::idle_cb> (this);	2427	idle.set <myclass, &myclass::idle_cb> (this);
2278		2428
2279	io.start (fd, ev::READ);	2429	io.start (fd, ev::READ);
		2430	}
2280	}	2431	};
2281		2432
2282		2433
2283	=head1 MACRO MAGIC	2434	=head1 MACRO MAGIC
2284		2435
2285	Libev can be compiled with a variety of options, the most fundamantal	2436	Libev can be compiled with a variety of options, the most fundamantal
…		…
2490	wants osf handles on win32 (this is the case when the select to	2641	wants osf handles on win32 (this is the case when the select to
2491	be used is the winsock select). This means that it will call	2642	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,	2643	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	2644	it is assumed that all these functions actually work on fds, even
2494	on win32. Should not be defined on non-win32 platforms.	2645	on win32. Should not be defined on non-win32 platforms.
		2646
		2647	=item EV_FD_TO_WIN32_HANDLE
		2648
		2649	If C<EV_SELECT_IS_WINSOCKET> is enabled, then libev needs a way to map
		2650	file descriptors to socket handles. When not defining this symbol (the
		2651	default), then libev will call C<_get_osfhandle>, which is usually
		2652	correct. In some cases, programs use their own file descriptor management,
		2653	in which case they can provide this function to map fds to socket handles.
2495		2654
2496	=item EV_USE_POLL	2655	=item EV_USE_POLL
2497		2656
2498	If defined to be C<1>, libev will compile in support for the C<poll>(2)	2657	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	2658	backend. Otherwise it will be enabled on non-win32 platforms. It
…		…
2533		2692
2534	If defined to be C<1>, libev will compile in support for the Linux inotify	2693	If defined to be C<1>, libev will compile in support for the Linux inotify
2535	interface to speed up C<ev_stat> watchers. Its actual availability will	2694	interface to speed up C<ev_stat> watchers. Its actual availability will
2536	be detected at runtime.	2695	be detected at runtime.
2537		2696
		2697	=item EV_ATOMIC_T
		2698
		2699	Libev requires an integer type (suitable for storing C<0> or C<1>) whose
		2700	access is atomic with respect to other threads or signal contexts. No such
		2701	type is easily found in the C language, so you can provide your own type
		2702	that you know is safe for your purposes.
		2703
		2704	In the absense of this define, libev will use C<sig_atomic_t volatile>
		2705	(from F<signal.h>), which is usually good enough on most platforms.
		2706
2538	=item EV_H	2707	=item EV_H
2539		2708
2540	The name of the F<ev.h> header file used to include it. The default if	2709	The name of the F<ev.h> header file used to include it. The default if
2541	undefined is C<"ev.h"> in F<event.h> and F<ev.c>. This can be used to	2710	undefined is C<"ev.h"> in F<event.h>, F<ev.c> and F<ev++.h>. This can be
2542	virtually rename the F<ev.h> header file in case of conflicts.	2711	used to virtually rename the F<ev.h> header file in case of conflicts.
2543		2712
2544	=item EV_CONFIG_H	2713	=item EV_CONFIG_H
2545		2714
2546	If C<EV_STANDALONE> isn't C<1>, this variable can be used to override	2715	If C<EV_STANDALONE> isn't C<1>, this variable can be used to override
2547	F<ev.c>'s idea of where to find the F<config.h> file, similarly to	2716	F<ev.c>'s idea of where to find the F<config.h> file, similarly to
2548	C<EV_H>, above.	2717	C<EV_H>, above.
2549		2718
2550	=item EV_EVENT_H	2719	=item EV_EVENT_H
2551		2720
2552	Similarly to C<EV_H>, this macro can be used to override F<event.c>'s idea	2721	Similarly to C<EV_H>, this macro can be used to override F<event.c>'s idea
2553	of how the F<event.h> header can be found, the dfeault is C<"event.h">.	2722	of how the F<event.h> header can be found, the default is C<"event.h">.
2554		2723
2555	=item EV_PROTOTYPES	2724	=item EV_PROTOTYPES
2556		2725
2557	If defined to be C<0>, then F<ev.h> will not define any function	2726	If defined to be C<0>, then F<ev.h> will not define any function
2558	prototypes, but still define all the structs and other symbols. This is	2727	prototypes, but still define all the structs and other symbols. This is
…		…
2607	defined to be C<0>, then they are not.	2776	defined to be C<0>, then they are not.
2608		2777
2609	=item EV_FORK_ENABLE	2778	=item EV_FORK_ENABLE
2610		2779
2611	If undefined or defined to be C<1>, then fork watchers are supported. If	2780	If undefined or defined to be C<1>, then fork watchers are supported. If
		2781	defined to be C<0>, then they are not.
		2782
		2783	=item EV_ASYNC_ENABLE
		2784
		2785	If undefined or defined to be C<1>, then async watchers are supported. If
2612	defined to be C<0>, then they are not.	2786	defined to be C<0>, then they are not.
2613		2787
2614	=item EV_MINIMAL	2788	=item EV_MINIMAL
2615		2789
2616	If you need to shave off some kilobytes of code at the expense of some	2790	If you need to shave off some kilobytes of code at the expense of some
…		…
2772	watchers becomes O(1) w.r.t. prioritiy handling.	2946	watchers becomes O(1) w.r.t. prioritiy handling.
2773		2947
2774	=back	2948	=back
2775		2949
2776		2950
		2951	=head1 Win32 platform limitations and workarounds
		2952
		2953	Win32 doesn't support any of the standards (e.g. POSIX) that libev
		2954	requires, and its I/O model is fundamentally incompatible with the POSIX
		2955	model. Libev still offers limited functionality on this platform in
		2956	the form of the C<EVBACKEND_SELECT> backend, and only supports socket
		2957	descriptors. This only applies when using Win32 natively, not when using
		2958	e.g. cygwin.
		2959
		2960	There is no supported compilation method available on windows except
		2961	embedding it into other applications.
		2962
		2963	Due to the many, low, and arbitrary limits on the win32 platform and the
		2964	abysmal performance of winsockets, using a large number of sockets is not
		2965	recommended (and not reasonable). If your program needs to use more than
		2966	a hundred or so sockets, then likely it needs to use a totally different
		2967	implementation for windows, as libev offers the POSIX model, which cannot
		2968	be implemented efficiently on windows (microsoft monopoly games).
		2969
		2970	=over 4
		2971
		2972	=item The winsocket select function
		2973
		2974	The winsocket C<select> function doesn't follow POSIX in that it requires
		2975	socket I<handles> and not socket I<file descriptors>. This makes select
		2976	very inefficient, and also requires a mapping from file descriptors
		2977	to socket handles. See the discussion of the C<EV_SELECT_USE_FD_SET>,
		2978	C<EV_SELECT_IS_WINSOCKET> and C<EV_FD_TO_WIN32_HANDLE> preprocessor
		2979	symbols for more info.
		2980
		2981	The configuration for a "naked" win32 using the microsoft runtime
		2982	libraries and raw winsocket select is:
		2983
		2984	#define EV_USE_SELECT 1
		2985	#define EV_SELECT_IS_WINSOCKET 1 /* forces EV_SELECT_USE_FD_SET, too */
		2986
		2987	Note that winsockets handling of fd sets is O(n), so you can easily get a
		2988	complexity in the O(n²) range when using win32.
		2989
		2990	=item Limited number of file descriptors
		2991
		2992	Windows has numerous arbitrary (and low) limits on things. Early versions
		2993	of winsocket's select only supported waiting for a max. of C<64> handles
		2994	(probably owning to the fact that all windows kernels can only wait for
		2995	C<64> things at the same time internally; microsoft recommends spawning a
		2996	chain of threads and wait for 63 handles and the previous thread in each).
		2997
		2998	Newer versions support more handles, but you need to define C<FD_SETSIZE>
		2999	to some high number (e.g. C<2048>) before compiling the winsocket select
		3000	call (which might be in libev or elsewhere, for example, perl does its own
		3001	select emulation on windows).
		3002
		3003	Another limit is the number of file descriptors in the microsoft runtime
		3004	libraries, which by default is C<64> (there must be a hidden I<64> fetish
		3005	or something like this inside microsoft). You can increase this by calling
		3006	C<_setmaxstdio>, which can increase this limit to C<2048> (another
		3007	arbitrary limit), but is broken in many versions of the microsoft runtime
		3008	libraries.
		3009
		3010	This might get you to about C<512> or C<2048> sockets (depending on
		3011	windows version and/or the phase of the moon). To get more, you need to
		3012	wrap all I/O functions and provide your own fd management, but the cost of
		3013	calling select (O(n²)) will likely make this unworkable.
		3014
		3015	=back
		3016
		3017
2777	=head1 AUTHOR	3018	=head1 AUTHOR
2778		3019
2779	Marc Lehmann <libev@schmorp.de>.	3020	Marc Lehmann <libev@schmorp.de>.
2780		3021

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.126 by root, Fri Feb 1 13:46:26 2008 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.126 by root, Fri Feb 1 13:46:26 2008 UTC