… | |
… | |
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-21" "perl v5.8.8" "User Contributed Perl Documentation" |
132 | .TH EV 1 "2007-12-22" "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 |
… | |
… | |
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 |
|
|
261 | .IX Item "void ev_sleep (ev_tstamp interval)" |
|
|
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 |
|
|
264 | this is a subsecond-resolution \f(CW\*(C`sleep ()\*(C'\fR. |
260 | .IP "int ev_version_major ()" 4 |
265 | .IP "int ev_version_major ()" 4 |
261 | .IX Item "int ev_version_major ()" |
266 | .IX Item "int ev_version_major ()" |
262 | .PD 0 |
267 | .PD 0 |
263 | .IP "int ev_version_minor ()" 4 |
268 | .IP "int ev_version_minor ()" 4 |
264 | .IX Item "int ev_version_minor ()" |
269 | .IX Item "int ev_version_minor ()" |
… | |
… | |
463 | For few fds, this backend is a bit little slower than poll and select, |
468 | For few fds, this backend is a bit little slower than poll and select, |
464 | but it scales phenomenally better. While poll and select usually scale |
469 | but it scales phenomenally better. While poll and select usually scale |
465 | like O(total_fds) where n is the total number of fds (or the highest fd), |
470 | like O(total_fds) where n is the total number of fds (or the highest fd), |
466 | epoll scales either O(1) or O(active_fds). The epoll design has a number |
471 | epoll scales either O(1) or O(active_fds). The epoll design has a number |
467 | of shortcomings, such as silently dropping events in some hard-to-detect |
472 | of shortcomings, such as silently dropping events in some hard-to-detect |
468 | cases and rewuiring a syscall per fd change, no fork support and bad |
473 | cases and rewiring a syscall per fd change, no fork support and bad |
469 | support for dup: |
474 | support for dup: |
470 | .Sp |
475 | .Sp |
471 | While stopping, setting and starting an I/O watcher in the same iteration |
476 | While stopping, setting and starting an I/O watcher in the same iteration |
472 | will result in some caching, there is still a syscall per such incident |
477 | will result in some caching, there is still a syscall per such incident |
473 | (because the fd could point to a different file description now), so its |
478 | (because the fd could point to a different file description now), so its |
… | |
… | |
724 | .Sp |
729 | .Sp |
725 | .Vb 2 |
730 | .Vb 2 |
726 | \& ev_ref (loop); |
731 | \& ev_ref (loop); |
727 | \& ev_signal_stop (loop, &exitsig); |
732 | \& ev_signal_stop (loop, &exitsig); |
728 | .Ve |
733 | .Ve |
|
|
734 | .IP "ev_set_io_collect_interval (ev_tstamp interval)" 4 |
|
|
735 | .IX Item "ev_set_io_collect_interval (ev_tstamp interval)" |
|
|
736 | .PD 0 |
|
|
737 | .IP "ev_set_timeout_collect_interval (ev_tstamp interval)" 4 |
|
|
738 | .IX Item "ev_set_timeout_collect_interval (ev_tstamp interval)" |
|
|
739 | .PD |
|
|
740 | 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 |
|
|
742 | invoke timer/periodic callbacks and I/O callbacks with minimum latency. |
|
|
743 | .Sp |
|
|
744 | Setting these to a higher value (the \f(CW\*(C`interval\*(C'\fR \fImust\fR be >= \f(CW0\fR) |
|
|
745 | allows libev to delay invocation of I/O and timer/periodic callbacks to |
|
|
746 | increase efficiency of loop iterations. |
|
|
747 | .Sp |
|
|
748 | The background is that sometimes your program runs just fast enough to |
|
|
749 | handle one (or very few) event(s) per loop iteration. While this makes |
|
|
750 | the program responsive, it also wastes a lot of \s-1CPU\s0 time to poll for new |
|
|
751 | events, especially with backends like \f(CW\*(C`select ()\*(C'\fR which have a high |
|
|
752 | overhead for the actual polling but can deliver many events at once. |
|
|
753 | .Sp |
|
|
754 | 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, |
|
|
756 | 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. |
|
|
758 | .Sp |
|
|
759 | Likewise, by setting a higher \fItimeout collect interval\fR you allow libev |
|
|
760 | 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 |
|
|
762 | will not be affected. |
|
|
763 | .Sp |
|
|
764 | Many programs can usually benefit by setting the io collect interval to |
|
|
765 | a value near \f(CW0.1\fR or so, which is often enough for interactive servers |
|
|
766 | (of course not for games), likewise for timeouts. It usually doesn't make |
|
|
767 | much sense to set it to a lower value than \f(CW0.01\fR, as this approsaches |
|
|
768 | the timing granularity of most systems. |
729 | .SH "ANATOMY OF A WATCHER" |
769 | .SH "ANATOMY OF A WATCHER" |
730 | .IX Header "ANATOMY OF A WATCHER" |
770 | .IX Header "ANATOMY OF A WATCHER" |
731 | A watcher is a structure that you create and register to record your |
771 | A watcher is a structure that you create and register to record your |
732 | interest in some event. For instance, if you want to wait for \s-1STDIN\s0 to |
772 | interest in some event. For instance, if you want to wait for \s-1STDIN\s0 to |
733 | become readable, you would create an \f(CW\*(C`ev_io\*(C'\fR watcher for that: |
773 | become readable, you would create an \f(CW\*(C`ev_io\*(C'\fR watcher for that: |
… | |
… | |
2501 | realtime clock option at compiletime (and assume its availability at |
2541 | realtime clock option at compiletime (and assume its availability at |
2502 | runtime if successful). Otherwise no use of the realtime clock option will |
2542 | runtime if successful). Otherwise no use of the realtime clock option will |
2503 | be attempted. This effectively replaces \f(CW\*(C`gettimeofday\*(C'\fR by \f(CW\*(C`clock_get |
2543 | be attempted. This effectively replaces \f(CW\*(C`gettimeofday\*(C'\fR by \f(CW\*(C`clock_get |
2504 | (CLOCK_REALTIME, ...)\*(C'\fR and will not normally affect correctness. See the |
2544 | (CLOCK_REALTIME, ...)\*(C'\fR and will not normally affect correctness. See the |
2505 | note about libraries in the description of \f(CW\*(C`EV_USE_MONOTONIC\*(C'\fR, though. |
2545 | note about libraries in the description of \f(CW\*(C`EV_USE_MONOTONIC\*(C'\fR, though. |
|
|
2546 | .IP "\s-1EV_USE_NANOSLEEP\s0" 4 |
|
|
2547 | .IX Item "EV_USE_NANOSLEEP" |
|
|
2548 | If defined to be \f(CW1\fR, libev will assume that \f(CW\*(C`nanosleep ()\*(C'\fR is available |
|
|
2549 | and will use it for delays. Otherwise it will use \f(CW\*(C`select ()\*(C'\fR. |
2506 | .IP "\s-1EV_USE_SELECT\s0" 4 |
2550 | .IP "\s-1EV_USE_SELECT\s0" 4 |
2507 | .IX Item "EV_USE_SELECT" |
2551 | .IX Item "EV_USE_SELECT" |
2508 | If undefined or defined to be \f(CW1\fR, libev will compile in support for the |
2552 | If undefined or defined to be \f(CW1\fR, libev will compile in support for the |
2509 | \&\f(CW\*(C`select\*(C'\fR(2) backend. No attempt at autodetection will be done: if no |
2553 | \&\f(CW\*(C`select\*(C'\fR(2) backend. No attempt at autodetection will be done: if no |
2510 | other method takes over, select will be it. Otherwise the select backend |
2554 | other method takes over, select will be it. Otherwise the select backend |