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

Comparing libev/ev.pod (file contents):
Revision 1.237 by root, Thu Apr 16 07:58:03 2009 UTC vs.
Revision 1.241 by root, Sat Apr 25 14:23:26 2009 UTC

 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)
 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,
 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.237 by root, Thu Apr 16 07:58:03 2009 UTC vs. Revision 1.241 by root, Sat Apr 25 14:23:26 2009 UTC

Diff Legend

Comparing libev/ev.pod (file contents):
Revision 1.237 by root, Thu Apr 16 07:58:03 2009 UTC vs.
Revision 1.241 by root, Sat Apr 25 14:23:26 2009 UTC