ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/libev/ev.pod
(Generate patch)

Comparing libev/ev.pod (file contents):
Revision 1.122 by root, Thu Jan 31 13:10:56 2008 UTC vs.
Revision 1.126 by root, Fri Feb 1 13:46:26 2008 UTC

… …
2070C<ev_async_sent> calls). 2070C<ev_async_sent> calls).
2071 2071
2072Unlike C<ev_signal> watchers, C<ev_async> works with any event loop, not 2072Unlike C<ev_signal> watchers, C<ev_async> works with any event loop, not
2073just the default loop. 2073just the default loop.
2074 2074
2075=head3 Queueing
2076
2077C<ev_async> does not support queueing of data in any way. The reason
2078is that the author does not know of a simple (or any) algorithm for a
2079multiple-writer-single-reader queue that works in all cases and doesn't
2080need elaborate support such as pthreads.
2081
2082That means that if you want to queue data, you have to provide your own
2083queue. And here is how you would implement locking:
2084
2085=over 4
2086
2087=item queueing from a signal handler context
2088
2089To implement race-free queueing, you simply add to the queue in the signal
2090handler but you block the signal handler in the watcher callback. Here is an example that does that for
2091some 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>
2123instead of C<sigprocmask> when you use threads, but libev doesn't do it
2124either...).
2125
2126=item queueing from a thread context
2127
2128The strategy for threads is different, as you cannot (easily) block
2129threads but you can easily preempt them, so to queue safely you need to
2130emply 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
2075=head3 Watcher-Specific Functions and Data Members 2160=head3 Watcher-Specific Functions and Data Members
2076 2161
2077=over 4 2162=over 4
2078 2163
2079=item ev_async_init (ev_async *, callback) 2164=item ev_async_init (ev_async *, callback)
… …
2607 2692
2608If defined to be C<1>, libev will compile in support for the Linux inotify 2693If defined to be C<1>, libev will compile in support for the Linux inotify
2609interface to speed up C<ev_stat> watchers. Its actual availability will 2694interface to speed up C<ev_stat> watchers. Its actual availability will
2610be detected at runtime. 2695be detected at runtime.
2611 2696
2697=item EV_ATOMIC_T
2698
2699Libev requires an integer type (suitable for storing C<0> or C<1>) whose
2700access is atomic with respect to other threads or signal contexts. No such
2701type is easily found in the C language, so you can provide your own type
2702that you know is safe for your purposes.
2703
2704In 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
2612=item EV_H 2707=item EV_H
2613 2708
2614The name of the F<ev.h> header file used to include it. The default if 2709The name of the F<ev.h> header file used to include it. The default if
2615undefined is C<"ev.h"> in F<event.h>, F<ev.c> and F<ev++.h>. This can be 2710undefined is C<"ev.h"> in F<event.h>, F<ev.c> and F<ev++.h>. This can be
2616used to virtually rename the F<ev.h> header file in case of conflicts. 2711used to virtually rename the F<ev.h> header file in case of conflicts.
… …
2681defined to be C<0>, then they are not. 2776defined to be C<0>, then they are not.
2682 2777
2683=item EV_FORK_ENABLE 2778=item EV_FORK_ENABLE
2684 2779
2685If undefined or defined to be C<1>, then fork watchers are supported. If 2780If undefined or defined to be C<1>, then fork watchers are supported. If
2781defined to be C<0>, then they are not.
2782
2783=item EV_ASYNC_ENABLE
2784
2785If undefined or defined to be C<1>, then async watchers are supported. If
2686defined to be C<0>, then they are not. 2786defined to be C<0>, then they are not.
2687 2787
2688=item EV_MINIMAL 2788=item EV_MINIMAL
2689 2789
2690If you need to shave off some kilobytes of code at the expense of some 2790If you need to shave off some kilobytes of code at the expense of some

Diff Legend

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