@ -1,11 +1,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
- "PORTING FROM LIBEV 3.X TO 4.X" (in ev.pod) is recommended reading.
@ -25,6 +21,7 @@ TODO: section watcher states/lifetime
- configure now prepends -O3, not appends it, so one can still
- 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).
@ -1283,6 +1283,11 @@ evpipe_write (EV_P_ EV_ATOMIC_T *flag)
/* win32 people keep sending patches that change this write() to send() */
/* and then run away. but send() is wrong, it wants a socket handle on win32 */
/* so when you think this write should be a send instead, please find out */
/* where your send() is from - it's definitely not the microsoft send, and */
/* tell me. thank you. */
write (evpipe , &dummy, 1);
errno = old_errno;
@ -1306,6 +1311,7 @@ pipecb (EV_P_ ev_io *iow, int revents)
/* see discussion in evpipe_write when you think this read should be recv in win32 */
read (evpipe , &dummy, 1);
@ -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.
=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
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,19 +4398,106 @@ 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
=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
=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
=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
=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. Actually, it only applies to the microsofts own compilers,
as every compielr comes with a slightly differently broken/incompatible
Lifting these limitations would basically require the full
re-implementation of the I/O system. If you are into these kinds of
things, then note that glib does exactly that for you in a very portable
way (note also that glib is the slowest event library known to man).
re-implementation of the I/O system. If you are into this kind of thing,
then note that glib does exactly that for you in a very portable way (note
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.
@ -4449,9 +4535,7 @@ you do I<not> compile the F<ev.c> or any other embedded source files!):
=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
@ -4470,7 +4554,7 @@ libraries and raw winsocket select is:
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.
@ -4495,8 +4579,6 @@ runtime libraries. This might get you to about C<512> or C<2048> sockets
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.
=head2 PORTABILITY REQUIREMENTS
In addition to a working ISO-C implementation and of course the