diff options
| -rw-r--r-- | Changes | 3 | ||||
| -rw-r--r-- | ev.pod | 99 |
2 files changed, 93 insertions, 9 deletions
@@ -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). @@ -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 |