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

Comparing libev/ev.pod (file contents):
Revision 1.241 by root, Sat Apr 25 14:23:26 2009 UTC vs.
Revision 1.245 by root, Tue Jun 30 06:24:38 2009 UTC

 By setting a higher I<io collect interval> you allow libev to spend more
 time collecting I/O events, so you can handle more events per iteration,
 at the cost of increasing latency. Timeouts (both C<ev_periodic> and
 C<ev_timer>) will be not affected. Setting this to a non-null value will
-introduce an additional C<ev_sleep ()> call into most loop iterations.
+introduce an additional C<ev_sleep ()> call into most loop iterations. The
+sleep time ensures that libev will not poll for I/O events more often then
+once per this interval, on average.
 Likewise, by setting a higher I<timeout collect interval> you allow libev
 to spend more time collecting timeouts, at the expense of increased
 latency/jitter/inexactness (the watcher callback will be called
 later). C<ev_io> watchers will not be affected. Setting this to a non-null
 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.
+as this approaches the timing granularity of most systems. Note that if
+you do transactions with the outside world and you can't increase the
+parallelity, then this setting will limit your transaction rate (if you
+need to poll once per transaction and the I/O collect interval is 0.01,
+then you can't do more than 100 transations per second).
 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.
+Example: we only need 0.1s timeout granularity, and we wish not to poll
+more often than 100 times per second:
+   ev_set_timeout_collect_interval (EV_DEFAULT_UC_ 0.1);
+   ev_set_io_collect_interval (EV_DEFAULT_UC_ 0.01);
 =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
    #include <stddef.h>
    static void
    t1_cb (EV_P_ ev_timer *w, int revents)
    {
-     struct my_biggy big = (struct my_biggy *
+     struct my_biggy big = (struct my_biggy *)
        (((char *)w) - offsetof (struct my_biggy, t1));
    }
    static void
    t2_cb (EV_P_ ev_timer *w, int revents)
    {
-     struct my_biggy big = (struct my_biggy *
+     struct my_biggy big = (struct my_biggy *)
        (((char *)w) - offsetof (struct my_biggy, t2));
    }
 =head2 WATCHER PRIORITY MODELS
      // with the default priority are receiving events.
      ev_idle_start (EV_A_ &idle);
    }
    static void
-   idle-cb (EV_P_ ev_idle *w, int revents)
+   idle_cb (EV_P_ ev_idle *w, int revents)
    {
      // actual processing
      read (STDIN_FILENO, ...);
      // have to start the I/O watcher again, as
 C<after> argument to C<ev_timer_set>, and only ever use the C<repeat>
 member and C<ev_timer_again>.
 At start:
-   ev_timer_init (timer, callback);
+   ev_init (timer, callback);
    timer->repeat = 60.;
    ev_timer_again (loop, timer);
 Each time there is some activity:
 To start the timer, simply initialise the watcher and set C<last_activity>
 to the current time (meaning we just have some activity :), then call the
 callback, which will "do the right thing" and start the timer:
-   ev_timer_init (timer, callback);
+   ev_init (timer, callback);
    last_activity = ev_now (loop);
    callback (loop, timer, EV_TIMEOUT);
 And when there is some activity, simply store the current time in
 C<last_activity>, no libev calls at all:
 some child status changes (most typically when a child of yours dies or
 exits). 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), i.e.,
 forking and then immediately registering a watcher for the child is fine,
-but forking and registering a watcher a few event loop iterations later is
+but forking and registering a watcher a few event loop iterations later or
-not.
+in the next callback invocation is not.
 Only the default event loop is capable of handling signals, and therefore
 you can only register child watchers in the default event loop.
 =head3 Process Interaction
      // no longer anything immediate to do.
    }
    ev_idle *idle_watcher = malloc (sizeof (ev_idle));
    ev_idle_init (idle_watcher, idle_cb);
-   ev_idle_start (loop, idle_cb);
+   ev_idle_start (loop, idle_watcher);
 =head2 C<ev_prepare> and C<ev_check> - customise your event loop!
 Prepare and check watchers are usually (but not always) used in pairs:
      struct pollfd fds [nfd];
      // actual code will need to loop here and realloc etc.
      adns_beforepoll (ads, fds, &nfd, &timeout, timeval_from (ev_time ()));
      /* the callback is illegal, but won't be called as we stop during check */
-     ev_timer_init (&tw, 0, timeout * 1e-3);
+     ev_timer_init (&tw, 0, timeout * 1e-3, 0.);
      ev_timer_start (loop, &tw);
      // create one ev_io per pollfd
      for (int i = 0; i < nfd; ++i)
        {

Diff Legend

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

Comparing libev/ev.pod (file contents): Revision 1.241 by root, Sat Apr 25 14:23:26 2009 UTC vs. Revision 1.245 by root, Tue Jun 30 06:24:38 2009 UTC

Diff Legend

Comparing libev/ev.pod (file contents):
Revision 1.241 by root, Sat Apr 25 14:23:26 2009 UTC vs.
Revision 1.245 by root, Tue Jun 30 06:24:38 2009 UTC