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

Comparing libev/ev.pod (file contents):
Revision 1.118 by root, Thu Jan 10 06:00:55 2008 UTC vs.
Revision 1.130 by root, Wed Feb 6 18:34:24 2008 UTC

…		…
483	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
484	earlier call to C<ev_loop_new>.	484	earlier call to C<ev_loop_new>.
485		485
486	=item ev_default_fork ()	486	=item ev_default_fork ()
487		487
		488	This function sets a flag that causes subsequent C<ev_loop> iterations
488	This function reinitialises the kernel state for backends that have	489	to reinitialise the kernel state for backends that have one. Despite the
489	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
490	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
491	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.
492		494
493	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
494	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
495	fork+exec, you don't have to call it.	497	you just fork+exec, you don't have to call it at all.
496		498
497	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
498	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
499	quite nicely into a call to C<pthread_atfork>:	501	quite nicely into a call to C<pthread_atfork>:
500		502
501	pthread_atfork (0, 0, ev_default_fork);	503	pthread_atfork (0, 0, ev_default_fork);
502
503	At the moment, C<EVBACKEND_SELECT> and C<EVBACKEND_POLL> are safe to use
504	without calling this function, so if you force one of those backends you
505	do not need to care.
506		504
507	=item ev_loop_fork (loop)	505	=item ev_loop_fork (loop)
508		506
509	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
510	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
…		…
776	=item C<EV_FORK>	774	=item C<EV_FORK>
777		775
778	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
779	C<ev_fork>).	777	C<ev_fork>).
780		778
		779	=item C<EV_ASYNC>
		780
		781	The given async watcher has been asynchronously notified (see C<ev_async>).
		782
