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

Comparing libev/ev.pod (file contents):
Revision 1.132 by root, Wed Feb 20 17:45:29 2008 UTC vs.
Revision 1.144 by root, Mon Apr 7 12:33:29 2008 UTC

   #include <ev.h>
 =head2 EXAMPLE PROGRAM
+  // a single header file is required
   #include <ev.h>
+  // every watcher type has its own typedef'd struct
+  // with the name ev_<type>
   ev_io stdin_watcher;
   ev_timer timeout_watcher;
+  // all watcher callbacks have a similar signature
-  /* called when data readable on stdin */
+  // this callback is called when data is readable on stdin
   static void
   stdin_cb (EV_P_ struct ev_io *w, int revents)
   {
-    /* puts ("stdin ready"); */
+    puts ("stdin ready");
-    ev_io_stop (EV_A_ w); /* just a syntax example */
+    // for one-shot events, one must manually stop the watcher
-    ev_unloop (EV_A_ EVUNLOOP_ALL); /* leave all loop calls */
+    // with its corresponding stop function.
+    ev_io_stop (EV_A_ w);
+    // this causes all nested ev_loop's to stop iterating
+    ev_unloop (EV_A_ EVUNLOOP_ALL);
   }
+  // another callback, this time for a time-out
   static void
   timeout_cb (EV_P_ struct ev_timer *w, int revents)
   {
-    /* puts ("timeout"); */
+    puts ("timeout");
-    ev_unloop (EV_A_ EVUNLOOP_ONE); /* leave one loop call */
+    // this causes the innermost ev_loop to stop iterating
+    ev_unloop (EV_A_ EVUNLOOP_ONE);
   }
   int
   main (void)
   {
+    // use the default event loop unless you have special needs
     struct ev_loop *loop = ev_default_loop (0);
-    /* initialise an io watcher, then start it */
+    // initialise an io watcher, then start it
+    // this one will watch for stdin to become readable
     ev_io_init (&stdin_watcher, stdin_cb, /*STDIN_FILENO*/ 0, EV_READ);
     ev_io_start (loop, &stdin_watcher);
+    // initialise a timer watcher, then start it
-    /* simple non-repeating 5.5 second timeout */
+    // simple non-repeating 5.5 second timeout
     ev_timer_init (&timeout_watcher, timeout_cb, 5.5, 0.);
     ev_timer_start (loop, &timeout_watcher);
-    /* loop till timeout or data ready */
+    // now wait for events to arrive
     ev_loop (loop, 0);
+    // unloop was called, so exit
     return 0;
   }
 =head1 DESCRIPTION
-The newest version of this document is also available as a html-formatted
+The newest version of this document is also available as an html-formatted
 web page you might find easier to navigate when reading it for the first
 time: L<http://cvs.schmorp.de/libev/ev.html>.
 Libev is an event loop: you register interest in certain events (such as a
 file descriptor being readable or a timeout occurring), and it will manage
 L<benchmark|http://libev.schmorp.de/bench.html> comparing it to libevent
 for example).
 =head2 CONVENTIONS
