… | |
… | |
1538 | |
1538 | |
1539 | So when you encounter spurious, unexplained daemon exits, make sure you |
1539 | So when you encounter spurious, unexplained daemon exits, make sure you |
1540 | ignore SIGPIPE (and maybe make sure you log the exit status of your daemon |
1540 | ignore SIGPIPE (and maybe make sure you log the exit status of your daemon |
1541 | somewhere, as that would have given you a big clue). |
1541 | somewhere, as that would have given you a big clue). |
1542 | |
1542 | |
|
|
1543 | =head3 The special problem of accept()ing when you can't |
|
|
1544 | |
|
|
1545 | Many implementations of the POSIX C<accept> function (for example, |
|
|
1546 | found in port-2004 Linux) have the peculiar behaviour of not removing a |
|
|
1547 | connection from the pending queue in all error cases. |
|
|
1548 | |
|
|
1549 | For example, larger servers often run out of file descriptors (because |
|
|
1550 | of resource limits), causing C<accept> to fail with C<ENFILE> but not |
|
|
1551 | rejecting the connection, leading to libev signalling readiness on |
|
|
1552 | the next iteration again (the connection still exists after all), and |
|
|
1553 | typically causing the program to loop at 100% CPU usage. |
|
|
1554 | |
|
|
1555 | Unfortunately, the set of errors that cause this issue differs between |
|
|
1556 | operating systems, there is usually little the app can do to remedy the |
|
|
1557 | situation, and no known thread-safe method of removing the connection to |
|
|
1558 | cope with overload is known (to me). |
|
|
1559 | |
|
|
1560 | One of the easiest ways to handle this situation is to just ignore it |
|
|
1561 | - when the program encounters an overload, it will just loop until the |
|
|
1562 | situation is over. While this is a form of busy waiting, no OS offers an |
|
|
1563 | event-based way to handle this situation, so it's the best one can do. |
|
|
1564 | |
|
|
1565 | A better way to handle the situation is to log any errors other than |
|
|
1566 | C<EAGAIN> and C<EWOULDBLOCK>, making sure not to flood the log with such |
|
|
1567 | messages, and continue as usual, which at least gives the user an idea of |
|
|
1568 | what could be wrong ("raise the ulimit!"). For extra points one could stop |
|
|
1569 | the C<ev_io> watcher on the listening fd "for a while", which reduces CPU |
|
|
1570 | usage. |
|
|
1571 | |
|
|
1572 | If your program is single-threaded, then you could also keep a dummy file |
|
|
1573 | descriptor for overload situations (e.g. by opening F</dev/null>), and |
|
|
1574 | when you run into C<ENFILE> or C<EMFILE>, close it, run C<accept>, |
|
|
1575 | close that fd, and create a new dummy fd. This will gracefully refuse |
|
|
1576 | clients under typical overload conditions. |
|
|
1577 | |
|
|
1578 | The last way to handle it is to simply log the error and C<exit>, as |
|
|
1579 | is often done with C<malloc> failures, but this results in an easy |
|
|
1580 | opportunity for a DoS attack. |
1543 | |
1581 | |
1544 | =head3 Watcher-Specific Functions |
1582 | =head3 Watcher-Specific Functions |
1545 | |
1583 | |
1546 | =over 4 |
1584 | =over 4 |
1547 | |
1585 | |
… | |
… | |
1867 | Returns the remaining time until a timer fires. If the timer is active, |
1905 | Returns the remaining time until a timer fires. If the timer is active, |
1868 | then this time is relative to the current event loop time, otherwise it's |
1906 | then this time is relative to the current event loop time, otherwise it's |
1869 | the timeout value currently configured. |
1907 | the timeout value currently configured. |
1870 | |
1908 | |
1871 | That is, after an C<ev_timer_set (w, 5, 7)>, C<ev_timer_remaining> returns |
1909 | That is, after an C<ev_timer_set (w, 5, 7)>, C<ev_timer_remaining> returns |
1872 | C<5>. When the timer is started and one second passes, C<ev_timer_remain> |
1910 | C<5>. When the timer is started and one second passes, C<ev_timer_remaining> |
1873 | will return C<4>. When the timer expires and is restarted, it will return |
1911 | will return C<4>. When the timer expires and is restarted, it will return |
1874 | roughly C<7> (likely slightly less as callback invocation takes some time, |
1912 | roughly C<7> (likely slightly less as callback invocation takes some time, |
1875 | too), and so on. |
1913 | too), and so on. |
1876 | |
1914 | |
1877 | =item ev_tstamp repeat [read-write] |
1915 | =item ev_tstamp repeat [read-write] |
… | |
… | |
3617 | libev.m4 |
3655 | libev.m4 |
3618 | |
3656 | |
3619 | =head2 PREPROCESSOR SYMBOLS/MACROS |
3657 | =head2 PREPROCESSOR SYMBOLS/MACROS |
3620 | |
3658 | |
3621 | Libev can be configured via a variety of preprocessor symbols you have to |
3659 | Libev can be configured via a variety of preprocessor symbols you have to |
3622 | define before including any of its files. The default in the absence of |
3660 | define before including (or compiling) any of its files. The default in |
3623 | autoconf is documented for every option. |
3661 | the absence of autoconf is documented for every option. |
|
|
3662 | |
|
|
3663 | Symbols marked with "(h)" do not change the ABI, and can have different |
|
|
3664 | values when compiling libev vs. including F<ev.h>, so it is permissible |
|
|
3665 | to redefine them before including F<ev.h> without breakign compatibility |
|
|
3666 | to a compiled library. All other symbols change the ABI, which means all |
|
|
3667 | users of libev and the libev code itself must be compiled with compatible |
|
|
3668 | settings. |
3624 | |
3669 | |
3625 | =over 4 |
3670 | =over 4 |
3626 | |
3671 | |
3627 | =item EV_STANDALONE |
3672 | =item EV_STANDALONE (h) |
3628 | |
3673 | |
3629 | Must always be C<1> if you do not use autoconf configuration, which |
3674 | Must always be C<1> if you do not use autoconf configuration, which |
3630 | keeps libev from including F<config.h>, and it also defines dummy |
3675 | keeps libev from including F<config.h>, and it also defines dummy |
3631 | implementations for some libevent functions (such as logging, which is not |
3676 | implementations for some libevent functions (such as logging, which is not |
3632 | supported). It will also not define any of the structs usually found in |
3677 | supported). It will also not define any of the structs usually found in |
… | |
… | |
3782 | as well as for signal and thread safety in C<ev_async> watchers. |
3827 | as well as for signal and thread safety in C<ev_async> watchers. |
3783 | |
3828 | |
3784 | In the absence of this define, libev will use C<sig_atomic_t volatile> |
3829 | In the absence of this define, libev will use C<sig_atomic_t volatile> |
3785 | (from F<signal.h>), which is usually good enough on most platforms. |
3830 | (from F<signal.h>), which is usually good enough on most platforms. |
3786 | |
3831 | |
3787 | =item EV_H |
3832 | =item EV_H (h) |
3788 | |
3833 | |
3789 | The name of the F<ev.h> header file used to include it. The default if |
3834 | The name of the F<ev.h> header file used to include it. The default if |
3790 | undefined is C<"ev.h"> in F<event.h>, F<ev.c> and F<ev++.h>. This can be |
3835 | undefined is C<"ev.h"> in F<event.h>, F<ev.c> and F<ev++.h>. This can be |
3791 | used to virtually rename the F<ev.h> header file in case of conflicts. |
3836 | used to virtually rename the F<ev.h> header file in case of conflicts. |
3792 | |
3837 | |
3793 | =item EV_CONFIG_H |
3838 | =item EV_CONFIG_H (h) |
3794 | |
3839 | |
3795 | If C<EV_STANDALONE> isn't C<1>, this variable can be used to override |
3840 | If C<EV_STANDALONE> isn't C<1>, this variable can be used to override |
3796 | F<ev.c>'s idea of where to find the F<config.h> file, similarly to |
3841 | F<ev.c>'s idea of where to find the F<config.h> file, similarly to |
3797 | C<EV_H>, above. |
3842 | C<EV_H>, above. |
3798 | |
3843 | |
3799 | =item EV_EVENT_H |
3844 | =item EV_EVENT_H (h) |
3800 | |
3845 | |
3801 | Similarly to C<EV_H>, this macro can be used to override F<event.c>'s idea |
3846 | Similarly to C<EV_H>, this macro can be used to override F<event.c>'s idea |
3802 | of how the F<event.h> header can be found, the default is C<"event.h">. |
3847 | of how the F<event.h> header can be found, the default is C<"event.h">. |
3803 | |
3848 | |
3804 | =item EV_PROTOTYPES |
3849 | =item EV_PROTOTYPES (h) |
3805 | |
3850 | |
3806 | If defined to be C<0>, then F<ev.h> will not define any function |
3851 | If defined to be C<0>, then F<ev.h> will not define any function |
3807 | prototypes, but still define all the structs and other symbols. This is |
3852 | prototypes, but still define all the structs and other symbols. This is |
3808 | occasionally useful if you want to provide your own wrapper functions |
3853 | occasionally useful if you want to provide your own wrapper functions |
3809 | around libev functions. |
3854 | around libev functions. |
… | |
… | |
3831 | fine. |
3876 | fine. |
3832 | |
3877 | |
3833 | If your embedding application does not need any priorities, defining these |
3878 | If your embedding application does not need any priorities, defining these |
3834 | both to C<0> will save some memory and CPU. |
3879 | both to C<0> will save some memory and CPU. |
3835 | |
3880 | |
3836 | =item EV_PERIODIC_ENABLE |
3881 | =item EV_PERIODIC_ENABLE, EV_IDLE_ENABLE, EV_EMBED_ENABLE, EV_STAT_ENABLE, |
|
|
3882 | EV_PREPARE_ENABLE, EV_CHECK_ENABLE, EV_FORK_ENABLE, EV_SIGNAL_ENABLE, |
|
|
3883 | EV_ASYNC_ENABLE, EV_CHILD_ENABLE. |
3837 | |
3884 | |
3838 | If undefined or defined to be C<1>, then periodic timers are supported. If |
3885 | If undefined or defined to be C<1> (and the platform supports it), then |
3839 | defined to be C<0>, then they are not. Disabling them saves a few kB of |
3886 | the respective watcher type is supported. If defined to be C<0>, then it |
3840 | code. |
3887 | is not. Disabling watcher types mainly saves codesize. |
3841 | |
|
|
3842 | =item EV_IDLE_ENABLE |
|
|
3843 | |
|
|
3844 | If undefined or defined to be C<1>, then idle watchers are supported. If |
|
|
3845 | defined to be C<0>, then they are not. Disabling them saves a few kB of |
|
|
3846 | code. |
|
|
3847 | |
|
|
3848 | =item EV_EMBED_ENABLE |
|
|
3849 | |
|
|
3850 | If undefined or defined to be C<1>, then embed watchers are supported. If |
|
|
3851 | defined to be C<0>, then they are not. Embed watchers rely on most other |
|
|
3852 | watcher types, which therefore must not be disabled. |
|
|
3853 | |
|
|
3854 | =item EV_STAT_ENABLE |
|
|
3855 | |
|
|
3856 | If undefined or defined to be C<1>, then stat watchers are supported. If |
|
|
3857 | defined to be C<0>, then they are not. |
|
|
3858 | |
|
|
3859 | =item EV_FORK_ENABLE |
|
|
3860 | |
|
|
3861 | If undefined or defined to be C<1>, then fork watchers are supported. If |
|
|
3862 | defined to be C<0>, then they are not. |
|
|
3863 | |
|
|
3864 | =item EV_ASYNC_ENABLE |
|
|
3865 | |
|
|
3866 | If undefined or defined to be C<1>, then async watchers are supported. If |
|
|
3867 | defined to be C<0>, then they are not. |
|
|
3868 | |
3888 | |
3869 | =item EV_MINIMAL |
3889 | =item EV_MINIMAL |
3870 | |
3890 | |
3871 | If you need to shave off some kilobytes of code at the expense of some |
3891 | If you need to shave off some kilobytes of code at the expense of some |
3872 | speed (but with the full API), define this symbol to C<1>. Currently this |
3892 | speed (but with the full API), define this symbol to C<1>. Currently this |
… | |
… | |
3874 | on amd64. It also selects a much smaller 2-heap for timer management over |
3894 | on amd64. It also selects a much smaller 2-heap for timer management over |
3875 | the default 4-heap. |
3895 | the default 4-heap. |
3876 | |
3896 | |
3877 | You can save even more by disabling watcher types you do not need |
3897 | You can save even more by disabling watcher types you do not need |
3878 | and setting C<EV_MAXPRI> == C<EV_MINPRI>. Also, disabling C<assert> |
3898 | and setting C<EV_MAXPRI> == C<EV_MINPRI>. Also, disabling C<assert> |
3879 | (C<-DNDEBUG>) will usually reduce code size a lot. |
3899 | (C<-DNDEBUG>) will usually reduce code size a lot. Disabling inotify, |
|
|
3900 | eventfd and signalfd will further help, and disabling backends one doesn't |
|
|
3901 | need (e.g. poll, epoll, kqueue, ports) will help further. |
3880 | |
3902 | |
3881 | Defining C<EV_MINIMAL> to C<2> will additionally reduce the core API to |
3903 | Defining C<EV_MINIMAL> to C<2> will additionally reduce the core API to |
3882 | provide a bare-bones event library. See C<ev.h> for details on what parts |
3904 | provide a bare-bones event library. See C<ev.h> for details on what parts |
3883 | of the API are still available, and do not complain if this subset changes |
3905 | of the API are still available, and do not complain if this subset changes |
3884 | over time. |
3906 | over time. |
|
|
3907 | |
|
|
3908 | This example set of settings reduces the compiled size of libev from |
|
|
3909 | 23.9Kb to 7.7Kb on my GNU/Linux amd64 system (and leaves little |
|
|
3910 | in - there is also an effect on the amount of memory used). With |
|
|
3911 | an intelligent-enough linker (gcc+binutils do this when you use |
|
|
3912 | C<-Wl,--gc-sections -ffunction-sections>) further unused functions might |
|
|
3913 | be left out as well automatically - a binary starting a timer and an I/O |
|
|
3914 | watcher then might come out at only 5Kb. |
|
|
3915 | |
|
|
3916 | // tuning and API changes |
|
|
3917 | #define EV_MINIMAL 2 |
|
|
3918 | #define EV_MULTIPLICITY 0 |
|
|
3919 | #define EV_MINPRI 0 |
|
|
3920 | #define EV_MAXPRI 0 |
|
|
3921 | |
|
|
3922 | // OS-specific backends |
|
|
3923 | #define EV_USE_INOTIFY 0 |
|
|
3924 | #define EV_USE_EVENTFD 0 |
|
|
3925 | #define EV_USE_SIGNALFD 0 |
|
|
3926 | #define EV_USE_REALTIME 0 |
|
|
3927 | #define EV_USE_MONOTONIC 0 |
|
|
3928 | #define EV_USE_CLOCK_SYSCALL 0 |
|
|
3929 | |
|
|
3930 | // disable all backends except select |
|
|
3931 | #define EV_USE_POLL 0 |
|
|
3932 | #define EV_USE_PORT 0 |
|
|
3933 | #define EV_USE_KQUEUE 0 |
|
|
3934 | #define EV_USE_EPOLL 0 |
|
|
3935 | |
|
|
3936 | // disable all watcher types that cna be disabled |
|
|
3937 | #define EV_STAT_ENABLE 0 |
|
|
3938 | #define EV_PERIODIC_ENABLE 0 |
|
|
3939 | #define EV_IDLE_ENABLE 0 |
|
|
3940 | #define EV_CHECK_ENABLE 0 |
|
|
3941 | #define EV_PREPARE_ENABLE 0 |
|
|
3942 | #define EV_FORK_ENABLE 0 |
|
|
3943 | #define EV_SIGNAL_ENABLE 0 |
|
|
3944 | #define EV_CHILD_ENABLE 0 |
|
|
3945 | #define EV_ASYNC_ENABLE 0 |
|
|
3946 | #define EV_EMBED_ENABLE 0 |
|
|
3947 | |
|
|
3948 | =item EV_AVOID_STDIO |
|
|
3949 | |
|
|
3950 | If this is set to C<1> at compiletime, then libev will avoid using stdio |
|
|
3951 | functions (printf, scanf, perror etc.). This will increase the codesize |
|
|
3952 | somewhat, but if your program doesn't otherwise depend on stdio and your |
|
|
3953 | libc allows it, this avoids linking in the stdio library which is quite |
|
|
3954 | big. |
|
|
3955 | |
|
|
3956 | Note that error messages might become less precise when this option is |
|
|
3957 | enabled. |
3885 | |
3958 | |
3886 | =item EV_NSIG |
3959 | =item EV_NSIG |
3887 | |
3960 | |
3888 | The highest supported signal number, +1 (or, the number of |
3961 | The highest supported signal number, +1 (or, the number of |
3889 | signals): Normally, libev tries to deduce the maximum number of signals |
3962 | signals): Normally, libev tries to deduce the maximum number of signals |