… | |
… | |
4 | <head> |
4 | <head> |
5 | <title>libev</title> |
5 | <title>libev</title> |
6 | <meta name="description" content="Pod documentation for libev" /> |
6 | <meta name="description" content="Pod documentation for libev" /> |
7 | <meta name="inputfile" content="<standard input>" /> |
7 | <meta name="inputfile" content="<standard input>" /> |
8 | <meta name="outputfile" content="<standard output>" /> |
8 | <meta name="outputfile" content="<standard output>" /> |
9 | <meta name="created" content="Thu Nov 22 13:28:34 2007" /> |
9 | <meta name="created" content="Fri Nov 23 06:14:47 2007" /> |
10 | <meta name="generator" content="Pod::Xhtml 1.57" /> |
10 | <meta name="generator" content="Pod::Xhtml 1.57" /> |
11 | <link rel="stylesheet" href="http://res.tst.eu/pod.css"/></head> |
11 | <link rel="stylesheet" href="http://res.tst.eu/pod.css"/></head> |
12 | <body> |
12 | <body> |
13 | <div class="pod"> |
13 | <div class="pod"> |
14 | <!-- INDEX START --> |
14 | <!-- INDEX START --> |
… | |
… | |
123 | <p>Usually, it's a good idea to terminate if the major versions mismatch, |
123 | <p>Usually, it's a good idea to terminate if the major versions mismatch, |
124 | as this indicates an incompatible change. Minor versions are usually |
124 | as this indicates an incompatible change. Minor versions are usually |
125 | compatible to older versions, so a larger minor version alone is usually |
125 | compatible to older versions, so a larger minor version alone is usually |
126 | not a problem.</p> |
126 | not a problem.</p> |
127 | </dd> |
127 | </dd> |
|
|
128 | <dt>unsigned int ev_supported_backends ()</dt> |
|
|
129 | <dd> |
|
|
130 | <p>Return the set of all backends (i.e. their corresponding <code>EV_BACKEND_*</code> |
|
|
131 | value) compiled into this binary of libev (independent of their |
|
|
132 | availability on the system you are running on). See <code>ev_default_loop</code> for |
|
|
133 | a description of the set values.</p> |
|
|
134 | </dd> |
|
|
135 | <dt>unsigned int ev_recommended_backends ()</dt> |
|
|
136 | <dd> |
|
|
137 | <p>Return the set of all backends compiled into this binary of libev and also |
|
|
138 | recommended for this platform. This set is often smaller than the one |
|
|
139 | returned by <code>ev_supported_backends</code>, as for example kqueue is broken on |
|
|
140 | most BSDs and will not be autodetected unless you explicitly request it |
|
|
141 | (assuming you know what you are doing). This is the set of backends that |
|
|
142 | <code>EVFLAG_AUTO</code> will probe for.</p> |
|
|
143 | </dd> |
128 | <dt>ev_set_allocator (void *(*cb)(void *ptr, long size))</dt> |
144 | <dt>ev_set_allocator (void *(*cb)(void *ptr, long size))</dt> |
129 | <dd> |
145 | <dd> |
130 | <p>Sets the allocation function to use (the prototype is similar to the |
146 | <p>Sets the allocation function to use (the prototype is similar to the |
131 | realloc C function, the semantics are identical). It is used to allocate |
147 | realloc C function, the semantics are identical). It is used to allocate |
132 | and free memory (no surprises here). If it returns zero when memory |
148 | and free memory (no surprises here). If it returns zero when memory |
… | |
… | |
164 | <dt>struct ev_loop *ev_default_loop (unsigned int flags)</dt> |
180 | <dt>struct ev_loop *ev_default_loop (unsigned int flags)</dt> |
165 | <dd> |
181 | <dd> |
166 | <p>This will initialise the default event loop if it hasn't been initialised |
182 | <p>This will initialise the default event loop if it hasn't been initialised |
167 | yet and return it. If the default loop could not be initialised, returns |
183 | yet and return it. If the default loop could not be initialised, returns |
168 | false. If it already was initialised it simply returns it (and ignores the |
184 | false. If it already was initialised it simply returns it (and ignores the |
169 | flags).</p> |
185 | flags. If that is troubling you, check <code>ev_backend ()</code> afterwards).</p> |
170 | <p>If you don't know what event loop to use, use the one returned from this |
186 | <p>If you don't know what event loop to use, use the one returned from this |
171 | function.</p> |
187 | function.</p> |
172 | <p>The flags argument can be used to specify special behaviour or specific |
188 | <p>The flags argument can be used to specify special behaviour or specific |
173 | backends to use, and is usually specified as 0 (or EVFLAG_AUTO).</p> |
189 | backends to use, and is usually specified as <code>0</code> (or EVFLAG_AUTO).</p> |
174 | <p>It supports the following flags:</p> |
190 | <p>It supports the following flags:</p> |
175 | <p> |
191 | <p> |
176 | <dl> |
192 | <dl> |
177 | <dt><code>EVFLAG_AUTO</code></dt> |
193 | <dt><code>EVFLAG_AUTO</code></dt> |
178 | <dd> |
194 | <dd> |
… | |
… | |
186 | <code>LIBEV_FLAGS</code>. Otherwise (the default), this environment variable will |
202 | <code>LIBEV_FLAGS</code>. Otherwise (the default), this environment variable will |
187 | override the flags completely if it is found in the environment. This is |
203 | override the flags completely if it is found in the environment. This is |
188 | useful to try out specific backends to test their performance, or to work |
204 | useful to try out specific backends to test their performance, or to work |
189 | around bugs.</p> |
205 | around bugs.</p> |
190 | </dd> |
206 | </dd> |
191 | <dt><code>EVMETHOD_SELECT</code> (value 1, portable select backend)</dt> |
207 | <dt><code>EVBACKEND_SELECT</code> (value 1, portable select backend)</dt> |
192 | <dd> |
208 | <dd> |
193 | <p>This is your standard select(2) backend. Not <i>completely</i> standard, as |
209 | <p>This is your standard select(2) backend. Not <i>completely</i> standard, as |
194 | libev tries to roll its own fd_set with no limits on the number of fds, |
210 | libev tries to roll its own fd_set with no limits on the number of fds, |
195 | but if that fails, expect a fairly low limit on the number of fds when |
211 | but if that fails, expect a fairly low limit on the number of fds when |
196 | using this backend. It doesn't scale too well (O(highest_fd)), but its usually |
212 | using this backend. It doesn't scale too well (O(highest_fd)), but its usually |
197 | the fastest backend for a low number of fds.</p> |
213 | the fastest backend for a low number of fds.</p> |
198 | </dd> |
214 | </dd> |
199 | <dt><code>EVMETHOD_POLL</code> (value 2, poll backend, available everywhere except on windows)</dt> |
215 | <dt><code>EVBACKEND_POLL</code> (value 2, poll backend, available everywhere except on windows)</dt> |
200 | <dd> |
216 | <dd> |
201 | <p>And this is your standard poll(2) backend. It's more complicated than |
217 | <p>And this is your standard poll(2) backend. It's more complicated than |
202 | select, but handles sparse fds better and has no artificial limit on the |
218 | select, but handles sparse fds better and has no artificial limit on the |
203 | number of fds you can use (except it will slow down considerably with a |
219 | number of fds you can use (except it will slow down considerably with a |
204 | lot of inactive fds). It scales similarly to select, i.e. O(total_fds).</p> |
220 | lot of inactive fds). It scales similarly to select, i.e. O(total_fds).</p> |
205 | </dd> |
221 | </dd> |
206 | <dt><code>EVMETHOD_EPOLL</code> (value 4, Linux)</dt> |
222 | <dt><code>EVBACKEND_EPOLL</code> (value 4, Linux)</dt> |
207 | <dd> |
223 | <dd> |
208 | <p>For few fds, this backend is a bit little slower than poll and select, |
224 | <p>For few fds, this backend is a bit little slower than poll and select, |
209 | but it scales phenomenally better. While poll and select usually scale like |
225 | but it scales phenomenally better. While poll and select usually scale like |
210 | O(total_fds) where n is the total number of fds (or the highest fd), epoll scales |
226 | O(total_fds) where n is the total number of fds (or the highest fd), epoll scales |
211 | either O(1) or O(active_fds).</p> |
227 | either O(1) or O(active_fds).</p> |
… | |
… | |
213 | result in some caching, there is still a syscall per such incident |
229 | result in some caching, there is still a syscall per such incident |
214 | (because the fd could point to a different file description now), so its |
230 | (because the fd could point to a different file description now), so its |
215 | best to avoid that. Also, dup()ed file descriptors might not work very |
231 | best to avoid that. Also, dup()ed file descriptors might not work very |
216 | well if you register events for both fds.</p> |
232 | well if you register events for both fds.</p> |
217 | </dd> |
233 | </dd> |
218 | <dt><code>EVMETHOD_KQUEUE</code> (value 8, most BSD clones)</dt> |
234 | <dt><code>EVBACKEND_KQUEUE</code> (value 8, most BSD clones)</dt> |
219 | <dd> |
235 | <dd> |
220 | <p>Kqueue deserves special mention, as at the time of this writing, it |
236 | <p>Kqueue deserves special mention, as at the time of this writing, it |
221 | was broken on all BSDs except NetBSD (usually it doesn't work with |
237 | was broken on all BSDs except NetBSD (usually it doesn't work with |
222 | anything but sockets and pipes, except on Darwin, where of course its |
238 | anything but sockets and pipes, except on Darwin, where of course its |
223 | completely useless). For this reason its not being "autodetected" unless |
239 | completely useless). For this reason its not being "autodetected" unless |
… | |
… | |
226 | kernel is more efficient (which says nothing about its actual speed, of |
242 | kernel is more efficient (which says nothing about its actual speed, of |
227 | course). While starting and stopping an I/O watcher does not cause an |
243 | course). While starting and stopping an I/O watcher does not cause an |
228 | extra syscall as with epoll, it still adds up to four event changes per |
244 | extra syscall as with epoll, it still adds up to four event changes per |
229 | incident, so its best to avoid that.</p> |
245 | incident, so its best to avoid that.</p> |
230 | </dd> |
246 | </dd> |
231 | <dt><code>EVMETHOD_DEVPOLL</code> (value 16, Solaris 8)</dt> |
247 | <dt><code>EVBACKEND_DEVPOLL</code> (value 16, Solaris 8)</dt> |
232 | <dd> |
248 | <dd> |
233 | <p>This is not implemented yet (and might never be).</p> |
249 | <p>This is not implemented yet (and might never be).</p> |
234 | </dd> |
250 | </dd> |
235 | <dt><code>EVMETHOD_PORT</code> (value 32, Solaris 10)</dt> |
251 | <dt><code>EVBACKEND_PORT</code> (value 32, Solaris 10)</dt> |
236 | <dd> |
252 | <dd> |
237 | <p>This uses the Solaris 10 port mechanism. As with everything on Solaris, |
253 | <p>This uses the Solaris 10 port mechanism. As with everything on Solaris, |
238 | it's really slow, but it still scales very well (O(active_fds)).</p> |
254 | it's really slow, but it still scales very well (O(active_fds)).</p> |
239 | </dd> |
255 | </dd> |
240 | <dt><code>EVMETHOD_ALL</code></dt> |
256 | <dt><code>EVBACKEND_ALL</code></dt> |
241 | <dd> |
257 | <dd> |
242 | <p>Try all backends (even potentially broken ones that wouldn't be tried |
258 | <p>Try all backends (even potentially broken ones that wouldn't be tried |
243 | with <code>EVFLAG_AUTO</code>). Since this is a mask, you can do stuff such as |
259 | with <code>EVFLAG_AUTO</code>). Since this is a mask, you can do stuff such as |
244 | <code>EVMETHOD_ALL & ~EVMETHOD_KQUEUE</code>.</p> |
260 | <code>EVBACKEND_ALL & ~EVBACKEND_KQUEUE</code>.</p> |
245 | </dd> |
261 | </dd> |
246 | </dl> |
262 | </dl> |
247 | </p> |
263 | </p> |
248 | <p>If one or more of these are ored into the flags value, then only these |
264 | <p>If one or more of these are ored into the flags value, then only these |
249 | backends will be tried (in the reverse order as given here). If none are |
265 | backends will be tried (in the reverse order as given here). If none are |
… | |
… | |
272 | <dd> |
288 | <dd> |
273 | <p>This function reinitialises the kernel state for backends that have |
289 | <p>This function reinitialises the kernel state for backends that have |
274 | one. Despite the name, you can call it anytime, but it makes most sense |
290 | one. Despite the name, you can call it anytime, but it makes most sense |
275 | after forking, in either the parent or child process (or both, but that |
291 | after forking, in either the parent or child process (or both, but that |
276 | again makes little sense).</p> |
292 | again makes little sense).</p> |
277 | <p>You <i>must</i> call this function after forking if and only if you want to |
293 | <p>You <i>must</i> call this function in the child process after forking if and |
278 | use the event library in both processes. If you just fork+exec, you don't |
294 | only if you want to use the event library in both processes. If you just |
279 | have to call it.</p> |
295 | fork+exec, you don't have to call it.</p> |
280 | <p>The function itself is quite fast and it's usually not a problem to call |
296 | <p>The function itself is quite fast and it's usually not a problem to call |
281 | it just in case after a fork. To make this easy, the function will fit in |
297 | it just in case after a fork. To make this easy, the function will fit in |
282 | quite nicely into a call to <code>pthread_atfork</code>:</p> |
298 | quite nicely into a call to <code>pthread_atfork</code>:</p> |
283 | <pre> pthread_atfork (0, 0, ev_default_fork); |
299 | <pre> pthread_atfork (0, 0, ev_default_fork); |
284 | |
300 | |
285 | </pre> |
301 | </pre> |
|
|
302 | <p>At the moment, <code>EVBACKEND_SELECT</code> and <code>EVBACKEND_POLL</code> are safe to use |
|
|
303 | without calling this function, so if you force one of those backends you |
|
|
304 | do not need to care.</p> |
286 | </dd> |
305 | </dd> |
287 | <dt>ev_loop_fork (loop)</dt> |
306 | <dt>ev_loop_fork (loop)</dt> |
288 | <dd> |
307 | <dd> |
289 | <p>Like <code>ev_default_fork</code>, but acts on an event loop created by |
308 | <p>Like <code>ev_default_fork</code>, but acts on an event loop created by |
290 | <code>ev_loop_new</code>. Yes, you have to call this on every allocated event loop |
309 | <code>ev_loop_new</code>. Yes, you have to call this on every allocated event loop |
291 | after fork, and how you do this is entirely your own problem.</p> |
310 | after fork, and how you do this is entirely your own problem.</p> |
292 | </dd> |
311 | </dd> |
293 | <dt>unsigned int ev_method (loop)</dt> |
312 | <dt>unsigned int ev_backend (loop)</dt> |
294 | <dd> |
313 | <dd> |
295 | <p>Returns one of the <code>EVMETHOD_*</code> flags indicating the event backend in |
314 | <p>Returns one of the <code>EVBACKEND_*</code> flags indicating the event backend in |
296 | use.</p> |
315 | use.</p> |
297 | </dd> |
316 | </dd> |
298 | <dt>ev_tstamp ev_now (loop)</dt> |
317 | <dt>ev_tstamp ev_now (loop)</dt> |
299 | <dd> |
318 | <dd> |
300 | <p>Returns the current "event loop time", which is the time the event loop |
319 | <p>Returns the current "event loop time", which is the time the event loop |
… | |
… | |
398 | with a watcher-specific start function (<code>ev_<type>_start (loop, watcher |
417 | with a watcher-specific start function (<code>ev_<type>_start (loop, watcher |
399 | *)</code>), and you can stop watching for events at any time by calling the |
418 | *)</code>), and you can stop watching for events at any time by calling the |
400 | corresponding stop function (<code>ev_<type>_stop (loop, watcher *)</code>.</p> |
419 | corresponding stop function (<code>ev_<type>_stop (loop, watcher *)</code>.</p> |
401 | <p>As long as your watcher is active (has been started but not stopped) you |
420 | <p>As long as your watcher is active (has been started but not stopped) you |
402 | must not touch the values stored in it. Most specifically you must never |
421 | must not touch the values stored in it. Most specifically you must never |
403 | reinitialise it or call its set method.</p> |
422 | reinitialise it or call its set macro.</p> |
404 | <p>You can check whether an event is active by calling the <code>ev_is_active |
423 | <p>You can check whether an event is active by calling the <code>ev_is_active |
405 | (watcher *)</code> macro. To see whether an event is outstanding (but the |
424 | (watcher *)</code> macro. To see whether an event is outstanding (but the |
406 | callback for it has not been called yet) you can use the <code>ev_is_pending |
425 | callback for it has not been called yet) you can use the <code>ev_is_pending |
407 | (watcher *)</code> macro.</p> |
426 | (watcher *)</code> macro.</p> |
408 | <p>Each and every callback receives the event loop pointer as first, the |
427 | <p>Each and every callback receives the event loop pointer as first, the |
… | |
… | |
520 | (the linux epoll backend is a notable example) cannot handle dup'ed file |
539 | (the linux epoll backend is a notable example) cannot handle dup'ed file |
521 | descriptors correctly if you register interest in two or more fds pointing |
540 | descriptors correctly if you register interest in two or more fds pointing |
522 | to the same underlying file/socket etc. description (that is, they share |
541 | to the same underlying file/socket etc. description (that is, they share |
523 | the same underlying "file open").</p> |
542 | the same underlying "file open").</p> |
524 | <p>If you must do this, then force the use of a known-to-be-good backend |
543 | <p>If you must do this, then force the use of a known-to-be-good backend |
525 | (at the time of this writing, this includes only EVMETHOD_SELECT and |
544 | (at the time of this writing, this includes only <code>EVBACKEND_SELECT</code> and |
526 | EVMETHOD_POLL).</p> |
545 | <code>EVBACKEND_POLL</code>).</p> |
527 | <dl> |
546 | <dl> |
528 | <dt>ev_io_init (ev_io *, callback, int fd, int events)</dt> |
547 | <dt>ev_io_init (ev_io *, callback, int fd, int events)</dt> |
529 | <dt>ev_io_set (ev_io *, int fd, int events)</dt> |
548 | <dt>ev_io_set (ev_io *, int fd, int events)</dt> |
530 | <dd> |
549 | <dd> |
531 | <p>Configures an <code>ev_io</code> watcher. The fd is the file descriptor to rceeive |
550 | <p>Configures an <code>ev_io</code> watcher. The fd is the file descriptor to rceeive |