… | |
… | |
127 | .\} |
127 | .\} |
128 | .rm #[ #] #H #V #F C |
128 | .rm #[ #] #H #V #F C |
129 | .\" ======================================================================== |
129 | .\" ======================================================================== |
130 | .\" |
130 | .\" |
131 | .IX Title "EV 1" |
131 | .IX Title "EV 1" |
132 | .TH EV 1 "2007-12-21" "perl v5.8.8" "User Contributed Perl Documentation" |
132 | .TH EV 1 "2007-12-22" "perl v5.8.8" "User Contributed Perl Documentation" |
133 | .SH "NAME" |
133 | .SH "NAME" |
134 | libev \- a high performance full\-featured event loop written in C |
134 | libev \- a high performance full\-featured event loop written in C |
135 | .SH "SYNOPSIS" |
135 | .SH "SYNOPSIS" |
136 | .IX Header "SYNOPSIS" |
136 | .IX Header "SYNOPSIS" |
137 | .Vb 1 |
137 | .Vb 1 |
… | |
… | |
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 "ev_sleep (ev_tstamp interval)" 4 |
|
|
261 | .IX Item "ev_sleep (ev_tstamp interval)" |
|
|
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 |
|
|
264 | this is a subsecond-resolution \f(CW\*(C`sleep ()\*(C'\fR. |
260 | .IP "int ev_version_major ()" 4 |
265 | .IP "int ev_version_major ()" 4 |
261 | .IX Item "int ev_version_major ()" |
266 | .IX Item "int ev_version_major ()" |
262 | .PD 0 |
267 | .PD 0 |
263 | .IP "int ev_version_minor ()" 4 |
268 | .IP "int ev_version_minor ()" 4 |
264 | .IX Item "int ev_version_minor ()" |
269 | .IX Item "int ev_version_minor ()" |
… | |
… | |
463 | For few fds, this backend is a bit little slower than poll and select, |
468 | For few fds, this backend is a bit little slower than poll and select, |
464 | but it scales phenomenally better. While poll and select usually scale |
469 | but it scales phenomenally better. While poll and select usually scale |
465 | like O(total_fds) where n is the total number of fds (or the highest fd), |
470 | like O(total_fds) where n is the total number of fds (or the highest fd), |
466 | epoll scales either O(1) or O(active_fds). The epoll design has a number |
471 | epoll scales either O(1) or O(active_fds). The epoll design has a number |
467 | of shortcomings, such as silently dropping events in some hard-to-detect |
472 | of shortcomings, such as silently dropping events in some hard-to-detect |
468 | cases and rewuiring a syscall per fd change, no fork support and bad |
473 | cases and rewiring a syscall per fd change, no fork support and bad |
469 | support for dup: |
474 | support for dup: |
470 | .Sp |
475 | .Sp |
471 | While stopping, setting and starting an I/O watcher in the same iteration |
476 | While stopping, setting and starting an I/O watcher in the same iteration |
472 | will result in some caching, there is still a syscall per such incident |
477 | will result in some caching, there is still a syscall per such incident |
473 | (because the fd could point to a different file description now), so its |
478 | (because the fd could point to a different file description now), so its |
… | |
… | |
479 | (or space) is available. |
484 | (or space) is available. |
480 | .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 |
481 | .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 |
482 | .IX Item "EVBACKEND_KQUEUE (value 8, most BSD clones)" |
487 | .IX Item "EVBACKEND_KQUEUE (value 8, most BSD clones)" |
483 | 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 |
484 | 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 |
485 | 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 |
486 | useless. On NetBSD, it seems to work for all the \s-1FD\s0 types I tested, so it |
|
|
487 | 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" |
488 | 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 |
489 | \&\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) |
490 | system like NetBSD. |
494 | system like NetBSD. |
491 | .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 |
492 | 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 |
493 | kernel is more efficient (which says nothing about its actual speed, |
501 | kernel is more efficient (which says nothing about its actual speed, of |
494 | 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 |
495 | 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 |
496 | 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 |
497 | silently in similarly hard-to-detetc cases. |
505 | drops fds silently in similarly hard-to-detect cases. |
498 | .ie n .IP """EVBACKEND_DEVPOLL"" (value 16, Solaris 8)" 4 |
506 | .ie n .IP """EVBACKEND_DEVPOLL"" (value 16, Solaris 8)" 4 |
499 | .el .IP "\f(CWEVBACKEND_DEVPOLL\fR (value 16, Solaris 8)" 4 |
507 | .el .IP "\f(CWEVBACKEND_DEVPOLL\fR (value 16, Solaris 8)" 4 |
500 | .IX Item "EVBACKEND_DEVPOLL (value 16, Solaris 8)" |
508 | .IX Item "EVBACKEND_DEVPOLL (value 16, Solaris 8)" |
501 | This is not implemented yet (and might never be). |
509 | This is not implemented yet (and might never be). |
502 | .ie n .IP """EVBACKEND_PORT"" (value 32, Solaris 10)" 4 |
510 | .ie n .IP """EVBACKEND_PORT"" (value 32, Solaris 10)" 4 |
… | |
… | |
724 | .Sp |
732 | .Sp |
725 | .Vb 2 |
733 | .Vb 2 |
726 | \& ev_ref (loop); |
734 | \& ev_ref (loop); |
727 | \& ev_signal_stop (loop, &exitsig); |
735 | \& ev_signal_stop (loop, &exitsig); |
728 | .Ve |
736 | .Ve |
|
|
737 | .IP "ev_set_io_collect_interval (loop, ev_tstamp interval)" 4 |
|
|
738 | .IX Item "ev_set_io_collect_interval (loop, ev_tstamp interval)" |
|
|
739 | .PD 0 |
|
|
740 | .IP "ev_set_timeout_collect_interval (loop, ev_tstamp interval)" 4 |
|
|
741 | .IX Item "ev_set_timeout_collect_interval (loop, ev_tstamp interval)" |
|
|
742 | .PD |
|
|
743 | These advanced functions influence the time that libev will spend waiting |
|
|
744 | for events. Both are by default \f(CW0\fR, meaning that libev will try to |
|
|
745 | invoke timer/periodic callbacks and I/O callbacks with minimum latency. |
|
|
746 | .Sp |
|
|
747 | Setting these to a higher value (the \f(CW\*(C`interval\*(C'\fR \fImust\fR be >= \f(CW0\fR) |
|
|
748 | allows libev to delay invocation of I/O and timer/periodic callbacks to |
|
|
749 | increase efficiency of loop iterations. |
|
|
750 | .Sp |
|
|
751 | The background is that sometimes your program runs just fast enough to |
|
|
752 | handle one (or very few) event(s) per loop iteration. While this makes |
|
|
753 | the program responsive, it also wastes a lot of \s-1CPU\s0 time to poll for new |
|
|
754 | events, especially with backends like \f(CW\*(C`select ()\*(C'\fR which have a high |
|
|
755 | overhead for the actual polling but can deliver many events at once. |
|
|
756 | .Sp |
|
|
757 | By setting a higher \fIio collect interval\fR you allow libev to spend more |
|
|
758 | time collecting I/O events, so you can handle more events per iteration, |
|
|
759 | at the cost of increasing latency. Timeouts (both \f(CW\*(C`ev_periodic\*(C'\fR and |
|
|
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. |
|
|
762 | .Sp |
|
|
763 | Likewise, by setting a higher \fItimeout collect interval\fR you allow libev |
|
|
764 | to spend more time collecting timeouts, at the expense of increased |
|
|
765 | latency (the watcher callback will be called later). \f(CW\*(C`ev_io\*(C'\fR watchers |
|
|
766 | will not be affected. Setting this to a non-null value will not introduce |
|
|
767 | any overhead in libev. |
|
|
768 | .Sp |
|
|
769 | Many (busy) programs can usually benefit by setting the io collect |
|
|
770 | interval to a value near \f(CW0.1\fR or so, which is often enough for |
|
|
771 | interactive servers (of course not for games), likewise for timeouts. It |
|
|
772 | usually doesn't make much sense to set it to a lower value than \f(CW0.01\fR, |
|
|
773 | as this approsaches the timing granularity of most systems. |
729 | .SH "ANATOMY OF A WATCHER" |
774 | .SH "ANATOMY OF A WATCHER" |
730 | .IX Header "ANATOMY OF A WATCHER" |
775 | .IX Header "ANATOMY OF A WATCHER" |
731 | 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 |
732 | 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 |
733 | 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: |
… | |
… | |
1742 | .PP |
1787 | .PP |
1743 | 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) |
1744 | 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 |
1745 | 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, |
1746 | 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 |
1747 | 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 |
1748 | 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 |
1749 | 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 |
1750 | \&\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 |
1751 | others). |
1796 | coexist peacefully with others). |
1752 | .PP |
1797 | .PP |
1753 | \fIWatcher-Specific Functions and Data Members\fR |
1798 | \fIWatcher-Specific Functions and Data Members\fR |
1754 | .IX Subsection "Watcher-Specific Functions and Data Members" |
1799 | .IX Subsection "Watcher-Specific Functions and Data Members" |
1755 | .IP "ev_prepare_init (ev_prepare *, callback)" 4 |
1800 | .IP "ev_prepare_init (ev_prepare *, callback)" 4 |
1756 | .IX Item "ev_prepare_init (ev_prepare *, callback)" |
1801 | .IX Item "ev_prepare_init (ev_prepare *, callback)" |
… | |
… | |
1936 | .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..." |
1937 | .IX Subsection "ev_embed - when one backend isn't enough..." |
1982 | .IX Subsection "ev_embed - when one backend isn't enough..." |
1938 | 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 |
1939 | 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 |
1940 | 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 |
1941 | fashion and must not be used). (See portability notes, below). |
1986 | fashion and must not be used). |
1942 | .PP |
1987 | .PP |
1943 | 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 |
1944 | prioritise I/O. |
1989 | prioritise I/O. |
1945 | .PP |
1990 | .PP |
1946 | 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 |
… | |
… | |
2006 | \& ev_embed_start (loop_hi, &embed); |
2051 | \& ev_embed_start (loop_hi, &embed); |
2007 | \& } |
2052 | \& } |
2008 | \& else |
2053 | \& else |
2009 | \& loop_lo = loop_hi; |
2054 | \& loop_lo = loop_hi; |
2010 | .Ve |
2055 | .Ve |
2011 | .Sh "Portability notes" |
|
|
2012 | .IX Subsection "Portability notes" |
|
|
2013 | Kqueue is nominally embeddable, but this is broken on all BSDs that I |
|
|
2014 | tried, in various ways. Usually the embedded event loop will simply never |
|
|
2015 | receive events, sometimes it will only trigger a few times, sometimes in a |
|
|
2016 | loop. Epoll is also nominally embeddable, but many Linux kernel versions |
|
|
2017 | will always eport the epoll fd as ready, even when no events are pending. |
|
|
2018 | .PP |
|
|
2019 | While libev allows embedding these backends (they are contained in |
|
|
2020 | \&\f(CW\*(C`ev_embeddable_backends ()\*(C'\fR), take extreme care that it will actually |
|
|
2021 | work. |
|
|
2022 | .PP |
|
|
2023 | When in doubt, create a dynamic event loop forced to use sockets (this |
|
|
2024 | usually works) and possibly another thread and a pipe or so to report to |
|
|
2025 | your main event loop. |
|
|
2026 | .PP |
2056 | .PP |
2027 | \fIWatcher-Specific Functions and Data Members\fR |
2057 | \fIWatcher-Specific Functions and Data Members\fR |
2028 | .IX Subsection "Watcher-Specific Functions and Data Members" |
2058 | .IX Subsection "Watcher-Specific Functions and Data Members" |
2029 | .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 |
2030 | .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)" |
… | |
… | |
2501 | realtime clock option at compiletime (and assume its availability at |
2531 | realtime clock option at compiletime (and assume its availability at |
2502 | runtime if successful). Otherwise no use of the realtime clock option will |
2532 | runtime if successful). Otherwise no use of the realtime clock option will |
2503 | be attempted. This effectively replaces \f(CW\*(C`gettimeofday\*(C'\fR by \f(CW\*(C`clock_get |
2533 | be attempted. This effectively replaces \f(CW\*(C`gettimeofday\*(C'\fR by \f(CW\*(C`clock_get |
2504 | (CLOCK_REALTIME, ...)\*(C'\fR and will not normally affect correctness. See the |
2534 | (CLOCK_REALTIME, ...)\*(C'\fR and will not normally affect correctness. See the |
2505 | note about libraries in the description of \f(CW\*(C`EV_USE_MONOTONIC\*(C'\fR, though. |
2535 | note about libraries in the description of \f(CW\*(C`EV_USE_MONOTONIC\*(C'\fR, though. |
|
|
2536 | .IP "\s-1EV_USE_NANOSLEEP\s0" 4 |
|
|
2537 | .IX Item "EV_USE_NANOSLEEP" |
|
|
2538 | If defined to be \f(CW1\fR, libev will assume that \f(CW\*(C`nanosleep ()\*(C'\fR is available |
|
|
2539 | and will use it for delays. Otherwise it will use \f(CW\*(C`select ()\*(C'\fR. |
2506 | .IP "\s-1EV_USE_SELECT\s0" 4 |
2540 | .IP "\s-1EV_USE_SELECT\s0" 4 |
2507 | .IX Item "EV_USE_SELECT" |
2541 | .IX Item "EV_USE_SELECT" |
2508 | If undefined or defined to be \f(CW1\fR, libev will compile in support for the |
2542 | If undefined or defined to be \f(CW1\fR, libev will compile in support for the |
2509 | \&\f(CW\*(C`select\*(C'\fR(2) backend. No attempt at autodetection will be done: if no |
2543 | \&\f(CW\*(C`select\*(C'\fR(2) backend. No attempt at autodetection will be done: if no |
2510 | other method takes over, select will be it. Otherwise the select backend |
2544 | other method takes over, select will be it. Otherwise the select backend |