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

Comparing libev/ev.pod (file contents):
Revision 1.136 by root, Thu Mar 13 13:06:16 2008 UTC vs.
Revision 1.143 by root, Sun Apr 6 14:34:52 2008 UTC

 flags. If that is troubling you, check C<ev_backend ()> afterwards).
 If you don't know what event loop to use, use the one returned from this
 function.
+Note that this function is I<not> thread-safe, so if you want to use it
+from multiple threads, you have to lock (note also that this is unlikely,
+as loops cannot bes hared easily between threads anyway).
 The default loop is the only loop that can handle C<ev_signal> and
 C<ev_child> watchers, and to do this, it always registers a handler
 for C<SIGCHLD>. If this is a problem for your app you can either
 create a dynamic loop with C<ev_loop_new> that doesn't do that, or you
 can simply overwrite the C<SIGCHLD> signal handler I<after> calling
 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). The epoll design has a number
 of shortcomings, such as silently dropping events in some hard-to-detect
-cases and rewiring a syscall per fd change, no fork support and bad
+cases and requiring a syscall per fd change, no fork support and bad
 support for dup.
 While stopping, setting and starting an I/O watcher in the same iteration
 will result in some caching, there is still a syscall per such incident
 (because the fd could point to a different file description now), so its
 Similar to C<ev_default_loop>, but always creates a new event loop that is
 always distinct from the default loop. Unlike the default loop, it cannot
 handle signal and child watchers, and attempts to do so will be greeted by
 undefined behaviour (or a failed assertion if assertions are enabled).
+Note that this function I<is> thread-safe, and the recommended way to use
+libev with threads is indeed to create one loop per thread, and using the
+default loop in the "main" or "initial" thread.
 Example: Try to create a event loop that uses epoll and nothing else.
   struct ev_loop *epoller = ev_loop_new (EVBACKEND_EPOLL | EVFLAG_NOENV);
   if (!epoller)
 To support fork in your programs, you either have to call
 C<ev_default_fork ()> or C<ev_loop_fork ()> after a fork in the child,
 enable C<EVFLAG_FORKCHECK>, or resort to C<EVBACKEND_SELECT> or
 C<EVBACKEND_POLL>.
+=head3 The special problem of SIGPIPE
+While not really specific to libev, it is easy to forget about SIGPIPE:
+when reading from a pipe whose other end has been closed, your program
+gets send a SIGPIPE, which, by default, aborts your program. For most
+programs this is sensible behaviour, for daemons, this is usually
+undesirable.
+So when you encounter spurious, unexplained daemon exits, make sure you
+ignore SIGPIPE (and maybe make sure you log the exit status of your daemon
+somewhere, as that would have given you a big clue).
 =head3 Watcher-Specific Functions
 =over 4
 reader). Inotify will be used to give hints only and should not change the
 semantics of C<ev_stat> watchers, which means that libev sometimes needs
 to fall back to regular polling again even with inotify, but changes are
 usually detected immediately, and if the file exists there will be no
 polling.
+=head3 ABI Issues (Largefile Support)
+Libev by default (unless the user overrides this) uses the default
+compilation environment, which means that on systems with optionally
+disabled large file support, you get the 32 bit version of the stat
+structure. When using the library from programs that change the ABI to
+use 64 bit file offsets the programs will fail. In that case you have to
+compile libev with the same flags to get binary compatibility. This is
+obviously the case with any flags that change the ABI, but the problem is
+most noticably with ev_stat and largefile support.
 =head3 Inotify
 When C<inotify (7)> support has been compiled into libev (generally only
 available on Linux) and present at runtime, it will be used to speed up
 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<ev_async_send>.
