[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.321 by sf-exg, Fri Oct 22 10:50:24 2010 UTC

 this argument.
 =head2 TIME REPRESENTATION
 Libev represents time as a single floating point number, representing
-the (fractional) number of seconds since the (POSIX) epoch (in practise
+the (fractional) number of seconds since the (POSIX) epoch (in practice
 somewhere near the beginning of 1970, details are complicated, don't
 ask). This type is called C<ev_tstamp>, which is what you should use
 too. It usually aliases to the C<double> type in C. When you need to do
 any calculations on it, you should treat it as some floating point value.
 =item ev_tstamp ev_time ()
 Returns the current time as libev would use it. Please note that the
 C<ev_now> function is usually faster and also often returns the timestamp
-you actually want to know.
+you actually want to know. Also interesting is the combination of
+C<ev_update_now> and C<ev_now>.
 =item ev_sleep (ev_tstamp interval)
 Sleep for the given interval: The current thread will be blocked until
 either it is interrupted or the given time interval has passed. Basically
 as this indicates an incompatible change. Minor versions are usually
 compatible to older versions, so a larger minor version alone is usually
 not a problem.
 Example: Make sure we haven't accidentally been linked against the wrong
-version (note, however, that this will not detect ABI mismatches :).
+version (note, however, that this will not detect other ABI mismatches,
+such as LFS or reentrancy).
    assert (("libev version mismatch",
             ev_version_major () == EV_VERSION_MAJOR
             && ev_version_minor () >= EV_VERSION_MINOR));
    assert (("sorry, no epoll, no sex",
             ev_supported_backends () & EVBACKEND_EPOLL));
 =item unsigned int ev_recommended_backends ()
-Return the set of all backends compiled into this binary of libev and also
+Return the set of all backends compiled into this binary of libev and
-recommended for this platform. This set is often smaller than the one
+also recommended for this platform, meaning it will work for most file
+descriptor types. This set is often smaller than the one returned by
-returned by C<ev_supported_backends>, as for example kqueue is broken on
+C<ev_supported_backends>, as for example kqueue is broken on most BSDs
-most BSDs and will not be auto-detected unless you explicitly request it
+and will not be auto-detected unless you explicitly request it (assuming
-(assuming you know what you are doing). This is the set of backends that
+you know what you are doing). This is the set of backends that libev will
-libev will probe for if you specify no backends explicitly.
+probe for if you specify no backends explicitly.
 =item unsigned int ev_embeddable_backends ()
 Returns the set of backends that are embeddable in other event loops. This
-is the theoretical, all-platform, value. To find which backends
+value is platform-specific but can include backends not available on the
-might be supported on the current system, you would need to look at
+current system. To find which embeddable backends might be supported on
-C<ev_embeddable_backends () & ev_supported_backends ()>, likewise for
+the current system, you would need to look at C<ev_embeddable_backends ()
-recommended ones.
+& ev_supported_backends ()>, likewise for recommended ones.
 See the description of C<ev_embed> watchers for more info.
 =item ev_set_allocator (void *(*cb)(void *ptr, long size)) [NOT REENTRANT]
 =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.
+=item backend
+The part of the code dealing with the operating system interfaces.
 =item callback
 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.321 by sf-exg, Fri Oct 22 10:50:24 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.321 by sf-exg, Fri Oct 22 10:50:24 2010 UTC