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

Comparing libev/ev.pod (file contents):
Revision 1.191 by root, Tue Sep 30 19:45:23 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 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)

Diff Legend

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

Comparing libev/ev.pod (file contents): Revision 1.191 by root, Tue Sep 30 19:45:23 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.191 by root, Tue Sep 30 19:45:23 2008 UTC vs.
Revision 1.197 by root, Tue Oct 21 20:52:30 2008 UTC