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

Comparing libev/ev.pod (file contents):
Revision 1.164 by root, Sat May 31 23:22:23 2008 UTC vs.
Revision 1.181 by root, Fri Sep 19 03:47:50 2008 UTC

 writing a server, you should C<accept ()> in a loop to accept as many
 connections as possible during one iteration. You might also want to have
 a look at C<ev_set_io_collect_interval ()> to increase the amount of
 readiness notifications you get per iteration.
+This backend maps C<EV_READ> to the C<readfds> set and C<EV_WRITE> to the
+C<writefds> set (and to work around Microsoft Windows bugs, also onto the
+C<exceptfds> set on that platform).
 =item C<EVBACKEND_POLL>    (value 2, poll backend, available everywhere except on windows)
 And this is your standard poll(2) backend. It's more complicated
 than select, but handles sparse fds better and has no artificial
 limit on the number of fds you can use (except it will slow down
 considerably with a lot of inactive fds). It scales similarly to select,
 i.e. O(total_fds). See the entry for C<EVBACKEND_SELECT>, above, for
 performance tips.
+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)
 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
 keep at least one watcher active per fd at all times.
 While nominally embeddable in other event loops, this feature is broken in
 all kernel versions tested so far.
+This backend maps C<EV_READ> and C<EV_WRITE> in the same way as
+C<EVBACKEND_POLL>.
 =item C<EVBACKEND_KQUEUE>  (value 8, most BSD clones)
 Kqueue deserves special mention, as at the time of this writing, it
 was broken on all BSDs except NetBSD (usually it doesn't work reliably
 with anything but sockets and pipes, except on Darwin, where of course
 almost everywhere, you should only use it when you have a lot of sockets
 (for which it usually works), by embedding it into another event loop
 (e.g. C<EVBACKEND_SELECT> or C<EVBACKEND_POLL>) and using it only for
 sockets.
+This backend maps C<EV_READ> into an C<EVFILT_READ> kevent with
+C<NOTE_EOF>, and C<EV_WRITE> into an C<EVFILT_WRITE> kevent with
+C<NOTE_EOF>.
 =item C<EVBACKEND_DEVPOLL> (value 16, Solaris 8)
 This is not implemented yet (and might never be, unless you send me an
 implementation). According to reports, C</dev/poll> only supports sockets
 and is not embeddable, which would limit the usefulness of this backend
 might perform better.
 On the positive side, ignoring the spurious readiness notifications, this
 backend actually performed to specification in all tests and is fully
 embeddable, which is a rare feat among the OS-specific backends.
+This backend maps C<EV_READ> and C<EV_WRITE> in the same way as
+C<EVBACKEND_POLL>.
 =item C<EVBACKEND_ALL>
 Try all backends (even potentially broken ones that wouldn't be tried
 with C<EVFLAG_AUTO>). Since this is a mask, you can do stuff such as
 received events and started processing them. This timestamp does not
 change as long as callbacks are being processed, and this is also the base
 time used for relative timers. You can treat it as the timestamp of the
 event occurring (or more correctly, libev finding out about it).
+=item ev_now_update (loop)
+Establishes the current time by querying the kernel, updating the time
+returned by C<ev_now ()> in the progress. This is a costly operation and
+is usually done automatically within C<ev_loop ()>.
+This function is rarely useful, but when some event callback runs for a
+very long time without entering the event loop, updating libev's idea of
+the current time is a good idea.
+See also "The special problem of time updates" in the C<ev_timer> section.
 =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.
 Here are the gory details of what C<ev_loop> does:
    - Before the first iteration, call any pending watchers.
    * If EVFLAG_FORKCHECK was used, check for a fork.
-   - If a fork was detected, queue and call all fork watchers.
+   - If a fork was detected (by any means), queue and call all fork watchers.
    - Queue and call all prepare watchers.
-   - If we have been forked, recreate the kernel state.
+   - If we have been forked, detach and recreate the kernel state
+     as to not disturb the other process.
    - Update the kernel state with all outstanding changes.
-   - Update the "event loop time".
+   - Update the "event loop time" (ev_now ()).
    - Calculate for how long to sleep or block, if at all
      (active idle watchers, EVLOOP_NONBLOCK or not having
      any active watchers at all will result in not sleeping).
    - Sleep if the I/O and timer collect interval say so.
    - Block the process, waiting for any events.
    - Queue all outstanding I/O (fd) events.
-   - Update the "event loop time" and do time jump handling.
+   - Update the "event loop time" (ev_now ()), and do time jump adjustments.
    - Queue all outstanding timers.
    - Queue all outstanding periodics.
-   - If no events are pending now, queue all idle watchers.
+   - Unless any events are pending now, queue all idle watchers.
    - Queue all check watchers.
    - Call all queued watchers in reverse order (i.e. check watchers first).
      Signals and child watchers are implemented as I/O watchers, and will
      be handled here by queueing them when their watcher gets executed.
    - If ev_unloop has been called, or EVLOOP_ONESHOT or EVLOOP_NONBLOCK
 anymore.
    ... queue jobs here, make sure they register event watchers as long
    ... as they still have work to do (even an idle watcher will do..)
    ev_loop (my_loop, 0);
-   ... jobs done. yeah!
+   ... jobs done or somebody called unloop. yeah!
 =item ev_unloop (loop, how)
 Can be used to make a call to C<ev_loop> return early (but only after it
 has processed all outstanding events). The C<how> argument must be either
 =item ev_set_io_collect_interval (loop, ev_tstamp interval)
 =item ev_set_timeout_collect_interval (loop, ev_tstamp interval)
 These advanced functions influence the time that libev will spend waiting
-for events. Both are by default C<0>, meaning that libev will try to
+for events. Both time intervals are by default C<0>, meaning that libev
-invoke timer/periodic callbacks and I/O callbacks with minimum latency.
+will try to invoke timer/periodic callbacks and I/O callbacks with minimum
+latency.
 Setting these to a higher value (the C<interval> I<must> be >= C<0>)
-allows libev to delay invocation of I/O and timer/periodic callbacks to
+allows libev to delay invocation of I/O and timer/periodic callbacks
-increase efficiency of loop iterations.
+to increase efficiency of loop iterations (or to increase power-saving
+opportunities).
 The background is that sometimes your program runs just fast enough to
 handle one (or very few) event(s) per loop iteration. While this makes
 the program responsive, it also wastes a lot of CPU time to poll for new
 events, especially with backends like C<select ()> which have a high
 Many (busy) programs can usually benefit by setting the I/O collect
 interval to a value near C<0.1> or so, which is often enough for
 interactive servers (of course not for games), likewise for timeouts. It
 usually doesn't make much sense to set it to a lower value than C<0.01>,
 as this approaches the timing granularity of most systems.
+Setting the I<timeout collect interval> can improve the opportunity for
+saving power, as the program will "bundle" timer callback invocations that
+are "near" in time together, by delaying some, thus reducing the number of
+times the process sleeps and wakes up again. Another useful technique to
+reduce iterations/wake-ups is to use C<ev_periodic> watchers and make sure
+they fire on, say, one-second boundaries only.
 =item ev_loop_verify (loop)
 This function only does something when C<EV_VERIFY> support has been
 compiled in. It tries to go through all internal structures and checks
    {
      struct ev_io io;
      int otherfd;
      void *somedata;
      struct whatever *mostinteresting;
-   }
+   };
+   ...
+   struct my_io w;
+   ev_io_init (&w.io, my_cb, fd, EV_READ);
 And since your callback will be called with a pointer to the watcher, you
 can cast it back to your own type:
    static void my_cb (struct ev_loop *loop, struct ev_io *w_, int revents)
    }
 More interesting and less C-conformant ways of casting your callback type
 instead have been omitted.
