… | |
… | |
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 |
… | |
… | |
2233 | when you fork, you not only have to call C<ev_loop_fork> on both loops, |
2233 | 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 |
2234 | 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, |
2235 | yourself - but you can use a fork watcher to handle this automatically, |
2236 | and future versions of libev might do just that. |
2236 | and future versions of libev might do just that. |
2237 | |
2237 | |
2238 | Unfortunately, not all backends are embeddable, only the ones returned by |
2238 | Unfortunately, not all backends are embeddable: only the ones returned by |
2239 | C<ev_embeddable_backends> are, which, unfortunately, does not include any |
2239 | C<ev_embeddable_backends> are, which, unfortunately, does not include any |
2240 | portable one. |
2240 | portable one. |
2241 | |
2241 | |
2242 | So when you want to use this feature you will always have to be prepared |
2242 | 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 |
2243 | 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 |
2244 | 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. |
2245 | create it, and if that fails, use the normal loop for everything. |
|
|
2246 | |
|
|
2247 | =head3 C<ev_embed> and fork |
|
|
2248 | |
|
|
2249 | While the C<ev_embed> watcher is running, forks in the embedding loop will |
|
|
2250 | automatically be applied to the embedded loop as well, so no special |
|
|
2251 | fork handling is required in that case. When the watcher is not running, |
|
|
2252 | however, it is still the task of the libev user to call C<ev_loop_fork ()> |
|
|
2253 | as applicable. |
2246 | |
2254 | |
2247 | =head3 Watcher-Specific Functions and Data Members |
2255 | =head3 Watcher-Specific Functions and Data Members |
2248 | |
2256 | |
2249 | =over 4 |
2257 | =over 4 |
2250 | |
2258 | |
… | |
… | |
2368 | is that the author does not know of a simple (or any) algorithm for a |
2376 | 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 |
2377 | multiple-writer-single-reader queue that works in all cases and doesn't |
2370 | need elaborate support such as pthreads. |
2378 | need elaborate support such as pthreads. |
2371 | |
2379 | |
2372 | That means that if you want to queue data, you have to provide your own |
2380 | 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 |
2381 | queue. But at least I can tell you how to implement locking around your |
2374 | queue: |
2382 | queue: |
2375 | |
2383 | |
2376 | =over 4 |
2384 | =over 4 |
2377 | |
2385 | |
2378 | =item queueing from a signal handler context |
2386 | =item queueing from a signal handler context |
… | |
… | |
2454 | |
2462 | |
2455 | =item ev_async_init (ev_async *, callback) |
2463 | =item ev_async_init (ev_async *, callback) |
2456 | |
2464 | |
2457 | Initialises and configures the async watcher - it has no parameters of any |
2465 | 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, |
2466 | kind. There is a C<ev_asynd_set> macro, but using it is utterly pointless, |
2459 | believe me. |
2467 | trust me. |
2460 | |
2468 | |
2461 | =item ev_async_send (loop, ev_async *) |
2469 | =item ev_async_send (loop, ev_async *) |
2462 | |
2470 | |
2463 | Sends/signals/activates the given C<ev_async> watcher, that is, feeds |
2471 | 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 |
2472 | 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 |
2473 | 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 |
2474 | similar contexts (see the discussion of C<EV_ATOMIC_T> in the embedding |
2467 | section below on what exactly this means). |
2475 | section below on what exactly this means). |
2468 | |
2476 | |
2469 | This call incurs the overhead of a system call only once per loop iteration, |
2477 | 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 |
2478 | so while the overhead might be noticeable, it doesn't apply to repeated |
… | |
… | |
2676 | |
2684 | |
2677 | The prototype of the C<function> must be C<void (*)(ev::TYPE &w, int)>. |
2685 | The prototype of the C<function> must be C<void (*)(ev::TYPE &w, int)>. |
2678 | |
2686 | |
2679 | See the method-C<set> above for more details. |
2687 | See the method-C<set> above for more details. |
2680 | |
2688 | |
2681 | Example: |
2689 | Example: Use a plain function as callback. |
2682 | |
2690 | |
2683 | static void io_cb (ev::io &w, int revents) { } |
2691 | static void io_cb (ev::io &w, int revents) { } |
2684 | iow.set <io_cb> (); |
2692 | iow.set <io_cb> (); |
2685 | |
2693 | |
2686 | =item w->set (struct ev_loop *) |
2694 | =item w->set (struct ev_loop *) |
… | |
… | |
2724 | Example: Define a class with an IO and idle watcher, start one of them in |
2732 | Example: Define a class with an IO and idle watcher, start one of them in |
2725 | the constructor. |
2733 | the constructor. |
2726 | |
2734 | |
2727 | class myclass |
2735 | class myclass |
2728 | { |
2736 | { |
2729 | ev::io io; void io_cb (ev::io &w, int revents); |
2737 | ev::io io ; void io_cb (ev::io &w, int revents); |
2730 | ev:idle idle void idle_cb (ev::idle &w, int revents); |
2738 | ev::idle idle; void idle_cb (ev::idle &w, int revents); |
2731 | |
2739 | |
2732 | myclass (int fd) |
2740 | myclass (int fd) |
2733 | { |
2741 | { |
2734 | io .set <myclass, &myclass::io_cb > (this); |
2742 | io .set <myclass, &myclass::io_cb > (this); |
2735 | idle.set <myclass, &myclass::idle_cb> (this); |
2743 | idle.set <myclass, &myclass::idle_cb> (this); |
… | |
… | |
2751 | =item Perl |
2759 | =item Perl |
2752 | |
2760 | |
2753 | The EV module implements the full libev API and is actually used to test |
2761 | 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, |
2762 | libev. EV is developed together with libev. Apart from the EV core module, |
2755 | there are additional modules that implement libev-compatible interfaces |
2763 | 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 |
2764 | 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>). |
2765 | C<Net::SNMP> (C<Net::SNMP::EV>) and the C<libglib> event core (C<Glib::EV> |
|
|
2766 | and C<EV::Glib>). |
2758 | |
2767 | |
2759 | It can be found and installed via CPAN, its homepage is at |
2768 | It can be found and installed via CPAN, its homepage is at |
2760 | L<http://software.schmorp.de/pkg/EV>. |
2769 | L<http://software.schmorp.de/pkg/EV>. |
2761 | |
2770 | |
2762 | =item Python |
2771 | =item Python |
… | |
… | |
2941 | |
2950 | |
2942 | =head2 PREPROCESSOR SYMBOLS/MACROS |
2951 | =head2 PREPROCESSOR SYMBOLS/MACROS |
2943 | |
2952 | |
2944 | Libev can be configured via a variety of preprocessor symbols you have to |
2953 | 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 |
2954 | define before including any of its files. The default in the absence of |
2946 | autoconf is noted for every option. |
2955 | autoconf is documented for every option. |
2947 | |
2956 | |
2948 | =over 4 |
2957 | =over 4 |
2949 | |
2958 | |
2950 | =item EV_STANDALONE |
2959 | =item EV_STANDALONE |
2951 | |
2960 | |
… | |
… | |
3121 | When doing priority-based operations, libev usually has to linearly search |
3130 | 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 |
3131 | 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 |
3132 | and time, so using the defaults of five priorities (-2 .. +2) is usually |
3124 | fine. |
3133 | fine. |
3125 | |
3134 | |
3126 | If your embedding application does not need any priorities, defining these both to |
3135 | If your embedding application does not need any priorities, defining these |
3127 | C<0> will save some memory and CPU. |
3136 | both to C<0> will save some memory and CPU. |
3128 | |
3137 | |
3129 | =item EV_PERIODIC_ENABLE |
3138 | =item EV_PERIODIC_ENABLE |
3130 | |
3139 | |
3131 | If undefined or defined to be C<1>, then periodic timers are supported. If |
3140 | 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 |
3141 | defined to be C<0>, then they are not. Disabling them saves a few kB of |
… | |
… | |
3139 | code. |
3148 | code. |
3140 | |
3149 | |
3141 | =item EV_EMBED_ENABLE |
3150 | =item EV_EMBED_ENABLE |
3142 | |
3151 | |
3143 | If undefined or defined to be C<1>, then embed watchers are supported. If |
3152 | If undefined or defined to be C<1>, then embed watchers are supported. If |
3144 | defined to be C<0>, then they are not. |
3153 | defined to be C<0>, then they are not. Embed watchers rely on most other |
|
|
3154 | watcher types, which therefore must not be disabled. |
3145 | |
3155 | |
3146 | =item EV_STAT_ENABLE |
3156 | =item EV_STAT_ENABLE |
3147 | |
3157 | |
3148 | If undefined or defined to be C<1>, then stat watchers are supported. If |
3158 | If undefined or defined to be C<1>, then stat watchers are supported. If |
3149 | defined to be C<0>, then they are not. |
3159 | defined to be C<0>, then they are not. |
… | |
… | |
3181 | two). |
3191 | two). |
3182 | |
3192 | |
3183 | =item EV_USE_4HEAP |
3193 | =item EV_USE_4HEAP |
3184 | |
3194 | |
3185 | Heaps are not very cache-efficient. To improve the cache-efficiency of the |
3195 | 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 |
3196 | 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 |
3197 | to C<1>. The 4-heap uses more complicated (longer) code but has noticeably |
3188 | noticeably faster performance with many (thousands) of watchers. |
3198 | faster performance with many (thousands) of watchers. |
3189 | |
3199 | |
3190 | The default is C<1> unless C<EV_MINIMAL> is set in which case it is C<0> |
3200 | The default is C<1> unless C<EV_MINIMAL> is set in which case it is C<0> |
3191 | (disabled). |
3201 | (disabled). |
3192 | |
3202 | |
3193 | =item EV_HEAP_CACHE_AT |
3203 | =item EV_HEAP_CACHE_AT |
3194 | |
3204 | |
3195 | Heaps are not very cache-efficient. To improve the cache-efficiency of the |
3205 | 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 |
3206 | 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>), |
3207 | 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, |
3208 | 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 |
3209 | but avoids random read accesses on heap changes. This improves performance |
3200 | noticeably with with many (hundreds) of watchers. |
3210 | noticeably with many (hundreds) of watchers. |
3201 | |
3211 | |
3202 | The default is C<1> unless C<EV_MINIMAL> is set in which case it is C<0> |
3212 | The default is C<1> unless C<EV_MINIMAL> is set in which case it is C<0> |
3203 | (disabled). |
3213 | (disabled). |
3204 | |
3214 | |
3205 | =item EV_VERIFY |
3215 | =item EV_VERIFY |
… | |
… | |
3211 | called once per loop, which can slow down libev. If set to C<3>, then the |
3221 | 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 |
3222 | verification code will be called very frequently, which will slow down |
3213 | libev considerably. |
3223 | libev considerably. |
3214 | |
3224 | |
3215 | The default is C<1>, unless C<EV_MINIMAL> is set, in which case it will be |
3225 | The default is C<1>, unless C<EV_MINIMAL> is set, in which case it will be |
3216 | C<0.> |
3226 | C<0>. |
3217 | |
3227 | |
3218 | =item EV_COMMON |
3228 | =item EV_COMMON |
3219 | |
3229 | |
3220 | By default, all watchers have a C<void *data> member. By redefining |
3230 | 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 |
3231 | 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 |
3248 | 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 |
3249 | 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 |
3250 | 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 |
3251 | 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++. |
3252 | method calls instead of plain function calls in C++. |
|
|
3253 | |
|
|
3254 | =back |
3243 | |
3255 | |
3244 | =head2 EXPORTED API SYMBOLS |
3256 | =head2 EXPORTED API SYMBOLS |
3245 | |
3257 | |
3246 | If you need to re-export the API (e.g. via a DLL) and you need a list of |
3258 | 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 |
3259 | exported symbols, you can use the provided F<Symbol.*> files which list |
… | |
… | |
3299 | |
3311 | |
3300 | =head1 THREADS AND COROUTINES |
3312 | =head1 THREADS AND COROUTINES |
3301 | |
3313 | |
3302 | =head2 THREADS |
3314 | =head2 THREADS |
3303 | |
3315 | |
3304 | Libev itself is thread-safe (unless the opposite is specifically |
3316 | All libev functions are reentrant and thread-safe unless explicitly |
3305 | documented for a function), but it uses no locking itself. This means that |
3317 | documented otherwise, but it uses no locking itself. This means that you |
3306 | you can use as many loops as you want in parallel, as long as only one |
3318 | can use as many loops as you want in parallel, as long as there are no |
3307 | thread ever calls into one libev function with the same loop parameter: |
3319 | concurrent calls into any libev function with the same loop parameter |
|
|
3320 | (C<ev_default_*> calls have an implicit default loop parameter, of |
3308 | libev guarentees that different event loops share no data structures that |
3321 | course): libev guarantees that different event loops share no data |
3309 | need locking. |
3322 | structures that need any locking. |
3310 | |
3323 | |
3311 | Or to put it differently: calls with different loop parameters can be done |
3324 | Or to put it differently: calls with different loop parameters can be done |
3312 | concurrently from multiple threads, calls with the same loop parameter |
3325 | 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 |
3326 | 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 |
3327 | only one thread ever is inside a call at any point in time, e.g. by using |
3315 | a mutex per loop). |
3328 | a mutex per loop). |
3316 | |
3329 | |
3317 | Specifically to support threads (and signal handlers), libev implements |
3330 | Specifically to support threads (and signal handlers), libev implements |
3318 | so-called C<ev_async> watchers, which allow some limited form of |
3331 | so-called C<ev_async> watchers, which allow some limited form of |
3319 | concurrency on the same event loop. |
3332 | concurrency on the same event loop, namely waking it up "from the |
|
|
3333 | outside". |
3320 | |
3334 | |
3321 | If you want to know which design (one loop, locking, or multiple loops |
3335 | 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 |
3336 | without or something else still) is best for your problem, then I cannot |
3323 | help you. I can give some generic advice however: |
3337 | help you, but here is some generic advice: |
3324 | |
3338 | |
3325 | =over 4 |
3339 | =over 4 |
3326 | |
3340 | |
3327 | =item * most applications have a main thread: use the default libev loop |
3341 | =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. |
3342 | in that thread, or create a separate thread running only the default loop. |
… | |
… | |
3420 | =item Priority handling: O(number_of_priorities) |
3434 | =item Priority handling: O(number_of_priorities) |
3421 | |
3435 | |
3422 | Priorities are implemented by allocating some space for each |
3436 | Priorities are implemented by allocating some space for each |
3423 | priority. When doing priority-based operations, libev usually has to |
3437 | priority. When doing priority-based operations, libev usually has to |
3424 | linearly search all the priorities, but starting/stopping and activating |
3438 | linearly search all the priorities, but starting/stopping and activating |
3425 | watchers becomes O(1) w.r.t. priority handling. |
3439 | watchers becomes O(1) with respect to priority handling. |
3426 | |
3440 | |
3427 | =item Sending an ev_async: O(1) |
3441 | =item Sending an ev_async: O(1) |
3428 | |
3442 | |
3429 | =item Processing ev_async_send: O(number_of_async_watchers) |
3443 | =item Processing ev_async_send: O(number_of_async_watchers) |
3430 | |
3444 | |
… | |
… | |
3456 | |
3470 | |
3457 | Not a libev limitation but worth mentioning: windows apparently doesn't |
3471 | Not a libev limitation but worth mentioning: windows apparently doesn't |
3458 | accept large writes: instead of resulting in a partial write, windows will |
3472 | 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, |
3473 | 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 |
3474 | 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 |
3475 | megabyte seems safe, but this apparently depends on the amount of memory |
3462 | available). |
3476 | available). |
3463 | |
3477 | |
3464 | Due to the many, low, and arbitrary limits on the win32 platform and |
3478 | 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 |
3479 | the abysmal performance of winsockets, using a large number of sockets |
3466 | is not recommended (and not reasonable). If your program needs to use |
3480 | is not recommended (and not reasonable). If your program needs to use |
… | |
… | |
3477 | #define EV_SELECT_IS_WINSOCKET 1 /* configure libev for windows select */ |
3491 | #define EV_SELECT_IS_WINSOCKET 1 /* configure libev for windows select */ |
3478 | |
3492 | |
3479 | #include "ev.h" |
3493 | #include "ev.h" |
3480 | |
3494 | |
3481 | And compile the following F<evwrap.c> file into your project (make sure |
3495 | 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!): |
3496 | you do I<not> compile the F<ev.c> or any other embedded source files!): |
3483 | |
3497 | |
3484 | #include "evwrap.h" |
3498 | #include "evwrap.h" |
3485 | #include "ev.c" |
3499 | #include "ev.c" |
3486 | |
3500 | |
3487 | =over 4 |
3501 | =over 4 |
… | |
… | |
3552 | calls them using an C<ev_watcher *> internally. |
3566 | calls them using an C<ev_watcher *> internally. |
3553 | |
3567 | |
3554 | =item C<sig_atomic_t volatile> must be thread-atomic as well |
3568 | =item C<sig_atomic_t volatile> must be thread-atomic as well |
3555 | |
3569 | |
3556 | The type C<sig_atomic_t volatile> (or whatever is defined as |
3570 | 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 |
3571 | 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 |
3572 | threads. This is not part of the specification for C<sig_atomic_t>, but is |
3559 | believed to be sufficiently portable. |
3573 | believed to be sufficiently portable. |
3560 | |
3574 | |
3561 | =item C<sigprocmask> must work in a threaded environment |
3575 | =item C<sigprocmask> must work in a threaded environment |
3562 | |
3576 | |