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.67 by root, Fri Dec 7 16:44:12 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
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.
268 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 noticeable (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.
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,
273but if that fails, expect a fairly low limit on the number of fds when 295but if that fails, expect a fairly low limit on the number of fds when
407=item ev_loop_fork (loop) 429=item ev_loop_fork (loop)
408 430
409Like C<ev_default_fork>, but acts on an event loop created by 431Like C<ev_default_fork>, but acts on an event loop created by
410C<ev_loop_new>. Yes, you have to call this on every allocated event loop 432C<ev_loop_new>. Yes, you have to call this on every allocated event loop
411after fork, and how you do this is entirely your own problem. 433after fork, and how you do this is entirely your own problem.
434
435=item unsigned int ev_loop_count (loop)
436
437Returns the count of loop iterations for the loop, which is identical to
438the number of times libev did poll for new events. It starts at C<0> and
439happily wraps around with enough iterations.
440
441This value can sometimes be useful as a generation counter of sorts (it
442"ticks" the number of loop iterations), as it roughly corresponds with
443C<ev_prepare> and C<ev_check> calls.
412 444
413=item unsigned int ev_backend (loop) 445=item unsigned int ev_backend (loop)
414 446
415Returns one of the C<EVBACKEND_*> flags indicating the event backend in 447Returns one of the C<EVBACKEND_*> flags indicating the event backend in
416use. 448use.
712=item ev_cb_set (ev_TYPE *watcher, callback) 744=item ev_cb_set (ev_TYPE *watcher, callback)
713 745
714Change the callback. You can change the callback at virtually any time 746Change the callback. You can change the callback at virtually any time
715(modulo threads). 747(modulo threads).
716 748
749=item ev_set_priority (ev_TYPE *watcher, priority)
750
751=item int ev_priority (ev_TYPE *watcher)
752
753Set and query the priority of the watcher. The priority is a small
754integer between C<EV_MAXPRI> (default: C<2>) and C<EV_MINPRI>
755(default: C<-2>). Pending watchers with higher priority will be invoked
756before watchers with lower priority, but priority will not keep watchers
757from being executed (except for C<ev_idle> watchers).
758
759This means that priorities are I<only> used for ordering callback
760invocation after new events have been received. This is useful, for
761example, to reduce latency after idling, or more often, to bind two
762watchers on the same event and make sure one is called first.
763
764If you need to suppress invocation when higher priority events are pending
765you need to look at C<ev_idle> watchers, which provide this functionality.
766
767The default priority used by watchers when no priority has been set is
768always C<0>, which is supposed to not be too high and not be too low :).
769
770Setting a priority outside the range of C<EV_MINPRI> to C<EV_MAXPRI> is
771fine, as long as you do not mind that the priority value you query might
772or might not have been adjusted to be within valid range.
773
717=back 774=back
718 775
719 776
720=head2 ASSOCIATING CUSTOM DATA WITH A WATCHER 777=head2 ASSOCIATING CUSTOM DATA WITH A WATCHER
721 778
914=item ev_timer_again (loop) 971=item ev_timer_again (loop)
915 972
916This will act as if the timer timed out and restart it again if it is 973This will act as if the timer timed out and restart it again if it is
917repeating. The exact semantics are: 974repeating. The exact semantics are:
918 975
976If the timer is pending, its pending status is cleared.
977
919If the timer is started but nonrepeating, stop it. 978If the timer is started but nonrepeating, stop it (as if it timed out).
920 979
921If the timer is repeating, either start it if necessary (with the repeat 980If the timer is repeating, either start it if necessary (with the
922value), or reset the running timer to the repeat value. 981C<repeat> value), or reset the running timer to the C<repeat> value.
923 982
924This sounds a bit complicated, but here is a useful and typical 983This sounds a bit complicated, but here is a useful and typical
925example: Imagine you have a tcp connection and you want a so-called 984example: Imagine you have a tcp connection and you want a so-called idle
926idle timeout, that is, you want to be called when there have been, 985timeout, that is, you want to be called when there have been, say, 60
927say, 60 seconds of inactivity on the socket. The easiest way to do 986seconds of inactivity on the socket. The easiest way to do this is to
928this is to configure an C<ev_timer> with C<after>=C<repeat>=C<60> and calling 987configure an C<ev_timer> with a C<repeat> value of C<60> and then call
929C<ev_timer_again> each time you successfully read or write some data. If 988C<ev_timer_again> each time you successfully read or write some data. If
930you go into an idle state where you do not expect data to travel on the 989you go into an idle state where you do not expect data to travel on the
931socket, you can stop the timer, and again will automatically restart it if 990socket, you can C<ev_timer_stop> the timer, and C<ev_timer_again> will
932need be. 991automatically restart it if need be.
933 992
934You can also ignore the C<after> value and C<ev_timer_start> altogether 993That means you can ignore the C<after> value and C<ev_timer_start>
935and only ever use the C<repeat> value: 994altogether and only ever use the C<repeat> value and C<ev_timer_again>:
936 995
937 ev_timer_init (timer, callback, 0., 5.); 996 ev_timer_init (timer, callback, 0., 5.);
938 ev_timer_again (loop, timer); 997 ev_timer_again (loop, timer);
939 ... 998 ...
940 timer->again = 17.; 999 timer->again = 17.;
941 ev_timer_again (loop, timer); 1000 ev_timer_again (loop, timer);
942 ... 1001 ...
943 timer->again = 10.; 1002 timer->again = 10.;
944 ev_timer_again (loop, timer); 1003 ev_timer_again (loop, timer);
945 1004
946This is more efficient then stopping/starting the timer eahc time you want 1005This is more slightly efficient then stopping/starting the timer each time
947to modify its timeout value. 1006you want to modify its timeout value.
948 1007
949=item ev_tstamp repeat [read-write] 1008=item ev_tstamp repeat [read-write]
950 1009
951The current C<repeat> value. Will be used each time the watcher times out 1010The current C<repeat> value. Will be used each time the watcher times out
952or C<ev_timer_again> is called and determines the next timeout (if any), 1011or C<ev_timer_again> is called and determines the next timeout (if any),
1221not exist" is a status change like any other. The condition "path does 1280not 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 1281not 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 1282otherwise always forced to be at least one) and all the other fields of
1224the stat buffer having unspecified contents. 1283the stat buffer having unspecified contents.
1225 1284
1285The path I<should> be absolute and I<must not> end in a slash. If it is
1286relative and your working directory changes, the behaviour is undefined.
1287
1226Since there is no standard to do this, the portable implementation simply 1288Since 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 1289calls 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 1290can specify a recommended polling interval for this case. If you specify
1229a polling interval of C<0> (highly recommended!) then a I<suitable, 1291a polling interval of C<0> (highly recommended!) then a I<suitable,
1230unspecified default> value will be used (which you can expect to be around 1292unspecified default> value will be used (which you can expect to be around
1231five seconds, although this might change dynamically). Libev will also 1293five seconds, although this might change dynamically). Libev will also
1232impose a minimum interval which is currently around C<0.1>, but thats 1294impose a minimum interval which is currently around C<0.1>, but thats
1234 1296
1235This watcher type is not meant for massive numbers of stat watchers, 1297This watcher type is not meant for massive numbers of stat watchers,
1236as even with OS-supported change notifications, this can be 1298as even with OS-supported change notifications, this can be
1237resource-intensive. 1299resource-intensive.
1238 1300
1239At the time of this writing, no specific OS backends are implemented, but 1301At the time of this writing, only the Linux inotify interface is
1240if demand increases, at least a kqueue and inotify backend will be added. 1302implemented (implementing kqueue support is left as an exercise for the
1303reader). Inotify will be used to give hints only and should not change the
1304semantics of C<ev_stat> watchers, which means that libev sometimes needs
1305to fall back to regular polling again even with inotify, but changes are
1306usually detected immediately, and if the file exists there will be no
1307polling.
1241 1308
1242=over 4 1309=over 4
1243 1310
1244=item ev_stat_init (ev_stat *, callback, const char *path, ev_tstamp interval) 1311=item ev_stat_init (ev_stat *, callback, const char *path, ev_tstamp interval)
1245 1312
1309 ev_stat_start (loop, &passwd); 1376 ev_stat_start (loop, &passwd);
1310 1377
1311 1378
1312=head2 C<ev_idle> - when you've got nothing better to do... 1379=head2 C<ev_idle> - when you've got nothing better to do...
1313 1380
1314Idle watchers trigger events when there are no other events are pending 1381Idle watchers trigger events when no other events of the same or higher
1315(prepare, check and other idle watchers do not count). That is, as long 1382priority are pending (prepare, check and other idle watchers do not
1316as your process is busy handling sockets or timeouts (or even signals, 1383count).
1317imagine) it will not be triggered. But when your process is idle all idle 1384
1318watchers are being called again and again, once per event loop iteration - 1385That is, as long as your process is busy handling sockets or timeouts
1386(or even signals, imagine) of the same or higher priority it will not be
1387triggered. But when your process is idle (or only lower-priority watchers
1388are pending), the idle watchers are being called once per event loop
1319until stopped, that is, or your process receives more events and becomes 1389iteration - until stopped, that is, or your process receives more events
1320busy. 1390and becomes busy again with higher priority stuff.
1321 1391
1322The most noteworthy effect is that as long as any idle watchers are 1392The most noteworthy effect is that as long as any idle watchers are
1323active, the process will not block when waiting for new events. 1393active, the process will not block when waiting for new events.
1324 1394
1325Apart from keeping your process non-blocking (which is a useful 1395Apart from keeping your process non-blocking (which is a useful
1425 1495
1426 // create io watchers for each fd and a timer before blocking 1496 // create io watchers for each fd and a timer before blocking
1427 static void 1497 static void
1428 adns_prepare_cb (ev_loop *loop, ev_prepare *w, int revents) 1498 adns_prepare_cb (ev_loop *loop, ev_prepare *w, int revents)
1429 { 1499 {
1430 int timeout = 3600000;truct pollfd fds [nfd]; 1500 int timeout = 3600000;
1501 struct pollfd fds [nfd];
1431 // actual code will need to loop here and realloc etc. 1502 // actual code will need to loop here and realloc etc.
1432 adns_beforepoll (ads, fds, &nfd, &timeout, timeval_from (ev_time ())); 1503 adns_beforepoll (ads, fds, &nfd, &timeout, timeval_from (ev_time ()));
1433 1504
1434 /* the callback is illegal, but won't be called as we stop during check */ 1505 /* the callback is illegal, but won't be called as we stop during check */
1435 ev_timer_init (&tw, 0, timeout * 1e-3); 1506 ev_timer_init (&tw, 0, timeout * 1e-3);
1816Similar to the other two macros, this gives you the value of the default 1887Similar to the other two macros, this gives you the value of the default
1817loop, if multiple loops are supported ("ev loop default"). 1888loop, if multiple loops are supported ("ev loop default").
1818 1889
1819=back 1890=back
1820 1891
1821Example: Declare and initialise a check watcher, working regardless of 1892Example: Declare and initialise a check watcher, utilising the above
1822wether multiple loops are supported or not. 1893macros so it will work regardless of wether multiple loops are supported
1894or not.
1823 1895
1824 static void 1896 static void
1825 check_cb (EV_P_ ev_timer *w, int revents) 1897 check_cb (EV_P_ ev_timer *w, int revents)
1826 { 1898 {
1827 ev_check_stop (EV_A_ w); 1899 ev_check_stop (EV_A_ w);
1829 1901
1830 ev_check check; 1902 ev_check check;
1831 ev_check_init (&check, check_cb); 1903 ev_check_init (&check, check_cb);
1832 ev_check_start (EV_DEFAULT_ &check); 1904 ev_check_start (EV_DEFAULT_ &check);
1833 ev_loop (EV_DEFAULT_ 0); 1905 ev_loop (EV_DEFAULT_ 0);
1834
1835 1906
1836=head1 EMBEDDING 1907=head1 EMBEDDING
1837 1908
1838Libev can (and often is) directly embedded into host 1909Libev can (and often is) directly embedded into host
1839applications. Examples of applications that embed it include the Deliantra 1910applications. Examples of applications that embed it include the Deliantra
1879 ev_vars.h 1950 ev_vars.h
1880 ev_wrap.h 1951 ev_wrap.h
1881 1952
1882 ev_win32.c required on win32 platforms only 1953 ev_win32.c required on win32 platforms only
1883 1954
1884 ev_select.c only when select backend is enabled (which is by default) 1955 ev_select.c only when select backend is enabled (which is enabled by default)
1885 ev_poll.c only when poll backend is enabled (disabled by default) 1956 ev_poll.c only when poll backend is enabled (disabled by default)
1886 ev_epoll.c only when the epoll backend is enabled (disabled by default) 1957 ev_epoll.c only when the epoll backend is enabled (disabled by default)
1887 ev_kqueue.c only when the kqueue backend is enabled (disabled by default) 1958 ev_kqueue.c only when the kqueue backend is enabled (disabled by default)
1888 ev_port.c only when the solaris port backend is enabled (disabled by default) 1959 ev_port.c only when the solaris port backend is enabled (disabled by default)
1889 1960
2014 2085
2015=item EV_USE_DEVPOLL 2086=item EV_USE_DEVPOLL
2016 2087
2017reserved for future expansion, works like the USE symbols above. 2088reserved for future expansion, works like the USE symbols above.
2018 2089
2090=item EV_USE_INOTIFY
2091
2092If defined to be C<1>, libev will compile in support for the Linux inotify
2093interface to speed up C<ev_stat> watchers. Its actual availability will
2094be detected at runtime.
2095
2019=item EV_H 2096=item EV_H
2020 2097
2021The name of the F<ev.h> header file used to include it. The default if 2098The 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 2099undefined 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. 2100can be used to virtually rename the F<ev.h> header file in case of conflicts.
2052 2129
2053If undefined or defined to be C<1>, then periodic timers are supported. If 2130If undefined or defined to be C<1>, then periodic timers are supported. If
2054defined to be C<0>, then they are not. Disabling them saves a few kB of 2131defined to be C<0>, then they are not. Disabling them saves a few kB of
2055code. 2132code.
2056 2133
2134=item EV_IDLE_ENABLE
2135
2136If undefined or defined to be C<1>, then idle watchers are supported. If
2137defined to be C<0>, then they are not. Disabling them saves a few kB of
2138code.
2139
2057=item EV_EMBED_ENABLE 2140=item EV_EMBED_ENABLE
2058 2141
2059If undefined or defined to be C<1>, then embed watchers are supported. If 2142If undefined or defined to be C<1>, then embed watchers are supported. If
2060defined to be C<0>, then they are not. 2143defined to be C<0>, then they are not.
2061 2144
2078=item EV_PID_HASHSIZE 2161=item EV_PID_HASHSIZE
2079 2162
2080C<ev_child> watchers use a small hash table to distribute workload by 2163C<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 2164pid. 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 2165than enough. If you need to manage thousands of children you might want to
2083increase this value. 2166increase this value (I<must> be a power of two).
2167
2168=item EV_INOTIFY_HASHSIZE
2169
2170C<ev_staz> watchers use a small hash table to distribute workload by
2171inotify watch id. The default size is C<16> (or C<1> with C<EV_MINIMAL>),
2172usually more than enough. If you need to manage thousands of C<ev_stat>
2173watchers you might want to increase this value (I<must> be a power of
2174two).
2084 2175
2085=item EV_COMMON 2176=item EV_COMMON
2086 2177
2087By default, all watchers have a C<void *data> member. By redefining 2178By 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 2179this macro to a something else you can include more and other types of
2117interface) and F<EV.xs> (implementation) files. Only the F<EV.xs> file 2208interface) and F<EV.xs> (implementation) files. Only the F<EV.xs> file
2118will be compiled. It is pretty complex because it provides its own header 2209will be compiled. It is pretty complex because it provides its own header
2119file. 2210file.
2120 2211
2121The usage in rxvt-unicode is simpler. It has a F<ev_cpp.h> header file 2212The usage in rxvt-unicode is simpler. It has a F<ev_cpp.h> header file
2122that everybody includes and which overrides some autoconf choices: 2213that everybody includes and which overrides some configure choices:
2123 2214
2215 #define EV_MINIMAL 1
2124 #define EV_USE_POLL 0 2216 #define EV_USE_POLL 0
2125 #define EV_MULTIPLICITY 0 2217 #define EV_MULTIPLICITY 0
2126 #define EV_PERIODICS 0 2218 #define EV_PERIODIC_ENABLE 0
2219 #define EV_STAT_ENABLE 0
2220 #define EV_FORK_ENABLE 0
2127 #define EV_CONFIG_H <config.h> 2221 #define EV_CONFIG_H <config.h>
2222 #define EV_MINPRI 0
2223 #define EV_MAXPRI 0
2128 2224
2129 #include "ev++.h" 2225 #include "ev++.h"
2130 2226
2131And a F<ev_cpp.C> implementation file that contains libev proper and is compiled: 2227And a F<ev_cpp.C> implementation file that contains libev proper and is compiled:
2132 2228
2148 2244
2149=item Starting io/check/prepare/idle/signal/child watchers: O(1) 2245=item Starting io/check/prepare/idle/signal/child watchers: O(1)
2150 2246
2151=item Stopping check/prepare/idle watchers: O(1) 2247=item Stopping check/prepare/idle watchers: O(1)
2152 2248
2153=item Stopping an io/signal/child watcher: O(number_of_watchers_for_this_(fd/signal/pid % 16)) 2249=item Stopping an io/signal/child watcher: O(number_of_watchers_for_this_(fd/signal/pid % EV_PID_HASHSIZE))
2154 2250
2155=item Finding the next timer per loop iteration: O(1) 2251=item Finding the next timer per loop iteration: O(1)
2156 2252
2157=item Each change on a file descriptor per loop iteration: O(number_of_watchers_for_this_fd) 2253=item Each change on a file descriptor per loop iteration: O(number_of_watchers_for_this_fd)
2158 2254

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines