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

Comparing libev/ev.pod (file contents):
Revision 1.303 by root, Thu Oct 14 04:29:34 2010 UTC vs.
Revision 1.308 by root, Thu Oct 21 02:46:59 2010 UTC

 of course I<doesn't>, and epoll just loves to report events for totally
 I<different> file descriptors (even already closed ones, so one cannot
 even remove them from the set) than registered in the set (especially
 on SMP systems). Libev tries to counter these spurious notifications by
 employing an additional generation counter and comparing that against the
-events to filter out spurious ones, recreating the set when required.
+events to filter out spurious ones, recreating the set when required. Last
+not least, it also refuses to work with some file descriptors which work
+perfectly fine with C<select> (files, many character devices...).
 While stopping, setting and starting an I/O watcher in the same iteration
 will result in some caching, there is still a system call per such
 incident (because the same I<file descriptor> could point to a different
 I<file description> now), so its best to avoid that. Also, C<dup ()>'ed
 Associates a different C<struct ev_loop> with this watcher. You can only
 do this when the watcher is inactive (and not pending either).
 =item w->set ([arguments])
-Basically the same as C<ev_TYPE_set>, with the same arguments. Must be
+Basically the same as C<ev_TYPE_set>, with the same arguments. Either this
-called at least once. Unlike the C counterpart, an active watcher gets
+method or a suitable start method must be called at least once. Unlike the
-automatically stopped and restarted when reconfiguring it with this
+C counterpart, an active watcher gets automatically stopped and restarted
-method.
+when reconfiguring it with this method.
 =item w->start ()
 Starts the watcher. Note that there is no C<loop> argument, as the
 constructor already stores the event loop.
+=item w->start ([arguments])
+Instead of calling C<set> and C<start> methods separately, it is often
+convenient to wrap them in one call. Uses the same type of arguments as
+the configure C<set> method of the watcher.
 =item w->stop ()
 Stops the watcher if it is active. Again, no C<loop> argument.
 =item w->again () (C<ev::timer>, C<ev::periodic> only)
 =back
 =back
-Example: Define a class with an IO and idle watcher, start one of them in
+Example: Define a class with two I/O and idle watchers, start the I/O
-the constructor.
+watchers in the constructor.
    class myclass
    {
      ev::io   io  ; void io_cb   (ev::io   &w, int revents);
+     ev::io2  io2 ; void io2_cb  (ev::io   &w, int revents);
      ev::idle idle; void idle_cb (ev::idle &w, int revents);
      myclass (int fd)
      {
        io  .set <myclass, &myclass::io_cb  > (this);
+       io2 .set <myclass, &myclass::io2_cb > (this);
        idle.set <myclass, &myclass::idle_cb> (this);
-       io.start (fd, ev::READ);
+       io.set (fd, ev::WRITE); // configure the watcher
+       io.start ();            // start it whenever convenient
+       io2.start (fd, ev::READ); // set + start in one call
      }
    };
 =head1 OTHER LANGUAGE BINDINGS
 =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
+this rotten platform, but of course you can still ask for it when creating
+a loop.
 =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
 release, so now C<kqueue> I<and> C<poll> are broken.
-Libev tries to work around this by neither using C<kqueue> nor C<poll> by
+Libev tries to work around this by not using C<poll> by default on
-default on this rotten platform, but of course you cna still ask for them
+this rotten platform, but of course you can still ask for it when creating
-when creating a loop.
+a loop.
 =head3 C<select> is buggy
 All that's left is C<select>, and of course Apple found a way to fuck this
 one up as well: On OS/X, C<select> actively limits the number of file
-descriptors you can pass in to 1024 - your program suddenyl crashes when
+descriptors you can pass in to 1024 - your program suddenly crashes when
 you use more.
 There is an undocumented "workaround" for this - defining
 C<_DARWIN_UNLIMITED_SELECT>, which libev tries to use, so select I<should>
 work on OS/X.
 this mechanism is very buggy. If you run into high CPU usage, your program
 freezes or you get a large number of spurious wakeups, make sure you have
 all the relevant and latest kernel patches applied. No, I don't know which
 ones, but there are multiple ones.
-If you can't get it to work, you can try running the program with
+If you can't get it to work, you can try running the program by setting
-C<LIBEV_FLAGS=3> to only allow C<poll> and C<select> backends.
+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
 watchers.
 =item C<double> must hold a time value in seconds with enough accuracy
 The type C<double> is used to represent timestamps. It is required to
-have at least 51 bits of mantissa (and 9 bits of exponent), which is good
+have at least 51 bits of mantissa (and 9 bits of exponent), which is
-enough for at least into the year 4000. This requirement is fulfilled by
+good enough for at least into the year 4000 with millisecond accuracy
+(the design goal for libev). This requirement is overfulfilled by
-implementations implementing IEEE 754, which is basically all existing
+implementations using IEEE 754, which is basically all existing ones. With
-ones. With IEEE 754 doubles, you get microsecond accuracy until at least
+IEEE 754 doubles, you get microsecond accuracy until at least 2200.
-2200.
 =back
 If you know of other additional requirements drop me a note.

Diff Legend

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

Comparing libev/ev.pod (file contents): Revision 1.303 by root, Thu Oct 14 04:29:34 2010 UTC vs. Revision 1.308 by root, Thu Oct 21 02:46:59 2010 UTC

Diff Legend

Comparing libev/ev.pod (file contents):
Revision 1.303 by root, Thu Oct 14 04:29:34 2010 UTC vs.
Revision 1.308 by root, Thu Oct 21 02:46:59 2010 UTC