-Libev is very configurable. In this manual the default configuration will
+Libev is very configurable. In this manual the default (and most common)
-be described, which supports multiple event loops. For more info about
+configuration will be described, which supports multiple event loops. For
-various configuration options please have a look at B<EMBED> section in
+more info about various configuration options please have a look at
-this manual. If libev was configured without support for multiple event
+B<EMBED> section in this manual. If libev was configured without support
-loops, then all functions taking an initial argument of name C<loop>
+for multiple event loops, then all functions taking an initial argument of
-(which is always of type C<struct ev_loop *>) will not have this argument.
+name C<loop> (which is always of type C<struct ev_loop *>) will not have
+this argument.
 =head2 TIME REPRESENTATION
 Libev represents time as a single floating point number, representing the
 (fractional) number of seconds since the (POSIX) epoch (somewhere near
 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
 false. If it already was initialised it simply returns it (and ignores the
 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
 enabling this flag.
 This works by calling C<getpid ()> on every iteration of the loop,
 and thus this might slow down your event loop if you do a lot of loop
 iterations and little real work, but is usually not noticeable (on my
-Linux system for example, C<getpid> is actually a simple 5-insn sequence
+GNU/Linux system for example, C<getpid> is actually a simple 5-insn sequence
-without a syscall and thus I<very> fast, but my Linux system also has
+without a syscall and thus I<very> fast, but my GNU/Linux system also has
 C<pthread_atfork> which is even faster).
 The big advantage of this flag is that you can forget about fork (and
 forget about forgetting to tell libev about forking) when you use this
 flag.
 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
 with the kernel (thus it coexists with your own signal handlers as long
 as you don't register any with libev). Similarly, when the last signal
 watcher for a signal is stopped libev will reset the signal handler to
 SIG_DFL (regardless of what it was set to before).
+If possible and supported, libev will install its handlers with
+C<SA_RESTART> behaviour enabled, so syscalls should not be unduly
+interrupted. If you have a problem with syscalls 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 Watcher-Specific Functions and Data Members
 =over 4
 =item ev_signal_init (ev_signal *, callback, int signum)
 =head2 C<ev_child> - watch out for process status changes
 Child watchers trigger when your process receives a SIGCHLD in response to
-some child status changes (most typically when a child of yours dies).
+some child status changes (most typically when a child of yours dies). It
+is permissible to install a child watcher I<after> the child has been
+forked (which implies it might have already exited), as long as the event
+loop isn't entered (or is continued from a watcher).
+Only the default event loop is capable of handling signals, and therefore
+you can only rgeister child watchers in the default event loop.
+=head3 Process Interaction
+Libev grabs C<SIGCHLD> as soon as the default event loop is
+initialised. This is necessary to guarantee proper behaviour even if
+the first child watcher is started after the child exits. The occurance
+of C<SIGCHLD> is recorded asynchronously, but child reaping is done
+synchronously as part of the event loop processing. Libev always reaps all
+children, even ones not watched.
+=head3 Overriding the Built-In Processing
+Libev offers no special support for overriding the built-in child
+processing, but if your application collides with libev's default child
+handler, you can override it easily by installing your own handler for
+C<SIGCHLD> after initialising the default loop, and making sure the
+default loop never gets destroyed. You are encouraged, however, to use an
+event-based approach to child reaping and thus use libev's support for
+that, so other libev users can use C<ev_child> watchers freely.
 =head3 Watcher-Specific Functions and Data Members
 =over 4
 The process exit/trace status caused by C<rpid> (see your systems
 C<waitpid> and C<sys/wait.h> documentation for details).
 =back
+=head3 Examples
+Example: C<fork()> a new process and install a child handler to wait for
+its completion.
+  ev_child cw;
+  static void
+  child_cb (EV_P_ struct ev_child *w, int revents)
+  {
+    ev_child_stop (EV_A_ w);
+    printf ("process %d exited with status %x\n", w->rpid, w->rstatus);
+  }
+  pid_t pid = fork ();
+  if (pid < 0)
+    // error
+  else if (pid == 0)
+    {
+      // the forked child executes here
+      exit (1);
+    }
+  else
+    {
+      ev_child_init (&cw, child_cb, pid, 0);
+      ev_child_start (EV_DEFAULT_ &cw);
+    }
 =head2 C<ev_stat> - did the file attributes just change?
 This watches a filesystem path for attribute changes. That is, it calls
 C<stat> regularly (or when the OS says it changed) and sees if it changed
 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
    {
      sometype data;
      // no locking etc.
      queue_put (data);
-     ev_async_send (DEFAULT_ &mysig);
+     ev_async_send (EV_DEFAULT_ &mysig);
    }
    static void
    mysig_cb (EV_P_ ev_async *w, int revents)
    {
      // only need to lock the actual queueing operation
      pthread_mutex_lock (&mymutex);
      queue_put (data);
      pthread_mutex_unlock (&mymutex);
-     ev_async_send (DEFAULT_ &mysig);
+     ev_async_send (EV_DEFAULT_ &mysig);
    }
    static void
    mysig_cb (EV_P_ ev_async *w, int revents)
    {
 section below on what exactly this means).
 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
       io.start (fd, ev::READ);
     }
   };
+=head1 OTHER LANGUAGE BINDINGS
+Libev does not offer other language bindings itself, but bindings for a
+numbe rof languages exist in the form of third-party packages. If you know
+any interesting language binding in addition to the ones listed here, drop
+me a note.
+=over 4
+=item Perl
+The EV module implements the full libev API and is actually used to test
+libev. EV is developed together with libev. Apart from the EV core module,
+there are additional modules that implement libev-compatible interfaces
+to C<libadns> (C<EV::ADNS>), C<Net::SNMP> (C<Net::SNMP::EV>) and the
+C<libglib> event core (C<Glib::EV> and C<EV::Glib>).
+It can be found and installed via CPAN, its homepage is found at
+L<http://software.schmorp.de/pkg/EV>.
+=item Ruby
+Tony Arcieri has written a ruby extension that offers access to a subset
+of the libev API and adds filehandle abstractions, asynchronous DNS and
+more on top of it. It can be found via gem servers. Its homepage is at
+L<http://rev.rubyforge.org/>.
+=item D
+Leandro Lucarella has written a D language binding (F<ev.d>) for libev, to
+be found at L<http://git.llucax.com.ar/?p=software/ev.d.git;a=summary>.
+=back
 =head1 MACRO MAGIC
 Libev can be compiled with a variety of options, the most fundamantal
 of which is C<EV_MULTIPLICITY>. This option determines whether (most)
 functions and callbacks have an initial C<struct ev_loop *> argument.
 =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
   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.132 by root, Wed Feb 20 17:45:29 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.132 by root, Wed Feb 20 17:45:29 2008 UTC vs.
Revision 1.144 by root, Mon Apr 7 12:33:29 2008 UTC