… | |
… | |
2123 | Example: Call a callback every hour, or, more precisely, whenever the |
2123 | Example: Call a callback every hour, or, more precisely, whenever the |
2124 | system time is divisible by 3600. The callback invocation times have |
2124 | system time is divisible by 3600. The callback invocation times have |
2125 | potentially a lot of jitter, but good long-term stability. |
2125 | potentially a lot of jitter, but good long-term stability. |
2126 | |
2126 | |
2127 | static void |
2127 | static void |
2128 | clock_cb (struct ev_loop *loop, ev_io *w, int revents) |
2128 | clock_cb (struct ev_loop *loop, ev_periodic *w, int revents) |
2129 | { |
2129 | { |
2130 | ... its now a full hour (UTC, or TAI or whatever your clock follows) |
2130 | ... its now a full hour (UTC, or TAI or whatever your clock follows) |
2131 | } |
2131 | } |
2132 | |
2132 | |
2133 | ev_periodic hourly_tick; |
2133 | ev_periodic hourly_tick; |
… | |
… | |
2965 | C<ev_default_fork> cheats and calls it in the wrong process, the fork |
2965 | C<ev_default_fork> cheats and calls it in the wrong process, the fork |
2966 | handlers will be invoked, too, of course. |
2966 | handlers will be invoked, too, of course. |
2967 | |
2967 | |
2968 | =head3 The special problem of life after fork - how is it possible? |
2968 | =head3 The special problem of life after fork - how is it possible? |
2969 | |
2969 | |
2970 | Most uses of C<fork()> consist of forking, then some simple calls to ste |
2970 | Most uses of C<fork()> consist of forking, then some simple calls to set |
2971 | up/change the process environment, followed by a call to C<exec()>. This |
2971 | up/change the process environment, followed by a call to C<exec()>. This |
2972 | sequence should be handled by libev without any problems. |
2972 | sequence should be handled by libev without any problems. |
2973 | |
2973 | |
2974 | This changes when the application actually wants to do event handling |
2974 | This changes when the application actually wants to do event handling |
2975 | in the child, or both parent in child, in effect "continuing" after the |
2975 | in the child, or both parent in child, in effect "continuing" after the |
… | |
… | |
3009 | believe me. |
3009 | believe me. |
3010 | |
3010 | |
3011 | =back |
3011 | =back |
3012 | |
3012 | |
3013 | |
3013 | |
3014 | =head2 C<ev_async> - how to wake up another event loop |
3014 | =head2 C<ev_async> - how to wake up an event loop |
3015 | |
3015 | |
3016 | In general, you cannot use an C<ev_loop> from multiple threads or other |
3016 | In general, you cannot use an C<ev_loop> from multiple threads or other |
3017 | asynchronous sources such as signal handlers (as opposed to multiple event |
3017 | asynchronous sources such as signal handlers (as opposed to multiple event |
3018 | loops - those are of course safe to use in different threads). |
3018 | loops - those are of course safe to use in different threads). |
3019 | |
3019 | |
3020 | Sometimes, however, you need to wake up another event loop you do not |
3020 | Sometimes, however, you need to wake up an event loop you do not control, |
3021 | control, for example because it belongs to another thread. This is what |
3021 | for example because it belongs to another thread. This is what C<ev_async> |
3022 | C<ev_async> watchers do: as long as the C<ev_async> watcher is active, you |
3022 | watchers do: as long as the C<ev_async> watcher is active, you can signal |
3023 | can signal it by calling C<ev_async_send>, which is thread- and signal |
3023 | it by calling C<ev_async_send>, which is thread- and signal safe. |
3024 | safe. |
|
|
3025 | |
3024 | |
3026 | This functionality is very similar to C<ev_signal> watchers, as signals, |
3025 | This functionality is very similar to C<ev_signal> watchers, as signals, |
3027 | too, are asynchronous in nature, and signals, too, will be compressed |
3026 | too, are asynchronous in nature, and signals, too, will be compressed |
3028 | (i.e. the number of callback invocations may be less than the number of |
3027 | (i.e. the number of callback invocations may be less than the number of |
3029 | C<ev_async_sent> calls). |
3028 | C<ev_async_sent> calls). |
… | |
… | |
4397 | I suggest using suppression lists. |
4396 | I suggest using suppression lists. |
4398 | |
4397 | |
4399 | |
4398 | |
4400 | =head1 PORTABILITY NOTES |
4399 | =head1 PORTABILITY NOTES |
4401 | |
4400 | |
|
|
4401 | =head2 GNU/LINUX 32 BIT LIMITATIONS |
|
|
4402 | |
|
|
4403 | GNU/Linux is the only common platform that supports 64 bit file/large file |
|
|
4404 | interfaces but I<disables> them by default. |
|
|
4405 | |
|
|
4406 | That means that libev compiled in the default environment doesn't support |
|
|
4407 | files larger than 2GiB or so, which mainly affects C<ev_stat> watchers. |
|
|
4408 | |
|
|
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 |
|
|
4411 | standard libev compiled for their system. |
|
|
4412 | |
|
|
4413 | Likewise, libev cannot enable the large file API itself as this would |
|
|
4414 | suddenly make it incompatible to the default compile time environment, |
|
|
4415 | i.e. all programs not using special compile switches. |
|
|
4416 | |
|
|
4417 | =head2 OS/X AND DARWIN BUGS |
|
|
4418 | |
|
|
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 the |
|
|
4421 | OpenGL drivers. |
|
|
4422 | |
|
|
4423 | =head3 C<kqueue> is buggy |
|
|
4424 | |
|
|
4425 | The kqueue syscall is broken in all known versions - most versions support |
|
|
4426 | only sockets, many support pipes. |
|
|
4427 | |
|
|
4428 | Libev tries to work around this by not using C<kqueue> by default on |
|
|
4429 | this rotten platform, but of course you can still ask for it when creating |
|
|
4430 | a loop. |
|
|
4431 | |
|
|
4432 | =head3 C<poll> is buggy |
|
|
4433 | |
|
|
4434 | Instead of fixing C<kqueue>, Apple replaced their (working) C<poll> |
|
|
4435 | implementation by something calling C<kqueue> internally around the 10.5.6 |
|
|
4436 | release, so now C<kqueue> I<and> C<poll> are broken. |
|
|
4437 | |
|
|
4438 | Libev tries to work around this by not using C<poll> by default on |
|
|
4439 | this rotten platform, but of course you can still ask for it when creating |
|
|
4440 | a loop. |
|
|
4441 | |
|
|
4442 | =head3 C<select> is buggy |
|
|
4443 | |
|
|
4444 | All that's left is C<select>, and of course Apple found a way to fuck this |
|
|
4445 | one up as well: On OS/X, C<select> actively limits the number of file |
|
|
4446 | descriptors you can pass in to 1024 - your program suddenyl crashes when |
|
|
4447 | you use more. |
|
|
4448 | |
|
|
4449 | There is an undocumented "workaround" for this - defining |
|
|
4450 | C<_DARWIN_UNLIMITED_SELECT>, which libev tries to use, so select I<should> |
|
|
4451 | work on OS/X. |
|
|
4452 | |
|
|
4453 | =head2 SOLARIS PROBLEMS AND WORKAROUNDS |
|
|
4454 | |
|
|
4455 | =head3 C<errno> reentrancy |
|
|
4456 | |
|
|
4457 | The default compile environment on Solaris is unfortunately so |
|
|
4458 | thread-unsafe that you can't even use components/libraries compiled |
|
|
4459 | without C<-D_REENTRANT> (as long as they use C<errno>), which, of course, |
|
|
4460 | isn't defined by default. |
|
|
4461 | |
|
|
4462 | If you want to use libev in threaded environments you have to make sure |
|
|
4463 | it's compiled with C<_REENTRANT> defined. |
|
|
4464 | |
|
|
4465 | =head3 Event port backend |
|
|
4466 | |
|
|
4467 | The scalable event interface for Solaris is called "event ports". Unfortunately, |
|
|
4468 | this mechanism is very buggy. If you run into high CPU usage, your program |
|
|
4469 | freezes or you get a large number of spurious wakeups, make sure you have |
|
|
4470 | all the relevant and latest kernel patches applied. No, I don't know which |
|
|
4471 | ones, but there are multiple ones. |
|
|
4472 | |
|
|
4473 | If you can't get it to work, you can try running the program with |
|
|
4474 | C<LIBEV_FLAGS=3> to only allow C<poll> and C<select> backends. |
|
|
4475 | |
|
|
4476 | =head2 AIX POLL BUG |
|
|
4477 | |
|
|
4478 | AIX unfortunately has a broken C<poll.h> header. Libev works around |
|
|
4479 | this by trying to avoid the poll backend altogether (i.e. it's not even |
|
|
4480 | compiled in), which normally isn't a big problem as C<select> works fine |
|
|
4481 | with large bitsets, and AIX is dead anyway. |
|
|
4482 | |
4402 | =head2 WIN32 PLATFORM LIMITATIONS AND WORKAROUNDS |
4483 | =head2 WIN32 PLATFORM LIMITATIONS AND WORKAROUNDS |
|
|
4484 | |
|
|
4485 | =head3 General issues |
4403 | |
4486 | |
4404 | Win32 doesn't support any of the standards (e.g. POSIX) that libev |
4487 | Win32 doesn't support any of the standards (e.g. POSIX) that libev |
4405 | requires, and its I/O model is fundamentally incompatible with the POSIX |
4488 | requires, and its I/O model is fundamentally incompatible with the POSIX |
4406 | model. Libev still offers limited functionality on this platform in |
4489 | model. Libev still offers limited functionality on this platform in |
4407 | the form of the C<EVBACKEND_SELECT> backend, and only supports socket |
4490 | the form of the C<EVBACKEND_SELECT> backend, and only supports socket |
4408 | descriptors. This only applies when using Win32 natively, not when using |
4491 | descriptors. This only applies when using Win32 natively, not when using |
4409 | e.g. cygwin. |
4492 | e.g. cygwin. Actually, it only applies to the microsofts own compilers, |
|
|
4493 | as every compielr comes with a slightly differently broken/incompatible |
|
|
4494 | environment. |
4410 | |
4495 | |
4411 | Lifting these limitations would basically require the full |
4496 | Lifting these limitations would basically require the full |
4412 | re-implementation of the I/O system. If you are into these kinds of |
4497 | re-implementation of the I/O system. If you are into this kind of thing, |
4413 | things, then note that glib does exactly that for you in a very portable |
4498 | then note that glib does exactly that for you in a very portable way (note |
4414 | way (note also that glib is the slowest event library known to man). |
4499 | also that glib is the slowest event library known to man). |
4415 | |
4500 | |
4416 | There is no supported compilation method available on windows except |
4501 | There is no supported compilation method available on windows except |
4417 | embedding it into other applications. |
4502 | embedding it into other applications. |
4418 | |
4503 | |
4419 | Sensible signal handling is officially unsupported by Microsoft - libev |
4504 | Sensible signal handling is officially unsupported by Microsoft - libev |
… | |
… | |
4447 | you do I<not> compile the F<ev.c> or any other embedded source files!): |
4532 | you do I<not> compile the F<ev.c> or any other embedded source files!): |
4448 | |
4533 | |
4449 | #include "evwrap.h" |
4534 | #include "evwrap.h" |
4450 | #include "ev.c" |
4535 | #include "ev.c" |
4451 | |
4536 | |
4452 | =over 4 |
|
|
4453 | |
|
|
4454 | =item The winsocket select function |
4537 | =head3 The winsocket C<select> function |
4455 | |
4538 | |
4456 | The winsocket C<select> function doesn't follow POSIX in that it |
4539 | The winsocket C<select> function doesn't follow POSIX in that it |
4457 | requires socket I<handles> and not socket I<file descriptors> (it is |
4540 | requires socket I<handles> and not socket I<file descriptors> (it is |
4458 | also extremely buggy). This makes select very inefficient, and also |
4541 | also extremely buggy). This makes select very inefficient, and also |
4459 | requires a mapping from file descriptors to socket handles (the Microsoft |
4542 | requires a mapping from file descriptors to socket handles (the Microsoft |
… | |
… | |
4468 | #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 */ |
4469 | |
4552 | |
4470 | Note that winsockets handling of fd sets is O(n), so you can easily get a |
4553 | Note that winsockets handling of fd sets is O(n), so you can easily get a |
4471 | complexity in the O(n²) range when using win32. |
4554 | complexity in the O(n²) range when using win32. |
4472 | |
4555 | |
4473 | =item Limited number of file descriptors |
4556 | =head3 Limited number of file descriptors |
4474 | |
4557 | |
4475 | Windows has numerous arbitrary (and low) limits on things. |
4558 | Windows has numerous arbitrary (and low) limits on things. |
4476 | |
4559 | |
4477 | Early versions of winsocket's select only supported waiting for a maximum |
4560 | Early versions of winsocket's select only supported waiting for a maximum |
4478 | of C<64> handles (probably owning to the fact that all windows kernels |
4561 | of C<64> handles (probably owning to the fact that all windows kernels |
… | |
… | |
4493 | runtime libraries. This might get you to about C<512> or C<2048> sockets |
4576 | runtime libraries. This might get you to about C<512> or C<2048> sockets |
4494 | (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, |
4495 | you need to wrap all I/O functions and provide your own fd management, but |
4578 | you need to wrap all I/O functions and provide your own fd management, but |
4496 | the cost of calling select (O(n²)) will likely make this unworkable. |
4579 | the cost of calling select (O(n²)) will likely make this unworkable. |
4497 | |
4580 | |
4498 | =back |
|
|
4499 | |
|
|
4500 | =head2 PORTABILITY REQUIREMENTS |
4581 | =head2 PORTABILITY REQUIREMENTS |
4501 | |
4582 | |
4502 | In addition to a working ISO-C implementation and of course the |
4583 | In addition to a working ISO-C implementation and of course the |
4503 | backend-specific APIs, libev relies on a few additional extensions: |
4584 | backend-specific APIs, libev relies on a few additional extensions: |
4504 | |
4585 | |