… | |
… | |
255 | .IP "ev_tstamp ev_time ()" 4 |
255 | .IP "ev_tstamp ev_time ()" 4 |
256 | .IX Item "ev_tstamp ev_time ()" |
256 | .IX Item "ev_tstamp ev_time ()" |
257 | Returns the current time as libev would use it. Please note that the |
257 | Returns the current time as libev would use it. Please note that the |
258 | \&\f(CW\*(C`ev_now\*(C'\fR function is usually faster and also often returns the timestamp |
258 | \&\f(CW\*(C`ev_now\*(C'\fR function is usually faster and also often returns the timestamp |
259 | you actually want to know. |
259 | you actually want to know. |
260 | .IP "void ev_sleep (ev_tstamp interval)" 4 |
260 | .IP "ev_sleep (ev_tstamp interval)" 4 |
261 | .IX Item "void ev_sleep (ev_tstamp interval)" |
261 | .IX Item "ev_sleep (ev_tstamp interval)" |
262 | Sleep for the given interval: The current thread will be blocked until |
262 | Sleep for the given interval: The current thread will be blocked until |
263 | either it is interrupted or the given time interval has passed. Basically |
263 | either it is interrupted or the given time interval has passed. Basically |
264 | this is a subsecond-resolution \f(CW\*(C`sleep ()\*(C'\fR. |
264 | this is a subsecond-resolution \f(CW\*(C`sleep ()\*(C'\fR. |
265 | .IP "int ev_version_major ()" 4 |
265 | .IP "int ev_version_major ()" 4 |
266 | .IX Item "int ev_version_major ()" |
266 | .IX Item "int ev_version_major ()" |
… | |
… | |
484 | (or space) is available. |
484 | (or space) is available. |
485 | .ie n .IP """EVBACKEND_KQUEUE"" (value 8, most \s-1BSD\s0 clones)" 4 |
485 | .ie n .IP """EVBACKEND_KQUEUE"" (value 8, most \s-1BSD\s0 clones)" 4 |
486 | .el .IP "\f(CWEVBACKEND_KQUEUE\fR (value 8, most \s-1BSD\s0 clones)" 4 |
486 | .el .IP "\f(CWEVBACKEND_KQUEUE\fR (value 8, most \s-1BSD\s0 clones)" 4 |
487 | .IX Item "EVBACKEND_KQUEUE (value 8, most BSD clones)" |
487 | .IX Item "EVBACKEND_KQUEUE (value 8, most BSD clones)" |
488 | Kqueue deserves special mention, as at the time of this writing, it |
488 | Kqueue deserves special mention, as at the time of this writing, it |
489 | was broken on \fIall\fR BSDs (usually it doesn't work with anything but |
489 | was broken on all BSDs except NetBSD (usually it doesn't work reliably |
490 | sockets and pipes, except on Darwin, where of course it's completely |
490 | with anything but sockets and pipes, except on Darwin, where of course |
491 | useless. On NetBSD, it seems to work for all the \s-1FD\s0 types I tested, so it |
|
|
492 | is used by default there). For this reason it's not being \*(L"autodetected\*(R" |
491 | it's completely useless). For this reason it's not being \*(L"autodetected\*(R" |
493 | unless you explicitly specify it explicitly in the flags (i.e. using |
492 | unless you explicitly specify it explicitly in the flags (i.e. using |
494 | \&\f(CW\*(C`EVBACKEND_KQUEUE\*(C'\fR) or libev was compiled on a known-to-be-good (\-enough) |
493 | \&\f(CW\*(C`EVBACKEND_KQUEUE\*(C'\fR) or libev was compiled on a known-to-be-good (\-enough) |
495 | system like NetBSD. |
494 | system like NetBSD. |
496 | .Sp |
495 | .Sp |
|
|
496 | You still can embed kqueue into a normal poll or select backend and use it |
|
|
497 | only for sockets (after having made sure that sockets work with kqueue on |
|
|
498 | the target platform). See \f(CW\*(C`ev_embed\*(C'\fR watchers for more info. |
|
|
499 | .Sp |
497 | It scales in the same way as the epoll backend, but the interface to the |
500 | It scales in the same way as the epoll backend, but the interface to the |
498 | kernel is more efficient (which says nothing about its actual speed, |
501 | kernel is more efficient (which says nothing about its actual speed, of |
499 | of course). While stopping, setting and starting an I/O watcher does |
502 | course). While stopping, setting and starting an I/O watcher does never |
500 | never cause an extra syscall as with epoll, it still adds up to two event |
503 | cause an extra syscall as with \f(CW\*(C`EVBACKEND_EPOLL\*(C'\fR, it still adds up to |
501 | changes per incident, support for \f(CW\*(C`fork ()\*(C'\fR is very bad and it drops fds |
504 | two event changes per incident, support for \f(CW\*(C`fork ()\*(C'\fR is very bad and it |
502 | silently in similarly hard-to-detetc cases. |
505 | drops fds silently in similarly hard-to-detect cases. |
503 | .ie n .IP """EVBACKEND_DEVPOLL"" (value 16, Solaris 8)" 4 |
506 | .ie n .IP """EVBACKEND_DEVPOLL"" (value 16, Solaris 8)" 4 |
504 | .el .IP "\f(CWEVBACKEND_DEVPOLL\fR (value 16, Solaris 8)" 4 |
507 | .el .IP "\f(CWEVBACKEND_DEVPOLL\fR (value 16, Solaris 8)" 4 |
505 | .IX Item "EVBACKEND_DEVPOLL (value 16, Solaris 8)" |
508 | .IX Item "EVBACKEND_DEVPOLL (value 16, Solaris 8)" |
506 | This is not implemented yet (and might never be). |
509 | This is not implemented yet (and might never be). |
507 | .ie n .IP """EVBACKEND_PORT"" (value 32, Solaris 10)" 4 |
510 | .ie n .IP """EVBACKEND_PORT"" (value 32, Solaris 10)" 4 |
… | |
… | |
729 | .Sp |
732 | .Sp |
730 | .Vb 2 |
733 | .Vb 2 |
731 | \& ev_ref (loop); |
734 | \& ev_ref (loop); |
732 | \& ev_signal_stop (loop, &exitsig); |
735 | \& ev_signal_stop (loop, &exitsig); |
733 | .Ve |
736 | .Ve |
734 | .IP "ev_set_io_collect_interval (ev_tstamp interval)" 4 |
737 | .IP "ev_set_io_collect_interval (loop, ev_tstamp interval)" 4 |
735 | .IX Item "ev_set_io_collect_interval (ev_tstamp interval)" |
738 | .IX Item "ev_set_io_collect_interval (loop, ev_tstamp interval)" |
736 | .PD 0 |
739 | .PD 0 |
737 | .IP "ev_set_timeout_collect_interval (ev_tstamp interval)" 4 |
740 | .IP "ev_set_timeout_collect_interval (loop, ev_tstamp interval)" 4 |
738 | .IX Item "ev_set_timeout_collect_interval (ev_tstamp interval)" |
741 | .IX Item "ev_set_timeout_collect_interval (loop, ev_tstamp interval)" |
739 | .PD |
742 | .PD |
740 | These advanced functions influence the time that libev will spend waiting |
743 | These advanced functions influence the time that libev will spend waiting |
741 | for events. Both are by default \f(CW0\fR, meaning that libev will try to |
744 | for events. Both are by default \f(CW0\fR, meaning that libev will try to |
742 | invoke timer/periodic callbacks and I/O callbacks with minimum latency. |
745 | invoke timer/periodic callbacks and I/O callbacks with minimum latency. |
743 | .Sp |
746 | .Sp |
… | |
… | |
752 | overhead for the actual polling but can deliver many events at once. |
755 | overhead for the actual polling but can deliver many events at once. |
753 | .Sp |
756 | .Sp |
754 | By setting a higher \fIio collect interval\fR you allow libev to spend more |
757 | By setting a higher \fIio collect interval\fR you allow libev to spend more |
755 | time collecting I/O events, so you can handle more events per iteration, |
758 | time collecting I/O events, so you can handle more events per iteration, |
756 | at the cost of increasing latency. Timeouts (both \f(CW\*(C`ev_periodic\*(C'\fR and |
759 | at the cost of increasing latency. Timeouts (both \f(CW\*(C`ev_periodic\*(C'\fR and |
757 | \&\f(CW\*(C`ev_timer\*(C'\fR) will be not affected. |
760 | \&\f(CW\*(C`ev_timer\*(C'\fR) will be not affected. Setting this to a non-null bvalue will |
|
|
761 | introduce an additional \f(CW\*(C`ev_sleep ()\*(C'\fR call into most loop iterations. |
758 | .Sp |
762 | .Sp |
759 | Likewise, by setting a higher \fItimeout collect interval\fR you allow libev |
763 | Likewise, by setting a higher \fItimeout collect interval\fR you allow libev |
760 | to spend more time collecting timeouts, at the expense of increased |
764 | to spend more time collecting timeouts, at the expense of increased |
761 | latency (the watcher callback will be called later). \f(CW\*(C`ev_io\*(C'\fR watchers |
765 | latency (the watcher callback will be called later). \f(CW\*(C`ev_io\*(C'\fR watchers |
762 | will not be affected. |
766 | will not be affected. Setting this to a non-null value will not introduce |
|
|
767 | any overhead in libev. |
763 | .Sp |
768 | .Sp |
764 | Many programs can usually benefit by setting the io collect interval to |
769 | Many (busy) programs can usually benefit by setting the io collect |
765 | a value near \f(CW0.1\fR or so, which is often enough for interactive servers |
770 | interval to a value near \f(CW0.1\fR or so, which is often enough for |
766 | (of course not for games), likewise for timeouts. It usually doesn't make |
771 | interactive servers (of course not for games), likewise for timeouts. It |
767 | much sense to set it to a lower value than \f(CW0.01\fR, as this approsaches |
772 | usually doesn't make much sense to set it to a lower value than \f(CW0.01\fR, |
768 | the timing granularity of most systems. |
773 | as this approsaches the timing granularity of most systems. |
769 | .SH "ANATOMY OF A WATCHER" |
774 | .SH "ANATOMY OF A WATCHER" |
770 | .IX Header "ANATOMY OF A WATCHER" |
775 | .IX Header "ANATOMY OF A WATCHER" |
771 | A watcher is a structure that you create and register to record your |
776 | A watcher is a structure that you create and register to record your |
772 | interest in some event. For instance, if you want to wait for \s-1STDIN\s0 to |
777 | interest in some event. For instance, if you want to wait for \s-1STDIN\s0 to |
773 | become readable, you would create an \f(CW\*(C`ev_io\*(C'\fR watcher for that: |
778 | become readable, you would create an \f(CW\*(C`ev_io\*(C'\fR watcher for that: |
… | |
… | |
1782 | .PP |
1787 | .PP |
1783 | It is recommended to give \f(CW\*(C`ev_check\*(C'\fR watchers highest (\f(CW\*(C`EV_MAXPRI\*(C'\fR) |
1788 | It is recommended to give \f(CW\*(C`ev_check\*(C'\fR watchers highest (\f(CW\*(C`EV_MAXPRI\*(C'\fR) |
1784 | priority, to ensure that they are being run before any other watchers |
1789 | priority, to ensure that they are being run before any other watchers |
1785 | after the poll. Also, \f(CW\*(C`ev_check\*(C'\fR watchers (and \f(CW\*(C`ev_prepare\*(C'\fR watchers, |
1790 | after the poll. Also, \f(CW\*(C`ev_check\*(C'\fR watchers (and \f(CW\*(C`ev_prepare\*(C'\fR watchers, |
1786 | too) should not activate (\*(L"feed\*(R") events into libev. While libev fully |
1791 | too) should not activate (\*(L"feed\*(R") events into libev. While libev fully |
1787 | supports this, they will be called before other \f(CW\*(C`ev_check\*(C'\fR watchers did |
1792 | supports this, they will be called before other \f(CW\*(C`ev_check\*(C'\fR watchers |
1788 | their job. As \f(CW\*(C`ev_check\*(C'\fR watchers are often used to embed other event |
1793 | did their job. As \f(CW\*(C`ev_check\*(C'\fR watchers are often used to embed other |
1789 | loops those other event loops might be in an unusable state until their |
1794 | (non\-libev) event loops those other event loops might be in an unusable |
1790 | \&\f(CW\*(C`ev_check\*(C'\fR watcher ran (always remind yourself to coexist peacefully with |
1795 | state until their \f(CW\*(C`ev_check\*(C'\fR watcher ran (always remind yourself to |
1791 | others). |
1796 | coexist peacefully with others). |
1792 | .PP |
1797 | .PP |
1793 | \fIWatcher-Specific Functions and Data Members\fR |
1798 | \fIWatcher-Specific Functions and Data Members\fR |
1794 | .IX Subsection "Watcher-Specific Functions and Data Members" |
1799 | .IX Subsection "Watcher-Specific Functions and Data Members" |
1795 | .IP "ev_prepare_init (ev_prepare *, callback)" 4 |
1800 | .IP "ev_prepare_init (ev_prepare *, callback)" 4 |
1796 | .IX Item "ev_prepare_init (ev_prepare *, callback)" |
1801 | .IX Item "ev_prepare_init (ev_prepare *, callback)" |
… | |
… | |
1976 | .el .Sh "\f(CWev_embed\fP \- when one backend isn't enough..." |
1981 | .el .Sh "\f(CWev_embed\fP \- when one backend isn't enough..." |
1977 | .IX Subsection "ev_embed - when one backend isn't enough..." |
1982 | .IX Subsection "ev_embed - when one backend isn't enough..." |
1978 | This is a rather advanced watcher type that lets you embed one event loop |
1983 | This is a rather advanced watcher type that lets you embed one event loop |
1979 | into another (currently only \f(CW\*(C`ev_io\*(C'\fR events are supported in the embedded |
1984 | into another (currently only \f(CW\*(C`ev_io\*(C'\fR events are supported in the embedded |
1980 | loop, other types of watchers might be handled in a delayed or incorrect |
1985 | loop, other types of watchers might be handled in a delayed or incorrect |
1981 | fashion and must not be used). (See portability notes, below). |
1986 | fashion and must not be used). |
1982 | .PP |
1987 | .PP |
1983 | There are primarily two reasons you would want that: work around bugs and |
1988 | There are primarily two reasons you would want that: work around bugs and |
1984 | prioritise I/O. |
1989 | prioritise I/O. |
1985 | .PP |
1990 | .PP |
1986 | As an example for a bug workaround, the kqueue backend might only support |
1991 | As an example for a bug workaround, the kqueue backend might only support |
… | |
… | |
2046 | \& ev_embed_start (loop_hi, &embed); |
2051 | \& ev_embed_start (loop_hi, &embed); |
2047 | \& } |
2052 | \& } |
2048 | \& else |
2053 | \& else |
2049 | \& loop_lo = loop_hi; |
2054 | \& loop_lo = loop_hi; |
2050 | .Ve |
2055 | .Ve |
2051 | .Sh "Portability notes" |
|
|
2052 | .IX Subsection "Portability notes" |
|
|
2053 | Kqueue is nominally embeddable, but this is broken on all BSDs that I |
|
|
2054 | tried, in various ways. Usually the embedded event loop will simply never |
|
|
2055 | receive events, sometimes it will only trigger a few times, sometimes in a |
|
|
2056 | loop. Epoll is also nominally embeddable, but many Linux kernel versions |
|
|
2057 | will always eport the epoll fd as ready, even when no events are pending. |
|
|
2058 | .PP |
|
|
2059 | While libev allows embedding these backends (they are contained in |
|
|
2060 | \&\f(CW\*(C`ev_embeddable_backends ()\*(C'\fR), take extreme care that it will actually |
|
|
2061 | work. |
|
|
2062 | .PP |
|
|
2063 | When in doubt, create a dynamic event loop forced to use sockets (this |
|
|
2064 | usually works) and possibly another thread and a pipe or so to report to |
|
|
2065 | your main event loop. |
|
|
2066 | .PP |
2056 | .PP |
2067 | \fIWatcher-Specific Functions and Data Members\fR |
2057 | \fIWatcher-Specific Functions and Data Members\fR |
2068 | .IX Subsection "Watcher-Specific Functions and Data Members" |
2058 | .IX Subsection "Watcher-Specific Functions and Data Members" |
2069 | .IP "ev_embed_init (ev_embed *, callback, struct ev_loop *embedded_loop)" 4 |
2059 | .IP "ev_embed_init (ev_embed *, callback, struct ev_loop *embedded_loop)" 4 |
2070 | .IX Item "ev_embed_init (ev_embed *, callback, struct ev_loop *embedded_loop)" |
2060 | .IX Item "ev_embed_init (ev_embed *, callback, struct ev_loop *embedded_loop)" |