… | |
… | |
122 | .\} |
122 | .\} |
123 | .rm #[ #] #H #V #F C |
123 | .rm #[ #] #H #V #F C |
124 | .\" ======================================================================== |
124 | .\" ======================================================================== |
125 | .\" |
125 | .\" |
126 | .IX Title "LIBEV 3" |
126 | .IX Title "LIBEV 3" |
127 | .TH LIBEV 3 "2009-07-15" "libev-3.7" "libev - high performance full featured event loop" |
127 | .TH LIBEV 3 "2009-07-27" "libev-3.8" "libev - high performance full featured event loop" |
128 | .\" For nroff, turn off justification. Always turn off hyphenation; it makes |
128 | .\" For nroff, turn off justification. Always turn off hyphenation; it makes |
129 | .\" way too many mistakes in technical documents. |
129 | .\" way too many mistakes in technical documents. |
130 | .if n .ad l |
130 | .if n .ad l |
131 | .nh |
131 | .nh |
132 | .SH "NAME" |
132 | .SH "NAME" |
… | |
… | |
227 | .SS "\s-1FEATURES\s0" |
227 | .SS "\s-1FEATURES\s0" |
228 | .IX Subsection "FEATURES" |
228 | .IX Subsection "FEATURES" |
229 | Libev supports \f(CW\*(C`select\*(C'\fR, \f(CW\*(C`poll\*(C'\fR, the Linux-specific \f(CW\*(C`epoll\*(C'\fR, the |
229 | Libev supports \f(CW\*(C`select\*(C'\fR, \f(CW\*(C`poll\*(C'\fR, the Linux-specific \f(CW\*(C`epoll\*(C'\fR, the |
230 | BSD-specific \f(CW\*(C`kqueue\*(C'\fR and the Solaris-specific event port mechanisms |
230 | BSD-specific \f(CW\*(C`kqueue\*(C'\fR and the Solaris-specific event port mechanisms |
231 | for file descriptor events (\f(CW\*(C`ev_io\*(C'\fR), the Linux \f(CW\*(C`inotify\*(C'\fR interface |
231 | for file descriptor events (\f(CW\*(C`ev_io\*(C'\fR), the Linux \f(CW\*(C`inotify\*(C'\fR interface |
232 | (for \f(CW\*(C`ev_stat\*(C'\fR), relative timers (\f(CW\*(C`ev_timer\*(C'\fR), absolute timers |
232 | (for \f(CW\*(C`ev_stat\*(C'\fR), Linux eventfd/signalfd (for faster and cleaner |
233 | with customised rescheduling (\f(CW\*(C`ev_periodic\*(C'\fR), synchronous signals |
233 | inter-thread wakeup (\f(CW\*(C`ev_async\*(C'\fR)/signal handling (\f(CW\*(C`ev_signal\*(C'\fR)) relative |
234 | (\f(CW\*(C`ev_signal\*(C'\fR), process status change events (\f(CW\*(C`ev_child\*(C'\fR), and event |
234 | timers (\f(CW\*(C`ev_timer\*(C'\fR), absolute timers with customised rescheduling |
235 | watchers dealing with the event loop mechanism itself (\f(CW\*(C`ev_idle\*(C'\fR, |
235 | (\f(CW\*(C`ev_periodic\*(C'\fR), synchronous signals (\f(CW\*(C`ev_signal\*(C'\fR), process status |
236 | \&\f(CW\*(C`ev_embed\*(C'\fR, \f(CW\*(C`ev_prepare\*(C'\fR and \f(CW\*(C`ev_check\*(C'\fR watchers) as well as |
236 | change events (\f(CW\*(C`ev_child\*(C'\fR), and event watchers dealing with the event |
237 | file watchers (\f(CW\*(C`ev_stat\*(C'\fR) and even limited support for fork events |
237 | loop mechanism itself (\f(CW\*(C`ev_idle\*(C'\fR, \f(CW\*(C`ev_embed\*(C'\fR, \f(CW\*(C`ev_prepare\*(C'\fR and |
238 | (\f(CW\*(C`ev_fork\*(C'\fR). |
238 | \&\f(CW\*(C`ev_check\*(C'\fR watchers) as well as file watchers (\f(CW\*(C`ev_stat\*(C'\fR) and even |
|
|
239 | limited support for fork events (\f(CW\*(C`ev_fork\*(C'\fR). |
239 | .PP |
240 | .PP |
240 | It also is quite fast (see this |
241 | It also is quite fast (see this |
241 | <benchmark> comparing it to libevent |
242 | <benchmark> comparing it to libevent |
242 | for example). |
243 | for example). |
243 | .SS "\s-1CONVENTIONS\s0" |
244 | .SS "\s-1CONVENTIONS\s0" |
… | |
… | |
478 | forget about forgetting to tell libev about forking) when you use this |
479 | forget about forgetting to tell libev about forking) when you use this |
479 | flag. |
480 | flag. |
480 | .Sp |
481 | .Sp |
481 | This flag setting cannot be overridden or specified in the \f(CW\*(C`LIBEV_FLAGS\*(C'\fR |
482 | This flag setting cannot be overridden or specified in the \f(CW\*(C`LIBEV_FLAGS\*(C'\fR |
482 | environment variable. |
483 | environment variable. |
|
|
484 | .ie n .IP """EVFLAG_NOINOTIFY""" 4 |
|
|
485 | .el .IP "\f(CWEVFLAG_NOINOTIFY\fR" 4 |
|
|
486 | .IX Item "EVFLAG_NOINOTIFY" |
|
|
487 | When this flag is specified, then libev will not attempt to use the |
|
|
488 | \&\fIinotify\fR \s-1API\s0 for it's \f(CW\*(C`ev_stat\*(C'\fR watchers. Apart from debugging and |
|
|
489 | testing, this flag can be useful to conserve inotify file descriptors, as |
|
|
490 | otherwise each loop using \f(CW\*(C`ev_stat\*(C'\fR watchers consumes one inotify handle. |
|
|
491 | .ie n .IP """EVFLAG_NOSIGNALFD""" 4 |
|
|
492 | .el .IP "\f(CWEVFLAG_NOSIGNALFD\fR" 4 |
|
|
493 | .IX Item "EVFLAG_NOSIGNALFD" |
|
|
494 | When this flag is specified, then libev will not attempt to use the |
|
|
495 | \&\fIsignalfd\fR \s-1API\s0 for it's \f(CW\*(C`ev_signal\*(C'\fR (and \f(CW\*(C`ev_child\*(C'\fR) watchers. This is |
|
|
496 | probably only useful to work around any bugs in libev. Consequently, this |
|
|
497 | flag might go away once the signalfd functionality is considered stable, |
|
|
498 | so it's useful mostly in environment variables and not in program code. |
483 | .ie n .IP """EVBACKEND_SELECT"" (value 1, portable select backend)" 4 |
499 | .ie n .IP """EVBACKEND_SELECT"" (value 1, portable select backend)" 4 |
484 | .el .IP "\f(CWEVBACKEND_SELECT\fR (value 1, portable select backend)" 4 |
500 | .el .IP "\f(CWEVBACKEND_SELECT\fR (value 1, portable select backend)" 4 |
485 | .IX Item "EVBACKEND_SELECT (value 1, portable select backend)" |
501 | .IX Item "EVBACKEND_SELECT (value 1, portable select backend)" |
486 | This is your standard \fIselect\fR\|(2) backend. Not \fIcompletely\fR standard, as |
502 | This is your standard \fIselect\fR\|(2) backend. Not \fIcompletely\fR standard, as |
487 | libev tries to roll its own fd_set with no limits on the number of fds, |
503 | libev tries to roll its own fd_set with no limits on the number of fds, |
… | |
… | |
635 | .Sp |
651 | .Sp |
636 | It is definitely not recommended to use this flag. |
652 | It is definitely not recommended to use this flag. |
637 | .RE |
653 | .RE |
638 | .RS 4 |
654 | .RS 4 |
639 | .Sp |
655 | .Sp |
640 | If one or more of these are or'ed into the flags value, then only these |
656 | If one or more of the backend flags are or'ed into the flags value, |
641 | backends will be tried (in the reverse order as listed here). If none are |
657 | then only these backends will be tried (in the reverse order as listed |
642 | specified, all backends in \f(CW\*(C`ev_recommended_backends ()\*(C'\fR will be tried. |
658 | here). If none are specified, all backends in \f(CW\*(C`ev_recommended_backends |
|
|
659 | ()\*(C'\fR will be tried. |
643 | .Sp |
660 | .Sp |
644 | Example: This is the most typical usage. |
661 | Example: This is the most typical usage. |
645 | .Sp |
662 | .Sp |
646 | .Vb 2 |
663 | .Vb 2 |
647 | \& if (!ev_default_loop (0)) |
664 | \& if (!ev_default_loop (0)) |
… | |
… | |
2217 | Signal watchers will trigger an event when the process receives a specific |
2234 | Signal watchers will trigger an event when the process receives a specific |
2218 | signal one or more times. Even though signals are very asynchronous, libev |
2235 | signal one or more times. Even though signals are very asynchronous, libev |
2219 | will try it's best to deliver signals synchronously, i.e. as part of the |
2236 | will try it's best to deliver signals synchronously, i.e. as part of the |
2220 | normal event processing, like any other event. |
2237 | normal event processing, like any other event. |
2221 | .PP |
2238 | .PP |
2222 | If you want signals asynchronously, just use \f(CW\*(C`sigaction\*(C'\fR as you would |
2239 | If you want signals to be delivered truly asynchronously, just use |
2223 | do without libev and forget about sharing the signal. You can even use |
2240 | \&\f(CW\*(C`sigaction\*(C'\fR as you would do without libev and forget about sharing |
2224 | \&\f(CW\*(C`ev_async\*(C'\fR from a signal handler to synchronously wake up an event loop. |
2241 | the signal. You can even use \f(CW\*(C`ev_async\*(C'\fR from a signal handler to |
|
|
2242 | synchronously wake up an event loop. |
2225 | .PP |
2243 | .PP |
2226 | You can configure as many watchers as you like per signal. Only when the |
2244 | You can configure as many watchers as you like for the same signal, but |
|
|
2245 | only within the same loop, i.e. you can watch for \f(CW\*(C`SIGINT\*(C'\fR in your |
|
|
2246 | default loop and for \f(CW\*(C`SIGIO\*(C'\fR in another loop, but you cannot watch for |
|
|
2247 | \&\f(CW\*(C`SIGINT\*(C'\fR in both the default loop and another loop at the same time. At |
|
|
2248 | the moment, \f(CW\*(C`SIGCHLD\*(C'\fR is permanently tied to the default loop. |
|
|
2249 | .PP |
2227 | first watcher gets started will libev actually register a signal handler |
2250 | When the first watcher gets started will libev actually register something |
2228 | with the kernel (thus it coexists with your own signal handlers as long as |
2251 | with the kernel (thus it coexists with your own signal handlers as long as |
2229 | you don't register any with libev for the same signal). Similarly, when |
2252 | you don't register any with libev for the same signal). |
2230 | the last signal watcher for a signal is stopped, libev will reset the |
2253 | .PP |
2231 | signal handler to \s-1SIG_DFL\s0 (regardless of what it was set to before). |
2254 | Both the signal mask state (\f(CW\*(C`sigprocmask\*(C'\fR) and the signal handler state |
|
|
2255 | (\f(CW\*(C`sigaction\*(C'\fR) are unspecified after starting a signal watcher (and after |
|
|
2256 | sotpping it again), that is, libev might or might not block the signal, |
|
|
2257 | and might or might not set or restore the installed signal handler. |
2232 | .PP |
2258 | .PP |
2233 | If possible and supported, libev will install its handlers with |
2259 | If possible and supported, libev will install its handlers with |
2234 | \&\f(CW\*(C`SA_RESTART\*(C'\fR behaviour enabled, so system calls should not be unduly |
2260 | \&\f(CW\*(C`SA_RESTART\*(C'\fR (or equivalent) behaviour enabled, so system calls should |
2235 | interrupted. If you have a problem with system calls getting interrupted by |
2261 | not be unduly interrupted. If you have a problem with system calls getting |
2236 | signals you can block all signals in an \f(CW\*(C`ev_check\*(C'\fR watcher and unblock |
2262 | interrupted by signals you can block all signals in an \f(CW\*(C`ev_check\*(C'\fR watcher |
2237 | them in an \f(CW\*(C`ev_prepare\*(C'\fR watcher. |
2263 | and unblock them in an \f(CW\*(C`ev_prepare\*(C'\fR watcher. |
2238 | .PP |
2264 | .PP |
2239 | \fIWatcher-Specific Functions and Data Members\fR |
2265 | \fIWatcher-Specific Functions and Data Members\fR |
2240 | .IX Subsection "Watcher-Specific Functions and Data Members" |
2266 | .IX Subsection "Watcher-Specific Functions and Data Members" |
2241 | .IP "ev_signal_init (ev_signal *, callback, int signum)" 4 |
2267 | .IP "ev_signal_init (ev_signal *, callback, int signum)" 4 |
2242 | .IX Item "ev_signal_init (ev_signal *, callback, int signum)" |
2268 | .IX Item "ev_signal_init (ev_signal *, callback, int signum)" |
… | |
… | |
2287 | .PP |
2313 | .PP |
2288 | \fIProcess Interaction\fR |
2314 | \fIProcess Interaction\fR |
2289 | .IX Subsection "Process Interaction" |
2315 | .IX Subsection "Process Interaction" |
2290 | .PP |
2316 | .PP |
2291 | Libev grabs \f(CW\*(C`SIGCHLD\*(C'\fR as soon as the default event loop is |
2317 | Libev grabs \f(CW\*(C`SIGCHLD\*(C'\fR as soon as the default event loop is |
2292 | initialised. This is necessary to guarantee proper behaviour even if |
2318 | initialised. This is necessary to guarantee proper behaviour even if the |
2293 | the first child watcher is started after the child exits. The occurrence |
2319 | first child watcher is started after the child exits. The occurrence |
2294 | of \f(CW\*(C`SIGCHLD\*(C'\fR is recorded asynchronously, but child reaping is done |
2320 | of \f(CW\*(C`SIGCHLD\*(C'\fR is recorded asynchronously, but child reaping is done |
2295 | synchronously as part of the event loop processing. Libev always reaps all |
2321 | synchronously as part of the event loop processing. Libev always reaps all |
2296 | children, even ones not watched. |
2322 | children, even ones not watched. |
2297 | .PP |
2323 | .PP |
2298 | \fIOverriding the Built-In Processing\fR |
2324 | \fIOverriding the Built-In Processing\fR |
… | |
… | |
2310 | .IX Subsection "Stopping the Child Watcher" |
2336 | .IX Subsection "Stopping the Child Watcher" |
2311 | .PP |
2337 | .PP |
2312 | Currently, the child watcher never gets stopped, even when the |
2338 | Currently, the child watcher never gets stopped, even when the |
2313 | child terminates, so normally one needs to stop the watcher in the |
2339 | child terminates, so normally one needs to stop the watcher in the |
2314 | callback. Future versions of libev might stop the watcher automatically |
2340 | callback. Future versions of libev might stop the watcher automatically |
2315 | when a child exit is detected. |
2341 | when a child exit is detected (calling \f(CW\*(C`ev_child_stop\*(C'\fR twice is not a |
|
|
2342 | problem). |
2316 | .PP |
2343 | .PP |
2317 | \fIWatcher-Specific Functions and Data Members\fR |
2344 | \fIWatcher-Specific Functions and Data Members\fR |
2318 | .IX Subsection "Watcher-Specific Functions and Data Members" |
2345 | .IX Subsection "Watcher-Specific Functions and Data Members" |
2319 | .IP "ev_child_init (ev_child *, callback, int pid, int trace)" 4 |
2346 | .IP "ev_child_init (ev_child *, callback, int pid, int trace)" 4 |
2320 | .IX Item "ev_child_init (ev_child *, callback, int pid, int trace)" |
2347 | .IX Item "ev_child_init (ev_child *, callback, int pid, int trace)" |
… | |
… | |
3486 | be found at <http://proj.llucax.com.ar/wiki/evd>. |
3513 | be found at <http://proj.llucax.com.ar/wiki/evd>. |
3487 | .IP "Ocaml" 4 |
3514 | .IP "Ocaml" 4 |
3488 | .IX Item "Ocaml" |
3515 | .IX Item "Ocaml" |
3489 | Erkki Seppala has written Ocaml bindings for libev, to be found at |
3516 | Erkki Seppala has written Ocaml bindings for libev, to be found at |
3490 | <http://modeemi.cs.tut.fi/~flux/software/ocaml\-ev/>. |
3517 | <http://modeemi.cs.tut.fi/~flux/software/ocaml\-ev/>. |
|
|
3518 | .IP "Lua" 4 |
|
|
3519 | .IX Item "Lua" |
|
|
3520 | Brian Maher has written a partial interface to libev |
|
|
3521 | for lua (only \f(CW\*(C`ev_io\*(C'\fR and \f(CW\*(C`ev_timer\*(C'\fR), to be found at |
|
|
3522 | <http://github.com/brimworks/lua\-ev>. |
3491 | .SH "MACRO MAGIC" |
3523 | .SH "MACRO MAGIC" |
3492 | .IX Header "MACRO MAGIC" |
3524 | .IX Header "MACRO MAGIC" |
3493 | Libev can be compiled with a variety of options, the most fundamental |
3525 | Libev can be compiled with a variety of options, the most fundamental |
3494 | of which is \f(CW\*(C`EV_MULTIPLICITY\*(C'\fR. This option determines whether (most) |
3526 | of which is \f(CW\*(C`EV_MULTIPLICITY\*(C'\fR. This option determines whether (most) |
3495 | functions and callbacks have an initial \f(CW\*(C`struct ev_loop *\*(C'\fR argument. |
3527 | functions and callbacks have an initial \f(CW\*(C`struct ev_loop *\*(C'\fR argument. |
… | |
… | |
3671 | keeps libev from including \fIconfig.h\fR, and it also defines dummy |
3703 | keeps libev from including \fIconfig.h\fR, and it also defines dummy |
3672 | implementations for some libevent functions (such as logging, which is not |
3704 | implementations for some libevent functions (such as logging, which is not |
3673 | supported). It will also not define any of the structs usually found in |
3705 | supported). It will also not define any of the structs usually found in |
3674 | \&\fIevent.h\fR that are not directly supported by the libev core alone. |
3706 | \&\fIevent.h\fR that are not directly supported by the libev core alone. |
3675 | .Sp |
3707 | .Sp |
3676 | In stanbdalone mode, libev will still try to automatically deduce the |
3708 | In standalone mode, libev will still try to automatically deduce the |
3677 | configuration, but has to be more conservative. |
3709 | configuration, but has to be more conservative. |
3678 | .IP "\s-1EV_USE_MONOTONIC\s0" 4 |
3710 | .IP "\s-1EV_USE_MONOTONIC\s0" 4 |
3679 | .IX Item "EV_USE_MONOTONIC" |
3711 | .IX Item "EV_USE_MONOTONIC" |
3680 | If defined to be \f(CW1\fR, libev will try to detect the availability of the |
3712 | If defined to be \f(CW1\fR, libev will try to detect the availability of the |
3681 | monotonic clock option at both compile time and runtime. Otherwise no |
3713 | monotonic clock option at both compile time and runtime. Otherwise no |
… | |
… | |
3880 | .Sp |
3912 | .Sp |
3881 | Defining \f(CW\*(C`EV_MINIMAL\*(C'\fR to \f(CW2\fR will additionally reduce the core \s-1API\s0 to |
3913 | Defining \f(CW\*(C`EV_MINIMAL\*(C'\fR to \f(CW2\fR will additionally reduce the core \s-1API\s0 to |
3882 | provide a bare-bones event library. See \f(CW\*(C`ev.h\*(C'\fR for details on what parts |
3914 | provide a bare-bones event library. See \f(CW\*(C`ev.h\*(C'\fR for details on what parts |
3883 | of the \s-1API\s0 are still available, and do not complain if this subset changes |
3915 | of the \s-1API\s0 are still available, and do not complain if this subset changes |
3884 | over time. |
3916 | over time. |
|
|
3917 | .IP "\s-1EV_NSIG\s0" 4 |
|
|
3918 | .IX Item "EV_NSIG" |
|
|
3919 | The highest supported signal number, +1 (or, the number of |
|
|
3920 | signals): Normally, libev tries to deduce the maximum number of signals |
|
|
3921 | automatically, but sometimes this fails, in which case it can be |
|
|
3922 | specified. Also, using a lower number than detected (\f(CW32\fR should be |
|
|
3923 | good for about any system in existance) can save some memory, as libev |
|
|
3924 | statically allocates some 12\-24 bytes per signal number. |
3885 | .IP "\s-1EV_PID_HASHSIZE\s0" 4 |
3925 | .IP "\s-1EV_PID_HASHSIZE\s0" 4 |
3886 | .IX Item "EV_PID_HASHSIZE" |
3926 | .IX Item "EV_PID_HASHSIZE" |
3887 | \&\f(CW\*(C`ev_child\*(C'\fR watchers use a small hash table to distribute workload by |
3927 | \&\f(CW\*(C`ev_child\*(C'\fR watchers use a small hash table to distribute workload by |
3888 | pid. The default size is \f(CW16\fR (or \f(CW1\fR with \f(CW\*(C`EV_MINIMAL\*(C'\fR), usually more |
3928 | pid. The default size is \f(CW16\fR (or \f(CW1\fR with \f(CW\*(C`EV_MINIMAL\*(C'\fR), usually more |
3889 | than enough. If you need to manage thousands of children you might want to |
3929 | than enough. If you need to manage thousands of children you might want to |