[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.130 by root, Wed Feb 6 18:34:24 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. 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
2049	=head1 OTHER FUNCTIONS	2186	=head1 OTHER FUNCTIONS
2050		2187
2051	There are some other functions of possible interest. Described. Here. Now.	2188	There are some other functions of possible interest. Described. Here. Now.
2052		2189
2053	=over 4	2190	=over 4
…		…
2280	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
2281	the constructor.	2418	the constructor.
2282		2419
2283	class myclass	2420	class myclass
2284	{	2421	{
2285	ev_io io; void io_cb (ev::io &w, int revents);	2422	ev::io io; void io_cb (ev::io &w, int revents);
2286	ev_idle idle void idle_cb (ev::idle &w, int revents);	2423	ev:idle idle void idle_cb (ev::idle &w, int revents);
2287		2424
2288	myclass ();	2425	myclass (int fd)
2289	}
2290
2291	myclass::myclass (int fd)
2292	{	2426	{
2293	io .set <myclass, &myclass::io_cb > (this);	2427	io .set <myclass, &myclass::io_cb > (this);
2294	idle.set <myclass, &myclass::idle_cb> (this);	2428	idle.set <myclass, &myclass::idle_cb> (this);
2295		2429
2296	io.start (fd, ev::READ);	2430	io.start (fd, ev::READ);
		2431	}
2297	}	2432	};
2298		2433
2299		2434
2300	=head1 MACRO MAGIC	2435	=head1 MACRO MAGIC
2301		2436
2302	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
…		…
2558		2693
2559	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
2560	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
2561	be detected at runtime.	2696	be detected at runtime.
2562		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
2563	=item EV_H	2709	=item EV_H
2564		2710
2565	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
2566	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
2567	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.
…		…
2632	defined to be C<0>, then they are not.	2778	defined to be C<0>, then they are not.
2633		2779
2634	=item EV_FORK_ENABLE	2780	=item EV_FORK_ENABLE
2635		2781
2636	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
2637	defined to be C<0>, then they are not.	2788	defined to be C<0>, then they are not.
2638		2789
2639	=item EV_MINIMAL	2790	=item EV_MINIMAL
2640		2791
2641	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
…		…
2762	=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)
2763		2914
2764	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
2765	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.
2766		2917
2767	=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)
2768		2919
2769	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.
2770		2921
2771	=item Stopping check/prepare/idle watchers: O(1)	2922	=item Stopping check/prepare/idle/fork/async watchers: O(1)
2772		2923
2773	=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))
2774		2925
2775	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
2776	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
…		…
2792	=item Priority handling: O(number_of_priorities)	2943	=item Priority handling: O(number_of_priorities)
2793		2944
2794	Priorities are implemented by allocating some space for each	2945	Priorities are implemented by allocating some space for each
2795	priority. When doing priority-based operations, libev usually has to	2946	priority. When doing priority-based operations, libev usually has to
2796	linearly search all the priorities, but starting/stopping and activating	2947	linearly search all the priorities, but starting/stopping and activating
2797	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.
2798		2959
2799	=back	2960	=back
2800		2961
2801		2962
2802	=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.119 by root, Tue Jan 15 04:07:37 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.119 by root, Tue Jan 15 04:07:37 2008 UTC vs.
Revision 1.130 by root, Wed Feb 6 18:34:24 2008 UTC