… | |
… | |
8 | |
8 | |
9 | =head2 EXAMPLE PROGRAM |
9 | =head2 EXAMPLE PROGRAM |
10 | |
10 | |
11 | // a single header file is required |
11 | // a single header file is required |
12 | #include <ev.h> |
12 | #include <ev.h> |
|
|
13 | |
|
|
14 | #include <stdio.h> // for puts |
13 | |
15 | |
14 | // every watcher type has its own typedef'd struct |
16 | // every watcher type has its own typedef'd struct |
15 | // with the name ev_TYPE |
17 | // with the name ev_TYPE |
16 | ev_io stdin_watcher; |
18 | ev_io stdin_watcher; |
17 | ev_timer timeout_watcher; |
19 | ev_timer timeout_watcher; |
… | |
… | |
417 | i.e. keep at least one watcher active per fd at all times. Stopping and |
419 | i.e. keep at least one watcher active per fd at all times. Stopping and |
418 | starting a watcher (without re-setting it) also usually doesn't cause |
420 | starting a watcher (without re-setting it) also usually doesn't cause |
419 | extra overhead. A fork can both result in spurious notifications as well |
421 | extra overhead. A fork can both result in spurious notifications as well |
420 | as in libev having to destroy and recreate the epoll object, which can |
422 | as in libev having to destroy and recreate the epoll object, which can |
421 | take considerable time and thus should be avoided. |
423 | take considerable time and thus should be avoided. |
|
|
424 | |
|
|
425 | All this means that, in practice, C<EVBACKEND_SELECT> can be as fast or |
|
|
426 | faster than epoll for maybe up to a hundred file descriptors, depending on |
|
|
427 | the usage. So sad. |
422 | |
428 | |
423 | While nominally embeddable in other event loops, this feature is broken in |
429 | While nominally embeddable in other event loops, this feature is broken in |
424 | all kernel versions tested so far. |
430 | all kernel versions tested so far. |
425 | |
431 | |
426 | This backend maps C<EV_READ> and C<EV_WRITE> in the same way as |
432 | This backend maps C<EV_READ> and C<EV_WRITE> in the same way as |
… | |
… | |
1415 | else |
1421 | else |
1416 | { |
1422 | { |
1417 | // callback was invoked, but there was some activity, re-arm |
1423 | // callback was invoked, but there was some activity, re-arm |
1418 | // the watcher to fire in last_activity + 60, which is |
1424 | // the watcher to fire in last_activity + 60, which is |
1419 | // guaranteed to be in the future, so "again" is positive: |
1425 | // guaranteed to be in the future, so "again" is positive: |
1420 | w->again = timeout - now; |
1426 | w->repeat = timeout - now; |
1421 | ev_timer_again (EV_A_ w); |
1427 | ev_timer_again (EV_A_ w); |
1422 | } |
1428 | } |
1423 | } |
1429 | } |
1424 | |
1430 | |
1425 | To summarise the callback: first calculate the real timeout (defined |
1431 | To summarise the callback: first calculate the real timeout (defined |
… | |
… | |
1932 | C<stat> on that path in regular intervals (or when the OS says it changed) |
1938 | C<stat> on that path in regular intervals (or when the OS says it changed) |
1933 | and sees if it changed compared to the last time, invoking the callback if |
1939 | and sees if it changed compared to the last time, invoking the callback if |
1934 | it did. |
1940 | it did. |
1935 | |
1941 | |
1936 | The path does not need to exist: changing from "path exists" to "path does |
1942 | The path does not need to exist: changing from "path exists" to "path does |
1937 | not exist" is a status change like any other. The condition "path does |
1943 | not exist" is a status change like any other. The condition "path does not |
1938 | not exist" is signified by the C<st_nlink> field being zero (which is |
1944 | exist" (or more correctly "path cannot be stat'ed") is signified by the |
1939 | otherwise always forced to be at least one) and all the other fields of |
1945 | C<st_nlink> field being zero (which is otherwise always forced to be at |
1940 | the stat buffer having unspecified contents. |
1946 | least one) and all the other fields of the stat buffer having unspecified |
|
|
1947 | contents. |
1941 | |
1948 | |
1942 | The path I<must not> end in a slash or contain special components such as |
1949 | The path I<must not> end in a slash or contain special components such as |
1943 | C<.> or C<..>. The path I<should> be absolute: If it is relative and |
1950 | C<.> or C<..>. The path I<should> be absolute: If it is relative and |
1944 | your working directory changes, then the behaviour is undefined. |
1951 | your working directory changes, then the behaviour is undefined. |
1945 | |
1952 | |
… | |
… | |
1955 | This watcher type is not meant for massive numbers of stat watchers, |
1962 | This watcher type is not meant for massive numbers of stat watchers, |
1956 | as even with OS-supported change notifications, this can be |
1963 | as even with OS-supported change notifications, this can be |
1957 | resource-intensive. |
1964 | resource-intensive. |
1958 | |
1965 | |
1959 | At the time of this writing, the only OS-specific interface implemented |
1966 | At the time of this writing, the only OS-specific interface implemented |
1960 | is the Linux inotify interface (implementing kqueue support is left as |
1967 | is the Linux inotify interface (implementing kqueue support is left as an |
1961 | an exercise for the reader. Note, however, that the author sees no way |
1968 | exercise for the reader. Note, however, that the author sees no way of |
1962 | of implementing C<ev_stat> semantics with kqueue). |
1969 | implementing C<ev_stat> semantics with kqueue, except as a hint). |
1963 | |
1970 | |
1964 | =head3 ABI Issues (Largefile Support) |
1971 | =head3 ABI Issues (Largefile Support) |
1965 | |
1972 | |
1966 | Libev by default (unless the user overrides this) uses the default |
1973 | Libev by default (unless the user overrides this) uses the default |
1967 | compilation environment, which means that on systems with large file |
1974 | compilation environment, which means that on systems with large file |
… | |
… | |
1978 | to exchange stat structures with application programs compiled using the |
1985 | to exchange stat structures with application programs compiled using the |
1979 | default compilation environment. |
1986 | default compilation environment. |
1980 | |
1987 | |
1981 | =head3 Inotify and Kqueue |
1988 | =head3 Inotify and Kqueue |
1982 | |
1989 | |
1983 | When C<inotify (7)> support has been compiled into libev (generally |
1990 | When C<inotify (7)> support has been compiled into libev and present at |
1984 | only available with Linux 2.6.25 or above due to bugs in earlier |
1991 | runtime, it will be used to speed up change detection where possible. The |
1985 | implementations) and present at runtime, it will be used to speed up |
1992 | inotify descriptor will be created lazily when the first C<ev_stat> |
1986 | change detection where possible. The inotify descriptor will be created |
1993 | watcher is being started. |
1987 | lazily when the first C<ev_stat> watcher is being started. |
|
|
1988 | |
1994 | |
1989 | Inotify presence does not change the semantics of C<ev_stat> watchers |
1995 | Inotify presence does not change the semantics of C<ev_stat> watchers |
1990 | except that changes might be detected earlier, and in some cases, to avoid |
1996 | except that changes might be detected earlier, and in some cases, to avoid |
1991 | making regular C<stat> calls. Even in the presence of inotify support |
1997 | making regular C<stat> calls. Even in the presence of inotify support |
1992 | there are many cases where libev has to resort to regular C<stat> polling, |
1998 | there are many cases where libev has to resort to regular C<stat> polling, |
1993 | but as long as the path exists, libev usually gets away without polling. |
1999 | but as long as kernel 2.6.25 or newer is used (2.6.24 and older have too |
|
|
2000 | many bugs), the path exists (i.e. stat succeeds), and the path resides on |
|
|
2001 | a local filesystem (libev currently assumes only ext2/3, jfs, reiserfs and |
|
|
2002 | xfs are fully working) libev usually gets away without polling. |
1994 | |
2003 | |
1995 | There is no support for kqueue, as apparently it cannot be used to |
2004 | There is no support for kqueue, as apparently it cannot be used to |
1996 | implement this functionality, due to the requirement of having a file |
2005 | implement this functionality, due to the requirement of having a file |
1997 | descriptor open on the object at all times, and detecting renames, unlinks |
2006 | descriptor open on the object at all times, and detecting renames, unlinks |
1998 | etc. is difficult. |
2007 | etc. is difficult. |
|
|
2008 | |
|
|
2009 | =head3 C<stat ()> is a synchronous operation |
|
|
2010 | |
|
|
2011 | Libev doesn't normally do any kind of I/O itself, and so is not blocking |
|
|
2012 | the process. The exception are C<ev_stat> watchers - those call C<stat |
|
|
2013 | ()>, which is a synchronous operation. |
|
|
2014 | |
|
|
2015 | For local paths, this usually doesn't matter: unless the system is very |
|
|
2016 | busy or the intervals between stat's are large, a stat call will be fast, |
|
|
2017 | as the path data is suually in memory already (except when starting the |
|
|
2018 | watcher). |
|
|
2019 | |
|
|
2020 | For networked file systems, calling C<stat ()> can block an indefinite |
|
|
2021 | time due to network issues, and even under good conditions, a stat call |
|
|
2022 | often takes multiple milliseconds. |
|
|
2023 | |
|
|
2024 | Therefore, it is best to avoid using C<ev_stat> watchers on networked |
|
|
2025 | paths, although this is fully supported by libev. |
1999 | |
2026 | |
2000 | =head3 The special problem of stat time resolution |
2027 | =head3 The special problem of stat time resolution |
2001 | |
2028 | |
2002 | The C<stat ()> system call only supports full-second resolution portably, |
2029 | The C<stat ()> system call only supports full-second resolution portably, |
2003 | and even on systems where the resolution is higher, most file systems |
2030 | and even on systems where the resolution is higher, most file systems |