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

Comparing libev/ev.pod (file contents):
Revision 1.299 by sf-exg, Sat Aug 28 21:42:12 2010 UTC vs.
Revision 1.309 by root, Thu Oct 21 09:23:21 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
 These two functions can be used to associate arbitrary data with a loop,
 and are intended solely for the C<invoke_pending_cb>, C<release> and
 C<acquire> callbacks described above, but of course can be (ab-)used for
 any other purpose as well.
-=item ev_loop_verify (loop)
+=item ev_verify (loop)
 This function only does something when C<EV_VERIFY> support has been
 compiled in, which is the default for non-minimal builds. It tries to go
 through all internal structures and checks them for validity. If anything
 is found to be inconsistent, it will print an error message to standard
 Example: Call a callback every hour, or, more precisely, whenever the
 system time is divisible by 3600. The callback invocation times have
 potentially a lot of jitter, but good long-term stability.
    static void
-   clock_cb (struct ev_loop *loop, ev_io *w, int revents)
+   clock_cb (struct ev_loop *loop, ev_periodic *w, int revents)
    {
      ... its now a full hour (UTC, or TAI or whatever your clock follows)
    }
    ev_periodic hourly_tick;
 C<ev_default_fork> cheats and calls it in the wrong process, the fork
 handlers will be invoked, too, of course.
 =head3 The special problem of life after fork - how is it possible?
-Most uses of C<fork()> consist of forking, then some simple calls to ste
+Most uses of C<fork()> consist of forking, then some simple calls to set
 up/change the process environment, followed by a call to C<exec()>. This
 sequence should be handled by libev without any problems.
 This changes when the application actually wants to do event handling
 in the child, or both parent in child, in effect "continuing" after the
 believe me.
 =back
-=head2 C<ev_async> - how to wake up another event loop
+=head2 C<ev_async> - how to wake up an event loop
 In general, you cannot use an C<ev_loop> from multiple threads or other
 asynchronous sources such as signal handlers (as opposed to multiple event
 loops - those are of course safe to use in different threads).
-Sometimes, however, you need to wake up another event loop you do not
+Sometimes, however, you need to wake up an event loop you do not control,
-control, for example because it belongs to another thread. This is what
+for example because it belongs to another thread. This is what C<ev_async>
-C<ev_async> watchers do: as long as the C<ev_async> watcher is active, you
+watchers do: as long as the C<ev_async> watcher is active, you can signal
-can signal it by calling C<ev_async_send>, which is thread- and signal
+it by calling C<ev_async_send>, which is thread- and signal safe.
-safe.
 This functionality is very similar to C<ev_signal> watchers, as signals,
 too, are asynchronous in nature, and signals, too, will be compressed
 (i.e. the number of callback invocations may be less than the number of
 C<ev_async_sent> calls).
 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
 The default is C<1>, unless C<EV_FEATURES> overrides it, in which case it
 will be C<0>.
 =item EV_VERIFY
-Controls how much internal verification (see C<ev_loop_verify ()>) will
+Controls how much internal verification (see C<ev_verify ()>) will
 be done: If set to C<0>, no internal verification code will be compiled
 in. If set to C<1>, then verification code will be compiled in, but not
 called. If set to C<2>, then the internal verification code will be
 called once per loop, which can slow down libev. If set to C<3>, then the
 verification code will be called very frequently, which will slow down
 will be C<0>.
 =item EV_COMMON
 By default, all watchers have a C<void *data> member. By redefining
-this macro to a something else you can include more and other types of
+this macro to something else you can include more and other types of
 members. You have to define it each time you include one of the files,
 though, and it must be identical each time.
 For example, the perl EV module uses something like this:
 maintainable.
 And of course, some compiler warnings are just plain stupid, or simply
 wrong (because they don't actually warn about the condition their message
 seems to warn about). For example, certain older gcc versions had some
-warnings that resulted an extreme number of false positives. These have
+warnings that resulted in an extreme number of false positives. These have
 been fixed, but some people still insist on making code warn-free with
 such buggy versions.
 While libev is written to generate as few warnings as possible,
 "warn-free" code is not a goal, and it is recommended not to build libev
 I suggest using suppression lists.
 =head1 PORTABILITY NOTES
