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

Comparing libev/ev.pod (file contents):
Revision 1.204 by root, Mon Oct 27 11:08:29 2008 UTC vs.
Revision 1.212 by root, Mon Nov 3 15:13:53 2008 UTC

298If you don't know what event loop to use, use the one returned from this 298If you don't know what event loop to use, use the one returned from this
299function. 299function.
300 300
301Note that this function is I<not> thread-safe, so if you want to use it 301Note that this function is I<not> thread-safe, so if you want to use it
302from multiple threads, you have to lock (note also that this is unlikely, 302from multiple threads, you have to lock (note also that this is unlikely,
303as loops cannot bes hared easily between threads anyway). 303as loops cannot be shared easily between threads anyway).
304 304
305The default loop is the only loop that can handle C<ev_signal> and 305The default loop is the only loop that can handle C<ev_signal> and
306C<ev_child> watchers, and to do this, it always registers a handler 306C<ev_child> watchers, and to do this, it always registers a handler
307for C<SIGCHLD>. If this is a problem for your application you can either 307for C<SIGCHLD>. If this is a problem for your application you can either
308create a dynamic loop with C<ev_loop_new> that doesn't do that, or you 308create a dynamic loop with C<ev_loop_new> that doesn't do that, or you
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
391cases and requiring a system call per fd change, no fork support and bad
392support for dup.
393 390
391The epoll mechanism deserves honorable mention as the most misdesigned
392of the more advanced event mechanisms: mere annoyances include silently
393dropping file descriptors, requiring a system call per change per file
394descriptor (and unnecessary guessing of parameters), problems with dup and
395so on. The biggest issue is fork races, however - if a program forks then
396I<both> parent and child process have to recreate the epoll set, which can
397take considerable time (one syscall per file descriptor) and is of course
398hard to detect.
399
394Epoll is also notoriously buggy - embedding epoll fds should work, but 400Epoll is also notoriously buggy - embedding epoll fds I<should> work, but
395of course doesn't, and epoll just loves to report events for totally 401of course I<doesn't>, and epoll just loves to report events for totally
396I<different> file descriptors (even already closed ones) than registered 402I<different> file descriptors (even already closed ones, so one cannot
397in the set (especially on SMP systems). Libev tries to counter these 403even remove them from the set) than registered in the set (especially
398spurious notifications by employing an additional generation counter and 404on SMP systems). Libev tries to counter these spurious notifications by
399comparing that against the events to filter out spurious ones. 405employing an additional generation counter and comparing that against the
406events to filter out spurious ones, recreating the set when required.
400 407
401While stopping, setting and starting an I/O watcher in the same iteration 408While stopping, setting and starting an I/O watcher in the same iteration
402will result in some caching, there is still a system call per such incident 409will result in some caching, there is still a system call per such
403(because the fd could point to a different file description now), so its 410incident (because the same I<file descriptor> could point to a different
404best to avoid that. Also, C<dup ()>'ed file descriptors might not work 411I<file description> now), so its best to avoid that. Also, C<dup ()>'ed
405very well if you register events for both fds. 412file descriptors might not work very well if you register events for both
413file descriptors.
406 414
407Best performance from this backend is achieved by not unregistering all 415Best performance from this backend is achieved by not unregistering all
408watchers for a file descriptor until it has been closed, if possible, 416watchers for a file descriptor until it has been closed, if possible,
409i.e. keep at least one watcher active per fd at all times. Stopping and 417i.e. keep at least one watcher active per fd at all times. Stopping and
410starting a watcher (without re-setting it) also usually doesn't cause 418starting a watcher (without re-setting it) also usually doesn't cause
411extra overhead. 419extra overhead. A fork can both result in spurious notifications as well
420as in libev having to destroy and recreate the epoll object, which can
421take considerable time and thus should be avoided.
412 422
413While nominally embeddable in other event loops, this feature is broken in 423While nominally embeddable in other event loops, this feature is broken in
414all kernel versions tested so far. 424all kernel versions tested so far.
415 425
416This backend maps C<EV_READ> and C<EV_WRITE> in the same way as 426This backend maps C<EV_READ> and C<EV_WRITE> in the same way as
417C<EVBACKEND_POLL>. 427C<EVBACKEND_POLL>.
418 428
419=item C<EVBACKEND_KQUEUE> (value 8, most BSD clones) 429=item C<EVBACKEND_KQUEUE> (value 8, most BSD clones)
420 430
421Kqueue deserves special mention, as at the time of this writing, it was 431Kqueue deserves special mention, as at the time of this writing, it
422broken on all BSDs except NetBSD (usually it doesn't work reliably with 432was broken on all BSDs except NetBSD (usually it doesn't work reliably
423anything but sockets and pipes, except on Darwin, where of course it's 433with anything but sockets and pipes, except on Darwin, where of course
424completely useless). For this reason it's not being "auto-detected" unless 434it's completely useless). Unlike epoll, however, whose brokenness
425you explicitly specify it in the flags (i.e. using C<EVBACKEND_KQUEUE>) or 435is by design, these kqueue bugs can (and eventually will) be fixed
426libev was compiled on a known-to-be-good (-enough) system like NetBSD. 436without API changes to existing programs. For this reason it's not being
437"auto-detected" unless you explicitly specify it in the flags (i.e. using
438C<EVBACKEND_KQUEUE>) or libev was compiled on a known-to-be-good (-enough)
439system like NetBSD.
427 440
428You still can embed kqueue into a normal poll or select backend and use it 441You still can embed kqueue into a normal poll or select backend and use it
429only for sockets (after having made sure that sockets work with kqueue on 442only for sockets (after having made sure that sockets work with kqueue on
430the target platform). See C<ev_embed> watchers for more info. 443the target platform). See C<ev_embed> watchers for more info.
431 444
432It scales in the same way as the epoll backend, but the interface to the 445It scales in the same way as the epoll backend, but the interface to the
433kernel is more efficient (which says nothing about its actual speed, of 446kernel is more efficient (which says nothing about its actual speed, of
434course). While stopping, setting and starting an I/O watcher does never 447course). While stopping, setting and starting an I/O watcher does never
435cause an extra system call as with C<EVBACKEND_EPOLL>, it still adds up to 448cause an extra system call as with C<EVBACKEND_EPOLL>, it still adds up to
436two event changes per incident. Support for C<fork ()> is very bad and it 449two event changes per incident. Support for C<fork ()> is very bad (but
437drops fds silently in similarly hard-to-detect cases. 450sane, unlike epoll) and it drops fds silently in similarly hard-to-detect
451cases
438 452
439This backend usually performs well under most conditions. 453This backend usually performs well under most conditions.
440 454
441While nominally embeddable in other event loops, this doesn't work 455While nominally embeddable in other event loops, this doesn't work
442everywhere, so you might need to test for this. And since it is broken 456everywhere, so you might need to test for this. And since it is broken
471might perform better. 485might perform better.
472 486
473On the positive side, with the exception of the spurious readiness 487On the positive side, with the exception of the spurious readiness
474notifications, this backend actually performed fully to specification 488notifications, this backend actually performed fully to specification
475in all tests and is fully embeddable, which is a rare feat among the 489in all tests and is fully embeddable, which is a rare feat among the
476OS-specific backends. 490OS-specific backends (I vastly prefer correctness over speed hacks).
477 491
478This backend maps C<EV_READ> and C<EV_WRITE> in the same way as 492This backend maps C<EV_READ> and C<EV_WRITE> in the same way as
479C<EVBACKEND_POLL>. 493C<EVBACKEND_POLL>.
480 494
481=item C<EVBACKEND_ALL> 495=item C<EVBACKEND_ALL>
638the loop. 652the loop.
639 653
640A flags value of C<EVLOOP_ONESHOT> will look for new events (waiting if 654A flags value of C<EVLOOP_ONESHOT> will look for new events (waiting if
641necessary) and will handle those and any already outstanding ones. It 655necessary) and will handle those and any already outstanding ones. It
642will block your process until at least one new event arrives (which could 656will block your process until at least one new event arrives (which could
643be an event internal to libev itself, so there is no guarentee that a 657be an event internal to libev itself, so there is no guarantee that a
644user-registered callback will be called), and will return after one 658user-registered callback will be called), and will return after one
645iteration of the loop. 659iteration of the loop.
646 660
647This is useful if you are waiting for some external event in conjunction 661This is useful if you are waiting for some external event in conjunction
648with something not expressible using other libev watchers (i.e. "roll your 662with something not expressible using other libev watchers (i.e. "roll your
1913 1927
1914 1928
1915=head2 C<ev_stat> - did the file attributes just change? 1929=head2 C<ev_stat> - did the file attributes just change?
1916 1930
1917This watches a file system path for attribute changes. That is, it calls 1931This watches a file system path for attribute changes. That is, it calls
1918C<stat> regularly (or when the OS says it changed) and sees if it changed 1932C<stat> on that path in regular intervals (or when the OS says it changed)
1919compared to the last time, invoking the callback if it did. 1933and sees if it changed compared to the last time, invoking the callback if
1934it did.
1920 1935
1921The path does not need to exist: changing from "path exists" to "path does 1936The path does not need to exist: changing from "path exists" to "path does
1922not exist" is a status change like any other. The condition "path does 1937not exist" is a status change like any other. The condition "path does not
1923not exist" is signified by the C<st_nlink> field being zero (which is 1938exist" (or more correctly "path cannot be stat'ed") is signified by the
1924otherwise always forced to be at least one) and all the other fields of 1939C<st_nlink> field being zero (which is otherwise always forced to be at
1925the stat buffer having unspecified contents. 1940least one) and all the other fields of the stat buffer having unspecified
1941contents.
1926 1942
1927The path I<should> be absolute and I<must not> end in a slash. If it is 1943The path I<must not> end in a slash or contain special components such as
1944C<.> or C<..>. The path I<should> be absolute: If it is relative and
1928relative and your working directory changes, the behaviour is undefined. 1945your working directory changes, then the behaviour is undefined.
1929 1946
1930Since there is no standard kernel interface to do this, the portable 1947Since there is no portable change notification interface available, the
1931implementation simply calls C<stat (2)> regularly on the path to see if 1948portable implementation simply calls C<stat(2)> regularly on the path
1932it changed somehow. You can specify a recommended polling interval for 1949to see if it changed somehow. You can specify a recommended polling
1933this case. If you specify a polling interval of C<0> (highly recommended!) 1950interval for this case. If you specify a polling interval of C<0> (highly
1934then a I<suitable, unspecified default> value will be used (which 1951recommended!) then a I<suitable, unspecified default> value will be used
1935you can expect to be around five seconds, although this might change 1952(which you can expect to be around five seconds, although this might
1936dynamically). Libev will also impose a minimum interval which is currently 1953change dynamically). Libev will also impose a minimum interval which is
1937around C<0.1>, but thats usually overkill. 1954currently around C<0.1>, but that's usually overkill.
1938 1955
1939This watcher type is not meant for massive numbers of stat watchers, 1956This watcher type is not meant for massive numbers of stat watchers,
1940as even with OS-supported change notifications, this can be 1957as even with OS-supported change notifications, this can be
1941resource-intensive. 1958resource-intensive.
1942 1959
1943At the time of this writing, the only OS-specific interface implemented 1960At the time of this writing, the only OS-specific interface implemented
1944is the Linux inotify interface (implementing kqueue support is left as 1961is the Linux inotify interface (implementing kqueue support is left as an
1945an exercise for the reader. Note, however, that the author sees no way 1962exercise for the reader. Note, however, that the author sees no way of
1946of implementing C<ev_stat> semantics with kqueue). 1963implementing C<ev_stat> semantics with kqueue, except as a hint).
1947 1964
1948=head3 ABI Issues (Largefile Support) 1965=head3 ABI Issues (Largefile Support)
1949 1966
1950Libev by default (unless the user overrides this) uses the default 1967Libev by default (unless the user overrides this) uses the default
1951compilation environment, which means that on systems with large file 1968compilation environment, which means that on systems with large file
1952support disabled by default, you get the 32 bit version of the stat 1969support disabled by default, you get the 32 bit version of the stat
1953structure. When using the library from programs that change the ABI to 1970structure. When using the library from programs that change the ABI to
1954use 64 bit file offsets the programs will fail. In that case you have to 1971use 64 bit file offsets the programs will fail. In that case you have to
1955compile libev with the same flags to get binary compatibility. This is 1972compile libev with the same flags to get binary compatibility. This is
1956obviously the case with any flags that change the ABI, but the problem is 1973obviously the case with any flags that change the ABI, but the problem is
1957most noticeably disabled with ev_stat and large file support. 1974most noticeably displayed with ev_stat and large file support.
1958 1975
1959The solution for this is to lobby your distribution maker to make large 1976The solution for this is to lobby your distribution maker to make large
1960file interfaces available by default (as e.g. FreeBSD does) and not 1977file interfaces available by default (as e.g. FreeBSD does) and not
1961optional. Libev cannot simply switch on large file support because it has 1978optional. Libev cannot simply switch on large file support because it has
1962to exchange stat structures with application programs compiled using the 1979to exchange stat structures with application programs compiled using the
1963default compilation environment. 1980default compilation environment.
1964 1981
1965=head3 Inotify and Kqueue 1982=head3 Inotify and Kqueue
1966 1983
1967When C<inotify (7)> support has been compiled into libev (generally 1984When C<inotify (7)> support has been compiled into libev and present at
1968only available with Linux 2.6.25 or above due to bugs in earlier 1985runtime, it will be used to speed up change detection where possible. The
1969implementations) and present at runtime, it will be used to speed up 1986inotify descriptor will be created lazily when the first C<ev_stat>
1970change detection where possible. The inotify descriptor will be created 1987watcher is being started.
1971lazily when the first C<ev_stat> watcher is being started.
1972 1988
1973Inotify presence does not change the semantics of C<ev_stat> watchers 1989Inotify presence does not change the semantics of C<ev_stat> watchers
1974except that changes might be detected earlier, and in some cases, to avoid 1990except that changes might be detected earlier, and in some cases, to avoid
1975making regular C<stat> calls. Even in the presence of inotify support 1991making regular C<stat> calls. Even in the presence of inotify support
1976there are many cases where libev has to resort to regular C<stat> polling, 1992there are many cases where libev has to resort to regular C<stat> polling,
1977but as long as the path exists, libev usually gets away without polling. 1993but as long as kernel 2.6.25 or newer is used (2.6.24 and older have too
1994many bugs), the path exists (i.e. stat succeeds), and the path resides on
1995a local filesystem (libev currently assumes only ext2/3, jfs, reiserfs and
1996xfs are fully working) libev usually gets away without polling.
1978 1997
1979There is no support for kqueue, as apparently it cannot be used to 1998There is no support for kqueue, as apparently it cannot be used to
1980implement this functionality, due to the requirement of having a file 1999implement this functionality, due to the requirement of having a file
1981descriptor open on the object at all times, and detecting renames, unlinks 2000descriptor open on the object at all times, and detecting renames, unlinks
1982etc. is difficult. 2001etc. is difficult.
1983 2002
2003=head3 C<stat ()> is a synchronous operation
2004
2005Libev doesn't normally do any kind of I/O itself, and so is not blocking
2006the process. The exception are C<ev_stat> watchers - those call C<stat
2007()>, which is a synchronous operation.
2008
2009For local paths, this usually doesn't matter: unless the system is very
2010busy or the intervals between stat's are large, a stat call will be fast,
2011as the path data is suually in memory already (except when starting the
2012watcher).
2013
2014For networked file systems, calling C<stat ()> can block an indefinite
2015time due to network issues, and even under good conditions, a stat call
2016often takes multiple milliseconds.
2017
2018Therefore, it is best to avoid using C<ev_stat> watchers on networked
2019paths, although this is fully supported by libev.
2020
1984=head3 The special problem of stat time resolution 2021=head3 The special problem of stat time resolution
1985 2022
1986The C<stat ()> system call only supports full-second resolution portably, and 2023The C<stat ()> system call only supports full-second resolution portably,
1987even on systems where the resolution is higher, most file systems still 2024and even on systems where the resolution is higher, most file systems
1988only support whole seconds. 2025still only support whole seconds.
1989 2026
1990That means that, if the time is the only thing that changes, you can 2027That means that, if the time is the only thing that changes, you can
1991easily miss updates: on the first update, C<ev_stat> detects a change and 2028easily miss updates: on the first update, C<ev_stat> detects a change and
1992calls your callback, which does something. When there is another update 2029calls your callback, which does something. When there is another update
1993within the same second, C<ev_stat> will be unable to detect unless the 2030within the same second, C<ev_stat> will be unable to detect unless the
2632=over 4 2669=over 4
2633 2670
2634=item ev_async_init (ev_async *, callback) 2671=item ev_async_init (ev_async *, callback)
2635 2672
2636Initialises and configures the async watcher - it has no parameters of any 2673Initialises and configures the async watcher - it has no parameters of any
2637kind. There is a C<ev_asynd_set> macro, but using it is utterly pointless, 2674kind. There is a C<ev_async_set> macro, but using it is utterly pointless,
2638trust me. 2675trust me.
2639 2676
2640=item ev_async_send (loop, ev_async *) 2677=item ev_async_send (loop, ev_async *)
2641 2678
2642Sends/signals/activates the given C<ev_async> watcher, that is, feeds 2679Sends/signals/activates the given C<ev_async> watcher, that is, feeds
3075 3112
3076 #define EV_STANDALONE 1 3113 #define EV_STANDALONE 1
3077 #include "ev.h" 3114 #include "ev.h"
3078 3115
3079Both header files and implementation files can be compiled with a C++ 3116Both header files and implementation files can be compiled with a C++
3080compiler (at least, thats a stated goal, and breakage will be treated 3117compiler (at least, that's a stated goal, and breakage will be treated
3081as a bug). 3118as a bug).
3082 3119
3083You need the following files in your source tree, or in a directory 3120You need the following files in your source tree, or in a directory
3084in your include path (e.g. in libev/ when using -Ilibev): 3121in your include path (e.g. in libev/ when using -Ilibev):
3085 3122
3557loop, as long as you don't confuse yourself). The only exception is that 3594loop, as long as you don't confuse yourself). The only exception is that
3558you must not do this from C<ev_periodic> reschedule callbacks. 3595you must not do this from C<ev_periodic> reschedule callbacks.
3559 3596
3560Care has been taken to ensure that libev does not keep local state inside 3597Care has been taken to ensure that libev does not keep local state inside
3561C<ev_loop>, and other calls do not usually allow for coroutine switches as 3598C<ev_loop>, and other calls do not usually allow for coroutine switches as
3562they do not clal any callbacks. 3599they do not call any callbacks.
3563 3600
3564=head2 COMPILER WARNINGS 3601=head2 COMPILER WARNINGS
3565 3602
3566Depending on your compiler and compiler settings, you might get no or a 3603Depending on your compiler and compiler settings, you might get no or a
3567lot of warnings when compiling libev code. Some people are apparently 3604lot of warnings when compiling libev code. Some people are apparently
3601 ==2274== definitely lost: 0 bytes in 0 blocks. 3638 ==2274== definitely lost: 0 bytes in 0 blocks.
3602 ==2274== possibly lost: 0 bytes in 0 blocks. 3639 ==2274== possibly lost: 0 bytes in 0 blocks.
3603 ==2274== still reachable: 256 bytes in 1 blocks. 3640 ==2274== still reachable: 256 bytes in 1 blocks.
3604 3641
3605Then there is no memory leak, just as memory accounted to global variables 3642Then there is no memory leak, just as memory accounted to global variables
3606is not a memleak - the memory is still being refernced, and didn't leak. 3643is not a memleak - the memory is still being referenced, and didn't leak.
3607 3644
3608Similarly, under some circumstances, valgrind might report kernel bugs 3645Similarly, under some circumstances, valgrind might report kernel bugs
3609as if it were a bug in libev (e.g. in realloc or in the poll backend, 3646as if it were a bug in libev (e.g. in realloc or in the poll backend,
3610although an acceptable workaround has been found here), or it might be 3647although an acceptable workaround has been found here), or it might be
3611confused. 3648confused.
3849=back 3886=back
3850 3887
3851 3888
3852=head1 AUTHOR 3889=head1 AUTHOR
3853 3890
3854Marc Lehmann <libev@schmorp.de>. 3891Marc Lehmann <libev@schmorp.de>, with repeated corrections by Mikael Magnusson.
3855 3892

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines