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

Comparing libev/ev.pod (file contents):
Revision 1.58 by root, Wed Nov 28 11:31:34 2007 UTC vs.
Revision 1.69 by root, Fri Dec 7 19:15:39 2007 UTC

47 47
48 return 0; 48 return 0;
49 } 49 }
50 50
51=head1 DESCRIPTION 51=head1 DESCRIPTION
52
53The newest version of this document is also available as a html-formatted
54web page you might find easier to navigate when reading it for the first
55time: L<http://cvs.schmorp.de/libev/ev.html>.
52 56
53Libev is an event loop: you register interest in certain events (such as a 57Libev is an event loop: you register interest in certain events (such as a
54file descriptor being readable or a timeout occuring), and it will manage 58file descriptor being readable or a timeout occuring), and it will manage
55these event sources and provide your program with events. 59these event sources and provide your program with events.
56 60
163C<ev_embeddable_backends () & ev_supported_backends ()>, likewise for 167C<ev_embeddable_backends () & ev_supported_backends ()>, likewise for
164recommended ones. 168recommended ones.
165 169
166See the description of C<ev_embed> watchers for more info. 170See the description of C<ev_embed> watchers for more info.
167 171
168=item ev_set_allocator (void *(*cb)(void *ptr, size_t size)) 172=item ev_set_allocator (void *(*cb)(void *ptr, long size))
169 173
170Sets the allocation function to use (the prototype and semantics are 174Sets the allocation function to use (the prototype is similar - the
171identical to the realloc C function). It is used to allocate and free 175semantics is identical - to the realloc C function). It is used to
172memory (no surprises here). If it returns zero when memory needs to be 176allocate and free memory (no surprises here). If it returns zero when
173allocated, the library might abort or take some potentially destructive 177memory needs to be allocated, the library might abort or take some
174action. The default is your system realloc function. 178potentially destructive action. The default is your system realloc
179function.
175 180
176You could override this function in high-availability programs to, say, 181You could override this function in high-availability programs to, say,
177free some memory if it cannot allocate memory, to use a special allocator, 182free some memory if it cannot allocate memory, to use a special allocator,
178or even to sleep a while and retry until some memory is available. 183or even to sleep a while and retry until some memory is available.
179 184
265C<LIBEV_FLAGS>. Otherwise (the default), this environment variable will 270C<LIBEV_FLAGS>. Otherwise (the default), this environment variable will
266override the flags completely if it is found in the environment. This is 271override the flags completely if it is found in the environment. This is
267useful to try out specific backends to test their performance, or to work 272useful to try out specific backends to test their performance, or to work
268around bugs. 273around bugs.
269 274
275=item C<EVFLAG_FORKCHECK>
276
277Instead of calling C<ev_default_fork> or C<ev_loop_fork> manually after
278a fork, you can also make libev check for a fork in each iteration by
279enabling this flag.
280
281This works by calling C<getpid ()> on every iteration of the loop,
282and thus this might slow down your event loop if you do a lot of loop
283iterations and little real work, but is usually not noticeable (on my
284Linux system for example, C<getpid> is actually a simple 5-insn sequence
285without a syscall and thus I<very> fast, but my Linux system also has
286C<pthread_atfork> which is even faster).
287
288The big advantage of this flag is that you can forget about fork (and
289forget about forgetting to tell libev about forking) when you use this
290flag.
291
292This flag setting cannot be overriden or specified in the C<LIBEV_FLAGS>
293environment variable.
294
270=item C<EVBACKEND_SELECT> (value 1, portable select backend) 295=item C<EVBACKEND_SELECT> (value 1, portable select backend)
271 296
272This is your standard select(2) backend. Not I<completely> standard, as 297This is your standard select(2) backend. Not I<completely> standard, as
273libev tries to roll its own fd_set with no limits on the number of fds, 298libev tries to roll its own fd_set with no limits on the number of fds,
274but if that fails, expect a fairly low limit on the number of fds when 299but if that fails, expect a fairly low limit on the number of fds when
408=item ev_loop_fork (loop) 433=item ev_loop_fork (loop)
409 434
410Like C<ev_default_fork>, but acts on an event loop created by 435Like C<ev_default_fork>, but acts on an event loop created by
411C<ev_loop_new>. Yes, you have to call this on every allocated event loop 436C<ev_loop_new>. Yes, you have to call this on every allocated event loop
412after fork, and how you do this is entirely your own problem. 437after fork, and how you do this is entirely your own problem.
438
439=item unsigned int ev_loop_count (loop)
440
441Returns the count of loop iterations for the loop, which is identical to
442the number of times libev did poll for new events. It starts at C<0> and
443happily wraps around with enough iterations.
444
445This value can sometimes be useful as a generation counter of sorts (it
446"ticks" the number of loop iterations), as it roughly corresponds with
447C<ev_prepare> and C<ev_check> calls.
413 448
414=item unsigned int ev_backend (loop) 449=item unsigned int ev_backend (loop)
415 450
416Returns one of the C<EVBACKEND_*> flags indicating the event backend in 451Returns one of the C<EVBACKEND_*> flags indicating the event backend in
417use. 452use.
713=item ev_cb_set (ev_TYPE *watcher, callback) 748=item ev_cb_set (ev_TYPE *watcher, callback)
714 749
715Change the callback. You can change the callback at virtually any time 750Change the callback. You can change the callback at virtually any time
716(modulo threads). 751(modulo threads).
717 752
753=item ev_set_priority (ev_TYPE *watcher, priority)
754
755=item int ev_priority (ev_TYPE *watcher)
756
757Set and query the priority of the watcher. The priority is a small
758integer between C<EV_MAXPRI> (default: C<2>) and C<EV_MINPRI>
759(default: C<-2>). Pending watchers with higher priority will be invoked
760before watchers with lower priority, but priority will not keep watchers
761from being executed (except for C<ev_idle> watchers).
762
763This means that priorities are I<only> used for ordering callback
764invocation after new events have been received. This is useful, for
765example, to reduce latency after idling, or more often, to bind two
766watchers on the same event and make sure one is called first.
767
768If you need to suppress invocation when higher priority events are pending
769you need to look at C<ev_idle> watchers, which provide this functionality.
770
771The default priority used by watchers when no priority has been set is
772always C<0>, which is supposed to not be too high and not be too low :).
773
774Setting a priority outside the range of C<EV_MINPRI> to C<EV_MAXPRI> is
775fine, as long as you do not mind that the priority value you query might
776or might not have been adjusted to be within valid range.
777
718=back 778=back
719 779
720 780
721=head2 ASSOCIATING CUSTOM DATA WITH A WATCHER 781=head2 ASSOCIATING CUSTOM DATA WITH A WATCHER
722 782
827it is best to always use non-blocking I/O: An extra C<read>(2) returning 887it is best to always use non-blocking I/O: An extra C<read>(2) returning
828C<EAGAIN> is far preferable to a program hanging until some data arrives. 888C<EAGAIN> is far preferable to a program hanging until some data arrives.
829 889
830If you cannot run the fd in non-blocking mode (for example you should not 890If you cannot run the fd in non-blocking mode (for example you should not
831play around with an Xlib connection), then you have to seperately re-test 891play around with an Xlib connection), then you have to seperately re-test
832wether a file descriptor is really ready with a known-to-be good interface 892whether a file descriptor is really ready with a known-to-be good interface
833such as poll (fortunately in our Xlib example, Xlib already does this on 893such as poll (fortunately in our Xlib example, Xlib already does this on
834its own, so its quite safe to use). 894its own, so its quite safe to use).
835 895
836=over 4 896=over 4
837 897
915=item ev_timer_again (loop) 975=item ev_timer_again (loop)
916 976
917This will act as if the timer timed out and restart it again if it is 977This will act as if the timer timed out and restart it again if it is
918repeating. The exact semantics are: 978repeating. The exact semantics are:
919 979
980If the timer is pending, its pending status is cleared.
981
920If the timer is started but nonrepeating, stop it. 982If the timer is started but nonrepeating, stop it (as if it timed out).
921 983
922If the timer is repeating, either start it if necessary (with the repeat 984If the timer is repeating, either start it if necessary (with the
923value), or reset the running timer to the repeat value. 985C<repeat> value), or reset the running timer to the C<repeat> value.
924 986
925This sounds a bit complicated, but here is a useful and typical 987This sounds a bit complicated, but here is a useful and typical
926example: Imagine you have a tcp connection and you want a so-called 988example: Imagine you have a tcp connection and you want a so-called idle
927idle timeout, that is, you want to be called when there have been, 989timeout, that is, you want to be called when there have been, say, 60
928say, 60 seconds of inactivity on the socket. The easiest way to do 990seconds of inactivity on the socket. The easiest way to do this is to
929this is to configure an C<ev_timer> with C<after>=C<repeat>=C<60> and calling 991configure an C<ev_timer> with a C<repeat> value of C<60> and then call
930C<ev_timer_again> each time you successfully read or write some data. If 992C<ev_timer_again> each time you successfully read or write some data. If
931you go into an idle state where you do not expect data to travel on the 993you go into an idle state where you do not expect data to travel on the
932socket, you can stop the timer, and again will automatically restart it if 994socket, you can C<ev_timer_stop> the timer, and C<ev_timer_again> will
933need be. 995automatically restart it if need be.
934 996
935You can also ignore the C<after> value and C<ev_timer_start> altogether 997That means you can ignore the C<after> value and C<ev_timer_start>
936and only ever use the C<repeat> value: 998altogether and only ever use the C<repeat> value and C<ev_timer_again>:
937 999
938 ev_timer_init (timer, callback, 0., 5.); 1000 ev_timer_init (timer, callback, 0., 5.);
939 ev_timer_again (loop, timer); 1001 ev_timer_again (loop, timer);
940 ... 1002 ...
941 timer->again = 17.; 1003 timer->again = 17.;
942 ev_timer_again (loop, timer); 1004 ev_timer_again (loop, timer);
943 ... 1005 ...
944 timer->again = 10.; 1006 timer->again = 10.;
945 ev_timer_again (loop, timer); 1007 ev_timer_again (loop, timer);
946 1008
947This is more efficient then stopping/starting the timer eahc time you want 1009This is more slightly efficient then stopping/starting the timer each time
948to modify its timeout value. 1010you want to modify its timeout value.
949 1011
950=item ev_tstamp repeat [read-write] 1012=item ev_tstamp repeat [read-write]
951 1013
952The current C<repeat> value. Will be used each time the watcher times out 1014The current C<repeat> value. Will be used each time the watcher times out
953or C<ev_timer_again> is called and determines the next timeout (if any), 1015or C<ev_timer_again> is called and determines the next timeout (if any),
1221The path does not need to exist: changing from "path exists" to "path does 1283The path does not need to exist: changing from "path exists" to "path does
1222not exist" is a status change like any other. The condition "path does 1284not exist" is a status change like any other. The condition "path does
1223not exist" is signified by the C<st_nlink> field being zero (which is 1285not exist" is signified by the C<st_nlink> field being zero (which is
1224otherwise always forced to be at least one) and all the other fields of 1286otherwise always forced to be at least one) and all the other fields of
1225the stat buffer having unspecified contents. 1287the stat buffer having unspecified contents.
1288
1289The path I<should> be absolute and I<must not> end in a slash. If it is
1290relative and your working directory changes, the behaviour is undefined.
1226 1291
1227Since there is no standard to do this, the portable implementation simply 1292Since there is no standard to do this, the portable implementation simply
1228calls C<stat (2)> regularly on the path to see if it changed somehow. You 1293calls C<stat (2)> regularly on the path to see if it changed somehow. You
1229can specify a recommended polling interval for this case. If you specify 1294can specify a recommended polling interval for this case. If you specify
1230a polling interval of C<0> (highly recommended!) then a I<suitable, 1295a polling interval of C<0> (highly recommended!) then a I<suitable,
1315 ev_stat_start (loop, &passwd); 1380 ev_stat_start (loop, &passwd);
1316 1381
1317 1382
1318=head2 C<ev_idle> - when you've got nothing better to do... 1383=head2 C<ev_idle> - when you've got nothing better to do...
1319 1384
1320Idle watchers trigger events when there are no other events are pending 1385Idle watchers trigger events when no other events of the same or higher
1321(prepare, check and other idle watchers do not count). That is, as long 1386priority are pending (prepare, check and other idle watchers do not
1322as your process is busy handling sockets or timeouts (or even signals, 1387count).
1323imagine) it will not be triggered. But when your process is idle all idle 1388
1324watchers are being called again and again, once per event loop iteration - 1389That is, as long as your process is busy handling sockets or timeouts
1390(or even signals, imagine) of the same or higher priority it will not be
1391triggered. But when your process is idle (or only lower-priority watchers
1392are pending), the idle watchers are being called once per event loop
1325until stopped, that is, or your process receives more events and becomes 1393iteration - until stopped, that is, or your process receives more events
1326busy. 1394and becomes busy again with higher priority stuff.
1327 1395
1328The most noteworthy effect is that as long as any idle watchers are 1396The most noteworthy effect is that as long as any idle watchers are
1329active, the process will not block when waiting for new events. 1397active, the process will not block when waiting for new events.
1330 1398
1331Apart from keeping your process non-blocking (which is a useful 1399Apart from keeping your process non-blocking (which is a useful
1431 1499
1432 // create io watchers for each fd and a timer before blocking 1500 // create io watchers for each fd and a timer before blocking
1433 static void 1501 static void
1434 adns_prepare_cb (ev_loop *loop, ev_prepare *w, int revents) 1502 adns_prepare_cb (ev_loop *loop, ev_prepare *w, int revents)
1435 { 1503 {
1436 int timeout = 3600000;truct pollfd fds [nfd]; 1504 int timeout = 3600000;
1505 struct pollfd fds [nfd];
1437 // actual code will need to loop here and realloc etc. 1506 // actual code will need to loop here and realloc etc.
1438 adns_beforepoll (ads, fds, &nfd, &timeout, timeval_from (ev_time ())); 1507 adns_beforepoll (ads, fds, &nfd, &timeout, timeval_from (ev_time ()));
1439 1508
1440 /* the callback is illegal, but won't be called as we stop during check */ 1509 /* the callback is illegal, but won't be called as we stop during check */
1441 ev_timer_init (&tw, 0, timeout * 1e-3); 1510 ev_timer_init (&tw, 0, timeout * 1e-3);
1779 1848
1780 1849
1781=head1 MACRO MAGIC 1850=head1 MACRO MAGIC
1782 1851
1783Libev can be compiled with a variety of options, the most fundemantal is 1852Libev can be compiled with a variety of options, the most fundemantal is
1784C<EV_MULTIPLICITY>. This option determines wether (most) functions and 1853C<EV_MULTIPLICITY>. This option determines whether (most) functions and
1785callbacks have an initial C<struct ev_loop *> argument. 1854callbacks have an initial C<struct ev_loop *> argument.
1786 1855
1787To make it easier to write programs that cope with either variant, the 1856To make it easier to write programs that cope with either variant, the
1788following macros are defined: 1857following macros are defined:
1789 1858
1822Similar to the other two macros, this gives you the value of the default 1891Similar to the other two macros, this gives you the value of the default
1823loop, if multiple loops are supported ("ev loop default"). 1892loop, if multiple loops are supported ("ev loop default").
1824 1893
1825=back 1894=back
1826 1895
1827Example: Declare and initialise a check watcher, working regardless of 1896Example: Declare and initialise a check watcher, utilising the above
1828wether multiple loops are supported or not. 1897macros so it will work regardless of whether multiple loops are supported
1898or not.
1829 1899
1830 static void 1900 static void
1831 check_cb (EV_P_ ev_timer *w, int revents) 1901 check_cb (EV_P_ ev_timer *w, int revents)
1832 { 1902 {
1833 ev_check_stop (EV_A_ w); 1903 ev_check_stop (EV_A_ w);
1836 ev_check check; 1906 ev_check check;
1837 ev_check_init (&check, check_cb); 1907 ev_check_init (&check, check_cb);
1838 ev_check_start (EV_DEFAULT_ &check); 1908 ev_check_start (EV_DEFAULT_ &check);
1839 ev_loop (EV_DEFAULT_ 0); 1909 ev_loop (EV_DEFAULT_ 0);
1840 1910
1841
1842=head1 EMBEDDING 1911=head1 EMBEDDING
1843 1912
1844Libev can (and often is) directly embedded into host 1913Libev can (and often is) directly embedded into host
1845applications. Examples of applications that embed it include the Deliantra 1914applications. Examples of applications that embed it include the Deliantra
1846Game Server, the EV perl module, the GNU Virtual Private Ethernet (gvpe) 1915Game Server, the EV perl module, the GNU Virtual Private Ethernet (gvpe)
1885 ev_vars.h 1954 ev_vars.h
1886 ev_wrap.h 1955 ev_wrap.h
1887 1956
1888 ev_win32.c required on win32 platforms only 1957 ev_win32.c required on win32 platforms only
1889 1958
1890 ev_select.c only when select backend is enabled (which is by default) 1959 ev_select.c only when select backend is enabled (which is enabled by default)
1891 ev_poll.c only when poll backend is enabled (disabled by default) 1960 ev_poll.c only when poll backend is enabled (disabled by default)
1892 ev_epoll.c only when the epoll backend is enabled (disabled by default) 1961 ev_epoll.c only when the epoll backend is enabled (disabled by default)
1893 ev_kqueue.c only when the kqueue backend is enabled (disabled by default) 1962 ev_kqueue.c only when the kqueue backend is enabled (disabled by default)
1894 ev_port.c only when the solaris port backend is enabled (disabled by default) 1963 ev_port.c only when the solaris port backend is enabled (disabled by default)
1895 1964
2058will have the C<struct ev_loop *> as first argument, and you can create 2127will have the C<struct ev_loop *> as first argument, and you can create
2059additional independent event loops. Otherwise there will be no support 2128additional independent event loops. Otherwise there will be no support
2060for multiple event loops and there is no first event loop pointer 2129for multiple event loops and there is no first event loop pointer
2061argument. Instead, all functions act on the single default loop. 2130argument. Instead, all functions act on the single default loop.
2062 2131
2132=item EV_MINPRI
2133
2134=item EV_MAXPRI
2135
2136The range of allowed priorities. C<EV_MINPRI> must be smaller or equal to
2137C<EV_MAXPRI>, but otherwise there are no non-obvious limitations. You can
2138provide for more priorities by overriding those symbols (usually defined
2139to be C<-2> and C<2>, respectively).
2140
2141When doing priority-based operations, libev usually has to linearly search
2142all the priorities, so having many of them (hundreds) uses a lot of space
2143and time, so using the defaults of five priorities (-2 .. +2) is usually
2144fine.
2145
2146If your embedding app does not need any priorities, defining these both to
2147C<0> will save some memory and cpu.
2148
2063=item EV_PERIODIC_ENABLE 2149=item EV_PERIODIC_ENABLE
2064 2150
2065If undefined or defined to be C<1>, then periodic timers are supported. If 2151If undefined or defined to be C<1>, then periodic timers are supported. If
2152defined to be C<0>, then they are not. Disabling them saves a few kB of
2153code.
2154
2155=item EV_IDLE_ENABLE
2156
2157If undefined or defined to be C<1>, then idle watchers are supported. If
2066defined to be C<0>, then they are not. Disabling them saves a few kB of 2158defined to be C<0>, then they are not. Disabling them saves a few kB of
2067code. 2159code.
2068 2160
2069=item EV_EMBED_ENABLE 2161=item EV_EMBED_ENABLE
2070 2162
2137interface) and F<EV.xs> (implementation) files. Only the F<EV.xs> file 2229interface) and F<EV.xs> (implementation) files. Only the F<EV.xs> file
2138will be compiled. It is pretty complex because it provides its own header 2230will be compiled. It is pretty complex because it provides its own header
2139file. 2231file.
2140 2232
2141The usage in rxvt-unicode is simpler. It has a F<ev_cpp.h> header file 2233The usage in rxvt-unicode is simpler. It has a F<ev_cpp.h> header file
2142that everybody includes and which overrides some autoconf choices: 2234that everybody includes and which overrides some configure choices:
2143 2235
2236 #define EV_MINIMAL 1
2144 #define EV_USE_POLL 0 2237 #define EV_USE_POLL 0
2145 #define EV_MULTIPLICITY 0 2238 #define EV_MULTIPLICITY 0
2146 #define EV_PERIODICS 0 2239 #define EV_PERIODIC_ENABLE 0
2240 #define EV_STAT_ENABLE 0
2241 #define EV_FORK_ENABLE 0
2147 #define EV_CONFIG_H <config.h> 2242 #define EV_CONFIG_H <config.h>
2243 #define EV_MINPRI 0
2244 #define EV_MAXPRI 0
2148 2245
2149 #include "ev++.h" 2246 #include "ev++.h"
2150 2247
2151And a F<ev_cpp.C> implementation file that contains libev proper and is compiled: 2248And a F<ev_cpp.C> implementation file that contains libev proper and is compiled:
2152 2249
2162 2259
2163=over 4 2260=over 4
2164 2261
2165=item Starting and stopping timer/periodic watchers: O(log skipped_other_timers) 2262=item Starting and stopping timer/periodic watchers: O(log skipped_other_timers)
2166 2263
2264This means that, when you have a watcher that triggers in one hour and
2265there are 100 watchers that would trigger before that then inserting will
2266have to skip those 100 watchers.
2267
2167=item Changing timer/periodic watchers (by autorepeat, again): O(log skipped_other_timers) 2268=item Changing timer/periodic watchers (by autorepeat, again): O(log skipped_other_timers)
2168 2269
2270That means that for changing a timer costs less than removing/adding them
2271as only the relative motion in the event queue has to be paid for.
2272
2169=item Starting io/check/prepare/idle/signal/child watchers: O(1) 2273=item Starting io/check/prepare/idle/signal/child watchers: O(1)
2170 2274
2275These just add the watcher into an array or at the head of a list. If
2276the array needs to be extended libev needs to realloc and move the whole
2277array, but this happen asymptotically less and less with more watchers,
2278thus amortised O(1).
2279
2171=item Stopping check/prepare/idle watchers: O(1) 2280=item Stopping check/prepare/idle watchers: O(1)
2172 2281
2173=item Stopping an io/signal/child watcher: O(number_of_watchers_for_this_(fd/signal/pid % EV_PID_HASHSIZE)) 2282=item Stopping an io/signal/child watcher: O(number_of_watchers_for_this_(fd/signal/pid % EV_PID_HASHSIZE))
2174 2283
2284These watchers are stored in lists then need to be walked to find the
2285correct watcher to remove. The lists are usually short (you don't usually
2286have many watchers waiting for the same fd or signal).
2287
2175=item Finding the next timer per loop iteration: O(1) 2288=item Finding the next timer per loop iteration: O(1)
2176 2289
2177=item Each change on a file descriptor per loop iteration: O(number_of_watchers_for_this_fd) 2290=item Each change on a file descriptor per loop iteration: O(number_of_watchers_for_this_fd)
2178 2291
2292A change means an I/O watcher gets started or stopped, which requires
2293libev to recalculate its status (and possibly tell the kernel).
2294
2179=item Activating one watcher: O(1) 2295=item Activating one watcher: O(1)
2180 2296
2297=item Priority handling: O(number_of_priorities)
2298
2299Priorities are implemented by allocating some space for each
2300priority. When doing priority-based operations, libev usually has to
2301linearly search all the priorities.
2302
2181=back 2303=back
2182 2304
2183 2305
2184=head1 AUTHOR 2306=head1 AUTHOR
2185 2307

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines