… | |
… | |
199 | .Sp |
199 | .Sp |
200 | Usually, it's a good idea to terminate if the major versions mismatch, |
200 | Usually, it's a good idea to terminate if the major versions mismatch, |
201 | as this indicates an incompatible change. Minor versions are usually |
201 | as this indicates an incompatible change. Minor versions are usually |
202 | compatible to older versions, so a larger minor version alone is usually |
202 | compatible to older versions, so a larger minor version alone is usually |
203 | not a problem. |
203 | not a problem. |
|
|
204 | .IP "unsigned int ev_supported_backends ()" 4 |
|
|
205 | .IX Item "unsigned int ev_supported_backends ()" |
|
|
206 | Return the set of all backends (i.e. their corresponding \f(CW\*(C`EV_BACKEND_*\*(C'\fR |
|
|
207 | value) compiled into this binary of libev (independent of their |
|
|
208 | availability on the system you are running on). See \f(CW\*(C`ev_default_loop\*(C'\fR for |
|
|
209 | a description of the set values. |
|
|
210 | .IP "unsigned int ev_recommended_backends ()" 4 |
|
|
211 | .IX Item "unsigned int ev_recommended_backends ()" |
|
|
212 | Return the set of all backends compiled into this binary of libev and also |
|
|
213 | recommended for this platform. This set is often smaller than the one |
|
|
214 | returned by \f(CW\*(C`ev_supported_backends\*(C'\fR, as for example kqueue is broken on |
|
|
215 | most BSDs and will not be autodetected unless you explicitly request it |
|
|
216 | (assuming you know what you are doing). This is the set of backends that |
|
|
217 | \&\f(CW\*(C`EVFLAG_AUTO\*(C'\fR will probe for. |
204 | .IP "ev_set_allocator (void *(*cb)(void *ptr, long size))" 4 |
218 | .IP "ev_set_allocator (void *(*cb)(void *ptr, long size))" 4 |
205 | .IX Item "ev_set_allocator (void *(*cb)(void *ptr, long size))" |
219 | .IX Item "ev_set_allocator (void *(*cb)(void *ptr, long size))" |
206 | Sets the allocation function to use (the prototype is similar to the |
220 | Sets the allocation function to use (the prototype is similar to the |
207 | realloc C function, the semantics are identical). It is used to allocate |
221 | realloc C function, the semantics are identical). It is used to allocate |
208 | and free memory (no surprises here). If it returns zero when memory |
222 | and free memory (no surprises here). If it returns zero when memory |
… | |
… | |
236 | .IP "struct ev_loop *ev_default_loop (unsigned int flags)" 4 |
250 | .IP "struct ev_loop *ev_default_loop (unsigned int flags)" 4 |
237 | .IX Item "struct ev_loop *ev_default_loop (unsigned int flags)" |
251 | .IX Item "struct ev_loop *ev_default_loop (unsigned int flags)" |
238 | This will initialise the default event loop if it hasn't been initialised |
252 | This will initialise the default event loop if it hasn't been initialised |
239 | yet and return it. If the default loop could not be initialised, returns |
253 | yet and return it. If the default loop could not be initialised, returns |
240 | false. If it already was initialised it simply returns it (and ignores the |
254 | false. If it already was initialised it simply returns it (and ignores the |
241 | flags). |
255 | flags. If that is troubling you, check \f(CW\*(C`ev_backend ()\*(C'\fR afterwards). |
242 | .Sp |
256 | .Sp |
243 | If you don't know what event loop to use, use the one returned from this |
257 | If you don't know what event loop to use, use the one returned from this |
244 | function. |
258 | function. |
245 | .Sp |
259 | .Sp |
246 | The flags argument can be used to specify special behaviour or specific |
260 | The flags argument can be used to specify special behaviour or specific |
247 | backends to use, and is usually specified as 0 (or \s-1EVFLAG_AUTO\s0). |
261 | backends to use, and is usually specified as \f(CW0\fR (or \s-1EVFLAG_AUTO\s0). |
248 | .Sp |
262 | .Sp |
249 | It supports the following flags: |
263 | It supports the following flags: |
250 | .RS 4 |
264 | .RS 4 |
251 | .ie n .IP """EVFLAG_AUTO""" 4 |
265 | .ie n .IP """EVFLAG_AUTO""" 4 |
252 | .el .IP "\f(CWEVFLAG_AUTO\fR" 4 |
266 | .el .IP "\f(CWEVFLAG_AUTO\fR" 4 |
… | |
… | |
260 | or setgid) then libev will \fInot\fR look at the environment variable |
274 | or setgid) then libev will \fInot\fR look at the environment variable |
261 | \&\f(CW\*(C`LIBEV_FLAGS\*(C'\fR. Otherwise (the default), this environment variable will |
275 | \&\f(CW\*(C`LIBEV_FLAGS\*(C'\fR. Otherwise (the default), this environment variable will |
262 | override the flags completely if it is found in the environment. This is |
276 | override the flags completely if it is found in the environment. This is |
263 | useful to try out specific backends to test their performance, or to work |
277 | useful to try out specific backends to test their performance, or to work |
264 | around bugs. |
278 | around bugs. |
265 | .ie n .IP """EVMETHOD_SELECT"" (value 1, portable select backend)" 4 |
279 | .ie n .IP """EVBACKEND_SELECT"" (value 1, portable select backend)" 4 |
266 | .el .IP "\f(CWEVMETHOD_SELECT\fR (value 1, portable select backend)" 4 |
280 | .el .IP "\f(CWEVBACKEND_SELECT\fR (value 1, portable select backend)" 4 |
267 | .IX Item "EVMETHOD_SELECT (value 1, portable select backend)" |
281 | .IX Item "EVBACKEND_SELECT (value 1, portable select backend)" |
268 | This is your standard \fIselect\fR\|(2) backend. Not \fIcompletely\fR standard, as |
282 | This is your standard \fIselect\fR\|(2) backend. Not \fIcompletely\fR standard, as |
269 | libev tries to roll its own fd_set with no limits on the number of fds, |
283 | libev tries to roll its own fd_set with no limits on the number of fds, |
270 | but if that fails, expect a fairly low limit on the number of fds when |
284 | but if that fails, expect a fairly low limit on the number of fds when |
271 | using this backend. It doesn't scale too well (O(highest_fd)), but its usually |
285 | using this backend. It doesn't scale too well (O(highest_fd)), but its usually |
272 | the fastest backend for a low number of fds. |
286 | the fastest backend for a low number of fds. |
273 | .ie n .IP """EVMETHOD_POLL"" (value 2, poll backend, available everywhere except on windows)" 4 |
287 | .ie n .IP """EVBACKEND_POLL"" (value 2, poll backend, available everywhere except on windows)" 4 |
274 | .el .IP "\f(CWEVMETHOD_POLL\fR (value 2, poll backend, available everywhere except on windows)" 4 |
288 | .el .IP "\f(CWEVBACKEND_POLL\fR (value 2, poll backend, available everywhere except on windows)" 4 |
275 | .IX Item "EVMETHOD_POLL (value 2, poll backend, available everywhere except on windows)" |
289 | .IX Item "EVBACKEND_POLL (value 2, poll backend, available everywhere except on windows)" |
276 | And this is your standard \fIpoll\fR\|(2) backend. It's more complicated than |
290 | And this is your standard \fIpoll\fR\|(2) backend. It's more complicated than |
277 | select, but handles sparse fds better and has no artificial limit on the |
291 | select, but handles sparse fds better and has no artificial limit on the |
278 | number of fds you can use (except it will slow down considerably with a |
292 | number of fds you can use (except it will slow down considerably with a |
279 | lot of inactive fds). It scales similarly to select, i.e. O(total_fds). |
293 | lot of inactive fds). It scales similarly to select, i.e. O(total_fds). |
280 | .ie n .IP """EVMETHOD_EPOLL"" (value 4, Linux)" 4 |
294 | .ie n .IP """EVBACKEND_EPOLL"" (value 4, Linux)" 4 |
281 | .el .IP "\f(CWEVMETHOD_EPOLL\fR (value 4, Linux)" 4 |
295 | .el .IP "\f(CWEVBACKEND_EPOLL\fR (value 4, Linux)" 4 |
282 | .IX Item "EVMETHOD_EPOLL (value 4, Linux)" |
296 | .IX Item "EVBACKEND_EPOLL (value 4, Linux)" |
283 | For few fds, this backend is a bit little slower than poll and select, |
297 | For few fds, this backend is a bit little slower than poll and select, |
284 | but it scales phenomenally better. While poll and select usually scale like |
298 | but it scales phenomenally better. While poll and select usually scale like |
285 | O(total_fds) where n is the total number of fds (or the highest fd), epoll scales |
299 | O(total_fds) where n is the total number of fds (or the highest fd), epoll scales |
286 | either O(1) or O(active_fds). |
300 | either O(1) or O(active_fds). |
287 | .Sp |
301 | .Sp |
288 | While stopping and starting an I/O watcher in the same iteration will |
302 | While stopping and starting an I/O watcher in the same iteration will |
289 | result in some caching, there is still a syscall per such incident |
303 | result in some caching, there is still a syscall per such incident |
290 | (because the fd could point to a different file description now), so its |
304 | (because the fd could point to a different file description now), so its |
291 | best to avoid that. Also, \fIdup()\fRed file descriptors might not work very |
305 | best to avoid that. Also, \fIdup()\fRed file descriptors might not work very |
292 | well if you register events for both fds. |
306 | well if you register events for both fds. |
293 | .ie n .IP """EVMETHOD_KQUEUE"" (value 8, most \s-1BSD\s0 clones)" 4 |
307 | .ie n .IP """EVBACKEND_KQUEUE"" (value 8, most \s-1BSD\s0 clones)" 4 |
294 | .el .IP "\f(CWEVMETHOD_KQUEUE\fR (value 8, most \s-1BSD\s0 clones)" 4 |
308 | .el .IP "\f(CWEVBACKEND_KQUEUE\fR (value 8, most \s-1BSD\s0 clones)" 4 |
295 | .IX Item "EVMETHOD_KQUEUE (value 8, most BSD clones)" |
309 | .IX Item "EVBACKEND_KQUEUE (value 8, most BSD clones)" |
296 | Kqueue deserves special mention, as at the time of this writing, it |
310 | Kqueue deserves special mention, as at the time of this writing, it |
297 | was broken on all BSDs except NetBSD (usually it doesn't work with |
311 | was broken on all BSDs except NetBSD (usually it doesn't work with |
298 | anything but sockets and pipes, except on Darwin, where of course its |
312 | anything but sockets and pipes, except on Darwin, where of course its |
299 | completely useless). For this reason its not being \*(L"autodetected\*(R" unless |
313 | completely useless). For this reason its not being \*(L"autodetected\*(R" unless |
300 | you explicitly specify the flags (i.e. you don't use \s-1EVFLAG_AUTO\s0). |
314 | you explicitly specify the flags (i.e. you don't use \s-1EVFLAG_AUTO\s0). |
… | |
… | |
302 | It scales in the same way as the epoll backend, but the interface to the |
316 | It scales in the same way as the epoll backend, but the interface to the |
303 | kernel is more efficient (which says nothing about its actual speed, of |
317 | kernel is more efficient (which says nothing about its actual speed, of |
304 | course). While starting and stopping an I/O watcher does not cause an |
318 | course). While starting and stopping an I/O watcher does not cause an |
305 | extra syscall as with epoll, it still adds up to four event changes per |
319 | extra syscall as with epoll, it still adds up to four event changes per |
306 | incident, so its best to avoid that. |
320 | incident, so its best to avoid that. |
307 | .ie n .IP """EVMETHOD_DEVPOLL"" (value 16, Solaris 8)" 4 |
321 | .ie n .IP """EVBACKEND_DEVPOLL"" (value 16, Solaris 8)" 4 |
308 | .el .IP "\f(CWEVMETHOD_DEVPOLL\fR (value 16, Solaris 8)" 4 |
322 | .el .IP "\f(CWEVBACKEND_DEVPOLL\fR (value 16, Solaris 8)" 4 |
309 | .IX Item "EVMETHOD_DEVPOLL (value 16, Solaris 8)" |
323 | .IX Item "EVBACKEND_DEVPOLL (value 16, Solaris 8)" |
310 | This is not implemented yet (and might never be). |
324 | This is not implemented yet (and might never be). |
311 | .ie n .IP """EVMETHOD_PORT"" (value 32, Solaris 10)" 4 |
325 | .ie n .IP """EVBACKEND_PORT"" (value 32, Solaris 10)" 4 |
312 | .el .IP "\f(CWEVMETHOD_PORT\fR (value 32, Solaris 10)" 4 |
326 | .el .IP "\f(CWEVBACKEND_PORT\fR (value 32, Solaris 10)" 4 |
313 | .IX Item "EVMETHOD_PORT (value 32, Solaris 10)" |
327 | .IX Item "EVBACKEND_PORT (value 32, Solaris 10)" |
314 | This uses the Solaris 10 port mechanism. As with everything on Solaris, |
328 | This uses the Solaris 10 port mechanism. As with everything on Solaris, |
315 | it's really slow, but it still scales very well (O(active_fds)). |
329 | it's really slow, but it still scales very well (O(active_fds)). |
316 | .ie n .IP """EVMETHOD_ALL""" 4 |
330 | .ie n .IP """EVBACKEND_ALL""" 4 |
317 | .el .IP "\f(CWEVMETHOD_ALL\fR" 4 |
331 | .el .IP "\f(CWEVBACKEND_ALL\fR" 4 |
318 | .IX Item "EVMETHOD_ALL" |
332 | .IX Item "EVBACKEND_ALL" |
319 | Try all backends (even potentially broken ones that wouldn't be tried |
333 | Try all backends (even potentially broken ones that wouldn't be tried |
320 | with \f(CW\*(C`EVFLAG_AUTO\*(C'\fR). Since this is a mask, you can do stuff such as |
334 | with \f(CW\*(C`EVFLAG_AUTO\*(C'\fR). Since this is a mask, you can do stuff such as |
321 | \&\f(CW\*(C`EVMETHOD_ALL & ~EVMETHOD_KQUEUE\*(C'\fR. |
335 | \&\f(CW\*(C`EVBACKEND_ALL & ~EVBACKEND_KQUEUE\*(C'\fR. |
322 | .RE |
336 | .RE |
323 | .RS 4 |
337 | .RS 4 |
324 | .Sp |
338 | .Sp |
325 | If one or more of these are ored into the flags value, then only these |
339 | If one or more of these are ored into the flags value, then only these |
326 | backends will be tried (in the reverse order as given here). If none are |
340 | backends will be tried (in the reverse order as given here). If none are |
… | |
… | |
358 | quite nicely into a call to \f(CW\*(C`pthread_atfork\*(C'\fR: |
372 | quite nicely into a call to \f(CW\*(C`pthread_atfork\*(C'\fR: |
359 | .Sp |
373 | .Sp |
360 | .Vb 1 |
374 | .Vb 1 |
361 | \& pthread_atfork (0, 0, ev_default_fork); |
375 | \& pthread_atfork (0, 0, ev_default_fork); |
362 | .Ve |
376 | .Ve |
|
|
377 | .Sp |
|
|
378 | At the moment, \f(CW\*(C`EVBACKEND_SELECT\*(C'\fR and \f(CW\*(C`EVBACKEND_POLL\*(C'\fR are safe to use |
|
|
379 | without calling this function, so if you force one of those backends you |
|
|
380 | do not need to care. |
363 | .IP "ev_loop_fork (loop)" 4 |
381 | .IP "ev_loop_fork (loop)" 4 |
364 | .IX Item "ev_loop_fork (loop)" |
382 | .IX Item "ev_loop_fork (loop)" |
365 | Like \f(CW\*(C`ev_default_fork\*(C'\fR, but acts on an event loop created by |
383 | Like \f(CW\*(C`ev_default_fork\*(C'\fR, but acts on an event loop created by |
366 | \&\f(CW\*(C`ev_loop_new\*(C'\fR. Yes, you have to call this on every allocated event loop |
384 | \&\f(CW\*(C`ev_loop_new\*(C'\fR. Yes, you have to call this on every allocated event loop |
367 | after fork, and how you do this is entirely your own problem. |
385 | after fork, and how you do this is entirely your own problem. |
368 | .IP "unsigned int ev_method (loop)" 4 |
386 | .IP "unsigned int ev_backend (loop)" 4 |
369 | .IX Item "unsigned int ev_method (loop)" |
387 | .IX Item "unsigned int ev_backend (loop)" |
370 | Returns one of the \f(CW\*(C`EVMETHOD_*\*(C'\fR flags indicating the event backend in |
388 | Returns one of the \f(CW\*(C`EVBACKEND_*\*(C'\fR flags indicating the event backend in |
371 | use. |
389 | use. |
372 | .IP "ev_tstamp ev_now (loop)" 4 |
390 | .IP "ev_tstamp ev_now (loop)" 4 |
373 | .IX Item "ev_tstamp ev_now (loop)" |
391 | .IX Item "ev_tstamp ev_now (loop)" |
374 | Returns the current \*(L"event loop time\*(R", which is the time the event loop |
392 | Returns the current \*(L"event loop time\*(R", which is the time the event loop |
375 | got events and started processing them. This timestamp does not change |
393 | got events and started processing them. This timestamp does not change |
… | |
… | |
482 | *)\*(C'\fR), and you can stop watching for events at any time by calling the |
500 | *)\*(C'\fR), and you can stop watching for events at any time by calling the |
483 | corresponding stop function (\f(CW\*(C`ev_<type>_stop (loop, watcher *)\*(C'\fR. |
501 | corresponding stop function (\f(CW\*(C`ev_<type>_stop (loop, watcher *)\*(C'\fR. |
484 | .PP |
502 | .PP |
485 | As long as your watcher is active (has been started but not stopped) you |
503 | As long as your watcher is active (has been started but not stopped) you |
486 | must not touch the values stored in it. Most specifically you must never |
504 | must not touch the values stored in it. Most specifically you must never |
487 | reinitialise it or call its set method. |
505 | reinitialise it or call its set macro. |
488 | .PP |
506 | .PP |
489 | You can check whether an event is active by calling the \f(CW\*(C`ev_is_active |
507 | You can check whether an event is active by calling the \f(CW\*(C`ev_is_active |
490 | (watcher *)\*(C'\fR macro. To see whether an event is outstanding (but the |
508 | (watcher *)\*(C'\fR macro. To see whether an event is outstanding (but the |
491 | callback for it has not been called yet) you can use the \f(CW\*(C`ev_is_pending |
509 | callback for it has not been called yet) you can use the \f(CW\*(C`ev_is_pending |
492 | (watcher *)\*(C'\fR macro. |
510 | (watcher *)\*(C'\fR macro. |
… | |
… | |
612 | descriptors correctly if you register interest in two or more fds pointing |
630 | descriptors correctly if you register interest in two or more fds pointing |
613 | to the same underlying file/socket etc. description (that is, they share |
631 | to the same underlying file/socket etc. description (that is, they share |
614 | the same underlying \*(L"file open\*(R"). |
632 | the same underlying \*(L"file open\*(R"). |
615 | .PP |
633 | .PP |
616 | If you must do this, then force the use of a known-to-be-good backend |
634 | If you must do this, then force the use of a known-to-be-good backend |
617 | (at the time of this writing, this includes only \s-1EVMETHOD_SELECT\s0 and |
635 | (at the time of this writing, this includes only \f(CW\*(C`EVBACKEND_SELECT\*(C'\fR and |
618 | \&\s-1EVMETHOD_POLL\s0). |
636 | \&\f(CW\*(C`EVBACKEND_POLL\*(C'\fR). |
619 | .IP "ev_io_init (ev_io *, callback, int fd, int events)" 4 |
637 | .IP "ev_io_init (ev_io *, callback, int fd, int events)" 4 |
620 | .IX Item "ev_io_init (ev_io *, callback, int fd, int events)" |
638 | .IX Item "ev_io_init (ev_io *, callback, int fd, int events)" |
621 | .PD 0 |
639 | .PD 0 |
622 | .IP "ev_io_set (ev_io *, int fd, int events)" 4 |
640 | .IP "ev_io_set (ev_io *, int fd, int events)" 4 |
623 | .IX Item "ev_io_set (ev_io *, int fd, int events)" |
641 | .IX Item "ev_io_set (ev_io *, int fd, int events)" |