… | |
… | |
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 |
… | |
… | |
2368 | is that the author does not know of a simple (or any) algorithm for a |
2368 | 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 |
2369 | multiple-writer-single-reader queue that works in all cases and doesn't |
2370 | need elaborate support such as pthreads. |
2370 | need elaborate support such as pthreads. |
2371 | |
2371 | |
2372 | That means that if you want to queue data, you have to provide your own |
2372 | 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 |
2373 | queue. But at least I can tell you how to implement locking around your |
2374 | queue: |
2374 | queue: |
2375 | |
2375 | |
2376 | =over 4 |
2376 | =over 4 |
2377 | |
2377 | |
2378 | =item queueing from a signal handler context |
2378 | =item queueing from a signal handler context |
… | |
… | |
2454 | |
2454 | |
2455 | =item ev_async_init (ev_async *, callback) |
2455 | =item ev_async_init (ev_async *, callback) |
2456 | |
2456 | |
2457 | Initialises and configures the async watcher - it has no parameters of any |
2457 | 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, |
2458 | kind. There is a C<ev_asynd_set> macro, but using it is utterly pointless, |
2459 | believe me. |
2459 | trust me. |
2460 | |
2460 | |
2461 | =item ev_async_send (loop, ev_async *) |
2461 | =item ev_async_send (loop, ev_async *) |
2462 | |
2462 | |
2463 | Sends/signals/activates the given C<ev_async> watcher, that is, feeds |
2463 | 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 |
2464 | 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 |
2465 | 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 |
2466 | similar contexts (see the discussion of C<EV_ATOMIC_T> in the embedding |
2467 | section below on what exactly this means). |
2467 | section below on what exactly this means). |
2468 | |
2468 | |
2469 | This call incurs the overhead of a system call only once per loop iteration, |
2469 | 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 |
2470 | so while the overhead might be noticeable, it doesn't apply to repeated |
… | |
… | |
2676 | |
2676 | |
2677 | The prototype of the C<function> must be C<void (*)(ev::TYPE &w, int)>. |
2677 | The prototype of the C<function> must be C<void (*)(ev::TYPE &w, int)>. |
2678 | |
2678 | |
2679 | See the method-C<set> above for more details. |
2679 | See the method-C<set> above for more details. |
2680 | |
2680 | |
2681 | Example: |
2681 | Example: Use a plain function as callback. |
2682 | |
2682 | |
2683 | static void io_cb (ev::io &w, int revents) { } |
2683 | static void io_cb (ev::io &w, int revents) { } |
2684 | iow.set <io_cb> (); |
2684 | iow.set <io_cb> (); |
2685 | |
2685 | |
2686 | =item w->set (struct ev_loop *) |
2686 | =item w->set (struct ev_loop *) |
… | |
… | |
2724 | Example: Define a class with an IO and idle watcher, start one of them in |
2724 | Example: Define a class with an IO and idle watcher, start one of them in |
2725 | the constructor. |
2725 | the constructor. |
2726 | |
2726 | |
2727 | class myclass |
2727 | class myclass |
2728 | { |
2728 | { |
2729 | ev::io io; void io_cb (ev::io &w, int revents); |
2729 | ev::io io ; void io_cb (ev::io &w, int revents); |
2730 | ev:idle idle void idle_cb (ev::idle &w, int revents); |
2730 | ev::idle idle; void idle_cb (ev::idle &w, int revents); |
2731 | |
2731 | |
2732 | myclass (int fd) |
2732 | myclass (int fd) |
2733 | { |
2733 | { |
2734 | io .set <myclass, &myclass::io_cb > (this); |
2734 | io .set <myclass, &myclass::io_cb > (this); |
2735 | idle.set <myclass, &myclass::idle_cb> (this); |
2735 | idle.set <myclass, &myclass::idle_cb> (this); |
… | |
… | |
2751 | =item Perl |
2751 | =item Perl |
2752 | |
2752 | |
2753 | The EV module implements the full libev API and is actually used to test |
2753 | 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, |
2754 | libev. EV is developed together with libev. Apart from the EV core module, |
2755 | there are additional modules that implement libev-compatible interfaces |
2755 | 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 |
2756 | 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>). |
2757 | C<Net::SNMP> (C<Net::SNMP::EV>) and the C<libglib> event core (C<Glib::EV> |
|
|
2758 | and C<EV::Glib>). |
2758 | |
2759 | |
2759 | It can be found and installed via CPAN, its homepage is at |
2760 | It can be found and installed via CPAN, its homepage is at |
2760 | L<http://software.schmorp.de/pkg/EV>. |
2761 | L<http://software.schmorp.de/pkg/EV>. |
2761 | |
2762 | |
2762 | =item Python |
2763 | =item Python |
… | |
… | |
2941 | |
2942 | |
2942 | =head2 PREPROCESSOR SYMBOLS/MACROS |
2943 | =head2 PREPROCESSOR SYMBOLS/MACROS |
2943 | |
2944 | |
2944 | Libev can be configured via a variety of preprocessor symbols you have to |
2945 | 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 |
2946 | define before including any of its files. The default in the absence of |
2946 | autoconf is noted for every option. |
2947 | autoconf is documented for every option. |
2947 | |
2948 | |
2948 | =over 4 |
2949 | =over 4 |
2949 | |
2950 | |
2950 | =item EV_STANDALONE |
2951 | =item EV_STANDALONE |
2951 | |
2952 | |
… | |
… | |
3121 | When doing priority-based operations, libev usually has to linearly search |
3122 | 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 |
3123 | 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 |
3124 | and time, so using the defaults of five priorities (-2 .. +2) is usually |
3124 | fine. |
3125 | fine. |
3125 | |
3126 | |
3126 | If your embedding application does not need any priorities, defining these both to |
3127 | If your embedding application does not need any priorities, defining these |
3127 | C<0> will save some memory and CPU. |
3128 | both to C<0> will save some memory and CPU. |
3128 | |
3129 | |
3129 | =item EV_PERIODIC_ENABLE |
3130 | =item EV_PERIODIC_ENABLE |
3130 | |
3131 | |
3131 | If undefined or defined to be C<1>, then periodic timers are supported. If |
3132 | 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 |
3133 | defined to be C<0>, then they are not. Disabling them saves a few kB of |
… | |
… | |
3139 | code. |
3140 | code. |
3140 | |
3141 | |
3141 | =item EV_EMBED_ENABLE |
3142 | =item EV_EMBED_ENABLE |
3142 | |
3143 | |
3143 | If undefined or defined to be C<1>, then embed watchers are supported. If |
3144 | If undefined or defined to be C<1>, then embed watchers are supported. If |
3144 | defined to be C<0>, then they are not. |
3145 | defined to be C<0>, then they are not. Embed watchers rely on most other |
|
|
3146 | watcher types, which therefore must not be disabled. |
3145 | |
3147 | |
3146 | =item EV_STAT_ENABLE |
3148 | =item EV_STAT_ENABLE |
3147 | |
3149 | |
3148 | If undefined or defined to be C<1>, then stat watchers are supported. If |
3150 | If undefined or defined to be C<1>, then stat watchers are supported. If |
3149 | defined to be C<0>, then they are not. |
3151 | defined to be C<0>, then they are not. |
… | |
… | |
3181 | two). |
3183 | two). |
3182 | |
3184 | |
3183 | =item EV_USE_4HEAP |
3185 | =item EV_USE_4HEAP |
3184 | |
3186 | |
3185 | Heaps are not very cache-efficient. To improve the cache-efficiency of the |
3187 | 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 |
3188 | 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 |
3189 | to C<1>. The 4-heap uses more complicated (longer) code but has noticeably |
3188 | noticeably faster performance with many (thousands) of watchers. |
3190 | faster performance with many (thousands) of watchers. |
3189 | |
3191 | |
3190 | The default is C<1> unless C<EV_MINIMAL> is set in which case it is C<0> |
3192 | The default is C<1> unless C<EV_MINIMAL> is set in which case it is C<0> |
3191 | (disabled). |
3193 | (disabled). |
3192 | |
3194 | |
3193 | =item EV_HEAP_CACHE_AT |
3195 | =item EV_HEAP_CACHE_AT |
3194 | |
3196 | |
3195 | Heaps are not very cache-efficient. To improve the cache-efficiency of the |
3197 | 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 |
3198 | 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>), |
3199 | 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, |
3200 | 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 |
3201 | but avoids random read accesses on heap changes. This improves performance |
3200 | noticeably with with many (hundreds) of watchers. |
3202 | noticeably with many (hundreds) of watchers. |
3201 | |
3203 | |
3202 | The default is C<1> unless C<EV_MINIMAL> is set in which case it is C<0> |
3204 | The default is C<1> unless C<EV_MINIMAL> is set in which case it is C<0> |
3203 | (disabled). |
3205 | (disabled). |
3204 | |
3206 | |
3205 | =item EV_VERIFY |
3207 | =item EV_VERIFY |
… | |
… | |
3211 | called once per loop, which can slow down libev. If set to C<3>, then the |
3213 | 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 |
3214 | verification code will be called very frequently, which will slow down |
3213 | libev considerably. |
3215 | libev considerably. |
3214 | |
3216 | |
3215 | The default is C<1>, unless C<EV_MINIMAL> is set, in which case it will be |
3217 | The default is C<1>, unless C<EV_MINIMAL> is set, in which case it will be |
3216 | C<0.> |
3218 | C<0>. |
3217 | |
3219 | |
3218 | =item EV_COMMON |
3220 | =item EV_COMMON |
3219 | |
3221 | |
3220 | By default, all watchers have a C<void *data> member. By redefining |
3222 | 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 |
3223 | this macro to a something else you can include more and other types of |
… | |
… | |
3303 | |
3305 | |
3304 | Libev itself is thread-safe (unless the opposite is specifically |
3306 | Libev itself is thread-safe (unless the opposite is specifically |
3305 | documented for a function), but it uses no locking itself. This means that |
3307 | documented for a function), but it uses no locking itself. This means that |
3306 | you can use as many loops as you want in parallel, as long as only one |
3308 | you can use as many loops as you want in parallel, as long as only one |
3307 | thread ever calls into one libev function with the same loop parameter: |
3309 | thread ever calls into one libev function with the same loop parameter: |
3308 | libev guarentees that different event loops share no data structures that |
3310 | libev guarantees that different event loops share no data structures that |
3309 | need locking. |
3311 | need locking. |
3310 | |
3312 | |
3311 | Or to put it differently: calls with different loop parameters can be done |
3313 | Or to put it differently: calls with different loop parameters can be done |
3312 | concurrently from multiple threads, calls with the same loop parameter |
3314 | 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 |
3315 | must be done serially (but can be done from different threads, as long as |
… | |
… | |
3420 | =item Priority handling: O(number_of_priorities) |
3422 | =item Priority handling: O(number_of_priorities) |
3421 | |
3423 | |
3422 | Priorities are implemented by allocating some space for each |
3424 | Priorities are implemented by allocating some space for each |
3423 | priority. When doing priority-based operations, libev usually has to |
3425 | priority. When doing priority-based operations, libev usually has to |
3424 | linearly search all the priorities, but starting/stopping and activating |
3426 | linearly search all the priorities, but starting/stopping and activating |
3425 | watchers becomes O(1) w.r.t. priority handling. |
3427 | watchers becomes O(1) with respect to priority handling. |
3426 | |
3428 | |
3427 | =item Sending an ev_async: O(1) |
3429 | =item Sending an ev_async: O(1) |
3428 | |
3430 | |
3429 | =item Processing ev_async_send: O(number_of_async_watchers) |
3431 | =item Processing ev_async_send: O(number_of_async_watchers) |
3430 | |
3432 | |
… | |
… | |
3456 | |
3458 | |
3457 | Not a libev limitation but worth mentioning: windows apparently doesn't |
3459 | Not a libev limitation but worth mentioning: windows apparently doesn't |
3458 | accept large writes: instead of resulting in a partial write, windows will |
3460 | 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, |
3461 | 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 |
3462 | 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 |
3463 | megabyte seems safe, but this apparently depends on the amount of memory |
3462 | available). |
3464 | available). |
3463 | |
3465 | |
3464 | Due to the many, low, and arbitrary limits on the win32 platform and |
3466 | 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 |
3467 | the abysmal performance of winsockets, using a large number of sockets |
3466 | is not recommended (and not reasonable). If your program needs to use |
3468 | is not recommended (and not reasonable). If your program needs to use |
… | |
… | |
3477 | #define EV_SELECT_IS_WINSOCKET 1 /* configure libev for windows select */ |
3479 | #define EV_SELECT_IS_WINSOCKET 1 /* configure libev for windows select */ |
3478 | |
3480 | |
3479 | #include "ev.h" |
3481 | #include "ev.h" |
3480 | |
3482 | |
3481 | And compile the following F<evwrap.c> file into your project (make sure |
3483 | 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!): |
3484 | you do I<not> compile the F<ev.c> or any other embedded source files!): |
3483 | |
3485 | |
3484 | #include "evwrap.h" |
3486 | #include "evwrap.h" |
3485 | #include "ev.c" |
3487 | #include "ev.c" |
3486 | |
3488 | |
3487 | =over 4 |
3489 | =over 4 |
… | |
… | |
3552 | calls them using an C<ev_watcher *> internally. |
3554 | calls them using an C<ev_watcher *> internally. |
3553 | |
3555 | |
3554 | =item C<sig_atomic_t volatile> must be thread-atomic as well |
3556 | =item C<sig_atomic_t volatile> must be thread-atomic as well |
3555 | |
3557 | |
3556 | The type C<sig_atomic_t volatile> (or whatever is defined as |
3558 | 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 |
3559 | 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 |
3560 | threads. This is not part of the specification for C<sig_atomic_t>, but is |
3559 | believed to be sufficiently portable. |
3561 | believed to be sufficiently portable. |
3560 | |
3562 | |
3561 | =item C<sigprocmask> must work in a threaded environment |
3563 | =item C<sigprocmask> must work in a threaded environment |
3562 | |
3564 | |