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

Comparing libev/ev.pod (file contents):
Revision 1.172 by root, Wed Aug 6 07:01:25 2008 UTC vs.
Revision 1.178 by root, Sat Sep 13 18:25:50 2008 UTC

 Returns the current "event loop time", which is the time the event loop
 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
    {
      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

Diff Legend

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

Comparing libev/ev.pod (file contents): Revision 1.172 by root, Wed Aug 6 07:01:25 2008 UTC vs. Revision 1.178 by root, Sat Sep 13 18:25:50 2008 UTC

Diff Legend

Comparing libev/ev.pod (file contents):
Revision 1.172 by root, Wed Aug 6 07:01:25 2008 UTC vs.
Revision 1.178 by root, Sat Sep 13 18:25:50 2008 UTC