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