ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/libev/ev.pod
(Generate patch)

Comparing libev/ev.pod (file contents):
Revision 1.302 by root, Thu Oct 14 04:23:19 2010 UTC vs.
Revision 1.303 by root, Thu Oct 14 04:29:34 2010 UTC

… …
4399=head1 PORTABILITY NOTES 4399=head1 PORTABILITY NOTES
4400 4400
4401=head2 GNU/LINUX 32 BIT LIMITATIONS 4401=head2 GNU/LINUX 32 BIT LIMITATIONS
4402 4402
4403GNU/Linux is the only common platform that supports 64 bit file/large file 4403GNU/Linux is the only common platform that supports 64 bit file/large file
4404interfaces but disables them by default. 4404interfaces but I<disables> them by default.
4405 4405
4406That means that libev compiled in the default environment doesn't support 4406That means that libev compiled in the default environment doesn't support
4407files larger than 2GiB, which mainly affects C<ev_stat> watchers. 4407files larger than 2GiB or so, which mainly affects C<ev_stat> watchers.
4408 4408
4409Unfortunately, many programs try to work around this GNU/Linux issue 4409Unfortunately, many programs try to work around this GNU/Linux issue
4410by enabling the large file API, which makes them incompatible with the 4410by enabling the large file API, which makes them incompatible with the
4411standard libev compiled for their system. 4411standard libev compiled for their system.
4412 4412
… …
4415i.e. all programs not using special compile switches. 4415i.e. all programs not using special compile switches.
4416 4416
4417=head2 OS/X AND DARWIN BUGS 4417=head2 OS/X AND DARWIN BUGS
4418 4418
4419The whole thing is a bug if you ask me - basically any system interface 4419The whole thing is a bug if you ask me - basically any system interface
4420you touch is broken, whether it is locales, poll, kqueue or even their 4420you touch is broken, whether it is locales, poll, kqueue or even the
4421OpenGL drivers. 4421OpenGL drivers.
4422 4422
4423=over 4 4423=head3 C<kqueue> is buggy
4424
4425=item KQUEUE IS BUGGY
4426 4424
4427The kqueue syscall is broken in all known versions - most versions support 4425The kqueue syscall is broken in all known versions - most versions support
4428only sockets, many support pipes. 4426only sockets, many support pipes.
4429 4427
4430=item POLL IS BUGGY 4428=head3 C<poll> is buggy
4431 4429
4432Instead of fixing C<kqueue>, Apple replaced their (working) C<poll> 4430Instead of fixing C<kqueue>, Apple replaced their (working) C<poll>
4433implementation by something calling C<kqueue> internally around the 10.5.6 4431implementation by something calling C<kqueue> internally around the 10.5.6
4434release, so now C<kqueue> I<and> C<poll> are broken. 4432release, so now C<kqueue> I<and> C<poll> are broken.
4435 4433
4436Libev tries to work around this by neither using C<kqueue> nor C<poll> by 4434Libev tries to work around this by neither using C<kqueue> nor C<poll> by
4437default on this rotten platform, but of course you cna still ask for them 4435default on this rotten platform, but of course you cna still ask for them
4438when creating a loop. 4436when creating a loop.
4439 4437
4440=item SELECT IS BUGGY 4438=head3 C<select> is buggy
4441 4439
4442All that's left is C<select>, and of course Apple found a way to fuck this 4440All that's left is C<select>, and of course Apple found a way to fuck this
4443one up as well: On OS/X, C<select> actively limits the number of file 4441one up as well: On OS/X, C<select> actively limits the number of file
4444descriptors you can pass in to 1024 - your program suddenyl crashes when 4442descriptors you can pass in to 1024 - your program suddenyl crashes when
4445you use more. 4443you use more.
4446 4444
4447There is an undocumented "workaround" for this - defining 4445There is an undocumented "workaround" for this - defining
4448C<_DARWIN_UNLIMITED_SELECT>, which libev tries to use, so select I<should> 4446C<_DARWIN_UNLIMITED_SELECT>, which libev tries to use, so select I<should>
4449work on OS/X. 4447work on OS/X.
4450 4448
4451=back
4452
4453=head2 SOLARIS PROBLEMS AND WORKAROUNDS 4449=head2 SOLARIS PROBLEMS AND WORKAROUNDS
4454 4450
4455=over 4
4456
4457=item C<errno> reentrancy 4451=head3 C<errno> reentrancy
4458 4452
4459The default compile environment on Solaris is unfortunately so 4453The default compile environment on Solaris is unfortunately so
4460thread-unsafe that you can't even use components/libraries compiled 4454thread-unsafe that you can't even use components/libraries compiled
4461without C<-D_REENTRANT> (as long as they use C<errno>), which, of course, 4455without C<-D_REENTRANT> (as long as they use C<errno>), which, of course,
4462isn't defined by default. 4456isn't defined by default.
4463 4457
4464If you want to use libev in threaded environments you have to make sure 4458If you want to use libev in threaded environments you have to make sure
4465it's compiled with C<_REENTRANT> defined. 4459it's compiled with C<_REENTRANT> defined.
4466 4460
4467=item Event Port Backend 4461=head3 Event port backend
4468 4462
4469The scalable event interface for Solaris is called "event ports". Unfortunately, 4463The scalable event interface for Solaris is called "event ports". Unfortunately,
4470this mechanism is very buggy. If you run into high CPU usage, your program 4464this mechanism is very buggy. If you run into high CPU usage, your program
4471freezes or you get a large number of spurious wakeups, make sure you have 4465freezes or you get a large number of spurious wakeups, make sure you have
4472all the relevant and latest kernel patches applied. No, I don't know which 4466all the relevant and latest kernel patches applied. No, I don't know which
4473ones, but there are multiple ones. 4467ones, but there are multiple ones.
4474 4468
4475If you can't get it to work, you can try running the program with 4469If you can't get it to work, you can try running the program with
4476C<LIBEV_FLAGS=3> to only allow C<poll> and C<select> backends. 4470C<LIBEV_FLAGS=3> to only allow C<poll> and C<select> backends.
4477 4471
4478=back
4479
4480=head2 AIX POLL BUG 4472=head2 AIX POLL BUG
4481 4473
4482AIX unfortunately has a broken C<poll.h> header. Libev works around 4474AIX unfortunately has a broken C<poll.h> header. Libev works around
4483this by trying to avoid the poll backend altogether (i.e. it's not even 4475this by trying to avoid the poll backend altogether (i.e. it's not even
4484compiled in), which normally isn't a big problem as C<select> works fine 4476compiled in), which normally isn't a big problem as C<select> works fine
4485with large bitsets, and AIX is dead anyway. 4477with large bitsets, and AIX is dead anyway.
4486 4478
4487=head2 WIN32 PLATFORM LIMITATIONS AND WORKAROUNDS 4479=head2 WIN32 PLATFORM LIMITATIONS AND WORKAROUNDS
4480
4481=head3 General issues
4488 4482
4489Win32 doesn't support any of the standards (e.g. POSIX) that libev 4483Win32 doesn't support any of the standards (e.g. POSIX) that libev
4490requires, and its I/O model is fundamentally incompatible with the POSIX 4484requires, and its I/O model is fundamentally incompatible with the POSIX
4491model. Libev still offers limited functionality on this platform in 4485model. Libev still offers limited functionality on this platform in
4492the form of the C<EVBACKEND_SELECT> backend, and only supports socket 4486the form of the C<EVBACKEND_SELECT> backend, and only supports socket
4493descriptors. This only applies when using Win32 natively, not when using 4487descriptors. This only applies when using Win32 natively, not when using
4494e.g. cygwin. 4488e.g. cygwin. Actually, it only applies to the microsofts own compilers,
4489as every compielr comes with a slightly differently broken/incompatible
4490environment.
4495 4491
4496Lifting these limitations would basically require the full 4492Lifting these limitations would basically require the full
4497re-implementation of the I/O system. If you are into these kinds of 4493re-implementation of the I/O system. If you are into this kind of thing,
4498things, then note that glib does exactly that for you in a very portable 4494then note that glib does exactly that for you in a very portable way (note
4499way (note also that glib is the slowest event library known to man). 4495also that glib is the slowest event library known to man).
4500 4496
4501There is no supported compilation method available on windows except 4497There is no supported compilation method available on windows except
4502embedding it into other applications. 4498embedding it into other applications.
4503 4499
4504Sensible signal handling is officially unsupported by Microsoft - libev 4500Sensible signal handling is officially unsupported by Microsoft - libev
… …
4532you do I<not> compile the F<ev.c> or any other embedded source files!): 4528you do I<not> compile the F<ev.c> or any other embedded source files!):
4533 4529
4534 #include "evwrap.h" 4530 #include "evwrap.h"
4535 #include "ev.c" 4531 #include "ev.c"
4536 4532
4537=over 4
4538
4539=item The winsocket select function 4533=head3 The winsocket C<select> function
4540 4534
4541The winsocket C<select> function doesn't follow POSIX in that it 4535The winsocket C<select> function doesn't follow POSIX in that it
4542requires socket I<handles> and not socket I<file descriptors> (it is 4536requires socket I<handles> and not socket I<file descriptors> (it is
4543also extremely buggy). This makes select very inefficient, and also 4537also extremely buggy). This makes select very inefficient, and also
4544requires a mapping from file descriptors to socket handles (the Microsoft 4538requires a mapping from file descriptors to socket handles (the Microsoft
… …
4553 #define EV_SELECT_IS_WINSOCKET 1 /* forces EV_SELECT_USE_FD_SET, too */ 4547 #define EV_SELECT_IS_WINSOCKET 1 /* forces EV_SELECT_USE_FD_SET, too */
4554 4548
4555Note that winsockets handling of fd sets is O(n), so you can easily get a 4549Note that winsockets handling of fd sets is O(n), so you can easily get a
4556complexity in the O(n²) range when using win32. 4550complexity in the O(n²) range when using win32.
4557 4551
4558=item Limited number of file descriptors 4552=head3 Limited number of file descriptors
4559 4553
4560Windows has numerous arbitrary (and low) limits on things. 4554Windows has numerous arbitrary (and low) limits on things.
4561 4555
4562Early versions of winsocket's select only supported waiting for a maximum 4556Early versions of winsocket's select only supported waiting for a maximum
4563of C<64> handles (probably owning to the fact that all windows kernels 4557of C<64> handles (probably owning to the fact that all windows kernels
… …
4578runtime libraries. This might get you to about C<512> or C<2048> sockets 4572runtime libraries. This might get you to about C<512> or C<2048> sockets
4579(depending on windows version and/or the phase of the moon). To get more, 4573(depending on windows version and/or the phase of the moon). To get more,
4580you need to wrap all I/O functions and provide your own fd management, but 4574you need to wrap all I/O functions and provide your own fd management, but
4581the cost of calling select (O(n²)) will likely make this unworkable. 4575the cost of calling select (O(n²)) will likely make this unworkable.
4582 4576
4583=back
4584
4585=head2 PORTABILITY REQUIREMENTS 4577=head2 PORTABILITY REQUIREMENTS
4586 4578
4587In addition to a working ISO-C implementation and of course the 4579In addition to a working ISO-C implementation and of course the
4588backend-specific APIs, libev relies on a few additional extensions: 4580backend-specific APIs, libev relies on a few additional extensions:
4589 4581

Diff Legend

– Removed lines
+ Added lines
< Changed lines
> Changed lines