-Another common scenario is having some data structure with multiple
+Another common scenario is to use some data structure with multiple
-watchers:
+embedded watchers:
    struct my_biggy
    {
      int some_data;
      ev_timer t1;
      ev_timer t2;
    }
-In this case getting the pointer to C<my_biggy> is a bit more complicated,
+In this case getting the pointer to C<my_biggy> is a bit more
-you need to use C<offsetof>:
+complicated: Either you store the address of your C<my_biggy> struct
+in the C<data> member of the watcher, or you need to use some pointer
+arithmetic using C<offsetof> inside your watchers:
    #include <stddef.h>
    static void
    t1_cb (EV_P_ struct ev_timer *w, int revents)
 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
+when writing to a pipe whose other end has been closed, your program gets
-gets send a SIGPIPE, which, by default, aborts your program. For most
+send a SIGPIPE, which, by default, aborts your program. For most programs
-programs this is sensible behaviour, for daemons, this is usually
+this is sensible behaviour, for daemons, this is usually undesirable.
-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).
 times out after an hour and you reset your system clock to January last
 year, it will still time out after (roughly) and hour. "Roughly" because
 detecting time jumps is hard, and some inaccuracies are unavoidable (the
 monotonic clock option helps a lot here).
+The callback is guaranteed to be invoked only after its timeout has passed,
+but if multiple timers become ready during the same loop iteration then
+order of execution is undefined.
+=head3 The special problem of time updates
+Establishing the current time is a costly operation (it usually takes at
+least two system calls): EV therefore updates its idea of the current
+time only before and after C<ev_loop> polls for new events, which causes
+a growing difference between C<ev_now ()> and C<ev_time ()> when handling
+lots of events.
 The relative timeouts are calculated relative to the C<ev_now ()>
 time. This is usually the right thing as this timestamp refers to the time
 of the event triggering whatever timeout you are modifying/starting. If
