X-Git-Url: https://git.llucax.com/software/libev.git/blobdiff_plain/5c23f3932f8060a6541f2374689c96c92da21355..bcb5dd319c35f6c72b57f4153f08a9720eb9cd4e:/ev.pod diff --git a/ev.pod b/ev.pod index 6e39af3..36b927a 100644 --- a/ev.pod +++ b/ev.pod @@ -117,6 +117,12 @@ Returns the current time as libev would use it. Please note that the C function is usually faster and also often returns the timestamp you actually want to know. +=item ev_sleep (ev_tstamp interval) + +Sleep for the given interval: The current thread will be blocked until +either it is interrupted or the given time interval has passed. Basically +this is a subsecond-resolution C. + =item int ev_version_major () =item int ev_version_minor () @@ -302,15 +308,24 @@ environment variable. This is your standard select(2) backend. Not I standard, as libev tries to roll its own fd_set with no limits on the number of fds, but if that fails, expect a fairly low limit on the number of fds when -using this backend. It doesn't scale too well (O(highest_fd)), but its usually -the fastest backend for a low number of fds. +using this backend. It doesn't scale too well (O(highest_fd)), but its +usually the fastest backend for a low number of (low-numbered :) fds. + +To get good performance out of this backend you need a high amount of +parallelity (most of the file descriptors should be busy). If you are +writing a server, you should C in a loop to accept as many +connections as possible during one iteration. You might also want to have +a look at C to increase the amount of +readyness notifications you get per iteration. =item C (value 2, poll backend, available everywhere except on windows) -And this is your standard poll(2) backend. It's more complicated than -select, but handles sparse fds better and has no artificial limit on the -number of fds you can use (except it will slow down considerably with a -lot of inactive fds). It scales similarly to select, i.e. O(total_fds). +And this is your standard poll(2) backend. It's more complicated +than select, but handles sparse fds better and has no artificial +limit on the number of fds you can use (except it will slow down +considerably with a lot of inactive fds). It scales similarly to select, +i.e. O(total_fds). See the entry for C, above, for +performance tips. =item C (value 4, Linux) @@ -319,8 +334,8 @@ but it scales phenomenally better. While poll and select usually scale like O(total_fds) where n is the total number of fds (or the highest fd), epoll scales either O(1) or O(active_fds). The epoll design has a number of shortcomings, such as silently dropping events in some hard-to-detect -cases and rewuiring a syscall per fd change, no fork support and bad -support for dup: +cases and rewiring a syscall per fd change, no fork support and bad +support for dup. While stopping, setting and starting an I/O watcher in the same iteration will result in some caching, there is still a syscall per such incident @@ -332,27 +347,49 @@ Please note that epoll sometimes generates spurious notifications, so you need to use non-blocking I/O or other means to avoid blocking when no data (or space) is available. +Best performance from this backend is achieved by not unregistering all +watchers for a file descriptor until it has been closed, if possible, i.e. +keep at least one watcher active per fd at all times. + +While nominally embeddeble in other event loops, this feature is broken in +all kernel versions tested so far. + =item C (value 8, most BSD clones) Kqueue deserves special mention, as at the time of this writing, it -was broken on I BSDs (usually it doesn't work with anything but -sockets and pipes, except on Darwin, where of course it's completely -useless. On NetBSD, it seems to work for all the FD types I tested, so it -is used by default there). For this reason it's not being "autodetected" +was broken on all BSDs except NetBSD (usually it doesn't work reliably +with anything but sockets and pipes, except on Darwin, where of course +it's completely useless). For this reason it's not being "autodetected" unless you explicitly specify it explicitly in the flags (i.e. using C) or libev was compiled on a known-to-be-good (-enough) system like NetBSD. +You still can embed kqueue into a normal poll or select backend and use it +only for sockets (after having made sure that sockets work with kqueue on +the target platform). See C watchers for more info. + It scales in the same way as the epoll backend, but the interface to the -kernel is more efficient (which says nothing about its actual speed, -of course). While stopping, setting and starting an I/O watcher does -never cause an extra syscall as with epoll, it still adds up to two event -changes per incident, support for C is very bad and it drops fds -silently in similarly hard-to-detetc cases. +kernel is more efficient (which says nothing about its actual speed, of +course). While stopping, setting and starting an I/O watcher does never +cause an extra syscall as with C, it still adds up to +two event changes per incident, support for C is very bad and it +drops fds silently in similarly hard-to-detect cases. + +This backend usually performs well under most conditions. + +While nominally embeddable in other event loops, this doesn't work +everywhere, so you might need to test for this. And since it is broken +almost everywhere, you should only use it when you have a lot of sockets +(for which it usually works), by embedding it into another event loop +(e.g. C or C) and using it only for +sockets. =item C (value 16, Solaris 8) -This is not implemented yet (and might never be). +This is not implemented yet (and might never be, unless you send me an +implementation). According to reports, C only supports sockets +and is not embeddable, which would limit the usefulness of this backend +immensely. =item C (value 32, Solaris 10) @@ -363,12 +400,19 @@ Please note that solaris event ports can deliver a lot of spurious notifications, so you need to use non-blocking I/O or other means to avoid blocking when no data (or space) is available. +While this backend scales well, it requires one system call per active +file descriptor per loop iteration. For small and medium numbers of file +descriptors a "slow" C or C backend +might perform better. + =item C Try all backends (even potentially broken ones that wouldn't be tried with C). Since this is a mask, you can do stuff such as C. +It is definitely not recommended to use this flag. + =back If one or more of these are ored into the flags value, then only these @@ -571,6 +615,42 @@ Example: For some weird reason, unregister the above signal handler again. ev_ref (loop); ev_signal_stop (loop, &exitsig); +=item ev_set_io_collect_interval (loop, ev_tstamp interval) + +=item ev_set_timeout_collect_interval (loop, ev_tstamp interval) + +These advanced functions influence the time that libev will spend waiting +for events. Both are by default C<0>, meaning that libev will try to +invoke timer/periodic callbacks and I/O callbacks with minimum latency. + +Setting these to a higher value (the C I be >= C<0>) +allows libev to delay invocation of I/O and timer/periodic callbacks to +increase efficiency of loop iterations. + +The background is that sometimes your program runs just fast enough to +handle one (or very few) event(s) per loop iteration. While this makes +the program responsive, it also wastes a lot of CPU time to poll for new +events, especially with backends like C. + =item EV_USE_SELECT If undefined or defined to be C<1>, libev will compile in support for the