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

Comparing libev/ev.pod (file contents):
Revision 1.311 by root, Thu Oct 21 14:40:07 2010 UTC vs.
Revision 1.315 by root, Fri Oct 22 09:33:14 2010 UTC

 =item ev_invoke_pending (loop)
 This call will simply invoke all pending watchers while resetting their
 pending state. Normally, C<ev_run> does this automatically when required,
-but when overriding the invoke callback this call comes handy.
+but when overriding the invoke callback this call comes handy. This
+function can be invoked from a watcher - this can be useful for example
+when you want to do some lengthy calculation and want to pass further
+event handling to another thread (you still have to make sure only one
+thread executes within C<ev_invoke_pending> or C<ev_run> of course).
 =item int ev_pending_count (loop)
 Returns the number of pending watchers - zero indicates that no watchers
 are pending.
 and call libev functions on it that are documented to work on active watchers.
 =item pending
 If a watcher is active and libev determines that an event it is interested
-in has occured (such as a timer expiring), it will become pending. It will
+in has occurred (such as a timer expiring), it will become pending. It will
 stay in this pending state until either it is stopped or its callback is
 about to be invoked, so it is not normally pending inside the watcher
 callback.
 The watcher might or might not be active while it is pending (for example,
 =head3 C<kqueue> is buggy
 The kqueue syscall is broken in all known versions - most versions support
 only sockets, many support pipes.
-Libev tries to work around this by not using C<kqueue> by default on
+Libev tries to work around this by not using C<kqueue> by default on this
-this rotten platform, but of course you can still ask for it when creating
+rotten platform, but of course you can still ask for it when creating a
-a loop.
+loop - embedding a socket-only kqueue loop into a select-based one is
+probably going to work well.
 =head3 C<poll> is buggy
 Instead of fixing C<kqueue>, Apple replaced their (working) C<poll>
 implementation by something calling C<kqueue> internally around the 10.5.6
 =head3 C<errno> reentrancy
 The default compile environment on Solaris is unfortunately so
 thread-unsafe that you can't even use components/libraries compiled
-without C<-D_REENTRANT> (as long as they use C<errno>), which, of course,
+without C<-D_REENTRANT> in a threaded program, which, of course, isn't
-isn't defined by default.
+defined by default. A valid, if stupid, implementation choice.
 If you want to use libev in threaded environments you have to make sure
 it's compiled with C<_REENTRANT> defined.
 =head3 Event port backend
-The scalable event interface for Solaris is called "event ports". Unfortunately,
+The scalable event interface for Solaris is called "event
-this mechanism is very buggy. If you run into high CPU usage, your program
+ports". Unfortunately, this mechanism is very buggy in all major
+releases. If you run into high CPU usage, your program freezes or you get
-freezes or you get a large number of spurious wakeups, make sure you have
+a large number of spurious wakeups, make sure you have all the relevant
-all the relevant and latest kernel patches applied. No, I don't know which
+and latest kernel patches applied. No, I don't know which ones, but there
-ones, but there are multiple ones.
+are multiple ones to apply, and afterwards, event ports actually work
+great.
 If you can't get it to work, you can try running the program by setting
 the environment variable C<LIBEV_FLAGS=3> to only allow C<poll> and
 C<select> backends.
 =head2 AIX POLL BUG
 AIX unfortunately has a broken C<poll.h> header. Libev works around
 this by trying to avoid the poll backend altogether (i.e. it's not even
 compiled in), which normally isn't a big problem as C<select> works fine
-with large bitsets, and AIX is dead anyway.
+with large bitsets on AIX, and AIX is dead anyway.
 =head2 WIN32 PLATFORM LIMITATIONS AND WORKAROUNDS
 =head3 General issues
 =over 4
 =item active
-A watcher is active as long as it has been started (has been attached to
+A watcher is active as long as it has been started and not yet stopped.
-an event loop) but not yet stopped (disassociated from the event loop).
+See L<WATCHER STATES> for details.
 =item application
 In this document, an application is whatever is using libev.
 The address of a function that is called when some event has been
 detected. Callbacks are being passed the event loop, the watcher that
 received the event, and the actual event bitset.
-=item callback invocation
+=item callback/watcher invocation
 The act of calling the callback associated with a watcher.
 =item event
 The model used to describe how an event loop handles and processes
 watchers and events.
 =item pending
-A watcher is pending as soon as the corresponding event has been detected,
+A watcher is pending as soon as the corresponding event has been
-and stops being pending as soon as the watcher will be invoked or its
+detected. See L<WATCHER STATES> for details.
-pending status is explicitly cleared by the application.
-A watcher can be pending, but not active. Stopping a watcher also clears
-its pending status.
 =item real time
 The physical time that is observed. It is apparently strictly monotonic :)
 =item watcher
 A data structure that describes interest in certain events. Watchers need
 to be started (attached to an event loop) before they can receive events.
-=item watcher invocation
-The act of calling the callback associated with a watcher.
 =back
 =head1 AUTHOR
 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.311 by root, Thu Oct 21 14:40:07 2010 UTC vs. Revision 1.315 by root, Fri Oct 22 09:33:14 2010 UTC

Diff Legend

Comparing libev/ev.pod (file contents):
Revision 1.311 by root, Thu Oct 21 14:40:07 2010 UTC vs.
Revision 1.315 by root, Fri Oct 22 09:33:14 2010 UTC