… | |
… | |
370 | When this flag is specified, then libev will not attempt to use the |
370 | When this flag is specified, then libev will not attempt to use the |
371 | I<inotify> API for it's C<ev_stat> watchers. Apart from debugging and |
371 | I<inotify> API for it's C<ev_stat> watchers. Apart from debugging and |
372 | testing, this flag can be useful to conserve inotify file descriptors, as |
372 | testing, this flag can be useful to conserve inotify file descriptors, as |
373 | otherwise each loop using C<ev_stat> watchers consumes one inotify handle. |
373 | otherwise each loop using C<ev_stat> watchers consumes one inotify handle. |
374 | |
374 | |
375 | =item C<EVFLAG_NOSIGFD> |
375 | =item C<EVFLAG_SIGNALFD> |
376 | |
376 | |
377 | When this flag is specified, then libev will not attempt to use the |
377 | When this flag is specified, then libev will attempt to use the |
378 | I<signalfd> API for it's C<ev_signal> (and C<ev_child>) watchers. This is |
378 | I<signalfd> API for it's C<ev_signal> (and C<ev_child>) watchers. This API |
379 | probably only useful to work around any bugs in libev. Consequently, this |
379 | delivers signals synchronously, which makes it both faster and might make |
380 | flag might go away once the signalfd functionality is considered stable, |
380 | it possible to get the queued signal data. It can also simplify signal |
381 | so it's useful mostly in environment variables and not in program code. |
381 | handling with threads, as long as you properly block signals in your |
|
|
382 | threads that are not interested in handling them. |
|
|
383 | |
|
|
384 | Signalfd will not be used by default as this changes your signal mask, and |
|
|
385 | there are a lot of shoddy libraries and programs (glib's threadpool for |
|
|
386 | example) that can't properly initialise their signal masks. |
382 | |
387 | |
383 | =item C<EVBACKEND_SELECT> (value 1, portable select backend) |
388 | =item C<EVBACKEND_SELECT> (value 1, portable select backend) |
384 | |
389 | |
385 | This is your standard select(2) backend. Not I<completely> standard, as |
390 | This is your standard select(2) backend. Not I<completely> standard, as |
386 | libev tries to roll its own fd_set with no limits on the number of fds, |
391 | libev tries to roll its own fd_set with no limits on the number of fds, |
… | |
… | |
792 | |
797 | |
793 | Ref/unref can be used to add or remove a reference count on the event |
798 | Ref/unref can be used to add or remove a reference count on the event |
794 | loop: Every watcher keeps one reference, and as long as the reference |
799 | loop: Every watcher keeps one reference, and as long as the reference |
795 | count is nonzero, C<ev_loop> will not return on its own. |
800 | count is nonzero, C<ev_loop> will not return on its own. |
796 | |
801 | |
797 | If you have a watcher you never unregister that should not keep C<ev_loop> |
802 | This is useful when you have a watcher that you never intend to |
798 | from returning, call ev_unref() after starting, and ev_ref() before |
803 | unregister, but that nevertheless should not keep C<ev_loop> from |
|
|
804 | returning. In such a case, call C<ev_unref> after starting, and C<ev_ref> |
799 | stopping it. |
805 | before stopping it. |
800 | |
806 | |
801 | As an example, libev itself uses this for its internal signal pipe: It |
807 | As an example, libev itself uses this for its internal signal pipe: It |
802 | is not visible to the libev user and should not keep C<ev_loop> from |
808 | is not visible to the libev user and should not keep C<ev_loop> from |
803 | exiting if no event watchers registered by it are active. It is also an |
809 | exiting if no event watchers registered by it are active. It is also an |
804 | excellent way to do this for generic recurring timers or from within |
810 | excellent way to do this for generic recurring timers or from within |
… | |
… | |
1861 | Returns the remaining time until a timer fires. If the timer is active, |
1867 | Returns the remaining time until a timer fires. If the timer is active, |
1862 | then this time is relative to the current event loop time, otherwise it's |
1868 | then this time is relative to the current event loop time, otherwise it's |
1863 | the timeout value currently configured. |
1869 | the timeout value currently configured. |
1864 | |
1870 | |
1865 | That is, after an C<ev_timer_set (w, 5, 7)>, C<ev_timer_remaining> returns |
1871 | That is, after an C<ev_timer_set (w, 5, 7)>, C<ev_timer_remaining> returns |
1866 | C<5>. When the timer is started and one second passes, C<ev_timer_remain> |
1872 | C<5>. When the timer is started and one second passes, C<ev_timer_remaining> |
1867 | will return C<4>. When the timer expires and is restarted, it will return |
1873 | will return C<4>. When the timer expires and is restarted, it will return |
1868 | roughly C<7> (likely slightly less as callback invocation takes some time, |
1874 | roughly C<7> (likely slightly less as callback invocation takes some time, |
1869 | too), and so on. |
1875 | too), and so on. |
1870 | |
1876 | |
1871 | =item ev_tstamp repeat [read-write] |
1877 | =item ev_tstamp repeat [read-write] |
… | |
… | |
2131 | C<SA_RESTART> (or equivalent) behaviour enabled, so system calls should |
2137 | C<SA_RESTART> (or equivalent) behaviour enabled, so system calls should |
2132 | not be unduly interrupted. If you have a problem with system calls getting |
2138 | not be unduly interrupted. If you have a problem with system calls getting |
2133 | interrupted by signals you can block all signals in an C<ev_check> watcher |
2139 | interrupted by signals you can block all signals in an C<ev_check> watcher |
2134 | and unblock them in an C<ev_prepare> watcher. |
2140 | and unblock them in an C<ev_prepare> watcher. |
2135 | |
2141 | |
2136 | =head3 The special problem of inheritance over execve |
2142 | =head3 The special problem of inheritance over fork/execve/pthread_create |
2137 | |
2143 | |
2138 | Both the signal mask (C<sigprocmask>) and the signal disposition |
2144 | Both the signal mask (C<sigprocmask>) and the signal disposition |
2139 | (C<sigaction>) are unspecified after starting a signal watcher (and after |
2145 | (C<sigaction>) are unspecified after starting a signal watcher (and after |
2140 | stopping it again), that is, libev might or might not block the signal, |
2146 | stopping it again), that is, libev might or might not block the signal, |
2141 | and might or might not set or restore the installed signal handler. |
2147 | and might or might not set or restore the installed signal handler. |
… | |
… | |
2151 | |
2157 | |
2152 | The simplest way to ensure that the signal mask is reset in the child is |
2158 | The simplest way to ensure that the signal mask is reset in the child is |
2153 | to install a fork handler with C<pthread_atfork> that resets it. That will |
2159 | to install a fork handler with C<pthread_atfork> that resets it. That will |
2154 | catch fork calls done by libraries (such as the libc) as well. |
2160 | catch fork calls done by libraries (such as the libc) as well. |
2155 | |
2161 | |
2156 | In current versions of libev, you can also ensure that the signal mask is |
2162 | In current versions of libev, the signal will not be blocked indefinitely |
2157 | not blocking any signals (except temporarily, so thread users watch out) |
2163 | unless you use the C<signalfd> API (C<EV_SIGNALFD>). While this reduces |
2158 | by specifying the C<EVFLAG_NOSIGFD> when creating the event loop. This |
2164 | the window of opportunity for problems, it will not go away, as libev |
2159 | is not guaranteed for future versions, however. |
2165 | I<has> to modify the signal mask, at least temporarily. |
|
|
2166 | |
|
|
2167 | So I can't stress this enough: I<If you do not reset your signal mask when |
|
|
2168 | you expect it to be empty, you have a race condition in your code>. This |
|
|
2169 | is not a libev-specific thing, this is true for most event libraries. |
2160 | |
2170 | |
2161 | =head3 Watcher-Specific Functions and Data Members |
2171 | =head3 Watcher-Specific Functions and Data Members |
2162 | |
2172 | |
2163 | =over 4 |
2173 | =over 4 |
2164 | |
2174 | |
… | |
… | |
3441 | Erkki Seppala has written Ocaml bindings for libev, to be found at |
3451 | Erkki Seppala has written Ocaml bindings for libev, to be found at |
3442 | L<http://modeemi.cs.tut.fi/~flux/software/ocaml-ev/>. |
3452 | L<http://modeemi.cs.tut.fi/~flux/software/ocaml-ev/>. |
3443 | |
3453 | |
3444 | =item Lua |
3454 | =item Lua |
3445 | |
3455 | |
3446 | Brian Maher has written a partial interface to libev |
3456 | Brian Maher has written a partial interface to libev for lua (at the |
3447 | for lua (only C<ev_io> and C<ev_timer>), to be found at |
3457 | time of this writing, only C<ev_io> and C<ev_timer>), to be found at |
3448 | L<http://github.com/brimworks/lua-ev>. |
3458 | L<http://github.com/brimworks/lua-ev>. |
3449 | |
3459 | |
3450 | =back |
3460 | =back |
3451 | |
3461 | |
3452 | |
3462 | |
… | |
… | |
3607 | libev.m4 |
3617 | libev.m4 |
3608 | |
3618 | |
3609 | =head2 PREPROCESSOR SYMBOLS/MACROS |
3619 | =head2 PREPROCESSOR SYMBOLS/MACROS |
3610 | |
3620 | |
3611 | Libev can be configured via a variety of preprocessor symbols you have to |
3621 | Libev can be configured via a variety of preprocessor symbols you have to |
3612 | define before including any of its files. The default in the absence of |
3622 | define before including (or compiling) any of its files. The default in |
3613 | autoconf is documented for every option. |
3623 | the absence of autoconf is documented for every option. |
|
|
3624 | |
|
|
3625 | Symbols marked with "(h)" do not change the ABI, and can have different |
|
|
3626 | values when compiling libev vs. including F<ev.h>, so it is permissible |
|
|
3627 | to redefine them before including F<ev.h> without breakign compatibility |
|
|
3628 | to a compiled library. All other symbols change the ABI, which means all |
|
|
3629 | users of libev and the libev code itself must be compiled with compatible |
|
|
3630 | settings. |
3614 | |
3631 | |
3615 | =over 4 |
3632 | =over 4 |
3616 | |
3633 | |
3617 | =item EV_STANDALONE |
3634 | =item EV_STANDALONE (h) |
3618 | |
3635 | |
3619 | Must always be C<1> if you do not use autoconf configuration, which |
3636 | Must always be C<1> if you do not use autoconf configuration, which |
3620 | keeps libev from including F<config.h>, and it also defines dummy |
3637 | keeps libev from including F<config.h>, and it also defines dummy |
3621 | implementations for some libevent functions (such as logging, which is not |
3638 | implementations for some libevent functions (such as logging, which is not |
3622 | supported). It will also not define any of the structs usually found in |
3639 | supported). It will also not define any of the structs usually found in |
… | |
… | |
3772 | as well as for signal and thread safety in C<ev_async> watchers. |
3789 | as well as for signal and thread safety in C<ev_async> watchers. |
3773 | |
3790 | |
3774 | In the absence of this define, libev will use C<sig_atomic_t volatile> |
3791 | In the absence of this define, libev will use C<sig_atomic_t volatile> |
3775 | (from F<signal.h>), which is usually good enough on most platforms. |
3792 | (from F<signal.h>), which is usually good enough on most platforms. |
3776 | |
3793 | |
3777 | =item EV_H |
3794 | =item EV_H (h) |
3778 | |
3795 | |
3779 | The name of the F<ev.h> header file used to include it. The default if |
3796 | The name of the F<ev.h> header file used to include it. The default if |
3780 | undefined is C<"ev.h"> in F<event.h>, F<ev.c> and F<ev++.h>. This can be |
3797 | undefined is C<"ev.h"> in F<event.h>, F<ev.c> and F<ev++.h>. This can be |
3781 | used to virtually rename the F<ev.h> header file in case of conflicts. |
3798 | used to virtually rename the F<ev.h> header file in case of conflicts. |
3782 | |
3799 | |
3783 | =item EV_CONFIG_H |
3800 | =item EV_CONFIG_H (h) |
3784 | |
3801 | |
3785 | If C<EV_STANDALONE> isn't C<1>, this variable can be used to override |
3802 | If C<EV_STANDALONE> isn't C<1>, this variable can be used to override |
3786 | F<ev.c>'s idea of where to find the F<config.h> file, similarly to |
3803 | F<ev.c>'s idea of where to find the F<config.h> file, similarly to |
3787 | C<EV_H>, above. |
3804 | C<EV_H>, above. |
3788 | |
3805 | |
3789 | =item EV_EVENT_H |
3806 | =item EV_EVENT_H (h) |
3790 | |
3807 | |
3791 | Similarly to C<EV_H>, this macro can be used to override F<event.c>'s idea |
3808 | Similarly to C<EV_H>, this macro can be used to override F<event.c>'s idea |
3792 | of how the F<event.h> header can be found, the default is C<"event.h">. |
3809 | of how the F<event.h> header can be found, the default is C<"event.h">. |
3793 | |
3810 | |
3794 | =item EV_PROTOTYPES |
3811 | =item EV_PROTOTYPES (h) |
3795 | |
3812 | |
3796 | If defined to be C<0>, then F<ev.h> will not define any function |
3813 | If defined to be C<0>, then F<ev.h> will not define any function |
3797 | prototypes, but still define all the structs and other symbols. This is |
3814 | prototypes, but still define all the structs and other symbols. This is |
3798 | occasionally useful if you want to provide your own wrapper functions |
3815 | occasionally useful if you want to provide your own wrapper functions |
3799 | around libev functions. |
3816 | around libev functions. |
… | |
… | |
3849 | =item EV_FORK_ENABLE |
3866 | =item EV_FORK_ENABLE |
3850 | |
3867 | |
3851 | If undefined or defined to be C<1>, then fork watchers are supported. If |
3868 | If undefined or defined to be C<1>, then fork watchers are supported. If |
3852 | defined to be C<0>, then they are not. |
3869 | defined to be C<0>, then they are not. |
3853 | |
3870 | |
|
|
3871 | =item EV_SIGNAL_ENABLE |
|
|
3872 | |
|
|
3873 | If undefined or defined to be C<1>, then signal watchers are supported. If |
|
|
3874 | defined to be C<0>, then they are not. |
|
|
3875 | |
3854 | =item EV_ASYNC_ENABLE |
3876 | =item EV_ASYNC_ENABLE |
3855 | |
3877 | |
3856 | If undefined or defined to be C<1>, then async watchers are supported. If |
3878 | If undefined or defined to be C<1>, then async watchers are supported. If |
3857 | defined to be C<0>, then they are not. |
3879 | defined to be C<0>, then they are not. |
|
|
3880 | |
|
|
3881 | =item EV_CHILD_ENABLE |
|
|
3882 | |
|
|
3883 | If undefined or defined to be C<1> (and C<_WIN32> is not defined), then |
|
|
3884 | child watchers are supported. If defined to be C<0>, then they are not. |
3858 | |
3885 | |
3859 | =item EV_MINIMAL |
3886 | =item EV_MINIMAL |
3860 | |
3887 | |
3861 | If you need to shave off some kilobytes of code at the expense of some |
3888 | If you need to shave off some kilobytes of code at the expense of some |
3862 | speed (but with the full API), define this symbol to C<1>. Currently this |
3889 | speed (but with the full API), define this symbol to C<1>. Currently this |
… | |
… | |
3864 | on amd64. It also selects a much smaller 2-heap for timer management over |
3891 | on amd64. It also selects a much smaller 2-heap for timer management over |
3865 | the default 4-heap. |
3892 | the default 4-heap. |
3866 | |
3893 | |
3867 | You can save even more by disabling watcher types you do not need |
3894 | You can save even more by disabling watcher types you do not need |
3868 | and setting C<EV_MAXPRI> == C<EV_MINPRI>. Also, disabling C<assert> |
3895 | and setting C<EV_MAXPRI> == C<EV_MINPRI>. Also, disabling C<assert> |
3869 | (C<-DNDEBUG>) will usually reduce code size a lot. |
3896 | (C<-DNDEBUG>) will usually reduce code size a lot. Disabling inotify, |
|
|
3897 | eventfd and signalfd will further help, and disabling backends one doesn't |
|
|
3898 | need (e.g. poll, epoll, kqueue, ports) will help further. |
3870 | |
3899 | |
3871 | Defining C<EV_MINIMAL> to C<2> will additionally reduce the core API to |
3900 | Defining C<EV_MINIMAL> to C<2> will additionally reduce the core API to |
3872 | provide a bare-bones event library. See C<ev.h> for details on what parts |
3901 | provide a bare-bones event library. See C<ev.h> for details on what parts |
3873 | of the API are still available, and do not complain if this subset changes |
3902 | of the API are still available, and do not complain if this subset changes |
3874 | over time. |
3903 | over time. |
|
|
3904 | |
|
|
3905 | This example set of settings reduces the compiled size of libev from 24Kb |
|
|
3906 | to 8Kb on my GNU/Linux amd64 system (and leaves little in - there is also |
|
|
3907 | an effect on the amount of memory used). With an intelligent-enough linker |
|
|
3908 | further unused functions might be left out as well automatically. |
|
|
3909 | |
|
|
3910 | // tuning and API changes |
|
|
3911 | #define EV_MINIMAL 2 |
|
|
3912 | #define EV_MULTIPLICITY 0 |
|
|
3913 | #define EV_MINPRI 0 |
|
|
3914 | #define EV_MAXPRI 0 |
|
|
3915 | |
|
|
3916 | // OS-specific backends |
|
|
3917 | #define EV_USE_INOTIFY 0 |
|
|
3918 | #define EV_USE_EVENTFD 0 |
|
|
3919 | #define EV_USE_SIGNALFD 0 |
|
|
3920 | #define EV_USE_REALTIME 0 |
|
|
3921 | #define EV_USE_MONOTONIC 0 |
|
|
3922 | #define EV_USE_CLOCK_SYSCALL 0 |
|
|
3923 | |
|
|
3924 | // disable all backends except select |
|
|
3925 | #define EV_USE_POLL 0 |
|
|
3926 | #define EV_USE_PORT 0 |
|
|
3927 | #define EV_USE_KQUEUE 0 |
|
|
3928 | #define EV_USE_EPOLL 0 |
|
|
3929 | |
|
|
3930 | // disable all watcher types that cna be disabled |
|
|
3931 | #define EV_STAT_ENABLE 0 |
|
|
3932 | #define EV_PERIODIC_ENABLE 0 |
|
|
3933 | #define EV_IDLE_ENABLE 0 |
|
|
3934 | #define EV_FORK_ENABLE 0 |
|
|
3935 | #define EV_SIGNAL_ENABLE 0 |
|
|
3936 | #define EV_CHILD_ENABLE 0 |
|
|
3937 | #define EV_ASYNC_ENABLE 0 |
|
|
3938 | #define EV_EMBED_ENABLE 0 |
|
|
3939 | |
|
|
3940 | =item EV_AVOID_STDIO |
|
|
3941 | |
|
|
3942 | If this is set to C<1> at compiletime, then libev will avoid using stdio |
|
|
3943 | functions (printf, scanf, perror etc.). This will increase the codesize |
|
|
3944 | somewhat, but if your program doesn't otherwise depend on stdio and your |
|
|
3945 | libc allows it, this avoids linking in the stdio library which is quite |
|
|
3946 | big. |
|
|
3947 | |
|
|
3948 | Note that error messages might become less precise when this option is |
|
|
3949 | enabled. |
3875 | |
3950 | |
3876 | =item EV_NSIG |
3951 | =item EV_NSIG |
3877 | |
3952 | |
3878 | The highest supported signal number, +1 (or, the number of |
3953 | The highest supported signal number, +1 (or, the number of |
3879 | signals): Normally, libev tries to deduce the maximum number of signals |
3954 | signals): Normally, libev tries to deduce the maximum number of signals |