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.130 by root, Wed Feb 6 18:34:24 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. But at least I can tell you would implement locking around your
2084queue:
2085
2086=over 4
2087
2088=item queueing from a signal handler context
2089
2090To implement race-free queueing, you simply add to the queue in the signal
2091handler but you block the signal handler in the watcher callback. Here is an example that does that for
2092some 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>
2124instead of C<sigprocmask> when you use threads, but libev doesn't do it
2125either...).
2126
2127=item queueing from a thread context
2128
2129The strategy for threads is different, as you cannot (easily) block
2130threads but you can easily preempt them, so to queue safely you need to
2131employ 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
2075=head3 Watcher-Specific Functions and Data Members 2161=head3 Watcher-Specific Functions and Data Members
2076 2162
2077=over 4 2163=over 4
2078 2164
2079=item ev_async_init (ev_async *, callback) 2165=item ev_async_init (ev_async *, callback)
… …
2607 2693
2608If defined to be C<1>, libev will compile in support for the Linux inotify 2694If 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 2695interface to speed up C<ev_stat> watchers. Its actual availability will
2610be detected at runtime. 2696be detected at runtime.
2611 2697
2698=item EV_ATOMIC_T
2699
2700Libev requires an integer type (suitable for storing C<0> or C<1>) whose
2701access is atomic with respect to other threads or signal contexts. No such
2702type is easily found in the C language, so you can provide your own type
2703that you know is safe for your purposes. It is used both for signal handler "locking"
2704as well as for signal and thread safety in C<ev_async> watchers.
2705
2706In 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
2612=item EV_H 2709=item EV_H
2613 2710
2614The name of the F<ev.h> header file used to include it. The default if 2711The 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 2712undefined 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. 2713used to virtually rename the F<ev.h> header file in case of conflicts.
… …
2681defined to be C<0>, then they are not. 2778defined to be C<0>, then they are not.
2682 2779
2683=item EV_FORK_ENABLE 2780=item EV_FORK_ENABLE
2684 2781
2685If undefined or defined to be C<1>, then fork watchers are supported. If 2782If undefined or defined to be C<1>, then fork watchers are supported. If
2783defined to be C<0>, then they are not.
2784
2785=item EV_ASYNC_ENABLE
2786
2787If undefined or defined to be C<1>, then async watchers are supported. If
2686defined to be C<0>, then they are not. 2788defined to be C<0>, then they are not.
2687 2789
2688=item EV_MINIMAL 2790=item EV_MINIMAL
2689 2791
2690If you need to shave off some kilobytes of code at the expense of some 2792If you need to shave off some kilobytes of code at the expense of some
… …
2811=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)
2812 2914
2813That means that changing a timer costs less than removing/adding them 2915That means that changing a timer costs less than removing/adding them
2814as only the relative motion in the event queue has to be paid for. 2916as only the relative motion in the event queue has to be paid for.
2815 2917
2816=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)
2817 2919
2818These just add the watcher into an array or at the head of a list. 2920These just add the watcher into an array or at the head of a list.
2819 2921
2820=item Stopping check/prepare/idle watchers: O(1) 2922=item Stopping check/prepare/idle/fork/async watchers: O(1)
2821 2923
2822=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))
2823 2925
2824These watchers are stored in lists then need to be walked to find the 2926These watchers are stored in lists then need to be walked to find the
2825correct watcher to remove. The lists are usually short (you don't usually 2927correct watcher to remove. The lists are usually short (you don't usually
… …
2841=item Priority handling: O(number_of_priorities) 2943=item Priority handling: O(number_of_priorities)
2842 2944
2843Priorities are implemented by allocating some space for each 2945Priorities are implemented by allocating some space for each
2844priority. When doing priority-based operations, libev usually has to 2946priority. When doing priority-based operations, libev usually has to
2845linearly search all the priorities, but starting/stopping and activating 2947linearly search all the priorities, but starting/stopping and activating
2846watchers becomes O(1) w.r.t. prioritiy handling. 2948watchers 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
2956Sending involves a syscall I<iff> there were no other C<ev_async_send>
2957calls in the current loop iteration. Checking for async and signal events
2958involves iterating over all running async watchers or all signal numbers.
2847 2959
2848=back 2960=back
2849 2961
2850 2962
2851=head1 Win32 platform limitations and workarounds 2963=head1 Win32 platform limitations and workarounds

Diff Legend

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