--- libev/ev.pod 2008/01/15 04:07:37 1.119 +++ libev/ev.pod 2008/02/24 06:50:16 1.133 @@ -508,6 +508,10 @@ C. Yes, you have to call this on every allocated event loop after fork, and how you do this is entirely your own problem. +=item int ev_is_default_loop (loop) + +Returns true when the given loop actually is the default loop, false otherwise. + =item unsigned int ev_loop_count (loop) Returns the count of loop iterations for the loop, which is identical to @@ -776,6 +780,10 @@ The event loop has been resumed in the child process after fork (see C). +=item C + +The given async watcher has been asynchronously notified (see C). + =item C An unspecified error has occured, the watcher has been stopped. This might @@ -1150,7 +1158,7 @@ the timer (because it takes longer than those 10 seconds to do stuff) the timer will not fire more than once per event loop iteration. -=item ev_timer_again (loop) +=item ev_timer_again (loop, ev_timer *) This will act as if the timer timed out and restart it again if it is repeating. The exact semantics are: @@ -1269,7 +1277,7 @@ that is, if it is to be run at January 1st 2011 then it will run when the system time reaches or surpasses this time. -=item * non-repeating interval timer (at = offset, interval > 0, reschedule_cb = 0) +=item * repeating interval timer (at = offset, interval > 0, reschedule_cb = 0) In this mode the watcher will always be scheduled to time out at the next C time (for some integer N, which can also be negative) @@ -1430,6 +1438,20 @@ =back +=head3 Examples + +Example: Try to exit cleanly on SIGINT and SIGTERM. + + static void + sigint_cb (struct ev_loop *loop, struct ev_signal *w, int revents) + { + ev_unloop (loop, EVUNLOOP_ALL); + } + + struct ev_signal signal_watcher; + ev_signal_init (&signal_watcher, sigint_cb, SIGINT); + ev_signal_start (loop, &sigint_cb); + =head2 C - watch out for process status changes @@ -1440,16 +1462,18 @@ =over 4 -=item ev_child_init (ev_child *, callback, int pid) +=item ev_child_init (ev_child *, callback, int pid, int trace) -=item ev_child_set (ev_child *, int pid) +=item ev_child_set (ev_child *, int pid, int trace) Configures the watcher to wait for status changes of process C (or I process if C is specified as C<0>). The callback can look at the C member of the C watcher structure to see the status word (use the macros from C and see your systems C documentation). The C member contains the pid of the -process causing the status change. +process causing the status change. C must be either C<0> (only +activate the watcher when the process terminates) or C<1> (additionally +activate the watcher when the process is stopped or continued). =item int pid [read-only] @@ -1466,20 +1490,6 @@ =back -=head3 Examples - -Example: Try to exit cleanly on SIGINT and SIGTERM. - - static void - sigint_cb (struct ev_loop *loop, struct ev_signal *w, int revents) - { - ev_unloop (loop, EVUNLOOP_ALL); - } - - struct ev_signal signal_watcher; - ev_signal_init (&signal_watcher, sigint_cb, SIGINT); - ev_signal_start (loop, &sigint_cb); - =head2 C - did the file attributes just change? @@ -1568,7 +1578,7 @@ relative to the attributes at the time the watcher was started (or the last change was detected). -=item ev_stat_stat (ev_stat *) +=item ev_stat_stat (loop, ev_stat *) Updates the stat buffer immediately with new values. If you change the watched path in your callback, you could call this fucntion to avoid @@ -1695,7 +1705,7 @@ { free (w); // now do something you wanted to do when the program has - // no longer asnything immediate to do. + // no longer anything immediate to do. } struct ev_idle *idle_watcher = malloc (sizeof (struct ev_idle)); @@ -2046,6 +2056,137 @@ =back +=head2 C - how to wake up another event loop + +In general, you cannot use an C from multiple threads or other +asynchronous sources such as signal handlers (as opposed to multiple event +loops - those are of course safe to use in different threads). + +Sometimes, however, you need to wake up another event loop you do not +control, for example because it belongs to another thread. This is what +C watchers do: as long as the C watcher is active, you +can signal it by calling C, which is thread- and signal +safe. + +This functionality is very similar to C watchers, as signals, +too, are asynchronous in nature, and signals, too, will be compressed +(i.e. the number of callback invocations may be less than the number of +C calls). + +Unlike C watchers, C works with any event loop, not +just the default loop. + +=head3 Queueing + +C does not support queueing of data in any way. The reason +is that the author does not know of a simple (or any) algorithm for a +multiple-writer-single-reader queue that works in all cases and doesn't +need elaborate support such as pthreads. + +That means that if you want to queue data, you have to provide your own +queue. But at least I can tell you would implement locking around your +queue: + +=over 4 + +=item queueing from a signal handler context + +To implement race-free queueing, you simply add to the queue in the signal +handler but you block the signal handler in the watcher callback. Here is an example that does that for +some fictitiuous SIGUSR1 handler: + + static ev_async mysig; + + static void + sigusr1_handler (void) + { + sometype data; + + // no locking etc. + queue_put (data); + ev_async_send (EV_DEFAULT_ &mysig); + } + + static void + mysig_cb (EV_P_ ev_async *w, int revents) + { + sometype data; + sigset_t block, prev; + + sigemptyset (&block); + sigaddset (&block, SIGUSR1); + sigprocmask (SIG_BLOCK, &block, &prev); + + while (queue_get (&data)) + process (data); + + if (sigismember (&prev, SIGUSR1) + sigprocmask (SIG_UNBLOCK, &block, 0); + } + +(Note: pthreads in theory requires you to use C +instead of C when you use threads, but libev doesn't do it +either...). + +=item queueing from a thread context + +The strategy for threads is different, as you cannot (easily) block +threads but you can easily preempt them, so to queue safely you need to +employ a traditional mutex lock, such as in this pthread example: + + static ev_async mysig; + static pthread_mutex_t mymutex = PTHREAD_MUTEX_INITIALIZER; + + static void + otherthread (void) + { + // only need to lock the actual queueing operation + pthread_mutex_lock (&mymutex); + queue_put (data); + pthread_mutex_unlock (&mymutex); + + ev_async_send (EV_DEFAULT_ &mysig); + } + + static void + mysig_cb (EV_P_ ev_async *w, int revents) + { + pthread_mutex_lock (&mymutex); + + while (queue_get (&data)) + process (data); + + pthread_mutex_unlock (&mymutex); + } + +=back + + +=head3 Watcher-Specific Functions and Data Members + +=over 4 + +=item ev_async_init (ev_async *, callback) + +Initialises and configures the async watcher - it has no parameters of any +kind. There is a C macro, but using it is utterly pointless, +believe me. + +=item ev_async_send (loop, ev_async *) + +Sends/signals/activates the given C watcher, that is, feeds +an C event on the watcher into the event loop. Unlike +C, this call is safe to do in other threads, signal or +similar contexts (see the dicusssion of C in the embedding +section below on what exactly this means). + +This call incurs the overhead of a syscall only once per loop iteration, +so while the overhead might be noticable, it doesn't apply to repeated +calls to C. + +=back + + =head1 OTHER FUNCTIONS There are some other functions of possible interest. Described. Here. Now. @@ -2282,19 +2423,17 @@ class myclass { - ev_io io; void io_cb (ev::io &w, int revents); - ev_idle idle void idle_cb (ev::idle &w, int revents); - - myclass (); - } + ev::io io; void io_cb (ev::io &w, int revents); + ev:idle idle void idle_cb (ev::idle &w, int revents); - myclass::myclass (int fd) - { - io .set (this); - idle.set (this); + myclass (int fd) + { + io .set (this); + idle.set (this); - io.start (fd, ev::READ); - } + io.start (fd, ev::READ); + } + }; =head1 MACRO MAGIC @@ -2560,6 +2699,17 @@ interface to speed up C watchers. Its actual availability will be detected at runtime. +=item EV_ATOMIC_T + +Libev requires an integer type (suitable for storing C<0> or C<1>) whose +access is atomic with respect to other threads or signal contexts. No such +type is easily found in the C language, so you can provide your own type +that you know is safe for your purposes. It is used both for signal handler "locking" +as well as for signal and thread safety in C watchers. + +In the absense of this define, libev will use C +(from F), which is usually good enough on most platforms. + =item EV_H The name of the F header file used to include it. The default if @@ -2636,6 +2786,11 @@ If undefined or defined to be C<1>, then fork watchers are supported. If defined to be C<0>, then they are not. +=item EV_ASYNC_ENABLE + +If undefined or defined to be C<1>, then async watchers are supported. If +defined to be C<0>, then they are not. + =item EV_MINIMAL If you need to shave off some kilobytes of code at the expense of some @@ -2764,11 +2919,11 @@ That means that changing a timer costs less than removing/adding them as only the relative motion in the event queue has to be paid for. -=item Starting io/check/prepare/idle/signal/child watchers: O(1) +=item Starting io/check/prepare/idle/signal/child/fork/async watchers: O(1) These just add the watcher into an array or at the head of a list. -=item Stopping check/prepare/idle watchers: O(1) +=item Stopping check/prepare/idle/fork/async watchers: O(1) =item Stopping an io/signal/child watcher: O(number_of_watchers_for_this_(fd/signal/pid % EV_PID_HASHSIZE)) @@ -2794,7 +2949,17 @@ Priorities are implemented by allocating some space for each priority. When doing priority-based operations, libev usually has to linearly search all the priorities, but starting/stopping and activating -watchers becomes O(1) w.r.t. prioritiy handling. +watchers becomes O(1) w.r.t. priority handling. + +=item Sending an ev_async: O(1) + +=item Processing ev_async_send: O(number_of_async_watchers) + +=item Processing signals: O(max_signal_number) + +Sending involves a syscall I there were no other C +calls in the current loop iteration. Checking for async and signal events +involves iterating over all running async watchers or all signal numbers. =back