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

Comparing libev/ev.pod (file contents):
Revision 1.54 by root, Tue Nov 27 20:26:51 2007 UTC vs.
Revision 1.58 by root, Wed Nov 28 11:31:34 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
… …
703events but its callback has not yet been invoked). As long as a watcher 704events but its callback has not yet been invoked). As long as a watcher
704is pending (but not active) you must not call an init function on it (but 705is pending (but not active) you must not call an init function on it (but
705C<ev_TYPE_set> is safe) and you must make sure the watcher is available to 706C<ev_TYPE_set> is safe) and you must make sure the watcher is available to
706libev (e.g. you cnanot C<free ()> it). 707libev (e.g. you cnanot C<free ()> it).
707 708
708=item callback = ev_cb (ev_TYPE *watcher) 709=item callback ev_cb (ev_TYPE *watcher)
709 710
710Returns the callback currently set on the watcher. 711Returns the callback currently set on the watcher.
711 712
712=item ev_cb_set (ev_TYPE *watcher, callback) 713=item ev_cb_set (ev_TYPE *watcher, callback)
713 714
… …
741 { 742 {
742 struct my_io *w = (struct my_io *)w_; 743 struct my_io *w = (struct my_io *)w_;
743 ... 744 ...
744 } 745 }
745 746
746More interesting and less C-conformant ways of catsing your callback type 747More interesting and less C-conformant ways of casting your callback type
747have been omitted.... 748instead have been omitted.
749
750Another common scenario is having some data structure with multiple
751watchers:
752
753 struct my_biggy
754 {
755 int some_data;
756 ev_timer t1;
757 ev_timer t2;
758 }
759
760In this case getting the pointer to C<my_biggy> is a bit more complicated,
761you need to use C<offsetof>:
762
763 #include <stddef.h>
764
765 static void
766 t1_cb (EV_P_ struct ev_timer *w, int revents)
767 {
768 struct my_biggy big = (struct my_biggy *
769 (((char *)w) - offsetof (struct my_biggy, t1));
770 }
771
772 static void
773 t2_cb (EV_P_ struct ev_timer *w, int revents)
774 {
775 struct my_biggy big = (struct my_biggy *
776 (((char *)w) - offsetof (struct my_biggy, t2));
777 }
748 778
749 779
750=head1 WATCHER TYPES 780=head1 WATCHER TYPES
751 781
752This section describes each watcher in detail, but will not repeat 782This section describes each watcher in detail, but will not repeat
… …
1193not exist" is signified by the C<st_nlink> field being zero (which is 1223not exist" is signified by the C<st_nlink> field being zero (which is
1194otherwise always forced to be at least one) and all the other fields of 1224otherwise always forced to be at least one) and all the other fields of
1195the stat buffer having unspecified contents. 1225the stat buffer having unspecified contents.
1196 1226
1197Since there is no standard to do this, the portable implementation simply 1227Since there is no standard to do this, the portable implementation simply
1198calls C<stat (2)> regulalry on the path to see if it changed somehow. You 1228calls C<stat (2)> regularly on the path to see if it changed somehow. You
1199can specify a recommended polling interval for this case. If you specify 1229can specify a recommended polling interval for this case. If you specify
1200a polling interval of C<0> (highly recommended!) then a I<suitable, 1230a polling interval of C<0> (highly recommended!) then a I<suitable,
1201unspecified default> value will be used (which you can expect to be around 1231unspecified default> value will be used (which you can expect to be around
1202five seconds, although this might change dynamically). Libev will also 1232five seconds, although this might change dynamically). Libev will also
1203impose a minimum interval which is currently around C<0.1>, but thats 1233impose a minimum interval which is currently around C<0.1>, but thats
… …
1205 1235
1206This watcher type is not meant for massive numbers of stat watchers, 1236This watcher type is not meant for massive numbers of stat watchers,
1207as even with OS-supported change notifications, this can be 1237as even with OS-supported change notifications, this can be
1208resource-intensive. 1238resource-intensive.
1209 1239
1210At the time of this writing, no specific OS backends are implemented, but 1240At the time of this writing, only the Linux inotify interface is
1211if demand increases, at least a kqueue and inotify backend will be added. 1241implemented (implementing kqueue support is left as an exercise for the
1242reader). Inotify will be used to give hints only and should not change the
1243semantics of C<ev_stat> watchers, which means that libev sometimes needs
1244to fall back to regular polling again even with inotify, but changes are
1245usually detected immediately, and if the file exists there will be no
1246polling.
1212 1247
1213=over 4 1248=over 4
1214 1249
1215=item ev_stat_init (ev_stat *, callback, const char *path, ev_tstamp interval) 1250=item ev_stat_init (ev_stat *, callback, const char *path, ev_tstamp interval)
1216 1251
… …
1985 2020
1986=item EV_USE_DEVPOLL 2021=item EV_USE_DEVPOLL
1987 2022
1988reserved for future expansion, works like the USE symbols above. 2023reserved for future expansion, works like the USE symbols above.
1989 2024
2025=item EV_USE_INOTIFY
2026
2027If defined to be C<1>, libev will compile in support for the Linux inotify
2028interface to speed up C<ev_stat> watchers. Its actual availability will
2029be detected at runtime.
2030
1990=item EV_H 2031=item EV_H
1991 2032
1992The name of the F<ev.h> header file used to include it. The default if 2033The name of the F<ev.h> header file used to include it. The default if
1993undefined is C<< <ev.h> >> in F<event.h> and C<"ev.h"> in F<ev.c>. This 2034undefined is C<< <ev.h> >> in F<event.h> and C<"ev.h"> in F<ev.c>. This
1994can be used to virtually rename the F<ev.h> header file in case of conflicts. 2035can be used to virtually rename the F<ev.h> header file in case of conflicts.
… …
2049=item EV_PID_HASHSIZE 2090=item EV_PID_HASHSIZE
2050 2091
2051C<ev_child> watchers use a small hash table to distribute workload by 2092C<ev_child> watchers use a small hash table to distribute workload by
2052pid. The default size is C<16> (or C<1> with C<EV_MINIMAL>), usually more 2093pid. The default size is C<16> (or C<1> with C<EV_MINIMAL>), usually more
2053than enough. If you need to manage thousands of children you might want to 2094than enough. If you need to manage thousands of children you might want to
2054increase this value. 2095increase this value (I<must> be a power of two).
2096
2097=item EV_INOTIFY_HASHSIZE
2098
2099C<ev_staz> watchers use a small hash table to distribute workload by
2100inotify watch id. The default size is C<16> (or C<1> with C<EV_MINIMAL>),
2101usually more than enough. If you need to manage thousands of C<ev_stat>
2102watchers you might want to increase this value (I<must> be a power of
2103two).
2055 2104
2056=item EV_COMMON 2105=item EV_COMMON
2057 2106
2058By default, all watchers have a C<void *data> member. By redefining 2107By default, all watchers have a C<void *data> member. By redefining
2059this macro to a something else you can include more and other types of 2108this macro to a something else you can include more and other types of
… …
2119 2168
2120=item Starting io/check/prepare/idle/signal/child watchers: O(1) 2169=item Starting io/check/prepare/idle/signal/child watchers: O(1)
2121 2170
2122=item Stopping check/prepare/idle watchers: O(1) 2171=item Stopping check/prepare/idle watchers: O(1)
2123 2172
2124=item Stopping an io/signal/child watcher: O(number_of_watchers_for_this_(fd/signal/pid % 16)) 2173=item Stopping an io/signal/child watcher: O(number_of_watchers_for_this_(fd/signal/pid % EV_PID_HASHSIZE))
2125 2174
2126=item Finding the next timer per loop iteration: O(1) 2175=item Finding the next timer per loop iteration: O(1)
2127 2176
2128=item Each change on a file descriptor per loop iteration: O(number_of_watchers_for_this_fd) 2177=item Each change on a file descriptor per loop iteration: O(number_of_watchers_for_this_fd)
2129 2178

Diff Legend

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