ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/libev/ev.3
(Generate patch)

Comparing libev/ev.3 (file contents):
Revision 1.64 by root, Wed Apr 16 17:08:29 2008 UTC vs.
Revision 1.65 by root, Sun May 11 11:47:27 2008 UTC

… …
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 *)"
1512Simply stops and restarts the periodic watcher again. This is only useful 1512Simply stops and restarts the periodic watcher again. This is only useful
1513when you changed some parameters or the reschedule callback would return 1513when you changed some parameters or the reschedule callback would return
1514a different time than the last time it was called (e.g. in a crond like 1514a different time than the last time it was called (e.g. in a crond like
1515program when the crontabs have changed). 1515program 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 *)"
1518When active, returns the absolute time that the watcher is supposed to
1519trigger 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]"
1518When repeating, this contains the offset value, otherwise this is the 1522When repeating, this contains the offset value, otherwise this is the
1519absolute point in time (the \f(CW\*(C`at\*(C'\fR value passed to \f(CW\*(C`ev_periodic_set\*(C'\fR). 1523absolute 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]"
1530The current reschedule callback, or \f(CW0\fR, if this functionality is 1534The current reschedule callback, or \f(CW0\fR, if this functionality is
1531switched off. Can be changed any time, but changes only take effect when 1535switched off. Can be changed any time, but changes only take effect when
1532the periodic timer fires or \f(CW\*(C`ev_periodic_again\*(C'\fR is being called. 1536the 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]"
1535When active, contains the absolute time that the watcher is supposed to
1536trigger next.
1537.PP 1537.PP
1538\fIExamples\fR 1538\fIExamples\fR
1539.IX Subsection "Examples" 1539.IX Subsection "Examples"
1540.PP 1540.PP
1541Example: Call a callback every hour, or, more precisely, whenever the 1541Example: Call a callback every hour, or, more precisely, whenever the
… …
1747as even with OS-supported change notifications, this can be 1747as even with OS-supported change notifications, this can be
1748resource-intensive. 1748resource-intensive.
1749.PP 1749.PP
1750At the time of this writing, only the Linux inotify interface is 1750At the time of this writing, only the Linux inotify interface is
1751implemented (implementing kqueue support is left as an exercise for the 1751implemented (implementing kqueue support is left as an exercise for the
1752reader, note, however, that the author sees no way of implementing ev_stat
1752reader). Inotify will be used to give hints only and should not change the 1753semantics with kqueue). Inotify will be used to give hints only and should
1753semantics of \f(CW\*(C`ev_stat\*(C'\fR watchers, which means that libev sometimes needs 1754not change the semantics of \f(CW\*(C`ev_stat\*(C'\fR watchers, which means that libev
1754to fall back to regular polling again even with inotify, but changes are 1755sometimes needs to fall back to regular polling again even with inotify,
1755usually detected immediately, and if the file exists there will be no 1756but changes are usually detected immediately, and if the file exists there
1756polling. 1757will 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
1761Libev by default (unless the user overrides this) uses the default 1762Libev by default (unless the user overrides this) uses the default
… …
1773When \f(CW\*(C`inotify (7)\*(C'\fR support has been compiled into libev (generally only 1774When \f(CW\*(C`inotify (7)\*(C'\fR support has been compiled into libev (generally only
1774available on Linux) and present at runtime, it will be used to speed up 1775available on Linux) and present at runtime, it will be used to speed up
1775change detection where possible. The inotify descriptor will be created lazily 1776change detection where possible. The inotify descriptor will be created lazily
1776when the first \f(CW\*(C`ev_stat\*(C'\fR watcher is being started. 1777when the first \f(CW\*(C`ev_stat\*(C'\fR watcher is being started.
1777.PP 1778.PP
1778Inotify presense does not change the semantics of \f(CW\*(C`ev_stat\*(C'\fR watchers 1779Inotify presence does not change the semantics of \f(CW\*(C`ev_stat\*(C'\fR watchers
1779except that changes might be detected earlier, and in some cases, to avoid 1780except that changes might be detected earlier, and in some cases, to avoid
1780making regular \f(CW\*(C`stat\*(C'\fR calls. Even in the presense of inotify support 1781making regular \f(CW\*(C`stat\*(C'\fR calls. Even in the presence of inotify support
1781there are many cases where libev has to resort to regular \f(CW\*(C`stat\*(C'\fR polling. 1782there 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
1784implement this functionality, due to the requirement of having a file 1785implement this functionality, due to the requirement of having a file
1785descriptor open on the object at all times). 1786descriptor open on the object at all times).
… …
1789.PP 1790.PP
1790The \f(CW\*(C`stat ()\*(C'\fR syscall only supports full-second resolution portably, and 1791The \f(CW\*(C`stat ()\*(C'\fR syscall only supports full-second resolution portably, and
1791even on systems where the resolution is higher, many filesystems still 1792even on systems where the resolution is higher, many filesystems still
1792only support whole seconds. 1793only support whole seconds.
1793.PP 1794.PP
1794That means that, if the time is the only thing that changes, you might 1795That means that, if the time is the only thing that changes, you can
1795miss updates: on the first update, \f(CW\*(C`ev_stat\*(C'\fR detects a change and calls 1796easily miss updates: on the first update, \f(CW\*(C`ev_stat\*(C'\fR detects a change and
1796your callback, which does something. When there is another update within 1797calls your callback, which does something. When there is another update
1797the same second, \f(CW\*(C`ev_stat\*(C'\fR will be unable to detect it. 1798within the same second, \f(CW\*(C`ev_stat\*(C'\fR will be unable to detect it as the stat
1799data does not change.
1798.PP 1800.PP
1799The solution to this is to delay acting on a change for a second (or till 1801The solution to this is to delay acting on a change for slightly more
1800the next second boundary), using a roughly one-second delay \f(CW\*(C`ev_timer\*(C'\fR 1802than 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 1803a roughly one-second-delay \f(CW\*(C`ev_timer\*(C'\fR (e.g. \f(CW\*(C`ev_timer_set (w, 0., 1.02);
1802is added to work around small timing inconsistencies of some operating 1804ev_timer_again (loop, w)\*(C'\fR).
1803systems. 1805.PP
1806The \f(CW.02\fR offset is added to work around small timing inconsistencies
1807of some operating systems (where the second counter of the current time
1808might 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
1810a subsequent \f(CW\*(C`time\*(C'\fR call \- if the equivalent of \f(CW\*(C`time ()\*(C'\fR is used to
1811update file times then there will be a small window where the kernel uses
1812the previous second to update file times but libev might already execute
1813the 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
1815be detected and should normally be specified as \f(CW0\fR to let libev choose 1825be detected and should normally be specified as \f(CW0\fR to let libev choose
1816a suitable value. The memory pointed to by \f(CW\*(C`path\*(C'\fR must point to the same 1826a suitable value. The memory pointed to by \f(CW\*(C`path\*(C'\fR must point to the same
1817path for as long as the watcher is active. 1827path for as long as the watcher is active.
1818.Sp 1828.Sp
1819The callback will be receive \f(CW\*(C`EV_STAT\*(C'\fR when a change was detected, 1829The callback will receive \f(CW\*(C`EV_STAT\*(C'\fR when a change was detected, relative
1820relative to the attributes at the time the watcher was started (or the 1830to the attributes at the time the watcher was started (or the last change
1821last change was detected). 1831was 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 *)"
1824Updates the stat buffer immediately with new values. If you change the 1834Updates the stat buffer immediately with new values. If you change the
1825watched path in your callback, you could call this fucntion to avoid 1835watched path in your callback, you could call this function to avoid
1826detecting this change (while introducing a race condition). Can also be 1836detecting this change (while introducing a race condition if you are not
1827useful simply to find out the new values. 1837the only one changing the path). Can also be useful simply to find out the
1838new 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]"
1830The most-recently detected attributes of the file. Although the type is of 1841The 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
1843suitable for your system, but you can only rely on the POSIX-standardised
1832suitable for your system. If the \f(CW\*(C`st_nlink\*(C'\fR member is \f(CW0\fR, then there 1844members to be present. If the \f(CW\*(C`st_nlink\*(C'\fR member is \f(CW0\fR, then there was
1833was some error while \f(CW\*(C`stat\*(C'\fRing the file. 1845some 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]"
1836The previous attributes of the file. The callback gets invoked whenever 1848The 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
1850differ: \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]"
1840The specified interval. 1854The 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..."
1906Idle watchers trigger events when no other events of the same or higher 1920Idle watchers trigger events when no other events of the same or higher
… …
1992.PP 2006.PP
1993It is recommended to give \f(CW\*(C`ev_check\*(C'\fR watchers highest (\f(CW\*(C`EV_MAXPRI\*(C'\fR) 2007It is recommended to give \f(CW\*(C`ev_check\*(C'\fR watchers highest (\f(CW\*(C`EV_MAXPRI\*(C'\fR)
1994priority, to ensure that they are being run before any other watchers 2008priority, to ensure that they are being run before any other watchers
1995after the poll. Also, \f(CW\*(C`ev_check\*(C'\fR watchers (and \f(CW\*(C`ev_prepare\*(C'\fR watchers, 2009after the poll. Also, \f(CW\*(C`ev_check\*(C'\fR watchers (and \f(CW\*(C`ev_prepare\*(C'\fR watchers,
1996too) should not activate (\*(L"feed\*(R") events into libev. While libev fully 2010too) should not activate (\*(L"feed\*(R") events into libev. While libev fully
1997supports this, they will be called before other \f(CW\*(C`ev_check\*(C'\fR watchers 2011supports this, they might get executed before other \f(CW\*(C`ev_check\*(C'\fR watchers
1998did their job. As \f(CW\*(C`ev_check\*(C'\fR watchers are often used to embed other 2012did 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
2000state until their \f(CW\*(C`ev_check\*(C'\fR watcher ran (always remind yourself to 2014state until their \f(CW\*(C`ev_check\*(C'\fR watcher ran (always remind yourself to
2001coexist peacefully with others). 2015coexist peacefully with others).
2002.PP 2016.PP
… …
2016.IX Subsection "Examples" 2030.IX Subsection "Examples"
2017.PP 2031.PP
2018There are a number of principal ways to embed other event loops or modules 2032There are a number of principal ways to embed other event loops or modules
2019into libev. Here are some ideas on how to include libadns into libev 2033into 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
2021use for an actually working example. Another Perl module named \f(CW\*(C`EV::Glib\*(C'\fR 2035use as a working example. Another Perl module named \f(CW\*(C`EV::Glib\*(C'\fR embeds a
2022embeds a Glib main context into libev, and finally, \f(CW\*(C`Glib::EV\*(C'\fR embeds \s-1EV\s0 2036Glib main context into libev, and finally, \f(CW\*(C`Glib::EV\*(C'\fR embeds \s-1EV\s0 into the
2023into the Glib event loop). 2037Glib event loop).
2024.PP 2038.PP
2025Method 1: Add \s-1IO\s0 watchers and a timeout watcher in a prepare handler, 2039Method 1: Add \s-1IO\s0 watchers and a timeout watcher in a prepare handler,
2026and in a check watcher, destroy them and call into libadns. What follows 2040and in a check watcher, destroy them and call into libadns. What follows
2027is pseudo-code only of course. This requires you to either use a low 2041is pseudo-code only of course. This requires you to either use a low
2028priority for the check watcher or use \f(CW\*(C`ev_clear_pending\*(C'\fR explicitly, as 2042priority for the check watcher or use \f(CW\*(C`ev_clear_pending\*(C'\fR explicitly, as
… …
3052If undefined or defined to be \f(CW1\fR, then async watchers are supported. If 3066If undefined or defined to be \f(CW1\fR, then async watchers are supported. If
3053defined to be \f(CW0\fR, then they are not. 3067defined 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"
3056If you need to shave off some kilobytes of code at the expense of some 3070If you need to shave off some kilobytes of code at the expense of some
3057speed, define this symbol to \f(CW1\fR. Currently only used for gcc to override 3071speed, define this symbol to \f(CW1\fR. Currently this is used to override some
3058some inlining decisions, saves roughly 30% codesize of amd64. 3072inlining decisions, saves roughly 30% codesize of amd64. It also selects a
3073much 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
3062pid. The default size is \f(CW16\fR (or \f(CW1\fR with \f(CW\*(C`EV_MINIMAL\*(C'\fR), usually more 3077pid. The default size is \f(CW16\fR (or \f(CW1\fR with \f(CW\*(C`EV_MINIMAL\*(C'\fR), usually more
3063than enough. If you need to manage thousands of children you might want to 3078than 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
3068inotify watch id. The default size is \f(CW16\fR (or \f(CW1\fR with \f(CW\*(C`EV_MINIMAL\*(C'\fR), 3083inotify watch id. The default size is \f(CW16\fR (or \f(CW1\fR with \f(CW\*(C`EV_MINIMAL\*(C'\fR),
3069usually more than enough. If you need to manage thousands of \f(CW\*(C`ev_stat\*(C'\fR 3084usually more than enough. If you need to manage thousands of \f(CW\*(C`ev_stat\*(C'\fR
3070watchers you might want to increase this value (\fImust\fR be a power of 3085watchers you might want to increase this value (\fImust\fR be a power of
3071two). 3086two).
3087.IP "\s-1EV_USE_4HEAP\s0" 4
3088.IX Item "EV_USE_4HEAP"
3089Heaps are not very cache-efficient. To improve the cache-efficiency of the
3090timer and periodics heap, libev uses a 4\-heap when this symbol is defined
3091to \f(CW1\fR. The 4\-heap uses more complicated (longer) code but has a
3092noticable after performance with many (thousands) of watchers.
3093.Sp
3094The 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"
3098Heaps are not very cache-efficient. To improve the cache-efficiency of the
3099timer and periodics heap, libev can cache the timestamp (\fIat\fR) within
3100the heap structure (selected by defining \f(CW\*(C`EV_HEAP_CACHE_AT\*(C'\fR to \f(CW1\fR),
3101which uses 8\-12 bytes more per watcher and a few hundred bytes more code,
3102but avoids random read accesses on heap changes. This noticably improves
3103performance noticably with with many (hundreds) of watchers.
3104.Sp
3105The 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"
3074By default, all watchers have a \f(CW\*(C`void *data\*(C'\fR member. By redefining 3109By default, all watchers have a \f(CW\*(C`void *data\*(C'\fR member. By redefining
3075this macro to a something else you can include more and other types of 3110this macro to a something else you can include more and other types of
3076members. You have to define it each time you include one of the files, 3111members. You have to define it each time you include one of the files,
… …
3242These watchers are stored in lists then need to be walked to find the 3277These watchers are stored in lists then need to be walked to find the
3243correct watcher to remove. The lists are usually short (you don't usually 3278correct watcher to remove. The lists are usually short (you don't usually
3244have many watchers waiting for the same fd or signal). 3279have 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)"
3247By virtue of using a binary heap, the next timer is always found at the 3282By virtue of using a binary or 4\-heap, the next timer is always found at a
3248beginning of the storage array. 3283fixed 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)"
3251A change means an I/O watcher gets started or stopped, which requires 3286A change means an I/O watcher gets started or stopped, which requires
3252libev to recalculate its status (and possibly tell the kernel, depending 3287libev to recalculate its status (and possibly tell the kernel, depending
3253on backend and wether \f(CW\*(C`ev_io_set\*(C'\fR was used). 3288on backend and wether \f(CW\*(C`ev_io_set\*(C'\fR was used).
… …
3279model. Libev still offers limited functionality on this platform in 3314model. Libev still offers limited functionality on this platform in
3280the form of the \f(CW\*(C`EVBACKEND_SELECT\*(C'\fR backend, and only supports socket 3315the form of the \f(CW\*(C`EVBACKEND_SELECT\*(C'\fR backend, and only supports socket
3281descriptors. This only applies when using Win32 natively, not when using 3316descriptors. This only applies when using Win32 natively, not when using
3282e.g. cygwin. 3317e.g. cygwin.
3283.PP 3318.PP
3319Lifting these limitations would basically require the full
3320re-implementation of the I/O system. If you are into these kinds of
3321things, then note that glib does exactly that for you in a very portable
3322way (note also that glib is the slowest event library known to man).
3323.PP
3284There is no supported compilation method available on windows except 3324There is no supported compilation method available on windows except
3285embedding it into other applications. 3325embedding it into other applications.
3286.PP 3326.PP
3287Due to the many, low, and arbitrary limits on the win32 platform and the 3327Due to the many, low, and arbitrary limits on the win32 platform and
3288abysmal performance of winsockets, using a large number of sockets is not 3328the abysmal performance of winsockets, using a large number of sockets
3289recommended (and not reasonable). If your program needs to use more than 3329is not recommended (and not reasonable). If your program needs to use
3290a hundred or so sockets, then likely it needs to use a totally different 3330more than a hundred or so sockets, then likely it needs to use a totally
3291implementation for windows, as libev offers the \s-1POSIX\s0 model, which cannot 3331different implementation for windows, as libev offers the \s-1POSIX\s0 readyness
3292be implemented efficiently on windows (microsoft monopoly games). 3332notification 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"
3295The winsocket \f(CW\*(C`select\*(C'\fR function doesn't follow \s-1POSIX\s0 in that it requires 3336The winsocket \f(CW\*(C`select\*(C'\fR function doesn't follow \s-1POSIX\s0 in that it requires
3296socket \fIhandles\fR and not socket \fIfile descriptors\fR. This makes select 3337socket \fIhandles\fR and not socket \fIfile descriptors\fR. This makes select
3297very inefficient, and also requires a mapping from file descriptors 3338very inefficient, and also requires a mapping from file descriptors
… …
3309.Sp 3350.Sp
3310Note that winsockets handling of fd sets is O(n), so you can easily get a 3351Note that winsockets handling of fd sets is O(n), so you can easily get a
3311complexity in the O(nA\*^X) range when using win32. 3352complexity 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"
3314Windows has numerous arbitrary (and low) limits on things. Early versions 3355Windows has numerous arbitrary (and low) limits on things.
3315of 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 3357Early 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 3358of \f(CW64\fR handles (probably owning to the fact that all windows kernels
3318chain of threads and wait for 63 handles and the previous thread in each). 3359can only wait for \f(CW64\fR things at the same time internally; microsoft
3360recommends spawning a chain of threads and wait for 63 handles and the
3361previous thread in each. Great).
3319.Sp 3362.Sp
3320Newer versions support more handles, but you need to define \f(CW\*(C`FD_SETSIZE\*(C'\fR 3363Newer versions support more handles, but you need to define \f(CW\*(C`FD_SETSIZE\*(C'\fR
3321to some high number (e.g. \f(CW2048\fR) before compiling the winsocket select 3364to some high number (e.g. \f(CW2048\fR) before compiling the winsocket select
3322call (which might be in libev or elsewhere, for example, perl does its own 3365call (which might be in libev or elsewhere, for example, perl does its own
3323select emulation on windows). 3366select emulation on windows).
… …
3331.Sp 3374.Sp
3332This might get you to about \f(CW512\fR or \f(CW2048\fR sockets (depending on 3375This might get you to about \f(CW512\fR or \f(CW2048\fR sockets (depending on
3333windows version and/or the phase of the moon). To get more, you need to 3376windows version and/or the phase of the moon). To get more, you need to
3334wrap all I/O functions and provide your own fd management, but the cost of 3377wrap all I/O functions and provide your own fd management, but the cost of
3335calling select (O(nA\*^X)) will likely make this unworkable. 3378calling select (O(nA\*^X)) will likely make this unworkable.
3379.SH "PORTABILITY REQUIREMENTS"
3380.IX Header "PORTABILITY REQUIREMENTS"
3381In addition to a working ISO-C implementation, libev relies on a few
3382additional 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"
3386The 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
3388threads. This is not part of the specification for \f(CW\*(C`sig_atomic_t\*(C'\fR, but is
3389believed 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"
3393Libev uses \f(CW\*(C`sigprocmask\*(C'\fR to temporarily block signals. This is not
3394allowed in a threaded program (\f(CW\*(C`pthread_sigmask\*(C'\fR has to be used). Typical
3395pthread implementations will either allow \f(CW\*(C`sigprocmask\*(C'\fR in the \*(L"main
3396thread\*(R" or will block signals process-wide, both behaviours would
3397be 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
3400The most portable way to handle signals is to block signals in all threads
3401except the initial one, and run the default loop in the initial thread as
3402well.
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"
3406To improve portability and simplify using libev, libev uses \f(CW\*(C`long\*(C'\fR
3407internally instead of \f(CW\*(C`size_t\*(C'\fR when allocating its data structures. On
3408non-POSIX systems (Microsoft...) this might be unexpectedly low, but
3409is still at least 31 bits everywhere, which is enough for hundreds of
3410millions 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"
3414The type \f(CW\*(C`double\*(C'\fR is used to represent timestamps. It is required to
3415have at least 51 bits of mantissa (and 9 bits of exponent), which is good
3416enough for at least into the year 4000. This requirement is fulfilled by
3417implementations implementing \s-1IEEE\s0 754 (basically all existing ones).
3418.PP
3419If you know of other additional requirements drop me a note.
3336.SH "AUTHOR" 3420.SH "AUTHOR"
3337.IX Header "AUTHOR" 3421.IX Header "AUTHOR"
3338Marc Lehmann <libev@schmorp.de>. 3422Marc Lehmann <libev@schmorp.de>.
3339.SH "POD ERRORS" 3423.SH "POD ERRORS"
3340.IX Header "POD ERRORS" 3424.IX Header "POD ERRORS"
3341Hey! \fBThe above document had some coding errors, which are explained below:\fR 3425Hey! \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:"
3344You forgot a '=back' before '=head2' 3428You forgot a '=back' before '=head2'

Diff Legend

– Removed lines
+ Added lines
< Changed lines
> Changed lines