… | |
… | |
214 | C<ev_embeddable_backends () & ev_supported_backends ()>, likewise for |
214 | C<ev_embeddable_backends () & ev_supported_backends ()>, likewise for |
215 | recommended ones. |
215 | recommended ones. |
216 | |
216 | |
217 | See the description of C<ev_embed> watchers for more info. |
217 | See the description of C<ev_embed> watchers for more info. |
218 | |
218 | |
219 | =item ev_set_allocator (void *(*cb)(void *ptr, long size)) |
219 | =item ev_set_allocator (void *(*cb)(void *ptr, long size)) [NOT REENTRANT] |
220 | |
220 | |
221 | Sets the allocation function to use (the prototype is similar - the |
221 | Sets the allocation function to use (the prototype is similar - the |
222 | semantics are identical to the C<realloc> C89/SuS/POSIX function). It is |
222 | semantics are identical to the C<realloc> C89/SuS/POSIX function). It is |
223 | used to allocate and free memory (no surprises here). If it returns zero |
223 | used to allocate and free memory (no surprises here). If it returns zero |
224 | when memory needs to be allocated (C<size != 0>), the library might abort |
224 | when memory needs to be allocated (C<size != 0>), the library might abort |
… | |
… | |
250 | } |
250 | } |
251 | |
251 | |
252 | ... |
252 | ... |
253 | ev_set_allocator (persistent_realloc); |
253 | ev_set_allocator (persistent_realloc); |
254 | |
254 | |
255 | =item ev_set_syserr_cb (void (*cb)(const char *msg)); |
255 | =item ev_set_syserr_cb (void (*cb)(const char *msg)); [NOT REENTRANT] |
256 | |
256 | |
257 | Set the callback function to call on a retryable system call error (such |
257 | Set the callback function to call on a retryable system call error (such |
258 | as failed select, poll, epoll_wait). The message is a printable string |
258 | as failed select, poll, epoll_wait). The message is a printable string |
259 | indicating the system call or subsystem causing the problem. If this |
259 | indicating the system call or subsystem causing the problem. If this |
260 | callback is set, then libev will expect it to remedy the situation, no |
260 | callback is set, then libev will expect it to remedy the situation, no |
… | |
… | |
685 | C<EVUNLOOP_ONE>, which will make the innermost C<ev_loop> call return, or |
685 | C<EVUNLOOP_ONE>, which will make the innermost C<ev_loop> call return, or |
686 | C<EVUNLOOP_ALL>, which will make all nested C<ev_loop> calls return. |
686 | C<EVUNLOOP_ALL>, which will make all nested C<ev_loop> calls return. |
687 | |
687 | |
688 | This "unloop state" will be cleared when entering C<ev_loop> again. |
688 | This "unloop state" will be cleared when entering C<ev_loop> again. |
689 | |
689 | |
|
|
690 | It is safe to call C<ev_unloop> from otuside any C<ev_loop> calls. |
|
|
691 | |
690 | =item ev_ref (loop) |
692 | =item ev_ref (loop) |
691 | |
693 | |
692 | =item ev_unref (loop) |
694 | =item ev_unref (loop) |
693 | |
695 | |
694 | Ref/unref can be used to add or remove a reference count on the event |
696 | Ref/unref can be used to add or remove a reference count on the event |
… | |
… | |
967 | |
969 | |
968 | ev_io_start (EV_DEFAULT_UC, &w); |
970 | ev_io_start (EV_DEFAULT_UC, &w); |
969 | |
971 | |
970 | =item C<ev_TYPE_stop> (loop *, ev_TYPE *watcher) |
972 | =item C<ev_TYPE_stop> (loop *, ev_TYPE *watcher) |
971 | |
973 | |
972 | Stops the given watcher again (if active) and clears the pending |
974 | Stops the given watcher if active, and clears the pending status (whether |
|
|
975 | the watcher was active or not). |
|
|
976 | |
973 | status. It is possible that stopped watchers are pending (for example, |
977 | It is possible that stopped watchers are pending - for example, |
974 | non-repeating timers are being stopped when they become pending), but |
978 | non-repeating timers are being stopped when they become pending - but |
975 | C<ev_TYPE_stop> ensures that the watcher is neither active nor pending. If |
979 | calling C<ev_TYPE_stop> ensures that the watcher is neither active nor |
976 | you want to free or reuse the memory used by the watcher it is therefore a |
980 | pending. If you want to free or reuse the memory used by the watcher it is |
977 | good idea to always call its C<ev_TYPE_stop> function. |
981 | therefore a good idea to always call its C<ev_TYPE_stop> function. |
978 | |
982 | |
979 | =item bool ev_is_active (ev_TYPE *watcher) |
983 | =item bool ev_is_active (ev_TYPE *watcher) |
980 | |
984 | |
981 | Returns a true value iff the watcher is active (i.e. it has been started |
985 | Returns a true value iff the watcher is active (i.e. it has been started |
982 | and not yet been stopped). As long as a watcher is active you must not modify |
986 | and not yet been stopped). As long as a watcher is active you must not modify |
… | |
… | |
1625 | |
1629 | |
1626 | =back |
1630 | =back |
1627 | |
1631 | |
1628 | =head3 Examples |
1632 | =head3 Examples |
1629 | |
1633 | |
1630 | Example: Try to exit cleanly on SIGINT and SIGTERM. |
1634 | Example: Try to exit cleanly on SIGINT. |
1631 | |
1635 | |
1632 | static void |
1636 | static void |
1633 | sigint_cb (struct ev_loop *loop, struct ev_signal *w, int revents) |
1637 | sigint_cb (struct ev_loop *loop, struct ev_signal *w, int revents) |
1634 | { |
1638 | { |
1635 | ev_unloop (loop, EVUNLOOP_ALL); |
1639 | ev_unloop (loop, EVUNLOOP_ALL); |
1636 | } |
1640 | } |
1637 | |
1641 | |
1638 | struct ev_signal signal_watcher; |
1642 | struct ev_signal signal_watcher; |
1639 | ev_signal_init (&signal_watcher, sigint_cb, SIGINT); |
1643 | ev_signal_init (&signal_watcher, sigint_cb, SIGINT); |
1640 | ev_signal_start (loop, &sigint_cb); |
1644 | ev_signal_start (loop, &signal_watcher); |
1641 | |
1645 | |
1642 | |
1646 | |
1643 | =head2 C<ev_child> - watch out for process status changes |
1647 | =head2 C<ev_child> - watch out for process status changes |
1644 | |
1648 | |
1645 | Child watchers trigger when your process receives a SIGCHLD in response to |
1649 | Child watchers trigger when your process receives a SIGCHLD in response to |
… | |
… | |
2233 | when you fork, you not only have to call C<ev_loop_fork> on both loops, |
2237 | when you fork, you not only have to call C<ev_loop_fork> on both loops, |
2234 | but you will also have to stop and restart any C<ev_embed> watchers |
2238 | but you will also have to stop and restart any C<ev_embed> watchers |
2235 | yourself - but you can use a fork watcher to handle this automatically, |
2239 | yourself - but you can use a fork watcher to handle this automatically, |
2236 | and future versions of libev might do just that. |
2240 | and future versions of libev might do just that. |
2237 | |
2241 | |
2238 | Unfortunately, not all backends are embeddable, only the ones returned by |
2242 | Unfortunately, not all backends are embeddable: only the ones returned by |
2239 | C<ev_embeddable_backends> are, which, unfortunately, does not include any |
2243 | C<ev_embeddable_backends> are, which, unfortunately, does not include any |
2240 | portable one. |
2244 | portable one. |
2241 | |
2245 | |
2242 | So when you want to use this feature you will always have to be prepared |
2246 | So when you want to use this feature you will always have to be prepared |
2243 | that you cannot get an embeddable loop. The recommended way to get around |
2247 | that you cannot get an embeddable loop. The recommended way to get around |
2244 | this is to have a separate variables for your embeddable loop, try to |
2248 | this is to have a separate variables for your embeddable loop, try to |
2245 | create it, and if that fails, use the normal loop for everything. |
2249 | create it, and if that fails, use the normal loop for everything. |
|
|
2250 | |
|
|
2251 | =head3 C<ev_embed> and fork |
|
|
2252 | |
|
|
2253 | While the C<ev_embed> watcher is running, forks in the embedding loop will |
|
|
2254 | automatically be applied to the embedded loop as well, so no special |
|
|
2255 | fork handling is required in that case. When the watcher is not running, |
|
|
2256 | however, it is still the task of the libev user to call C<ev_loop_fork ()> |
|
|
2257 | as applicable. |
2246 | |
2258 | |
2247 | =head3 Watcher-Specific Functions and Data Members |
2259 | =head3 Watcher-Specific Functions and Data Members |
2248 | |
2260 | |
2249 | =over 4 |
2261 | =over 4 |
2250 | |
2262 | |
… | |
… | |
2368 | is that the author does not know of a simple (or any) algorithm for a |
2380 | is that the author does not know of a simple (or any) algorithm for a |
2369 | multiple-writer-single-reader queue that works in all cases and doesn't |
2381 | multiple-writer-single-reader queue that works in all cases and doesn't |
2370 | need elaborate support such as pthreads. |
2382 | need elaborate support such as pthreads. |
2371 | |
2383 | |
2372 | That means that if you want to queue data, you have to provide your own |
2384 | That means that if you want to queue data, you have to provide your own |
2373 | queue. But at least I can tell you would implement locking around your |
2385 | queue. But at least I can tell you how to implement locking around your |
2374 | queue: |
2386 | queue: |
2375 | |
2387 | |
2376 | =over 4 |
2388 | =over 4 |
2377 | |
2389 | |
2378 | =item queueing from a signal handler context |
2390 | =item queueing from a signal handler context |
2379 | |
2391 | |
2380 | To implement race-free queueing, you simply add to the queue in the signal |
2392 | To implement race-free queueing, you simply add to the queue in the signal |
2381 | handler but you block the signal handler in the watcher callback. Here is an example that does that for |
2393 | handler but you block the signal handler in the watcher callback. Here is |
2382 | some fictitious SIGUSR1 handler: |
2394 | an example that does that for some fictitious SIGUSR1 handler: |
2383 | |
2395 | |
2384 | static ev_async mysig; |
2396 | static ev_async mysig; |
2385 | |
2397 | |
2386 | static void |
2398 | static void |
2387 | sigusr1_handler (void) |
2399 | sigusr1_handler (void) |
… | |
… | |
2454 | |
2466 | |
2455 | =item ev_async_init (ev_async *, callback) |
2467 | =item ev_async_init (ev_async *, callback) |
2456 | |
2468 | |
2457 | Initialises and configures the async watcher - it has no parameters of any |
2469 | Initialises and configures the async watcher - it has no parameters of any |
2458 | kind. There is a C<ev_asynd_set> macro, but using it is utterly pointless, |
2470 | kind. There is a C<ev_asynd_set> macro, but using it is utterly pointless, |
2459 | believe me. |
2471 | trust me. |
2460 | |
2472 | |
2461 | =item ev_async_send (loop, ev_async *) |
2473 | =item ev_async_send (loop, ev_async *) |
2462 | |
2474 | |
2463 | Sends/signals/activates the given C<ev_async> watcher, that is, feeds |
2475 | Sends/signals/activates the given C<ev_async> watcher, that is, feeds |
2464 | an C<EV_ASYNC> event on the watcher into the event loop. Unlike |
2476 | an C<EV_ASYNC> event on the watcher into the event loop. Unlike |
2465 | C<ev_feed_event>, this call is safe to do in other threads, signal or |
2477 | C<ev_feed_event>, this call is safe to do from other threads, signal or |
2466 | similar contexts (see the discussion of C<EV_ATOMIC_T> in the embedding |
2478 | similar contexts (see the discussion of C<EV_ATOMIC_T> in the embedding |
2467 | section below on what exactly this means). |
2479 | section below on what exactly this means). |
2468 | |
2480 | |
2469 | This call incurs the overhead of a system call only once per loop iteration, |
2481 | This call incurs the overhead of a system call only once per loop iteration, |
2470 | so while the overhead might be noticeable, it doesn't apply to repeated |
2482 | so while the overhead might be noticeable, it doesn't apply to repeated |
… | |
… | |
2494 | =over 4 |
2506 | =over 4 |
2495 | |
2507 | |
2496 | =item ev_once (loop, int fd, int events, ev_tstamp timeout, callback) |
2508 | =item ev_once (loop, int fd, int events, ev_tstamp timeout, callback) |
2497 | |
2509 | |
2498 | This function combines a simple timer and an I/O watcher, calls your |
2510 | This function combines a simple timer and an I/O watcher, calls your |
2499 | callback on whichever event happens first and automatically stop both |
2511 | callback on whichever event happens first and automatically stops both |
2500 | watchers. This is useful if you want to wait for a single event on an fd |
2512 | watchers. This is useful if you want to wait for a single event on an fd |
2501 | or timeout without having to allocate/configure/start/stop/free one or |
2513 | or timeout without having to allocate/configure/start/stop/free one or |
2502 | more watchers yourself. |
2514 | more watchers yourself. |
2503 | |
2515 | |
2504 | If C<fd> is less than 0, then no I/O watcher will be started and events |
2516 | If C<fd> is less than 0, then no I/O watcher will be started and the |
2505 | is being ignored. Otherwise, an C<ev_io> watcher for the given C<fd> and |
2517 | C<events> argument is being ignored. Otherwise, an C<ev_io> watcher for |
2506 | C<events> set will be created and started. |
2518 | the given C<fd> and C<events> set will be created and started. |
2507 | |
2519 | |
2508 | If C<timeout> is less than 0, then no timeout watcher will be |
2520 | If C<timeout> is less than 0, then no timeout watcher will be |
2509 | started. Otherwise an C<ev_timer> watcher with after = C<timeout> (and |
2521 | started. Otherwise an C<ev_timer> watcher with after = C<timeout> (and |
2510 | repeat = 0) will be started. While C<0> is a valid timeout, it is of |
2522 | repeat = 0) will be started. C<0> is a valid timeout. |
2511 | dubious value. |
|
|
2512 | |
2523 | |
2513 | The callback has the type C<void (*cb)(int revents, void *arg)> and gets |
2524 | The callback has the type C<void (*cb)(int revents, void *arg)> and gets |
2514 | passed an C<revents> set like normal event callbacks (a combination of |
2525 | passed an C<revents> set like normal event callbacks (a combination of |
2515 | C<EV_ERROR>, C<EV_READ>, C<EV_WRITE> or C<EV_TIMEOUT>) and the C<arg> |
2526 | C<EV_ERROR>, C<EV_READ>, C<EV_WRITE> or C<EV_TIMEOUT>) and the C<arg> |
2516 | value passed to C<ev_once>: |
2527 | value passed to C<ev_once>. Note that it is possible to receive I<both> |
|
|
2528 | a timeout and an io event at the same time - you probably should give io |
|
|
2529 | events precedence. |
|
|
2530 | |
|
|
2531 | Example: wait up to ten seconds for data to appear on STDIN_FILENO. |
2517 | |
2532 | |
2518 | static void stdin_ready (int revents, void *arg) |
2533 | static void stdin_ready (int revents, void *arg) |
2519 | { |
2534 | { |
|
|
2535 | if (revents & EV_READ) |
|
|
2536 | /* stdin might have data for us, joy! */; |
2520 | if (revents & EV_TIMEOUT) |
2537 | else if (revents & EV_TIMEOUT) |
2521 | /* doh, nothing entered */; |
2538 | /* doh, nothing entered */; |
2522 | else if (revents & EV_READ) |
|
|
2523 | /* stdin might have data for us, joy! */; |
|
|
2524 | } |
2539 | } |
2525 | |
2540 | |
2526 | ev_once (STDIN_FILENO, EV_READ, 10., stdin_ready, 0); |
2541 | ev_once (STDIN_FILENO, EV_READ, 10., stdin_ready, 0); |
2527 | |
2542 | |
2528 | =item ev_feed_event (ev_loop *, watcher *, int revents) |
2543 | =item ev_feed_event (ev_loop *, watcher *, int revents) |
… | |
… | |
2676 | |
2691 | |
2677 | The prototype of the C<function> must be C<void (*)(ev::TYPE &w, int)>. |
2692 | The prototype of the C<function> must be C<void (*)(ev::TYPE &w, int)>. |
2678 | |
2693 | |
2679 | See the method-C<set> above for more details. |
2694 | See the method-C<set> above for more details. |
2680 | |
2695 | |
2681 | Example: |
2696 | Example: Use a plain function as callback. |
2682 | |
2697 | |
2683 | static void io_cb (ev::io &w, int revents) { } |
2698 | static void io_cb (ev::io &w, int revents) { } |
2684 | iow.set <io_cb> (); |
2699 | iow.set <io_cb> (); |
2685 | |
2700 | |
2686 | =item w->set (struct ev_loop *) |
2701 | =item w->set (struct ev_loop *) |
… | |
… | |
2724 | Example: Define a class with an IO and idle watcher, start one of them in |
2739 | Example: Define a class with an IO and idle watcher, start one of them in |
2725 | the constructor. |
2740 | the constructor. |
2726 | |
2741 | |
2727 | class myclass |
2742 | class myclass |
2728 | { |
2743 | { |
2729 | ev::io io; void io_cb (ev::io &w, int revents); |
2744 | ev::io io ; void io_cb (ev::io &w, int revents); |
2730 | ev:idle idle void idle_cb (ev::idle &w, int revents); |
2745 | ev::idle idle; void idle_cb (ev::idle &w, int revents); |
2731 | |
2746 | |
2732 | myclass (int fd) |
2747 | myclass (int fd) |
2733 | { |
2748 | { |
2734 | io .set <myclass, &myclass::io_cb > (this); |
2749 | io .set <myclass, &myclass::io_cb > (this); |
2735 | idle.set <myclass, &myclass::idle_cb> (this); |
2750 | idle.set <myclass, &myclass::idle_cb> (this); |
… | |
… | |
2751 | =item Perl |
2766 | =item Perl |
2752 | |
2767 | |
2753 | The EV module implements the full libev API and is actually used to test |
2768 | The EV module implements the full libev API and is actually used to test |
2754 | libev. EV is developed together with libev. Apart from the EV core module, |
2769 | libev. EV is developed together with libev. Apart from the EV core module, |
2755 | there are additional modules that implement libev-compatible interfaces |
2770 | there are additional modules that implement libev-compatible interfaces |
2756 | to C<libadns> (C<EV::ADNS>), C<Net::SNMP> (C<Net::SNMP::EV>) and the |
2771 | to C<libadns> (C<EV::ADNS>, but C<AnyEvent::DNS> is preferred nowadays), |
2757 | C<libglib> event core (C<Glib::EV> and C<EV::Glib>). |
2772 | C<Net::SNMP> (C<Net::SNMP::EV>) and the C<libglib> event core (C<Glib::EV> |
|
|
2773 | and C<EV::Glib>). |
2758 | |
2774 | |
2759 | It can be found and installed via CPAN, its homepage is at |
2775 | It can be found and installed via CPAN, its homepage is at |
2760 | L<http://software.schmorp.de/pkg/EV>. |
2776 | L<http://software.schmorp.de/pkg/EV>. |
2761 | |
2777 | |
2762 | =item Python |
2778 | =item Python |
… | |
… | |
2941 | |
2957 | |
2942 | =head2 PREPROCESSOR SYMBOLS/MACROS |
2958 | =head2 PREPROCESSOR SYMBOLS/MACROS |
2943 | |
2959 | |
2944 | Libev can be configured via a variety of preprocessor symbols you have to |
2960 | Libev can be configured via a variety of preprocessor symbols you have to |
2945 | define before including any of its files. The default in the absence of |
2961 | define before including any of its files. The default in the absence of |
2946 | autoconf is noted for every option. |
2962 | autoconf is documented for every option. |
2947 | |
2963 | |
2948 | =over 4 |
2964 | =over 4 |
2949 | |
2965 | |
2950 | =item EV_STANDALONE |
2966 | =item EV_STANDALONE |
2951 | |
2967 | |
… | |
… | |
3121 | When doing priority-based operations, libev usually has to linearly search |
3137 | When doing priority-based operations, libev usually has to linearly search |
3122 | all the priorities, so having many of them (hundreds) uses a lot of space |
3138 | all the priorities, so having many of them (hundreds) uses a lot of space |
3123 | and time, so using the defaults of five priorities (-2 .. +2) is usually |
3139 | and time, so using the defaults of five priorities (-2 .. +2) is usually |
3124 | fine. |
3140 | fine. |
3125 | |
3141 | |
3126 | If your embedding application does not need any priorities, defining these both to |
3142 | If your embedding application does not need any priorities, defining these |
3127 | C<0> will save some memory and CPU. |
3143 | both to C<0> will save some memory and CPU. |
3128 | |
3144 | |
3129 | =item EV_PERIODIC_ENABLE |
3145 | =item EV_PERIODIC_ENABLE |
3130 | |
3146 | |
3131 | If undefined or defined to be C<1>, then periodic timers are supported. If |
3147 | If undefined or defined to be C<1>, then periodic timers are supported. If |
3132 | defined to be C<0>, then they are not. Disabling them saves a few kB of |
3148 | defined to be C<0>, then they are not. Disabling them saves a few kB of |
… | |
… | |
3139 | code. |
3155 | code. |
3140 | |
3156 | |
3141 | =item EV_EMBED_ENABLE |
3157 | =item EV_EMBED_ENABLE |
3142 | |
3158 | |
3143 | If undefined or defined to be C<1>, then embed watchers are supported. If |
3159 | If undefined or defined to be C<1>, then embed watchers are supported. If |
3144 | defined to be C<0>, then they are not. |
3160 | defined to be C<0>, then they are not. Embed watchers rely on most other |
|
|
3161 | watcher types, which therefore must not be disabled. |
3145 | |
3162 | |
3146 | =item EV_STAT_ENABLE |
3163 | =item EV_STAT_ENABLE |
3147 | |
3164 | |
3148 | If undefined or defined to be C<1>, then stat watchers are supported. If |
3165 | If undefined or defined to be C<1>, then stat watchers are supported. If |
3149 | defined to be C<0>, then they are not. |
3166 | defined to be C<0>, then they are not. |
… | |
… | |
3181 | two). |
3198 | two). |
3182 | |
3199 | |
3183 | =item EV_USE_4HEAP |
3200 | =item EV_USE_4HEAP |
3184 | |
3201 | |
3185 | Heaps are not very cache-efficient. To improve the cache-efficiency of the |
3202 | Heaps are not very cache-efficient. To improve the cache-efficiency of the |
3186 | timer and periodics heap, libev uses a 4-heap when this symbol is defined |
3203 | timer and periodics heaps, libev uses a 4-heap when this symbol is defined |
3187 | to C<1>. The 4-heap uses more complicated (longer) code but has |
3204 | to C<1>. The 4-heap uses more complicated (longer) code but has noticeably |
3188 | noticeably faster performance with many (thousands) of watchers. |
3205 | faster performance with many (thousands) of watchers. |
3189 | |
3206 | |
3190 | The default is C<1> unless C<EV_MINIMAL> is set in which case it is C<0> |
3207 | The default is C<1> unless C<EV_MINIMAL> is set in which case it is C<0> |
3191 | (disabled). |
3208 | (disabled). |
3192 | |
3209 | |
3193 | =item EV_HEAP_CACHE_AT |
3210 | =item EV_HEAP_CACHE_AT |
3194 | |
3211 | |
3195 | Heaps are not very cache-efficient. To improve the cache-efficiency of the |
3212 | Heaps are not very cache-efficient. To improve the cache-efficiency of the |
3196 | timer and periodics heap, libev can cache the timestamp (I<at>) within |
3213 | timer and periodics heaps, libev can cache the timestamp (I<at>) within |
3197 | the heap structure (selected by defining C<EV_HEAP_CACHE_AT> to C<1>), |
3214 | the heap structure (selected by defining C<EV_HEAP_CACHE_AT> to C<1>), |
3198 | which uses 8-12 bytes more per watcher and a few hundred bytes more code, |
3215 | which uses 8-12 bytes more per watcher and a few hundred bytes more code, |
3199 | but avoids random read accesses on heap changes. This improves performance |
3216 | but avoids random read accesses on heap changes. This improves performance |
3200 | noticeably with with many (hundreds) of watchers. |
3217 | noticeably with many (hundreds) of watchers. |
3201 | |
3218 | |
3202 | The default is C<1> unless C<EV_MINIMAL> is set in which case it is C<0> |
3219 | The default is C<1> unless C<EV_MINIMAL> is set in which case it is C<0> |
3203 | (disabled). |
3220 | (disabled). |
3204 | |
3221 | |
3205 | =item EV_VERIFY |
3222 | =item EV_VERIFY |
… | |
… | |
3211 | called once per loop, which can slow down libev. If set to C<3>, then the |
3228 | called once per loop, which can slow down libev. If set to C<3>, then the |
3212 | verification code will be called very frequently, which will slow down |
3229 | verification code will be called very frequently, which will slow down |
3213 | libev considerably. |
3230 | libev considerably. |
3214 | |
3231 | |
3215 | The default is C<1>, unless C<EV_MINIMAL> is set, in which case it will be |
3232 | The default is C<1>, unless C<EV_MINIMAL> is set, in which case it will be |
3216 | C<0.> |
3233 | C<0>. |
3217 | |
3234 | |
3218 | =item EV_COMMON |
3235 | =item EV_COMMON |
3219 | |
3236 | |
3220 | By default, all watchers have a C<void *data> member. By redefining |
3237 | By default, all watchers have a C<void *data> member. By redefining |
3221 | this macro to a something else you can include more and other types of |
3238 | this macro to a something else you can include more and other types of |
… | |
… | |
3238 | and the way callbacks are invoked and set. Must expand to a struct member |
3255 | and the way callbacks are invoked and set. Must expand to a struct member |
3239 | definition and a statement, respectively. See the F<ev.h> header file for |
3256 | definition and a statement, respectively. See the F<ev.h> header file for |
3240 | their default definitions. One possible use for overriding these is to |
3257 | their default definitions. One possible use for overriding these is to |
3241 | avoid the C<struct ev_loop *> as first argument in all cases, or to use |
3258 | avoid the C<struct ev_loop *> as first argument in all cases, or to use |
3242 | method calls instead of plain function calls in C++. |
3259 | method calls instead of plain function calls in C++. |
|
|
3260 | |
|
|
3261 | =back |
3243 | |
3262 | |
3244 | =head2 EXPORTED API SYMBOLS |
3263 | =head2 EXPORTED API SYMBOLS |
3245 | |
3264 | |
3246 | If you need to re-export the API (e.g. via a DLL) and you need a list of |
3265 | If you need to re-export the API (e.g. via a DLL) and you need a list of |
3247 | exported symbols, you can use the provided F<Symbol.*> files which list |
3266 | exported symbols, you can use the provided F<Symbol.*> files which list |
… | |
… | |
3294 | And a F<ev_cpp.C> implementation file that contains libev proper and is compiled: |
3313 | And a F<ev_cpp.C> implementation file that contains libev proper and is compiled: |
3295 | |
3314 | |
3296 | #include "ev_cpp.h" |
3315 | #include "ev_cpp.h" |
3297 | #include "ev.c" |
3316 | #include "ev.c" |
3298 | |
3317 | |
|
|
3318 | =head1 INTERACTION WITH OTHER PROGRAMS OR LIBRARIES |
3299 | |
3319 | |
3300 | =head1 THREADS AND COROUTINES |
3320 | =head2 THREADS AND COROUTINES |
3301 | |
3321 | |
3302 | =head2 THREADS |
3322 | =head3 THREADS |
3303 | |
3323 | |
3304 | Libev itself is thread-safe (unless the opposite is specifically |
3324 | All libev functions are reentrant and thread-safe unless explicitly |
3305 | documented for a function), but it uses no locking itself. This means that |
3325 | documented otherwise, but libev implements no locking itself. This means |
3306 | you can use as many loops as you want in parallel, as long as only one |
3326 | that you can use as many loops as you want in parallel, as long as there |
3307 | thread ever calls into one libev function with the same loop parameter: |
3327 | are no concurrent calls into any libev function with the same loop |
|
|
3328 | parameter (C<ev_default_*> calls have an implicit default loop parameter, |
3308 | libev guarentees that different event loops share no data structures that |
3329 | of course): libev guarantees that different event loops share no data |
3309 | need locking. |
3330 | structures that need any locking. |
3310 | |
3331 | |
3311 | Or to put it differently: calls with different loop parameters can be done |
3332 | Or to put it differently: calls with different loop parameters can be done |
3312 | concurrently from multiple threads, calls with the same loop parameter |
3333 | concurrently from multiple threads, calls with the same loop parameter |
3313 | must be done serially (but can be done from different threads, as long as |
3334 | must be done serially (but can be done from different threads, as long as |
3314 | only one thread ever is inside a call at any point in time, e.g. by using |
3335 | only one thread ever is inside a call at any point in time, e.g. by using |
3315 | a mutex per loop). |
3336 | a mutex per loop). |
3316 | |
3337 | |
3317 | Specifically to support threads (and signal handlers), libev implements |
3338 | Specifically to support threads (and signal handlers), libev implements |
3318 | so-called C<ev_async> watchers, which allow some limited form of |
3339 | so-called C<ev_async> watchers, which allow some limited form of |
3319 | concurrency on the same event loop. |
3340 | concurrency on the same event loop, namely waking it up "from the |
|
|
3341 | outside". |
3320 | |
3342 | |
3321 | If you want to know which design (one loop, locking, or multiple loops |
3343 | If you want to know which design (one loop, locking, or multiple loops |
3322 | without or something else still) is best for your problem, then I cannot |
3344 | without or something else still) is best for your problem, then I cannot |
3323 | help you. I can give some generic advice however: |
3345 | help you, but here is some generic advice: |
3324 | |
3346 | |
3325 | =over 4 |
3347 | =over 4 |
3326 | |
3348 | |
3327 | =item * most applications have a main thread: use the default libev loop |
3349 | =item * most applications have a main thread: use the default libev loop |
3328 | in that thread, or create a separate thread running only the default loop. |
3350 | in that thread, or create a separate thread running only the default loop. |
… | |
… | |
3352 | default loop and triggering an C<ev_async> watcher from the default loop |
3374 | default loop and triggering an C<ev_async> watcher from the default loop |
3353 | watcher callback into the event loop interested in the signal. |
3375 | watcher callback into the event loop interested in the signal. |
3354 | |
3376 | |
3355 | =back |
3377 | =back |
3356 | |
3378 | |
3357 | =head2 COROUTINES |
3379 | =head3 COROUTINES |
3358 | |
3380 | |
3359 | Libev is much more accommodating to coroutines ("cooperative threads"): |
3381 | Libev is very accommodating to coroutines ("cooperative threads"): |
3360 | libev fully supports nesting calls to it's functions from different |
3382 | libev fully supports nesting calls to its functions from different |
3361 | coroutines (e.g. you can call C<ev_loop> on the same loop from two |
3383 | coroutines (e.g. you can call C<ev_loop> on the same loop from two |
3362 | different coroutines and switch freely between both coroutines running the |
3384 | different coroutines, and switch freely between both coroutines running the |
3363 | loop, as long as you don't confuse yourself). The only exception is that |
3385 | loop, as long as you don't confuse yourself). The only exception is that |
3364 | you must not do this from C<ev_periodic> reschedule callbacks. |
3386 | you must not do this from C<ev_periodic> reschedule callbacks. |
3365 | |
3387 | |
3366 | Care has been taken to ensure that libev does not keep local state inside |
3388 | Care has been taken to ensure that libev does not keep local state inside |
3367 | C<ev_loop>, and other calls do not usually allow coroutine switches. |
3389 | C<ev_loop>, and other calls do not usually allow for coroutine switches as |
|
|
3390 | they do not clal any callbacks. |
3368 | |
3391 | |
|
|
3392 | =head2 COMPILER WARNINGS |
3369 | |
3393 | |
3370 | =head1 COMPLEXITIES |
3394 | Depending on your compiler and compiler settings, you might get no or a |
|
|
3395 | lot of warnings when compiling libev code. Some people are apparently |
|
|
3396 | scared by this. |
3371 | |
3397 | |
3372 | In this section the complexities of (many of) the algorithms used inside |
3398 | However, these are unavoidable for many reasons. For one, each compiler |
3373 | libev will be explained. For complexity discussions about backends see the |
3399 | has different warnings, and each user has different tastes regarding |
3374 | documentation for C<ev_default_init>. |
3400 | warning options. "Warn-free" code therefore cannot be a goal except when |
|
|
3401 | targeting a specific compiler and compiler-version. |
3375 | |
3402 | |
3376 | All of the following are about amortised time: If an array needs to be |
3403 | Another reason is that some compiler warnings require elaborate |
3377 | extended, libev needs to realloc and move the whole array, but this |
3404 | workarounds, or other changes to the code that make it less clear and less |
3378 | happens asymptotically never with higher number of elements, so O(1) might |
3405 | maintainable. |
3379 | mean it might do a lengthy realloc operation in rare cases, but on average |
|
|
3380 | it is much faster and asymptotically approaches constant time. |
|
|
3381 | |
3406 | |
3382 | =over 4 |
3407 | And of course, some compiler warnings are just plain stupid, or simply |
|
|
3408 | wrong (because they don't actually warn about the condition their message |
|
|
3409 | seems to warn about). For example, certain older gcc versions had some |
|
|
3410 | warnings that resulted an extreme number of false positives. These have |
|
|
3411 | been fixed, but some people still insist on making code warn-free with |
|
|
3412 | such buggy versions. |
3383 | |
3413 | |
3384 | =item Starting and stopping timer/periodic watchers: O(log skipped_other_timers) |
3414 | While libev is written to generate as few warnings as possible, |
|
|
3415 | "warn-free" code is not a goal, and it is recommended not to build libev |
|
|
3416 | with any compiler warnings enabled unless you are prepared to cope with |
|
|
3417 | them (e.g. by ignoring them). Remember that warnings are just that: |
|
|
3418 | warnings, not errors, or proof of bugs. |
3385 | |
3419 | |
3386 | This means that, when you have a watcher that triggers in one hour and |
|
|
3387 | there are 100 watchers that would trigger before that then inserting will |
|
|
3388 | have to skip roughly seven (C<ld 100>) of these watchers. |
|
|
3389 | |
3420 | |
3390 | =item Changing timer/periodic watchers (by autorepeat or calling again): O(log skipped_other_timers) |
3421 | =head2 VALGRIND |
3391 | |
3422 | |
3392 | That means that changing a timer costs less than removing/adding them |
3423 | Valgrind has a special section here because it is a popular tool that is |
3393 | as only the relative motion in the event queue has to be paid for. |
3424 | highly useful. Unfortunately, valgrind reports are very hard to interpret. |
3394 | |
3425 | |
3395 | =item Starting io/check/prepare/idle/signal/child/fork/async watchers: O(1) |
3426 | If you think you found a bug (memory leak, uninitialised data access etc.) |
|
|
3427 | in libev, then check twice: If valgrind reports something like: |
3396 | |
3428 | |
3397 | These just add the watcher into an array or at the head of a list. |
3429 | ==2274== definitely lost: 0 bytes in 0 blocks. |
|
|
3430 | ==2274== possibly lost: 0 bytes in 0 blocks. |
|
|
3431 | ==2274== still reachable: 256 bytes in 1 blocks. |
3398 | |
3432 | |
3399 | =item Stopping check/prepare/idle/fork/async watchers: O(1) |
3433 | Then there is no memory leak, just as memory accounted to global variables |
|
|
3434 | is not a memleak - the memory is still being refernced, and didn't leak. |
3400 | |
3435 | |
3401 | =item Stopping an io/signal/child watcher: O(number_of_watchers_for_this_(fd/signal/pid % EV_PID_HASHSIZE)) |
3436 | Similarly, under some circumstances, valgrind might report kernel bugs |
|
|
3437 | as if it were a bug in libev (e.g. in realloc or in the poll backend, |
|
|
3438 | although an acceptable workaround has been found here), or it might be |
|
|
3439 | confused. |
3402 | |
3440 | |
3403 | These watchers are stored in lists then need to be walked to find the |
3441 | Keep in mind that valgrind is a very good tool, but only a tool. Don't |
3404 | correct watcher to remove. The lists are usually short (you don't usually |
3442 | make it into some kind of religion. |
3405 | have many watchers waiting for the same fd or signal). |
|
|
3406 | |
3443 | |
3407 | =item Finding the next timer in each loop iteration: O(1) |
3444 | If you are unsure about something, feel free to contact the mailing list |
|
|
3445 | with the full valgrind report and an explanation on why you think this |
|
|
3446 | is a bug in libev (best check the archives, too :). However, don't be |
|
|
3447 | annoyed when you get a brisk "this is no bug" answer and take the chance |
|
|
3448 | of learning how to interpret valgrind properly. |
3408 | |
3449 | |
3409 | By virtue of using a binary or 4-heap, the next timer is always found at a |
3450 | If you need, for some reason, empty reports from valgrind for your project |
3410 | fixed position in the storage array. |
3451 | I suggest using suppression lists. |
3411 | |
3452 | |
3412 | =item Each change on a file descriptor per loop iteration: O(number_of_watchers_for_this_fd) |
|
|
3413 | |
3453 | |
3414 | A change means an I/O watcher gets started or stopped, which requires |
3454 | =head1 PORTABILITY NOTES |
3415 | libev to recalculate its status (and possibly tell the kernel, depending |
|
|
3416 | on backend and whether C<ev_io_set> was used). |
|
|
3417 | |
3455 | |
3418 | =item Activating one watcher (putting it into the pending state): O(1) |
|
|
3419 | |
|
|
3420 | =item Priority handling: O(number_of_priorities) |
|
|
3421 | |
|
|
3422 | Priorities are implemented by allocating some space for each |
|
|
3423 | priority. When doing priority-based operations, libev usually has to |
|
|
3424 | linearly search all the priorities, but starting/stopping and activating |
|
|
3425 | watchers becomes O(1) w.r.t. priority handling. |
|
|
3426 | |
|
|
3427 | =item Sending an ev_async: O(1) |
|
|
3428 | |
|
|
3429 | =item Processing ev_async_send: O(number_of_async_watchers) |
|
|
3430 | |
|
|
3431 | =item Processing signals: O(max_signal_number) |
|
|
3432 | |
|
|
3433 | Sending involves a system call I<iff> there were no other C<ev_async_send> |
|
|
3434 | calls in the current loop iteration. Checking for async and signal events |
|
|
3435 | involves iterating over all running async watchers or all signal numbers. |
|
|
3436 | |
|
|
3437 | =back |
|
|
3438 | |
|
|
3439 | |
|
|
3440 | =head1 WIN32 PLATFORM LIMITATIONS AND WORKAROUNDS |
3456 | =head2 WIN32 PLATFORM LIMITATIONS AND WORKAROUNDS |
3441 | |
3457 | |
3442 | Win32 doesn't support any of the standards (e.g. POSIX) that libev |
3458 | Win32 doesn't support any of the standards (e.g. POSIX) that libev |
3443 | requires, and its I/O model is fundamentally incompatible with the POSIX |
3459 | requires, and its I/O model is fundamentally incompatible with the POSIX |
3444 | model. Libev still offers limited functionality on this platform in |
3460 | model. Libev still offers limited functionality on this platform in |
3445 | the form of the C<EVBACKEND_SELECT> backend, and only supports socket |
3461 | the form of the C<EVBACKEND_SELECT> backend, and only supports socket |
… | |
… | |
3456 | |
3472 | |
3457 | Not a libev limitation but worth mentioning: windows apparently doesn't |
3473 | Not a libev limitation but worth mentioning: windows apparently doesn't |
3458 | accept large writes: instead of resulting in a partial write, windows will |
3474 | accept large writes: instead of resulting in a partial write, windows will |
3459 | either accept everything or return C<ENOBUFS> if the buffer is too large, |
3475 | either accept everything or return C<ENOBUFS> if the buffer is too large, |
3460 | so make sure you only write small amounts into your sockets (less than a |
3476 | so make sure you only write small amounts into your sockets (less than a |
3461 | megabyte seems safe, but thsi apparently depends on the amount of memory |
3477 | megabyte seems safe, but this apparently depends on the amount of memory |
3462 | available). |
3478 | available). |
3463 | |
3479 | |
3464 | Due to the many, low, and arbitrary limits on the win32 platform and |
3480 | Due to the many, low, and arbitrary limits on the win32 platform and |
3465 | the abysmal performance of winsockets, using a large number of sockets |
3481 | the abysmal performance of winsockets, using a large number of sockets |
3466 | is not recommended (and not reasonable). If your program needs to use |
3482 | is not recommended (and not reasonable). If your program needs to use |
… | |
… | |
3477 | #define EV_SELECT_IS_WINSOCKET 1 /* configure libev for windows select */ |
3493 | #define EV_SELECT_IS_WINSOCKET 1 /* configure libev for windows select */ |
3478 | |
3494 | |
3479 | #include "ev.h" |
3495 | #include "ev.h" |
3480 | |
3496 | |
3481 | And compile the following F<evwrap.c> file into your project (make sure |
3497 | And compile the following F<evwrap.c> file into your project (make sure |
3482 | you do I<not> compile the F<ev.c> or any other embedded soruce files!): |
3498 | you do I<not> compile the F<ev.c> or any other embedded source files!): |
3483 | |
3499 | |
3484 | #include "evwrap.h" |
3500 | #include "evwrap.h" |
3485 | #include "ev.c" |
3501 | #include "ev.c" |
3486 | |
3502 | |
3487 | =over 4 |
3503 | =over 4 |
… | |
… | |
3532 | wrap all I/O functions and provide your own fd management, but the cost of |
3548 | wrap all I/O functions and provide your own fd management, but the cost of |
3533 | calling select (O(n²)) will likely make this unworkable. |
3549 | calling select (O(n²)) will likely make this unworkable. |
3534 | |
3550 | |
3535 | =back |
3551 | =back |
3536 | |
3552 | |
3537 | |
|
|
3538 | =head1 PORTABILITY REQUIREMENTS |
3553 | =head2 PORTABILITY REQUIREMENTS |
3539 | |
3554 | |
3540 | In addition to a working ISO-C implementation, libev relies on a few |
3555 | In addition to a working ISO-C implementation and of course the |
3541 | additional extensions: |
3556 | backend-specific APIs, libev relies on a few additional extensions: |
3542 | |
3557 | |
3543 | =over 4 |
3558 | =over 4 |
3544 | |
3559 | |
3545 | =item C<void (*)(ev_watcher_type *, int revents)> must have compatible |
3560 | =item C<void (*)(ev_watcher_type *, int revents)> must have compatible |
3546 | calling conventions regardless of C<ev_watcher_type *>. |
3561 | calling conventions regardless of C<ev_watcher_type *>. |
… | |
… | |
3552 | calls them using an C<ev_watcher *> internally. |
3567 | calls them using an C<ev_watcher *> internally. |
3553 | |
3568 | |
3554 | =item C<sig_atomic_t volatile> must be thread-atomic as well |
3569 | =item C<sig_atomic_t volatile> must be thread-atomic as well |
3555 | |
3570 | |
3556 | The type C<sig_atomic_t volatile> (or whatever is defined as |
3571 | The type C<sig_atomic_t volatile> (or whatever is defined as |
3557 | C<EV_ATOMIC_T>) must be atomic w.r.t. accesses from different |
3572 | C<EV_ATOMIC_T>) must be atomic with respect to accesses from different |
3558 | threads. This is not part of the specification for C<sig_atomic_t>, but is |
3573 | threads. This is not part of the specification for C<sig_atomic_t>, but is |
3559 | believed to be sufficiently portable. |
3574 | believed to be sufficiently portable. |
3560 | |
3575 | |
3561 | =item C<sigprocmask> must work in a threaded environment |
3576 | =item C<sigprocmask> must work in a threaded environment |
3562 | |
3577 | |
… | |
… | |
3571 | except the initial one, and run the default loop in the initial thread as |
3586 | except the initial one, and run the default loop in the initial thread as |
3572 | well. |
3587 | well. |
3573 | |
3588 | |
3574 | =item C<long> must be large enough for common memory allocation sizes |
3589 | =item C<long> must be large enough for common memory allocation sizes |
3575 | |
3590 | |
3576 | To improve portability and simplify using libev, libev uses C<long> |
3591 | To improve portability and simplify its API, libev uses C<long> internally |
3577 | internally instead of C<size_t> when allocating its data structures. On |
3592 | instead of C<size_t> when allocating its data structures. On non-POSIX |
3578 | non-POSIX systems (Microsoft...) this might be unexpectedly low, but |
3593 | systems (Microsoft...) this might be unexpectedly low, but is still at |
3579 | is still at least 31 bits everywhere, which is enough for hundreds of |
3594 | least 31 bits everywhere, which is enough for hundreds of millions of |
3580 | millions of watchers. |
3595 | watchers. |
3581 | |
3596 | |
3582 | =item C<double> must hold a time value in seconds with enough accuracy |
3597 | =item C<double> must hold a time value in seconds with enough accuracy |
3583 | |
3598 | |
3584 | The type C<double> is used to represent timestamps. It is required to |
3599 | The type C<double> is used to represent timestamps. It is required to |
3585 | have at least 51 bits of mantissa (and 9 bits of exponent), which is good |
3600 | have at least 51 bits of mantissa (and 9 bits of exponent), which is good |
… | |
… | |
3589 | =back |
3604 | =back |
3590 | |
3605 | |
3591 | If you know of other additional requirements drop me a note. |
3606 | If you know of other additional requirements drop me a note. |
3592 | |
3607 | |
3593 | |
3608 | |
3594 | =head1 COMPILER WARNINGS |
3609 | =head1 ALGORITHMIC COMPLEXITIES |
3595 | |
3610 | |
3596 | Depending on your compiler and compiler settings, you might get no or a |
3611 | In this section the complexities of (many of) the algorithms used inside |
3597 | lot of warnings when compiling libev code. Some people are apparently |
3612 | libev will be documented. For complexity discussions about backends see |
3598 | scared by this. |
3613 | the documentation for C<ev_default_init>. |
3599 | |
3614 | |
3600 | However, these are unavoidable for many reasons. For one, each compiler |
3615 | All of the following are about amortised time: If an array needs to be |
3601 | has different warnings, and each user has different tastes regarding |
3616 | extended, libev needs to realloc and move the whole array, but this |
3602 | warning options. "Warn-free" code therefore cannot be a goal except when |
3617 | happens asymptotically rarer with higher number of elements, so O(1) might |
3603 | targeting a specific compiler and compiler-version. |
3618 | mean that libev does a lengthy realloc operation in rare cases, but on |
|
|
3619 | average it is much faster and asymptotically approaches constant time. |
3604 | |
3620 | |
3605 | Another reason is that some compiler warnings require elaborate |
3621 | =over 4 |
3606 | workarounds, or other changes to the code that make it less clear and less |
|
|
3607 | maintainable. |
|
|
3608 | |
3622 | |
3609 | And of course, some compiler warnings are just plain stupid, or simply |
3623 | =item Starting and stopping timer/periodic watchers: O(log skipped_other_timers) |
3610 | wrong (because they don't actually warn about the condition their message |
|
|
3611 | seems to warn about). |
|
|
3612 | |
3624 | |
3613 | While libev is written to generate as few warnings as possible, |
3625 | This means that, when you have a watcher that triggers in one hour and |
3614 | "warn-free" code is not a goal, and it is recommended not to build libev |
3626 | there are 100 watchers that would trigger before that, then inserting will |
3615 | with any compiler warnings enabled unless you are prepared to cope with |
3627 | have to skip roughly seven (C<ld 100>) of these watchers. |
3616 | them (e.g. by ignoring them). Remember that warnings are just that: |
|
|
3617 | warnings, not errors, or proof of bugs. |
|
|
3618 | |
3628 | |
|
|
3629 | =item Changing timer/periodic watchers (by autorepeat or calling again): O(log skipped_other_timers) |
3619 | |
3630 | |
3620 | =head1 VALGRIND |
3631 | That means that changing a timer costs less than removing/adding them, |
|
|
3632 | as only the relative motion in the event queue has to be paid for. |
3621 | |
3633 | |
3622 | Valgrind has a special section here because it is a popular tool that is |
3634 | =item Starting io/check/prepare/idle/signal/child/fork/async watchers: O(1) |
3623 | highly useful, but valgrind reports are very hard to interpret. |
|
|
3624 | |
3635 | |
3625 | If you think you found a bug (memory leak, uninitialised data access etc.) |
3636 | These just add the watcher into an array or at the head of a list. |
3626 | in libev, then check twice: If valgrind reports something like: |
|
|
3627 | |
3637 | |
3628 | ==2274== definitely lost: 0 bytes in 0 blocks. |
3638 | =item Stopping check/prepare/idle/fork/async watchers: O(1) |
3629 | ==2274== possibly lost: 0 bytes in 0 blocks. |
|
|
3630 | ==2274== still reachable: 256 bytes in 1 blocks. |
|
|
3631 | |
3639 | |
3632 | Then there is no memory leak. Similarly, under some circumstances, |
3640 | =item Stopping an io/signal/child watcher: O(number_of_watchers_for_this_(fd/signal/pid % EV_PID_HASHSIZE)) |
3633 | valgrind might report kernel bugs as if it were a bug in libev, or it |
|
|
3634 | might be confused (it is a very good tool, but only a tool). |
|
|
3635 | |
3641 | |
3636 | If you are unsure about something, feel free to contact the mailing list |
3642 | These watchers are stored in lists, so they need to be walked to find the |
3637 | with the full valgrind report and an explanation on why you think this is |
3643 | correct watcher to remove. The lists are usually short (you don't usually |
3638 | a bug in libev. However, don't be annoyed when you get a brisk "this is |
3644 | have many watchers waiting for the same fd or signal: one is typical, two |
3639 | no bug" answer and take the chance of learning how to interpret valgrind |
3645 | is rare). |
3640 | properly. |
|
|
3641 | |
3646 | |
3642 | If you need, for some reason, empty reports from valgrind for your project |
3647 | =item Finding the next timer in each loop iteration: O(1) |
3643 | I suggest using suppression lists. |
3648 | |
|
|
3649 | By virtue of using a binary or 4-heap, the next timer is always found at a |
|
|
3650 | fixed position in the storage array. |
|
|
3651 | |
|
|
3652 | =item Each change on a file descriptor per loop iteration: O(number_of_watchers_for_this_fd) |
|
|
3653 | |
|
|
3654 | A change means an I/O watcher gets started or stopped, which requires |
|
|
3655 | libev to recalculate its status (and possibly tell the kernel, depending |
|
|
3656 | on backend and whether C<ev_io_set> was used). |
|
|
3657 | |
|
|
3658 | =item Activating one watcher (putting it into the pending state): O(1) |
|
|
3659 | |
|
|
3660 | =item Priority handling: O(number_of_priorities) |
|
|
3661 | |
|
|
3662 | Priorities are implemented by allocating some space for each |
|
|
3663 | priority. When doing priority-based operations, libev usually has to |
|
|
3664 | linearly search all the priorities, but starting/stopping and activating |
|
|
3665 | watchers becomes O(1) with respect to priority handling. |
|
|
3666 | |
|
|
3667 | =item Sending an ev_async: O(1) |
|
|
3668 | |
|
|
3669 | =item Processing ev_async_send: O(number_of_async_watchers) |
|
|
3670 | |
|
|
3671 | =item Processing signals: O(max_signal_number) |
|
|
3672 | |
|
|
3673 | Sending involves a system call I<iff> there were no other C<ev_async_send> |
|
|
3674 | calls in the current loop iteration. Checking for async and signal events |
|
|
3675 | involves iterating over all running async watchers or all signal numbers. |
|
|
3676 | |
|
|
3677 | =back |
3644 | |
3678 | |
3645 | |
3679 | |
3646 | =head1 AUTHOR |
3680 | =head1 AUTHOR |
3647 | |
3681 | |
3648 | Marc Lehmann <libev@schmorp.de>. |
3682 | Marc Lehmann <libev@schmorp.de>. |