portability section

1 files changed, 92 insertions, 7 deletions

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