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

Comparing libev/ev.3 (file contents):
Revision 1.62 by root, Sun Mar 16 16:38:23 2008 UTC vs.
Revision 1.63 by root, Wed Apr 2 15:23:11 2008 UTC

… …
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"
… …
404flags. If that is troubling you, check \f(CW\*(C`ev_backend ()\*(C'\fR afterwards). 404flags. If that is troubling you, check \f(CW\*(C`ev_backend ()\*(C'\fR afterwards).
405.Sp 405.Sp
406If you don't know what event loop to use, use the one returned from this 406If you don't know what event loop to use, use the one returned from this
407function. 407function.
408.Sp 408.Sp
409Note that this function is \fInot\fR thread-safe, so if you want to use it
410from multiple threads, you have to lock (note also that this is unlikely,
411as loops cannot bes hared easily between threads anyway).
412.Sp
409The default loop is the only loop that can handle \f(CW\*(C`ev_signal\*(C'\fR and 413The 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
411for \f(CW\*(C`SIGCHLD\*(C'\fR. If this is a problem for your app you can either 415for \f(CW\*(C`SIGCHLD\*(C'\fR. If this is a problem for your app you can either
412create a dynamic loop with \f(CW\*(C`ev_loop_new\*(C'\fR that doesn't do that, or you 416create a dynamic loop with \f(CW\*(C`ev_loop_new\*(C'\fR that doesn't do that, or you
413can simply overwrite the \f(CW\*(C`SIGCHLD\*(C'\fR signal handler \fIafter\fR calling 417can 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)"
600Similar to \f(CW\*(C`ev_default_loop\*(C'\fR, but always creates a new event loop that is 604Similar to \f(CW\*(C`ev_default_loop\*(C'\fR, but always creates a new event loop that is
601always distinct from the default loop. Unlike the default loop, it cannot 605always distinct from the default loop. Unlike the default loop, it cannot
602handle signal and child watchers, and attempts to do so will be greeted by 606handle signal and child watchers, and attempts to do so will be greeted by
603undefined behaviour (or a failed assertion if assertions are enabled). 607undefined behaviour (or a failed assertion if assertions are enabled).
608.Sp
609Note that this function \fIis\fR thread-safe, and the recommended way to use
610libev with threads is indeed to create one loop per thread, and using the
611default loop in the \*(L"main\*(R" or \*(L"initial\*(R" thread.
604.Sp 612.Sp
605Example: Try to create a event loop that uses epoll and nothing else. 613Example: 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);
… …
1219To support fork in your programs, you either have to call 1227To 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,
1221enable \f(CW\*(C`EVFLAG_FORKCHECK\*(C'\fR, or resort to \f(CW\*(C`EVBACKEND_SELECT\*(C'\fR or 1229enable \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
1235While not really specific to libev, it is easy to forget about \s-1SIGPIPE:\s0
1236when reading from a pipe whose other end has been closed, your program
1237gets send a \s-1SIGPIPE\s0, which, by default, aborts your program. For most
1238programs this is sensible behaviour, for daemons, this is usually
1239undesirable.
1240.PP
1241So when you encounter spurious, unexplained daemon exits, make sure you
1242ignore \s-1SIGPIPE\s0 (and maybe make sure you log the exit status of your daemon
1243somewhere, 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
… …
1736semantics of \f(CW\*(C`ev_stat\*(C'\fR watchers, which means that libev sometimes needs 1757semantics of \f(CW\*(C`ev_stat\*(C'\fR watchers, which means that libev sometimes needs
1737to fall back to regular polling again even with inotify, but changes are 1758to fall back to regular polling again even with inotify, but changes are
1738usually detected immediately, and if the file exists there will be no 1759usually detected immediately, and if the file exists there will be no
1739polling. 1760polling.
1740.PP 1761.PP
1762\fI\s-1ABI\s0 Issues (Largefile Support)\fR
1763.IX Subsection "ABI Issues (Largefile Support)"
1764.PP
1765Libev by default (unless the user overrides this) uses the default
1766compilation environment, which means that on systems with optionally
1767disabled large file support, you get the 32 bit version of the stat
1768structure. When using the library from programs that change the \s-1ABI\s0 to
1769use 64 bit file offsets the programs will fail. In that case you have to
1770compile libev with the same flags to get binary compatibility. This is
1771obviously the case with any flags that change the \s-1ABI\s0, but the problem is
1772most 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
1744When \f(CW\*(C`inotify (7)\*(C'\fR support has been compiled into libev (generally only 1777When \f(CW\*(C`inotify (7)\*(C'\fR support has been compiled into libev (generally only
1745available on Linux) and present at runtime, it will be used to speed up 1778available on Linux) and present at runtime, it will be used to speed up
… …
2383section below on what exactly this means). 2416section below on what exactly this means).
2384.Sp 2417.Sp
2385This call incurs the overhead of a syscall only once per loop iteration, 2418This call incurs the overhead of a syscall only once per loop iteration,
2386so while the overhead might be noticable, it doesn't apply to repeated 2419so while the overhead might be noticable, it doesn't apply to repeated
2387calls to \f(CW\*(C`ev_async_send\*(C'\fR. 2420calls 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 *)"
2423Returns a non-zero value when \f(CW\*(C`ev_async_send\*(C'\fR has been called on the
2424watcher but the event has not yet been processed (or even noted) by the
2425event loop.
2426.Sp
2427\&\f(CW\*(C`ev_async_send\*(C'\fR sets a flag in the watcher and wakes up the loop. When
2428the loop iterates next and checks for the watcher to have become active,
2429it will reset the flag again. \f(CW\*(C`ev_async_pending\*(C'\fR can be used to very
2430quickly check wether invoking the loop might be a good idea.
2431.Sp
2432Not that this does \fInot\fR check wether the watcher itself is pending, only
2433wether 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"
2390There are some other functions of possible interest. Described. Here. Now. 2436There 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"
3224Marc Lehmann <libev@schmorp.de>. 3270Marc Lehmann <libev@schmorp.de>.
3225.SH "POD ERRORS" 3271.SH "POD ERRORS"
3226.IX Header "POD ERRORS" 3272.IX Header "POD ERRORS"
3227Hey! \fBThe above document had some coding errors, which are explained below:\fR 3273Hey! \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:"
3230You forgot a '=back' before '=head2' 3276You forgot a '=back' before '=head2'

Diff Legend

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