-you suspect event processing to be delayed and you I<need> to base the timeout
+you suspect event processing to be delayed and you I<need> to base the
-on the current time, use something like this to adjust for this:
+timeout on the current time, use something like this to adjust for this:
    ev_timer_set (&timer, after + ev_now () - ev_time (), 0.);
-The callback is guaranteed to be invoked only after its timeout has passed,
+If the event loop is suspended for a long time, you can also force an
-but if multiple timers become ready during the same loop iteration then
+update of the time returned by C<ev_now ()> by calling C<ev_now_update
-order of execution is undefined.
+()>.
 =head3 Watcher-Specific Functions and Data Members
 =over 4
 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 Stopping the Child Watcher
+Currently, the child watcher never gets stopped, even when the
+child terminates, so normally one needs to stop the watcher in the
+callback. Future versions of libev might stop the watcher automatically
+when a child exit is detected.
 =head3 Watcher-Specific Functions and Data Members
 =over 4
 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
+compilation environment, which means that on systems with large file
-disabled large file support, you get the 32 bit version of the stat
+support disabled by default, 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 noticeably with ev_stat and large file support.
+most noticeably disabled with ev_stat and large file support.
+The solution for this is to lobby your distribution maker to make large
+file interfaces available by default (as e.g. FreeBSD does) and not
+optional. Libev cannot simply switch on large file support because it has
+to exchange stat structures with application programs compiled using the
+default compilation environment.
 =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
 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
+It can be found and installed via CPAN, its homepage is at
 L<http://software.schmorp.de/pkg/EV>.
+=item Python
+Python bindings can be found at L<http://code.google.com/p/pyev/>. It
+seems to be quite complete and well-documented. Note, however, that the
+patch they require for libev is outright dangerous as it breaks the ABI
+for everybody else, and therefore, should never be applied in an installed
+libev (if python requires an incompatible ABI then it needs to embed
+libev).
 =item Ruby
 Tony Arcieri has written a ruby extension that offers access to a subset
 of the libev API and adds file handle abstractions, asynchronous DNS and
 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>.
+be found at L<http://proj.llucax.com.ar/wiki/evd>.
 =back
 =head1 MACRO MAGIC
 =head1 THREADS AND COROUTINES
 =head2 THREADS
