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

Comparing libev/ev.pod (file contents):
Revision 1.207 by root, Tue Oct 28 14:13:52 2008 UTC vs.
Revision 1.210 by root, Thu Oct 30 08:09:30 2008 UTC

 If you don't know what event loop to use, use the one returned from this
 function.
 Note that this function is I<not> thread-safe, so if you want to use it
 from multiple threads, you have to lock (note also that this is unlikely,
-as loops cannot bes hared easily between threads anyway).
+as loops cannot be shared easily between threads anyway).
 The default loop is the only loop that can handle C<ev_signal> and
 C<ev_child> watchers, and to do this, it always registers a handler
 for C<SIGCHLD>. If this is a problem for your application you can either
 create a dynamic loop with C<ev_loop_new> that doesn't do that, or you
 For few fds, this backend is a bit little slower than poll and select,
 but it scales phenomenally better. While poll and select usually scale
 like O(total_fds) where n is the total number of fds (or the highest fd),
 epoll scales either O(1) or O(active_fds).
-The epoll syscalls are the most misdesigned of the more advanced event
+The epoll mechanism deserves honorable mention as the most misdesigned
-mechanisms: problems include silently dropping fds, requiring a system
+of the more advanced event mechanisms: mere annoyances include silently
-call per change per fd (and unnecessary guessing of parameters), problems
+dropping file descriptors, requiring a system call per change per file
+descriptor (and unnecessary guessing of parameters), problems with dup and
-with dup and so on. The biggest issue is fork races, however - if a
+so on. The biggest issue is fork races, however - if a program forks then
-program forks then I<both> parent and child process have to recreate the
+I<both> parent and child process have to recreate the epoll set, which can
-epoll set, which can take considerable time (one syscall per fd) and is of
+take considerable time (one syscall per file descriptor) and is of course
-course hard to detect.
+hard to detect.
-Epoll is also notoriously buggy - embedding epoll fds should work, but
+Epoll is also notoriously buggy - embedding epoll fds I<should> work, but
-of course doesn't, and epoll just loves to report events for totally
+of course I<doesn't>, and epoll just loves to report events for totally
 I<different> file descriptors (even already closed ones, so one cannot
 even remove them from the set) than registered in the set (especially
 on SMP systems). Libev tries to counter these spurious notifications by
 employing an additional generation counter and comparing that against the
-events to filter out spurious ones.
+events to filter out spurious ones, recreating the set when required.
 While stopping, setting and starting an I/O watcher in the same iteration
-will result in some caching, there is still a system call per such incident
+will result in some caching, there is still a system call per such
-(because the fd could point to a different file description now), so its
+incident (because the same I<file descriptor> could point to a different
-best to avoid that. Also, C<dup ()>'ed file descriptors might not work
+I<file description> now), so its best to avoid that. Also, C<dup ()>'ed
-very well if you register events for both fds.
+file descriptors might not work very well if you register events for both
+file descriptors.
 Best performance from this backend is achieved by not unregistering all
 watchers for a file descriptor until it has been closed, if possible,
 i.e. keep at least one watcher active per fd at all times. Stopping and
 starting a watcher (without re-setting it) also usually doesn't cause
 This backend maps C<EV_READ> and C<EV_WRITE> in the same way as
 C<EVBACKEND_POLL>.
 =item C<EVBACKEND_KQUEUE>  (value 8, most BSD clones)
