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.62 by root, Thu Nov 29 17:28:13 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
… …
263or setgid) then libev will I<not> look at the environment variable 265or setgid) then libev will I<not> look at the environment variable
264C<LIBEV_FLAGS>. Otherwise (the default), this environment variable will 266C<LIBEV_FLAGS>. Otherwise (the default), this environment variable will
265override the flags completely if it is found in the environment. This is 267override the flags completely if it is found in the environment. This is
266useful to try out specific backends to test their performance, or to work 268useful to try out specific backends to test their performance, or to work
267around bugs. 269around bugs.
270
271=item C<EVFLAG_FORKCHECK>
272
273Instead of calling C<ev_default_fork> or C<ev_loop_fork> manually after
274a fork, you can also make libev check for a fork in each iteration by
275enabling this flag.
276
277This works by calling C<getpid ()> on every iteration of the loop,
278and thus this might slow down your event loop if you do a lot of loop
279iterations and little real work, but is usually not noticable (on my
280Linux system for example, C<getpid> is actually a simple 5-insn sequence
281without a syscall and thus I<very> fast, but my Linux system also has
282C<pthread_atfork> which is even faster).
283
284The big advantage of this flag is that you can forget about fork (and
285forget about forgetting to tell libev about forking) when you use this
286flag.
287
288This flag setting cannot be overriden or specified in the C<LIBEV_FLAGS>
289environment variable.
268 290
269=item C<EVBACKEND_SELECT> (value 1, portable select backend) 291=item C<EVBACKEND_SELECT> (value 1, portable select backend)
270 292
271This is your standard select(2) backend. Not I<completely> standard, as 293This is your standard select(2) backend. Not I<completely> standard, as
272libev tries to roll its own fd_set with no limits on the number of fds, 294libev tries to roll its own fd_set with no limits on the number of fds,
… …
703events but its callback has not yet been invoked). As long as a watcher 725events 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 726is 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 727C<ev_TYPE_set> is safe) and you must make sure the watcher is available to
706libev (e.g. you cnanot C<free ()> it). 728libev (e.g. you cnanot C<free ()> it).
707 729
708=item callback = ev_cb (ev_TYPE *watcher) 730=item callback ev_cb (ev_TYPE *watcher)
709 731
710Returns the callback currently set on the watcher. 732Returns the callback currently set on the watcher.
711 733
712=item ev_cb_set (ev_TYPE *watcher, callback) 734=item ev_cb_set (ev_TYPE *watcher, callback)
713 735
… …
741 { 763 {
742 struct my_io *w = (struct my_io *)w_; 764 struct my_io *w = (struct my_io *)w_;
743 ... 765 ...
744 } 766 }
745 767
746More interesting and less C-conformant ways of catsing your callback type 768More interesting and less C-conformant ways of casting your callback type
747have been omitted.... 769instead have been omitted.
770
771Another common scenario is having some data structure with multiple
772watchers:
773
774 struct my_biggy
775 {
776 int some_data;
777 ev_timer t1;
778 ev_timer t2;
779 }
780
781In this case getting the pointer to C<my_biggy> is a bit more complicated,
782you need to use C<offsetof>:
783
784 #include <stddef.h>
785
786 static void
787 t1_cb (EV_P_ struct ev_timer *w, int revents)
788 {
789 struct my_biggy big = (struct my_biggy *
790 (((char *)w) - offsetof (struct my_biggy, t1));
791 }
792
793 static void
794 t2_cb (EV_P_ struct ev_timer *w, int revents)
795 {
796 struct my_biggy big = (struct my_biggy *
797 (((char *)w) - offsetof (struct my_biggy, t2));
798 }
748 799
749 800
750=head1 WATCHER TYPES 801=head1 WATCHER TYPES
751 802
752This section describes each watcher in detail, but will not repeat 803This section describes each watcher in detail, but will not repeat
… …
885=item ev_timer_again (loop) 936=item ev_timer_again (loop)
886 937
887This will act as if the timer timed out and restart it again if it is 938This will act as if the timer timed out and restart it again if it is
888repeating. The exact semantics are: 939repeating. The exact semantics are:
889 940
941If the timer is pending, its pending status is cleared.
942
890If the timer is started but nonrepeating, stop it. 943If the timer is started but nonrepeating, stop it (as if it timed out).
891 944
892If the timer is repeating, either start it if necessary (with the repeat 945If the timer is repeating, either start it if necessary (with the
893value), or reset the running timer to the repeat value. 946C<repeat> value), or reset the running timer to the C<repeat> value.
894 947
895This sounds a bit complicated, but here is a useful and typical 948This sounds a bit complicated, but here is a useful and typical
896example: Imagine you have a tcp connection and you want a so-called 949example: Imagine you have a tcp connection and you want a so-called idle
897idle timeout, that is, you want to be called when there have been, 950timeout, that is, you want to be called when there have been, say, 60
898say, 60 seconds of inactivity on the socket. The easiest way to do 951seconds of inactivity on the socket. The easiest way to do this is to
899this is to configure an C<ev_timer> with C<after>=C<repeat>=C<60> and calling 952configure an C<ev_timer> with a C<repeat> value of C<60> and then call
900C<ev_timer_again> each time you successfully read or write some data. If 953C<ev_timer_again> each time you successfully read or write some data. If
901you go into an idle state where you do not expect data to travel on the 954you go into an idle state where you do not expect data to travel on the
902socket, you can stop the timer, and again will automatically restart it if 955socket, you can C<ev_timer_stop> the timer, and C<ev_timer_again> will
903need be. 956automatically restart it if need be.
904 957
905You can also ignore the C<after> value and C<ev_timer_start> altogether 958That means you can ignore the C<after> value and C<ev_timer_start>
906and only ever use the C<repeat> value: 959altogether and only ever use the C<repeat> value and C<ev_timer_again>:
907 960
908 ev_timer_init (timer, callback, 0., 5.); 961 ev_timer_init (timer, callback, 0., 5.);
909 ev_timer_again (loop, timer); 962 ev_timer_again (loop, timer);
910 ... 963 ...
911 timer->again = 17.; 964 timer->again = 17.;
912 ev_timer_again (loop, timer); 965 ev_timer_again (loop, timer);
913 ... 966 ...
914 timer->again = 10.; 967 timer->again = 10.;
915 ev_timer_again (loop, timer); 968 ev_timer_again (loop, timer);
916 969
917This is more efficient then stopping/starting the timer eahc time you want 970This is more slightly efficient then stopping/starting the timer each time
918to modify its timeout value. 971you want to modify its timeout value.
919 972
920=item ev_tstamp repeat [read-write] 973=item ev_tstamp repeat [read-write]
921 974
922The current C<repeat> value. Will be used each time the watcher times out 975The current C<repeat> value. Will be used each time the watcher times out
923or C<ev_timer_again> is called and determines the next timeout (if any), 976or C<ev_timer_again> is called and determines the next timeout (if any),
… …
1192not exist" is a status change like any other. The condition "path does 1245not exist" is a status change like any other. The condition "path does
1193not exist" is signified by the C<st_nlink> field being zero (which is 1246not 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 1247otherwise always forced to be at least one) and all the other fields of
1195the stat buffer having unspecified contents. 1248the stat buffer having unspecified contents.
1196 1249
1250The path I<should> be absolute and I<must not> end in a slash. If it is
1251relative and your working directory changes, the behaviour is undefined.
1252
1197Since there is no standard to do this, the portable implementation simply 1253Since 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 1254calls 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 1255can specify a recommended polling interval for this case. If you specify
1200a polling interval of C<0> (highly recommended!) then a I<suitable, 1256a polling interval of C<0> (highly recommended!) then a I<suitable,
1201unspecified default> value will be used (which you can expect to be around 1257unspecified default> value will be used (which you can expect to be around
1202five seconds, although this might change dynamically). Libev will also 1258five seconds, although this might change dynamically). Libev will also
1203impose a minimum interval which is currently around C<0.1>, but thats 1259impose a minimum interval which is currently around C<0.1>, but thats
… …
1205 1261
1206This watcher type is not meant for massive numbers of stat watchers, 1262This watcher type is not meant for massive numbers of stat watchers,
1207as even with OS-supported change notifications, this can be 1263as even with OS-supported change notifications, this can be
1208resource-intensive. 1264resource-intensive.
1209 1265
1210At the time of this writing, no specific OS backends are implemented, but 1266At the time of this writing, only the Linux inotify interface is
1211if demand increases, at least a kqueue and inotify backend will be added. 1267implemented (implementing kqueue support is left as an exercise for the
1268reader). Inotify will be used to give hints only and should not change the
1269semantics of C<ev_stat> watchers, which means that libev sometimes needs
1270to fall back to regular polling again even with inotify, but changes are
1271usually detected immediately, and if the file exists there will be no
1272polling.
1212 1273
1213=over 4 1274=over 4
1214 1275
1215=item ev_stat_init (ev_stat *, callback, const char *path, ev_tstamp interval) 1276=item ev_stat_init (ev_stat *, callback, const char *path, ev_tstamp interval)
1216 1277
… …
1985 2046
1986=item EV_USE_DEVPOLL 2047=item EV_USE_DEVPOLL
1987 2048
1988reserved for future expansion, works like the USE symbols above. 2049reserved for future expansion, works like the USE symbols above.
1989 2050
2051=item EV_USE_INOTIFY
2052
2053If defined to be C<1>, libev will compile in support for the Linux inotify
2054interface to speed up C<ev_stat> watchers. Its actual availability will
2055be detected at runtime.
2056
1990=item EV_H 2057=item EV_H
1991 2058
1992The name of the F<ev.h> header file used to include it. The default if 2059The 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 2060undefined 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. 2061can be used to virtually rename the F<ev.h> header file in case of conflicts.
… …
2049=item EV_PID_HASHSIZE 2116=item EV_PID_HASHSIZE
2050 2117
2051C<ev_child> watchers use a small hash table to distribute workload by 2118C<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 2119pid. 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 2120than enough. If you need to manage thousands of children you might want to
2054increase this value. 2121increase this value (I<must> be a power of two).
2122
2123=item EV_INOTIFY_HASHSIZE
2124
2125C<ev_staz> watchers use a small hash table to distribute workload by
2126inotify watch id. The default size is C<16> (or C<1> with C<EV_MINIMAL>),
2127usually more than enough. If you need to manage thousands of C<ev_stat>
2128watchers you might want to increase this value (I<must> be a power of
2129two).
2055 2130
2056=item EV_COMMON 2131=item EV_COMMON
2057 2132
2058By default, all watchers have a C<void *data> member. By redefining 2133By 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 2134this macro to a something else you can include more and other types of
… …
2119 2194
2120=item Starting io/check/prepare/idle/signal/child watchers: O(1) 2195=item Starting io/check/prepare/idle/signal/child watchers: O(1)
2121 2196
2122=item Stopping check/prepare/idle watchers: O(1) 2197=item Stopping check/prepare/idle watchers: O(1)
2123 2198
2124=item Stopping an io/signal/child watcher: O(number_of_watchers_for_this_(fd/signal/pid % 16)) 2199=item Stopping an io/signal/child watcher: O(number_of_watchers_for_this_(fd/signal/pid % EV_PID_HASHSIZE))
2125 2200
2126=item Finding the next timer per loop iteration: O(1) 2201=item Finding the next timer per loop iteration: O(1)
2127 2202
2128=item Each change on a file descriptor per loop iteration: O(number_of_watchers_for_this_fd) 2203=item Each change on a file descriptor per loop iteration: O(number_of_watchers_for_this_fd)
2129 2204

Diff Legend

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