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

Comparing libev/ev.pod (file contents):
Revision 1.177 by root, Mon Sep 8 17:27:42 2008 UTC vs.
Revision 1.181 by root, Fri Sep 19 03:47:50 2008 UTC

 writing a server, you should C<accept ()> in a loop to accept as many
 connections as possible during one iteration. You might also want to have
 a look at C<ev_set_io_collect_interval ()> to increase the amount of
 readiness notifications you get per iteration.
+This backend maps C<EV_READ> to the C<readfds> set and C<EV_WRITE> to the
+C<writefds> set (and to work around Microsoft Windows bugs, also onto the
+C<exceptfds> set on that platform).
 =item C<EVBACKEND_POLL>    (value 2, poll backend, available everywhere except on windows)
 And this is your standard poll(2) backend. It's more complicated
 than select, but handles sparse fds better and has no artificial
 limit on the number of fds you can use (except it will slow down
 considerably with a lot of inactive fds). It scales similarly to select,
 i.e. O(total_fds). See the entry for C<EVBACKEND_SELECT>, above, for
 performance tips.
+This backend maps C<EV_READ> to C<POLLIN | POLLERR | POLLHUP>, and
+C<EV_WRITE> to C<POLLOUT | POLLERR | POLLHUP>.
 =item C<EVBACKEND_EPOLL>   (value 4, Linux)
 For few fds, this backend is a bit little slower than poll and select,
 but it scales phenomenally better. While poll and select usually scale
 keep at least one watcher active per fd at all times.
 While nominally embeddable in other event loops, this feature is broken in
 all kernel versions tested so far.
+This backend maps C<EV_READ> and C<EV_WRITE> in the same way as
+C<EVBACKEND_POLL>.
 =item C<EVBACKEND_KQUEUE>  (value 8, most BSD clones)
 Kqueue deserves special mention, as at the time of this writing, it
 was broken on all BSDs except NetBSD (usually it doesn't work reliably
 with anything but sockets and pipes, except on Darwin, where of course
 almost everywhere, you should only use it when you have a lot of sockets
 (for which it usually works), by embedding it into another event loop
 (e.g. C<EVBACKEND_SELECT> or C<EVBACKEND_POLL>) and using it only for
 sockets.
+This backend maps C<EV_READ> into an C<EVFILT_READ> kevent with
+C<NOTE_EOF>, and C<EV_WRITE> into an C<EVFILT_WRITE> kevent with
+C<NOTE_EOF>.
 =item C<EVBACKEND_DEVPOLL> (value 16, Solaris 8)
 This is not implemented yet (and might never be, unless you send me an
 implementation). According to reports, C</dev/poll> only supports sockets
 and is not embeddable, which would limit the usefulness of this backend
 might perform better.
 On the positive side, ignoring the spurious readiness notifications, this
 backend actually performed to specification in all tests and is fully
 embeddable, which is a rare feat among the OS-specific backends.
+This backend maps C<EV_READ> and C<EV_WRITE> in the same way as
+C<EVBACKEND_POLL>.
 =item C<EVBACKEND_ALL>
 Try all backends (even potentially broken ones that wouldn't be tried
 with C<EVFLAG_AUTO>). Since this is a mask, you can do stuff such as
    {
      struct ev_io io;
      int otherfd;
      void *somedata;
      struct whatever *mostinteresting;
-   }
+   };
+   ...
+   struct my_io w;
+   ev_io_init (&w.io, my_cb, fd, EV_READ);
 And since your callback will be called with a pointer to the watcher, you
 can cast it back to your own type:
    static void my_cb (struct ev_loop *loop, struct ev_io *w_, int revents)
    }
 More interesting and less C-conformant ways of casting your callback type
 instead have been omitted.
-Another common scenario is having some data structure with multiple
+Another common scenario is to use some data structure with multiple
-watchers:
+embedded watchers:
    struct my_biggy
    {
      int some_data;
      ev_timer t1;
      ev_timer t2;
    }
-In this case getting the pointer to C<my_biggy> is a bit more complicated,
+In this case getting the pointer to C<my_biggy> is a bit more
-you need to use C<offsetof>:
+complicated: Either you store the address of your C<my_biggy> struct
+in the C<data> member of the watcher, or you need to use some pointer
+arithmetic using C<offsetof> inside your watchers:
    #include <stddef.h>
    static void
    t1_cb (EV_P_ struct ev_timer *w, int revents)
 =head1 THREADS AND COROUTINES
 =head2 THREADS
-Libev itself is completely thread-safe, but it uses no locking. This
+Libev itself is thread-safe (unless the opposite is specifically
+documented for a function), but it uses no locking itself. This means that
-means that you can use as many loops as you want in parallel, as long as
+you can use as many loops as you want in parallel, as long as only one
-only one thread ever calls into one libev function with the same loop
+thread ever calls into one libev function with the same loop parameter:
-parameter.
+libev guarentees that different event loops share no data structures that
+need locking.
-Or put differently: calls with different loop parameters can be done in
+Or to put it differently: calls with different loop parameters can be done
-parallel from multiple threads, calls with the same loop parameter must be
+concurrently from multiple threads, calls with the same loop parameter
-done serially (but can be done from different threads, as long as only one
+must be done serially (but can be done from different threads, as long as
-thread ever is inside a call at any point in time, e.g. by using a mutex
+only one thread ever is inside a call at any point in time, e.g. by using
-per loop).
+a mutex per loop).
+Specifically to support threads (and signal handlers), libev implements
+so-called C<ev_async> watchers, which allow some limited form of
+concurrency on the same event loop.
 If you want to know which design (one loop, locking, or multiple loops
 without or something else still) is best for your problem, then I cannot
 help you. I can give some generic advice however:
 better than you currently do :-)
 =item * often you need to talk to some other thread which blocks in the
 event loop - C<ev_async> watchers can be used to wake them up from other
 threads safely (or from signal contexts...).
+=item * some watcher types are only supported in the default loop - use
+C<ev_async> watchers to tell your other loops about any such events.
 =back
 =head2 COROUTINES
 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
 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 invested into making sure that libev does not keep local
+Care has been taken to ensure that libev does not keep local state inside
-state inside C<ev_loop>, and other calls do not usually allow coroutine
+C<ev_loop>, and other calls do not usually allow coroutine switches.
-switches.
 =head1 COMPLEXITIES
 In this section the complexities of (many of) the algorithms used inside

Diff Legend

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

Comparing libev/ev.pod (file contents): Revision 1.177 by root, Mon Sep 8 17:27:42 2008 UTC vs. Revision 1.181 by root, Fri Sep 19 03:47:50 2008 UTC

Diff Legend

Comparing libev/ev.pod (file contents):
Revision 1.177 by root, Mon Sep 8 17:27:42 2008 UTC vs.
Revision 1.181 by root, Fri Sep 19 03:47:50 2008 UTC