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

Comparing libev/ev.pod (file contents):
Revision 1.80 by root, Sun Dec 9 19:47:30 2007 UTC vs.
Revision 1.93 by root, Fri Dec 21 01:29:34 2007 UTC

53The newest version of this document is also available as a html-formatted 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 54web page you might find easier to navigate when reading it for the first
55time: L<http://cvs.schmorp.de/libev/ev.html>. 55time: L<http://cvs.schmorp.de/libev/ev.html>.
56 56
57Libev 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
58file descriptor being readable or a timeout occuring), and it will manage 58file descriptor being readable or a timeout occurring), and it will manage
59these event sources and provide your program with events. 59these event sources and provide your program with events.
60 60
61To do this, it must take more or less complete control over your process 61To do this, it must take more or less complete control over your process
62(or thread) by executing the I<event loop> handler, and will then 62(or thread) by executing the I<event loop> handler, and will then
63communicate events via a callback mechanism. 63communicate events via a callback mechanism.
98Libev represents time as a single floating point number, representing the 98Libev represents time as a single floating point number, representing the
99(fractional) number of seconds since the (POSIX) epoch (somewhere near 99(fractional) number of seconds since the (POSIX) epoch (somewhere near
100the beginning of 1970, details are complicated, don't ask). This type is 100the beginning of 1970, details are complicated, don't ask). This type is
101called C<ev_tstamp>, which is what you should use too. It usually aliases 101called C<ev_tstamp>, which is what you should use too. It usually aliases
102to the C<double> type in C, and when you need to do any calculations on 102to the C<double> type in C, and when you need to do any calculations on
103it, you should treat it as such. 103it, you should treat it as some floatingpoint value. Unlike the name
104component C<stamp> might indicate, it is also used for time differences
105throughout libev.
104 106
105=head1 GLOBAL FUNCTIONS 107=head1 GLOBAL FUNCTIONS
106 108
107These functions can be called anytime, even before initialising the 109These functions can be called anytime, even before initialising the
108library in any way. 110library in any way.
329 331
330=item C<EVBACKEND_KQUEUE> (value 8, most BSD clones) 332=item C<EVBACKEND_KQUEUE> (value 8, most BSD clones)
331 333
332Kqueue deserves special mention, as at the time of this writing, it 334Kqueue deserves special mention, as at the time of this writing, it
333was broken on all BSDs except NetBSD (usually it doesn't work with 335was broken on all BSDs except NetBSD (usually it doesn't work with
334anything but sockets and pipes, except on Darwin, where of course its 336anything but sockets and pipes, except on Darwin, where of course it's
335completely useless). For this reason its not being "autodetected" 337completely useless). For this reason it's not being "autodetected"
336unless you explicitly specify it explicitly in the flags (i.e. using 338unless you explicitly specify it explicitly in the flags (i.e. using
337C<EVBACKEND_KQUEUE>). 339C<EVBACKEND_KQUEUE>).
338 340
339It scales in the same way as the epoll backend, but the interface to the 341It scales in the same way as the epoll backend, but the interface to the
340kernel is more efficient (which says nothing about its actual speed, of 342kernel is more efficient (which says nothing about its actual speed, of
402Destroys the default loop again (frees all memory and kernel state 404Destroys the default loop again (frees all memory and kernel state
403etc.). None of the active event watchers will be stopped in the normal 405etc.). None of the active event watchers will be stopped in the normal
404sense, so e.g. C<ev_is_active> might still return true. It is your 406sense, so e.g. C<ev_is_active> might still return true. It is your
405responsibility to either stop all watchers cleanly yoursef I<before> 407responsibility to either stop all watchers cleanly yoursef I<before>
406calling this function, or cope with the fact afterwards (which is usually 408calling this function, or cope with the fact afterwards (which is usually
407the easiest thing, youc na just ignore the watchers and/or C<free ()> them 409the easiest thing, you can just ignore the watchers and/or C<free ()> them
408for example). 410for example).
411
412Note that certain global state, such as signal state, will not be freed by
413this function, and related watchers (such as signal and child watchers)
414would need to be stopped manually.
415
416In general it is not advisable to call this function except in the
417rare occasion where you really need to free e.g. the signal handling
418pipe fds. If you need dynamically allocated loops it is better to use
419C<ev_loop_new> and C<ev_loop_destroy>).
409 420
410=item ev_loop_destroy (loop) 421=item ev_loop_destroy (loop)
411 422
412Like C<ev_default_destroy>, but destroys an event loop created by an 423Like C<ev_default_destroy>, but destroys an event loop created by an
413earlier call to C<ev_loop_new>. 424earlier call to C<ev_loop_new>.
458 469
459Returns the current "event loop time", which is the time the event loop 470Returns the current "event loop time", which is the time the event loop
460received events and started processing them. This timestamp does not 471received events and started processing them. This timestamp does not
461change as long as callbacks are being processed, and this is also the base 472change as long as callbacks are being processed, and this is also the base
462time used for relative timers. You can treat it as the timestamp of the 473time used for relative timers. You can treat it as the timestamp of the
463event occuring (or more correctly, libev finding out about it). 474event occurring (or more correctly, libev finding out about it).
464 475
465=item ev_loop (loop, int flags) 476=item ev_loop (loop, int flags)
466 477
467Finally, this is it, the event handler. This function usually is called 478Finally, this is it, the event handler. This function usually is called
468after you initialised all your watchers and you want to start handling 479after you initialised all your watchers and you want to start handling
911play around with an Xlib connection), then you have to seperately re-test 922play around with an Xlib connection), then you have to seperately re-test
912whether a file descriptor is really ready with a known-to-be good interface 923whether a file descriptor is really ready with a known-to-be good interface
913such as poll (fortunately in our Xlib example, Xlib already does this on 924such as poll (fortunately in our Xlib example, Xlib already does this on
914its own, so its quite safe to use). 925its own, so its quite safe to use).
915 926
927=head3 The special problem of disappearing file descriptors
928
929Some backends (e.g kqueue, epoll) need to be told about closing a file
930descriptor (either by calling C<close> explicitly or by any other means,
931such as C<dup>). The reason is that you register interest in some file
932descriptor, but when it goes away, the operating system will silently drop
933this interest. If another file descriptor with the same number then is
934registered with libev, there is no efficient way to see that this is, in
935fact, a different file descriptor.
936
937To avoid having to explicitly tell libev about such cases, libev follows
938the following policy: Each time C<ev_io_set> is being called, libev
939will assume that this is potentially a new file descriptor, otherwise
940it is assumed that the file descriptor stays the same. That means that
941you I<have> to call C<ev_io_set> (or C<ev_io_init>) when you change the
942descriptor even if the file descriptor number itself did not change.
943
944This is how one would do it normally anyway, the important point is that
945the libev application should not optimise around libev but should leave
946optimisations to libev.
947
948
949=head3 Watcher-Specific Functions
950
916=over 4 951=over 4
917 952
918=item ev_io_init (ev_io *, callback, int fd, int events) 953=item ev_io_init (ev_io *, callback, int fd, int events)
919 954
920=item ev_io_set (ev_io *, int fd, int events) 955=item ev_io_set (ev_io *, int fd, int events)
972 ev_timer_set (&timer, after + ev_now () - ev_time (), 0.); 1007 ev_timer_set (&timer, after + ev_now () - ev_time (), 0.);
973 1008
974The callback is guarenteed to be invoked only when its timeout has passed, 1009The callback is guarenteed to be invoked only when its timeout has passed,
975but if multiple timers become ready during the same loop iteration then 1010but if multiple timers become ready during the same loop iteration then
976order of execution is undefined. 1011order of execution is undefined.
1012
1013=head3 Watcher-Specific Functions and Data Members
977 1014
978=over 4 1015=over 4
979 1016
980=item ev_timer_init (ev_timer *, callback, ev_tstamp after, ev_tstamp repeat) 1017=item ev_timer_init (ev_timer *, callback, ev_tstamp after, ev_tstamp repeat)
981 1018
1087 1124
1088As with timers, the callback is guarenteed to be invoked only when the 1125As with timers, the callback is guarenteed to be invoked only when the
1089time (C<at>) has been passed, but if multiple periodic timers become ready 1126time (C<at>) has been passed, but if multiple periodic timers become ready
1090during the same loop iteration then order of execution is undefined. 1127during the same loop iteration then order of execution is undefined.
1091 1128
1129=head3 Watcher-Specific Functions and Data Members
1130
1092=over 4 1131=over 4
1093 1132
1094=item ev_periodic_init (ev_periodic *, callback, ev_tstamp at, ev_tstamp interval, reschedule_cb) 1133=item ev_periodic_init (ev_periodic *, callback, ev_tstamp at, ev_tstamp interval, reschedule_cb)
1095 1134
1096=item ev_periodic_set (ev_periodic *, ev_tstamp after, ev_tstamp repeat, reschedule_cb) 1135=item ev_periodic_set (ev_periodic *, ev_tstamp after, ev_tstamp repeat, reschedule_cb)
1191=item ev_tstamp (*reschedule_cb)(struct ev_periodic *w, ev_tstamp now) [read-write] 1230=item ev_tstamp (*reschedule_cb)(struct ev_periodic *w, ev_tstamp now) [read-write]
1192 1231
1193The current reschedule callback, or C<0>, if this functionality is 1232The current reschedule callback, or C<0>, if this functionality is
1194switched off. Can be changed any time, but changes only take effect when 1233switched off. Can be changed any time, but changes only take effect when
1195the periodic timer fires or C<ev_periodic_again> is being called. 1234the periodic timer fires or C<ev_periodic_again> is being called.
1235
1236=item ev_tstamp at [read-only]
1237
1238When active, contains the absolute time that the watcher is supposed to
1239trigger next.
1196 1240
1197=back 1241=back
1198 1242
1199Example: Call a callback every hour, or, more precisely, whenever the 1243Example: Call a callback every hour, or, more precisely, whenever the
1200system clock is divisible by 3600. The callback invocation times have 1244system clock is divisible by 3600. The callback invocation times have
1242with the kernel (thus it coexists with your own signal handlers as long 1286with the kernel (thus it coexists with your own signal handlers as long
1243as you don't register any with libev). Similarly, when the last signal 1287as you don't register any with libev). Similarly, when the last signal
1244watcher for a signal is stopped libev will reset the signal handler to 1288watcher for a signal is stopped libev will reset the signal handler to
1245SIG_DFL (regardless of what it was set to before). 1289SIG_DFL (regardless of what it was set to before).
1246 1290
1291=head3 Watcher-Specific Functions and Data Members
1292
1247=over 4 1293=over 4
1248 1294
1249=item ev_signal_init (ev_signal *, callback, int signum) 1295=item ev_signal_init (ev_signal *, callback, int signum)
1250 1296
1251=item ev_signal_set (ev_signal *, int signum) 1297=item ev_signal_set (ev_signal *, int signum)
1262 1308
1263=head2 C<ev_child> - watch out for process status changes 1309=head2 C<ev_child> - watch out for process status changes
1264 1310
1265Child watchers trigger when your process receives a SIGCHLD in response to 1311Child watchers trigger when your process receives a SIGCHLD in response to
1266some child status changes (most typically when a child of yours dies). 1312some child status changes (most typically when a child of yours dies).
1313
1314=head3 Watcher-Specific Functions and Data Members
1267 1315
1268=over 4 1316=over 4
1269 1317
1270=item ev_child_init (ev_child *, callback, int pid) 1318=item ev_child_init (ev_child *, callback, int pid)
1271 1319
1339reader). Inotify will be used to give hints only and should not change the 1387reader). Inotify will be used to give hints only and should not change the
1340semantics of C<ev_stat> watchers, which means that libev sometimes needs 1388semantics of C<ev_stat> watchers, which means that libev sometimes needs
1341to fall back to regular polling again even with inotify, but changes are 1389to fall back to regular polling again even with inotify, but changes are
1342usually detected immediately, and if the file exists there will be no 1390usually detected immediately, and if the file exists there will be no
1343polling. 1391polling.
1392
1393=head3 Watcher-Specific Functions and Data Members
1344 1394
1345=over 4 1395=over 4
1346 1396
1347=item ev_stat_init (ev_stat *, callback, const char *path, ev_tstamp interval) 1397=item ev_stat_init (ev_stat *, callback, const char *path, ev_tstamp interval)
1348 1398
1431Apart from keeping your process non-blocking (which is a useful 1481Apart from keeping your process non-blocking (which is a useful
1432effect on its own sometimes), idle watchers are a good place to do 1482effect on its own sometimes), idle watchers are a good place to do
1433"pseudo-background processing", or delay processing stuff to after the 1483"pseudo-background processing", or delay processing stuff to after the
1434event loop has handled all outstanding events. 1484event loop has handled all outstanding events.
1435 1485
1486=head3 Watcher-Specific Functions and Data Members
1487
1436=over 4 1488=over 4
1437 1489
1438=item ev_idle_init (ev_signal *, callback) 1490=item ev_idle_init (ev_signal *, callback)
1439 1491
1440Initialises and configures the idle watcher - it has no parameters of any 1492Initialises and configures the idle watcher - it has no parameters of any
1507their job. As C<ev_check> watchers are often used to embed other event 1559their job. As C<ev_check> watchers are often used to embed other event
1508loops those other event loops might be in an unusable state until their 1560loops those other event loops might be in an unusable state until their
1509C<ev_check> watcher ran (always remind yourself to coexist peacefully with 1561C<ev_check> watcher ran (always remind yourself to coexist peacefully with
1510others). 1562others).
1511 1563
1564=head3 Watcher-Specific Functions and Data Members
1565
1512=over 4 1566=over 4
1513 1567
1514=item ev_prepare_init (ev_prepare *, callback) 1568=item ev_prepare_init (ev_prepare *, callback)
1515 1569
1516=item ev_check_init (ev_check *, callback) 1570=item ev_check_init (ev_check *, callback)
1717 ev_embed_start (loop_hi, &embed); 1771 ev_embed_start (loop_hi, &embed);
1718 } 1772 }
1719 else 1773 else
1720 loop_lo = loop_hi; 1774 loop_lo = loop_hi;
1721 1775
1776=head3 Watcher-Specific Functions and Data Members
1777
1722=over 4 1778=over 4
1723 1779
1724=item ev_embed_init (ev_embed *, callback, struct ev_loop *embedded_loop) 1780=item ev_embed_init (ev_embed *, callback, struct ev_loop *embedded_loop)
1725 1781
1726=item ev_embed_set (ev_embed *, callback, struct ev_loop *embedded_loop) 1782=item ev_embed_set (ev_embed *, callback, struct ev_loop *embedded_loop)
1735 1791
1736Make a single, non-blocking sweep over the embedded loop. This works 1792Make a single, non-blocking sweep over the embedded loop. This works
1737similarly to C<ev_loop (embedded_loop, EVLOOP_NONBLOCK)>, but in the most 1793similarly to C<ev_loop (embedded_loop, EVLOOP_NONBLOCK)>, but in the most
1738apropriate way for embedded loops. 1794apropriate way for embedded loops.
1739 1795
1740=item struct ev_loop *loop [read-only] 1796=item struct ev_loop *other [read-only]
1741 1797
1742The embedded event loop. 1798The embedded event loop.
1743 1799
1744=back 1800=back
1745 1801
1752event loop blocks next and before C<ev_check> watchers are being called, 1808event loop blocks next and before C<ev_check> watchers are being called,
1753and only in the child after the fork. If whoever good citizen calling 1809and only in the child after the fork. If whoever good citizen calling
1754C<ev_default_fork> cheats and calls it in the wrong process, the fork 1810C<ev_default_fork> cheats and calls it in the wrong process, the fork
1755handlers will be invoked, too, of course. 1811handlers will be invoked, too, of course.
1756 1812
1813=head3 Watcher-Specific Functions and Data Members
1814
1757=over 4 1815=over 4
1758 1816
1759=item ev_fork_init (ev_signal *, callback) 1817=item ev_fork_init (ev_signal *, callback)
1760 1818
1761Initialises and configures the fork watcher - it has no parameters of any 1819Initialises and configures the fork watcher - it has no parameters of any
1977 2035
1978=item w->stop () 2036=item w->stop ()
1979 2037
1980Stops the watcher if it is active. Again, no C<loop> argument. 2038Stops the watcher if it is active. Again, no C<loop> argument.
1981 2039
1982=item w->again () C<ev::timer>, C<ev::periodic> only 2040=item w->again () (C<ev::timer>, C<ev::periodic> only)
1983 2041
1984For C<ev::timer> and C<ev::periodic>, this invokes the corresponding 2042For C<ev::timer> and C<ev::periodic>, this invokes the corresponding
1985C<ev_TYPE_again> function. 2043C<ev_TYPE_again> function.
1986 2044
1987=item w->sweep () C<ev::embed> only 2045=item w->sweep () (C<ev::embed> only)
1988 2046
1989Invokes C<ev_embed_sweep>. 2047Invokes C<ev_embed_sweep>.
1990 2048
1991=item w->update () C<ev::stat> only 2049=item w->update () (C<ev::stat> only)
1992 2050
1993Invokes C<ev_stat_stat>. 2051Invokes C<ev_stat_stat>.
1994 2052
1995=back 2053=back
1996 2054
2016 } 2074 }
2017 2075
2018 2076
2019=head1 MACRO MAGIC 2077=head1 MACRO MAGIC
2020 2078
2021Libev can be compiled with a variety of options, the most fundemantal is 2079Libev can be compiled with a variety of options, the most fundamantal
2022C<EV_MULTIPLICITY>. This option determines whether (most) functions and 2080of which is C<EV_MULTIPLICITY>. This option determines whether (most)
2023callbacks have an initial C<struct ev_loop *> argument. 2081functions and callbacks have an initial C<struct ev_loop *> argument.
2024 2082
2025To make it easier to write programs that cope with either variant, the 2083To make it easier to write programs that cope with either variant, the
2026following macros are defined: 2084following macros are defined:
2027 2085
2028=over 4 2086=over 4
2082Libev can (and often is) directly embedded into host 2140Libev can (and often is) directly embedded into host
2083applications. Examples of applications that embed it include the Deliantra 2141applications. Examples of applications that embed it include the Deliantra
2084Game Server, the EV perl module, the GNU Virtual Private Ethernet (gvpe) 2142Game Server, the EV perl module, the GNU Virtual Private Ethernet (gvpe)
2085and rxvt-unicode. 2143and rxvt-unicode.
2086 2144
2087The goal is to enable you to just copy the neecssary files into your 2145The goal is to enable you to just copy the necessary files into your
2088source directory without having to change even a single line in them, so 2146source directory without having to change even a single line in them, so
2089you can easily upgrade by simply copying (or having a checked-out copy of 2147you can easily upgrade by simply copying (or having a checked-out copy of
2090libev somewhere in your source tree). 2148libev somewhere in your source tree).
2091 2149
2092=head2 FILESETS 2150=head2 FILESETS
2182 2240
2183If defined to be C<1>, libev will try to detect the availability of the 2241If defined to be C<1>, libev will try to detect the availability of the
2184monotonic clock option at both compiletime and runtime. Otherwise no use 2242monotonic clock option at both compiletime and runtime. Otherwise no use
2185of the monotonic clock option will be attempted. If you enable this, you 2243of the monotonic clock option will be attempted. If you enable this, you
2186usually have to link against librt or something similar. Enabling it when 2244usually have to link against librt or something similar. Enabling it when
2187the functionality isn't available is safe, though, althoguh you have 2245the functionality isn't available is safe, though, although you have
2188to make sure you link against any libraries where the C<clock_gettime> 2246to make sure you link against any libraries where the C<clock_gettime>
2189function is hiding in (often F<-lrt>). 2247function is hiding in (often F<-lrt>).
2190 2248
2191=item EV_USE_REALTIME 2249=item EV_USE_REALTIME
2192 2250
2193If defined to be C<1>, libev will try to detect the availability of the 2251If defined to be C<1>, libev will try to detect the availability of the
2194realtime clock option at compiletime (and assume its availability at 2252realtime clock option at compiletime (and assume its availability at
2195runtime if successful). Otherwise no use of the realtime clock option will 2253runtime if successful). Otherwise no use of the realtime clock option will
2196be attempted. This effectively replaces C<gettimeofday> by C<clock_get 2254be attempted. This effectively replaces C<gettimeofday> by C<clock_get
2197(CLOCK_REALTIME, ...)> and will not normally affect correctness. See tzhe note about libraries 2255(CLOCK_REALTIME, ...)> and will not normally affect correctness. See the
2198in the description of C<EV_USE_MONOTONIC>, though. 2256note about libraries in the description of C<EV_USE_MONOTONIC>, though.
2199 2257
2200=item EV_USE_SELECT 2258=item EV_USE_SELECT
2201 2259
2202If undefined or defined to be C<1>, libev will compile in support for the 2260If undefined or defined to be C<1>, libev will compile in support for the
2203C<select>(2) backend. No attempt at autodetection will be done: if no 2261C<select>(2) backend. No attempt at autodetection will be done: if no
2382 2440
2383=item ev_set_cb (ev, cb) 2441=item ev_set_cb (ev, cb)
2384 2442
2385Can be used to change the callback member declaration in each watcher, 2443Can be used to change the callback member declaration in each watcher,
2386and the way callbacks are invoked and set. Must expand to a struct member 2444and the way callbacks are invoked and set. Must expand to a struct member
2387definition and a statement, respectively. See the F<ev.v> header file for 2445definition and a statement, respectively. See the F<ev.h> header file for
2388their default definitions. One possible use for overriding these is to 2446their default definitions. One possible use for overriding these is to
2389avoid the C<struct ev_loop *> as first argument in all cases, or to use 2447avoid the C<struct ev_loop *> as first argument in all cases, or to use
2390method calls instead of plain function calls in C++. 2448method calls instead of plain function calls in C++.
2449
2450=head2 EXPORTED API SYMBOLS
2451
2452If you need to re-export the API (e.g. via a dll) and you need a list of
2453exported symbols, you can use the provided F<Symbol.*> files which list
2454all public symbols, one per line:
2455
2456 Symbols.ev for libev proper
2457 Symbols.event for the libevent emulation
2458
2459This can also be used to rename all public symbols to avoid clashes with
2460multiple versions of libev linked together (which is obviously bad in
2461itself, but sometimes it is inconvinient to avoid this).
2462
2463A sed command like this will create wrapper C<#define>'s that you need to
2464include before including F<ev.h>:
2465
2466 <Symbols.ev sed -e "s/.*/#define & myprefix_&/" >wrap.h
2467
2468This would create a file F<wrap.h> which essentially looks like this:
2469
2470 #define ev_backend myprefix_ev_backend
2471 #define ev_check_start myprefix_ev_check_start
2472 #define ev_check_stop myprefix_ev_check_stop
2473 ...
2391 2474
2392=head2 EXAMPLES 2475=head2 EXAMPLES
2393 2476
2394For a real-world example of a program the includes libev 2477For a real-world example of a program the includes libev
2395verbatim, you can have a look at the EV perl module 2478verbatim, you can have a look at the EV perl module

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines