… | |
… | |
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 |
… | |
… | |
1625 | |
1625 | |
1626 | =back |
1626 | =back |
1627 | |
1627 | |
1628 | =head3 Examples |
1628 | =head3 Examples |
1629 | |
1629 | |
1630 | Example: Try to exit cleanly on SIGINT and SIGTERM. |
1630 | Example: Try to exit cleanly on SIGINT. |
1631 | |
1631 | |
1632 | static void |
1632 | static void |
1633 | sigint_cb (struct ev_loop *loop, struct ev_signal *w, int revents) |
1633 | sigint_cb (struct ev_loop *loop, struct ev_signal *w, int revents) |
1634 | { |
1634 | { |
1635 | ev_unloop (loop, EVUNLOOP_ALL); |
1635 | ev_unloop (loop, EVUNLOOP_ALL); |
1636 | } |
1636 | } |
1637 | |
1637 | |
1638 | struct ev_signal signal_watcher; |
1638 | struct ev_signal signal_watcher; |
1639 | ev_signal_init (&signal_watcher, sigint_cb, SIGINT); |
1639 | ev_signal_init (&signal_watcher, sigint_cb, SIGINT); |
1640 | ev_signal_start (loop, &sigint_cb); |
1640 | ev_signal_start (loop, &signal_watcher); |
1641 | |
1641 | |
1642 | |
1642 | |
1643 | =head2 C<ev_child> - watch out for process status changes |
1643 | =head2 C<ev_child> - watch out for process status changes |
1644 | |
1644 | |
1645 | Child watchers trigger when your process receives a SIGCHLD in response to |
1645 | Child watchers trigger when your process receives a SIGCHLD in response to |
… | |
… | |
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 | |
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. |
|
|
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 | |
2251 | =item ev_embed_init (ev_embed *, callback, struct ev_loop *embedded_loop) |
2259 | =item ev_embed_init (ev_embed *, callback, struct ev_loop *embedded_loop) |
… | |
… | |
3241 | 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 |
3242 | their default definitions. One possible use for overriding these is to |
3250 | their default definitions. One possible use for overriding these is to |
3243 | 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 |
3244 | method calls instead of plain function calls in C++. |
3252 | method calls instead of plain function calls in C++. |
3245 | |
3253 | |
|
|
3254 | =back |
|
|
3255 | |
3246 | =head2 EXPORTED API SYMBOLS |
3256 | =head2 EXPORTED API SYMBOLS |
3247 | |
3257 | |
3248 | 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 |
3249 | 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 |
3250 | all public symbols, one per line: |
3260 | all public symbols, one per line: |
… | |
… | |
3301 | |
3311 | |
3302 | =head1 THREADS AND COROUTINES |
3312 | =head1 THREADS AND COROUTINES |
3303 | |
3313 | |
3304 | =head2 THREADS |
3314 | =head2 THREADS |
3305 | |
3315 | |
3306 | Libev itself is thread-safe (unless the opposite is specifically |
3316 | All libev functions are reentrant and thread-safe unless explicitly |
3307 | 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 |
3308 | 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 |
3309 | 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 |
3310 | libev guarantees that different event loops share no data structures that |
3321 | course): libev guarantees that different event loops share no data |
3311 | need locking. |
3322 | structures that need any locking. |
3312 | |
3323 | |
3313 | 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 |
3314 | concurrently from multiple threads, calls with the same loop parameter |
3325 | concurrently from multiple threads, calls with the same loop parameter |
3315 | 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 |
3316 | 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 |
3317 | a mutex per loop). |
3328 | a mutex per loop). |
3318 | |
3329 | |
3319 | Specifically to support threads (and signal handlers), libev implements |
3330 | Specifically to support threads (and signal handlers), libev implements |
3320 | 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 |
3321 | concurrency on the same event loop. |
3332 | concurrency on the same event loop, namely waking it up "from the |
|
|
3333 | outside". |
3322 | |
3334 | |
3323 | 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 |
3324 | 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 |
3325 | help you. I can give some generic advice however: |
3337 | help you, but here is some generic advice: |
3326 | |
3338 | |
3327 | =over 4 |
3339 | =over 4 |
3328 | |
3340 | |
3329 | =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 |
3330 | 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. |