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

Comparing libev/ev.pod (file contents):
Revision 1.235 by root, Thu Apr 16 07:50:39 2009 UTC vs.
Revision 1.242 by root, Thu Jun 18 18:16:54 2009 UTC

      // unloop was called, so exit
      return 0;
    }
-=head1 DESCRIPTION
+=head1 ABOUT THIS DOCUMENT
+This document documents the libev software package.
 The newest version of this document is also available as an html-formatted
 web page you might find easier to navigate when reading it for the first
 time: L<http://pod.tst.eu/http://cvs.schmorp.de/libev/ev.pod>.
+While this document tries to be as complete as possible in documenting
+libev, its usage and the rationale behind its design, it is not a tutorial
+on event-based programming, nor will it introduce event-based programming
+with libev.
+Familarity with event based programming techniques in general is assumed
+throughout this document.
+=head1 ABOUT LIBEV
 Libev is an event loop: you register interest in certain events (such as a
 file descriptor being readable or a timeout occurring), and it will manage
 these event sources and provide your program with events.
 name C<loop> (which is always of type C<ev_loop *>) will not have
 this argument.
 =head2 TIME REPRESENTATION
-Libev represents time as a single floating point number, representing the
+Libev represents time as a single floating point number, representing
-(fractional) number of seconds since the (POSIX) epoch (somewhere near
+the (fractional) number of seconds since the (POSIX) epoch (somewhere
-the beginning of 1970, details are complicated, don't ask). This type is
+near the beginning of 1970, details are complicated, don't ask). This
-called C<ev_tstamp>, which is what you should use too. It usually aliases
+type is called C<ev_tstamp>, which is what you should use too. It usually
-to the C<double> type in C, and when you need to do any calculations on
+aliases to the C<double> type in C. When you need to do any calculations
-it, you should treat it as some floating point value. Unlike the name
+on it, you should treat it as some floating point value. Unlike the name
 component C<stamp> might indicate, it is also used for time differences
 throughout libev.
 =head1 ERROR HANDLING
 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.
+See also L<The special problem of time updates> in the C<ev_timer> section.
 =item ev_suspend (loop)
 =item ev_resume (loop)
    #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
 descriptors to non-blocking mode is also usually a good idea (but not
 required if you know what you are doing).
 If you cannot use non-blocking mode, then force the use of a
 known-to-be-good backend (at the time of this writing, this includes only
-C<EVBACKEND_SELECT> and C<EVBACKEND_POLL>).
+C<EVBACKEND_SELECT> and C<EVBACKEND_POLL>). The same applies to file
+descriptors for which non-blocking operation makes no sense (such as
+files) - libev doesn't guarentee any specific behaviour in that case.
 Another thing you have to watch out for is that it is quite easy to
 receive "spurious" readiness notifications, that is your callback might
 be called with C<EV_READ> but a subsequent C<read>(2) will actually block
 because there is no data. Not only are some backends known to create a
 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,
      // 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:
 event loop blocks next and before C<ev_check> watchers are being called,
 and only in the child after the fork. If whoever good citizen calling
 C<ev_default_fork> cheats and calls it in the wrong process, the fork
 handlers will be invoked, too, of course.
+=head3 The special problem of life after fork - how is it possible?
+Most uses of C<fork()> consist of forking, then some simple calls to ste
+up/change the process environment, followed by a call to C<exec()>. This
+sequence should be handled by libev without any problems.
+This changes when the application actually wants to do event handling
+in the child, or both parent in child, in effect "continuing" after the
+fork.
+The default mode of operation (for libev, with application help to detect
+forks) is to duplicate all the state in the child, as would be expected
+when I<either> the parent I<or> the child process continues.
+When both processes want to continue using libev, then this is usually the
+wrong result. In that case, usually one process (typically the parent) is
+supposed to continue with all watchers in place as before, while the other
+process typically wants to start fresh, i.e. without any active watchers.
+The cleanest and most efficient way to achieve that with libev is to
+simply create a new event loop, which of course will be "empty", and
+use that for new watchers. This has the advantage of not touching more
+memory than necessary, and thus avoiding the copy-on-write, and the
+disadvantage of having to use multiple event loops (which do not support
+signal watchers).
+When this is not possible, or you want to use the default loop for
+other reasons, then in the process that wants to start "fresh", call
+C<ev_default_destroy ()> followed by C<ev_default_loop (...)>. Destroying
+the default loop will "orphan" (not stop) all registered watchers, so you
+have to be careful not to execute code that modifies those watchers. Note
+also that in that case, you have to re-register any signal watchers.
 =head3 Watcher-Specific Functions and Data Members
 =over 4
 =item ev_fork_init (ev_signal *, callback)
 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.235 by root, Thu Apr 16 07:50:39 2009 UTC vs. Revision 1.242 by root, Thu Jun 18 18:16:54 2009 UTC

Diff Legend

Comparing libev/ev.pod (file contents):
Revision 1.235 by root, Thu Apr 16 07:50:39 2009 UTC vs.
Revision 1.242 by root, Thu Jun 18 18:16:54 2009 UTC