… | |
… | |
127 | .\} |
127 | .\} |
128 | .rm #[ #] #H #V #F C |
128 | .rm #[ #] #H #V #F C |
129 | .\" ======================================================================== |
129 | .\" ======================================================================== |
130 | .\" |
130 | .\" |
131 | .IX Title "EV 1" |
131 | .IX Title "EV 1" |
132 | .TH EV 1 "2007-12-22" "perl v5.8.8" "User Contributed Perl Documentation" |
132 | .TH EV 1 "2007-12-25" "perl v5.8.8" "User Contributed Perl Documentation" |
133 | .SH "NAME" |
133 | .SH "NAME" |
134 | libev \- a high performance full\-featured event loop written in C |
134 | libev \- a high performance full\-featured event loop written in C |
135 | .SH "SYNOPSIS" |
135 | .SH "SYNOPSIS" |
136 | .IX Header "SYNOPSIS" |
136 | .IX Header "SYNOPSIS" |
137 | .Vb 1 |
137 | .Vb 1 |
138 | \& #include <ev.h> |
138 | \& #include <ev.h> |
139 | .Ve |
139 | .Ve |
140 | .SH "EXAMPLE PROGRAM" |
140 | .Sh "\s-1EXAMPLE\s0 \s-1PROGRAM\s0" |
141 | .IX Header "EXAMPLE PROGRAM" |
141 | .IX Subsection "EXAMPLE PROGRAM" |
142 | .Vb 1 |
142 | .Vb 1 |
143 | \& #include <ev.h> |
143 | \& #include <ev.h> |
144 | .Ve |
144 | .Ve |
145 | .PP |
145 | .PP |
146 | .Vb 2 |
146 | .Vb 2 |
… | |
… | |
212 | .PP |
212 | .PP |
213 | You register interest in certain events by registering so-called \fIevent |
213 | You register interest in certain events by registering so-called \fIevent |
214 | watchers\fR, which are relatively small C structures you initialise with the |
214 | watchers\fR, which are relatively small C structures you initialise with the |
215 | details of the event, and then hand it over to libev by \fIstarting\fR the |
215 | details of the event, and then hand it over to libev by \fIstarting\fR the |
216 | watcher. |
216 | watcher. |
217 | .SH "FEATURES" |
217 | .Sh "\s-1FEATURES\s0" |
218 | .IX Header "FEATURES" |
218 | .IX Subsection "FEATURES" |
219 | Libev supports \f(CW\*(C`select\*(C'\fR, \f(CW\*(C`poll\*(C'\fR, the Linux-specific \f(CW\*(C`epoll\*(C'\fR, the |
219 | Libev supports \f(CW\*(C`select\*(C'\fR, \f(CW\*(C`poll\*(C'\fR, the Linux-specific \f(CW\*(C`epoll\*(C'\fR, the |
220 | BSD-specific \f(CW\*(C`kqueue\*(C'\fR and the Solaris-specific event port mechanisms |
220 | BSD-specific \f(CW\*(C`kqueue\*(C'\fR and the Solaris-specific event port mechanisms |
221 | for file descriptor events (\f(CW\*(C`ev_io\*(C'\fR), the Linux \f(CW\*(C`inotify\*(C'\fR interface |
221 | for file descriptor events (\f(CW\*(C`ev_io\*(C'\fR), the Linux \f(CW\*(C`inotify\*(C'\fR interface |
222 | (for \f(CW\*(C`ev_stat\*(C'\fR), relative timers (\f(CW\*(C`ev_timer\*(C'\fR), absolute timers |
222 | (for \f(CW\*(C`ev_stat\*(C'\fR), relative timers (\f(CW\*(C`ev_timer\*(C'\fR), absolute timers |
223 | with customised rescheduling (\f(CW\*(C`ev_periodic\*(C'\fR), synchronous signals |
223 | with customised rescheduling (\f(CW\*(C`ev_periodic\*(C'\fR), synchronous signals |
… | |
… | |
228 | (\f(CW\*(C`ev_fork\*(C'\fR). |
228 | (\f(CW\*(C`ev_fork\*(C'\fR). |
229 | .PP |
229 | .PP |
230 | It also is quite fast (see this |
230 | It also is quite fast (see this |
231 | benchmark comparing it to libevent |
231 | benchmark comparing it to libevent |
232 | for example). |
232 | for example). |
233 | .SH "CONVENTIONS" |
233 | .Sh "\s-1CONVENTIONS\s0" |
234 | .IX Header "CONVENTIONS" |
234 | .IX Subsection "CONVENTIONS" |
235 | Libev is very configurable. In this manual the default configuration will |
235 | Libev is very configurable. In this manual the default configuration will |
236 | be described, which supports multiple event loops. For more info about |
236 | be described, which supports multiple event loops. For more info about |
237 | various configuration options please have a look at \fB\s-1EMBED\s0\fR section in |
237 | various configuration options please have a look at \fB\s-1EMBED\s0\fR section in |
238 | this manual. If libev was configured without support for multiple event |
238 | this manual. If libev was configured without support for multiple event |
239 | loops, then all functions taking an initial argument of name \f(CW\*(C`loop\*(C'\fR |
239 | loops, then all functions taking an initial argument of name \f(CW\*(C`loop\*(C'\fR |
240 | (which is always of type \f(CW\*(C`struct ev_loop *\*(C'\fR) will not have this argument. |
240 | (which is always of type \f(CW\*(C`struct ev_loop *\*(C'\fR) will not have this argument. |
241 | .SH "TIME REPRESENTATION" |
241 | .Sh "\s-1TIME\s0 \s-1REPRESENTATION\s0" |
242 | .IX Header "TIME REPRESENTATION" |
242 | .IX Subsection "TIME REPRESENTATION" |
243 | Libev represents time as a single floating point number, representing the |
243 | Libev represents time as a single floating point number, representing the |
244 | (fractional) number of seconds since the (\s-1POSIX\s0) epoch (somewhere near |
244 | (fractional) number of seconds since the (\s-1POSIX\s0) epoch (somewhere near |
245 | the beginning of 1970, details are complicated, don't ask). This type is |
245 | the beginning of 1970, details are complicated, don't ask). This type is |
246 | called \f(CW\*(C`ev_tstamp\*(C'\fR, which is what you should use too. It usually aliases |
246 | called \f(CW\*(C`ev_tstamp\*(C'\fR, which is what you should use too. It usually aliases |
247 | to the \f(CW\*(C`double\*(C'\fR type in C, and when you need to do any calculations on |
247 | to the \f(CW\*(C`double\*(C'\fR type in C, and when you need to do any calculations on |
… | |
… | |
255 | .IP "ev_tstamp ev_time ()" 4 |
255 | .IP "ev_tstamp ev_time ()" 4 |
256 | .IX Item "ev_tstamp ev_time ()" |
256 | .IX Item "ev_tstamp ev_time ()" |
257 | Returns the current time as libev would use it. Please note that the |
257 | Returns the current time as libev would use it. Please note that the |
258 | \&\f(CW\*(C`ev_now\*(C'\fR function is usually faster and also often returns the timestamp |
258 | \&\f(CW\*(C`ev_now\*(C'\fR function is usually faster and also often returns the timestamp |
259 | you actually want to know. |
259 | you actually want to know. |
260 | .IP "void ev_sleep (ev_tstamp interval)" 4 |
260 | .IP "ev_sleep (ev_tstamp interval)" 4 |
261 | .IX Item "void ev_sleep (ev_tstamp interval)" |
261 | .IX Item "ev_sleep (ev_tstamp interval)" |
262 | Sleep for the given interval: The current thread will be blocked until |
262 | Sleep for the given interval: The current thread will be blocked until |
263 | either it is interrupted or the given time interval has passed. Basically |
263 | either it is interrupted or the given time interval has passed. Basically |
264 | this is a subsecond-resolution \f(CW\*(C`sleep ()\*(C'\fR. |
264 | this is a subsecond-resolution \f(CW\*(C`sleep ()\*(C'\fR. |
265 | .IP "int ev_version_major ()" 4 |
265 | .IP "int ev_version_major ()" 4 |
266 | .IX Item "int ev_version_major ()" |
266 | .IX Item "int ev_version_major ()" |
… | |
… | |
451 | .el .IP "\f(CWEVBACKEND_SELECT\fR (value 1, portable select backend)" 4 |
451 | .el .IP "\f(CWEVBACKEND_SELECT\fR (value 1, portable select backend)" 4 |
452 | .IX Item "EVBACKEND_SELECT (value 1, portable select backend)" |
452 | .IX Item "EVBACKEND_SELECT (value 1, portable select backend)" |
453 | This is your standard \fIselect\fR\|(2) backend. Not \fIcompletely\fR standard, as |
453 | This is your standard \fIselect\fR\|(2) backend. Not \fIcompletely\fR standard, as |
454 | libev tries to roll its own fd_set with no limits on the number of fds, |
454 | libev tries to roll its own fd_set with no limits on the number of fds, |
455 | but if that fails, expect a fairly low limit on the number of fds when |
455 | but if that fails, expect a fairly low limit on the number of fds when |
456 | using this backend. It doesn't scale too well (O(highest_fd)), but its usually |
456 | using this backend. It doesn't scale too well (O(highest_fd)), but its |
457 | the fastest backend for a low number of fds. |
457 | usually the fastest backend for a low number of (low\-numbered :) fds. |
|
|
458 | .Sp |
|
|
459 | To get good performance out of this backend you need a high amount of |
|
|
460 | parallelity (most of the file descriptors should be busy). If you are |
|
|
461 | writing a server, you should \f(CW\*(C`accept ()\*(C'\fR in a loop to accept as many |
|
|
462 | connections as possible during one iteration. You might also want to have |
|
|
463 | a look at \f(CW\*(C`ev_set_io_collect_interval ()\*(C'\fR to increase the amount of |
|
|
464 | readyness notifications you get per iteration. |
458 | .ie n .IP """EVBACKEND_POLL"" (value 2, poll backend, available everywhere except on windows)" 4 |
465 | .ie n .IP """EVBACKEND_POLL"" (value 2, poll backend, available everywhere except on windows)" 4 |
459 | .el .IP "\f(CWEVBACKEND_POLL\fR (value 2, poll backend, available everywhere except on windows)" 4 |
466 | .el .IP "\f(CWEVBACKEND_POLL\fR (value 2, poll backend, available everywhere except on windows)" 4 |
460 | .IX Item "EVBACKEND_POLL (value 2, poll backend, available everywhere except on windows)" |
467 | .IX Item "EVBACKEND_POLL (value 2, poll backend, available everywhere except on windows)" |
461 | And this is your standard \fIpoll\fR\|(2) backend. It's more complicated than |
468 | And this is your standard \fIpoll\fR\|(2) backend. It's more complicated |
462 | select, but handles sparse fds better and has no artificial limit on the |
469 | than select, but handles sparse fds better and has no artificial |
463 | number of fds you can use (except it will slow down considerably with a |
470 | limit on the number of fds you can use (except it will slow down |
464 | lot of inactive fds). It scales similarly to select, i.e. O(total_fds). |
471 | considerably with a lot of inactive fds). It scales similarly to select, |
|
|
472 | i.e. O(total_fds). See the entry for \f(CW\*(C`EVBACKEND_SELECT\*(C'\fR, above, for |
|
|
473 | performance tips. |
465 | .ie n .IP """EVBACKEND_EPOLL"" (value 4, Linux)" 4 |
474 | .ie n .IP """EVBACKEND_EPOLL"" (value 4, Linux)" 4 |
466 | .el .IP "\f(CWEVBACKEND_EPOLL\fR (value 4, Linux)" 4 |
475 | .el .IP "\f(CWEVBACKEND_EPOLL\fR (value 4, Linux)" 4 |
467 | .IX Item "EVBACKEND_EPOLL (value 4, Linux)" |
476 | .IX Item "EVBACKEND_EPOLL (value 4, Linux)" |
468 | For few fds, this backend is a bit little slower than poll and select, |
477 | For few fds, this backend is a bit little slower than poll and select, |
469 | but it scales phenomenally better. While poll and select usually scale |
478 | but it scales phenomenally better. While poll and select usually scale |
470 | like O(total_fds) where n is the total number of fds (or the highest fd), |
479 | like O(total_fds) where n is the total number of fds (or the highest fd), |
471 | epoll scales either O(1) or O(active_fds). The epoll design has a number |
480 | epoll scales either O(1) or O(active_fds). The epoll design has a number |
472 | of shortcomings, such as silently dropping events in some hard-to-detect |
481 | of shortcomings, such as silently dropping events in some hard-to-detect |
473 | cases and rewiring a syscall per fd change, no fork support and bad |
482 | cases and rewiring a syscall per fd change, no fork support and bad |
474 | support for dup: |
483 | support for dup. |
475 | .Sp |
484 | .Sp |
476 | While stopping, setting and starting an I/O watcher in the same iteration |
485 | While stopping, setting and starting an I/O watcher in the same iteration |
477 | will result in some caching, there is still a syscall per such incident |
486 | will result in some caching, there is still a syscall per such incident |
478 | (because the fd could point to a different file description now), so its |
487 | (because the fd could point to a different file description now), so its |
479 | best to avoid that. Also, \f(CW\*(C`dup ()\*(C'\fR'ed file descriptors might not work |
488 | best to avoid that. Also, \f(CW\*(C`dup ()\*(C'\fR'ed file descriptors might not work |
480 | very well if you register events for both fds. |
489 | very well if you register events for both fds. |
481 | .Sp |
490 | .Sp |
482 | Please note that epoll sometimes generates spurious notifications, so you |
491 | Please note that epoll sometimes generates spurious notifications, so you |
483 | need to use non-blocking I/O or other means to avoid blocking when no data |
492 | need to use non-blocking I/O or other means to avoid blocking when no data |
484 | (or space) is available. |
493 | (or space) is available. |
|
|
494 | .Sp |
|
|
495 | Best performance from this backend is achieved by not unregistering all |
|
|
496 | watchers for a file descriptor until it has been closed, if possible, i.e. |
|
|
497 | keep at least one watcher active per fd at all times. |
|
|
498 | .Sp |
|
|
499 | While nominally embeddeble in other event loops, this feature is broken in |
|
|
500 | all kernel versions tested so far. |
485 | .ie n .IP """EVBACKEND_KQUEUE"" (value 8, most \s-1BSD\s0 clones)" 4 |
501 | .ie n .IP """EVBACKEND_KQUEUE"" (value 8, most \s-1BSD\s0 clones)" 4 |
486 | .el .IP "\f(CWEVBACKEND_KQUEUE\fR (value 8, most \s-1BSD\s0 clones)" 4 |
502 | .el .IP "\f(CWEVBACKEND_KQUEUE\fR (value 8, most \s-1BSD\s0 clones)" 4 |
487 | .IX Item "EVBACKEND_KQUEUE (value 8, most BSD clones)" |
503 | .IX Item "EVBACKEND_KQUEUE (value 8, most BSD clones)" |
488 | Kqueue deserves special mention, as at the time of this writing, it |
504 | Kqueue deserves special mention, as at the time of this writing, it |
489 | was broken on \fIall\fR BSDs (usually it doesn't work with anything but |
505 | was broken on all BSDs except NetBSD (usually it doesn't work reliably |
490 | sockets and pipes, except on Darwin, where of course it's completely |
506 | with anything but sockets and pipes, except on Darwin, where of course |
491 | useless. On NetBSD, it seems to work for all the \s-1FD\s0 types I tested, so it |
|
|
492 | is used by default there). For this reason it's not being \*(L"autodetected\*(R" |
507 | it's completely useless). For this reason it's not being \*(L"autodetected\*(R" |
493 | unless you explicitly specify it explicitly in the flags (i.e. using |
508 | unless you explicitly specify it explicitly in the flags (i.e. using |
494 | \&\f(CW\*(C`EVBACKEND_KQUEUE\*(C'\fR) or libev was compiled on a known-to-be-good (\-enough) |
509 | \&\f(CW\*(C`EVBACKEND_KQUEUE\*(C'\fR) or libev was compiled on a known-to-be-good (\-enough) |
495 | system like NetBSD. |
510 | system like NetBSD. |
496 | .Sp |
511 | .Sp |
|
|
512 | You still can embed kqueue into a normal poll or select backend and use it |
|
|
513 | only for sockets (after having made sure that sockets work with kqueue on |
|
|
514 | the target platform). See \f(CW\*(C`ev_embed\*(C'\fR watchers for more info. |
|
|
515 | .Sp |
497 | It scales in the same way as the epoll backend, but the interface to the |
516 | It scales in the same way as the epoll backend, but the interface to the |
498 | kernel is more efficient (which says nothing about its actual speed, |
517 | kernel is more efficient (which says nothing about its actual speed, of |
499 | of course). While stopping, setting and starting an I/O watcher does |
518 | course). While stopping, setting and starting an I/O watcher does never |
500 | never cause an extra syscall as with epoll, it still adds up to two event |
519 | cause an extra syscall as with \f(CW\*(C`EVBACKEND_EPOLL\*(C'\fR, it still adds up to |
501 | changes per incident, support for \f(CW\*(C`fork ()\*(C'\fR is very bad and it drops fds |
520 | two event changes per incident, support for \f(CW\*(C`fork ()\*(C'\fR is very bad and it |
502 | silently in similarly hard-to-detetc cases. |
521 | drops fds silently in similarly hard-to-detect cases. |
|
|
522 | .Sp |
|
|
523 | This backend usually performs well under most conditions. |
|
|
524 | .Sp |
|
|
525 | While nominally embeddable in other event loops, this doesn't work |
|
|
526 | everywhere, so you might need to test for this. And since it is broken |
|
|
527 | almost everywhere, you should only use it when you have a lot of sockets |
|
|
528 | (for which it usually works), by embedding it into another event loop |
|
|
529 | (e.g. \f(CW\*(C`EVBACKEND_SELECT\*(C'\fR or \f(CW\*(C`EVBACKEND_POLL\*(C'\fR) and using it only for |
|
|
530 | sockets. |
503 | .ie n .IP """EVBACKEND_DEVPOLL"" (value 16, Solaris 8)" 4 |
531 | .ie n .IP """EVBACKEND_DEVPOLL"" (value 16, Solaris 8)" 4 |
504 | .el .IP "\f(CWEVBACKEND_DEVPOLL\fR (value 16, Solaris 8)" 4 |
532 | .el .IP "\f(CWEVBACKEND_DEVPOLL\fR (value 16, Solaris 8)" 4 |
505 | .IX Item "EVBACKEND_DEVPOLL (value 16, Solaris 8)" |
533 | .IX Item "EVBACKEND_DEVPOLL (value 16, Solaris 8)" |
506 | This is not implemented yet (and might never be). |
534 | This is not implemented yet (and might never be, unless you send me an |
|
|
535 | implementation). According to reports, \f(CW\*(C`/dev/poll\*(C'\fR only supports sockets |
|
|
536 | and is not embeddable, which would limit the usefulness of this backend |
|
|
537 | immensely. |
507 | .ie n .IP """EVBACKEND_PORT"" (value 32, Solaris 10)" 4 |
538 | .ie n .IP """EVBACKEND_PORT"" (value 32, Solaris 10)" 4 |
508 | .el .IP "\f(CWEVBACKEND_PORT\fR (value 32, Solaris 10)" 4 |
539 | .el .IP "\f(CWEVBACKEND_PORT\fR (value 32, Solaris 10)" 4 |
509 | .IX Item "EVBACKEND_PORT (value 32, Solaris 10)" |
540 | .IX Item "EVBACKEND_PORT (value 32, Solaris 10)" |
510 | This uses the Solaris 10 event port mechanism. As with everything on Solaris, |
541 | This uses the Solaris 10 event port mechanism. As with everything on Solaris, |
511 | it's really slow, but it still scales very well (O(active_fds)). |
542 | it's really slow, but it still scales very well (O(active_fds)). |
512 | .Sp |
543 | .Sp |
513 | Please note that solaris event ports can deliver a lot of spurious |
544 | Please note that solaris event ports can deliver a lot of spurious |
514 | notifications, so you need to use non-blocking I/O or other means to avoid |
545 | notifications, so you need to use non-blocking I/O or other means to avoid |
515 | blocking when no data (or space) is available. |
546 | blocking when no data (or space) is available. |
|
|
547 | .Sp |
|
|
548 | While this backend scales well, it requires one system call per active |
|
|
549 | file descriptor per loop iteration. For small and medium numbers of file |
|
|
550 | descriptors a \*(L"slow\*(R" \f(CW\*(C`EVBACKEND_SELECT\*(C'\fR or \f(CW\*(C`EVBACKEND_POLL\*(C'\fR backend |
|
|
551 | might perform better. |
516 | .ie n .IP """EVBACKEND_ALL""" 4 |
552 | .ie n .IP """EVBACKEND_ALL""" 4 |
517 | .el .IP "\f(CWEVBACKEND_ALL\fR" 4 |
553 | .el .IP "\f(CWEVBACKEND_ALL\fR" 4 |
518 | .IX Item "EVBACKEND_ALL" |
554 | .IX Item "EVBACKEND_ALL" |
519 | Try all backends (even potentially broken ones that wouldn't be tried |
555 | Try all backends (even potentially broken ones that wouldn't be tried |
520 | with \f(CW\*(C`EVFLAG_AUTO\*(C'\fR). Since this is a mask, you can do stuff such as |
556 | with \f(CW\*(C`EVFLAG_AUTO\*(C'\fR). Since this is a mask, you can do stuff such as |
521 | \&\f(CW\*(C`EVBACKEND_ALL & ~EVBACKEND_KQUEUE\*(C'\fR. |
557 | \&\f(CW\*(C`EVBACKEND_ALL & ~EVBACKEND_KQUEUE\*(C'\fR. |
|
|
558 | .Sp |
|
|
559 | It is definitely not recommended to use this flag. |
522 | .RE |
560 | .RE |
523 | .RS 4 |
561 | .RS 4 |
524 | .Sp |
562 | .Sp |
525 | If one or more of these are ored into the flags value, then only these |
563 | If one or more of these are ored into the flags value, then only these |
526 | backends will be tried (in the reverse order as given here). If none are |
564 | backends will be tried (in the reverse order as given here). If none are |
… | |
… | |
729 | .Sp |
767 | .Sp |
730 | .Vb 2 |
768 | .Vb 2 |
731 | \& ev_ref (loop); |
769 | \& ev_ref (loop); |
732 | \& ev_signal_stop (loop, &exitsig); |
770 | \& ev_signal_stop (loop, &exitsig); |
733 | .Ve |
771 | .Ve |
734 | .IP "ev_set_io_collect_interval (ev_tstamp interval)" 4 |
772 | .IP "ev_set_io_collect_interval (loop, ev_tstamp interval)" 4 |
735 | .IX Item "ev_set_io_collect_interval (ev_tstamp interval)" |
773 | .IX Item "ev_set_io_collect_interval (loop, ev_tstamp interval)" |
736 | .PD 0 |
774 | .PD 0 |
737 | .IP "ev_set_timeout_collect_interval (ev_tstamp interval)" 4 |
775 | .IP "ev_set_timeout_collect_interval (loop, ev_tstamp interval)" 4 |
738 | .IX Item "ev_set_timeout_collect_interval (ev_tstamp interval)" |
776 | .IX Item "ev_set_timeout_collect_interval (loop, ev_tstamp interval)" |
739 | .PD |
777 | .PD |
740 | These advanced functions influence the time that libev will spend waiting |
778 | These advanced functions influence the time that libev will spend waiting |
741 | for events. Both are by default \f(CW0\fR, meaning that libev will try to |
779 | for events. Both are by default \f(CW0\fR, meaning that libev will try to |
742 | invoke timer/periodic callbacks and I/O callbacks with minimum latency. |
780 | invoke timer/periodic callbacks and I/O callbacks with minimum latency. |
743 | .Sp |
781 | .Sp |
… | |
… | |
752 | overhead for the actual polling but can deliver many events at once. |
790 | overhead for the actual polling but can deliver many events at once. |
753 | .Sp |
791 | .Sp |
754 | By setting a higher \fIio collect interval\fR you allow libev to spend more |
792 | By setting a higher \fIio collect interval\fR you allow libev to spend more |
755 | time collecting I/O events, so you can handle more events per iteration, |
793 | time collecting I/O events, so you can handle more events per iteration, |
756 | at the cost of increasing latency. Timeouts (both \f(CW\*(C`ev_periodic\*(C'\fR and |
794 | at the cost of increasing latency. Timeouts (both \f(CW\*(C`ev_periodic\*(C'\fR and |
757 | \&\f(CW\*(C`ev_timer\*(C'\fR) will be not affected. |
795 | \&\f(CW\*(C`ev_timer\*(C'\fR) will be not affected. Setting this to a non-null value will |
|
|
796 | introduce an additional \f(CW\*(C`ev_sleep ()\*(C'\fR call into most loop iterations. |
758 | .Sp |
797 | .Sp |
759 | Likewise, by setting a higher \fItimeout collect interval\fR you allow libev |
798 | Likewise, by setting a higher \fItimeout collect interval\fR you allow libev |
760 | to spend more time collecting timeouts, at the expense of increased |
799 | to spend more time collecting timeouts, at the expense of increased |
761 | latency (the watcher callback will be called later). \f(CW\*(C`ev_io\*(C'\fR watchers |
800 | latency (the watcher callback will be called later). \f(CW\*(C`ev_io\*(C'\fR watchers |
762 | will not be affected. |
801 | will not be affected. Setting this to a non-null value will not introduce |
|
|
802 | any overhead in libev. |
763 | .Sp |
803 | .Sp |
764 | Many programs can usually benefit by setting the io collect interval to |
804 | Many (busy) programs can usually benefit by setting the io collect |
765 | a value near \f(CW0.1\fR or so, which is often enough for interactive servers |
805 | interval to a value near \f(CW0.1\fR or so, which is often enough for |
766 | (of course not for games), likewise for timeouts. It usually doesn't make |
806 | interactive servers (of course not for games), likewise for timeouts. It |
767 | much sense to set it to a lower value than \f(CW0.01\fR, as this approsaches |
807 | usually doesn't make much sense to set it to a lower value than \f(CW0.01\fR, |
768 | the timing granularity of most systems. |
808 | as this approsaches the timing granularity of most systems. |
769 | .SH "ANATOMY OF A WATCHER" |
809 | .SH "ANATOMY OF A WATCHER" |
770 | .IX Header "ANATOMY OF A WATCHER" |
810 | .IX Header "ANATOMY OF A WATCHER" |
771 | A watcher is a structure that you create and register to record your |
811 | A watcher is a structure that you create and register to record your |
772 | interest in some event. For instance, if you want to wait for \s-1STDIN\s0 to |
812 | interest in some event. For instance, if you want to wait for \s-1STDIN\s0 to |
773 | become readable, you would create an \f(CW\*(C`ev_io\*(C'\fR watcher for that: |
813 | become readable, you would create an \f(CW\*(C`ev_io\*(C'\fR watcher for that: |
… | |
… | |
1098 | In general you can register as many read and/or write event watchers per |
1138 | In general you can register as many read and/or write event watchers per |
1099 | fd as you want (as long as you don't confuse yourself). Setting all file |
1139 | fd as you want (as long as you don't confuse yourself). Setting all file |
1100 | descriptors to non-blocking mode is also usually a good idea (but not |
1140 | descriptors to non-blocking mode is also usually a good idea (but not |
1101 | required if you know what you are doing). |
1141 | required if you know what you are doing). |
1102 | .PP |
1142 | .PP |
1103 | You have to be careful with dup'ed file descriptors, though. Some backends |
|
|
1104 | (the linux epoll backend is a notable example) cannot handle dup'ed file |
|
|
1105 | descriptors correctly if you register interest in two or more fds pointing |
|
|
1106 | to the same underlying file/socket/etc. description (that is, they share |
|
|
1107 | the same underlying \*(L"file open\*(R"). |
|
|
1108 | .PP |
|
|
1109 | If you must do this, then force the use of a known-to-be-good backend |
1143 | If you must do this, then force the use of a known-to-be-good backend |
1110 | (at the time of this writing, this includes only \f(CW\*(C`EVBACKEND_SELECT\*(C'\fR and |
1144 | (at the time of this writing, this includes only \f(CW\*(C`EVBACKEND_SELECT\*(C'\fR and |
1111 | \&\f(CW\*(C`EVBACKEND_POLL\*(C'\fR). |
1145 | \&\f(CW\*(C`EVBACKEND_POLL\*(C'\fR). |
1112 | .PP |
1146 | .PP |
1113 | Another thing you have to watch out for is that it is quite easy to |
1147 | Another thing you have to watch out for is that it is quite easy to |
… | |
… | |
1149 | .PP |
1183 | .PP |
1150 | \fIThe special problem of dup'ed file descriptors\fR |
1184 | \fIThe special problem of dup'ed file descriptors\fR |
1151 | .IX Subsection "The special problem of dup'ed file descriptors" |
1185 | .IX Subsection "The special problem of dup'ed file descriptors" |
1152 | .PP |
1186 | .PP |
1153 | Some backends (e.g. epoll), cannot register events for file descriptors, |
1187 | Some backends (e.g. epoll), cannot register events for file descriptors, |
1154 | but only events for the underlying file descriptions. That menas when you |
1188 | but only events for the underlying file descriptions. That means when you |
1155 | have \f(CW\*(C`dup ()\*(C'\fR'ed file descriptors and register events for them, only one |
1189 | have \f(CW\*(C`dup ()\*(C'\fR'ed file descriptors or weirder constellations, and register |
1156 | file descriptor might actually receive events. |
1190 | events for them, only one file descriptor might actually receive events. |
1157 | .PP |
1191 | .PP |
1158 | There is no workaorund possible except not registering events |
1192 | There is no workaround possible except not registering events |
1159 | for potentially \f(CW\*(C`dup ()\*(C'\fR'ed file descriptors or to resort to |
1193 | for potentially \f(CW\*(C`dup ()\*(C'\fR'ed file descriptors, or to resort to |
1160 | \&\f(CW\*(C`EVBACKEND_SELECT\*(C'\fR or \f(CW\*(C`EVBACKEND_POLL\*(C'\fR. |
1194 | \&\f(CW\*(C`EVBACKEND_SELECT\*(C'\fR or \f(CW\*(C`EVBACKEND_POLL\*(C'\fR. |
1161 | .PP |
1195 | .PP |
1162 | \fIThe special problem of fork\fR |
1196 | \fIThe special problem of fork\fR |
1163 | .IX Subsection "The special problem of fork" |
1197 | .IX Subsection "The special problem of fork" |
1164 | .PP |
1198 | .PP |
… | |
… | |
1619 | reader). Inotify will be used to give hints only and should not change the |
1653 | reader). Inotify will be used to give hints only and should not change the |
1620 | semantics of \f(CW\*(C`ev_stat\*(C'\fR watchers, which means that libev sometimes needs |
1654 | semantics of \f(CW\*(C`ev_stat\*(C'\fR watchers, which means that libev sometimes needs |
1621 | to fall back to regular polling again even with inotify, but changes are |
1655 | to fall back to regular polling again even with inotify, but changes are |
1622 | usually detected immediately, and if the file exists there will be no |
1656 | usually detected immediately, and if the file exists there will be no |
1623 | polling. |
1657 | polling. |
|
|
1658 | .PP |
|
|
1659 | \fIInotify\fR |
|
|
1660 | .IX Subsection "Inotify" |
|
|
1661 | .PP |
|
|
1662 | When \f(CW\*(C`inotify (7)\*(C'\fR support has been compiled into libev (generally only |
|
|
1663 | available on Linux) and present at runtime, it will be used to speed up |
|
|
1664 | change detection where possible. The inotify descriptor will be created lazily |
|
|
1665 | when the first \f(CW\*(C`ev_stat\*(C'\fR watcher is being started. |
|
|
1666 | .PP |
|
|
1667 | Inotify presense does not change the semantics of \f(CW\*(C`ev_stat\*(C'\fR watchers |
|
|
1668 | except that changes might be detected earlier, and in some cases, to avoid |
|
|
1669 | making regular \f(CW\*(C`stat\*(C'\fR calls. Even in the presense of inotify support |
|
|
1670 | there are many cases where libev has to resort to regular \f(CW\*(C`stat\*(C'\fR polling. |
|
|
1671 | .PP |
|
|
1672 | (There is no support for kqueue, as apparently it cannot be used to |
|
|
1673 | implement this functionality, due to the requirement of having a file |
|
|
1674 | descriptor open on the object at all times). |
|
|
1675 | .PP |
|
|
1676 | \fIThe special problem of stat time resolution\fR |
|
|
1677 | .IX Subsection "The special problem of stat time resolution" |
|
|
1678 | .PP |
|
|
1679 | The \f(CW\*(C`stat ()\*(C'\fR syscall only supports full-second resolution portably, and |
|
|
1680 | even on systems where the resolution is higher, many filesystems still |
|
|
1681 | only support whole seconds. |
|
|
1682 | .PP |
|
|
1683 | That means that, if the time is the only thing that changes, you might |
|
|
1684 | miss updates: on the first update, \f(CW\*(C`ev_stat\*(C'\fR detects a change and calls |
|
|
1685 | your callback, which does something. When there is another update within |
|
|
1686 | the same second, \f(CW\*(C`ev_stat\*(C'\fR will be unable to detect it. |
|
|
1687 | .PP |
|
|
1688 | The solution to this is to delay acting on a change for a second (or till |
|
|
1689 | the next second boundary), using a roughly one-second delay \f(CW\*(C`ev_timer\*(C'\fR |
|
|
1690 | (\f(CW\*(C`ev_timer_set (w, 0., 1.01); ev_timer_again (loop, w)\*(C'\fR). The \f(CW.01\fR |
|
|
1691 | is added to work around small timing inconsistencies of some operating |
|
|
1692 | systems. |
1624 | .PP |
1693 | .PP |
1625 | \fIWatcher-Specific Functions and Data Members\fR |
1694 | \fIWatcher-Specific Functions and Data Members\fR |
1626 | .IX Subsection "Watcher-Specific Functions and Data Members" |
1695 | .IX Subsection "Watcher-Specific Functions and Data Members" |
1627 | .IP "ev_stat_init (ev_stat *, callback, const char *path, ev_tstamp interval)" 4 |
1696 | .IP "ev_stat_init (ev_stat *, callback, const char *path, ev_tstamp interval)" 4 |
1628 | .IX Item "ev_stat_init (ev_stat *, callback, const char *path, ev_tstamp interval)" |
1697 | .IX Item "ev_stat_init (ev_stat *, callback, const char *path, ev_tstamp interval)" |
… | |
… | |
1660 | The specified interval. |
1729 | The specified interval. |
1661 | .IP "const char *path [read\-only]" 4 |
1730 | .IP "const char *path [read\-only]" 4 |
1662 | .IX Item "const char *path [read-only]" |
1731 | .IX Item "const char *path [read-only]" |
1663 | The filesystem path that is being watched. |
1732 | The filesystem path that is being watched. |
1664 | .PP |
1733 | .PP |
|
|
1734 | \fIExamples\fR |
|
|
1735 | .IX Subsection "Examples" |
|
|
1736 | .PP |
1665 | Example: Watch \f(CW\*(C`/etc/passwd\*(C'\fR for attribute changes. |
1737 | Example: Watch \f(CW\*(C`/etc/passwd\*(C'\fR for attribute changes. |
1666 | .PP |
1738 | .PP |
1667 | .Vb 15 |
1739 | .Vb 15 |
1668 | \& static void |
1740 | \& static void |
1669 | \& passwd_cb (struct ev_loop *loop, ev_stat *w, int revents) |
1741 | \& passwd_cb (struct ev_loop *loop, ev_stat *w, int revents) |
… | |
… | |
1686 | \& ... |
1758 | \& ... |
1687 | \& ev_stat passwd; |
1759 | \& ev_stat passwd; |
1688 | .Ve |
1760 | .Ve |
1689 | .PP |
1761 | .PP |
1690 | .Vb 2 |
1762 | .Vb 2 |
1691 | \& ev_stat_init (&passwd, passwd_cb, "/etc/passwd"); |
1763 | \& ev_stat_init (&passwd, passwd_cb, "/etc/passwd", 0.); |
1692 | \& ev_stat_start (loop, &passwd); |
1764 | \& ev_stat_start (loop, &passwd); |
|
|
1765 | .Ve |
|
|
1766 | .PP |
|
|
1767 | Example: Like above, but additionally use a one-second delay so we do not |
|
|
1768 | miss updates (however, frequent updates will delay processing, too, so |
|
|
1769 | one might do the work both on \f(CW\*(C`ev_stat\*(C'\fR callback invocation \fIand\fR on |
|
|
1770 | \&\f(CW\*(C`ev_timer\*(C'\fR callback invocation). |
|
|
1771 | .PP |
|
|
1772 | .Vb 2 |
|
|
1773 | \& static ev_stat passwd; |
|
|
1774 | \& static ev_timer timer; |
|
|
1775 | .Ve |
|
|
1776 | .PP |
|
|
1777 | .Vb 4 |
|
|
1778 | \& static void |
|
|
1779 | \& timer_cb (EV_P_ ev_timer *w, int revents) |
|
|
1780 | \& { |
|
|
1781 | \& ev_timer_stop (EV_A_ w); |
|
|
1782 | .Ve |
|
|
1783 | .PP |
|
|
1784 | .Vb 2 |
|
|
1785 | \& /* now it's one second after the most recent passwd change */ |
|
|
1786 | \& } |
|
|
1787 | .Ve |
|
|
1788 | .PP |
|
|
1789 | .Vb 6 |
|
|
1790 | \& static void |
|
|
1791 | \& stat_cb (EV_P_ ev_stat *w, int revents) |
|
|
1792 | \& { |
|
|
1793 | \& /* reset the one-second timer */ |
|
|
1794 | \& ev_timer_again (EV_A_ &timer); |
|
|
1795 | \& } |
|
|
1796 | .Ve |
|
|
1797 | .PP |
|
|
1798 | .Vb 4 |
|
|
1799 | \& ... |
|
|
1800 | \& ev_stat_init (&passwd, stat_cb, "/etc/passwd", 0.); |
|
|
1801 | \& ev_stat_start (loop, &passwd); |
|
|
1802 | \& ev_timer_init (&timer, timer_cb, 0., 1.01); |
1693 | .Ve |
1803 | .Ve |
1694 | .ie n .Sh """ev_idle"" \- when you've got nothing better to do..." |
1804 | .ie n .Sh """ev_idle"" \- when you've got nothing better to do..." |
1695 | .el .Sh "\f(CWev_idle\fP \- when you've got nothing better to do..." |
1805 | .el .Sh "\f(CWev_idle\fP \- when you've got nothing better to do..." |
1696 | .IX Subsection "ev_idle - when you've got nothing better to do..." |
1806 | .IX Subsection "ev_idle - when you've got nothing better to do..." |
1697 | Idle watchers trigger events when no other events of the same or higher |
1807 | Idle watchers trigger events when no other events of the same or higher |
… | |
… | |
1782 | .PP |
1892 | .PP |
1783 | It is recommended to give \f(CW\*(C`ev_check\*(C'\fR watchers highest (\f(CW\*(C`EV_MAXPRI\*(C'\fR) |
1893 | It is recommended to give \f(CW\*(C`ev_check\*(C'\fR watchers highest (\f(CW\*(C`EV_MAXPRI\*(C'\fR) |
1784 | priority, to ensure that they are being run before any other watchers |
1894 | priority, to ensure that they are being run before any other watchers |
1785 | after the poll. Also, \f(CW\*(C`ev_check\*(C'\fR watchers (and \f(CW\*(C`ev_prepare\*(C'\fR watchers, |
1895 | after the poll. Also, \f(CW\*(C`ev_check\*(C'\fR watchers (and \f(CW\*(C`ev_prepare\*(C'\fR watchers, |
1786 | too) should not activate (\*(L"feed\*(R") events into libev. While libev fully |
1896 | too) should not activate (\*(L"feed\*(R") events into libev. While libev fully |
1787 | supports this, they will be called before other \f(CW\*(C`ev_check\*(C'\fR watchers did |
1897 | supports this, they will be called before other \f(CW\*(C`ev_check\*(C'\fR watchers |
1788 | their job. As \f(CW\*(C`ev_check\*(C'\fR watchers are often used to embed other event |
1898 | did their job. As \f(CW\*(C`ev_check\*(C'\fR watchers are often used to embed other |
1789 | loops those other event loops might be in an unusable state until their |
1899 | (non\-libev) event loops those other event loops might be in an unusable |
1790 | \&\f(CW\*(C`ev_check\*(C'\fR watcher ran (always remind yourself to coexist peacefully with |
1900 | state until their \f(CW\*(C`ev_check\*(C'\fR watcher ran (always remind yourself to |
1791 | others). |
1901 | coexist peacefully with others). |
1792 | .PP |
1902 | .PP |
1793 | \fIWatcher-Specific Functions and Data Members\fR |
1903 | \fIWatcher-Specific Functions and Data Members\fR |
1794 | .IX Subsection "Watcher-Specific Functions and Data Members" |
1904 | .IX Subsection "Watcher-Specific Functions and Data Members" |
1795 | .IP "ev_prepare_init (ev_prepare *, callback)" 4 |
1905 | .IP "ev_prepare_init (ev_prepare *, callback)" 4 |
1796 | .IX Item "ev_prepare_init (ev_prepare *, callback)" |
1906 | .IX Item "ev_prepare_init (ev_prepare *, callback)" |
… | |
… | |
1976 | .el .Sh "\f(CWev_embed\fP \- when one backend isn't enough..." |
2086 | .el .Sh "\f(CWev_embed\fP \- when one backend isn't enough..." |
1977 | .IX Subsection "ev_embed - when one backend isn't enough..." |
2087 | .IX Subsection "ev_embed - when one backend isn't enough..." |
1978 | This is a rather advanced watcher type that lets you embed one event loop |
2088 | This is a rather advanced watcher type that lets you embed one event loop |
1979 | into another (currently only \f(CW\*(C`ev_io\*(C'\fR events are supported in the embedded |
2089 | into another (currently only \f(CW\*(C`ev_io\*(C'\fR events are supported in the embedded |
1980 | loop, other types of watchers might be handled in a delayed or incorrect |
2090 | loop, other types of watchers might be handled in a delayed or incorrect |
1981 | fashion and must not be used). (See portability notes, below). |
2091 | fashion and must not be used). |
1982 | .PP |
2092 | .PP |
1983 | There are primarily two reasons you would want that: work around bugs and |
2093 | There are primarily two reasons you would want that: work around bugs and |
1984 | prioritise I/O. |
2094 | prioritise I/O. |
1985 | .PP |
2095 | .PP |
1986 | As an example for a bug workaround, the kqueue backend might only support |
2096 | As an example for a bug workaround, the kqueue backend might only support |
… | |
… | |
2046 | \& ev_embed_start (loop_hi, &embed); |
2156 | \& ev_embed_start (loop_hi, &embed); |
2047 | \& } |
2157 | \& } |
2048 | \& else |
2158 | \& else |
2049 | \& loop_lo = loop_hi; |
2159 | \& loop_lo = loop_hi; |
2050 | .Ve |
2160 | .Ve |
2051 | .Sh "Portability notes" |
|
|
2052 | .IX Subsection "Portability notes" |
|
|
2053 | Kqueue is nominally embeddable, but this is broken on all BSDs that I |
|
|
2054 | tried, in various ways. Usually the embedded event loop will simply never |
|
|
2055 | receive events, sometimes it will only trigger a few times, sometimes in a |
|
|
2056 | loop. Epoll is also nominally embeddable, but many Linux kernel versions |
|
|
2057 | will always eport the epoll fd as ready, even when no events are pending. |
|
|
2058 | .PP |
|
|
2059 | While libev allows embedding these backends (they are contained in |
|
|
2060 | \&\f(CW\*(C`ev_embeddable_backends ()\*(C'\fR), take extreme care that it will actually |
|
|
2061 | work. |
|
|
2062 | .PP |
|
|
2063 | When in doubt, create a dynamic event loop forced to use sockets (this |
|
|
2064 | usually works) and possibly another thread and a pipe or so to report to |
|
|
2065 | your main event loop. |
|
|
2066 | .PP |
2161 | .PP |
2067 | \fIWatcher-Specific Functions and Data Members\fR |
2162 | \fIWatcher-Specific Functions and Data Members\fR |
2068 | .IX Subsection "Watcher-Specific Functions and Data Members" |
2163 | .IX Subsection "Watcher-Specific Functions and Data Members" |
2069 | .IP "ev_embed_init (ev_embed *, callback, struct ev_loop *embedded_loop)" 4 |
2164 | .IP "ev_embed_init (ev_embed *, callback, struct ev_loop *embedded_loop)" 4 |
2070 | .IX Item "ev_embed_init (ev_embed *, callback, struct ev_loop *embedded_loop)" |
2165 | .IX Item "ev_embed_init (ev_embed *, callback, struct ev_loop *embedded_loop)" |
… | |
… | |
2608 | interface to speed up \f(CW\*(C`ev_stat\*(C'\fR watchers. Its actual availability will |
2703 | interface to speed up \f(CW\*(C`ev_stat\*(C'\fR watchers. Its actual availability will |
2609 | be detected at runtime. |
2704 | be detected at runtime. |
2610 | .IP "\s-1EV_H\s0" 4 |
2705 | .IP "\s-1EV_H\s0" 4 |
2611 | .IX Item "EV_H" |
2706 | .IX Item "EV_H" |
2612 | The name of the \fIev.h\fR header file used to include it. The default if |
2707 | The name of the \fIev.h\fR header file used to include it. The default if |
2613 | undefined is \f(CW\*(C`<ev.h>\*(C'\fR in \fIevent.h\fR and \f(CW"ev.h"\fR in \fIev.c\fR. This |
2708 | undefined is \f(CW"ev.h"\fR in \fIevent.h\fR and \fIev.c\fR. This can be used to |
2614 | can be used to virtually rename the \fIev.h\fR header file in case of conflicts. |
2709 | virtually rename the \fIev.h\fR header file in case of conflicts. |
2615 | .IP "\s-1EV_CONFIG_H\s0" 4 |
2710 | .IP "\s-1EV_CONFIG_H\s0" 4 |
2616 | .IX Item "EV_CONFIG_H" |
2711 | .IX Item "EV_CONFIG_H" |
2617 | If \f(CW\*(C`EV_STANDALONE\*(C'\fR isn't \f(CW1\fR, this variable can be used to override |
2712 | If \f(CW\*(C`EV_STANDALONE\*(C'\fR isn't \f(CW1\fR, this variable can be used to override |
2618 | \&\fIev.c\fR's idea of where to find the \fIconfig.h\fR file, similarly to |
2713 | \&\fIev.c\fR's idea of where to find the \fIconfig.h\fR file, similarly to |
2619 | \&\f(CW\*(C`EV_H\*(C'\fR, above. |
2714 | \&\f(CW\*(C`EV_H\*(C'\fR, above. |
2620 | .IP "\s-1EV_EVENT_H\s0" 4 |
2715 | .IP "\s-1EV_EVENT_H\s0" 4 |
2621 | .IX Item "EV_EVENT_H" |
2716 | .IX Item "EV_EVENT_H" |
2622 | Similarly to \f(CW\*(C`EV_H\*(C'\fR, this macro can be used to override \fIevent.c\fR's idea |
2717 | Similarly to \f(CW\*(C`EV_H\*(C'\fR, this macro can be used to override \fIevent.c\fR's idea |
2623 | of how the \fIevent.h\fR header can be found. |
2718 | of how the \fIevent.h\fR header can be found, the dfeault is \f(CW"event.h"\fR. |
2624 | .IP "\s-1EV_PROTOTYPES\s0" 4 |
2719 | .IP "\s-1EV_PROTOTYPES\s0" 4 |
2625 | .IX Item "EV_PROTOTYPES" |
2720 | .IX Item "EV_PROTOTYPES" |
2626 | If defined to be \f(CW0\fR, then \fIev.h\fR will not define any function |
2721 | If defined to be \f(CW0\fR, then \fIev.h\fR will not define any function |
2627 | prototypes, but still define all the structs and other symbols. This is |
2722 | prototypes, but still define all the structs and other symbols. This is |
2628 | occasionally useful if you want to provide your own wrapper functions |
2723 | occasionally useful if you want to provide your own wrapper functions |
… | |
… | |
2685 | pid. The default size is \f(CW16\fR (or \f(CW1\fR with \f(CW\*(C`EV_MINIMAL\*(C'\fR), usually more |
2780 | pid. The default size is \f(CW16\fR (or \f(CW1\fR with \f(CW\*(C`EV_MINIMAL\*(C'\fR), usually more |
2686 | than enough. If you need to manage thousands of children you might want to |
2781 | than enough. If you need to manage thousands of children you might want to |
2687 | increase this value (\fImust\fR be a power of two). |
2782 | increase this value (\fImust\fR be a power of two). |
2688 | .IP "\s-1EV_INOTIFY_HASHSIZE\s0" 4 |
2783 | .IP "\s-1EV_INOTIFY_HASHSIZE\s0" 4 |
2689 | .IX Item "EV_INOTIFY_HASHSIZE" |
2784 | .IX Item "EV_INOTIFY_HASHSIZE" |
2690 | \&\f(CW\*(C`ev_staz\*(C'\fR watchers use a small hash table to distribute workload by |
2785 | \&\f(CW\*(C`ev_stat\*(C'\fR watchers use a small hash table to distribute workload by |
2691 | inotify watch id. The default size is \f(CW16\fR (or \f(CW1\fR with \f(CW\*(C`EV_MINIMAL\*(C'\fR), |
2786 | inotify watch id. The default size is \f(CW16\fR (or \f(CW1\fR with \f(CW\*(C`EV_MINIMAL\*(C'\fR), |
2692 | usually more than enough. If you need to manage thousands of \f(CW\*(C`ev_stat\*(C'\fR |
2787 | usually more than enough. If you need to manage thousands of \f(CW\*(C`ev_stat\*(C'\fR |
2693 | watchers you might want to increase this value (\fImust\fR be a power of |
2788 | watchers you might want to increase this value (\fImust\fR be a power of |
2694 | two). |
2789 | two). |
2695 | .IP "\s-1EV_COMMON\s0" 4 |
2790 | .IP "\s-1EV_COMMON\s0" 4 |
… | |
… | |
2799 | .RS 4 |
2894 | .RS 4 |
2800 | .IP "Starting and stopping timer/periodic watchers: O(log skipped_other_timers)" 4 |
2895 | .IP "Starting and stopping timer/periodic watchers: O(log skipped_other_timers)" 4 |
2801 | .IX Item "Starting and stopping timer/periodic watchers: O(log skipped_other_timers)" |
2896 | .IX Item "Starting and stopping timer/periodic watchers: O(log skipped_other_timers)" |
2802 | This means that, when you have a watcher that triggers in one hour and |
2897 | This means that, when you have a watcher that triggers in one hour and |
2803 | there are 100 watchers that would trigger before that then inserting will |
2898 | there are 100 watchers that would trigger before that then inserting will |
2804 | have to skip those 100 watchers. |
2899 | have to skip roughly seven (\f(CW\*(C`ld 100\*(C'\fR) of these watchers. |
2805 | .IP "Changing timer/periodic watchers (by autorepeat, again): O(log skipped_other_timers)" 4 |
2900 | .IP "Changing timer/periodic watchers (by autorepeat or calling again): O(log skipped_other_timers)" 4 |
2806 | .IX Item "Changing timer/periodic watchers (by autorepeat, again): O(log skipped_other_timers)" |
2901 | .IX Item "Changing timer/periodic watchers (by autorepeat or calling again): O(log skipped_other_timers)" |
2807 | That means that for changing a timer costs less than removing/adding them |
2902 | That means that changing a timer costs less than removing/adding them |
2808 | as only the relative motion in the event queue has to be paid for. |
2903 | as only the relative motion in the event queue has to be paid for. |
2809 | .IP "Starting io/check/prepare/idle/signal/child watchers: O(1)" 4 |
2904 | .IP "Starting io/check/prepare/idle/signal/child watchers: O(1)" 4 |
2810 | .IX Item "Starting io/check/prepare/idle/signal/child watchers: O(1)" |
2905 | .IX Item "Starting io/check/prepare/idle/signal/child watchers: O(1)" |
2811 | These just add the watcher into an array or at the head of a list. |
2906 | These just add the watcher into an array or at the head of a list. |
|
|
2907 | .IP "Stopping check/prepare/idle watchers: O(1)" 4 |
2812 | =item Stopping check/prepare/idle watchers: O(1) |
2908 | .IX Item "Stopping check/prepare/idle watchers: O(1)" |
|
|
2909 | .PD 0 |
2813 | .IP "Stopping an io/signal/child watcher: O(number_of_watchers_for_this_(fd/signal/pid % \s-1EV_PID_HASHSIZE\s0))" 4 |
2910 | .IP "Stopping an io/signal/child watcher: O(number_of_watchers_for_this_(fd/signal/pid % \s-1EV_PID_HASHSIZE\s0))" 4 |
2814 | .IX Item "Stopping an io/signal/child watcher: O(number_of_watchers_for_this_(fd/signal/pid % EV_PID_HASHSIZE))" |
2911 | .IX Item "Stopping an io/signal/child watcher: O(number_of_watchers_for_this_(fd/signal/pid % EV_PID_HASHSIZE))" |
|
|
2912 | .PD |
2815 | These watchers are stored in lists then need to be walked to find the |
2913 | These watchers are stored in lists then need to be walked to find the |
2816 | correct watcher to remove. The lists are usually short (you don't usually |
2914 | correct watcher to remove. The lists are usually short (you don't usually |
2817 | have many watchers waiting for the same fd or signal). |
2915 | have many watchers waiting for the same fd or signal). |
2818 | .IP "Finding the next timer per loop iteration: O(1)" 4 |
2916 | .IP "Finding the next timer in each loop iteration: O(1)" 4 |
2819 | .IX Item "Finding the next timer per loop iteration: O(1)" |
2917 | .IX Item "Finding the next timer in each loop iteration: O(1)" |
2820 | .PD 0 |
2918 | By virtue of using a binary heap, the next timer is always found at the |
|
|
2919 | beginning of the storage array. |
2821 | .IP "Each change on a file descriptor per loop iteration: O(number_of_watchers_for_this_fd)" 4 |
2920 | .IP "Each change on a file descriptor per loop iteration: O(number_of_watchers_for_this_fd)" 4 |
2822 | .IX Item "Each change on a file descriptor per loop iteration: O(number_of_watchers_for_this_fd)" |
2921 | .IX Item "Each change on a file descriptor per loop iteration: O(number_of_watchers_for_this_fd)" |
2823 | .PD |
|
|
2824 | A change means an I/O watcher gets started or stopped, which requires |
2922 | A change means an I/O watcher gets started or stopped, which requires |
2825 | libev to recalculate its status (and possibly tell the kernel). |
2923 | libev to recalculate its status (and possibly tell the kernel, depending |
2826 | .IP "Activating one watcher: O(1)" 4 |
2924 | on backend and wether \f(CW\*(C`ev_io_set\*(C'\fR was used). |
2827 | .IX Item "Activating one watcher: O(1)" |
2925 | .IP "Activating one watcher (putting it into the pending state): O(1)" 4 |
|
|
2926 | .IX Item "Activating one watcher (putting it into the pending state): O(1)" |
2828 | .PD 0 |
2927 | .PD 0 |
2829 | .IP "Priority handling: O(number_of_priorities)" 4 |
2928 | .IP "Priority handling: O(number_of_priorities)" 4 |
2830 | .IX Item "Priority handling: O(number_of_priorities)" |
2929 | .IX Item "Priority handling: O(number_of_priorities)" |
2831 | .PD |
2930 | .PD |
2832 | Priorities are implemented by allocating some space for each |
2931 | Priorities are implemented by allocating some space for each |
2833 | priority. When doing priority-based operations, libev usually has to |
2932 | priority. When doing priority-based operations, libev usually has to |
2834 | linearly search all the priorities. |
2933 | linearly search all the priorities, but starting/stopping and activating |
|
|
2934 | watchers becomes O(1) w.r.t. prioritiy handling. |
2835 | .RE |
2935 | .RE |
2836 | .RS 4 |
2936 | .RS 4 |
2837 | .SH "AUTHOR" |
2937 | .SH "AUTHOR" |
2838 | .IX Header "AUTHOR" |
2938 | .IX Header "AUTHOR" |
2839 | Marc Lehmann <libev@schmorp.de>. |
2939 | Marc Lehmann <libev@schmorp.de>. |