[ViewVC] Diff of: cvs/libev/ev.pod

Comparing libev/ev.pod (file contents):
Revision 1.260 by root, Sun Jul 19 21:18:03 2009 UTC vs.
Revision 1.273 by root, Tue Nov 24 14:46:59 2009 UTC

 =head2 FEATURES
 Libev supports C<select>, C<poll>, the Linux-specific C<epoll>, the
 BSD-specific C<kqueue> and the Solaris-specific event port mechanisms
 for file descriptor events (C<ev_io>), the Linux C<inotify> interface
-(for C<ev_stat>), relative timers (C<ev_timer>), absolute timers
+(for C<ev_stat>), Linux eventfd/signalfd (for faster and cleaner
-with customised rescheduling (C<ev_periodic>), synchronous signals
+inter-thread wakeup (C<ev_async>)/signal handling (C<ev_signal>)) relative
-(C<ev_signal>), process status change events (C<ev_child>), and event
+timers (C<ev_timer>), absolute timers with customised rescheduling
-watchers dealing with the event loop mechanism itself (C<ev_idle>,
+(C<ev_periodic>), synchronous signals (C<ev_signal>), process status
-C<ev_embed>, C<ev_prepare> and C<ev_check> watchers) as well as
+change events (C<ev_child>), and event watchers dealing with the event
-file watchers (C<ev_stat>) and even limited support for fork events
+loop mechanism itself (C<ev_idle>, C<ev_embed>, C<ev_prepare> and
-(C<ev_fork>).
+C<ev_check> watchers) as well as file watchers (C<ev_stat>) and even
+limited support for fork events (C<ev_fork>).
 It also is quite fast (see this
 L<benchmark|http://libev.schmorp.de/bench.html> comparing it to libevent
 for example).
 When this flag is specified, then libev will not attempt to use the
 I<inotify> API for it's C<ev_stat> watchers. Apart from debugging and
 testing, this flag can be useful to conserve inotify file descriptors, as
 otherwise each loop using C<ev_stat> watchers consumes one inotify handle.
-=item C<EVFLAG_NOSIGNALFD>
+=item C<EVFLAG_NOSIGFD>
 When this flag is specified, then libev will not attempt to use the
 I<signalfd> API for it's C<ev_signal> (and C<ev_child>) 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,
 This backend maps C<EV_READ> to C<POLLIN | POLLERR | POLLHUP>, and
 C<EV_WRITE> to C<POLLOUT | POLLERR | POLLHUP>.
 =item C<EVBACKEND_EPOLL>   (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),
 epoll scales either O(1) or O(active_fds).
 as signal and child watchers) would need to be stopped manually.
 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<ev_loop_new> and C<ev_loop_destroy>).
+C<ev_loop_new> and C<ev_loop_destroy>.
 =item ev_loop_destroy (loop)
 Like C<ev_default_destroy>, but destroys an event loop created by an
 earlier call to C<ev_loop_new>.
 event loop time (see C<ev_now_update>).
 =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
+after you have initialised all your watchers and you want to start
-events.
+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<ev_unloop> was called.
 Please note that an explicit C<ev_unloop> is usually better than
 watcher isn't pending it does nothing and returns C<0>.
 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)
+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<ev_clear_pending> will clear the pending event, even if the watcher was
+not started in the first place.
+See also C<ev_feed_fd_event> and C<ev_feed_signal_event> for related
+functions that do not need a watcher.
 =back
 =head2 ASSOCIATING CUSTOM DATA WITH A WATCHER
 When the first watcher gets started will libev actually register something
 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<sigprocmask>) and the signal handler state
-(C<sigaction>) 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<SA_RESTART> (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<ev_check> watcher
 and unblock them in an C<ev_prepare> watcher.
+=head3 The special problem of inheritance over execve
+Both the signal mask (C<sigprocmask>) and the signal disposition
+(C<sigaction>) 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<SIG_IGN>, so handlers will be reset to C<SIG_DFL> on
+C<execve>), this matters for the signal mask: many programs do not expect
+certain signals to be blocked.
+This means that before calling C<exec> (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<pthread_atfork> 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<EVFLAG_NOSIGFD> when creating the event loop. This
+is not guaranteed for future versions, however.
 =head3 Watcher-Specific Functions and Data Members
 =over 4
        /* doh, nothing entered */;
    }
    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)
 Feed an event on the given fd, as if a file descriptor backend detected
 the given events it.
 =item Ocaml
 Erkki Seppala has written Ocaml bindings for libev, to be found at
 L<http://modeemi.cs.tut.fi/~flux/software/ocaml-ev/>.
+=item Lua
+Brian Maher has written a partial interface to libev
+for lua (only C<ev_io> and C<ev_timer>), to be found at
+L<http://github.com/brimworks/lua-ev>.
 =back
 =head1 MACRO MAGIC
 keeps libev from including F<config.h>, and it also defines dummy
 implementations for some libevent functions (such as logging, which is not
 supported). It will also not define any of the structs usually found in
 F<event.h> that are not directly supported by the libev core alone.
-In stanbdalone mode, libev will still try to automatically deduce the
+In standalone mode, libev will still try to automatically deduce the
 configuration, but has to be more conservative.
 =item EV_USE_MONOTONIC
 If defined to be C<1>, libev will try to detect the availability of the
 be used is the winsock select). This means that it will call
 C<_get_osfhandle> on the fd to convert it to an OS handle. Otherwise,
 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<EV_SELECT_IS_WINSOCKET> is enabled, then libev needs a way to map
 file descriptors to socket handles. When not defining this symbol (the
 default), then libev will call C<_get_osfhandle>, which is usually
 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<EV_SELECT_IS_WINSOCKET> 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<close> 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<poll>(2)
 backend. Otherwise it will be enabled on non-win32 platforms. It

Diff Legend

-–
+Removed lines
-+
+Added lines
-<
+Changed lines
->
+Changed lines

Comparing libev/ev.pod (file contents): Revision 1.260 by root, Sun Jul 19 21:18:03 2009 UTC vs. Revision 1.273 by root, Tue Nov 24 14:46:59 2009 UTC

Diff Legend

Comparing libev/ev.pod (file contents):
Revision 1.260 by root, Sun Jul 19 21:18:03 2009 UTC vs.
Revision 1.273 by root, Tue Nov 24 14:46:59 2009 UTC