-Kqueue deserves special mention, as at the time of this writing, it was
+Kqueue deserves special mention, as at the time of this writing, it
-broken on all BSDs except NetBSD (usually it doesn't work reliably with
+was broken on all BSDs except NetBSD (usually it doesn't work reliably
-anything but sockets and pipes, except on Darwin, where of course it's
+with anything but sockets and pipes, except on Darwin, where of course
-completely useless). For this reason it's not being "auto-detected" unless
+it's completely useless). Unlike epoll, however, whose brokenness
-you explicitly specify it in the flags (i.e. using C<EVBACKEND_KQUEUE>) or
+is by design, these kqueue bugs can (and eventually will) be fixed
-libev was compiled on a known-to-be-good (-enough) system like NetBSD.
+without API changes to existing programs. For this reason it's not being
+"auto-detected" unless you explicitly specify it in the flags (i.e. using
+C<EVBACKEND_KQUEUE>) or libev was compiled on a known-to-be-good (-enough)
+system like NetBSD.
 You still can embed kqueue into a normal poll or select backend and use it
 only for sockets (after having made sure that sockets work with kqueue on
 the target platform). See C<ev_embed> watchers for more info.
 the loop.
 A flags value of C<EVLOOP_ONESHOT> will look for new events (waiting if
 necessary) and will handle those and any already outstanding ones. It
 will block your process until at least one new event arrives (which could
-be an event internal to libev itself, so there is no guarentee that a
+be an event internal to libev itself, so there is no guarantee that a
 user-registered callback will be called), and will return after one
 iteration of the loop.
 This is useful if you are waiting for some external event in conjunction
 with something not expressible using other libev watchers (i.e. "roll your
 to see if it changed somehow. You can specify a recommended polling
 interval for this case. If you specify a polling interval of C<0> (highly
 recommended!) then a I<suitable, unspecified default> value will be used
 (which you can expect to be around five seconds, although this might
 change dynamically). Libev will also impose a minimum interval which is
-currently around C<0.1>, but thats usually overkill.
+currently around C<0.1>, but that's usually overkill.
 This watcher type is not meant for massive numbers of stat watchers,
 as even with OS-supported change notifications, this can be
 resource-intensive.
 =over 4
 =item ev_async_init (ev_async *, callback)
 Initialises and configures the async watcher - it has no parameters of any
-kind. There is a C<ev_asynd_set> macro, but using it is utterly pointless,
+kind. There is a C<ev_async_set> macro, but using it is utterly pointless,
 trust me.
 =item ev_async_send (loop, ev_async *)
 Sends/signals/activates the given C<ev_async> watcher, that is, feeds
    #define EV_STANDALONE 1
    #include "ev.h"
 Both header files and implementation files can be compiled with a C++
-compiler (at least, thats a stated goal, and breakage will be treated
+compiler (at least, that's a stated goal, and breakage will be treated
 as a bug).
 You need the following files in your source tree, or in a directory
 in your include path (e.g. in libev/ when using -Ilibev):
 loop, as long as you don't confuse yourself). The only exception is that
 you must not do this from C<ev_periodic> reschedule callbacks.
 Care has been taken to ensure that libev does not keep local state inside
 C<ev_loop>, and other calls do not usually allow for coroutine switches as
-they do not clal any callbacks.
+they do not call any callbacks.
 =head2 COMPILER WARNINGS
 Depending on your compiler and compiler settings, you might get no or a
 lot of warnings when compiling libev code. Some people are apparently
    ==2274==    definitely lost: 0 bytes in 0 blocks.
    ==2274==      possibly lost: 0 bytes in 0 blocks.
    ==2274==    still reachable: 256 bytes in 1 blocks.
 Then there is no memory leak, just as memory accounted to global variables
-is not a memleak - the memory is still being refernced, and didn't leak.
+is not a memleak - the memory is still being referenced, and didn't leak.
 Similarly, under some circumstances, valgrind might report kernel bugs
 as if it were a bug in libev (e.g. in realloc or in the poll backend,
 although an acceptable workaround has been found here), or it might be
 confused.
 =back
 =head1 AUTHOR
-Marc Lehmann <libev@schmorp.de>.
+Marc Lehmann <libev@schmorp.de>, with repeated corrections by Mikael Magnusson.

Diff Legend

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

Comparing libev/ev.pod (file contents): Revision 1.207 by root, Tue Oct 28 14:13:52 2008 UTC vs. Revision 1.210 by root, Thu Oct 30 08:09:30 2008 UTC

Diff Legend

Comparing libev/ev.pod (file contents):
Revision 1.207 by root, Tue Oct 28 14:13:52 2008 UTC vs.
Revision 1.210 by root, Thu Oct 30 08:09:30 2008 UTC