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

Comparing libev/ev.pod (file contents):
Revision 1.189 by root, Tue Sep 30 19:33:33 2008 UTC vs.
Revision 1.197 by root, Tue Oct 21 20:52:30 2008 UTC

 C<EVUNLOOP_ONE>, which will make the innermost C<ev_loop> call return, or
 C<EVUNLOOP_ALL>, which will make all nested C<ev_loop> calls return.
 This "unloop state" will be cleared when entering C<ev_loop> again.
+It is safe to call C<ev_unloop> from otuside any C<ev_loop> calls.
 =item ev_ref (loop)
 =item ev_unref (loop)
 Ref/unref can be used to add or remove a reference count on the event
 =item C<EV_ERROR>
 An unspecified error has occurred, the watcher has been stopped. This might
 happen because the watcher could not be properly started because libev
 ran out of memory, a file descriptor was found to be closed or any other
+problem. Libev considers these application bugs.
-problem. You best act on it by reporting the problem and somehow coping
+You best act on it by reporting the problem and somehow coping with the
-with the watcher being stopped.
+watcher being stopped. Note that well-written programs should not receive
+an error ever, so when your watcher receives it, this usually indicates a
+bug in your program.
 Libev will usually signal a few "dummy" events together with an error, for
 example it might indicate that a fd is readable or writable, and if your
 callbacks is well-written it can just attempt the operation and cope with
 the error from read() or write(). This will not work in multi-threaded
    ev_io_start (EV_DEFAULT_UC, &w);
 =item C<ev_TYPE_stop> (loop *, ev_TYPE *watcher)
-Stops the given watcher again (if active) and clears the pending
+Stops the given watcher if active, and clears the pending status (whether
+the watcher was active or not).
-status. It is possible that stopped watchers are pending (for example,
+It is possible that stopped watchers are pending - for example,
-non-repeating timers are being stopped when they become pending), but
+non-repeating timers are being stopped when they become pending - but
-C<ev_TYPE_stop> ensures that the watcher is neither active nor pending. If
+calling C<ev_TYPE_stop> ensures that the watcher is neither active nor
-you want to free or reuse the memory used by the watcher it is therefore a
+pending. If you want to free or reuse the memory used by the watcher it is
-good idea to always call its C<ev_TYPE_stop> function.
+therefore a good idea to always call its C<ev_TYPE_stop> function.
 =item bool ev_is_active (ev_TYPE *watcher)
 Returns a true value iff the watcher is active (i.e. it has been started
 and not yet been stopped). As long as a watcher is active you must not modify
 to exchange stat structures with application programs compiled using the
 default compilation environment.
 =head3 Inotify and Kqueue
-When C<inotify (7)> support has been compiled into libev (generally only
+When C<inotify (7)> support has been compiled into libev (generally
+only available with Linux 2.6.25 or above due to bugs in earlier
-available with Linux) and present at runtime, it will be used to speed up
+implementations) and present at runtime, it will be used to speed up
-change detection where possible. The inotify descriptor will be created lazily
+change detection where possible. The inotify descriptor will be created
-when the first C<ev_stat> watcher is being started.
+lazily when the first C<ev_stat> watcher is being started.
 Inotify presence does not change the semantics of C<ev_stat> watchers
 except that changes might be detected earlier, and in some cases, to avoid
 making regular C<stat> calls. Even in the presence of inotify support
 there are many cases where libev has to resort to regular C<stat> polling,
 =over 4
 =item queueing from a signal handler context
 To implement race-free queueing, you simply add to the queue in the signal
-handler but you block the signal handler in the watcher callback. Here is an example that does that for
+handler but you block the signal handler in the watcher callback. Here is
-some fictitious SIGUSR1 handler:
+an example that does that for some fictitious SIGUSR1 handler:
    static ev_async mysig;
    static void
    sigusr1_handler (void)
 =over 4
 =item ev_once (loop, int fd, int events, ev_tstamp timeout, callback)
 This function combines a simple timer and an I/O watcher, calls your
-callback on whichever event happens first and automatically stop both
+callback on whichever event happens first and automatically stops both
 watchers. This is useful if you want to wait for a single event on an fd
 or timeout without having to allocate/configure/start/stop/free one or
 more watchers yourself.
