--- libev/ev.pod 2009/07/27 01:10:17 1.263 +++ libev/ev.pod 2009/12/26 09:21:54 1.275 @@ -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,7 +372,7 @@ 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 @@ -413,6 +413,9 @@ =item C (value 4, Linux) +Use the linux-specific epoll(7) interface (for both pre- and post-2.6.9 +kernels). + For few fds, this backend is a bit little slower than poll and select, but it scales phenomenally better. While poll and select usually scale like O(total_fds) where n is the total number of fds (or the highest fd), @@ -592,7 +595,7 @@ In general it is not advisable to call this function except in the rare occasion where you really need to free e.g. the signal handling pipe fds. If you need dynamically allocated loops it is better to use -C and C). +C and C. =item ev_loop_destroy (loop) @@ -706,8 +709,8 @@ =item ev_loop (loop, int flags) Finally, this is it, the event handler. This function usually is called -after you initialised all your watchers and you want to start handling -events. +after you have initialised all your watchers and you want to start +handling events. If the flags argument is specified as C<0>, it will not return until either no event watchers are active anymore or C was called. @@ -918,7 +921,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 @@ -1125,7 +1128,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 @@ -1148,7 +1151,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. @@ -1158,7 +1161,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). @@ -1193,7 +1196,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) @@ -1235,6 +1238,20 @@ 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 (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 +initialised but not necessarily started event watcher). Obviously you must +not free the watcher as long as it has pending events. + +Stopping the watcher, letting libev invoke it, or calling +C will clear the pending event, even if the watcher was +not started in the first place. + +See also C and C for related +functions that do not need a watcher. + =back @@ -1839,7 +1856,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 @@ -2110,17 +2127,37 @@ with the kernel (thus it coexists with your own signal handlers as long as you don't register any with libev for the same signal). -Both the signal mask state (C) and the signal handler state -(C) are unspecified after starting a signal watcher (and after -sotpping it again), that is, libev might or might not block the signal, -and might or might not set or restore the installed signal handler. - If possible and supported, libev will install its handlers with C (or equivalent) behaviour enabled, so system calls should not be unduly interrupted. If you have a problem with system calls getting 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 + +Both the signal mask (C) and the signal disposition +(C) are unspecified after starting a signal watcher (and after +stopping it again), that is, libev might or might not block the signal, +and might or might not set or restore the installed signal handler. + +While this does not matter for the signal disposition (libev never +sets signals to C, so handlers will be reset to C on +C), this matters for the signal mask: many programs do not expect +certain signals to be blocked. + +This means that before calling C (from the child) you should reset +the signal mask to whatever "default" you expect (all clear is a good +choice usually). + +The simplest way to ensure that the signal mask is reset in the child is +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. + =head3 Watcher-Specific Functions and Data Members =over 4 @@ -2946,7 +2983,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 @@ -3114,18 +3152,12 @@ ev_once (STDIN_FILENO, EV_READ, 10., stdin_ready, 0); -=item ev_feed_event (struct ev_loop *, 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 -initialised but not necessarily started event watcher). - -=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!). @@ -3215,7 +3247,7 @@ =item ev::TYPE::TYPE () -=item ev::TYPE::TYPE (struct ev_loop *) +=item ev::TYPE::TYPE (loop) =item ev::TYPE::~TYPE @@ -3302,7 +3334,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). @@ -3665,7 +3697,7 @@ it is assumed that all these functions actually work on fds, even on win32. Should not be defined on non-win32 platforms. -=item EV_FD_TO_WIN32_HANDLE +=item EV_FD_TO_WIN32_HANDLE(fd) If C is enabled, then libev needs a way to map file descriptors to socket handles. When not defining this symbol (the @@ -3673,6 +3705,20 @@ correct. In some cases, programs use their own file descriptor management, in which case they can provide this function to map fds to socket handles. +=item EV_WIN32_HANDLE_TO_FD(handle) + +If C then libev maps handles to file descriptors +using the standard C<_open_osfhandle> function. For programs implementing +their own fd to handle mapping, overwriting this function makes it easier +to do so. This can be done by defining this macro to an appropriate value. + +=item EV_WIN32_CLOSE_FD(fd) + +If programs implement their own fd to handle mapping on win32, then this +macro can be used to override the C function, useful to unregister +file descriptors again. Note that the replacement function has to close +the underlying OS handle. + =item EV_USE_POLL If defined to be C<1>, libev will compile in support for the C(2)