… | |
… | |
122 | .\} |
122 | .\} |
123 | .rm #[ #] #H #V #F C |
123 | .rm #[ #] #H #V #F C |
124 | .\" ======================================================================== |
124 | .\" ======================================================================== |
125 | .\" |
125 | .\" |
126 | .IX Title "LIBEV 3" |
126 | .IX Title "LIBEV 3" |
127 | .TH LIBEV 3 "2010-10-25" "libev-4.00" "libev - high performance full featured event loop" |
127 | .TH LIBEV 3 "2010-11-03" "libev-4.01" "libev - high performance full featured event loop" |
128 | .\" For nroff, turn off justification. Always turn off hyphenation; it makes |
128 | .\" For nroff, turn off justification. Always turn off hyphenation; it makes |
129 | .\" way too many mistakes in technical documents. |
129 | .\" way too many mistakes in technical documents. |
130 | .if n .ad l |
130 | .if n .ad l |
131 | .nh |
131 | .nh |
132 | .SH "NAME" |
132 | .SH "NAME" |
… | |
… | |
361 | current system. To find which embeddable backends might be supported on |
361 | current system. To find which embeddable backends might be supported on |
362 | the current system, you would need to look at \f(CW\*(C`ev_embeddable_backends () |
362 | the current system, you would need to look at \f(CW\*(C`ev_embeddable_backends () |
363 | & ev_supported_backends ()\*(C'\fR, likewise for recommended ones. |
363 | & ev_supported_backends ()\*(C'\fR, likewise for recommended ones. |
364 | .Sp |
364 | .Sp |
365 | See the description of \f(CW\*(C`ev_embed\*(C'\fR watchers for more info. |
365 | See the description of \f(CW\*(C`ev_embed\*(C'\fR watchers for more info. |
366 | .IP "ev_set_allocator (void *(*cb)(void *ptr, long size)) [\s-1NOT\s0 \s-1REENTRANT\s0]" 4 |
366 | .IP "ev_set_allocator (void *(*cb)(void *ptr, long size))" 4 |
367 | .IX Item "ev_set_allocator (void *(*cb)(void *ptr, long size)) [NOT REENTRANT]" |
367 | .IX Item "ev_set_allocator (void *(*cb)(void *ptr, long size))" |
368 | Sets the allocation function to use (the prototype is similar \- the |
368 | Sets the allocation function to use (the prototype is similar \- the |
369 | semantics are identical to the \f(CW\*(C`realloc\*(C'\fR C89/SuS/POSIX function). It is |
369 | semantics are identical to the \f(CW\*(C`realloc\*(C'\fR C89/SuS/POSIX function). It is |
370 | used to allocate and free memory (no surprises here). If it returns zero |
370 | used to allocate and free memory (no surprises here). If it returns zero |
371 | when memory needs to be allocated (\f(CW\*(C`size != 0\*(C'\fR), the library might abort |
371 | when memory needs to be allocated (\f(CW\*(C`size != 0\*(C'\fR), the library might abort |
372 | or take some potentially destructive action. |
372 | or take some potentially destructive action. |
… | |
… | |
398 | \& } |
398 | \& } |
399 | \& |
399 | \& |
400 | \& ... |
400 | \& ... |
401 | \& ev_set_allocator (persistent_realloc); |
401 | \& ev_set_allocator (persistent_realloc); |
402 | .Ve |
402 | .Ve |
403 | .IP "ev_set_syserr_cb (void (*cb)(const char *msg)); [\s-1NOT\s0 \s-1REENTRANT\s0]" 4 |
403 | .IP "ev_set_syserr_cb (void (*cb)(const char *msg))" 4 |
404 | .IX Item "ev_set_syserr_cb (void (*cb)(const char *msg)); [NOT REENTRANT]" |
404 | .IX Item "ev_set_syserr_cb (void (*cb)(const char *msg))" |
405 | Set the callback function to call on a retryable system call error (such |
405 | Set the callback function to call on a retryable system call error (such |
406 | as failed select, poll, epoll_wait). The message is a printable string |
406 | as failed select, poll, epoll_wait). The message is a printable string |
407 | indicating the system call or subsystem causing the problem. If this |
407 | indicating the system call or subsystem causing the problem. If this |
408 | callback is set, then libev will expect it to remedy the situation, no |
408 | callback is set, then libev will expect it to remedy the situation, no |
409 | matter what, when it returns. That is, libev will generally retry the |
409 | matter what, when it returns. That is, libev will generally retry the |
… | |
… | |
521 | environment variable. |
521 | environment variable. |
522 | .ie n .IP """EVFLAG_NOINOTIFY""" 4 |
522 | .ie n .IP """EVFLAG_NOINOTIFY""" 4 |
523 | .el .IP "\f(CWEVFLAG_NOINOTIFY\fR" 4 |
523 | .el .IP "\f(CWEVFLAG_NOINOTIFY\fR" 4 |
524 | .IX Item "EVFLAG_NOINOTIFY" |
524 | .IX Item "EVFLAG_NOINOTIFY" |
525 | When this flag is specified, then libev will not attempt to use the |
525 | When this flag is specified, then libev will not attempt to use the |
526 | \&\fIinotify\fR \s-1API\s0 for it's \f(CW\*(C`ev_stat\*(C'\fR watchers. Apart from debugging and |
526 | \&\fIinotify\fR \s-1API\s0 for its \f(CW\*(C`ev_stat\*(C'\fR watchers. Apart from debugging and |
527 | testing, this flag can be useful to conserve inotify file descriptors, as |
527 | testing, this flag can be useful to conserve inotify file descriptors, as |
528 | otherwise each loop using \f(CW\*(C`ev_stat\*(C'\fR watchers consumes one inotify handle. |
528 | otherwise each loop using \f(CW\*(C`ev_stat\*(C'\fR watchers consumes one inotify handle. |
529 | .ie n .IP """EVFLAG_SIGNALFD""" 4 |
529 | .ie n .IP """EVFLAG_SIGNALFD""" 4 |
530 | .el .IP "\f(CWEVFLAG_SIGNALFD\fR" 4 |
530 | .el .IP "\f(CWEVFLAG_SIGNALFD\fR" 4 |
531 | .IX Item "EVFLAG_SIGNALFD" |
531 | .IX Item "EVFLAG_SIGNALFD" |
532 | When this flag is specified, then libev will attempt to use the |
532 | When this flag is specified, then libev will attempt to use the |
533 | \&\fIsignalfd\fR \s-1API\s0 for it's \f(CW\*(C`ev_signal\*(C'\fR (and \f(CW\*(C`ev_child\*(C'\fR) watchers. This \s-1API\s0 |
533 | \&\fIsignalfd\fR \s-1API\s0 for its \f(CW\*(C`ev_signal\*(C'\fR (and \f(CW\*(C`ev_child\*(C'\fR) watchers. This \s-1API\s0 |
534 | delivers signals synchronously, which makes it both faster and might make |
534 | delivers signals synchronously, which makes it both faster and might make |
535 | it possible to get the queued signal data. It can also simplify signal |
535 | it possible to get the queued signal data. It can also simplify signal |
536 | handling with threads, as long as you properly block signals in your |
536 | handling with threads, as long as you properly block signals in your |
537 | threads that are not interested in handling them. |
537 | threads that are not interested in handling them. |
538 | .Sp |
538 | .Sp |
… | |
… | |
582 | epoll scales either O(1) or O(active_fds). |
582 | epoll scales either O(1) or O(active_fds). |
583 | .Sp |
583 | .Sp |
584 | The epoll mechanism deserves honorable mention as the most misdesigned |
584 | The epoll mechanism deserves honorable mention as the most misdesigned |
585 | of the more advanced event mechanisms: mere annoyances include silently |
585 | of the more advanced event mechanisms: mere annoyances include silently |
586 | dropping file descriptors, requiring a system call per change per file |
586 | dropping file descriptors, requiring a system call per change per file |
587 | descriptor (and unnecessary guessing of parameters), problems with dup and |
587 | descriptor (and unnecessary guessing of parameters), problems with dup, |
|
|
588 | returning before the timeout value, resulting in additional iterations |
|
|
589 | (and only giving 5ms accuracy while select on the same platform gives |
588 | so on. The biggest issue is fork races, however \- if a program forks then |
590 | 0.1ms) and so on. The biggest issue is fork races, however \- if a program |
589 | \&\fIboth\fR parent and child process have to recreate the epoll set, which can |
591 | forks then \fIboth\fR parent and child process have to recreate the epoll |
590 | take considerable time (one syscall per file descriptor) and is of course |
592 | set, which can take considerable time (one syscall per file descriptor) |
591 | hard to detect. |
593 | and is of course hard to detect. |
592 | .Sp |
594 | .Sp |
593 | Epoll is also notoriously buggy \- embedding epoll fds \fIshould\fR work, but |
595 | Epoll is also notoriously buggy \- embedding epoll fds \fIshould\fR work, but |
594 | of course \fIdoesn't\fR, and epoll just loves to report events for totally |
596 | of course \fIdoesn't\fR, and epoll just loves to report events for totally |
595 | \&\fIdifferent\fR file descriptors (even already closed ones, so one cannot |
597 | \&\fIdifferent\fR file descriptors (even already closed ones, so one cannot |
596 | even remove them from the set) than registered in the set (especially |
598 | even remove them from the set) than registered in the set (especially |
597 | on \s-1SMP\s0 systems). Libev tries to counter these spurious notifications by |
599 | on \s-1SMP\s0 systems). Libev tries to counter these spurious notifications by |
598 | employing an additional generation counter and comparing that against the |
600 | employing an additional generation counter and comparing that against the |
599 | events to filter out spurious ones, recreating the set when required. Last |
601 | events to filter out spurious ones, recreating the set when required. Last |
600 | not least, it also refuses to work with some file descriptors which work |
602 | not least, it also refuses to work with some file descriptors which work |
601 | perfectly fine with \f(CW\*(C`select\*(C'\fR (files, many character devices...). |
603 | perfectly fine with \f(CW\*(C`select\*(C'\fR (files, many character devices...). |
|
|
604 | .Sp |
|
|
605 | Epoll is truly the train wreck analog among event poll mechanisms. |
602 | .Sp |
606 | .Sp |
603 | While stopping, setting and starting an I/O watcher in the same iteration |
607 | While stopping, setting and starting an I/O watcher in the same iteration |
604 | will result in some caching, there is still a system call per such |
608 | will result in some caching, there is still a system call per such |
605 | incident (because the same \fIfile descriptor\fR could point to a different |
609 | incident (because the same \fIfile descriptor\fR could point to a different |
606 | \&\fIfile description\fR now), so its best to avoid that. Also, \f(CW\*(C`dup ()\*(C'\fR'ed |
610 | \&\fIfile description\fR now), so its best to avoid that. Also, \f(CW\*(C`dup ()\*(C'\fR'ed |
… | |
… | |
738 | This function is normally used on loop objects allocated by |
742 | This function is normally used on loop objects allocated by |
739 | \&\f(CW\*(C`ev_loop_new\*(C'\fR, but it can also be used on the default loop returned by |
743 | \&\f(CW\*(C`ev_loop_new\*(C'\fR, but it can also be used on the default loop returned by |
740 | \&\f(CW\*(C`ev_default_loop\*(C'\fR, in which case it is not thread-safe. |
744 | \&\f(CW\*(C`ev_default_loop\*(C'\fR, in which case it is not thread-safe. |
741 | .Sp |
745 | .Sp |
742 | Note that it is not advisable to call this function on the default loop |
746 | Note that it is not advisable to call this function on the default loop |
743 | except in the rare occasion where you really need to free it's resources. |
747 | except in the rare occasion where you really need to free its resources. |
744 | If you need dynamically allocated loops it is better to use \f(CW\*(C`ev_loop_new\*(C'\fR |
748 | If you need dynamically allocated loops it is better to use \f(CW\*(C`ev_loop_new\*(C'\fR |
745 | and \f(CW\*(C`ev_loop_destroy\*(C'\fR. |
749 | and \f(CW\*(C`ev_loop_destroy\*(C'\fR. |
746 | .IP "ev_loop_fork (loop)" 4 |
750 | .IP "ev_loop_fork (loop)" 4 |
747 | .IX Item "ev_loop_fork (loop)" |
751 | .IX Item "ev_loop_fork (loop)" |
748 | This function sets a flag that causes subsequent \f(CW\*(C`ev_run\*(C'\fR iterations to |
752 | This function sets a flag that causes subsequent \f(CW\*(C`ev_run\*(C'\fR iterations to |
… | |
… | |
2391 | .ie n .SS """ev_signal"" \- signal me when a signal gets signalled!" |
2395 | .ie n .SS """ev_signal"" \- signal me when a signal gets signalled!" |
2392 | .el .SS "\f(CWev_signal\fP \- signal me when a signal gets signalled!" |
2396 | .el .SS "\f(CWev_signal\fP \- signal me when a signal gets signalled!" |
2393 | .IX Subsection "ev_signal - signal me when a signal gets signalled!" |
2397 | .IX Subsection "ev_signal - signal me when a signal gets signalled!" |
2394 | Signal watchers will trigger an event when the process receives a specific |
2398 | Signal watchers will trigger an event when the process receives a specific |
2395 | signal one or more times. Even though signals are very asynchronous, libev |
2399 | signal one or more times. Even though signals are very asynchronous, libev |
2396 | will try it's best to deliver signals synchronously, i.e. as part of the |
2400 | will try its best to deliver signals synchronously, i.e. as part of the |
2397 | normal event processing, like any other event. |
2401 | normal event processing, like any other event. |
2398 | .PP |
2402 | .PP |
2399 | If you want signals to be delivered truly asynchronously, just use |
2403 | If you want signals to be delivered truly asynchronously, just use |
2400 | \&\f(CW\*(C`sigaction\*(C'\fR as you would do without libev and forget about sharing |
2404 | \&\f(CW\*(C`sigaction\*(C'\fR as you would do without libev and forget about sharing |
2401 | the signal. You can even use \f(CW\*(C`ev_async\*(C'\fR from a signal handler to |
2405 | the signal. You can even use \f(CW\*(C`ev_async\*(C'\fR from a signal handler to |