| … | |
… | |
| 439 | of course I<doesn't>, and epoll just loves to report events for totally |
439 | of course I<doesn't>, and epoll just loves to report events for totally |
| 440 | I<different> file descriptors (even already closed ones, so one cannot |
440 | I<different> file descriptors (even already closed ones, so one cannot |
| 441 | even remove them from the set) than registered in the set (especially |
441 | even remove them from the set) than registered in the set (especially |
| 442 | on SMP systems). Libev tries to counter these spurious notifications by |
442 | on SMP systems). Libev tries to counter these spurious notifications by |
| 443 | employing an additional generation counter and comparing that against the |
443 | employing an additional generation counter and comparing that against the |
| 444 | events to filter out spurious ones, recreating the set when required. |
444 | events to filter out spurious ones, recreating the set when required. Last |
|
|
445 | not least, it also refuses to work with some file descriptors which work |
|
|
446 | perfectly fine with C<select> (files, many character devices...). |
| 445 | |
447 | |
| 446 | While stopping, setting and starting an I/O watcher in the same iteration |
448 | While stopping, setting and starting an I/O watcher in the same iteration |
| 447 | will result in some caching, there is still a system call per such |
449 | will result in some caching, there is still a system call per such |
| 448 | incident (because the same I<file descriptor> could point to a different |
450 | incident (because the same I<file descriptor> could point to a different |
| 449 | I<file description> now), so its best to avoid that. Also, C<dup ()>'ed |
451 | I<file description> now), so its best to avoid that. Also, C<dup ()>'ed |
| … | |
… | |
| 4399 | =head1 PORTABILITY NOTES |
4401 | =head1 PORTABILITY NOTES |
| 4400 | |
4402 | |
| 4401 | =head2 GNU/LINUX 32 BIT LIMITATIONS |
4403 | =head2 GNU/LINUX 32 BIT LIMITATIONS |
| 4402 | |
4404 | |
| 4403 | GNU/Linux is the only common platform that supports 64 bit file/large file |
4405 | GNU/Linux is the only common platform that supports 64 bit file/large file |
| 4404 | interfaces but disables them by default. |
4406 | interfaces but I<disables> them by default. |
| 4405 | |
4407 | |
| 4406 | That means that libev compiled in the default environment doesn't support |
4408 | That means that libev compiled in the default environment doesn't support |
| 4407 | files larger than 2GiB, which mainly affects C<ev_stat> watchers. |
4409 | files larger than 2GiB or so, which mainly affects C<ev_stat> watchers. |
| 4408 | |
4410 | |
| 4409 | Unfortunately, many programs try to work around this GNU/Linux issue |
4411 | Unfortunately, many programs try to work around this GNU/Linux issue |
| 4410 | by enabling the large file API, which makes them incompatible with the |
4412 | by enabling the large file API, which makes them incompatible with the |
| 4411 | standard libev compiled for their system. |
4413 | standard libev compiled for their system. |
| 4412 | |
4414 | |
| … | |
… | |
| 4415 | i.e. all programs not using special compile switches. |
4417 | i.e. all programs not using special compile switches. |
| 4416 | |
4418 | |
| 4417 | =head2 OS/X AND DARWIN BUGS |
4419 | =head2 OS/X AND DARWIN BUGS |
| 4418 | |
4420 | |
| 4419 | The whole thing is a bug if you ask me - basically any system interface |
4421 | 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 |
4422 | you touch is broken, whether it is locales, poll, kqueue or even the |
| 4421 | OpenGL drivers. |
4423 | OpenGL drivers. |
| 4422 | |
4424 | |
| 4423 | =over 4 |
4425 | =head3 C<kqueue> is buggy |
| 4424 | |
|
|
| 4425 | =item KQUEUE IS BUGGY |
|
|
| 4426 | |
4426 | |
| 4427 | The kqueue syscall is broken in all known versions - most versions support |
4427 | The kqueue syscall is broken in all known versions - most versions support |
| 4428 | only sockets, many support pipes. |
4428 | only sockets, many support pipes. |
| 4429 | |
4429 | |
| 4430 | =item POLL IS BUGGY |
4430 | Libev tries to work around this by not using C<kqueue> by default on |
|
|
4431 | this rotten platform, but of course you can still ask for it when creating |
|
|
4432 | a loop. |
|
|
4433 | |
|
|
4434 | =head3 C<poll> is buggy |
| 4431 | |
4435 | |
| 4432 | Instead of fixing C<kqueue>, Apple replaced their (working) C<poll> |
4436 | Instead of fixing C<kqueue>, Apple replaced their (working) C<poll> |
| 4433 | implementation by something calling C<kqueue> internally around the 10.5.6 |
4437 | implementation by something calling C<kqueue> internally around the 10.5.6 |
| 4434 | release, so now C<kqueue> I<and> C<poll> are broken. |
4438 | release, so now C<kqueue> I<and> C<poll> are broken. |
| 4435 | |
4439 | |
| 4436 | Libev tries to work around this by neither using C<kqueue> nor C<poll> by |
4440 | Libev tries to work around this by not using C<poll> by default on |
| 4437 | default on this rotten platform, but of course you cna still ask for them |
4441 | this rotten platform, but of course you can still ask for it when creating |
| 4438 | when creating a loop. |
4442 | a loop. |
| 4439 | |
4443 | |
| 4440 | =item SELECT IS BUGGY |
4444 | =head3 C<select> is buggy |
| 4441 | |
4445 | |
| 4442 | All that's left is C<select>, and of course Apple found a way to fuck this |
4446 | 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 |
4447 | 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 |
4448 | descriptors you can pass in to 1024 - your program suddenly crashes when |
| 4445 | you use more. |
4449 | you use more. |
| 4446 | |
4450 | |
| 4447 | There is an undocumented "workaround" for this - defining |
4451 | There is an undocumented "workaround" for this - defining |
| 4448 | C<_DARWIN_UNLIMITED_SELECT>, which libev tries to use, so select I<should> |
4452 | C<_DARWIN_UNLIMITED_SELECT>, which libev tries to use, so select I<should> |
| 4449 | work on OS/X. |
4453 | work on OS/X. |
| 4450 | |
4454 | |
| 4451 | =back |
|
|
| 4452 | |
|
|
| 4453 | =head2 SOLARIS PROBLEMS AND WORKAROUNDS |
4455 | =head2 SOLARIS PROBLEMS AND WORKAROUNDS |
| 4454 | |
4456 | |
| 4455 | =over 4 |
|
|
| 4456 | |
|
|
| 4457 | =item C<errno> reentrancy |
4457 | =head3 C<errno> reentrancy |
| 4458 | |
4458 | |
| 4459 | The default compile environment on Solaris is unfortunately so |
4459 | The default compile environment on Solaris is unfortunately so |
| 4460 | thread-unsafe that you can't even use components/libraries compiled |
4460 | 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, |
4461 | without C<-D_REENTRANT> (as long as they use C<errno>), which, of course, |
| 4462 | isn't defined by default. |
4462 | isn't defined by default. |
| 4463 | |
4463 | |
| 4464 | If you want to use libev in threaded environments you have to make sure |
4464 | If you want to use libev in threaded environments you have to make sure |
| 4465 | it's compiled with C<_REENTRANT> defined. |
4465 | it's compiled with C<_REENTRANT> defined. |
| 4466 | |
4466 | |
| 4467 | =item Event Port Backend |
4467 | =head3 Event port backend |
| 4468 | |
4468 | |
| 4469 | The scalable event interface for Solaris is called "event ports". Unfortunately, |
4469 | 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 |
4470 | 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 |
4471 | 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 |
4472 | all the relevant and latest kernel patches applied. No, I don't know which |
| 4473 | ones, but there are multiple ones. |
4473 | ones, but there are multiple ones. |
| 4474 | |
4474 | |
| 4475 | If you can't get it to work, you can try running the program with |
4475 | If you can't get it to work, you can try running the program by setting |
| 4476 | C<LIBEV_FLAGS=3> to only allow C<poll> and C<select> backends. |
4476 | the environment variable C<LIBEV_FLAGS=3> to only allow C<poll> and |
| 4477 | |
4477 | C<select> backends. |
| 4478 | =back |
|
|
| 4479 | |
4478 | |
| 4480 | =head2 AIX POLL BUG |
4479 | =head2 AIX POLL BUG |
| 4481 | |
4480 | |
| 4482 | AIX unfortunately has a broken C<poll.h> header. Libev works around |
4481 | 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 |
4482 | 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 |
4483 | compiled in), which normally isn't a big problem as C<select> works fine |
| 4485 | with large bitsets, and AIX is dead anyway. |
4484 | with large bitsets, and AIX is dead anyway. |
| 4486 | |
4485 | |
| 4487 | =head2 WIN32 PLATFORM LIMITATIONS AND WORKAROUNDS |
4486 | =head2 WIN32 PLATFORM LIMITATIONS AND WORKAROUNDS |
|
|
4487 | |
|
|
4488 | =head3 General issues |
| 4488 | |
4489 | |
| 4489 | Win32 doesn't support any of the standards (e.g. POSIX) that libev |
4490 | 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 |
4491 | requires, and its I/O model is fundamentally incompatible with the POSIX |
| 4491 | model. Libev still offers limited functionality on this platform in |
4492 | model. Libev still offers limited functionality on this platform in |
| 4492 | the form of the C<EVBACKEND_SELECT> backend, and only supports socket |
4493 | the form of the C<EVBACKEND_SELECT> backend, and only supports socket |
| 4493 | descriptors. This only applies when using Win32 natively, not when using |
4494 | descriptors. This only applies when using Win32 natively, not when using |
| 4494 | e.g. cygwin. |
4495 | e.g. cygwin. Actually, it only applies to the microsofts own compilers, |
|
|
4496 | as every compielr comes with a slightly differently broken/incompatible |
|
|
4497 | environment. |
| 4495 | |
4498 | |
| 4496 | Lifting these limitations would basically require the full |
4499 | Lifting these limitations would basically require the full |
| 4497 | re-implementation of the I/O system. If you are into these kinds of |
4500 | 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 |
4501 | 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). |
4502 | also that glib is the slowest event library known to man). |
| 4500 | |
4503 | |
| 4501 | There is no supported compilation method available on windows except |
4504 | There is no supported compilation method available on windows except |
| 4502 | embedding it into other applications. |
4505 | embedding it into other applications. |
| 4503 | |
4506 | |
| 4504 | Sensible signal handling is officially unsupported by Microsoft - libev |
4507 | 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!): |
4535 | you do I<not> compile the F<ev.c> or any other embedded source files!): |
| 4533 | |
4536 | |
| 4534 | #include "evwrap.h" |
4537 | #include "evwrap.h" |
| 4535 | #include "ev.c" |
4538 | #include "ev.c" |
| 4536 | |
4539 | |
| 4537 | =over 4 |
|
|
| 4538 | |
|
|
| 4539 | =item The winsocket select function |
4540 | =head3 The winsocket C<select> function |
| 4540 | |
4541 | |
| 4541 | The winsocket C<select> function doesn't follow POSIX in that it |
4542 | 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 |
4543 | requires socket I<handles> and not socket I<file descriptors> (it is |
| 4543 | also extremely buggy). This makes select very inefficient, and also |
4544 | also extremely buggy). This makes select very inefficient, and also |
| 4544 | requires a mapping from file descriptors to socket handles (the Microsoft |
4545 | 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 */ |
4554 | #define EV_SELECT_IS_WINSOCKET 1 /* forces EV_SELECT_USE_FD_SET, too */ |
| 4554 | |
4555 | |
| 4555 | Note that winsockets handling of fd sets is O(n), so you can easily get a |
4556 | 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. |
4557 | complexity in the O(n²) range when using win32. |
| 4557 | |
4558 | |
| 4558 | =item Limited number of file descriptors |
4559 | =head3 Limited number of file descriptors |
| 4559 | |
4560 | |
| 4560 | Windows has numerous arbitrary (and low) limits on things. |
4561 | Windows has numerous arbitrary (and low) limits on things. |
| 4561 | |
4562 | |
| 4562 | Early versions of winsocket's select only supported waiting for a maximum |
4563 | 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 |
4564 | 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 |
4579 | 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, |
4580 | (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 |
4581 | 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. |
4582 | the cost of calling select (O(n²)) will likely make this unworkable. |
| 4582 | |
4583 | |
| 4583 | =back |
|
|
| 4584 | |
|
|
| 4585 | =head2 PORTABILITY REQUIREMENTS |
4584 | =head2 PORTABILITY REQUIREMENTS |
| 4586 | |
4585 | |
| 4587 | In addition to a working ISO-C implementation and of course the |
4586 | In addition to a working ISO-C implementation and of course the |
| 4588 | backend-specific APIs, libev relies on a few additional extensions: |
4587 | backend-specific APIs, libev relies on a few additional extensions: |
| 4589 | |
4588 | |
