… | |
… | |
130 | .\} |
130 | .\} |
131 | .rm #[ #] #H #V #F C |
131 | .rm #[ #] #H #V #F C |
132 | .\" ======================================================================== |
132 | .\" ======================================================================== |
133 | .\" |
133 | .\" |
134 | .IX Title "EV 1" |
134 | .IX Title "EV 1" |
135 | .TH EV 1 "2008-03-13" "perl v5.10.0" "User Contributed Perl Documentation" |
135 | .TH EV 1 "2008-04-02" "perl v5.10.0" "User Contributed Perl Documentation" |
136 | .\" For nroff, turn off justification. Always turn off hyphenation; it makes |
136 | .\" For nroff, turn off justification. Always turn off hyphenation; it makes |
137 | .\" way too many mistakes in technical documents. |
137 | .\" way too many mistakes in technical documents. |
138 | .if n .ad l |
138 | .if n .ad l |
139 | .nh |
139 | .nh |
140 | .SH "NAME" |
140 | .SH "NAME" |
… | |
… | |
404 | flags. If that is troubling you, check \f(CW\*(C`ev_backend ()\*(C'\fR afterwards). |
404 | flags. If that is troubling you, check \f(CW\*(C`ev_backend ()\*(C'\fR afterwards). |
405 | .Sp |
405 | .Sp |
406 | If you don't know what event loop to use, use the one returned from this |
406 | If you don't know what event loop to use, use the one returned from this |
407 | function. |
407 | function. |
408 | .Sp |
408 | .Sp |
|
|
409 | Note that this function is \fInot\fR thread-safe, so if you want to use it |
|
|
410 | from multiple threads, you have to lock (note also that this is unlikely, |
|
|
411 | as loops cannot bes hared easily between threads anyway). |
|
|
412 | .Sp |
409 | The default loop is the only loop that can handle \f(CW\*(C`ev_signal\*(C'\fR and |
413 | The default loop is the only loop that can handle \f(CW\*(C`ev_signal\*(C'\fR and |
410 | \&\f(CW\*(C`ev_child\*(C'\fR watchers, and to do this, it always registers a handler |
414 | \&\f(CW\*(C`ev_child\*(C'\fR watchers, and to do this, it always registers a handler |
411 | for \f(CW\*(C`SIGCHLD\*(C'\fR. If this is a problem for your app you can either |
415 | for \f(CW\*(C`SIGCHLD\*(C'\fR. If this is a problem for your app you can either |
412 | create a dynamic loop with \f(CW\*(C`ev_loop_new\*(C'\fR that doesn't do that, or you |
416 | create a dynamic loop with \f(CW\*(C`ev_loop_new\*(C'\fR that doesn't do that, or you |
413 | can simply overwrite the \f(CW\*(C`SIGCHLD\*(C'\fR signal handler \fIafter\fR calling |
417 | can simply overwrite the \f(CW\*(C`SIGCHLD\*(C'\fR signal handler \fIafter\fR calling |
… | |
… | |
599 | .IX Item "struct ev_loop *ev_loop_new (unsigned int flags)" |
603 | .IX Item "struct ev_loop *ev_loop_new (unsigned int flags)" |
600 | Similar to \f(CW\*(C`ev_default_loop\*(C'\fR, but always creates a new event loop that is |
604 | Similar to \f(CW\*(C`ev_default_loop\*(C'\fR, but always creates a new event loop that is |
601 | always distinct from the default loop. Unlike the default loop, it cannot |
605 | always distinct from the default loop. Unlike the default loop, it cannot |
602 | handle signal and child watchers, and attempts to do so will be greeted by |
606 | handle signal and child watchers, and attempts to do so will be greeted by |
603 | undefined behaviour (or a failed assertion if assertions are enabled). |
607 | undefined behaviour (or a failed assertion if assertions are enabled). |
|
|
608 | .Sp |
|
|
609 | Note that this function \fIis\fR thread-safe, and the recommended way to use |
|
|
610 | libev with threads is indeed to create one loop per thread, and using the |
|
|
611 | default loop in the \*(L"main\*(R" or \*(L"initial\*(R" thread. |
604 | .Sp |
612 | .Sp |
605 | Example: Try to create a event loop that uses epoll and nothing else. |
613 | Example: Try to create a event loop that uses epoll and nothing else. |
606 | .Sp |
614 | .Sp |
607 | .Vb 3 |
615 | .Vb 3 |
608 | \& struct ev_loop *epoller = ev_loop_new (EVBACKEND_EPOLL | EVFLAG_NOENV); |
616 | \& struct ev_loop *epoller = ev_loop_new (EVBACKEND_EPOLL | EVFLAG_NOENV); |
… | |
… | |
1219 | To support fork in your programs, you either have to call |
1227 | To support fork in your programs, you either have to call |
1220 | \&\f(CW\*(C`ev_default_fork ()\*(C'\fR or \f(CW\*(C`ev_loop_fork ()\*(C'\fR after a fork in the child, |
1228 | \&\f(CW\*(C`ev_default_fork ()\*(C'\fR or \f(CW\*(C`ev_loop_fork ()\*(C'\fR after a fork in the child, |
1221 | enable \f(CW\*(C`EVFLAG_FORKCHECK\*(C'\fR, or resort to \f(CW\*(C`EVBACKEND_SELECT\*(C'\fR or |
1229 | enable \f(CW\*(C`EVFLAG_FORKCHECK\*(C'\fR, or resort to \f(CW\*(C`EVBACKEND_SELECT\*(C'\fR or |
1222 | \&\f(CW\*(C`EVBACKEND_POLL\*(C'\fR. |
1230 | \&\f(CW\*(C`EVBACKEND_POLL\*(C'\fR. |
1223 | .PP |
1231 | .PP |
|
|
1232 | \fIThe special problem of \s-1SIGPIPE\s0\fR |
|
|
1233 | .IX Subsection "The special problem of SIGPIPE" |
|
|
1234 | .PP |
|
|
1235 | While not really specific to libev, it is easy to forget about \s-1SIGPIPE:\s0 |
|
|
1236 | when reading from a pipe whose other end has been closed, your program |
|
|
1237 | gets send a \s-1SIGPIPE\s0, which, by default, aborts your program. For most |
|
|
1238 | programs this is sensible behaviour, for daemons, this is usually |
|
|
1239 | undesirable. |
|
|
1240 | .PP |
|
|
1241 | So when you encounter spurious, unexplained daemon exits, make sure you |
|
|
1242 | ignore \s-1SIGPIPE\s0 (and maybe make sure you log the exit status of your daemon |
|
|
1243 | somewhere, as that would have given you a big clue). |
|
|
1244 | .PP |
1224 | \fIWatcher-Specific Functions\fR |
1245 | \fIWatcher-Specific Functions\fR |
1225 | .IX Subsection "Watcher-Specific Functions" |
1246 | .IX Subsection "Watcher-Specific Functions" |
1226 | .IP "ev_io_init (ev_io *, callback, int fd, int events)" 4 |
1247 | .IP "ev_io_init (ev_io *, callback, int fd, int events)" 4 |
1227 | .IX Item "ev_io_init (ev_io *, callback, int fd, int events)" |
1248 | .IX Item "ev_io_init (ev_io *, callback, int fd, int events)" |
1228 | .PD 0 |
1249 | .PD 0 |
… | |
… | |
1736 | semantics of \f(CW\*(C`ev_stat\*(C'\fR watchers, which means that libev sometimes needs |
1757 | semantics of \f(CW\*(C`ev_stat\*(C'\fR watchers, which means that libev sometimes needs |
1737 | to fall back to regular polling again even with inotify, but changes are |
1758 | to fall back to regular polling again even with inotify, but changes are |
1738 | usually detected immediately, and if the file exists there will be no |
1759 | usually detected immediately, and if the file exists there will be no |
1739 | polling. |
1760 | polling. |
1740 | .PP |
1761 | .PP |
|
|
1762 | \fI\s-1ABI\s0 Issues (Largefile Support)\fR |
|
|
1763 | .IX Subsection "ABI Issues (Largefile Support)" |
|
|
1764 | .PP |
|
|
1765 | Libev by default (unless the user overrides this) uses the default |
|
|
1766 | compilation environment, which means that on systems with optionally |
|
|
1767 | disabled large file support, you get the 32 bit version of the stat |
|
|
1768 | structure. When using the library from programs that change the \s-1ABI\s0 to |
|
|
1769 | use 64 bit file offsets the programs will fail. In that case you have to |
|
|
1770 | compile libev with the same flags to get binary compatibility. This is |
|
|
1771 | obviously the case with any flags that change the \s-1ABI\s0, but the problem is |
|
|
1772 | most noticably with ev_stat and largefile support. |
|
|
1773 | .PP |
1741 | \fIInotify\fR |
1774 | \fIInotify\fR |
1742 | .IX Subsection "Inotify" |
1775 | .IX Subsection "Inotify" |
1743 | .PP |
1776 | .PP |
1744 | When \f(CW\*(C`inotify (7)\*(C'\fR support has been compiled into libev (generally only |
1777 | When \f(CW\*(C`inotify (7)\*(C'\fR support has been compiled into libev (generally only |
1745 | available on Linux) and present at runtime, it will be used to speed up |
1778 | available on Linux) and present at runtime, it will be used to speed up |
… | |
… | |
2383 | section below on what exactly this means). |
2416 | section below on what exactly this means). |
2384 | .Sp |
2417 | .Sp |
2385 | This call incurs the overhead of a syscall only once per loop iteration, |
2418 | This call incurs the overhead of a syscall only once per loop iteration, |
2386 | so while the overhead might be noticable, it doesn't apply to repeated |
2419 | so while the overhead might be noticable, it doesn't apply to repeated |
2387 | calls to \f(CW\*(C`ev_async_send\*(C'\fR. |
2420 | calls to \f(CW\*(C`ev_async_send\*(C'\fR. |
|
|
2421 | .IP "bool = ev_async_pending (ev_async *)" 4 |
|
|
2422 | .IX Item "bool = ev_async_pending (ev_async *)" |
|
|
2423 | Returns a non-zero value when \f(CW\*(C`ev_async_send\*(C'\fR has been called on the |
|
|
2424 | watcher but the event has not yet been processed (or even noted) by the |
|
|
2425 | event loop. |
|
|
2426 | .Sp |
|
|
2427 | \&\f(CW\*(C`ev_async_send\*(C'\fR sets a flag in the watcher and wakes up the loop. When |
|
|
2428 | the loop iterates next and checks for the watcher to have become active, |
|
|
2429 | it will reset the flag again. \f(CW\*(C`ev_async_pending\*(C'\fR can be used to very |
|
|
2430 | quickly check wether invoking the loop might be a good idea. |
|
|
2431 | .Sp |
|
|
2432 | Not that this does \fInot\fR check wether the watcher itself is pending, only |
|
|
2433 | wether it has been requested to make this watcher pending. |
2388 | .SH "OTHER FUNCTIONS" |
2434 | .SH "OTHER FUNCTIONS" |
2389 | .IX Header "OTHER FUNCTIONS" |
2435 | .IX Header "OTHER FUNCTIONS" |
2390 | There are some other functions of possible interest. Described. Here. Now. |
2436 | There are some other functions of possible interest. Described. Here. Now. |
2391 | .IP "ev_once (loop, int fd, int events, ev_tstamp timeout, callback)" 4 |
2437 | .IP "ev_once (loop, int fd, int events, ev_tstamp timeout, callback)" 4 |
2392 | .IX Item "ev_once (loop, int fd, int events, ev_tstamp timeout, callback)" |
2438 | .IX Item "ev_once (loop, int fd, int events, ev_tstamp timeout, callback)" |
… | |
… | |
3223 | .IX Header "AUTHOR" |
3269 | .IX Header "AUTHOR" |
3224 | Marc Lehmann <libev@schmorp.de>. |
3270 | Marc Lehmann <libev@schmorp.de>. |
3225 | .SH "POD ERRORS" |
3271 | .SH "POD ERRORS" |
3226 | .IX Header "POD ERRORS" |
3272 | .IX Header "POD ERRORS" |
3227 | Hey! \fBThe above document had some coding errors, which are explained below:\fR |
3273 | Hey! \fBThe above document had some coding errors, which are explained below:\fR |
3228 | .IP "Around line 2951:" 4 |
3274 | .IP "Around line 2996:" 4 |
3229 | .IX Item "Around line 2951:" |
3275 | .IX Item "Around line 2996:" |
3230 | You forgot a '=back' before '=head2' |
3276 | You forgot a '=back' before '=head2' |