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

Comparing libev/ev.pod (file contents):
Revision 1.199 by root, Thu Oct 23 07:18:21 2008 UTC vs.
Revision 1.204 by root, Mon Oct 27 11:08:29 2008 UTC

    // a single header file is required
    #include <ev.h>
    // every watcher type has its own typedef'd struct
-   // with the name ev_<type>
+   // with the name ev_TYPE
    ev_io stdin_watcher;
    ev_timer timeout_watcher;
    // all watcher callbacks have a similar signature
    // this callback is called when data is readable on stdin
 =back
 =head1 FUNCTIONS CONTROLLING THE EVENT LOOP
-An event loop is described by a C<ev_loop *>. The library knows two
+An event loop is described by a C<struct ev_loop *> (the C<struct>
-types of such loops, the I<default> loop, which supports signals and child
+is I<not> optional in this case, as there is also an C<ev_loop>
-events, and dynamically created loops which do not.
+I<function>).
+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.
 =over 4
 =item struct ev_loop *ev_default_loop (unsigned int flags)
 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 requiring a system call per fd change, no fork support and bad
 support for dup.
+Epoll is also notoriously buggy - embedding epoll fds should work, but
+of course doesn't, and epoll just loves to report events for totally
+I<different> file descriptors (even already closed ones) than registered
+in the set (especially on SMP systems). Libev tries to counter these
+spurious notifications by employing an additional generation counter and
+comparing that against the events to filter out spurious ones.
 While stopping, setting and starting an I/O watcher in the same iteration
 will result in some caching, there is still a system call per such incident
 (because the fd could point to a different file description now), so its
 best to avoid that. Also, C<dup ()>'ed file descriptors might not work
 very well if you register events for both fds.
-Please note that epoll sometimes generates spurious notifications, so you
-need to use non-blocking I/O or other means to avoid blocking when no data
-(or space) is available.
 Best performance from this backend is achieved by not unregistering all
 watchers for a file descriptor until it has been closed, if possible,
 i.e. keep at least one watcher active per fd at all times. Stopping and
 starting a watcher (without re-setting it) also usually doesn't cause
 responsibility to either stop all watchers cleanly yourself I<before>
 calling this function, or cope with the fact afterwards (which is usually
 the easiest thing, you can just ignore the watchers and/or C<free ()> them
 for example).
-Note that certain global state, such as signal state, will not be freed by
+Note that certain global state, such as signal state (and installed signal
-this function, and related watchers (such as signal and child watchers)
+handlers), will not be freed by this function, and related watchers (such
-would need to be stopped manually.
+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>).
 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. which is the default for non-minimal builds. It tries to go
+compiled in, which is the default for non-minimal builds. It tries to go
 through all internal structures and checks them for validity. If anything
 is found to be inconsistent, it will print an error message to standard
 error and call C<abort ()>.
 This can be used to catch bugs inside libev itself: under normal
 =back
 =head1 ANATOMY OF A WATCHER
+In the following description, uppercase C<TYPE> in names stands for the
+watcher type, e.g. C<ev_TYPE_start> can mean C<ev_timer_start> for timer
+watchers and C<ev_io_start> for I/O watchers.
 A watcher is a structure that you create and register to record your
 interest in some event. For instance, if you want to wait for STDIN to
 become readable, you would create an C<ev_io> watcher for that:
      ev_io_stop (w);
      ev_unloop (loop, EVUNLOOP_ALL);
    }
    struct ev_loop *loop = ev_default_loop (0);
    ev_io stdin_watcher;
    ev_init (&stdin_watcher, my_cb);
    ev_io_set (&stdin_watcher, STDIN_FILENO, EV_READ);
    ev_io_start (loop, &stdin_watcher);
    ev_loop (loop, 0);
 As you can see, you are responsible for allocating the memory for your
-watcher structures (and it is usually a bad idea to do this on the stack,
+watcher structures (and it is I<usually> a bad idea to do this on the
-although this can sometimes be quite valid).
+stack).
+Each watcher has an associated watcher structure (called C<struct ev_TYPE>
+or simply C<ev_TYPE>, as typedefs are provided for all watcher structs).
 Each watcher structure must be initialised by a call to C<ev_init
 (watcher *, callback)>, which expects a callback to be provided. This
 callback gets invoked each time the event occurs (or, in the case of I/O
 watchers, each time the event loop detects that the file descriptor given
 is readable and/or writable).
