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

Comparing libev/ev.pod (file contents):
Revision 1.201 by root, Fri Oct 24 08:26:04 2008 UTC vs.
Revision 1.204 by root, Mon Oct 27 11:08:29 2008 UTC

… …
389epoll scales either O(1) or O(active_fds). The epoll design has a number 389epoll scales either O(1) or O(active_fds). The epoll design has a number
390of shortcomings, such as silently dropping events in some hard-to-detect 390of shortcomings, such as silently dropping events in some hard-to-detect
391cases and requiring a system call per fd change, no fork support and bad 391cases and requiring a system call per fd change, no fork support and bad
392support for dup. 392support for dup.
393 393
394Epoll is also notoriously buggy - embedding epoll fds should work, but
395of course doesn't, and epoll just loves to report events for totally
396I<different> file descriptors (even already closed ones) than registered
397in the set (especially on SMP systems). Libev tries to counter these
398spurious notifications by employing an additional generation counter and
399comparing that against the events to filter out spurious ones.
400
394While stopping, setting and starting an I/O watcher in the same iteration 401While 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 402will 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 403(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 404best to avoid that. Also, C<dup ()>'ed file descriptors might not work
398very well if you register events for both fds. 405very well if you register events for both fds.
399
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 406
404Best performance from this backend is achieved by not unregistering all 407Best performance from this backend is achieved by not unregistering all
405watchers for a file descriptor until it has been closed, if possible, 408watchers 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 409i.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 410starting a watcher (without re-setting it) also usually doesn't cause
… …
531responsibility to either stop all watchers cleanly yourself I<before> 534responsibility to either stop all watchers cleanly yourself I<before>
532calling this function, or cope with the fact afterwards (which is usually 535calling 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 536the easiest thing, you can just ignore the watchers and/or C<free ()> them
534for example). 537for example).
535 538
536Note that certain global state, such as signal state, will not be freed by 539Note that certain global state, such as signal state (and installed signal
537this function, and related watchers (such as signal and child watchers) 540handlers), will not be freed by this function, and related watchers (such
538would need to be stopped manually. 541as signal and child watchers) would need to be stopped manually.
539 542
540In general it is not advisable to call this function except in the 543In 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 544rare 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 545pipe fds. If you need dynamically allocated loops it is better to use
543C<ev_loop_new> and C<ev_loop_destroy>). 546C<ev_loop_new> and C<ev_loop_destroy>).
… …
1043The default priority used by watchers when no priority has been set is 1046The 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 :). 1047always C<0>, which is supposed to not be too high and not be too low :).
1045 1048
1046Setting a priority outside the range of C<EV_MINPRI> to C<EV_MAXPRI> is 1049Setting 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 1050fine, 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. 1051or might not have been clamped to the valid range.
1049 1052
1050=item ev_invoke (loop, ev_TYPE *watcher, int revents) 1053=item ev_invoke (loop, ev_TYPE *watcher, int revents)
1051 1054
1052Invoke the C<watcher> with the given C<loop> and C<revents>. Neither 1055Invoke 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 1056C<loop> nor C<revents> need to be valid as long as the watcher callback

Diff Legend

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