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

Comparing libev/ev.pod (file contents):
Revision 1.200 by root, Thu Oct 23 07:33:45 2008 UTC vs.
Revision 1.206 by root, Tue Oct 28 12:31:38 2008 UTC

… …
384=item C<EVBACKEND_EPOLL> (value 4, Linux) 384=item C<EVBACKEND_EPOLL> (value 4, Linux)
385 385
386For few fds, this backend is a bit little slower than poll and select, 386For few fds, this backend is a bit little slower than poll and select,
387but it scales phenomenally better. While poll and select usually scale 387but it scales phenomenally better. While poll and select usually scale
388like O(total_fds) where n is the total number of fds (or the highest fd), 388like O(total_fds) where n is the total number of fds (or the highest fd),
389epoll scales either O(1) or O(active_fds). The epoll design has a number 389epoll scales either O(1) or O(active_fds).
390of shortcomings, such as silently dropping events in some hard-to-detect 390
391cases and requiring a system call per fd change, no fork support and bad 391The epoll syscalls are the most misdesigned of the more advanced event
392support for dup. 392mechanisms: problems include silently dropping fds, requiring a system
393call per change per fd (and unnecessary guessing of parameters), problems
394with dup and so on. The biggest issue is fork races, however - if a
395program forks then I<both> parent and child process have to recreate the
396epoll set, which can take considerable time (one syscall per fd) and is of
397course hard to detect.
398
399Epoll is also notoriously buggy - embedding epoll fds should work, but
400of course doesn't, and epoll just loves to report events for totally
401I<different> file descriptors (even already closed ones, so one cannot
402even remove them from the set) than registered in the set (especially
403on SMP systems). Libev tries to counter these spurious notifications by
404employing an additional generation counter and comparing that against the
405events to filter out spurious ones.
393 406
394While stopping, setting and starting an I/O watcher in the same iteration 407While stopping, setting and starting an I/O watcher in the same iteration
395will result in some caching, there is still a system call per such incident 408will result in some caching, there is still a system call per such incident
396(because the fd could point to a different file description now), so its 409(because the fd could point to a different file description now), so its
397best to avoid that. Also, C<dup ()>'ed file descriptors might not work 410best to avoid that. Also, C<dup ()>'ed file descriptors might not work
398very well if you register events for both fds. 411very well if you register events for both fds.
399 412
400Please note that epoll sometimes generates spurious notifications, so you
401need to use non-blocking I/O or other means to avoid blocking when no data
402(or space) is available.
403
404Best performance from this backend is achieved by not unregistering all 413Best performance from this backend is achieved by not unregistering all
405watchers for a file descriptor until it has been closed, if possible, 414watchers for a file descriptor until it has been closed, if possible,
406i.e. keep at least one watcher active per fd at all times. Stopping and 415i.e. keep at least one watcher active per fd at all times. Stopping and
407starting a watcher (without re-setting it) also usually doesn't cause 416starting a watcher (without re-setting it) also usually doesn't cause
408extra overhead. 417extra overhead. A fork can both result in spurious notifications as well
418as in libev having to destroy and recreate the epoll object, which can
419take considerable time and thus should be avoided.
409 420
410While nominally embeddable in other event loops, this feature is broken in 421While nominally embeddable in other event loops, this feature is broken in
411all kernel versions tested so far. 422all kernel versions tested so far.
412 423
413This backend maps C<EV_READ> and C<EV_WRITE> in the same way as 424This backend maps C<EV_READ> and C<EV_WRITE> in the same way as
… …
428 439
429It scales in the same way as the epoll backend, but the interface to the 440It scales in the same way as the epoll backend, but the interface to the
430kernel is more efficient (which says nothing about its actual speed, of 441kernel is more efficient (which says nothing about its actual speed, of
431course). While stopping, setting and starting an I/O watcher does never 442course). While stopping, setting and starting an I/O watcher does never
432cause an extra system call as with C<EVBACKEND_EPOLL>, it still adds up to 443cause an extra system call as with C<EVBACKEND_EPOLL>, it still adds up to
433two event changes per incident. Support for C<fork ()> is very bad and it 444two event changes per incident. Support for C<fork ()> is very bad (but
434drops fds silently in similarly hard-to-detect cases. 445sane, unlike epoll) and it drops fds silently in similarly hard-to-detect
446cases
435 447
436This backend usually performs well under most conditions. 448This backend usually performs well under most conditions.
437 449
438While nominally embeddable in other event loops, this doesn't work 450While nominally embeddable in other event loops, this doesn't work
439everywhere, so you might need to test for this. And since it is broken 451everywhere, so you might need to test for this. And since it is broken
… …
468might perform better. 480might perform better.
469 481
470On the positive side, with the exception of the spurious readiness 482On the positive side, with the exception of the spurious readiness
471notifications, this backend actually performed fully to specification 483notifications, this backend actually performed fully to specification
472in all tests and is fully embeddable, which is a rare feat among the 484in all tests and is fully embeddable, which is a rare feat among the
473OS-specific backends. 485OS-specific backends (I vastly prefer correctness over speed hacks).
474 486
475This backend maps C<EV_READ> and C<EV_WRITE> in the same way as 487This backend maps C<EV_READ> and C<EV_WRITE> in the same way as
476C<EVBACKEND_POLL>. 488C<EVBACKEND_POLL>.
477 489
478=item C<EVBACKEND_ALL> 490=item C<EVBACKEND_ALL>
… …
531responsibility to either stop all watchers cleanly yourself I<before> 543responsibility to either stop all watchers cleanly yourself I<before>
532calling this function, or cope with the fact afterwards (which is usually 544calling this function, or cope with the fact afterwards (which is usually
533the easiest thing, you can just ignore the watchers and/or C<free ()> them 545the easiest thing, you can just ignore the watchers and/or C<free ()> them
534for example). 546for example).
535 547
536Note that certain global state, such as signal state, will not be freed by 548Note that certain global state, such as signal state (and installed signal
537this function, and related watchers (such as signal and child watchers) 549handlers), will not be freed by this function, and related watchers (such
538would need to be stopped manually. 550as signal and child watchers) would need to be stopped manually.
539 551
540In general it is not advisable to call this function except in the 552In general it is not advisable to call this function except in the
541rare occasion where you really need to free e.g. the signal handling 553rare occasion where you really need to free e.g. the signal handling
542pipe fds. If you need dynamically allocated loops it is better to use 554pipe fds. If you need dynamically allocated loops it is better to use
543C<ev_loop_new> and C<ev_loop_destroy>). 555C<ev_loop_new> and C<ev_loop_destroy>).
… …
1043The default priority used by watchers when no priority has been set is 1055The default priority used by watchers when no priority has been set is
1044always C<0>, which is supposed to not be too high and not be too low :). 1056always C<0>, which is supposed to not be too high and not be too low :).
1045 1057
1046Setting a priority outside the range of C<EV_MINPRI> to C<EV_MAXPRI> is 1058Setting a priority outside the range of C<EV_MINPRI> to C<EV_MAXPRI> is
1047fine, as long as you do not mind that the priority value you query might 1059fine, as long as you do not mind that the priority value you query might
1048or might not have been adjusted to be within valid range. 1060or might not have been clamped to the valid range.
1049 1061
1050=item ev_invoke (loop, ev_TYPE *watcher, int revents) 1062=item ev_invoke (loop, ev_TYPE *watcher, int revents)
1051 1063
1052Invoke the C<watcher> with the given C<loop> and C<revents>. Neither 1064Invoke the C<watcher> with the given C<loop> and C<revents>. Neither
1053C<loop> nor C<revents> need to be valid as long as the watcher callback 1065C<loop> nor C<revents> need to be valid as long as the watcher callback
… …
2958=item D 2970=item D
2959 2971
2960Leandro Lucarella has written a D language binding (F<ev.d>) for libev, to 2972Leandro Lucarella has written a D language binding (F<ev.d>) for libev, to
2961be found at L<http://proj.llucax.com.ar/wiki/evd>. 2973be found at L<http://proj.llucax.com.ar/wiki/evd>.
2962 2974
2975=item Ocaml
2976
2977Erkki Seppala has written Ocaml bindings for libev, to be found at
2978L<http://modeemi.cs.tut.fi/~flux/software/ocaml-ev/>.
2979
2963=back 2980=back
2964 2981
2965 2982
2966=head1 MACRO MAGIC 2983=head1 MACRO MAGIC
2967 2984

Diff Legend

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