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

Comparing libev/ev.pod (file contents):
Revision 1.205 by root, Mon Oct 27 12:20:32 2008 UTC vs.
Revision 1.207 by root, Tue Oct 28 14:13:52 2008 UTC

… …
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). 389epoll scales either O(1) or O(active_fds).
390 390
391The epoll syscalls are the most misdesigned of the more advanced 391The epoll syscalls are the most misdesigned of the more advanced event
392event mechanisms: probelsm include silently dropping events in some 392mechanisms: problems include silently dropping fds, requiring a system
393hard-to-detect cases, requiring a system call per fd change, no fork 393call per change per fd (and unnecessary guessing of parameters), problems
394support, problems with dup and so on. 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.
395 398
396Epoll is also notoriously buggy - embedding epoll fds should work, but 399Epoll is also notoriously buggy - embedding epoll fds should work, but
397of course doesn't, and epoll just loves to report events for totally 400of course doesn't, and epoll just loves to report events for totally
398I<different> file descriptors (even already closed ones, so one cannot 401I<different> file descriptors (even already closed ones, so one cannot
399even remove them from the set) than registered in the set (especially 402even remove them from the set) than registered in the set (especially
… …
409 412
410Best performance from this backend is achieved by not unregistering all 413Best performance from this backend is achieved by not unregistering all
411watchers for a file descriptor until it has been closed, if possible, 414watchers for a file descriptor until it has been closed, if possible,
412i.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
413starting a watcher (without re-setting it) also usually doesn't cause 416starting a watcher (without re-setting it) also usually doesn't cause
414extra 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.
415 420
416While nominally embeddable in other event loops, this feature is broken in 421While nominally embeddable in other event loops, this feature is broken in
417all kernel versions tested so far. 422all kernel versions tested so far.
418 423
419This 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
… …
434 439
435It 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
436kernel is more efficient (which says nothing about its actual speed, of 441kernel is more efficient (which says nothing about its actual speed, of
437course). While stopping, setting and starting an I/O watcher does never 442course). While stopping, setting and starting an I/O watcher does never
438cause 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
439two 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
440drops fds silently in similarly hard-to-detect cases. 445sane, unlike epoll) and it drops fds silently in similarly hard-to-detect
446cases
441 447
442This backend usually performs well under most conditions. 448This backend usually performs well under most conditions.
443 449
444While nominally embeddable in other event loops, this doesn't work 450While nominally embeddable in other event loops, this doesn't work
445everywhere, 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
… …
474might perform better. 480might perform better.
475 481
476On the positive side, with the exception of the spurious readiness 482On the positive side, with the exception of the spurious readiness
477notifications, this backend actually performed fully to specification 483notifications, this backend actually performed fully to specification
478in 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
479OS-specific backends. 485OS-specific backends (I vastly prefer correctness over speed hacks).
480 486
481This 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
482C<EVBACKEND_POLL>. 488C<EVBACKEND_POLL>.
483 489
484=item C<EVBACKEND_ALL> 490=item C<EVBACKEND_ALL>
… …
1916 1922
1917 1923
1918=head2 C<ev_stat> - did the file attributes just change? 1924=head2 C<ev_stat> - did the file attributes just change?
1919 1925
1920This watches a file system path for attribute changes. That is, it calls 1926This watches a file system path for attribute changes. That is, it calls
1921C<stat> regularly (or when the OS says it changed) and sees if it changed 1927C<stat> on that path in regular intervals (or when the OS says it changed)
1922compared to the last time, invoking the callback if it did. 1928and sees if it changed compared to the last time, invoking the callback if
1929it did.
1923 1930
1924The path does not need to exist: changing from "path exists" to "path does 1931The path does not need to exist: changing from "path exists" to "path does
1925not exist" is a status change like any other. The condition "path does 1932not exist" is a status change like any other. The condition "path does
1926not exist" is signified by the C<st_nlink> field being zero (which is 1933not exist" is signified by the C<st_nlink> field being zero (which is
1927otherwise always forced to be at least one) and all the other fields of 1934otherwise always forced to be at least one) and all the other fields of
1928the stat buffer having unspecified contents. 1935the stat buffer having unspecified contents.
1929 1936
1930The path I<should> be absolute and I<must not> end in a slash. If it is 1937The path I<must not> end in a slash or contain special components such as
1938C<.> or C<..>. The path I<should> be absolute: If it is relative and
1931relative and your working directory changes, the behaviour is undefined. 1939your working directory changes, then the behaviour is undefined.
1932 1940
1933Since there is no standard kernel interface to do this, the portable 1941Since there is no portable change notification interface available, the
1934implementation simply calls C<stat (2)> regularly on the path to see if 1942portable implementation simply calls C<stat(2)> regularly on the path
1935it changed somehow. You can specify a recommended polling interval for 1943to see if it changed somehow. You can specify a recommended polling
1936this case. If you specify a polling interval of C<0> (highly recommended!) 1944interval for this case. If you specify a polling interval of C<0> (highly
1937then a I<suitable, unspecified default> value will be used (which 1945recommended!) then a I<suitable, unspecified default> value will be used
1938you can expect to be around five seconds, although this might change 1946(which you can expect to be around five seconds, although this might
1939dynamically). Libev will also impose a minimum interval which is currently 1947change dynamically). Libev will also impose a minimum interval which is
1940around C<0.1>, but thats usually overkill. 1948currently around C<0.1>, but thats usually overkill.
1941 1949
1942This watcher type is not meant for massive numbers of stat watchers, 1950This watcher type is not meant for massive numbers of stat watchers,
1943as even with OS-supported change notifications, this can be 1951as even with OS-supported change notifications, this can be
1944resource-intensive. 1952resource-intensive.
1945 1953
… …
1955support disabled by default, you get the 32 bit version of the stat 1963support disabled by default, you get the 32 bit version of the stat
1956structure. When using the library from programs that change the ABI to 1964structure. When using the library from programs that change the ABI to
1957use 64 bit file offsets the programs will fail. In that case you have to 1965use 64 bit file offsets the programs will fail. In that case you have to
1958compile libev with the same flags to get binary compatibility. This is 1966compile libev with the same flags to get binary compatibility. This is
1959obviously the case with any flags that change the ABI, but the problem is 1967obviously the case with any flags that change the ABI, but the problem is
1960most noticeably disabled with ev_stat and large file support. 1968most noticeably displayed with ev_stat and large file support.
1961 1969
1962The solution for this is to lobby your distribution maker to make large 1970The solution for this is to lobby your distribution maker to make large
1963file interfaces available by default (as e.g. FreeBSD does) and not 1971file interfaces available by default (as e.g. FreeBSD does) and not
1964optional. Libev cannot simply switch on large file support because it has 1972optional. Libev cannot simply switch on large file support because it has
1965to exchange stat structures with application programs compiled using the 1973to exchange stat structures with application programs compiled using the
… …
1984descriptor open on the object at all times, and detecting renames, unlinks 1992descriptor open on the object at all times, and detecting renames, unlinks
1985etc. is difficult. 1993etc. is difficult.
1986 1994
1987=head3 The special problem of stat time resolution 1995=head3 The special problem of stat time resolution
1988 1996
1989The C<stat ()> system call only supports full-second resolution portably, and 1997The C<stat ()> system call only supports full-second resolution portably,
1990even on systems where the resolution is higher, most file systems still 1998and even on systems where the resolution is higher, most file systems
1991only support whole seconds. 1999still only support whole seconds.
1992 2000
1993That means that, if the time is the only thing that changes, you can 2001That means that, if the time is the only thing that changes, you can
1994easily miss updates: on the first update, C<ev_stat> detects a change and 2002easily miss updates: on the first update, C<ev_stat> detects a change and
1995calls your callback, which does something. When there is another update 2003calls your callback, which does something. When there is another update
1996within the same second, C<ev_stat> will be unable to detect unless the 2004within the same second, C<ev_stat> will be unable to detect unless the

Diff Legend

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