781	=item C<EV_ERROR>	783	=item C<EV_ERROR>
782		784
783	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
784	happen because the watcher could not be properly started because libev	786	happen because the watcher could not be properly started because libev
785	ran out of memory, a file descriptor was found to be closed or any other	787	ran out of memory, a file descriptor was found to be closed or any other
…		…
1440		1442
1441	=head3 Watcher-Specific Functions and Data Members	1443	=head3 Watcher-Specific Functions and Data Members
1442		1444
1443	=over 4	1445	=over 4
1444		1446
1445	=item ev_child_init (ev_child *, callback, int pid)	1447	=item ev_child_init (ev_child *, callback, int pid, int trace)
1446		1448
1447	=item ev_child_set (ev_child *, int pid)	1449	=item ev_child_set (ev_child *, int pid, int trace)
1448		1450
1449	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
1450	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
1451	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
1452	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
1453	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
1454	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).
1455		1459
1456	=item int pid [read-only]	1460	=item int pid [read-only]
1457		1461
1458	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.
1459		1463
…		…
1695	static void	1699	static void
1696	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)
1697	{	1701	{
1698	free (w);	1702	free (w);
1699	// now do something you wanted to do when the program has	1703	// now do something you wanted to do when the program has
1700	// no longer asnything immediate to do.	1704	// no longer anything immediate to do.
1701	}	1705	}
1702		1706
1703	struct ev_idle *idle_watcher = malloc (sizeof (struct ev_idle));	1707	struct ev_idle *idle_watcher = malloc (sizeof (struct ev_idle));
1704	ev_idle_init (idle_watcher, idle_cb);	1708	ev_idle_init (idle_watcher, idle_cb);
1705	ev_idle_start (loop, idle_cb);	1709	ev_idle_start (loop, idle_cb);
…		…
2046	believe me.	2050	believe me.
2047		2051
2048	=back	2052	=back
2049		2053
2050		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. But at least I can tell you would implement locking around your
		2084	queue:
		2085
		2086	=over 4
		2087
		2088	=item queueing from a signal handler context
		2089
		2090	To implement race-free queueing, you simply add to the queue in the signal
		2091	handler but you block the signal handler in the watcher callback. Here is an example that does that for
		2092	some fictitiuous SIGUSR1 handler:
		2093
		2094	static ev_async mysig;
		2095
		2096	static void
		2097	sigusr1_handler (void)
		2098	{
		2099	sometype data;
		2100
		2101	// no locking etc.
		2102	queue_put (data);
		2103	ev_async_send (DEFAULT_ &mysig);
		2104	}
		2105
		2106	static void
		2107	mysig_cb (EV_P_ ev_async *w, int revents)
		2108	{
		2109	sometype data;
		2110	sigset_t block, prev;
		2111
		2112	sigemptyset (&block);
		2113	sigaddset (&block, SIGUSR1);
		2114	sigprocmask (SIG_BLOCK, &block, &prev);
		2115
		2116	while (queue_get (&data))
		2117	process (data);
		2118
		2119	if (sigismember (&prev, SIGUSR1)
		2120	sigprocmask (SIG_UNBLOCK, &block, 0);
		2121	}
		2122
		2123	(Note: pthreads in theory requires you to use C<pthread_setmask>
		2124	instead of C<sigprocmask> when you use threads, but libev doesn't do it
		2125	either...).
		2126
		2127	=item queueing from a thread context
		2128
		2129	The strategy for threads is different, as you cannot (easily) block
		2130	threads but you can easily preempt them, so to queue safely you need to
		2131	employ a traditional mutex lock, such as in this pthread example:
		2132
		2133	static ev_async mysig;
		2134	static pthread_mutex_t mymutex = PTHREAD_MUTEX_INITIALIZER;
		2135
		2136	static void
		2137	otherthread (void)
		2138	{
		2139	// only need to lock the actual queueing operation
		2140	pthread_mutex_lock (&mymutex);
		2141	queue_put (data);
		2142	pthread_mutex_unlock (&mymutex);
		2143
		2144	ev_async_send (DEFAULT_ &mysig);
		2145	}
		2146
		2147	static void
		2148	mysig_cb (EV_P_ ev_async *w, int revents)
		2149	{
		2150	pthread_mutex_lock (&mymutex);
		2151
		2152	while (queue_get (&data))
		2153	process (data);
		2154
		2155	pthread_mutex_unlock (&mymutex);
		2156	}
		2157
		2158	=back
		2159
		2160
		2161	=head3 Watcher-Specific Functions and Data Members
		2162
		2163	=over 4
		2164
		2165	=item ev_async_init (ev_async *, callback)
		2166
		2167	Initialises and configures the async watcher - it has no parameters of any
		2168	kind. There is a C<ev_asynd_set> macro, but using it is utterly pointless,
		2169	believe me.
		2170
		2171	=item ev_async_send (loop, ev_async *)
		2172
		2173	Sends/signals/activates the given C<ev_async> watcher, that is, feeds
		2174	an C<EV_ASYNC> event on the watcher into the event loop. Unlike
		2175	C<ev_feed_event>, this call is safe to do in other threads, signal or
		2176	similar contexts (see the dicusssion of C<EV_ATOMIC_T> in the embedding
		2177	section below on what exactly this means).
		2178
		2179	This call incurs the overhead of a syscall only once per loop iteration,
		2180	so while the overhead might be noticable, it doesn't apply to repeated
		2181	calls to C<ev_async_send>.
		2182
		2183	=back
		2184
		2185
2051	=head1 OTHER FUNCTIONS	2186	=head1 OTHER FUNCTIONS
2052		2187
2053	There are some other functions of possible interest. Described. Here. Now.	2188	There are some other functions of possible interest. Described. Here. Now.
2054		2189
2055	=over 4	2190	=over 4
…		…
2282	Example: Define a class with an IO and idle watcher, start one of them in	2417	Example: Define a class with an IO and idle watcher, start one of them in
2283	the constructor.	2418	the constructor.
2284		2419
2285	class myclass	2420	class myclass
2286	{	2421	{
2287	ev_io io; void io_cb (ev::io &w, int revents);	2422	ev::io io; void io_cb (ev::io &w, int revents);
2288	ev_idle idle void idle_cb (ev::idle &w, int revents);	2423	ev:idle idle void idle_cb (ev::idle &w, int revents);
2289		2424
2290	myclass ();	2425	myclass (int fd)
2291	}
2292
2293	myclass::myclass (int fd)
2294	{	2426	{
2295	io .set <myclass, &myclass::io_cb > (this);	2427	io .set <myclass, &myclass::io_cb > (this);
2296	idle.set <myclass, &myclass::idle_cb> (this);	2428	idle.set <myclass, &myclass::idle_cb> (this);
2297		2429
2298	io.start (fd, ev::READ);	2430	io.start (fd, ev::READ);
		2431	}
2299	}	2432	};
2300		2433
2301		2434
2302	=head1 MACRO MAGIC	2435	=head1 MACRO MAGIC
2303		2436
2304	Libev can be compiled with a variety of options, the most fundamantal	2437	Libev can be compiled with a variety of options, the most fundamantal
…		…
2560		2693
2561	If defined to be C<1>, libev will compile in support for the Linux inotify	2694	If defined to be C<1>, libev will compile in support for the Linux inotify
2562	interface to speed up C<ev_stat> watchers. Its actual availability will	2695	interface to speed up C<ev_stat> watchers. Its actual availability will
2563	be detected at runtime.	2696	be detected at runtime.
2564		2697
		2698	=item EV_ATOMIC_T
		2699
		2700	Libev requires an integer type (suitable for storing C<0> or C<1>) whose
		2701	access is atomic with respect to other threads or signal contexts. No such
		2702	type is easily found in the C language, so you can provide your own type
		2703	that you know is safe for your purposes. It is used both for signal handler "locking"
		2704	as well as for signal and thread safety in C<ev_async> watchers.
		2705
		2706	In the absense of this define, libev will use C<sig_atomic_t volatile>
		2707	(from F<signal.h>), which is usually good enough on most platforms.
		2708
2565	=item EV_H	2709	=item EV_H
2566		2710
2567	The name of the F<ev.h> header file used to include it. The default if	2711	The name of the F<ev.h> header file used to include it. The default if
2568	undefined is C<"ev.h"> in F<event.h>, F<ev.c> and F<ev++.h>. This can be	2712	undefined is C<"ev.h"> in F<event.h>, F<ev.c> and F<ev++.h>. This can be
2569	used to virtually rename the F<ev.h> header file in case of conflicts.	2713	used to virtually rename the F<ev.h> header file in case of conflicts.
…		…
2634	defined to be C<0>, then they are not.	2778	defined to be C<0>, then they are not.
2635		2779
2636	=item EV_FORK_ENABLE	2780	=item EV_FORK_ENABLE
2637		2781
2638	If undefined or defined to be C<1>, then fork watchers are supported. If	2782	If undefined or defined to be C<1>, then fork watchers are supported. If
		2783	defined to be C<0>, then they are not.
		2784
		2785	=item EV_ASYNC_ENABLE
		2786
		2787	If undefined or defined to be C<1>, then async watchers are supported. If
2639	defined to be C<0>, then they are not.	2788	defined to be C<0>, then they are not.
2640		2789
2641	=item EV_MINIMAL	2790	=item EV_MINIMAL
2642		2791
2643	If you need to shave off some kilobytes of code at the expense of some	2792	If you need to shave off some kilobytes of code at the expense of some
…		…
2764	=item Changing timer/periodic watchers (by autorepeat or calling again): O(log skipped_other_timers)	2913	=item Changing timer/periodic watchers (by autorepeat or calling again): O(log skipped_other_timers)
2765		2914
2766	That means that changing a timer costs less than removing/adding them	2915	That means that changing a timer costs less than removing/adding them
2767	as only the relative motion in the event queue has to be paid for.	2916	as only the relative motion in the event queue has to be paid for.
2768		2917
2769	=item Starting io/check/prepare/idle/signal/child watchers: O(1)	2918	=item Starting io/check/prepare/idle/signal/child/fork/async watchers: O(1)
2770		2919
2771	These just add the watcher into an array or at the head of a list.	2920	These just add the watcher into an array or at the head of a list.
2772		2921
2773	=item Stopping check/prepare/idle watchers: O(1)	2922	=item Stopping check/prepare/idle/fork/async watchers: O(1)
2774		2923
2775	=item Stopping an io/signal/child watcher: O(number_of_watchers_for_this_(fd/signal/pid % EV_PID_HASHSIZE))	2924	=item Stopping an io/signal/child watcher: O(number_of_watchers_for_this_(fd/signal/pid % EV_PID_HASHSIZE))
2776		2925
2777	These watchers are stored in lists then need to be walked to find the	2926	These watchers are stored in lists then need to be walked to find the
2778	correct watcher to remove. The lists are usually short (you don't usually	2927	correct watcher to remove. The lists are usually short (you don't usually
…		…
2794	=item Priority handling: O(number_of_priorities)	2943	=item Priority handling: O(number_of_priorities)
2795		2944
2796	Priorities are implemented by allocating some space for each	2945	Priorities are implemented by allocating some space for each
2797	priority. When doing priority-based operations, libev usually has to	2946	priority. When doing priority-based operations, libev usually has to
2798	linearly search all the priorities, but starting/stopping and activating	2947	linearly search all the priorities, but starting/stopping and activating
2799	watchers becomes O(1) w.r.t. prioritiy handling.	2948	watchers becomes O(1) w.r.t. priority handling.
		2949
		2950	=item Sending an ev_async: O(1)
		2951
		2952	=item Processing ev_async_send: O(number_of_async_watchers)
		2953
		2954	=item Processing signals: O(max_signal_number)
		2955
		2956	Sending involves a syscall I<iff> there were no other C<ev_async_send>
		2957	calls in the current loop iteration. Checking for async and signal events
		2958	involves iterating over all running async watchers or all signal numbers.
2800		2959
2801	=back	2960	=back
2802		2961
2803		2962
2804	=head1 Win32 platform limitations and workarounds	2963	=head1 Win32 platform limitations and workarounds

Diff Legend

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

Comparing libev/ev.pod (file contents): Revision 1.118 by root, Thu Jan 10 06:00:55 2008 UTC vs. Revision 1.130 by root, Wed Feb 6 18:34:24 2008 UTC

Diff Legend

Comparing libev/ev.pod (file contents):
Revision 1.118 by root, Thu Jan 10 06:00:55 2008 UTC vs.
Revision 1.130 by root, Wed Feb 6 18:34:24 2008 UTC