--- libev/ev.pod 2009/11/24 14:46:59 1.273 +++ libev/ev.pod 2009/12/31 06:50:17 1.277 @@ -120,7 +120,7 @@ more info about various configuration options please have a look at B section in this manual. If libev was configured without support for multiple event loops, then all functions taking an initial argument of -name C (which is always of type C) will not have +name C (which is always of type C) will not have this argument. =head2 TIME REPRESENTATION @@ -372,13 +372,16 @@ testing, this flag can be useful to conserve inotify file descriptors, as otherwise each loop using C watchers consumes one inotify handle. -=item C +=item C -When this flag is specified, then libev will not attempt to use the -I API for it's C (and C) watchers. This is -probably only useful to work around any bugs in libev. Consequently, this -flag might go away once the signalfd functionality is considered stable, -so it's useful mostly in environment variables and not in program code. +When this flag is specified, then libev will attempt to use the +I API for it's C (and C) watchers. This API +delivers signals synchronously, which makes is both faster and might make +it possible to get the queued signal data. + +Signalfd will not be used by default as this changes your signal mask, and +there are a lot of shoddy libraries and programs (glib's threadpool for +example) that can't properly initialise their signal masks. =item C (value 1, portable select backend) @@ -794,9 +797,10 @@ loop: Every watcher keeps one reference, and as long as the reference count is nonzero, C will not return on its own. -If you have a watcher you never unregister that should not keep C -from returning, call ev_unref() after starting, and ev_ref() before -stopping it. +This is useful when you have a watcher that you never intend to +unregister, but that nevertheless should not keep C from +returning. In such a case, call C after starting, and C +before stopping it. As an example, libev itself uses this for its internal signal pipe: It is not visible to the libev user and should not keep C from @@ -921,7 +925,7 @@ C and C (that's their only purpose after all), no modifications done will affect the event loop, i.e. adding watchers will have no effect on the set of file descriptors being watched, or the time -waited. USe an C watcher to wake up C when you want it +waited. Use an C watcher to wake up C when you want it to take note of any changes you made. In theory, threads executing C will be async-cancel safe between @@ -1128,7 +1132,7 @@ ev_init (&w, my_cb); ev_io_set (&w, STDIN_FILENO, EV_READ); -=item C (ev_TYPE *, [args]) +=item C (ev_TYPE *watcher, [args]) This macro initialises the type-specific parts of a watcher. You need to call C at least once before you call this macro, but you can @@ -1151,7 +1155,7 @@ ev_io_init (&w, my_cb, STDIN_FILENO, EV_READ); -=item C (loop *, ev_TYPE *watcher) +=item C (loop, ev_TYPE *watcher) Starts (activates) the given watcher. Only active watchers will receive events. If the watcher is already active nothing will happen. @@ -1161,7 +1165,7 @@ ev_io_start (EV_DEFAULT_UC, &w); -=item C (loop *, ev_TYPE *watcher) +=item C (loop, ev_TYPE *watcher) Stops the given watcher if active, and clears the pending status (whether the watcher was active or not). @@ -1196,7 +1200,7 @@ Change the callback. You can change the callback at virtually any time (modulo threads). -=item ev_set_priority (ev_TYPE *watcher, priority) +=item ev_set_priority (ev_TYPE *watcher, int priority) =item int ev_priority (ev_TYPE *watcher) @@ -1238,7 +1242,7 @@ Sometimes it can be useful to "poll" a watcher instead of waiting for its callback to be invoked, which can be accomplished with this function. -=item ev_feed_event (struct ev_loop *, watcher *, int revents) +=item ev_feed_event (loop, ev_TYPE *watcher, int revents) Feeds the given event set into the event loop, as if the specified event had happened for the specified watcher (which must be a pointer to an @@ -1856,7 +1860,7 @@ This sounds a bit complicated, see L, above, for a usage example. -=item ev_timer_remaining (loop, ev_timer *) +=item ev_tstamp ev_timer_remaining (loop, ev_timer *) Returns the remaining time until a timer fires. If the timer is active, then this time is relative to the current event loop time, otherwise it's @@ -2133,7 +2137,7 @@ interrupted by signals you can block all signals in an C watcher and unblock them in an C watcher. -=head3 The special problem of inheritance over execve +=head3 The special problem of inheritance over fork/execve/pthread_create Both the signal mask (C) and the signal disposition (C) are unspecified after starting a signal watcher (and after @@ -2153,10 +2157,15 @@ to install a fork handler with C that resets it. That will catch fork calls done by libraries (such as the libc) as well. -In current versions of libev, you can also ensure that the signal mask is -not blocking any signals (except temporarily, so thread users watch out) -by specifying the C when creating the event loop. This -is not guaranteed for future versions, however. +In current versions of libev, the signal will not be blocked indefinitely +unless you use the C API (C). While this reduces +the window of opportunity for problems, it will not go away, as libev +I to modify the signal mask, at least temporarily. + +So I can't stress this enough I. This is not a libev-specific thing, this is true for most event +libraries. =head3 Watcher-Specific Functions and Data Members @@ -2983,7 +2992,8 @@ 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. +need elaborate support such as pthreads or unportable memory access +semantics. That means that if you want to queue data, you have to provide your own queue. But at least I can tell you how to implement locking around your @@ -3151,12 +3161,12 @@ ev_once (STDIN_FILENO, EV_READ, 10., stdin_ready, 0); -=item ev_feed_fd_event (struct ev_loop *, int fd, int revents) +=item ev_feed_fd_event (loop, int fd, int revents) Feed an event on the given fd, as if a file descriptor backend detected the given events it. -=item ev_feed_signal_event (struct ev_loop *loop, int signum) +=item ev_feed_signal_event (loop, int signum) Feed an event as if the given signal occurred (C must be the default loop!). @@ -3246,7 +3256,7 @@ =item ev::TYPE::TYPE () -=item ev::TYPE::TYPE (struct ev_loop *) +=item ev::TYPE::TYPE (loop) =item ev::TYPE::~TYPE @@ -3333,7 +3343,7 @@ static void io_cb (ev::io &w, int revents) { } iow.set (); -=item w->set (struct ev_loop *) +=item w->set (loop) Associates a different C with this watcher. You can only do this when the watcher is inactive (and not pending either).