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

Comparing libev/ev.pod (file contents):
Revision 1.312 by root, Thu Oct 21 15:14:49 2010 UTC vs.
Revision 1.319 by root, Fri Oct 22 10:09:12 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 interetsing 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
    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.
 =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.312 by root, Thu Oct 21 15:14:49 2010 UTC vs. Revision 1.319 by root, Fri Oct 22 10:09:12 2010 UTC

Diff Legend

Comparing libev/ev.pod (file contents):
Revision 1.312 by root, Thu Oct 21 15:14:49 2010 UTC vs.
Revision 1.319 by root, Fri Oct 22 10:09:12 2010 UTC