… | |
… | |
129 | . ds Ae AE |
129 | . ds Ae AE |
130 | .\} |
130 | .\} |
131 | .rm #[ #] #H #V #F C |
131 | .rm #[ #] #H #V #F C |
132 | .\" ======================================================================== |
132 | .\" ======================================================================== |
133 | .\" |
133 | .\" |
134 | .IX Title "EV 1" |
134 | .IX Title "LIBEV 3" |
135 | .TH EV 1 "2008-04-11" "perl v5.10.0" "User Contributed Perl Documentation" |
135 | .TH LIBEV 3 "2008-05-09" "libev-1.1" "libev - high perfromance full featured event loop" |
136 | .\" For nroff, turn off justification. Always turn off hyphenation; it makes |
136 | .\" For nroff, turn off justification. Always turn off hyphenation; it makes |
137 | .\" way too many mistakes in technical documents. |
137 | .\" way too many mistakes in technical documents. |
138 | .if n .ad l |
138 | .if n .ad l |
139 | .nh |
139 | .nh |
140 | .SH "NAME" |
140 | .SH "NAME" |
… | |
… | |
1511 | .IX Item "ev_periodic_again (loop, ev_periodic *)" |
1511 | .IX Item "ev_periodic_again (loop, ev_periodic *)" |
1512 | Simply stops and restarts the periodic watcher again. This is only useful |
1512 | Simply stops and restarts the periodic watcher again. This is only useful |
1513 | when you changed some parameters or the reschedule callback would return |
1513 | when you changed some parameters or the reschedule callback would return |
1514 | a different time than the last time it was called (e.g. in a crond like |
1514 | a different time than the last time it was called (e.g. in a crond like |
1515 | program when the crontabs have changed). |
1515 | program when the crontabs have changed). |
|
|
1516 | .IP "ev_tstamp ev_periodic_at (ev_periodic *)" 4 |
|
|
1517 | .IX Item "ev_tstamp ev_periodic_at (ev_periodic *)" |
|
|
1518 | When active, returns the absolute time that the watcher is supposed to |
|
|
1519 | trigger next. |
1516 | .IP "ev_tstamp offset [read\-write]" 4 |
1520 | .IP "ev_tstamp offset [read\-write]" 4 |
1517 | .IX Item "ev_tstamp offset [read-write]" |
1521 | .IX Item "ev_tstamp offset [read-write]" |
1518 | When repeating, this contains the offset value, otherwise this is the |
1522 | When repeating, this contains the offset value, otherwise this is the |
1519 | absolute point in time (the \f(CW\*(C`at\*(C'\fR value passed to \f(CW\*(C`ev_periodic_set\*(C'\fR). |
1523 | absolute point in time (the \f(CW\*(C`at\*(C'\fR value passed to \f(CW\*(C`ev_periodic_set\*(C'\fR). |
1520 | .Sp |
1524 | .Sp |
… | |
… | |
1528 | .IP "ev_tstamp (*reschedule_cb)(struct ev_periodic *w, ev_tstamp now) [read\-write]" 4 |
1532 | .IP "ev_tstamp (*reschedule_cb)(struct ev_periodic *w, ev_tstamp now) [read\-write]" 4 |
1529 | .IX Item "ev_tstamp (*reschedule_cb)(struct ev_periodic *w, ev_tstamp now) [read-write]" |
1533 | .IX Item "ev_tstamp (*reschedule_cb)(struct ev_periodic *w, ev_tstamp now) [read-write]" |
1530 | The current reschedule callback, or \f(CW0\fR, if this functionality is |
1534 | The current reschedule callback, or \f(CW0\fR, if this functionality is |
1531 | switched off. Can be changed any time, but changes only take effect when |
1535 | switched off. Can be changed any time, but changes only take effect when |
1532 | the periodic timer fires or \f(CW\*(C`ev_periodic_again\*(C'\fR is being called. |
1536 | the periodic timer fires or \f(CW\*(C`ev_periodic_again\*(C'\fR is being called. |
1533 | .IP "ev_tstamp at [read\-only]" 4 |
|
|
1534 | .IX Item "ev_tstamp at [read-only]" |
|
|
1535 | When active, contains the absolute time that the watcher is supposed to |
|
|
1536 | trigger next. |
|
|
1537 | .PP |
1537 | .PP |
1538 | \fIExamples\fR |
1538 | \fIExamples\fR |
1539 | .IX Subsection "Examples" |
1539 | .IX Subsection "Examples" |
1540 | .PP |
1540 | .PP |
1541 | Example: Call a callback every hour, or, more precisely, whenever the |
1541 | Example: Call a callback every hour, or, more precisely, whenever the |
… | |
… | |
1747 | as even with OS-supported change notifications, this can be |
1747 | as even with OS-supported change notifications, this can be |
1748 | resource-intensive. |
1748 | resource-intensive. |
1749 | .PP |
1749 | .PP |
1750 | At the time of this writing, only the Linux inotify interface is |
1750 | At the time of this writing, only the Linux inotify interface is |
1751 | implemented (implementing kqueue support is left as an exercise for the |
1751 | implemented (implementing kqueue support is left as an exercise for the |
|
|
1752 | reader, note, however, that the author sees no way of implementing ev_stat |
1752 | reader). Inotify will be used to give hints only and should not change the |
1753 | semantics with kqueue). Inotify will be used to give hints only and should |
1753 | semantics of \f(CW\*(C`ev_stat\*(C'\fR watchers, which means that libev sometimes needs |
1754 | not change the semantics of \f(CW\*(C`ev_stat\*(C'\fR watchers, which means that libev |
1754 | to fall back to regular polling again even with inotify, but changes are |
1755 | sometimes needs to fall back to regular polling again even with inotify, |
1755 | usually detected immediately, and if the file exists there will be no |
1756 | but changes are usually detected immediately, and if the file exists there |
1756 | polling. |
1757 | will be no polling. |
1757 | .PP |
1758 | .PP |
1758 | \fI\s-1ABI\s0 Issues (Largefile Support)\fR |
1759 | \fI\s-1ABI\s0 Issues (Largefile Support)\fR |
1759 | .IX Subsection "ABI Issues (Largefile Support)" |
1760 | .IX Subsection "ABI Issues (Largefile Support)" |
1760 | .PP |
1761 | .PP |
1761 | Libev by default (unless the user overrides this) uses the default |
1762 | Libev by default (unless the user overrides this) uses the default |
… | |
… | |
1773 | When \f(CW\*(C`inotify (7)\*(C'\fR support has been compiled into libev (generally only |
1774 | When \f(CW\*(C`inotify (7)\*(C'\fR support has been compiled into libev (generally only |
1774 | available on Linux) and present at runtime, it will be used to speed up |
1775 | available on Linux) and present at runtime, it will be used to speed up |
1775 | change detection where possible. The inotify descriptor will be created lazily |
1776 | change detection where possible. The inotify descriptor will be created lazily |
1776 | when the first \f(CW\*(C`ev_stat\*(C'\fR watcher is being started. |
1777 | when the first \f(CW\*(C`ev_stat\*(C'\fR watcher is being started. |
1777 | .PP |
1778 | .PP |
1778 | Inotify presense does not change the semantics of \f(CW\*(C`ev_stat\*(C'\fR watchers |
1779 | Inotify presence does not change the semantics of \f(CW\*(C`ev_stat\*(C'\fR watchers |
1779 | except that changes might be detected earlier, and in some cases, to avoid |
1780 | except that changes might be detected earlier, and in some cases, to avoid |
1780 | making regular \f(CW\*(C`stat\*(C'\fR calls. Even in the presense of inotify support |
1781 | making regular \f(CW\*(C`stat\*(C'\fR calls. Even in the presence of inotify support |
1781 | there are many cases where libev has to resort to regular \f(CW\*(C`stat\*(C'\fR polling. |
1782 | there are many cases where libev has to resort to regular \f(CW\*(C`stat\*(C'\fR polling. |
1782 | .PP |
1783 | .PP |
1783 | (There is no support for kqueue, as apparently it cannot be used to |
1784 | (There is no support for kqueue, as apparently it cannot be used to |
1784 | implement this functionality, due to the requirement of having a file |
1785 | implement this functionality, due to the requirement of having a file |
1785 | descriptor open on the object at all times). |
1786 | descriptor open on the object at all times). |
… | |
… | |
1789 | .PP |
1790 | .PP |
1790 | The \f(CW\*(C`stat ()\*(C'\fR syscall only supports full-second resolution portably, and |
1791 | The \f(CW\*(C`stat ()\*(C'\fR syscall only supports full-second resolution portably, and |
1791 | even on systems where the resolution is higher, many filesystems still |
1792 | even on systems where the resolution is higher, many filesystems still |
1792 | only support whole seconds. |
1793 | only support whole seconds. |
1793 | .PP |
1794 | .PP |
1794 | That means that, if the time is the only thing that changes, you might |
1795 | That means that, if the time is the only thing that changes, you can |
1795 | miss updates: on the first update, \f(CW\*(C`ev_stat\*(C'\fR detects a change and calls |
1796 | easily miss updates: on the first update, \f(CW\*(C`ev_stat\*(C'\fR detects a change and |
1796 | your callback, which does something. When there is another update within |
1797 | calls your callback, which does something. When there is another update |
1797 | the same second, \f(CW\*(C`ev_stat\*(C'\fR will be unable to detect it. |
1798 | within the same second, \f(CW\*(C`ev_stat\*(C'\fR will be unable to detect it as the stat |
|
|
1799 | data does not change. |
1798 | .PP |
1800 | .PP |
1799 | The solution to this is to delay acting on a change for a second (or till |
1801 | The solution to this is to delay acting on a change for slightly more |
1800 | the next second boundary), using a roughly one-second delay \f(CW\*(C`ev_timer\*(C'\fR |
1802 | than second (or till slightly after the next full second boundary), using |
1801 | (\f(CW\*(C`ev_timer_set (w, 0., 1.01); ev_timer_again (loop, w)\*(C'\fR). The \f(CW.01\fR |
1803 | a roughly one-second-delay \f(CW\*(C`ev_timer\*(C'\fR (e.g. \f(CW\*(C`ev_timer_set (w, 0., 1.02); |
1802 | is added to work around small timing inconsistencies of some operating |
1804 | ev_timer_again (loop, w)\*(C'\fR). |
1803 | systems. |
1805 | .PP |
|
|
1806 | The \f(CW.02\fR offset is added to work around small timing inconsistencies |
|
|
1807 | of some operating systems (where the second counter of the current time |
|
|
1808 | might be be delayed. One such system is the Linux kernel, where a call to |
|
|
1809 | \&\f(CW\*(C`gettimeofday\*(C'\fR might return a timestamp with a full second later than |
|
|
1810 | a subsequent \f(CW\*(C`time\*(C'\fR call \- if the equivalent of \f(CW\*(C`time ()\*(C'\fR is used to |
|
|
1811 | update file times then there will be a small window where the kernel uses |
|
|
1812 | the previous second to update file times but libev might already execute |
|
|
1813 | the timer callback). |
1804 | .PP |
1814 | .PP |
1805 | \fIWatcher-Specific Functions and Data Members\fR |
1815 | \fIWatcher-Specific Functions and Data Members\fR |
1806 | .IX Subsection "Watcher-Specific Functions and Data Members" |
1816 | .IX Subsection "Watcher-Specific Functions and Data Members" |
1807 | .IP "ev_stat_init (ev_stat *, callback, const char *path, ev_tstamp interval)" 4 |
1817 | .IP "ev_stat_init (ev_stat *, callback, const char *path, ev_tstamp interval)" 4 |
1808 | .IX Item "ev_stat_init (ev_stat *, callback, const char *path, ev_tstamp interval)" |
1818 | .IX Item "ev_stat_init (ev_stat *, callback, const char *path, ev_tstamp interval)" |
… | |
… | |
1814 | \&\f(CW\*(C`path\*(C'\fR. The \f(CW\*(C`interval\*(C'\fR is a hint on how quickly a change is expected to |
1824 | \&\f(CW\*(C`path\*(C'\fR. The \f(CW\*(C`interval\*(C'\fR is a hint on how quickly a change is expected to |
1815 | be detected and should normally be specified as \f(CW0\fR to let libev choose |
1825 | be detected and should normally be specified as \f(CW0\fR to let libev choose |
1816 | a suitable value. The memory pointed to by \f(CW\*(C`path\*(C'\fR must point to the same |
1826 | a suitable value. The memory pointed to by \f(CW\*(C`path\*(C'\fR must point to the same |
1817 | path for as long as the watcher is active. |
1827 | path for as long as the watcher is active. |
1818 | .Sp |
1828 | .Sp |
1819 | The callback will be receive \f(CW\*(C`EV_STAT\*(C'\fR when a change was detected, |
1829 | The callback will receive \f(CW\*(C`EV_STAT\*(C'\fR when a change was detected, relative |
1820 | relative to the attributes at the time the watcher was started (or the |
1830 | to the attributes at the time the watcher was started (or the last change |
1821 | last change was detected). |
1831 | was detected). |
1822 | .IP "ev_stat_stat (loop, ev_stat *)" 4 |
1832 | .IP "ev_stat_stat (loop, ev_stat *)" 4 |
1823 | .IX Item "ev_stat_stat (loop, ev_stat *)" |
1833 | .IX Item "ev_stat_stat (loop, ev_stat *)" |
1824 | Updates the stat buffer immediately with new values. If you change the |
1834 | Updates the stat buffer immediately with new values. If you change the |
1825 | watched path in your callback, you could call this fucntion to avoid |
1835 | watched path in your callback, you could call this function to avoid |
1826 | detecting this change (while introducing a race condition). Can also be |
1836 | detecting this change (while introducing a race condition if you are not |
1827 | useful simply to find out the new values. |
1837 | the only one changing the path). Can also be useful simply to find out the |
|
|
1838 | new values. |
1828 | .IP "ev_statdata attr [read\-only]" 4 |
1839 | .IP "ev_statdata attr [read\-only]" 4 |
1829 | .IX Item "ev_statdata attr [read-only]" |
1840 | .IX Item "ev_statdata attr [read-only]" |
1830 | The most-recently detected attributes of the file. Although the type is of |
1841 | The most-recently detected attributes of the file. Although the type is |
1831 | \&\f(CW\*(C`ev_statdata\*(C'\fR, this is usually the (or one of the) \f(CW\*(C`struct stat\*(C'\fR types |
1842 | \&\f(CW\*(C`ev_statdata\*(C'\fR, this is usually the (or one of the) \f(CW\*(C`struct stat\*(C'\fR types |
|
|
1843 | suitable for your system, but you can only rely on the POSIX-standardised |
1832 | suitable for your system. If the \f(CW\*(C`st_nlink\*(C'\fR member is \f(CW0\fR, then there |
1844 | members to be present. If the \f(CW\*(C`st_nlink\*(C'\fR member is \f(CW0\fR, then there was |
1833 | was some error while \f(CW\*(C`stat\*(C'\fRing the file. |
1845 | some error while \f(CW\*(C`stat\*(C'\fRing the file. |
1834 | .IP "ev_statdata prev [read\-only]" 4 |
1846 | .IP "ev_statdata prev [read\-only]" 4 |
1835 | .IX Item "ev_statdata prev [read-only]" |
1847 | .IX Item "ev_statdata prev [read-only]" |
1836 | The previous attributes of the file. The callback gets invoked whenever |
1848 | The previous attributes of the file. The callback gets invoked whenever |
1837 | \&\f(CW\*(C`prev\*(C'\fR != \f(CW\*(C`attr\*(C'\fR. |
1849 | \&\f(CW\*(C`prev\*(C'\fR != \f(CW\*(C`attr\*(C'\fR, or, more precisely, one or more of these members |
|
|
1850 | differ: \f(CW\*(C`st_dev\*(C'\fR, \f(CW\*(C`st_ino\*(C'\fR, \f(CW\*(C`st_mode\*(C'\fR, \f(CW\*(C`st_nlink\*(C'\fR, \f(CW\*(C`st_uid\*(C'\fR, |
|
|
1851 | \&\f(CW\*(C`st_gid\*(C'\fR, \f(CW\*(C`st_rdev\*(C'\fR, \f(CW\*(C`st_size\*(C'\fR, \f(CW\*(C`st_atime\*(C'\fR, \f(CW\*(C`st_mtime\*(C'\fR, \f(CW\*(C`st_ctime\*(C'\fR. |
1838 | .IP "ev_tstamp interval [read\-only]" 4 |
1852 | .IP "ev_tstamp interval [read\-only]" 4 |
1839 | .IX Item "ev_tstamp interval [read-only]" |
1853 | .IX Item "ev_tstamp interval [read-only]" |
1840 | The specified interval. |
1854 | The specified interval. |
1841 | .IP "const char *path [read\-only]" 4 |
1855 | .IP "const char *path [read\-only]" 4 |
1842 | .IX Item "const char *path [read-only]" |
1856 | .IX Item "const char *path [read-only]" |
… | |
… | |
1896 | \& } |
1910 | \& } |
1897 | \& |
1911 | \& |
1898 | \& ... |
1912 | \& ... |
1899 | \& ev_stat_init (&passwd, stat_cb, "/etc/passwd", 0.); |
1913 | \& ev_stat_init (&passwd, stat_cb, "/etc/passwd", 0.); |
1900 | \& ev_stat_start (loop, &passwd); |
1914 | \& ev_stat_start (loop, &passwd); |
1901 | \& ev_timer_init (&timer, timer_cb, 0., 1.01); |
1915 | \& ev_timer_init (&timer, timer_cb, 0., 1.02); |
1902 | .Ve |
1916 | .Ve |
1903 | .ie n .Sh """ev_idle"" \- when you've got nothing better to do..." |
1917 | .ie n .Sh """ev_idle"" \- when you've got nothing better to do..." |
1904 | .el .Sh "\f(CWev_idle\fP \- when you've got nothing better to do..." |
1918 | .el .Sh "\f(CWev_idle\fP \- when you've got nothing better to do..." |
1905 | .IX Subsection "ev_idle - when you've got nothing better to do..." |
1919 | .IX Subsection "ev_idle - when you've got nothing better to do..." |
1906 | Idle watchers trigger events when no other events of the same or higher |
1920 | Idle watchers trigger events when no other events of the same or higher |
… | |
… | |
1992 | .PP |
2006 | .PP |
1993 | It is recommended to give \f(CW\*(C`ev_check\*(C'\fR watchers highest (\f(CW\*(C`EV_MAXPRI\*(C'\fR) |
2007 | It is recommended to give \f(CW\*(C`ev_check\*(C'\fR watchers highest (\f(CW\*(C`EV_MAXPRI\*(C'\fR) |
1994 | priority, to ensure that they are being run before any other watchers |
2008 | priority, to ensure that they are being run before any other watchers |
1995 | after the poll. Also, \f(CW\*(C`ev_check\*(C'\fR watchers (and \f(CW\*(C`ev_prepare\*(C'\fR watchers, |
2009 | after the poll. Also, \f(CW\*(C`ev_check\*(C'\fR watchers (and \f(CW\*(C`ev_prepare\*(C'\fR watchers, |
1996 | too) should not activate (\*(L"feed\*(R") events into libev. While libev fully |
2010 | too) should not activate (\*(L"feed\*(R") events into libev. While libev fully |
1997 | supports this, they will be called before other \f(CW\*(C`ev_check\*(C'\fR watchers |
2011 | supports this, they might get executed before other \f(CW\*(C`ev_check\*(C'\fR watchers |
1998 | did their job. As \f(CW\*(C`ev_check\*(C'\fR watchers are often used to embed other |
2012 | did their job. As \f(CW\*(C`ev_check\*(C'\fR watchers are often used to embed other |
1999 | (non-libev) event loops those other event loops might be in an unusable |
2013 | (non-libev) event loops those other event loops might be in an unusable |
2000 | state until their \f(CW\*(C`ev_check\*(C'\fR watcher ran (always remind yourself to |
2014 | state until their \f(CW\*(C`ev_check\*(C'\fR watcher ran (always remind yourself to |
2001 | coexist peacefully with others). |
2015 | coexist peacefully with others). |
2002 | .PP |
2016 | .PP |
… | |
… | |
2016 | .IX Subsection "Examples" |
2030 | .IX Subsection "Examples" |
2017 | .PP |
2031 | .PP |
2018 | There are a number of principal ways to embed other event loops or modules |
2032 | There are a number of principal ways to embed other event loops or modules |
2019 | into libev. Here are some ideas on how to include libadns into libev |
2033 | into libev. Here are some ideas on how to include libadns into libev |
2020 | (there is a Perl module named \f(CW\*(C`EV::ADNS\*(C'\fR that does this, which you could |
2034 | (there is a Perl module named \f(CW\*(C`EV::ADNS\*(C'\fR that does this, which you could |
2021 | use for an actually working example. Another Perl module named \f(CW\*(C`EV::Glib\*(C'\fR |
2035 | use as a working example. Another Perl module named \f(CW\*(C`EV::Glib\*(C'\fR embeds a |
2022 | embeds a Glib main context into libev, and finally, \f(CW\*(C`Glib::EV\*(C'\fR embeds \s-1EV\s0 |
2036 | Glib main context into libev, and finally, \f(CW\*(C`Glib::EV\*(C'\fR embeds \s-1EV\s0 into the |
2023 | into the Glib event loop). |
2037 | Glib event loop). |
2024 | .PP |
2038 | .PP |
2025 | Method 1: Add \s-1IO\s0 watchers and a timeout watcher in a prepare handler, |
2039 | Method 1: Add \s-1IO\s0 watchers and a timeout watcher in a prepare handler, |
2026 | and in a check watcher, destroy them and call into libadns. What follows |
2040 | and in a check watcher, destroy them and call into libadns. What follows |
2027 | is pseudo-code only of course. This requires you to either use a low |
2041 | is pseudo-code only of course. This requires you to either use a low |
2028 | priority for the check watcher or use \f(CW\*(C`ev_clear_pending\*(C'\fR explicitly, as |
2042 | priority for the check watcher or use \f(CW\*(C`ev_clear_pending\*(C'\fR explicitly, as |
… | |
… | |
3052 | If undefined or defined to be \f(CW1\fR, then async watchers are supported. If |
3066 | If undefined or defined to be \f(CW1\fR, then async watchers are supported. If |
3053 | defined to be \f(CW0\fR, then they are not. |
3067 | defined to be \f(CW0\fR, then they are not. |
3054 | .IP "\s-1EV_MINIMAL\s0" 4 |
3068 | .IP "\s-1EV_MINIMAL\s0" 4 |
3055 | .IX Item "EV_MINIMAL" |
3069 | .IX Item "EV_MINIMAL" |
3056 | If you need to shave off some kilobytes of code at the expense of some |
3070 | If you need to shave off some kilobytes of code at the expense of some |
3057 | speed, define this symbol to \f(CW1\fR. Currently only used for gcc to override |
3071 | speed, define this symbol to \f(CW1\fR. Currently this is used to override some |
3058 | some inlining decisions, saves roughly 30% codesize of amd64. |
3072 | inlining decisions, saves roughly 30% codesize of amd64. It also selects a |
|
|
3073 | much smaller 2\-heap for timer management over the default 4\-heap. |
3059 | .IP "\s-1EV_PID_HASHSIZE\s0" 4 |
3074 | .IP "\s-1EV_PID_HASHSIZE\s0" 4 |
3060 | .IX Item "EV_PID_HASHSIZE" |
3075 | .IX Item "EV_PID_HASHSIZE" |
3061 | \&\f(CW\*(C`ev_child\*(C'\fR watchers use a small hash table to distribute workload by |
3076 | \&\f(CW\*(C`ev_child\*(C'\fR watchers use a small hash table to distribute workload by |
3062 | pid. The default size is \f(CW16\fR (or \f(CW1\fR with \f(CW\*(C`EV_MINIMAL\*(C'\fR), usually more |
3077 | pid. The default size is \f(CW16\fR (or \f(CW1\fR with \f(CW\*(C`EV_MINIMAL\*(C'\fR), usually more |
3063 | than enough. If you need to manage thousands of children you might want to |
3078 | than enough. If you need to manage thousands of children you might want to |
… | |
… | |
3067 | \&\f(CW\*(C`ev_stat\*(C'\fR watchers use a small hash table to distribute workload by |
3082 | \&\f(CW\*(C`ev_stat\*(C'\fR watchers use a small hash table to distribute workload by |
3068 | inotify watch id. The default size is \f(CW16\fR (or \f(CW1\fR with \f(CW\*(C`EV_MINIMAL\*(C'\fR), |
3083 | inotify watch id. The default size is \f(CW16\fR (or \f(CW1\fR with \f(CW\*(C`EV_MINIMAL\*(C'\fR), |
3069 | usually more than enough. If you need to manage thousands of \f(CW\*(C`ev_stat\*(C'\fR |
3084 | usually more than enough. If you need to manage thousands of \f(CW\*(C`ev_stat\*(C'\fR |
3070 | watchers you might want to increase this value (\fImust\fR be a power of |
3085 | watchers you might want to increase this value (\fImust\fR be a power of |
3071 | two). |
3086 | two). |
|
|
3087 | .IP "\s-1EV_USE_4HEAP\s0" 4 |
|
|
3088 | .IX Item "EV_USE_4HEAP" |
|
|
3089 | Heaps are not very cache-efficient. To improve the cache-efficiency of the |
|
|
3090 | timer and periodics heap, libev uses a 4\-heap when this symbol is defined |
|
|
3091 | to \f(CW1\fR. The 4\-heap uses more complicated (longer) code but has a |
|
|
3092 | noticable after performance with many (thousands) of watchers. |
|
|
3093 | .Sp |
|
|
3094 | The default is \f(CW1\fR unless \f(CW\*(C`EV_MINIMAL\*(C'\fR is set in which case it is \f(CW0\fR |
|
|
3095 | (disabled). |
|
|
3096 | .IP "\s-1EV_HEAP_CACHE_AT\s0" 4 |
|
|
3097 | .IX Item "EV_HEAP_CACHE_AT" |
|
|
3098 | Heaps are not very cache-efficient. To improve the cache-efficiency of the |
|
|
3099 | timer and periodics heap, libev can cache the timestamp (\fIat\fR) within |
|
|
3100 | the heap structure (selected by defining \f(CW\*(C`EV_HEAP_CACHE_AT\*(C'\fR to \f(CW1\fR), |
|
|
3101 | which uses 8\-12 bytes more per watcher and a few hundred bytes more code, |
|
|
3102 | but avoids random read accesses on heap changes. This noticably improves |
|
|
3103 | performance noticably with with many (hundreds) of watchers. |
|
|
3104 | .Sp |
|
|
3105 | The default is \f(CW1\fR unless \f(CW\*(C`EV_MINIMAL\*(C'\fR is set in which case it is \f(CW0\fR |
|
|
3106 | (disabled). |
3072 | .IP "\s-1EV_COMMON\s0" 4 |
3107 | .IP "\s-1EV_COMMON\s0" 4 |
3073 | .IX Item "EV_COMMON" |
3108 | .IX Item "EV_COMMON" |
3074 | By default, all watchers have a \f(CW\*(C`void *data\*(C'\fR member. By redefining |
3109 | By default, all watchers have a \f(CW\*(C`void *data\*(C'\fR member. By redefining |
3075 | this macro to a something else you can include more and other types of |
3110 | this macro to a something else you can include more and other types of |
3076 | members. You have to define it each time you include one of the files, |
3111 | members. You have to define it each time you include one of the files, |
… | |
… | |
3242 | These watchers are stored in lists then need to be walked to find the |
3277 | These watchers are stored in lists then need to be walked to find the |
3243 | correct watcher to remove. The lists are usually short (you don't usually |
3278 | correct watcher to remove. The lists are usually short (you don't usually |
3244 | have many watchers waiting for the same fd or signal). |
3279 | have many watchers waiting for the same fd or signal). |
3245 | .IP "Finding the next timer in each loop iteration: O(1)" 4 |
3280 | .IP "Finding the next timer in each loop iteration: O(1)" 4 |
3246 | .IX Item "Finding the next timer in each loop iteration: O(1)" |
3281 | .IX Item "Finding the next timer in each loop iteration: O(1)" |
3247 | By virtue of using a binary heap, the next timer is always found at the |
3282 | By virtue of using a binary or 4\-heap, the next timer is always found at a |
3248 | beginning of the storage array. |
3283 | fixed position in the storage array. |
3249 | .IP "Each change on a file descriptor per loop iteration: O(number_of_watchers_for_this_fd)" 4 |
3284 | .IP "Each change on a file descriptor per loop iteration: O(number_of_watchers_for_this_fd)" 4 |
3250 | .IX Item "Each change on a file descriptor per loop iteration: O(number_of_watchers_for_this_fd)" |
3285 | .IX Item "Each change on a file descriptor per loop iteration: O(number_of_watchers_for_this_fd)" |
3251 | A change means an I/O watcher gets started or stopped, which requires |
3286 | A change means an I/O watcher gets started or stopped, which requires |
3252 | libev to recalculate its status (and possibly tell the kernel, depending |
3287 | libev to recalculate its status (and possibly tell the kernel, depending |
3253 | on backend and wether \f(CW\*(C`ev_io_set\*(C'\fR was used). |
3288 | on backend and wether \f(CW\*(C`ev_io_set\*(C'\fR was used). |
… | |
… | |
3279 | model. Libev still offers limited functionality on this platform in |
3314 | model. Libev still offers limited functionality on this platform in |
3280 | the form of the \f(CW\*(C`EVBACKEND_SELECT\*(C'\fR backend, and only supports socket |
3315 | the form of the \f(CW\*(C`EVBACKEND_SELECT\*(C'\fR backend, and only supports socket |
3281 | descriptors. This only applies when using Win32 natively, not when using |
3316 | descriptors. This only applies when using Win32 natively, not when using |
3282 | e.g. cygwin. |
3317 | e.g. cygwin. |
3283 | .PP |
3318 | .PP |
|
|
3319 | Lifting these limitations would basically require the full |
|
|
3320 | re-implementation of the I/O system. If you are into these kinds of |
|
|
3321 | things, then note that glib does exactly that for you in a very portable |
|
|
3322 | way (note also that glib is the slowest event library known to man). |
|
|
3323 | .PP |
3284 | There is no supported compilation method available on windows except |
3324 | There is no supported compilation method available on windows except |
3285 | embedding it into other applications. |
3325 | embedding it into other applications. |
3286 | .PP |
3326 | .PP |
3287 | Due to the many, low, and arbitrary limits on the win32 platform and the |
3327 | Due to the many, low, and arbitrary limits on the win32 platform and |
3288 | abysmal performance of winsockets, using a large number of sockets is not |
3328 | the abysmal performance of winsockets, using a large number of sockets |
3289 | recommended (and not reasonable). If your program needs to use more than |
3329 | is not recommended (and not reasonable). If your program needs to use |
3290 | a hundred or so sockets, then likely it needs to use a totally different |
3330 | more than a hundred or so sockets, then likely it needs to use a totally |
3291 | implementation for windows, as libev offers the \s-1POSIX\s0 model, which cannot |
3331 | different implementation for windows, as libev offers the \s-1POSIX\s0 readyness |
3292 | be implemented efficiently on windows (microsoft monopoly games). |
3332 | notification model, which cannot be implemented efficiently on windows |
|
|
3333 | (microsoft monopoly games). |
3293 | .IP "The winsocket select function" 4 |
3334 | .IP "The winsocket select function" 4 |
3294 | .IX Item "The winsocket select function" |
3335 | .IX Item "The winsocket select function" |
3295 | The winsocket \f(CW\*(C`select\*(C'\fR function doesn't follow \s-1POSIX\s0 in that it requires |
3336 | The winsocket \f(CW\*(C`select\*(C'\fR function doesn't follow \s-1POSIX\s0 in that it requires |
3296 | socket \fIhandles\fR and not socket \fIfile descriptors\fR. This makes select |
3337 | socket \fIhandles\fR and not socket \fIfile descriptors\fR. This makes select |
3297 | very inefficient, and also requires a mapping from file descriptors |
3338 | very inefficient, and also requires a mapping from file descriptors |
… | |
… | |
3309 | .Sp |
3350 | .Sp |
3310 | Note that winsockets handling of fd sets is O(n), so you can easily get a |
3351 | Note that winsockets handling of fd sets is O(n), so you can easily get a |
3311 | complexity in the O(nA\*^X) range when using win32. |
3352 | complexity in the O(nA\*^X) range when using win32. |
3312 | .IP "Limited number of file descriptors" 4 |
3353 | .IP "Limited number of file descriptors" 4 |
3313 | .IX Item "Limited number of file descriptors" |
3354 | .IX Item "Limited number of file descriptors" |
3314 | Windows has numerous arbitrary (and low) limits on things. Early versions |
3355 | Windows has numerous arbitrary (and low) limits on things. |
3315 | of winsocket's select only supported waiting for a max. of \f(CW64\fR handles |
3356 | .Sp |
3316 | (probably owning to the fact that all windows kernels can only wait for |
3357 | Early versions of winsocket's select only supported waiting for a maximum |
3317 | \&\f(CW64\fR things at the same time internally; microsoft recommends spawning a |
3358 | of \f(CW64\fR handles (probably owning to the fact that all windows kernels |
3318 | chain of threads and wait for 63 handles and the previous thread in each). |
3359 | can only wait for \f(CW64\fR things at the same time internally; microsoft |
|
|
3360 | recommends spawning a chain of threads and wait for 63 handles and the |
|
|
3361 | previous thread in each. Great). |
3319 | .Sp |
3362 | .Sp |
3320 | Newer versions support more handles, but you need to define \f(CW\*(C`FD_SETSIZE\*(C'\fR |
3363 | Newer versions support more handles, but you need to define \f(CW\*(C`FD_SETSIZE\*(C'\fR |
3321 | to some high number (e.g. \f(CW2048\fR) before compiling the winsocket select |
3364 | to some high number (e.g. \f(CW2048\fR) before compiling the winsocket select |
3322 | call (which might be in libev or elsewhere, for example, perl does its own |
3365 | call (which might be in libev or elsewhere, for example, perl does its own |
3323 | select emulation on windows). |
3366 | select emulation on windows). |
… | |
… | |
3331 | .Sp |
3374 | .Sp |
3332 | This might get you to about \f(CW512\fR or \f(CW2048\fR sockets (depending on |
3375 | This might get you to about \f(CW512\fR or \f(CW2048\fR sockets (depending on |
3333 | windows version and/or the phase of the moon). To get more, you need to |
3376 | windows version and/or the phase of the moon). To get more, you need to |
3334 | wrap all I/O functions and provide your own fd management, but the cost of |
3377 | wrap all I/O functions and provide your own fd management, but the cost of |
3335 | calling select (O(nA\*^X)) will likely make this unworkable. |
3378 | calling select (O(nA\*^X)) will likely make this unworkable. |
|
|
3379 | .SH "PORTABILITY REQUIREMENTS" |
|
|
3380 | .IX Header "PORTABILITY REQUIREMENTS" |
|
|
3381 | In addition to a working ISO-C implementation, libev relies on a few |
|
|
3382 | additional extensions: |
|
|
3383 | .ie n .IP """sig_atomic_t volatile"" must be thread-atomic as well" 4 |
|
|
3384 | .el .IP "\f(CWsig_atomic_t volatile\fR must be thread-atomic as well" 4 |
|
|
3385 | .IX Item "sig_atomic_t volatile must be thread-atomic as well" |
|
|
3386 | The type \f(CW\*(C`sig_atomic_t volatile\*(C'\fR (or whatever is defined as |
|
|
3387 | \&\f(CW\*(C`EV_ATOMIC_T\*(C'\fR) must be atomic w.r.t. accesses from different |
|
|
3388 | threads. This is not part of the specification for \f(CW\*(C`sig_atomic_t\*(C'\fR, but is |
|
|
3389 | believed to be sufficiently portable. |
|
|
3390 | .ie n .IP """sigprocmask"" must work in a threaded environment" 4 |
|
|
3391 | .el .IP "\f(CWsigprocmask\fR must work in a threaded environment" 4 |
|
|
3392 | .IX Item "sigprocmask must work in a threaded environment" |
|
|
3393 | Libev uses \f(CW\*(C`sigprocmask\*(C'\fR to temporarily block signals. This is not |
|
|
3394 | allowed in a threaded program (\f(CW\*(C`pthread_sigmask\*(C'\fR has to be used). Typical |
|
|
3395 | pthread implementations will either allow \f(CW\*(C`sigprocmask\*(C'\fR in the \*(L"main |
|
|
3396 | thread\*(R" or will block signals process-wide, both behaviours would |
|
|
3397 | be compatible with libev. Interaction between \f(CW\*(C`sigprocmask\*(C'\fR and |
|
|
3398 | \&\f(CW\*(C`pthread_sigmask\*(C'\fR could complicate things, however. |
|
|
3399 | .Sp |
|
|
3400 | The most portable way to handle signals is to block signals in all threads |
|
|
3401 | except the initial one, and run the default loop in the initial thread as |
|
|
3402 | well. |
|
|
3403 | .ie n .IP """long"" must be large enough for common memory allocation sizes" 4 |
|
|
3404 | .el .IP "\f(CWlong\fR must be large enough for common memory allocation sizes" 4 |
|
|
3405 | .IX Item "long must be large enough for common memory allocation sizes" |
|
|
3406 | To improve portability and simplify using libev, libev uses \f(CW\*(C`long\*(C'\fR |
|
|
3407 | internally instead of \f(CW\*(C`size_t\*(C'\fR when allocating its data structures. On |
|
|
3408 | non-POSIX systems (Microsoft...) this might be unexpectedly low, but |
|
|
3409 | is still at least 31 bits everywhere, which is enough for hundreds of |
|
|
3410 | millions of watchers. |
|
|
3411 | .ie n .IP """double"" must hold a time value in seconds with enough accuracy" 4 |
|
|
3412 | .el .IP "\f(CWdouble\fR must hold a time value in seconds with enough accuracy" 4 |
|
|
3413 | .IX Item "double must hold a time value in seconds with enough accuracy" |
|
|
3414 | The type \f(CW\*(C`double\*(C'\fR is used to represent timestamps. It is required to |
|
|
3415 | have at least 51 bits of mantissa (and 9 bits of exponent), which is good |
|
|
3416 | enough for at least into the year 4000. This requirement is fulfilled by |
|
|
3417 | implementations implementing \s-1IEEE\s0 754 (basically all existing ones). |
|
|
3418 | .PP |
|
|
3419 | If you know of other additional requirements drop me a note. |
3336 | .SH "AUTHOR" |
3420 | .SH "AUTHOR" |
3337 | .IX Header "AUTHOR" |
3421 | .IX Header "AUTHOR" |
3338 | Marc Lehmann <libev@schmorp.de>. |
3422 | Marc Lehmann <libev@schmorp.de>. |
3339 | .SH "POD ERRORS" |
3423 | .SH "POD ERRORS" |
3340 | .IX Header "POD ERRORS" |
3424 | .IX Header "POD ERRORS" |
3341 | Hey! \fBThe above document had some coding errors, which are explained below:\fR |
3425 | Hey! \fBThe above document had some coding errors, which are explained below:\fR |
3342 | .IP "Around line 3015:" 4 |
3426 | .IP "Around line 3052:" 4 |
3343 | .IX Item "Around line 3015:" |
3427 | .IX Item "Around line 3052:" |
3344 | You forgot a '=back' before '=head2' |
3428 | You forgot a '=back' before '=head2' |