-Each watcher type has its own C<< ev_<type>_set (watcher *, ...) >> macro
+Each watcher type further has its own C<< ev_TYPE_set (watcher *, ...) >>
-with arguments specific to this watcher type. There is also a macro
+macro to configure it, with arguments specific to the watcher type. There
-to combine initialisation and setting in one call: C<< ev_<type>_init
+is also a macro to combine initialisation and setting in one call: C<<
-(watcher *, callback, ...) >>.
+ev_TYPE_init (watcher *, callback, ...) >>.
 To make the watcher actually watch out for events, you have to start it
-with a watcher-specific start function (C<< ev_<type>_start (loop, watcher
+with a watcher-specific start function (C<< ev_TYPE_start (loop, watcher
 *) >>), and you can stop watching for events at any time by calling the
-corresponding stop function (C<< ev_<type>_stop (loop, watcher *) >>.
+corresponding stop function (C<< ev_TYPE_stop (loop, watcher *) >>.
 As long as your watcher is active (has been started but not stopped) you
 must not touch the values stored in it. Most specifically you must never
-reinitialise it or call its C<set> macro.
+reinitialise it or call its C<ev_TYPE_set> macro.
 Each and every callback receives the event loop pointer as first, the
 registered watcher structure as second, and a bitset of received events as
 third argument.
 =back
 =head2 GENERIC WATCHER FUNCTIONS
-In the following description, C<TYPE> stands for the watcher type,
-e.g. C<timer> for C<ev_timer> watchers and C<io> for C<ev_io> watchers.
 =over 4
 =item C<ev_init> (ev_TYPE *watcher, callback)
 This macro initialises the generic portion of a watcher. The contents
 The default priority used by watchers when no priority has been set is
 always C<0>, which is supposed to not be too high and not be too low :).
 Setting a priority outside the range of C<EV_MINPRI> to C<EV_MAXPRI> is
 fine, as long as you do not mind that the priority value you query might
-or might not have been adjusted to be within valid range.
+or might not have been clamped to the valid range.
 =item ev_invoke (loop, ev_TYPE *watcher, int revents)
 Invoke the C<watcher> with the given C<loop> and C<revents>. Neither
 C<loop> nor C<revents> need to be valid as long as the watcher callback
 Changing the timeout is trivial as well (if it isn't hard-coded in the
 callback :) - just change the timeout and invoke the callback, which will
 fix things for you.
-=item 4. Whee, use a double-linked list for your timeouts.
+=item 4. Wee, just use a double-linked list for your timeouts.
-If there is not one request, but many thousands, all employing some kind
+If there is not one request, but many thousands (millions...), all
-of timeout with the same timeout value, then one can do even better:
+employing some kind of timeout with the same timeout value, then one can
+do even better:
 When starting the timeout, calculate the timeout value and put the timeout
 at the I<end> of the list.
 Then use an C<ev_timer> to fire when the timeout at the I<beginning> of
 complication, and having to use a constant timeout. The constant timeout
 ensures that the list stays sorted.
 =back
-So what method is the best?
+So which method the best?
-The method #2 is a simple no-brain-required solution that is adequate in
+Method #2 is a simple no-brain-required solution that is adequate in most
-most situations. Method #3 requires a bit more thinking, but handles many
+situations. Method #3 requires a bit more thinking, but handles many cases
-cases better, and isn't very complicated either. In most case, choosing
+better, and isn't very complicated either. In most case, choosing either
-either one is fine.
+one is fine, with #3 being better in typical situations.
 Method #1 is almost always a bad idea, and buys you nothing. Method #4 is
 rather complicated, but extremely efficient, something that really pays
-off after the first or so million of active timers, i.e. it's usually
+off after the first million or so of active timers, i.e. it's usually
 overkill :)
 =head3 The special problem of time updates
 Establishing the current time is a costly operation (it usually takes at
 =item D
 Leandro Lucarella has written a D language binding (F<ev.d>) for libev, to
 be found at L<http://proj.llucax.com.ar/wiki/evd>.
+=item Ocaml
+Erkki Seppala has written Ocaml bindings for libev, to be found at
+L<http://modeemi.cs.tut.fi/~flux/software/ocaml-ev/>.
 =back
 =head1 MACRO MAGIC

Diff Legend

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

Comparing libev/ev.pod (file contents): Revision 1.199 by root, Thu Oct 23 07:18:21 2008 UTC vs. Revision 1.204 by root, Mon Oct 27 11:08:29 2008 UTC

Diff Legend

Comparing libev/ev.pod (file contents):
Revision 1.199 by root, Thu Oct 23 07:18:21 2008 UTC vs.
Revision 1.204 by root, Mon Oct 27 11:08:29 2008 UTC