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

Comparing libev/ev.pod (file contents):
Revision 1.202 by root, Fri Oct 24 08:30:01 2008 UTC vs.
Revision 1.210 by root, Thu Oct 30 08:09:30 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 390
391cases and requiring a system call per fd change, no fork support and bad 391The epoll mechanism deserves honorable mention as the most misdesigned
392support for dup. 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
400Epoll is also notoriously buggy - embedding epoll fds I<should> work, but
401of course I<doesn't>, and epoll just loves to report events for totally
402I<different> file descriptors (even already closed ones, so one cannot
403even remove them from the set) than registered in the set (especially
404on SMP systems). Libev tries to counter these spurious notifications by
405employing an additional generation counter and comparing that against the
406events to filter out spurious ones, recreating the set when required.
393 407
394While 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
395will 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
396(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
397best 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
398very well if you register events for both fds. 412file descriptors might not work very well if you register events for both
399 413file descriptors.
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 414
404Best performance from this backend is achieved by not unregistering all 415Best performance from this backend is achieved by not unregistering all
405watchers for a file descriptor until it has been closed, if possible, 416watchers 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 417i.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 418starting a watcher (without re-setting it) also usually doesn't cause
408extra 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.
409 422
410While nominally embeddable in other event loops, this feature is broken in 423While nominally embeddable in other event loops, this feature is broken in
411all kernel versions tested so far. 424all kernel versions tested so far.
412 425
413This 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
414C<EVBACKEND_POLL>. 427C<EVBACKEND_POLL>.
415 428
416=item C<EVBACKEND_KQUEUE> (value 8, most BSD clones) 429=item C<EVBACKEND_KQUEUE> (value 8, most BSD clones)
417 430
418Kqueue deserves special mention, as at the time of this writing, it was 431Kqueue deserves special mention, as at the time of this writing, it
419broken 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
420anything but sockets and pipes, except on Darwin, where of course it's 433with anything but sockets and pipes, except on Darwin, where of course
421completely useless). For this reason it's not being "auto-detected" unless 434it's completely useless). Unlike epoll, however, whose brokenness
422you 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
423libev 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.
424 440
425You 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
426only 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
427the target platform). See C<ev_embed> watchers for more info. 443the target platform). See C<ev_embed> watchers for more info.
428 444
429It 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
430kernel is more efficient (which says nothing about its actual speed, of 446kernel is more efficient (which says nothing about its actual speed, of
431course). While stopping, setting and starting an I/O watcher does never 447course). 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 448cause 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 449two event changes per incident. Support for C<fork ()> is very bad (but
434drops fds silently in similarly hard-to-detect cases. 450sane, unlike epoll) and it drops fds silently in similarly hard-to-detect
451cases
435 452
436This backend usually performs well under most conditions. 453This backend usually performs well under most conditions.
437 454
438While nominally embeddable in other event loops, this doesn't work 455While nominally embeddable in other event loops, this doesn't work
439everywhere, 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
… …
468might perform better. 485might perform better.
469 486
470On the positive side, with the exception of the spurious readiness 487On the positive side, with the exception of the spurious readiness
471notifications, this backend actually performed fully to specification 488notifications, this backend actually performed fully to specification
472in 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
473OS-specific backends. 490OS-specific backends (I vastly prefer correctness over speed hacks).
474 491
475This 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
476C<EVBACKEND_POLL>. 493C<EVBACKEND_POLL>.
477 494
478=item C<EVBACKEND_ALL> 495=item C<EVBACKEND_ALL>
… …
531responsibility to either stop all watchers cleanly yourself I<before> 548responsibility to either stop all watchers cleanly yourself I<before>
532calling this function, or cope with the fact afterwards (which is usually 549calling 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 550the easiest thing, you can just ignore the watchers and/or C<free ()> them
534for example). 551for example).
535 552
536Note that certain global state, such as signal state, will not be freed by 553Note that certain global state, such as signal state (and installed signal
537this function, and related watchers (such as signal and child watchers) 554handlers), will not be freed by this function, and related watchers (such
538would need to be stopped manually. 555as signal and child watchers) would need to be stopped manually.
539 556
540In general it is not advisable to call this function except in the 557In 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 558rare 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 559pipe fds. If you need dynamically allocated loops it is better to use
543C<ev_loop_new> and C<ev_loop_destroy>). 560C<ev_loop_new> and C<ev_loop_destroy>).
… …
635the loop. 652the loop.
636 653
637A 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
638necessary) and will handle those and any already outstanding ones. It 655necessary) and will handle those and any already outstanding ones. It
639will 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
640be 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
641user-registered callback will be called), and will return after one 658user-registered callback will be called), and will return after one
642iteration of the loop. 659iteration of the loop.
643 660
644This 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
645with something not expressible using other libev watchers (i.e. "roll your 662with something not expressible using other libev watchers (i.e. "roll your
… …
1910 1927
1911 1928
1912=head2 C<ev_stat> - did the file attributes just change? 1929=head2 C<ev_stat> - did the file attributes just change?
1913 1930
1914This 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
1915C<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)
1916compared 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.
1917 1935
1918The 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
1919not 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
1920not exist" is signified by the C<st_nlink> field being zero (which is 1938not exist" is signified by the C<st_nlink> field being zero (which is
1921otherwise always forced to be at least one) and all the other fields of 1939otherwise always forced to be at least one) and all the other fields of
1922the stat buffer having unspecified contents. 1940the stat buffer having unspecified contents.
1923 1941
1924The path I<should> be absolute and I<must not> end in a slash. If it is 1942The path I<must not> end in a slash or contain special components such as
1943C<.> or C<..>. The path I<should> be absolute: If it is relative and
1925relative and your working directory changes, the behaviour is undefined. 1944your working directory changes, then the behaviour is undefined.
1926 1945
1927Since there is no standard kernel interface to do this, the portable 1946Since there is no portable change notification interface available, the
1928implementation simply calls C<stat (2)> regularly on the path to see if 1947portable implementation simply calls C<stat(2)> regularly on the path
1929it changed somehow. You can specify a recommended polling interval for 1948to see if it changed somehow. You can specify a recommended polling
1930this case. If you specify a polling interval of C<0> (highly recommended!) 1949interval for this case. If you specify a polling interval of C<0> (highly
1931then a I<suitable, unspecified default> value will be used (which 1950recommended!) then a I<suitable, unspecified default> value will be used
1932you can expect to be around five seconds, although this might change 1951(which you can expect to be around five seconds, although this might
1933dynamically). Libev will also impose a minimum interval which is currently 1952change dynamically). Libev will also impose a minimum interval which is
1934around C<0.1>, but thats usually overkill. 1953currently around C<0.1>, but that's usually overkill.
1935 1954
1936This watcher type is not meant for massive numbers of stat watchers, 1955This watcher type is not meant for massive numbers of stat watchers,
1937as even with OS-supported change notifications, this can be 1956as even with OS-supported change notifications, this can be
1938resource-intensive. 1957resource-intensive.
1939 1958
… …
1949support disabled by default, you get the 32 bit version of the stat 1968support disabled by default, you get the 32 bit version of the stat
1950structure. When using the library from programs that change the ABI to 1969structure. When using the library from programs that change the ABI to
1951use 64 bit file offsets the programs will fail. In that case you have to 1970use 64 bit file offsets the programs will fail. In that case you have to
1952compile libev with the same flags to get binary compatibility. This is 1971compile libev with the same flags to get binary compatibility. This is
1953obviously the case with any flags that change the ABI, but the problem is 1972obviously the case with any flags that change the ABI, but the problem is
1954most noticeably disabled with ev_stat and large file support. 1973most noticeably displayed with ev_stat and large file support.
1955 1974
1956The solution for this is to lobby your distribution maker to make large 1975The solution for this is to lobby your distribution maker to make large
1957file interfaces available by default (as e.g. FreeBSD does) and not 1976file interfaces available by default (as e.g. FreeBSD does) and not
1958optional. Libev cannot simply switch on large file support because it has 1977optional. Libev cannot simply switch on large file support because it has
1959to exchange stat structures with application programs compiled using the 1978to exchange stat structures with application programs compiled using the
… …
1978descriptor open on the object at all times, and detecting renames, unlinks 1997descriptor open on the object at all times, and detecting renames, unlinks
1979etc. is difficult. 1998etc. is difficult.
1980 1999
1981=head3 The special problem of stat time resolution 2000=head3 The special problem of stat time resolution
1982 2001
1983The C<stat ()> system call only supports full-second resolution portably, and 2002The C<stat ()> system call only supports full-second resolution portably,
1984even on systems where the resolution is higher, most file systems still 2003and even on systems where the resolution is higher, most file systems
1985only support whole seconds. 2004still only support whole seconds.
1986 2005
1987That means that, if the time is the only thing that changes, you can 2006That means that, if the time is the only thing that changes, you can
1988easily miss updates: on the first update, C<ev_stat> detects a change and 2007easily miss updates: on the first update, C<ev_stat> detects a change and
1989calls your callback, which does something. When there is another update 2008calls your callback, which does something. When there is another update
1990within the same second, C<ev_stat> will be unable to detect unless the 2009within the same second, C<ev_stat> will be unable to detect unless the
… …
2629=over 4 2648=over 4
2630 2649
2631=item ev_async_init (ev_async *, callback) 2650=item ev_async_init (ev_async *, callback)
2632 2651
2633Initialises and configures the async watcher - it has no parameters of any 2652Initialises and configures the async watcher - it has no parameters of any
2634kind. There is a C<ev_asynd_set> macro, but using it is utterly pointless, 2653kind. There is a C<ev_async_set> macro, but using it is utterly pointless,
2635trust me. 2654trust me.
2636 2655
2637=item ev_async_send (loop, ev_async *) 2656=item ev_async_send (loop, ev_async *)
2638 2657
2639Sends/signals/activates the given C<ev_async> watcher, that is, feeds 2658Sends/signals/activates the given C<ev_async> watcher, that is, feeds
… …
3072 3091
3073 #define EV_STANDALONE 1 3092 #define EV_STANDALONE 1
3074 #include "ev.h" 3093 #include "ev.h"
3075 3094
3076Both header files and implementation files can be compiled with a C++ 3095Both header files and implementation files can be compiled with a C++
3077compiler (at least, thats a stated goal, and breakage will be treated 3096compiler (at least, that's a stated goal, and breakage will be treated
3078as a bug). 3097as a bug).
3079 3098
3080You need the following files in your source tree, or in a directory 3099You need the following files in your source tree, or in a directory
3081in your include path (e.g. in libev/ when using -Ilibev): 3100in your include path (e.g. in libev/ when using -Ilibev):
3082 3101
… …
3554loop, as long as you don't confuse yourself). The only exception is that 3573loop, as long as you don't confuse yourself). The only exception is that
3555you must not do this from C<ev_periodic> reschedule callbacks. 3574you must not do this from C<ev_periodic> reschedule callbacks.
3556 3575
3557Care has been taken to ensure that libev does not keep local state inside 3576Care has been taken to ensure that libev does not keep local state inside
3558C<ev_loop>, and other calls do not usually allow for coroutine switches as 3577C<ev_loop>, and other calls do not usually allow for coroutine switches as
3559they do not clal any callbacks. 3578they do not call any callbacks.
3560 3579
3561=head2 COMPILER WARNINGS 3580=head2 COMPILER WARNINGS
3562 3581
3563Depending on your compiler and compiler settings, you might get no or a 3582Depending on your compiler and compiler settings, you might get no or a
3564lot of warnings when compiling libev code. Some people are apparently 3583lot of warnings when compiling libev code. Some people are apparently
… …
3598 ==2274== definitely lost: 0 bytes in 0 blocks. 3617 ==2274== definitely lost: 0 bytes in 0 blocks.
3599 ==2274== possibly lost: 0 bytes in 0 blocks. 3618 ==2274== possibly lost: 0 bytes in 0 blocks.
3600 ==2274== still reachable: 256 bytes in 1 blocks. 3619 ==2274== still reachable: 256 bytes in 1 blocks.
3601 3620
3602Then there is no memory leak, just as memory accounted to global variables 3621Then there is no memory leak, just as memory accounted to global variables
3603is not a memleak - the memory is still being refernced, and didn't leak. 3622is not a memleak - the memory is still being referenced, and didn't leak.
3604 3623
3605Similarly, under some circumstances, valgrind might report kernel bugs 3624Similarly, under some circumstances, valgrind might report kernel bugs
3606as if it were a bug in libev (e.g. in realloc or in the poll backend, 3625as if it were a bug in libev (e.g. in realloc or in the poll backend,
3607although an acceptable workaround has been found here), or it might be 3626although an acceptable workaround has been found here), or it might be
3608confused. 3627confused.
… …
3846=back 3865=back
3847 3866
3848 3867
3849=head1 AUTHOR 3868=head1 AUTHOR
3850 3869
3851Marc Lehmann <libev@schmorp.de>. 3870Marc Lehmann <libev@schmorp.de>, with repeated corrections by Mikael Magnusson.
3852 3871

Diff Legend

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