-If C<fd> is less than 0, then no I/O watcher will be started and events
+If C<fd> is less than 0, then no I/O watcher will be started and the
-is being ignored. Otherwise, an C<ev_io> watcher for the given C<fd> and
+C<events> argument is being ignored. Otherwise, an C<ev_io> watcher for
-C<events> set will be created and started.
+the given C<fd> and C<events> set will be created and started.
 If C<timeout> is less than 0, then no timeout watcher will be
 started. Otherwise an C<ev_timer> watcher with after = C<timeout> (and
-repeat = 0) will be started. While C<0> is a valid timeout, it is of
+repeat = 0) will be started. C<0> is a valid timeout.
-dubious value.
 The callback has the type C<void (*cb)(int revents, void *arg)> and gets
 passed an C<revents> set like normal event callbacks (a combination of
 C<EV_ERROR>, C<EV_READ>, C<EV_WRITE> or C<EV_TIMEOUT>) and the C<arg>
-value passed to C<ev_once>:
+value passed to C<ev_once>. Note that it is possible to receive I<both>
+a timeout and an io event at the same time - you probably should give io
+events precedence.
+Example: wait up to ten seconds for data to appear on STDIN_FILENO.
    static void stdin_ready (int revents, void *arg)
    {
+     if (revents & EV_READ)
+       /* stdin might have data for us, joy! */;
-     if (revents & EV_TIMEOUT)
+     else if (revents & EV_TIMEOUT)
        /* doh, nothing entered */;
-     else if (revents & EV_READ)
-       /* stdin might have data for us, joy! */;
    }
    ev_once (STDIN_FILENO, EV_READ, 10., stdin_ready, 0);
 =item ev_feed_event (ev_loop *, watcher *, int revents)
 =head2 THREADS AND COROUTINES
 =head3 THREADS
 All libev functions are reentrant and thread-safe unless explicitly
