… | |
… | |
64 | |
64 | |
65 | =head1 DESCRIPTION |
65 | =head1 DESCRIPTION |
66 | |
66 | |
67 | The newest version of this document is also available as an html-formatted |
67 | The newest version of this document is also available as an html-formatted |
68 | web page you might find easier to navigate when reading it for the first |
68 | web page you might find easier to navigate when reading it for the first |
69 | time: L<http://cvs.schmorp.de/libev/ev.html>. |
69 | time: L<http://pod.tst.eu/http://cvs.schmorp.de/libev/ev.pod>. |
70 | |
70 | |
71 | Libev is an event loop: you register interest in certain events (such as a |
71 | Libev is an event loop: you register interest in certain events (such as a |
72 | file descriptor being readable or a timeout occurring), and it will manage |
72 | file descriptor being readable or a timeout occurring), and it will manage |
73 | these event sources and provide your program with events. |
73 | these event sources and provide your program with events. |
74 | |
74 | |
… | |
… | |
336 | To get good performance out of this backend you need a high amount of |
336 | To get good performance out of this backend you need a high amount of |
337 | parallelity (most of the file descriptors should be busy). If you are |
337 | parallelity (most of the file descriptors should be busy). If you are |
338 | writing a server, you should C<accept ()> in a loop to accept as many |
338 | writing a server, you should C<accept ()> in a loop to accept as many |
339 | connections as possible during one iteration. You might also want to have |
339 | connections as possible during one iteration. You might also want to have |
340 | a look at C<ev_set_io_collect_interval ()> to increase the amount of |
340 | a look at C<ev_set_io_collect_interval ()> to increase the amount of |
341 | readyness notifications you get per iteration. |
341 | readiness notifications you get per iteration. |
342 | |
342 | |
343 | =item C<EVBACKEND_POLL> (value 2, poll backend, available everywhere except on windows) |
343 | =item C<EVBACKEND_POLL> (value 2, poll backend, available everywhere except on windows) |
344 | |
344 | |
345 | And this is your standard poll(2) backend. It's more complicated |
345 | And this is your standard poll(2) backend. It's more complicated |
346 | than select, but handles sparse fds better and has no artificial |
346 | than select, but handles sparse fds better and has no artificial |
… | |
… | |
425 | While this backend scales well, it requires one system call per active |
425 | While this backend scales well, it requires one system call per active |
426 | file descriptor per loop iteration. For small and medium numbers of file |
426 | file descriptor per loop iteration. For small and medium numbers of file |
427 | descriptors a "slow" C<EVBACKEND_SELECT> or C<EVBACKEND_POLL> backend |
427 | descriptors a "slow" C<EVBACKEND_SELECT> or C<EVBACKEND_POLL> backend |
428 | might perform better. |
428 | might perform better. |
429 | |
429 | |
430 | On the positive side, ignoring the spurious readyness notifications, this |
430 | On the positive side, ignoring the spurious readiness notifications, this |
431 | backend actually performed to specification in all tests and is fully |
431 | backend actually performed to specification in all tests and is fully |
432 | embeddable, which is a rare feat among the OS-specific backends. |
432 | embeddable, which is a rare feat among the OS-specific backends. |
433 | |
433 | |
434 | =item C<EVBACKEND_ALL> |
434 | =item C<EVBACKEND_ALL> |
435 | |
435 | |
… | |
… | |
1032 | If you must do this, then force the use of a known-to-be-good backend |
1032 | If you must do this, then force the use of a known-to-be-good backend |
1033 | (at the time of this writing, this includes only C<EVBACKEND_SELECT> and |
1033 | (at the time of this writing, this includes only C<EVBACKEND_SELECT> and |
1034 | C<EVBACKEND_POLL>). |
1034 | C<EVBACKEND_POLL>). |
1035 | |
1035 | |
1036 | Another thing you have to watch out for is that it is quite easy to |
1036 | Another thing you have to watch out for is that it is quite easy to |
1037 | receive "spurious" readyness notifications, that is your callback might |
1037 | receive "spurious" readiness notifications, that is your callback might |
1038 | be called with C<EV_READ> but a subsequent C<read>(2) will actually block |
1038 | be called with C<EV_READ> but a subsequent C<read>(2) will actually block |
1039 | because there is no data. Not only are some backends known to create a |
1039 | because there is no data. Not only are some backends known to create a |
1040 | lot of those (for example solaris ports), it is very easy to get into |
1040 | lot of those (for example solaris ports), it is very easy to get into |
1041 | this situation even with a relatively standard program structure. Thus |
1041 | this situation even with a relatively standard program structure. Thus |
1042 | it is best to always use non-blocking I/O: An extra C<read>(2) returning |
1042 | it is best to always use non-blocking I/O: An extra C<read>(2) returning |
… | |
… | |
1657 | calls your callback, which does something. When there is another update |
1657 | calls your callback, which does something. When there is another update |
1658 | within the same second, C<ev_stat> will be unable to detect it as the stat |
1658 | within the same second, C<ev_stat> will be unable to detect it as the stat |
1659 | data does not change. |
1659 | data does not change. |
1660 | |
1660 | |
1661 | The solution to this is to delay acting on a change for slightly more |
1661 | The solution to this is to delay acting on a change for slightly more |
1662 | than second (or till slightly after the next full second boundary), using |
1662 | than a second (or till slightly after the next full second boundary), using |
1663 | a roughly one-second-delay C<ev_timer> (e.g. C<ev_timer_set (w, 0., 1.02); |
1663 | a roughly one-second-delay C<ev_timer> (e.g. C<ev_timer_set (w, 0., 1.02); |
1664 | ev_timer_again (loop, w)>). |
1664 | ev_timer_again (loop, w)>). |
1665 | |
1665 | |
1666 | The C<.02> offset is added to work around small timing inconsistencies |
1666 | The C<.02> offset is added to work around small timing inconsistencies |
1667 | of some operating systems (where the second counter of the current time |
1667 | of some operating systems (where the second counter of the current time |
… | |
… | |
2980 | defined to be C<0>, then they are not. |
2980 | defined to be C<0>, then they are not. |
2981 | |
2981 | |
2982 | =item EV_MINIMAL |
2982 | =item EV_MINIMAL |
2983 | |
2983 | |
2984 | If you need to shave off some kilobytes of code at the expense of some |
2984 | If you need to shave off some kilobytes of code at the expense of some |
2985 | speed, define this symbol to C<1>. Currently only used for gcc to override |
2985 | speed, define this symbol to C<1>. Currently this is used to override some |
2986 | some inlining decisions, saves roughly 30% codesize of amd64. |
2986 | inlining decisions, saves roughly 30% codesize of amd64. It also selects a |
|
|
2987 | much smaller 2-heap for timer management over the default 4-heap. |
2987 | |
2988 | |
2988 | =item EV_PID_HASHSIZE |
2989 | =item EV_PID_HASHSIZE |
2989 | |
2990 | |
2990 | C<ev_child> watchers use a small hash table to distribute workload by |
2991 | C<ev_child> watchers use a small hash table to distribute workload by |
2991 | pid. The default size is C<16> (or C<1> with C<EV_MINIMAL>), usually more |
2992 | pid. The default size is C<16> (or C<1> with C<EV_MINIMAL>), usually more |
… | |
… | |
2997 | C<ev_stat> watchers use a small hash table to distribute workload by |
2998 | C<ev_stat> watchers use a small hash table to distribute workload by |
2998 | inotify watch id. The default size is C<16> (or C<1> with C<EV_MINIMAL>), |
2999 | inotify watch id. The default size is C<16> (or C<1> with C<EV_MINIMAL>), |
2999 | usually more than enough. If you need to manage thousands of C<ev_stat> |
3000 | usually more than enough. If you need to manage thousands of C<ev_stat> |
3000 | watchers you might want to increase this value (I<must> be a power of |
3001 | watchers you might want to increase this value (I<must> be a power of |
3001 | two). |
3002 | two). |
|
|
3003 | |
|
|
3004 | =item EV_USE_4HEAP |
|
|
3005 | |
|
|
3006 | Heaps are not very cache-efficient. To improve the cache-efficiency of the |
|
|
3007 | timer and periodics heap, libev uses a 4-heap when this symbol is defined |
|
|
3008 | to C<1>. The 4-heap uses more complicated (longer) code but has |
|
|
3009 | noticably faster performance with many (thousands) of watchers. |
|
|
3010 | |
|
|
3011 | The default is C<1> unless C<EV_MINIMAL> is set in which case it is C<0> |
|
|
3012 | (disabled). |
|
|
3013 | |
|
|
3014 | =item EV_HEAP_CACHE_AT |
|
|
3015 | |
|
|
3016 | Heaps are not very cache-efficient. To improve the cache-efficiency of the |
|
|
3017 | timer and periodics heap, libev can cache the timestamp (I<at>) within |
|
|
3018 | the heap structure (selected by defining C<EV_HEAP_CACHE_AT> to C<1>), |
|
|
3019 | which uses 8-12 bytes more per watcher and a few hundred bytes more code, |
|
|
3020 | but avoids random read accesses on heap changes. This improves performance |
|
|
3021 | noticably with with many (hundreds) of watchers. |
|
|
3022 | |
|
|
3023 | The default is C<1> unless C<EV_MINIMAL> is set in which case it is C<0> |
|
|
3024 | (disabled). |
3002 | |
3025 | |
3003 | =item EV_COMMON |
3026 | =item EV_COMMON |
3004 | |
3027 | |
3005 | By default, all watchers have a C<void *data> member. By redefining |
3028 | By default, all watchers have a C<void *data> member. By redefining |
3006 | this macro to a something else you can include more and other types of |
3029 | this macro to a something else you can include more and other types of |
… | |
… | |
3176 | correct watcher to remove. The lists are usually short (you don't usually |
3199 | correct watcher to remove. The lists are usually short (you don't usually |
3177 | have many watchers waiting for the same fd or signal). |
3200 | have many watchers waiting for the same fd or signal). |
3178 | |
3201 | |
3179 | =item Finding the next timer in each loop iteration: O(1) |
3202 | =item Finding the next timer in each loop iteration: O(1) |
3180 | |
3203 | |
3181 | By virtue of using a binary heap, the next timer is always found at the |
3204 | By virtue of using a binary or 4-heap, the next timer is always found at a |
3182 | beginning of the storage array. |
3205 | fixed position in the storage array. |
3183 | |
3206 | |
3184 | =item Each change on a file descriptor per loop iteration: O(number_of_watchers_for_this_fd) |
3207 | =item Each change on a file descriptor per loop iteration: O(number_of_watchers_for_this_fd) |
3185 | |
3208 | |
3186 | A change means an I/O watcher gets started or stopped, which requires |
3209 | A change means an I/O watcher gets started or stopped, which requires |
3187 | libev to recalculate its status (and possibly tell the kernel, depending |
3210 | libev to recalculate its status (and possibly tell the kernel, depending |
… | |
… | |
3228 | |
3251 | |
3229 | Due to the many, low, and arbitrary limits on the win32 platform and |
3252 | Due to the many, low, and arbitrary limits on the win32 platform and |
3230 | the abysmal performance of winsockets, using a large number of sockets |
3253 | the abysmal performance of winsockets, using a large number of sockets |
3231 | is not recommended (and not reasonable). If your program needs to use |
3254 | is not recommended (and not reasonable). If your program needs to use |
3232 | more than a hundred or so sockets, then likely it needs to use a totally |
3255 | more than a hundred or so sockets, then likely it needs to use a totally |
3233 | different implementation for windows, as libev offers the POSIX readyness |
3256 | different implementation for windows, as libev offers the POSIX readiness |
3234 | notification model, which cannot be implemented efficiently on windows |
3257 | notification model, which cannot be implemented efficiently on windows |
3235 | (microsoft monopoly games). |
3258 | (microsoft monopoly games). |
3236 | |
3259 | |
3237 | =over 4 |
3260 | =over 4 |
3238 | |
3261 | |