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

Comparing libev/ev.pod (file contents):
Revision 1.374 by sf-exg, Sat Jun 4 16:54:59 2011 UTC vs.
Revision 1.375 by root, Mon Jun 13 09:52:36 2011 UTC

 among the OS-specific backends (I vastly prefer correctness over speed
 hacks).
 On the negative side, the interface is I<bizarre> - so bizarre that
 even sun itself gets it wrong in their code examples: The event polling
-function sometimes returning events to the caller even though an error
+function sometimes returns events to the caller even though an error
 occurred, but with no indication whether it has done so or not (yes, it's
-even documented that way) - deadly for edge-triggered interfaces where
+even documented that way) - deadly for edge-triggered interfaces where you
-you absolutely have to know whether an event occurred or not because you
+absolutely have to know whether an event occurred or not because you have
-have to re-arm the watcher.
+to re-arm the watcher.
 Fortunately libev seems to be able to work around these idiocies.
 This backend maps C<EV_READ> and C<EV_WRITE> in the same way as
 C<EVBACKEND_POLL>.
 keep up with the timer (because it takes longer than those 10 seconds to
 do stuff) the timer will not fire more than once per event loop iteration.
 =item ev_timer_again (loop, ev_timer *)
-This will act as if the timer timed out and restart it again if it is
+This will act as if the timer timed out and restarts it again if it is
 repeating. The exact semantics are:
 If the timer is pending, its pending status is cleared.
 If the timer is started but non-repeating, stop it (as if it timed out).
 C<ev_async_sent> calls). In fact, you could use signal watchers as a kind
 of "global async watchers" by using a watcher on an otherwise unused
 signal, and C<ev_feed_signal> to signal this watcher from another thread,
 even without knowing which loop owns the signal.
-Unlike C<ev_signal> watchers, C<ev_async> works with any event loop, not
-just the default loop.
 =head3 Queueing
 C<ev_async> does not support queueing of data in any way. The reason
 is that the author does not know of a simple (or any) algorithm for a
 multiple-writer-single-reader queue that works in all cases and doesn't
 Unlike C<ev_feed_event>, this call is safe to do from other threads,
 signal or similar contexts (see the discussion of C<EV_ATOMIC_T> in the
 embedding section below on what exactly this means).
 Note that, as with other watchers in libev, multiple events might get
-compressed into a single callback invocation (another way to look at this
+compressed into a single callback invocation (another way to look at
-is that C<ev_async> watchers are level-triggered, set on C<ev_async_send>,
+this is that C<ev_async> watchers are level-triggered: they are set on
-reset when the event loop detects that).
+C<ev_async_send>, reset when the event loop detects that).
-This call incurs the overhead of a system call only once per event loop
+This call incurs the overhead of at most one extra system call per event
-iteration, so while the overhead might be noticeable, it doesn't apply to
+loop iteration, if the event loop is blocked, and no syscall at all if
-repeated calls to C<ev_async_send> for the same event loop.
+the event loop (or your program) is processing events. That means that
+repeated calls are basically free (there is no need to avoid calls for
+performance reasons) and that the overhead becomes smaller (typically
+zero) under load.
 =item bool = ev_async_pending (ev_async *)
 Returns a non-zero value when C<ev_async_send> has been called on the
 watcher but the event has not yet been processed (or even noted) by the
 indicate GNU/Linux + Glibc 2.4 or newer, otherwise disabled.
 =item EV_ATOMIC_T
 Libev requires an integer type (suitable for storing C<0> or C<1>) whose
-access is atomic with respect to other threads or signal contexts. No such
+access is atomic and serialised with respect to other threads or signal
-type is easily found in the C language, so you can provide your own type
+contexts. No such type is easily found in the C language, so you can
-that you know is safe for your purposes. It is used both for signal handler "locking"
+provide your own type that you know is safe for your purposes. It is used
-as well as for signal and thread safety in C<ev_async> watchers.
+both for signal handler "locking" as well as for signal and thread safety
+in C<ev_async> watchers.
 In the absence of this define, libev will use C<sig_atomic_t volatile>
 (from F<signal.h>), which is usually good enough on most platforms.
 =item EV_H (h)
 =item Processing ev_async_send: O(number_of_async_watchers)
 =item Processing signals: O(max_signal_number)
 Sending involves a system call I<iff> there were no other C<ev_async_send>
-calls in the current loop iteration. Checking for async and signal events
+calls in the current loop iteration and the loop is currently
+blocked. Checking for async and signal events involves iterating over all
-involves iterating over all running async watchers or all signal numbers.
+running async watchers or all signal numbers.
 =back
 =head1 PORTING FROM LIBEV 3.X TO 4.X

Diff Legend

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

Comparing libev/ev.pod (file contents): Revision 1.374 by sf-exg, Sat Jun 4 16:54:59 2011 UTC vs. Revision 1.375 by root, Mon Jun 13 09:52:36 2011 UTC

Diff Legend

Comparing libev/ev.pod (file contents):
Revision 1.374 by sf-exg, Sat Jun 4 16:54:59 2011 UTC vs.
Revision 1.375 by root, Mon Jun 13 09:52:36 2011 UTC