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

Comparing libev/ev.pod (file contents):
Revision 1.119 by root, Tue Jan 15 04:07:37 2008 UTC vs.
Revision 1.129 by root, Tue Feb 5 23:56:33 2008 UTC

…		…
774	=item C<EV_FORK>	774	=item C<EV_FORK>
775		775
776	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
777	C<ev_fork>).	777	C<ev_fork>).
778		778
		779	=item C<EV_ASYNC>
		780
		781	The given async watcher has been asynchronously notified (see C<ev_async>).
		782
779	=item C<EV_ERROR>	783	=item C<EV_ERROR>
780		784
781	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
782	happen because the watcher could not be properly started because libev	786	happen because the watcher could not be properly started because libev
783	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
…		…
1438		1442
1439	=head3 Watcher-Specific Functions and Data Members	1443	=head3 Watcher-Specific Functions and Data Members
1440		1444
1441	=over 4	1445	=over 4
1442		1446
1443	=item ev_child_init (ev_child *, callback, int pid)	1447	=item ev_child_init (ev_child *, callback, int pid, int trace)
1444		1448
1445	=item ev_child_set (ev_child *, int pid)	1449	=item ev_child_set (ev_child *, int pid, int trace)
1446		1450
1447	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
1448	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
1449	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
1450	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
1451	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
1452	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).
1453		1459
1454	=item int pid [read-only]	1460	=item int pid [read-only]
1455		1461
1456	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.
1457		1463
…		…
1693	static void	1699	static void
1694	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)
1695	{	1701	{
1696	free (w);	1702	free (w);
1697	// now do something you wanted to do when the program has	1703	// now do something you wanted to do when the program has
1698	// no longer asnything immediate to do.	1704	// no longer anything immediate to do.
1699	}	1705	}
1700		1706
1701	struct ev_idle *idle_watcher = malloc (sizeof (struct ev_idle));	1707	struct ev_idle *idle_watcher = malloc (sizeof (struct ev_idle));
1702	ev_idle_init (idle_watcher, idle_cb);	1708	ev_idle_init (idle_watcher, idle_cb);
1703	ev_idle_start (loop, idle_cb);	1709	ev_idle_start (loop, idle_cb);
…		…
2044	believe me.	2050	believe me.
2045		2051
2046	=back	2052	=back
2047		2053
2048		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
2049	=head1 OTHER FUNCTIONS	2185	=head1 OTHER FUNCTIONS
2050		2186
2051	There are some other functions of possible interest. Described. Here. Now.	2187	There are some other functions of possible interest. Described. Here. Now.
2052		2188
2053	=over 4	2189	=over 4
…		…
2280	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
2281	the constructor.	2417	the constructor.
2282		2418
2283	class myclass	2419	class myclass
2284	{	2420	{
2285	ev_io io; void io_cb (ev::io &w, int revents);	2421	ev::io io; void io_cb (ev::io &w, int revents);
2286	ev_idle idle void idle_cb (ev::idle &w, int revents);	2422	ev:idle idle void idle_cb (ev::idle &w, int revents);
2287		2423
2288	myclass ();	2424	myclass (int fd)
2289	}
2290
2291	myclass::myclass (int fd)
2292	{	2425	{
2293	io .set <myclass, &myclass::io_cb > (this);	2426	io .set <myclass, &myclass::io_cb > (this);
2294	idle.set <myclass, &myclass::idle_cb> (this);	2427	idle.set <myclass, &myclass::idle_cb> (this);
2295		2428
2296	io.start (fd, ev::READ);	2429	io.start (fd, ev::READ);
		2430	}
2297	}	2431	};
2298		2432
2299		2433
2300	=head1 MACRO MAGIC	2434	=head1 MACRO MAGIC
2301		2435
2302	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
…		…
2558		2692
2559	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
2560	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
2561	be detected at runtime.	2695	be detected at runtime.
2562		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. It is used both for signal handler "locking"
		2703	as well as for signal and thread safety in C<ev_async> watchers.
		2704
		2705	In the absense of this define, libev will use C<sig_atomic_t volatile>
		2706	(from F<signal.h>), which is usually good enough on most platforms.
		2707