-Libev itself is completely thread-safe, but it uses no locking. This
+Libev itself is thread-safe (unless the opposite is specifically
+documented for a function), but it uses no locking itself. This means that
-means that you can use as many loops as you want in parallel, as long as
+you can use as many loops as you want in parallel, as long as only one
-only one thread ever calls into one libev function with the same loop
+thread ever calls into one libev function with the same loop parameter:
-parameter.
+libev guarentees that different event loops share no data structures that
+need locking.
-Or put differently: calls with different loop parameters can be done in
+Or to put it differently: calls with different loop parameters can be done
-parallel from multiple threads, calls with the same loop parameter must be
+concurrently from multiple threads, calls with the same loop parameter
-done serially (but can be done from different threads, as long as only one
+must be done serially (but can be done from different threads, as long as
-thread ever is inside a call at any point in time, e.g. by using a mutex
+only one thread ever is inside a call at any point in time, e.g. by using
-per loop).
+a mutex per loop).
-If you want to know which design is best for your problem, then I cannot
+Specifically to support threads (and signal handlers), libev implements
-help you but by giving some generic advice:
+so-called C<ev_async> watchers, which allow some limited form of
+concurrency on the same event loop.
+If you want to know which design (one loop, locking, or multiple loops
+without or something else still) is best for your problem, then I cannot
+help you. I can give some generic advice however:
 =over 4
 =item * most applications have a main thread: use the default libev loop
 in that thread, or create a separate thread running only the default loop.
 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...).
+=item * some watcher types are only supported in the default loop - use
+C<ev_async> watchers to tell your other loops about any such events.
 =back
 =head2 COROUTINES
 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
+Care has been taken to ensure that libev does not keep local state inside
-state inside C<ev_loop>, and other calls do not usually allow coroutine
+C<ev_loop>, and other calls do not usually allow coroutine switches.
-switches.
 =head1 COMPLEXITIES
 In this section the complexities of (many of) the algorithms used inside
 more than a hundred or so sockets, then likely it needs to use a totally
 different implementation for windows, as libev offers the POSIX readiness
 notification model, which cannot be implemented efficiently on windows
 (Microsoft monopoly games).
+A typical way to use libev under windows is to embed it (see the embedding
+section for details) and use the following F<evwrap.h> header file instead
+of F<ev.h>:
+   #define EV_STANDALONE              /* keeps ev from requiring config.h */
+   #define EV_SELECT_IS_WINSOCKET 1   /* configure libev for windows select */
+   #include "ev.h"
+And compile the following F<evwrap.c> file into your project (make sure
+you do I<not> compile the F<ev.c> or any other embedded soruce files!):
+   #include "evwrap.h"
+   #include "ev.c"
 =over 4
 =item The winsocket select function
 The winsocket C<select> function doesn't follow POSIX in that it
 requires socket I<handles> and not socket I<file descriptors> (it is
 also extremely buggy). This makes select very inefficient, and also
-requires a mapping from file descriptors to socket handles. See the
+requires a mapping from file descriptors to socket handles (the Microsoft
+C runtime provides the function C<_open_osfhandle> for this). See the
 discussion of the C<EV_SELECT_USE_FD_SET>, C<EV_SELECT_IS_WINSOCKET> and
 C<EV_FD_TO_WIN32_HANDLE> preprocessor symbols for more info.
 The configuration for a "naked" win32 using the Microsoft runtime
 libraries and raw winsocket select is:
 In addition to a working ISO-C implementation, libev relies on a few
 additional extensions:
 =over 4
+=item C<void (*)(ev_watcher_type *, int revents)> must have compatible
+calling conventions regardless of C<ev_watcher_type *>.
+Libev assumes not only that all watcher pointers have the same internal
+structure (guaranteed by POSIX but not by ISO C for example), but it also
+assumes that the same (machine) code can be used to call any watcher
+callback: The watcher callbacks have different type signatures, but libev
+calls them using an C<ev_watcher *> internally.
 =item C<sig_atomic_t volatile> must be thread-atomic as well
 The type C<sig_atomic_t volatile> (or whatever is defined as
 C<EV_ATOMIC_T>) must be atomic w.r.t. accesses from different
 threads. This is not part of the specification for C<sig_atomic_t>, but is

Diff Legend

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

Comparing libev/ev.pod (file contents): Revision 1.164 by root, Sat May 31 23:22:23 2008 UTC vs. Revision 1.181 by root, Fri Sep 19 03:47:50 2008 UTC

Diff Legend

Comparing libev/ev.pod (file contents):
Revision 1.164 by root, Sat May 31 23:22:23 2008 UTC vs.
Revision 1.181 by root, Fri Sep 19 03:47:50 2008 UTC