… | |
… | |
130 | .\} |
130 | .\} |
131 | .rm #[ #] #H #V #F C |
131 | .rm #[ #] #H #V #F C |
132 | .\" ======================================================================== |
132 | .\" ======================================================================== |
133 | .\" |
133 | .\" |
134 | .IX Title "LIBEV 3" |
134 | .IX Title "LIBEV 3" |
135 | .TH LIBEV 3 "2008-10-30" "libev-3.48" "libev - high performance full featured event loop" |
135 | .TH LIBEV 3 "2008-11-17" "libev-3.49" "libev - high performance 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" |
… | |
… | |
147 | .Sh "\s-1EXAMPLE\s0 \s-1PROGRAM\s0" |
147 | .Sh "\s-1EXAMPLE\s0 \s-1PROGRAM\s0" |
148 | .IX Subsection "EXAMPLE PROGRAM" |
148 | .IX Subsection "EXAMPLE PROGRAM" |
149 | .Vb 2 |
149 | .Vb 2 |
150 | \& // a single header file is required |
150 | \& // a single header file is required |
151 | \& #include <ev.h> |
151 | \& #include <ev.h> |
|
|
152 | \& |
|
|
153 | \& #include <stdio.h> // for puts |
152 | \& |
154 | \& |
153 | \& // every watcher type has its own typedef\*(Aqd struct |
155 | \& // every watcher type has its own typedef\*(Aqd struct |
154 | \& // with the name ev_TYPE |
156 | \& // with the name ev_TYPE |
155 | \& ev_io stdin_watcher; |
157 | \& ev_io stdin_watcher; |
156 | \& ev_timer timeout_watcher; |
158 | \& ev_timer timeout_watcher; |
… | |
… | |
543 | i.e. keep at least one watcher active per fd at all times. Stopping and |
545 | i.e. keep at least one watcher active per fd at all times. Stopping and |
544 | starting a watcher (without re-setting it) also usually doesn't cause |
546 | starting a watcher (without re-setting it) also usually doesn't cause |
545 | extra overhead. A fork can both result in spurious notifications as well |
547 | extra overhead. A fork can both result in spurious notifications as well |
546 | as in libev having to destroy and recreate the epoll object, which can |
548 | as in libev having to destroy and recreate the epoll object, which can |
547 | take considerable time and thus should be avoided. |
549 | take considerable time and thus should be avoided. |
|
|
550 | .Sp |
|
|
551 | All this means that, in practice, \f(CW\*(C`EVBACKEND_SELECT\*(C'\fR can be as fast or |
|
|
552 | faster than epoll for maybe up to a hundred file descriptors, depending on |
|
|
553 | the usage. So sad. |
548 | .Sp |
554 | .Sp |
549 | While nominally embeddable in other event loops, this feature is broken in |
555 | While nominally embeddable in other event loops, this feature is broken in |
550 | all kernel versions tested so far. |
556 | all kernel versions tested so far. |
551 | .Sp |
557 | .Sp |
552 | This backend maps \f(CW\*(C`EV_READ\*(C'\fR and \f(CW\*(C`EV_WRITE\*(C'\fR in the same way as |
558 | This backend maps \f(CW\*(C`EV_READ\*(C'\fR and \f(CW\*(C`EV_WRITE\*(C'\fR in the same way as |
… | |
… | |
1557 | \& else |
1563 | \& else |
1558 | \& { |
1564 | \& { |
1559 | \& // callback was invoked, but there was some activity, re\-arm |
1565 | \& // callback was invoked, but there was some activity, re\-arm |
1560 | \& // the watcher to fire in last_activity + 60, which is |
1566 | \& // the watcher to fire in last_activity + 60, which is |
1561 | \& // guaranteed to be in the future, so "again" is positive: |
1567 | \& // guaranteed to be in the future, so "again" is positive: |
1562 | \& w\->again = timeout \- now; |
1568 | \& w\->repeat = timeout \- now; |
1563 | \& ev_timer_again (EV_A_ w); |
1569 | \& ev_timer_again (EV_A_ w); |
1564 | \& } |
1570 | \& } |
1565 | \& } |
1571 | \& } |
1566 | .Ve |
1572 | .Ve |
1567 | .Sp |
1573 | .Sp |
… | |
… | |
2081 | \&\f(CW\*(C`stat\*(C'\fR on that path in regular intervals (or when the \s-1OS\s0 says it changed) |
2087 | \&\f(CW\*(C`stat\*(C'\fR on that path in regular intervals (or when the \s-1OS\s0 says it changed) |
2082 | and sees if it changed compared to the last time, invoking the callback if |
2088 | and sees if it changed compared to the last time, invoking the callback if |
2083 | it did. |
2089 | it did. |
2084 | .PP |
2090 | .PP |
2085 | The path does not need to exist: changing from \*(L"path exists\*(R" to \*(L"path does |
2091 | The path does not need to exist: changing from \*(L"path exists\*(R" to \*(L"path does |
2086 | not exist\*(R" is a status change like any other. The condition \*(L"path does |
2092 | not exist\*(R" is a status change like any other. The condition \*(L"path does not |
2087 | not exist\*(R" is signified by the \f(CW\*(C`st_nlink\*(C'\fR field being zero (which is |
2093 | exist\*(R" (or more correctly \*(L"path cannot be stat'ed\*(R") is signified by the |
2088 | otherwise always forced to be at least one) and all the other fields of |
2094 | \&\f(CW\*(C`st_nlink\*(C'\fR field being zero (which is otherwise always forced to be at |
2089 | the stat buffer having unspecified contents. |
2095 | least one) and all the other fields of the stat buffer having unspecified |
|
|
2096 | contents. |
2090 | .PP |
2097 | .PP |
2091 | The path \fImust not\fR end in a slash or contain special components such as |
2098 | The path \fImust not\fR end in a slash or contain special components such as |
2092 | \&\f(CW\*(C`.\*(C'\fR or \f(CW\*(C`..\*(C'\fR. The path \fIshould\fR be absolute: If it is relative and |
2099 | \&\f(CW\*(C`.\*(C'\fR or \f(CW\*(C`..\*(C'\fR. The path \fIshould\fR be absolute: If it is relative and |
2093 | your working directory changes, then the behaviour is undefined. |
2100 | your working directory changes, then the behaviour is undefined. |
2094 | .PP |
2101 | .PP |
… | |
… | |
2104 | This watcher type is not meant for massive numbers of stat watchers, |
2111 | This watcher type is not meant for massive numbers of stat watchers, |
2105 | as even with OS-supported change notifications, this can be |
2112 | as even with OS-supported change notifications, this can be |
2106 | resource-intensive. |
2113 | resource-intensive. |
2107 | .PP |
2114 | .PP |
2108 | At the time of this writing, the only OS-specific interface implemented |
2115 | At the time of this writing, the only OS-specific interface implemented |
2109 | is the Linux inotify interface (implementing kqueue support is left as |
2116 | is the Linux inotify interface (implementing kqueue support is left as an |
2110 | an exercise for the reader. Note, however, that the author sees no way |
2117 | exercise for the reader. Note, however, that the author sees no way of |
2111 | of implementing \f(CW\*(C`ev_stat\*(C'\fR semantics with kqueue). |
2118 | implementing \f(CW\*(C`ev_stat\*(C'\fR semantics with kqueue, except as a hint). |
2112 | .PP |
2119 | .PP |
2113 | \fI\s-1ABI\s0 Issues (Largefile Support)\fR |
2120 | \fI\s-1ABI\s0 Issues (Largefile Support)\fR |
2114 | .IX Subsection "ABI Issues (Largefile Support)" |
2121 | .IX Subsection "ABI Issues (Largefile Support)" |
2115 | .PP |
2122 | .PP |
2116 | Libev by default (unless the user overrides this) uses the default |
2123 | Libev by default (unless the user overrides this) uses the default |
… | |
… | |
2129 | default compilation environment. |
2136 | default compilation environment. |
2130 | .PP |
2137 | .PP |
2131 | \fIInotify and Kqueue\fR |
2138 | \fIInotify and Kqueue\fR |
2132 | .IX Subsection "Inotify and Kqueue" |
2139 | .IX Subsection "Inotify and Kqueue" |
2133 | .PP |
2140 | .PP |
2134 | When \f(CW\*(C`inotify (7)\*(C'\fR support has been compiled into libev (generally |
2141 | When \f(CW\*(C`inotify (7)\*(C'\fR support has been compiled into libev and present at |
2135 | only available with Linux 2.6.25 or above due to bugs in earlier |
2142 | runtime, it will be used to speed up change detection where possible. The |
2136 | implementations) and present at runtime, it will be used to speed up |
2143 | inotify descriptor will be created lazily when the first \f(CW\*(C`ev_stat\*(C'\fR |
2137 | change detection where possible. The inotify descriptor will be created |
2144 | watcher is being started. |
2138 | lazily when the first \f(CW\*(C`ev_stat\*(C'\fR watcher is being started. |
|
|
2139 | .PP |
2145 | .PP |
2140 | Inotify presence does not change the semantics of \f(CW\*(C`ev_stat\*(C'\fR watchers |
2146 | Inotify presence does not change the semantics of \f(CW\*(C`ev_stat\*(C'\fR watchers |
2141 | except that changes might be detected earlier, and in some cases, to avoid |
2147 | except that changes might be detected earlier, and in some cases, to avoid |
2142 | making regular \f(CW\*(C`stat\*(C'\fR calls. Even in the presence of inotify support |
2148 | making regular \f(CW\*(C`stat\*(C'\fR calls. Even in the presence of inotify support |
2143 | there are many cases where libev has to resort to regular \f(CW\*(C`stat\*(C'\fR polling, |
2149 | there are many cases where libev has to resort to regular \f(CW\*(C`stat\*(C'\fR polling, |
2144 | but as long as the path exists, libev usually gets away without polling. |
2150 | but as long as kernel 2.6.25 or newer is used (2.6.24 and older have too |
|
|
2151 | many bugs), the path exists (i.e. stat succeeds), and the path resides on |
|
|
2152 | a local filesystem (libev currently assumes only ext2/3, jfs, reiserfs and |
|
|
2153 | xfs are fully working) libev usually gets away without polling. |
2145 | .PP |
2154 | .PP |
2146 | There is no support for kqueue, as apparently it cannot be used to |
2155 | There is no support for kqueue, as apparently it cannot be used to |
2147 | implement this functionality, due to the requirement of having a file |
2156 | implement this functionality, due to the requirement of having a file |
2148 | descriptor open on the object at all times, and detecting renames, unlinks |
2157 | descriptor open on the object at all times, and detecting renames, unlinks |
2149 | etc. is difficult. |
2158 | etc. is difficult. |
|
|
2159 | .PP |
|
|
2160 | \fI\f(CI\*(C`stat ()\*(C'\fI is a synchronous operation\fR |
|
|
2161 | .IX Subsection "stat () is a synchronous operation" |
|
|
2162 | .PP |
|
|
2163 | Libev doesn't normally do any kind of I/O itself, and so is not blocking |
|
|
2164 | the process. The exception are \f(CW\*(C`ev_stat\*(C'\fR watchers \- those call \f(CW\*(C`stat |
|
|
2165 | ()\*(C'\fR, which is a synchronous operation. |
|
|
2166 | .PP |
|
|
2167 | For local paths, this usually doesn't matter: unless the system is very |
|
|
2168 | busy or the intervals between stat's are large, a stat call will be fast, |
|
|
2169 | as the path data is suually in memory already (except when starting the |
|
|
2170 | watcher). |
|
|
2171 | .PP |
|
|
2172 | For networked file systems, calling \f(CW\*(C`stat ()\*(C'\fR can block an indefinite |
|
|
2173 | time due to network issues, and even under good conditions, a stat call |
|
|
2174 | often takes multiple milliseconds. |
|
|
2175 | .PP |
|
|
2176 | Therefore, it is best to avoid using \f(CW\*(C`ev_stat\*(C'\fR watchers on networked |
|
|
2177 | paths, although this is fully supported by libev. |
2150 | .PP |
2178 | .PP |
2151 | \fIThe special problem of stat time resolution\fR |
2179 | \fIThe special problem of stat time resolution\fR |
2152 | .IX Subsection "The special problem of stat time resolution" |
2180 | .IX Subsection "The special problem of stat time resolution" |
2153 | .PP |
2181 | .PP |
2154 | The \f(CW\*(C`stat ()\*(C'\fR system call only supports full-second resolution portably, |
2182 | The \f(CW\*(C`stat ()\*(C'\fR system call only supports full-second resolution portably, |