ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/libev/ev.pod
(Generate patch)

Comparing libev/ev.pod (file contents):
Revision 1.264 by root, Wed Aug 19 23:44:51 2009 UTC vs.
Revision 1.272 by root, Tue Nov 24 06:39:28 2009 UTC

… …
370When this flag is specified, then libev will not attempt to use the 370When this flag is specified, then libev will not attempt to use the
371I<inotify> API for it's C<ev_stat> watchers. Apart from debugging and 371I<inotify> API for it's C<ev_stat> watchers. Apart from debugging and
372testing, this flag can be useful to conserve inotify file descriptors, as 372testing, this flag can be useful to conserve inotify file descriptors, as
373otherwise each loop using C<ev_stat> watchers consumes one inotify handle. 373otherwise each loop using C<ev_stat> watchers consumes one inotify handle.
374 374
375=item C<EVFLAG_NOSIGNALFD> 375=item C<EVFLAG_NOSIGFD>
376 376
377When this flag is specified, then libev will not attempt to use the 377When this flag is specified, then libev will not attempt to use the
378I<signalfd> API for it's C<ev_signal> (and C<ev_child>) watchers. This is 378I<signalfd> API for it's C<ev_signal> (and C<ev_child>) watchers. This is
379probably only useful to work around any bugs in libev. Consequently, this 379probably only useful to work around any bugs in libev. Consequently, this
380flag might go away once the signalfd functionality is considered stable, 380flag might go away once the signalfd functionality is considered stable,
… …
410 410
411This backend maps C<EV_READ> to C<POLLIN | POLLERR | POLLHUP>, and 411This backend maps C<EV_READ> to C<POLLIN | POLLERR | POLLHUP>, and
412C<EV_WRITE> to C<POLLOUT | POLLERR | POLLHUP>. 412C<EV_WRITE> to C<POLLOUT | POLLERR | POLLHUP>.
413 413
414=item C<EVBACKEND_EPOLL> (value 4, Linux) 414=item C<EVBACKEND_EPOLL> (value 4, Linux)
415
416Use the linux-specific epoll(7) interface (for both pre- and post-2.6.9
417kernels).
415 418
416For few fds, this backend is a bit little slower than poll and select, 419For few fds, this backend is a bit little slower than poll and select,
417but it scales phenomenally better. While poll and select usually scale 420but it scales phenomenally better. While poll and select usually scale
418like O(total_fds) where n is the total number of fds (or the highest fd), 421like O(total_fds) where n is the total number of fds (or the highest fd),
419epoll scales either O(1) or O(active_fds). 422epoll scales either O(1) or O(active_fds).
… …
590as signal and child watchers) would need to be stopped manually. 593as signal and child watchers) would need to be stopped manually.
591 594
592In general it is not advisable to call this function except in the 595In general it is not advisable to call this function except in the
593rare occasion where you really need to free e.g. the signal handling 596rare occasion where you really need to free e.g. the signal handling
594pipe fds. If you need dynamically allocated loops it is better to use 597pipe fds. If you need dynamically allocated loops it is better to use
595C<ev_loop_new> and C<ev_loop_destroy>). 598C<ev_loop_new> and C<ev_loop_destroy>.
596 599
597=item ev_loop_destroy (loop) 600=item ev_loop_destroy (loop)
598 601
599Like C<ev_default_destroy>, but destroys an event loop created by an 602Like C<ev_default_destroy>, but destroys an event loop created by an
600earlier call to C<ev_loop_new>. 603earlier call to C<ev_loop_new>.
… …
704event loop time (see C<ev_now_update>). 707event loop time (see C<ev_now_update>).
705 708
706=item ev_loop (loop, int flags) 709=item ev_loop (loop, int flags)
707 710
708Finally, this is it, the event handler. This function usually is called 711Finally, this is it, the event handler. This function usually is called
709after you initialised all your watchers and you want to start handling 712after you have initialised all your watchers and you want to start
710events. 713handling events.
711 714
712If the flags argument is specified as C<0>, it will not return until 715If the flags argument is specified as C<0>, it will not return until
713either no event watchers are active anymore or C<ev_unloop> was called. 716either no event watchers are active anymore or C<ev_unloop> was called.
714 717
715Please note that an explicit C<ev_unloop> is usually better than 718Please note that an explicit C<ev_unloop> is usually better than
… …
2108 2111
2109When the first watcher gets started will libev actually register something 2112When the first watcher gets started will libev actually register something
2110with the kernel (thus it coexists with your own signal handlers as long as 2113with the kernel (thus it coexists with your own signal handlers as long as
2111you don't register any with libev for the same signal). 2114you don't register any with libev for the same signal).
2112 2115
2113Both the signal mask state (C<sigprocmask>) and the signal handler state
2114(C<sigaction>) are unspecified after starting a signal watcher (and after
2115sotpping it again), that is, libev might or might not block the signal,
2116and might or might not set or restore the installed signal handler.
2117
2118If possible and supported, libev will install its handlers with 2116If possible and supported, libev will install its handlers with
2119C<SA_RESTART> (or equivalent) behaviour enabled, so system calls should 2117C<SA_RESTART> (or equivalent) behaviour enabled, so system calls should
2120not be unduly interrupted. If you have a problem with system calls getting 2118not be unduly interrupted. If you have a problem with system calls getting
2121interrupted by signals you can block all signals in an C<ev_check> watcher 2119interrupted by signals you can block all signals in an C<ev_check> watcher
2122and unblock them in an C<ev_prepare> watcher. 2120and unblock them in an C<ev_prepare> watcher.
2121
2122=head3 The special problem of inheritance over execve
2123
2124Both the signal mask (C<sigprocmask>) and the signal disposition
2125(C<sigaction>) are unspecified after starting a signal watcher (and after
2126stopping it again), that is, libev might or might not block the signal,
2127and might or might not set or restore the installed signal handler.
2128
2129While this does not matter for the signal disposition (libev never
2130sets signals to C<SIG_IGN>, so handlers will be reset to C<SIG_DFL> on
2131C<execve>), this matters for the signal mask: many programs do not expect
2132certain signals to be blocked.
2133
2134This means that before calling C<exec> (from the child) you should reset
2135the signal mask to whatever "default" you expect (all clear is a good
2136choice usually).
2137
2138The simplest way to ensure that the signal mask is reset in the child is
2139to install a fork handler with C<pthread_atfork> that resets it. That will
2140catch fork calls done by libraries (such as the libc) as well.
2141
2142In current versions of libev, you can also ensure that the signal mask is
2143not blocking any signals (except temporarily, so thread users watch out)
2144by specifying the C<EVFLAG_NOSIGFD> when creating the event loop. This
2145is not guaranteed for future versions, however.
2123 2146
2124=head3 Watcher-Specific Functions and Data Members 2147=head3 Watcher-Specific Functions and Data Members
2125 2148
2126=over 4 2149=over 4
2127 2150

Diff Legend

– Removed lines
+ Added lines
< Changed lines
> Changed lines