-documented otherwise, but it uses no locking itself. This means that you
+documented otherwise, but libev implements no locking itself. This means
-can use as many loops as you want in parallel, as long as there are no
+that you can use as many loops as you want in parallel, as long as there
-concurrent calls into any libev function with the same loop parameter
+are no concurrent calls into any libev function with the same loop
-(C<ev_default_*> calls have an implicit default loop parameter, of
+parameter (C<ev_default_*> calls have an implicit default loop parameter,
-course): libev guarantees that different event loops share no data
+of course): libev guarantees that different event loops share no data
 structures that need any locking.
 Or to put it differently: calls with different loop parameters can be done
 concurrently from multiple threads, calls with the same loop parameter
 must be done serially (but can be done from different threads, as long as
 =back
 =head3 COROUTINES
-Libev is much more accommodating to coroutines ("cooperative threads"):
+Libev is very accommodating to coroutines ("cooperative threads"):
-libev fully supports nesting calls to it's functions from different
+libev fully supports nesting calls to its functions from different
 coroutines (e.g. you can call C<ev_loop> on the same loop from two
-different coroutines and switch freely between both coroutines running the
+different coroutines, and switch freely between both coroutines running the
 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 coroutine switches.
+C<ev_loop>, and other calls do not usually allow for coroutine switches as
+they do not clal 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
 with any compiler warnings enabled unless you are prepared to cope with
 them (e.g. by ignoring them). Remember that warnings are just that:
 warnings, not errors, or proof of bugs.
-=head1 VALGRIND
+=head2 VALGRIND
 Valgrind has a special section here because it is a popular tool that is
 highly useful. Unfortunately, valgrind reports are very hard to interpret.
 If you think you found a bug (memory leak, uninitialised data access etc.)
 If you need, for some reason, empty reports from valgrind for your project
 I suggest using suppression lists.
-=head1 COMPLEXITIES
-In this section the complexities of (many of) the algorithms used inside
-libev will be explained. For complexity discussions about backends see the
-documentation for C<ev_default_init>.
-All of the following are about amortised time: If an array needs to be
-extended, libev needs to realloc and move the whole array, but this
-happens asymptotically never with higher number of elements, so O(1) might
-mean it might do a lengthy realloc operation in rare cases, but on average
-it is much faster and asymptotically approaches constant time.
-=over 4
-=item Starting and stopping timer/periodic watchers: O(log skipped_other_timers)
-This means that, when you have a watcher that triggers in one hour and
-there are 100 watchers that would trigger before that then inserting will
-have to skip roughly seven (C<ld 100>) of these watchers.
-=item Changing timer/periodic watchers (by autorepeat or calling again): O(log skipped_other_timers)
-That means that changing a timer costs less than removing/adding them
-as only the relative motion in the event queue has to be paid for.
-=item Starting io/check/prepare/idle/signal/child/fork/async watchers: O(1)
-These just add the watcher into an array or at the head of a list.
-=item Stopping check/prepare/idle/fork/async watchers: O(1)
-=item Stopping an io/signal/child watcher: O(number_of_watchers_for_this_(fd/signal/pid % EV_PID_HASHSIZE))
-These watchers are stored in lists then need to be walked to find the
-correct watcher to remove. The lists are usually short (you don't usually
-have many watchers waiting for the same fd or signal).
-=item Finding the next timer in each loop iteration: O(1)
-By virtue of using a binary or 4-heap, the next timer is always found at a
-fixed position in the storage array.
-=item Each change on a file descriptor per loop iteration: O(number_of_watchers_for_this_fd)
-A change means an I/O watcher gets started or stopped, which requires
-libev to recalculate its status (and possibly tell the kernel, depending
-on backend and whether C<ev_io_set> was used).
-=item Activating one watcher (putting it into the pending state): O(1)
-=item Priority handling: O(number_of_priorities)
-Priorities are implemented by allocating some space for each
-priority. When doing priority-based operations, libev usually has to
-linearly search all the priorities, but starting/stopping and activating
-watchers becomes O(1) with respect to priority handling.
-=item Sending an ev_async: O(1)
-=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
-involves iterating over all running async watchers or all signal numbers.
-=back
-=head1 PORTABILITY
+=head1 PORTABILITY NOTES
 =head2 WIN32 PLATFORM LIMITATIONS AND WORKAROUNDS
 Win32 doesn't support any of the standards (e.g. POSIX) that libev
 requires, and its I/O model is fundamentally incompatible with the POSIX
 =back
 If you know of other additional requirements drop me a note.
+=head1 ALGORITHMIC COMPLEXITIES
+In this section the complexities of (many of) the algorithms used inside
+libev will be documented. For complexity discussions about backends see
+the documentation for C<ev_default_init>.
+All of the following are about amortised time: If an array needs to be
+extended, libev needs to realloc and move the whole array, but this
+happens asymptotically rarer with higher number of elements, so O(1) might
+mean that libev does a lengthy realloc operation in rare cases, but on
+average it is much faster and asymptotically approaches constant time.
+=over 4
+=item Starting and stopping timer/periodic watchers: O(log skipped_other_timers)
+This means that, when you have a watcher that triggers in one hour and
+there are 100 watchers that would trigger before that, then inserting will
+have to skip roughly seven (C<ld 100>) of these watchers.
+=item Changing timer/periodic watchers (by autorepeat or calling again): O(log skipped_other_timers)
+That means that changing a timer costs less than removing/adding them,
+as only the relative motion in the event queue has to be paid for.
+=item Starting io/check/prepare/idle/signal/child/fork/async watchers: O(1)
+These just add the watcher into an array or at the head of a list.
+=item Stopping check/prepare/idle/fork/async watchers: O(1)
+=item Stopping an io/signal/child watcher: O(number_of_watchers_for_this_(fd/signal/pid % EV_PID_HASHSIZE))
+These watchers are stored in lists, so they need to be walked to find the
+correct watcher to remove. The lists are usually short (you don't usually
+have many watchers waiting for the same fd or signal: one is typical, two
+is rare).
+=item Finding the next timer in each loop iteration: O(1)
+By virtue of using a binary or 4-heap, the next timer is always found at a
+fixed position in the storage array.
+=item Each change on a file descriptor per loop iteration: O(number_of_watchers_for_this_fd)
+A change means an I/O watcher gets started or stopped, which requires
+libev to recalculate its status (and possibly tell the kernel, depending
+on backend and whether C<ev_io_set> was used).
+=item Activating one watcher (putting it into the pending state): O(1)
+=item Priority handling: O(number_of_priorities)
+Priorities are implemented by allocating some space for each
+priority. When doing priority-based operations, libev usually has to
+linearly search all the priorities, but starting/stopping and activating
+watchers becomes O(1) with respect to priority handling.
+=item Sending an ev_async: O(1)
+=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
+involves iterating over all running async watchers or all signal numbers.
+=back
 =head1 AUTHOR
 Marc Lehmann <libev@schmorp.de>.

Diff Legend

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

Comparing libev/ev.pod (file contents): Revision 1.189 by root, Tue Sep 30 19:33:33 2008 UTC vs. Revision 1.197 by root, Tue Oct 21 20:52:30 2008 UTC

Diff Legend

Comparing libev/ev.pod (file contents):
Revision 1.189 by root, Tue Sep 30 19:33:33 2008 UTC vs.
Revision 1.197 by root, Tue Oct 21 20:52:30 2008 UTC