+=item bool = ev_async_pending (ev_async *)
+Returns a non-zero value when C<ev_async_send> has been called on the
+watcher but the event has not yet been processed (or even noted) by the
+event loop.
+C<ev_async_send> sets a flag in the watcher and wakes up the loop. When
+the loop iterates next and checks for the watcher to have become active,
+it will reset the flag again. C<ev_async_pending> can be used to very
+quickly check wether invoking the loop might be a good idea.
+Not that this does I<not> check wether the watcher itself is pending, only
+wether it has been requested to make this watcher pending.
 =back
 =head1 OTHER FUNCTIONS
 =item C<EV_DEFAULT>, C<EV_DEFAULT_>
 Similar to the other two macros, this gives you the value of the default
 loop, if multiple loops are supported ("ev loop default").
+=item C<EV_DEFAULT_UC>, C<EV_DEFAULT_UC_>
+Usage identical to C<EV_DEFAULT> and C<EV_DEFAULT_>, but requires that the
+default loop has been initialised (C<UC> == unchecked). Their behaviour
+is undefined when the default loop has not been initialised by a previous
+execution of C<EV_DEFAULT>, C<EV_DEFAULT_> or C<ev_default_init (...)>.
+It is often prudent to use C<EV_DEFAULT> when initialising the first
+watcher in a function but use C<EV_DEFAULT_UC> afterwards.
 =back
 Example: Declare and initialise a check watcher, utilising the above
 macros so it will work regardless of whether multiple loops are supported
 or not.
   libev.m4
 =head2 PREPROCESSOR SYMBOLS/MACROS
-Libev can be configured via a variety of preprocessor symbols you have to define
+Libev can be configured via a variety of preprocessor symbols you have to
-before including any of its files. The default is not to build for multiplicity
+define before including any of its files. The default in the absense of
-and only include the select backend.
+autoconf is noted for every option.
 =over 4
 =item EV_STANDALONE
 =item EV_USE_NANOSLEEP
 If defined to be C<1>, libev will assume that C<nanosleep ()> is available
 and will use it for delays. Otherwise it will use C<select ()>.
+=item EV_USE_EVENTFD
+If defined to be C<1>, then libev will assume that C<eventfd ()> is
+available and will probe for kernel support at runtime. This will improve
+C<ev_signal> and C<ev_async> performance and reduce resource consumption.
+If undefined, it will be enabled if the headers indicate GNU/Linux + Glibc
+2.7 or newer, otherwise disabled.
 =item EV_USE_SELECT
 If undefined or defined to be C<1>, libev will compile in support for the
 C<select>(2) backend. No attempt at autodetection will be done: if no
 other method takes over, select will be it. Otherwise the select backend
 =item EV_USE_EPOLL
 If defined to be C<1>, libev will compile in support for the Linux
 C<epoll>(7) backend. Its availability will be detected at runtime,
-otherwise another method will be used as fallback. This is the
+otherwise another method will be used as fallback. This is the preferred
-preferred backend for GNU/Linux systems.
+backend for GNU/Linux systems. If undefined, it will be enabled if the
+headers indicate GNU/Linux + Glibc 2.4 or newer, otherwise disabled.
 =item EV_USE_KQUEUE
 If defined to be C<1>, libev will compile in support for the BSD style
 C<kqueue>(2) backend. Its actual availability will be detected at runtime,
 =item EV_USE_INOTIFY
 If defined to be C<1>, libev will compile in support for the Linux inotify
 interface to speed up C<ev_stat> watchers. Its actual availability will
-be detected at runtime.
+be detected at runtime. If undefined, it will be enabled if the headers
+indicate GNU/Linux + Glibc 2.4 or newer, otherwise disabled.
 =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

Diff Legend

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

Comparing libev/ev.pod (file contents): Revision 1.136 by root, Thu Mar 13 13:06:16 2008 UTC vs. Revision 1.143 by root, Sun Apr 6 14:34:52 2008 UTC

Diff Legend

Comparing libev/ev.pod (file contents):
Revision 1.136 by root, Thu Mar 13 13:06:16 2008 UTC vs.
Revision 1.143 by root, Sun Apr 6 14:34:52 2008 UTC