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

Comparing libev/ev.pod (file contents):
Revision 1.139 by root, Wed Apr 2 05:51:40 2008 UTC vs.
Revision 1.144 by root, Mon Apr 7 12:33:29 2008 UTC

 An event loop is described by a C<struct ev_loop *>. The library knows two
 types of such loops, the I<default> loop, which supports signals and child
 events, and dynamically created loops which do not.
-If you use threads, a common model is to run the default event loop
-in your main thread (or in a separate thread) and for each thread you
-create, you also create another event loop. Libev itself does no locking
-whatsoever, so if you mix calls to the same event loop in different
-threads, make sure you lock (this is usually a bad idea, though, even if
-done correctly, because it's hideous and inefficient).
 =over 4
 =item struct ev_loop *ev_default_loop (unsigned int flags)
 This will initialise the default event loop if it hasn't been initialised
 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
 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
   #include "ev_cpp.h"
   #include "ev.c"
+=head1 THREADS AND COROUTINES
+=head2 THREADS
+Libev itself is completely threadsafe, but it uses no locking. This
+means that you can use as many loops as you want in parallel, as long as
+only one thread ever calls into one libev function with the same loop
+parameter.
+Or put differently: calls with different loop parameters can be done in
+parallel from multiple threads, calls with the same loop parameter must be
+done serially (but can be done from different threads, as long as only one
+thread ever is inside a call at any point in time, e.g. by using a mutex
+per loop).
+If you want to know which design is best for your problem, then I cannot
+help you but by giving some generic advice:
+=over 4
+=item * most applications have a main thread: use the default libev loop
+in that thread, or create a seperate thread running only the default loop.
+This helps integrating other libraries or software modules that use libev
+themselves and don't care/know about threading.
+=item * one loop per thread is usually a good model.
+Doing this is almost never wrong, sometimes a better-performance model
+exists, but it is always a good start.
+=item * other models exist, such as the leader/follower pattern, where one
+loop is handed through multiple threads in a kind of round-robbin fashion.
+Chosing a model is hard - look around, learn, know that usually you cna do
+better than you currently do :-)
+=item * often you need to talk to some other thread which blocks in the
+event loop - C<ev_async> watchers can be used to wake them up from other
+threads safely (or from signal contexts...).
+=back
+=head2 COROUTINES
+Libev is much more accomodating to coroutines ("cooperative threads"):
+libev fully supports nesting calls to it's functions from different
+coroutines (e.g. you can call C<ev_loop> on the same loop from two
+different coroutines and switch freely between both coroutines running the
+loop, as long as you don't confuse yourself). The only exception is that
+you must not do this from C<ev_periodic> reschedule callbacks.
+Care has been invested into making sure that libev does not keep local
+state inside C<ev_loop>, and other calls do not usually allow coroutine
+switches.
 =head1 COMPLEXITIES
 In this section the complexities of (many of) the algorithms used inside
 libev will be explained. For complexity discussions about backends see the
 documentation for C<ev_default_init>.

Diff Legend

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

Comparing libev/ev.pod (file contents): Revision 1.139 by root, Wed Apr 2 05:51:40 2008 UTC vs. Revision 1.144 by root, Mon Apr 7 12:33:29 2008 UTC

Diff Legend

Comparing libev/ev.pod (file contents):
Revision 1.139 by root, Wed Apr 2 05:51:40 2008 UTC vs.
Revision 1.144 by root, Mon Apr 7 12:33:29 2008 UTC