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

Comparing libev/ev.pod (file contents):
Revision 1.55 by root, Tue Nov 27 20:38:07 2007 UTC vs.
Revision 1.60 by root, Wed Nov 28 18:29:30 2007 UTC

… …
63details of the event, and then hand it over to libev by I<starting> the 63details of the event, and then hand it over to libev by I<starting> the
64watcher. 64watcher.
65 65
66=head1 FEATURES 66=head1 FEATURES
67 67
68Libev supports C<select>, C<poll>, the linux-specific C<epoll>, the 68Libev supports C<select>, C<poll>, the Linux-specific C<epoll>, the
69bsd-specific C<kqueue> and the solaris-specific event port mechanisms 69BSD-specific C<kqueue> and the Solaris-specific event port mechanisms
70for file descriptor events (C<ev_io>), relative timers (C<ev_timer>), 70for file descriptor events (C<ev_io>), the Linux C<inotify> interface
71(for C<ev_stat>), relative timers (C<ev_timer>), absolute timers
71absolute timers with customised rescheduling (C<ev_periodic>), synchronous 72with customised rescheduling (C<ev_periodic>), synchronous signals
72signals (C<ev_signal>), process status change events (C<ev_child>), and 73(C<ev_signal>), process status change events (C<ev_child>), and event
73event watchers dealing with the event loop mechanism itself (C<ev_idle>, 74watchers dealing with the event loop mechanism itself (C<ev_idle>,
74C<ev_embed>, C<ev_prepare> and C<ev_check> watchers) as well as 75C<ev_embed>, C<ev_prepare> and C<ev_check> watchers) as well as
75file watchers (C<ev_stat>) and even limited support for fork events 76file watchers (C<ev_stat>) and even limited support for fork events
76(C<ev_fork>). 77(C<ev_fork>).
77 78
78It also is quite fast (see this 79It also is quite fast (see this
… …
162C<ev_embeddable_backends () & ev_supported_backends ()>, likewise for 163C<ev_embeddable_backends () & ev_supported_backends ()>, likewise for
163recommended ones. 164recommended ones.
164 165
165See the description of C<ev_embed> watchers for more info. 166See the description of C<ev_embed> watchers for more info.
166 167
167=item ev_set_allocator (void *(*cb)(void *ptr, size_t size)) 168=item ev_set_allocator (void *(*cb)(void *ptr, long size))
168 169
169Sets the allocation function to use (the prototype and semantics are 170Sets the allocation function to use (the prototype is similar - the
170identical to the realloc C function). It is used to allocate and free 171semantics is identical - to the realloc C function). It is used to
171memory (no surprises here). If it returns zero when memory needs to be 172allocate and free memory (no surprises here). If it returns zero when
172allocated, the library might abort or take some potentially destructive 173memory needs to be allocated, the library might abort or take some
173action. The default is your system realloc function. 174potentially destructive action. The default is your system realloc
175function.
174 176
175You could override this function in high-availability programs to, say, 177You could override this function in high-availability programs to, say,
176free some memory if it cannot allocate memory, to use a special allocator, 178free some memory if it cannot allocate memory, to use a special allocator,
177or even to sleep a while and retry until some memory is available. 179or even to sleep a while and retry until some memory is available.
178 180
… …
1221not exist" is a status change like any other. The condition "path does 1223not exist" is a status change like any other. The condition "path does
1222not exist" is signified by the C<st_nlink> field being zero (which is 1224not exist" is signified by the C<st_nlink> field being zero (which is
1223otherwise always forced to be at least one) and all the other fields of 1225otherwise always forced to be at least one) and all the other fields of
1224the stat buffer having unspecified contents. 1226the stat buffer having unspecified contents.
1225 1227
1228The path I<should> be absolute and I<must not> end in a slash. If it is
1229relative and your working directory changes, the behaviour is undefined.
1230
1226Since there is no standard to do this, the portable implementation simply 1231Since there is no standard to do this, the portable implementation simply
1227calls C<stat (2)> regulalry on the path to see if it changed somehow. You 1232calls C<stat (2)> regularly on the path to see if it changed somehow. You
1228can specify a recommended polling interval for this case. If you specify 1233can specify a recommended polling interval for this case. If you specify
1229a polling interval of C<0> (highly recommended!) then a I<suitable, 1234a polling interval of C<0> (highly recommended!) then a I<suitable,
1230unspecified default> value will be used (which you can expect to be around 1235unspecified default> value will be used (which you can expect to be around
1231five seconds, although this might change dynamically). Libev will also 1236five seconds, although this might change dynamically). Libev will also
1232impose a minimum interval which is currently around C<0.1>, but thats 1237impose a minimum interval which is currently around C<0.1>, but thats
… …
1234 1239
1235This watcher type is not meant for massive numbers of stat watchers, 1240This watcher type is not meant for massive numbers of stat watchers,
1236as even with OS-supported change notifications, this can be 1241as even with OS-supported change notifications, this can be
1237resource-intensive. 1242resource-intensive.
1238 1243
1239At the time of this writing, no specific OS backends are implemented, but 1244At the time of this writing, only the Linux inotify interface is
1240if demand increases, at least a kqueue and inotify backend will be added. 1245implemented (implementing kqueue support is left as an exercise for the
1246reader). Inotify will be used to give hints only and should not change the
1247semantics of C<ev_stat> watchers, which means that libev sometimes needs
1248to fall back to regular polling again even with inotify, but changes are
1249usually detected immediately, and if the file exists there will be no
1250polling.
1241 1251
1242=over 4 1252=over 4
1243 1253
1244=item ev_stat_init (ev_stat *, callback, const char *path, ev_tstamp interval) 1254=item ev_stat_init (ev_stat *, callback, const char *path, ev_tstamp interval)
1245 1255
… …
2014 2024
2015=item EV_USE_DEVPOLL 2025=item EV_USE_DEVPOLL
2016 2026
2017reserved for future expansion, works like the USE symbols above. 2027reserved for future expansion, works like the USE symbols above.
2018 2028
2029=item EV_USE_INOTIFY
2030
2031If defined to be C<1>, libev will compile in support for the Linux inotify
2032interface to speed up C<ev_stat> watchers. Its actual availability will
2033be detected at runtime.
2034
2019=item EV_H 2035=item EV_H
2020 2036
2021The name of the F<ev.h> header file used to include it. The default if 2037The name of the F<ev.h> header file used to include it. The default if
2022undefined is C<< <ev.h> >> in F<event.h> and C<"ev.h"> in F<ev.c>. This 2038undefined is C<< <ev.h> >> in F<event.h> and C<"ev.h"> in F<ev.c>. This
2023can be used to virtually rename the F<ev.h> header file in case of conflicts. 2039can be used to virtually rename the F<ev.h> header file in case of conflicts.
… …
2078=item EV_PID_HASHSIZE 2094=item EV_PID_HASHSIZE
2079 2095
2080C<ev_child> watchers use a small hash table to distribute workload by 2096C<ev_child> watchers use a small hash table to distribute workload by
2081pid. The default size is C<16> (or C<1> with C<EV_MINIMAL>), usually more 2097pid. The default size is C<16> (or C<1> with C<EV_MINIMAL>), usually more
2082than enough. If you need to manage thousands of children you might want to 2098than enough. If you need to manage thousands of children you might want to
2083increase this value. 2099increase this value (I<must> be a power of two).
2100
2101=item EV_INOTIFY_HASHSIZE
2102
2103C<ev_staz> watchers use a small hash table to distribute workload by
2104inotify watch id. The default size is C<16> (or C<1> with C<EV_MINIMAL>),
2105usually more than enough. If you need to manage thousands of C<ev_stat>
2106watchers you might want to increase this value (I<must> be a power of
2107two).
2084 2108
2085=item EV_COMMON 2109=item EV_COMMON
2086 2110
2087By default, all watchers have a C<void *data> member. By redefining 2111By default, all watchers have a C<void *data> member. By redefining
2088this macro to a something else you can include more and other types of 2112this macro to a something else you can include more and other types of
… …
2148 2172
2149=item Starting io/check/prepare/idle/signal/child watchers: O(1) 2173=item Starting io/check/prepare/idle/signal/child watchers: O(1)
2150 2174
2151=item Stopping check/prepare/idle watchers: O(1) 2175=item Stopping check/prepare/idle watchers: O(1)
2152 2176
2153=item Stopping an io/signal/child watcher: O(number_of_watchers_for_this_(fd/signal/pid % 16)) 2177=item Stopping an io/signal/child watcher: O(number_of_watchers_for_this_(fd/signal/pid % EV_PID_HASHSIZE))
2154 2178
2155=item Finding the next timer per loop iteration: O(1) 2179=item Finding the next timer per loop iteration: O(1)
2156 2180
2157=item Each change on a file descriptor per loop iteration: O(number_of_watchers_for_this_fd) 2181=item Each change on a file descriptor per loop iteration: O(number_of_watchers_for_this_fd)
2158 2182

Diff Legend

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