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

Comparing libev/ev.pod (file contents):
Revision 1.239 by root, Tue Apr 21 14:14:19 2009 UTC vs.
Revision 1.243 by root, Sat Jun 20 20:22:35 2009 UTC

    #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
 year, it will still time out after (roughly) one 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 I<after> its timeout has
-passed. If multiple timers become ready during the same loop iteration
+passed (not I<at>, so on systems with very low-resolution clocks this
-then the ones with earlier time-out values are invoked before ones with
+might introduce a small delay). If multiple timers become ready during the
+same loop iteration then the ones with earlier time-out values are invoked
-later time-out values (but this is no longer true when a callback calls
+before ones with later time-out values (but this is no longer true when a
-C<ev_loop> recursively).
+callback calls C<ev_loop> recursively).
 =head3 Be smart about timeouts
 Many real-world problems involve some kind of timeout, usually for error
 recovery. A typical example is an HTTP request - if the other side hangs,
 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:
      // 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)
        {
 way (note also that glib is the slowest event library known to man).
 There is no supported compilation method available on windows except
 embedding it into other applications.
+Sensible signal handling is officially unsupported by Microsoft - libev
+tries its best, but under most conditions, signals will simply not work.
 Not a libev limitation but worth mentioning: windows apparently doesn't
 accept large writes: instead of resulting in a partial write, windows will
 either accept everything or return C<ENOBUFS> if the buffer is too large,
 so make sure you only write small amounts into your sockets (less than a
 megabyte seems safe, but this apparently depends on the amount of memory
 the abysmal performance of winsockets, using a large number of sockets
 is not recommended (and not reasonable). If your program needs to use
 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).
+(due to 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>:
 Early versions of winsocket's select only supported waiting for a maximum
 of C<64> handles (probably owning to the fact that all windows kernels
 can only wait for C<64> things at the same time internally; Microsoft
 recommends spawning a chain of threads and wait for 63 handles and the
-previous thread in each. Great).
+previous thread in each. Sounds great!).
 Newer versions support more handles, but you need to define C<FD_SETSIZE>
 to some high number (e.g. C<2048>) before compiling the winsocket select
-call (which might be in libev or elsewhere, for example, perl does its own
+call (which might be in libev or elsewhere, for example, perl and many
-select emulation on windows).
+other interpreters do their own select emulation on windows).
 Another limit is the number of file descriptors in the Microsoft runtime
-libraries, which by default is C<64> (there must be a hidden I<64> fetish
+libraries, which by default is C<64> (there must be a hidden I<64>
-or something like this inside Microsoft). You can increase this by calling
+fetish or something like this inside Microsoft). You can increase this
-C<_setmaxstdio>, which can increase this limit to C<2048> (another
+by calling C<_setmaxstdio>, which can increase this limit to C<2048>
-arbitrary limit), but is broken in many versions of the Microsoft runtime
+(another arbitrary limit), but is broken in many versions of the Microsoft
-libraries.
-This might get you to about C<512> or C<2048> sockets (depending on
+runtime libraries. This might get you to about C<512> or C<2048> sockets
-windows version and/or the phase of the moon). To get more, you need to
+(depending on windows version and/or the phase of the moon). To get more,
-wrap all I/O functions and provide your own fd management, but the cost of
+you need to wrap all I/O functions and provide your own fd management, but
-calling select (O(n²)) will likely make this unworkable.
+the cost of calling select (O(n²)) will likely make this unworkable.
 =back
 =head2 PORTABILITY REQUIREMENTS

Diff Legend

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

Comparing libev/ev.pod (file contents): Revision 1.239 by root, Tue Apr 21 14:14:19 2009 UTC vs. Revision 1.243 by root, Sat Jun 20 20:22:35 2009 UTC

Diff Legend

Comparing libev/ev.pod (file contents):
Revision 1.239 by root, Tue Apr 21 14:14:19 2009 UTC vs.
Revision 1.243 by root, Sat Jun 20 20:22:35 2009 UTC