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.304 by root, Thu Oct 14 04:30:46 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 4428Libev tries to work around this by not using C<kqueue> by default on
4429this rotten platform, but of course you can still ask for it when creating
4430a loop.
4431
4432=head3 C<poll> is buggy
4431 4433
4432Instead of fixing C<kqueue>, Apple replaced their (working) C<poll> 4434Instead of fixing C<kqueue>, Apple replaced their (working) C<poll>
4433implementation by something calling C<kqueue> internally around the 10.5.6 4435implementation by something calling C<kqueue> internally around the 10.5.6
4434release, so now C<kqueue> I<and> C<poll> are broken. 4436release, so now C<kqueue> I<and> C<poll> are broken.
4435 4437
4436Libev tries to work around this by neither using C<kqueue> nor C<poll> by 4438Libev tries to work around this by not using C<poll> by default on
4437default on this rotten platform, but of course you cna still ask for them 4439this rotten platform, but of course you can still ask for it when creating
4438when creating a loop. 4440a loop.
4439 4441
4440=item SELECT IS BUGGY 4442=head3 C<select> is buggy
4441 4443
4442All that's left is C<select>, and of course Apple found a way to fuck this 4444All 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 4445one 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 4446descriptors you can pass in to 1024 - your program suddenyl crashes when
4445you use more. 4447you use more.
4446 4448
4447There is an undocumented "workaround" for this - defining 4449There is an undocumented "workaround" for this - defining
4448C<_DARWIN_UNLIMITED_SELECT>, which libev tries to use, so select I<should> 4450C<_DARWIN_UNLIMITED_SELECT>, which libev tries to use, so select I<should>
4449work on OS/X. 4451work on OS/X.
4450 4452
4451=back
4452
4453=head2 SOLARIS PROBLEMS AND WORKAROUNDS 4453=head2 SOLARIS PROBLEMS AND WORKAROUNDS
4454 4454
4455=over 4
4456
4457=item C<errno> reentrancy 4455=head3 C<errno> reentrancy
4458 4456
4459The default compile environment on Solaris is unfortunately so 4457The default compile environment on Solaris is unfortunately so
4460thread-unsafe that you can't even use components/libraries compiled 4458thread-unsafe that you can't even use components/libraries compiled
4461without C<-D_REENTRANT> (as long as they use C<errno>), which, of course, 4459without C<-D_REENTRANT> (as long as they use C<errno>), which, of course,
4462isn't defined by default. 4460isn't defined by default.
4463 4461
4464If you want to use libev in threaded environments you have to make sure 4462If you want to use libev in threaded environments you have to make sure
4465it's compiled with C<_REENTRANT> defined. 4463it's compiled with C<_REENTRANT> defined.
4466 4464
4467=item Event Port Backend 4465=head3 Event port backend
4468 4466
4469The scalable event interface for Solaris is called "event ports". Unfortunately, 4467The scalable event interface for Solaris is called "event ports". Unfortunately,
4470this mechanism is very buggy. If you run into high CPU usage, your program 4468this 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 4469freezes 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 4470all the relevant and latest kernel patches applied. No, I don't know which
4473ones, but there are multiple ones. 4471ones, but there are multiple ones.
4474 4472
4475If you can't get it to work, you can try running the program with 4473If 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. 4474C<LIBEV_FLAGS=3> to only allow C<poll> and C<select> backends.
4477 4475
4478=back
4479
4480=head2 AIX POLL BUG 4476=head2 AIX POLL BUG
4481 4477
4482AIX unfortunately has a broken C<poll.h> header. Libev works around 4478AIX 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 4479this 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 4480compiled in), which normally isn't a big problem as C<select> works fine
4485with large bitsets, and AIX is dead anyway. 4481with large bitsets, and AIX is dead anyway.
4486 4482
4487=head2 WIN32 PLATFORM LIMITATIONS AND WORKAROUNDS 4483=head2 WIN32 PLATFORM LIMITATIONS AND WORKAROUNDS
4484
4485=head3 General issues
4488 4486
4489Win32 doesn't support any of the standards (e.g. POSIX) that libev 4487Win32 doesn't support any of the standards (e.g. POSIX) that libev
4490requires, and its I/O model is fundamentally incompatible with the POSIX 4488requires, and its I/O model is fundamentally incompatible with the POSIX
4491model. Libev still offers limited functionality on this platform in 4489model. Libev still offers limited functionality on this platform in
4492the form of the C<EVBACKEND_SELECT> backend, and only supports socket 4490the form of the C<EVBACKEND_SELECT> backend, and only supports socket
4493descriptors. This only applies when using Win32 natively, not when using 4491descriptors. This only applies when using Win32 natively, not when using
4494e.g. cygwin. 4492e.g. cygwin. Actually, it only applies to the microsofts own compilers,
4493as every compielr comes with a slightly differently broken/incompatible
4494environment.
4495 4495
4496Lifting these limitations would basically require the full 4496Lifting these limitations would basically require the full
4497re-implementation of the I/O system. If you are into these kinds of 4497re-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 4498then 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). 4499also that glib is the slowest event library known to man).
4500 4500
4501There is no supported compilation method available on windows except 4501There is no supported compilation method available on windows except
4502embedding it into other applications. 4502embedding it into other applications.
4503 4503
4504Sensible signal handling is officially unsupported by Microsoft - libev 4504Sensible signal handling is officially unsupported by Microsoft - libev
… …
4532you do I<not> compile the F<ev.c> or any other embedded source files!): 4532you do I<not> compile the F<ev.c> or any other embedded source files!):
4533 4533
4534 #include "evwrap.h" 4534 #include "evwrap.h"
4535 #include "ev.c" 4535 #include "ev.c"
4536 4536
4537=over 4
4538
4539=item The winsocket select function 4537=head3 The winsocket C<select> function
4540 4538
4541The winsocket C<select> function doesn't follow POSIX in that it 4539The winsocket C<select> function doesn't follow POSIX in that it
4542requires socket I<handles> and not socket I<file descriptors> (it is 4540requires socket I<handles> and not socket I<file descriptors> (it is
4543also extremely buggy). This makes select very inefficient, and also 4541also extremely buggy). This makes select very inefficient, and also
4544requires a mapping from file descriptors to socket handles (the Microsoft 4542requires a mapping from file descriptors to socket handles (the Microsoft
… …
4553 #define EV_SELECT_IS_WINSOCKET 1 /* forces EV_SELECT_USE_FD_SET, too */ 4551 #define EV_SELECT_IS_WINSOCKET 1 /* forces EV_SELECT_USE_FD_SET, too */
4554 4552
4555Note that winsockets handling of fd sets is O(n), so you can easily get a 4553Note that winsockets handling of fd sets is O(n), so you can easily get a
4556complexity in the O(n²) range when using win32. 4554complexity in the O(n²) range when using win32.
4557 4555
4558=item Limited number of file descriptors 4556=head3 Limited number of file descriptors
4559 4557
4560Windows has numerous arbitrary (and low) limits on things. 4558Windows has numerous arbitrary (and low) limits on things.
4561 4559
4562Early versions of winsocket's select only supported waiting for a maximum 4560Early versions of winsocket's select only supported waiting for a maximum
4563of C<64> handles (probably owning to the fact that all windows kernels 4561of 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 4576runtime 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, 4577(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 4578you 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. 4579the cost of calling select (O(n²)) will likely make this unworkable.
4582 4580
4583=back
4584
4585=head2 PORTABILITY REQUIREMENTS 4581=head2 PORTABILITY REQUIREMENTS
4586 4582
4587In addition to a working ISO-C implementation and of course the 4583In addition to a working ISO-C implementation and of course the
4588backend-specific APIs, libev relies on a few additional extensions: 4584backend-specific APIs, libev relies on a few additional extensions:
4589 4585

Diff Legend

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