… | |
… | |
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 |
… | |
… | |
2046 | believe me. |
2050 | believe me. |
2047 | |
2051 | |
2048 | =back |
2052 | =back |
2049 | |
2053 | |
2050 | |
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 | |
2051 | =head1 OTHER FUNCTIONS |
2186 | =head1 OTHER FUNCTIONS |
2052 | |
2187 | |
2053 | There are some other functions of possible interest. Described. Here. Now. |
2188 | There are some other functions of possible interest. Described. Here. Now. |
2054 | |
2189 | |
2055 | =over 4 |
2190 | =over 4 |
… | |
… | |
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 |