--- libev/ev.pod 2008/10/23 07:18:21 1.199 +++ libev/ev.pod 2008/10/24 08:30:01 1.202 @@ -12,7 +12,7 @@ #include // every watcher type has its own typedef'd struct - // with the name ev_ + // with the name ev_TYPE ev_io stdin_watcher; ev_timer timeout_watcher; @@ -278,9 +278,13 @@ =head1 FUNCTIONS CONTROLLING THE EVENT LOOP -An event loop is described by a C. The library knows two -types of such loops, the I loop, which supports signals and child -events, and dynamically created loops which do not. +An event loop is described by a C (the C +is I optional in this case, as there is also an C +I). + +The library knows two types of such loops, the I loop, which +supports signals and child events, and dynamically created loops which do +not. =over 4 @@ -770,7 +774,7 @@ =item ev_loop_verify (loop) This function only does something when C 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. @@ -784,6 +788,10 @@ =head1 ANATOMY OF A WATCHER +In the following description, uppercase C in names stands for the +watcher type, e.g. C can mean C for timer +watchers and C 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 watcher for that: @@ -795,15 +803,21 @@ } 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, -although this can sometimes be quite valid). +watcher structures (and it is I a bad idea to do this on the +stack). + +Each watcher has an associated watcher structure (called C +or simply C, as typedefs are provided for all watcher structs). Each watcher structure must be initialised by a call to C, which expects a callback to be provided. This @@ -811,19 +825,19 @@ 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__set (watcher *, ...) >> macro -with arguments specific to this watcher type. There is also a macro -to combine initialisation and setting in one call: C<< ev__init -(watcher *, callback, ...) >>. +Each watcher type further has its own C<< ev_TYPE_set (watcher *, ...) >> +macro to configure it, with arguments specific to the watcher type. There +is also a macro to combine initialisation and setting in one call: C<< +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__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__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 macro. +reinitialise it or call its C 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 @@ -914,9 +928,6 @@ =head2 GENERIC WATCHER FUNCTIONS -In the following description, C stands for the watcher type, -e.g. C for C watchers and C for C watchers. - =over 4 =item C (ev_TYPE *watcher, callback) @@ -1034,7 +1045,7 @@ Setting a priority outside the range of C to C 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) @@ -1428,10 +1439,11 @@ 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 -of timeout with the same timeout value, then one can do even better: +If there is not one request, but many thousands (millions...), all +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 of the list. @@ -1450,16 +1462,16 @@ =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 -most situations. Method #3 requires a bit more thinking, but handles many -cases better, and isn't very complicated either. In most case, choosing -either one is fine. +Method #2 is a simple no-brain-required solution that is adequate in most +situations. Method #3 requires a bit more thinking, but handles many cases +better, and isn't very complicated either. In most case, choosing either +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 @@ -2948,6 +2960,11 @@ Leandro Lucarella has written a D language binding (F) for libev, to be found at L. +=item Ocaml + +Erkki Seppala has written Ocaml bindings for libev, to be found at +L. + =back