+=head2 GNU/LINUX 32 BIT LIMITATIONS
+GNU/Linux is the only common platform that supports 64 bit file/large file
+interfaces but I<disables> them by default.
+That means that libev compiled in the default environment doesn't support
+files larger than 2GiB or so, which mainly affects C<ev_stat> watchers.
+Unfortunately, many programs try to work around this GNU/Linux issue
+by enabling the large file API, which makes them incompatible with the
+standard libev compiled for their system.
+Likewise, libev cannot enable the large file API itself as this would
+suddenly make it incompatible to the default compile time environment,
+i.e. all programs not using special compile switches.
+=head2 OS/X AND DARWIN BUGS
+The whole thing is a bug if you ask me - basically any system interface
+you touch is broken, whether it is locales, poll, kqueue or even the
+OpenGL drivers.
+=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 not using C<poll> by default on
+this rotten platform, but of course you can still ask for it when creating
+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 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.
+=head2 SOLARIS PROBLEMS AND WORKAROUNDS
+=head3 C<errno> reentrancy
+The default compile environment on Solaris is unfortunately so
+thread-unsafe that you can't even use components/libraries compiled
+without C<-D_REENTRANT> (as long as they use C<errno>), which, of course,
+isn't defined by default.
+If you want to use libev in threaded environments you have to make sure
+it's compiled with C<_REENTRANT> defined.
+=head3 Event port backend
+The scalable event interface for Solaris is called "event ports". Unfortunately,
+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 by setting
+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
+compiled in), which normally isn't a big problem as C<select> works fine
+with large bitsets, and AIX is dead anyway.
 =head2 WIN32 PLATFORM LIMITATIONS AND WORKAROUNDS
+=head3 General issues
 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
 model. Libev still offers limited functionality on this platform in
 the form of the C<EVBACKEND_SELECT> backend, and only supports socket
 descriptors. This only applies when using Win32 natively, not when using
-e.g. cygwin.
+e.g. cygwin. Actually, it only applies to the microsofts own compilers,
+as every compielr comes with a slightly differently broken/incompatible
+environment.
 Lifting these limitations would basically require the full
-re-implementation of the I/O system. If you are into these kinds of
+re-implementation of the I/O system. If you are into this kind of thing,
-things, then note that glib does exactly that for you in a very portable
+then note that glib does exactly that for you in a very portable way (note
-way (note also that glib is the slowest event library known to man).
+also that glib is the slowest event library known to man).
 There is no supported compilation method available on windows except
 embedding it into other applications.
 Sensible signal handling is officially unsupported by Microsoft - libev
 you do I<not> compile the F<ev.c> or any other embedded source files!):
    #include "evwrap.h"
    #include "ev.c"
-=over 4
-=item The winsocket select function
+=head3 The winsocket C<select> function
 The winsocket C<select> function doesn't follow POSIX in that it
 requires socket I<handles> and not socket I<file descriptors> (it is
 also extremely buggy). This makes select very inefficient, and also
 requires a mapping from file descriptors to socket handles (the Microsoft
    #define EV_SELECT_IS_WINSOCKET 1   /* forces EV_SELECT_USE_FD_SET, too */
 Note that winsockets handling of fd sets is O(n), so you can easily get a
 complexity in the O(n²) range when using win32.
-=item Limited number of file descriptors
+=head3 Limited number of file descriptors
 Windows has numerous arbitrary (and low) limits on things.
 Early versions of winsocket's select only supported waiting for a maximum
 of C<64> handles (probably owning to the fact that all windows kernels
 runtime libraries. This might get you to about C<512> or C<2048> sockets
 (depending on windows version and/or the phase of the moon). To get more,
 you need to wrap all I/O functions and provide your own fd management, but
 the cost of calling select (O(n²)) will likely make this unworkable.
-=back
 =head2 PORTABILITY REQUIREMENTS
 In addition to a working ISO-C implementation and of course the
 backend-specific APIs, libev relies on a few additional extensions:
 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.299 by sf-exg, Sat Aug 28 21:42:12 2010 UTC vs. Revision 1.309 by root, Thu Oct 21 09:23:21 2010 UTC

Diff Legend

Comparing libev/ev.pod (file contents):
Revision 1.299 by sf-exg, Sat Aug 28 21:42:12 2010 UTC vs.
Revision 1.309 by root, Thu Oct 21 09:23:21 2010 UTC