2563	=item EV_H	2708	=item EV_H
2564		2709
2565	The name of the F<ev.h> header file used to include it. The default if	2710	The name of the F<ev.h> header file used to include it. The default if
2566	undefined is C<"ev.h"> in F<event.h>, F<ev.c> and F<ev++.h>. This can be	2711	undefined is C<"ev.h"> in F<event.h>, F<ev.c> and F<ev++.h>. This can be
2567	used to virtually rename the F<ev.h> header file in case of conflicts.	2712	used to virtually rename the F<ev.h> header file in case of conflicts.
…		…
2632	defined to be C<0>, then they are not.	2777	defined to be C<0>, then they are not.
2633		2778
2634	=item EV_FORK_ENABLE	2779	=item EV_FORK_ENABLE
2635		2780
2636	If undefined or defined to be C<1>, then fork watchers are supported. If	2781	If undefined or defined to be C<1>, then fork watchers are supported. If
		2782	defined to be C<0>, then they are not.
		2783
		2784	=item EV_ASYNC_ENABLE
		2785
		2786	If undefined or defined to be C<1>, then async watchers are supported. If
2637	defined to be C<0>, then they are not.	2787	defined to be C<0>, then they are not.
2638		2788
2639	=item EV_MINIMAL	2789	=item EV_MINIMAL
2640		2790
2641	If you need to shave off some kilobytes of code at the expense of some	2791	If you need to shave off some kilobytes of code at the expense of some
…		…
2762	=item Changing timer/periodic watchers (by autorepeat or calling again): O(log skipped_other_timers)	2912	=item Changing timer/periodic watchers (by autorepeat or calling again): O(log skipped_other_timers)
2763		2913
2764	That means that changing a timer costs less than removing/adding them	2914	That means that changing a timer costs less than removing/adding them
2765	as only the relative motion in the event queue has to be paid for.	2915	as only the relative motion in the event queue has to be paid for.
2766		2916
2767	=item Starting io/check/prepare/idle/signal/child watchers: O(1)	2917	=item Starting io/check/prepare/idle/signal/child/fork/async watchers: O(1)
2768		2918
2769	These just add the watcher into an array or at the head of a list.	2919	These just add the watcher into an array or at the head of a list.
2770		2920
2771	=item Stopping check/prepare/idle watchers: O(1)	2921	=item Stopping check/prepare/idle/fork/async watchers: O(1)
2772		2922
2773	=item Stopping an io/signal/child watcher: O(number_of_watchers_for_this_(fd/signal/pid % EV_PID_HASHSIZE))	2923	=item Stopping an io/signal/child watcher: O(number_of_watchers_for_this_(fd/signal/pid % EV_PID_HASHSIZE))
2774		2924
2775	These watchers are stored in lists then need to be walked to find the	2925	These watchers are stored in lists then need to be walked to find the
2776	correct watcher to remove. The lists are usually short (you don't usually	2926	correct watcher to remove. The lists are usually short (you don't usually
…		…
2792	=item Priority handling: O(number_of_priorities)	2942	=item Priority handling: O(number_of_priorities)
2793		2943
2794	Priorities are implemented by allocating some space for each	2944	Priorities are implemented by allocating some space for each
2795	priority. When doing priority-based operations, libev usually has to	2945	priority. When doing priority-based operations, libev usually has to
2796	linearly search all the priorities, but starting/stopping and activating	2946	linearly search all the priorities, but starting/stopping and activating
2797	watchers becomes O(1) w.r.t. prioritiy handling.	2947	watchers becomes O(1) w.r.t. priority handling.
		2948
		2949	=item Sending an ev_async: O(1)
		2950
		2951	=item Processing ev_async_send: O(number_of_async_watchers)
		2952
		2953	=item Processing signals: O(max_signal_number)
		2954
		2955	Sending involves a syscall I<iff> there were no other C<ev_async_send>
		2956	calls in the current loop iteration. Checking for async and signal events
		2957	involves iterating over all running async watchers or all signal numbers.
2798		2958
2799	=back	2959	=back
2800		2960
2801		2961
2802	=head1 Win32 platform limitations and workarounds	2962	=head1 Win32 platform limitations and workarounds

Diff Legend

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

Comparing libev/ev.pod (file contents): Revision 1.119 by root, Tue Jan 15 04:07:37 2008 UTC vs. Revision 1.129 by root, Tue Feb 5 23:56:33 2008 UTC

Diff Legend

Comparing libev/ev.pod (file contents):
Revision 1.119 by root, Tue Jan 15 04:07:37 2008 UTC vs.
Revision 1.129 by root, Tue Feb 5 23:56:33 2008 UTC