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

Comparing libev/ev.pod (file contents):
Revision 1.121 by root, Mon Jan 28 12:13:54 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
776The event loop has been resumed in the child process after fork (see 776The event loop has been resumed in the child process after fork (see
777C<ev_fork>). 777C<ev_fork>).
778 778
779=item C<EV_ASYNC>
780
781The given async watcher has been asynchronously notified (see C<ev_async>).
782
779=item C<EV_ERROR> 783=item C<EV_ERROR>
780 784
781An unspecified error has occured, the watcher has been stopped. This might 785An unspecified error has occured, the watcher has been stopped. This might
782happen because the watcher could not be properly started because libev 786happen because the watcher could not be properly started because libev
783ran out of memory, a file descriptor was found to be closed or any other 787ran out of memory, a file descriptor was found to be closed or any other
… …
2046believe me. 2050believe me.
2047 2051
2048=back 2052=back
2049 2053
2050 2054
2055=head2 C<ev_async> - how to wake up another event loop
2056
2057In general, you cannot use an C<ev_loop> from multiple threads or other
2058asynchronous sources such as signal handlers (as opposed to multiple event
2059loops - those are of course safe to use in different threads).
2060
2061Sometimes, however, you need to wake up another event loop you do not
2062control, for example because it belongs to another thread. This is what
2063C<ev_async> watchers do: as long as the C<ev_async> watcher is active, you
2064can signal it by calling C<ev_async_send>, which is thread- and signal
2065safe.
2066
2067This functionality is very similar to C<ev_signal> watchers, as signals,
2068too, 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
2070C<ev_async_sent> calls).
2071
2072Unlike C<ev_signal> watchers, C<ev_async> works with any event loop, not
2073just the default loop.
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
2160=head3 Watcher-Specific Functions and Data Members
2161
2162=over 4
2163
2164=item ev_async_init (ev_async *, callback)
2165
2166Initialises and configures the async watcher - it has no parameters of any
2167kind. There is a C<ev_asynd_set> macro, but using it is utterly pointless,
2168believe me.
2169
2170=item ev_async_send (loop, ev_async *)
2171
2172Sends/signals/activates the given C<ev_async> watcher, that is, feeds
2173an C<EV_ASYNC> event on the watcher into the event loop. Unlike
2174C<ev_feed_event>, this call is safe to do in other threads, signal or
2175similar contexts (see the dicusssion of C<EV_ATOMIC_T> in the embedding
2176section below on what exactly this means).
2177
2178This call incurs the overhead of a syscall only once per loop iteration,
2179so while the overhead might be noticable, it doesn't apply to repeated
2180calls to C<ev_async_send>.
2181
2182=back
2183
2184
2051=head1 OTHER FUNCTIONS 2185=head1 OTHER FUNCTIONS
2052 2186
2053There are some other functions of possible interest. Described. Here. Now. 2187There are some other functions of possible interest. Described. Here. Now.
2054 2188
2055=over 4 2189=over 4
… …
2558 2692
2559If 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
2560interface to speed up C<ev_stat> watchers. Its actual availability will 2694interface to speed up C<ev_stat> watchers. Its actual availability will
2561be detected at runtime. 2695be detected at runtime.
2562 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. It is used both for signal handler "locking"
2703as well as for signal and thread safety in C<ev_async> watchers.
2704
2705In 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
2565The name of the F<ev.h> header file used to include it. The default if 2710The name of the F<ev.h> header file used to include it. The default if
2566undefined is C<"ev.h"> in F<event.h>, F<ev.c> and F<ev++.h>. This can be 2711undefined is C<"ev.h"> in F<event.h>, F<ev.c> and F<ev++.h>. This can be
2567used to virtually rename the F<ev.h> header file in case of conflicts. 2712used to virtually rename the F<ev.h> header file in case of conflicts.
… …
2632defined to be C<0>, then they are not. 2777defined to be C<0>, then they are not.
2633 2778
2634=item EV_FORK_ENABLE 2779=item EV_FORK_ENABLE
2635 2780
2636If undefined or defined to be C<1>, then fork watchers are supported. If 2781If undefined or defined to be C<1>, then fork watchers are supported. If
2782defined to be C<0>, then they are not.
2783
2784=item EV_ASYNC_ENABLE
2785
2786If undefined or defined to be C<1>, then async watchers are supported. If
2637defined to be C<0>, then they are not. 2787defined to be C<0>, then they are not.
2638 2788
2639=item EV_MINIMAL 2789=item EV_MINIMAL
2640 2790
2641If you need to shave off some kilobytes of code at the expense of some 2791If 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
2764That means that changing a timer costs less than removing/adding them 2914That means that changing a timer costs less than removing/adding them
2765as only the relative motion in the event queue has to be paid for. 2915as 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
2769These just add the watcher into an array or at the head of a list. 2919These 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
2775These watchers are stored in lists then need to be walked to find the 2925These watchers are stored in lists then need to be walked to find the
2776correct watcher to remove. The lists are usually short (you don't usually 2926correct 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
2794Priorities are implemented by allocating some space for each 2944Priorities are implemented by allocating some space for each
2795priority. When doing priority-based operations, libev usually has to 2945priority. When doing priority-based operations, libev usually has to
2796linearly search all the priorities, but starting/stopping and activating 2946linearly search all the priorities, but starting/stopping and activating
2797watchers becomes O(1) w.r.t. prioritiy handling. 2947watchers 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
2955Sending involves a syscall I<iff> there were no other C<ev_async_send>
2956calls in the current loop iteration. Checking for async and signal events
2957involves 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