… | |
… | |
98 | Libev represents time as a single floating point number, representing the |
98 | Libev 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 |
100 | the beginning of 1970, details are complicated, don't ask). This type is |
100 | the beginning of 1970, details are complicated, don't ask). This type is |
101 | called C<ev_tstamp>, which is what you should use too. It usually aliases |
101 | called C<ev_tstamp>, which is what you should use too. It usually aliases |
102 | to the C<double> type in C, and when you need to do any calculations on |
102 | to the C<double> type in C, and when you need to do any calculations on |
103 | it, you should treat it as such. |
103 | it, you should treat it as some floatingpoint value. Unlike the name |
|
|
104 | component C<stamp> might indicate, it is also used for time differences |
|
|
105 | throughout libev. |
104 | |
106 | |
105 | =head1 GLOBAL FUNCTIONS |
107 | =head1 GLOBAL FUNCTIONS |
106 | |
108 | |
107 | These functions can be called anytime, even before initialising the |
109 | These functions can be called anytime, even before initialising the |
108 | library in any way. |
110 | library 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 | |
332 | Kqueue deserves special mention, as at the time of this writing, it |
334 | Kqueue deserves special mention, as at the time of this writing, it |
333 | was broken on all BSDs except NetBSD (usually it doesn't work with |
335 | was broken on all BSDs except NetBSD (usually it doesn't work with |
334 | anything but sockets and pipes, except on Darwin, where of course its |
336 | anything but sockets and pipes, except on Darwin, where of course it's |
335 | completely useless). For this reason its not being "autodetected" |
337 | completely useless). For this reason it's not being "autodetected" |
336 | unless you explicitly specify it explicitly in the flags (i.e. using |
338 | unless you explicitly specify it explicitly in the flags (i.e. using |
337 | C<EVBACKEND_KQUEUE>). |
339 | C<EVBACKEND_KQUEUE>). |
338 | |
340 | |
339 | It scales in the same way as the epoll backend, but the interface to the |
341 | It scales in the same way as the epoll backend, but the interface to the |
340 | kernel is more efficient (which says nothing about its actual speed, of |
342 | kernel is more efficient (which says nothing about its actual speed, of |
… | |
… | |
402 | Destroys the default loop again (frees all memory and kernel state |
404 | Destroys the default loop again (frees all memory and kernel state |
403 | etc.). None of the active event watchers will be stopped in the normal |
405 | etc.). None of the active event watchers will be stopped in the normal |
404 | sense, so e.g. C<ev_is_active> might still return true. It is your |
406 | sense, so e.g. C<ev_is_active> might still return true. It is your |
405 | responsibility to either stop all watchers cleanly yoursef I<before> |
407 | responsibility to either stop all watchers cleanly yoursef I<before> |
406 | calling this function, or cope with the fact afterwards (which is usually |
408 | calling this function, or cope with the fact afterwards (which is usually |
407 | the easiest thing, youc na just ignore the watchers and/or C<free ()> them |
409 | the easiest thing, you can just ignore the watchers and/or C<free ()> them |
408 | for example). |
410 | for example). |
|
|
411 | |
|
|
412 | Note that certain global state, such as signal state, will not be freed by |
|
|
413 | this function, and related watchers (such as signal and child watchers) |
|
|
414 | would need to be stopped manually. |
|
|
415 | |
|
|
416 | In general it is not advisable to call this function except in the |
|
|
417 | rare occasion where you really need to free e.g. the signal handling |
|
|
418 | pipe fds. If you need dynamically allocated loops it is better to use |
|
|
419 | C<ev_loop_new> and C<ev_loop_destroy>). |
409 | |
420 | |
410 | =item ev_loop_destroy (loop) |
421 | =item ev_loop_destroy (loop) |
411 | |
422 | |
412 | Like C<ev_default_destroy>, but destroys an event loop created by an |
423 | Like C<ev_default_destroy>, but destroys an event loop created by an |
413 | earlier call to C<ev_loop_new>. |
424 | earlier call to C<ev_loop_new>. |
… | |
… | |
1220 | |
1231 | |
1221 | The current reschedule callback, or C<0>, if this functionality is |
1232 | The current reschedule callback, or C<0>, if this functionality is |
1222 | switched off. Can be changed any time, but changes only take effect when |
1233 | switched off. Can be changed any time, but changes only take effect when |
1223 | the periodic timer fires or C<ev_periodic_again> is being called. |
1234 | the periodic timer fires or C<ev_periodic_again> is being called. |
1224 | |
1235 | |
|
|
1236 | =item ev_tstamp at [read-only] |
|
|
1237 | |
|
|
1238 | When active, contains the absolute time that the watcher is supposed to |
|
|
1239 | trigger next. |
|
|
1240 | |
1225 | =back |
1241 | =back |
1226 | |
1242 | |
1227 | Example: Call a callback every hour, or, more precisely, whenever the |
1243 | Example: Call a callback every hour, or, more precisely, whenever the |
1228 | system clock is divisible by 3600. The callback invocation times have |
1244 | system clock is divisible by 3600. The callback invocation times have |
1229 | potentially a lot of jittering, but good long-term stability. |
1245 | potentially a lot of jittering, but good long-term stability. |
… | |
… | |
1775 | |
1791 | |
1776 | Make a single, non-blocking sweep over the embedded loop. This works |
1792 | Make a single, non-blocking sweep over the embedded loop. This works |
1777 | similarly to C<ev_loop (embedded_loop, EVLOOP_NONBLOCK)>, but in the most |
1793 | similarly to C<ev_loop (embedded_loop, EVLOOP_NONBLOCK)>, but in the most |
1778 | apropriate way for embedded loops. |
1794 | apropriate way for embedded loops. |
1779 | |
1795 | |
1780 | =item struct ev_loop *loop [read-only] |
1796 | =item struct ev_loop *other [read-only] |
1781 | |
1797 | |
1782 | The embedded event loop. |
1798 | The embedded event loop. |
1783 | |
1799 | |
1784 | =back |
1800 | =back |
1785 | |
1801 | |
… | |
… | |
1792 | event loop blocks next and before C<ev_check> watchers are being called, |
1808 | event loop blocks next and before C<ev_check> watchers are being called, |
1793 | and only in the child after the fork. If whoever good citizen calling |
1809 | and only in the child after the fork. If whoever good citizen calling |
1794 | C<ev_default_fork> cheats and calls it in the wrong process, the fork |
1810 | C<ev_default_fork> cheats and calls it in the wrong process, the fork |
1795 | handlers will be invoked, too, of course. |
1811 | handlers will be invoked, too, of course. |
1796 | |
1812 | |
|
|
1813 | =head3 Watcher-Specific Functions and Data Members |
|
|
1814 | |
1797 | =over 4 |
1815 | =over 4 |
1798 | |
1816 | |
1799 | =item ev_fork_init (ev_signal *, callback) |
1817 | =item ev_fork_init (ev_signal *, callback) |
1800 | |
1818 | |
1801 | Initialises and configures the fork watcher - it has no parameters of any |
1819 | Initialises and configures the fork watcher - it has no parameters of any |
… | |
… | |
2017 | |
2035 | |
2018 | =item w->stop () |
2036 | =item w->stop () |
2019 | |
2037 | |
2020 | Stops the watcher if it is active. Again, no C<loop> argument. |
2038 | Stops the watcher if it is active. Again, no C<loop> argument. |
2021 | |
2039 | |
2022 | =item w->again () C<ev::timer>, C<ev::periodic> only |
2040 | =item w->again () (C<ev::timer>, C<ev::periodic> only) |
2023 | |
2041 | |
2024 | For C<ev::timer> and C<ev::periodic>, this invokes the corresponding |
2042 | For C<ev::timer> and C<ev::periodic>, this invokes the corresponding |
2025 | C<ev_TYPE_again> function. |
2043 | C<ev_TYPE_again> function. |
2026 | |
2044 | |
2027 | =item w->sweep () C<ev::embed> only |
2045 | =item w->sweep () (C<ev::embed> only) |
2028 | |
2046 | |
2029 | Invokes C<ev_embed_sweep>. |
2047 | Invokes C<ev_embed_sweep>. |
2030 | |
2048 | |
2031 | =item w->update () C<ev::stat> only |
2049 | =item w->update () (C<ev::stat> only) |
2032 | |
2050 | |
2033 | Invokes C<ev_stat_stat>. |
2051 | Invokes C<ev_stat_stat>. |
2034 | |
2052 | |
2035 | =back |
2053 | =back |
2036 | |
2054 | |
… | |
… | |
2056 | } |
2074 | } |
2057 | |
2075 | |
2058 | |
2076 | |
2059 | =head1 MACRO MAGIC |
2077 | =head1 MACRO MAGIC |
2060 | |
2078 | |
2061 | Libev can be compiled with a variety of options, the most fundemantal is |
2079 | Libev can be compiled with a variety of options, the most fundamantal |
2062 | C<EV_MULTIPLICITY>. This option determines whether (most) functions and |
2080 | of which is C<EV_MULTIPLICITY>. This option determines whether (most) |
2063 | callbacks have an initial C<struct ev_loop *> argument. |
2081 | functions and callbacks have an initial C<struct ev_loop *> argument. |
2064 | |
2082 | |
2065 | To make it easier to write programs that cope with either variant, the |
2083 | To make it easier to write programs that cope with either variant, the |
2066 | following macros are defined: |
2084 | following macros are defined: |
2067 | |
2085 | |
2068 | =over 4 |
2086 | =over 4 |
… | |
… | |
2122 | Libev can (and often is) directly embedded into host |
2140 | Libev can (and often is) directly embedded into host |
2123 | applications. Examples of applications that embed it include the Deliantra |
2141 | applications. Examples of applications that embed it include the Deliantra |
2124 | Game Server, the EV perl module, the GNU Virtual Private Ethernet (gvpe) |
2142 | Game Server, the EV perl module, the GNU Virtual Private Ethernet (gvpe) |
2125 | and rxvt-unicode. |
2143 | and rxvt-unicode. |
2126 | |
2144 | |
2127 | The goal is to enable you to just copy the neecssary files into your |
2145 | The goal is to enable you to just copy the necessary files into your |
2128 | source directory without having to change even a single line in them, so |
2146 | source directory without having to change even a single line in them, so |
2129 | you can easily upgrade by simply copying (or having a checked-out copy of |
2147 | you can easily upgrade by simply copying (or having a checked-out copy of |
2130 | libev somewhere in your source tree). |
2148 | libev somewhere in your source tree). |
2131 | |
2149 | |
2132 | =head2 FILESETS |
2150 | =head2 FILESETS |
… | |
… | |
2232 | |
2250 | |
2233 | If defined to be C<1>, libev will try to detect the availability of the |
2251 | If defined to be C<1>, libev will try to detect the availability of the |
2234 | realtime clock option at compiletime (and assume its availability at |
2252 | realtime clock option at compiletime (and assume its availability at |
2235 | runtime if successful). Otherwise no use of the realtime clock option will |
2253 | runtime if successful). Otherwise no use of the realtime clock option will |
2236 | be attempted. This effectively replaces C<gettimeofday> by C<clock_get |
2254 | be attempted. This effectively replaces C<gettimeofday> by C<clock_get |
2237 | (CLOCK_REALTIME, ...)> and will not normally affect correctness. See tzhe note about libraries |
2255 | (CLOCK_REALTIME, ...)> and will not normally affect correctness. See the |
2238 | in the description of C<EV_USE_MONOTONIC>, though. |
2256 | note about libraries in the description of C<EV_USE_MONOTONIC>, though. |
2239 | |
2257 | |
2240 | =item EV_USE_SELECT |
2258 | =item EV_USE_SELECT |
2241 | |
2259 | |
2242 | If undefined or defined to be C<1>, libev will compile in support for the |
2260 | If undefined or defined to be C<1>, libev will compile in support for the |
2243 | C<select>(2) backend. No attempt at autodetection will be done: if no |
2261 | C<select>(2) backend. No attempt at autodetection will be done: if no |
… | |
… | |
2427 | definition and a statement, respectively. See the F<ev.v> header file for |
2445 | definition and a statement, respectively. See the F<ev.v> header file for |
2428 | their default definitions. One possible use for overriding these is to |
2446 | their default definitions. One possible use for overriding these is to |
2429 | avoid the C<struct ev_loop *> as first argument in all cases, or to use |
2447 | avoid the C<struct ev_loop *> as first argument in all cases, or to use |
2430 | method calls instead of plain function calls in C++. |
2448 | method calls instead of plain function calls in C++. |
2431 | |
2449 | |
|
|
2450 | =head2 EXPORTED API SYMBOLS |
|
|
2451 | |
|
|
2452 | If you need to re-export the API (e.g. via a dll) and you need a list of |
|
|
2453 | exported symbols, you can use the provided F<Symbol.*> files which list |
|
|
2454 | all public symbols, one per line: |
|
|
2455 | |
|
|
2456 | Symbols.ev for libev proper |
|
|
2457 | Symbols.event for the libevent emulation |
|
|
2458 | |
|
|
2459 | This can also be used to rename all public symbols to avoid clashes with |
|
|
2460 | multiple versions of libev linked together (which is obviously bad in |
|
|
2461 | itself, but sometimes it is inconvinient to avoid this). |
|
|
2462 | |
|
|
2463 | A sed comamnd like this will create wrapper C<#define>'s that you need to |
|
|
2464 | include before including F<ev.h>: |
|
|
2465 | |
|
|
2466 | <Symbols.ev sed -e "s/.*/#define & myprefix_&/" >wrap.h |
|
|
2467 | |
|
|
2468 | This 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 | ... |
|
|
2474 | |
2432 | =head2 EXAMPLES |
2475 | =head2 EXAMPLES |
2433 | |
2476 | |
2434 | For a real-world example of a program the includes libev |
2477 | For a real-world example of a program the includes libev |
2435 | verbatim, you can have a look at the EV perl module |
2478 | verbatim, you can have a look at the EV perl module |
2436 | (L<http://software.schmorp.de/pkg/EV.html>). It has the libev files in |
2479 | (L<http://software.schmorp.de/pkg/EV.html>). It has the libev files in |