portability section

2 files changed, 93 insertions, 9 deletions

diff --git a/Changes b/Changes
index 2bb3a04..776a0c9 100644
--- a/Changes
+++ b/Changes
@@ -2,9 +2,7 @@ Revision history for libev, a high-performance and full-featured event loop.
 
 TODO: ABI??? API????? Changes???
 TODO: win32 write() to socket for signal handling
-TODO: poll asert
 TODO: EV_USE__XXX default with config, document
-TODO: pendingall => idleall?
 TODO: portbality section, solaris errno rrentrant, aix, win32, linux 32 bit
 TODO: include ev_xyz_start in each example?
 TODO: section watcher states/lifetime
@@ -25,6 +23,7 @@ TODO: section watcher states/lifetime
           on freebsd...).
         - configure now prepends -O3, not appends it, so one can still
           override it.
+        - greatly expanded the portability section.
         - disable poll backend on AIX, the poll header spams the namespace
           and it's not worth working around dead platforms (reported
           and analyzed by Aivars Kalvans).
diff --git a/ev.pod b/ev.pod
index 5f65061..387ec4e 100644
--- a/ev.pod
+++ b/ev.pod
@@ -2967,7 +2967,7 @@ 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.
 
@@ -3011,17 +3011,16 @@ 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
-control, for example because it belongs to another thread. This is what
-C<ev_async> watchers do: as long as the C<ev_async> watcher is active, you
-can signal it by calling C<ev_async_send>, which is thread- and signal
-safe.
+Sometimes, however, you need to wake up an event loop you do not control,
+for example because it belongs to another thread. This is what C<ev_async>
+watchers do: as long as the C<ev_async> watcher is active, you can signal
+it by calling C<ev_async_send>, which is thread- and signal safe.
 
 This functionality is very similar to C<ev_signal> watchers, as signals,
 too, are asynchronous in nature, and signals, too, will be compressed
@@ -4399,6 +4398,92 @@ 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 disables them by default.
+
+That means that libev compiled in the default environment doesn't support
+files larger than 2GiB, 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 their
+OpenGL drivers.
+
+=over 4
+
+=item KQUEUE IS BUGGY
+
+The kqueue syscall is broken in all known versions - most versions support
+only sockets, many support pipes.
+
+=item 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
+default on this rotten platform, but of course you cna still ask for them
+when creating a loop.
+
+=item 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
+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.
+
+=back
+
+=head2 SOLARIS PROBLEMS AND WORKAROUNDS
+
+=over 4
+
+=item 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.
+
+=item 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 with
+C<LIBEV_FLAGS=3> to only allow C<poll> and C<select> backends.
+
+=back
+
+=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
 
 Win32 doesn't support any of the standards (e.g. POSIX) that libev