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

Comparing libev/ev.pod (file contents):
Revision 1.263 by root, Mon Jul 27 01:10:17 2009 UTC vs.
Revision 1.268 by root, Sat Aug 29 08:15:11 2009 UTC

… …
704event loop time (see C<ev_now_update>). 704event loop time (see C<ev_now_update>).
705 705
706=item ev_loop (loop, int flags) 706=item ev_loop (loop, int flags)
707 707
708Finally, this is it, the event handler. This function usually is called 708Finally, this is it, the event handler. This function usually is called
709after you initialised all your watchers and you want to start handling 709after you have initialised all your watchers and you want to start
710events. 710handling events.
711 711
712If the flags argument is specified as C<0>, it will not return until 712If 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. 713either no event watchers are active anymore or C<ev_unloop> was called.
714 714
715Please note that an explicit C<ev_unloop> is usually better than 715Please note that an explicit C<ev_unloop> is usually better than
… …
2108 2108
2109When the first watcher gets started will libev actually register something 2109When the first watcher gets started will libev actually register something
2110with the kernel (thus it coexists with your own signal handlers as long as 2110with the kernel (thus it coexists with your own signal handlers as long as
2111you don't register any with libev for the same signal). 2111you don't register any with libev for the same signal).
2112 2112
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 2113If possible and supported, libev will install its handlers with
2119C<SA_RESTART> (or equivalent) behaviour enabled, so system calls should 2114C<SA_RESTART> (or equivalent) behaviour enabled, so system calls should
2120not be unduly interrupted. If you have a problem with system calls getting 2115not 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 2116interrupted by signals you can block all signals in an C<ev_check> watcher
2122and unblock them in an C<ev_prepare> watcher. 2117and unblock them in an C<ev_prepare> watcher.
2118
2119=head3 The special problem of inheritance over execve
2120
2121Both the signal mask (C<sigprocmask>) and the signal disposition
2122(C<sigaction>) are unspecified after starting a signal watcher (and after
2123stopping it again), that is, libev might or might not block the signal,
2124and might or might not set or restore the installed signal handler.
2125
2126While this does not matter for the signal disposition (libev never
2127sets signals to C<SIG_IGN>, so handlers will be reset to C<SIG_DFL> on
2128C<execve>), this matters for the signal mask: many programs do not expect
2129certain signals to be blocked.
2130
2131This means that before calling C<exec> (from the child) you should reset
2132the signal mask to whatever "default" you expect (all clear is a good
2133choice usually).
2134
2135The simplest way to ensure that the signal mask is reset in the child is
2136to install a fork handler with C<pthread_atfork> that resets it. That will
2137catch fork calls done by libraries (such as the libc) as well.
2138
2139In current versions of libev, you can also ensure that the signal mask is
2140not blocking any signals (except temporarily, so thread users watch out)
2141by specifying the C<EVFLAG_NOSIGNALFD> when creating the event loop. This
2142is not guaranteed for future versions, however.
2123 2143
2124=head3 Watcher-Specific Functions and Data Members 2144=head3 Watcher-Specific Functions and Data Members
2125 2145
2126=over 4 2146=over 4
2127 2147
… …
3663be used is the winsock select). This means that it will call 3683be used is the winsock select). This means that it will call
3664C<_get_osfhandle> on the fd to convert it to an OS handle. Otherwise, 3684C<_get_osfhandle> on the fd to convert it to an OS handle. Otherwise,
3665it is assumed that all these functions actually work on fds, even 3685it is assumed that all these functions actually work on fds, even
3666on win32. Should not be defined on non-win32 platforms. 3686on win32. Should not be defined on non-win32 platforms.
3667 3687
3668=item EV_FD_TO_WIN32_HANDLE 3688=item EV_FD_TO_WIN32_HANDLE(fd)
3669 3689
3670If C<EV_SELECT_IS_WINSOCKET> is enabled, then libev needs a way to map 3690If C<EV_SELECT_IS_WINSOCKET> is enabled, then libev needs a way to map
3671file descriptors to socket handles. When not defining this symbol (the 3691file descriptors to socket handles. When not defining this symbol (the
3672default), then libev will call C<_get_osfhandle>, which is usually 3692default), then libev will call C<_get_osfhandle>, which is usually
3673correct. In some cases, programs use their own file descriptor management, 3693correct. In some cases, programs use their own file descriptor management,
3674in which case they can provide this function to map fds to socket handles. 3694in which case they can provide this function to map fds to socket handles.
3695
3696=item EV_WIN32_HANDLE_TO_FD(handle)
3697
3698If C<EV_SELECT_IS_WINSOCKET> then libev maps handles to file descriptors
3699using the standard C<_open_osfhandle> function. For programs implementing
3700their own fd to handle mapping, overwriting this function makes it easier
3701to do so. This can be done by defining this macro to an appropriate value.
3702
3703=item EV_WIN32_CLOSE_FD(fd)
3704
3705If programs implement their own fd to handle mapping on win32, then this
3706macro can be used to override the C<close> function, useful to unregister
3707file descriptors again. Note that the replacement function has to close
3708the underlying OS handle.
3675 3709
3676=item EV_USE_POLL 3710=item EV_USE_POLL
3677 3711
3678If defined to be C<1>, libev will compile in support for the C<poll>(2) 3712If defined to be C<1>, libev will compile in support for the C<poll>(2)
3679backend. Otherwise it will be enabled on non-win32 platforms. It 3713backend. Otherwise it will be enabled on non-win32 platforms. It

Diff Legend

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