… | |
… | |
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. |
… | |
… | |
117 | |
119 | |
118 | =item int ev_version_major () |
120 | =item int ev_version_major () |
119 | |
121 | |
120 | =item int ev_version_minor () |
122 | =item int ev_version_minor () |
121 | |
123 | |
122 | You can find out the major and minor version numbers of the library |
124 | You can find out the major and minor ABI version numbers of the library |
123 | you linked against by calling the functions C<ev_version_major> and |
125 | you linked against by calling the functions C<ev_version_major> and |
124 | C<ev_version_minor>. If you want, you can compare against the global |
126 | C<ev_version_minor>. If you want, you can compare against the global |
125 | symbols C<EV_VERSION_MAJOR> and C<EV_VERSION_MINOR>, which specify the |
127 | symbols C<EV_VERSION_MAJOR> and C<EV_VERSION_MINOR>, which specify the |
126 | version of the library your program was compiled against. |
128 | version of the library your program was compiled against. |
127 | |
129 | |
|
|
130 | These version numbers refer to the ABI version of the library, not the |
|
|
131 | release version. |
|
|
132 | |
128 | Usually, it's a good idea to terminate if the major versions mismatch, |
133 | Usually, it's a good idea to terminate if the major versions mismatch, |
129 | as this indicates an incompatible change. Minor versions are usually |
134 | as this indicates an incompatible change. Minor versions are usually |
130 | compatible to older versions, so a larger minor version alone is usually |
135 | compatible to older versions, so a larger minor version alone is usually |
131 | not a problem. |
136 | not a problem. |
132 | |
137 | |
133 | Example: Make sure we haven't accidentally been linked against the wrong |
138 | Example: Make sure we haven't accidentally been linked against the wrong |
134 | version. |
139 | version. |
… | |
… | |
908 | play around with an Xlib connection), then you have to seperately re-test |
913 | play around with an Xlib connection), then you have to seperately re-test |
909 | whether a file descriptor is really ready with a known-to-be good interface |
914 | whether a file descriptor is really ready with a known-to-be good interface |
910 | such as poll (fortunately in our Xlib example, Xlib already does this on |
915 | such as poll (fortunately in our Xlib example, Xlib already does this on |
911 | its own, so its quite safe to use). |
916 | its own, so its quite safe to use). |
912 | |
917 | |
|
|
918 | =head3 The special problem of disappearing file descriptors |
|
|
919 | |
|
|
920 | Some backends (e.g kqueue, epoll) need to be told about closing a file |
|
|
921 | descriptor (either by calling C<close> explicitly or by any other means, |
|
|
922 | such as C<dup>). The reason is that you register interest in some file |
|
|
923 | descriptor, but when it goes away, the operating system will silently drop |
|
|
924 | this interest. If another file descriptor with the same number then is |
|
|
925 | registered with libev, there is no efficient way to see that this is, in |
|
|
926 | fact, a different file descriptor. |
|
|
927 | |
|
|
928 | To avoid having to explicitly tell libev about such cases, libev follows |
|
|
929 | the following policy: Each time C<ev_io_set> is being called, libev |
|
|
930 | will assume that this is potentially a new file descriptor, otherwise |
|
|
931 | it is assumed that the file descriptor stays the same. That means that |
|
|
932 | you I<have> to call C<ev_io_set> (or C<ev_io_init>) when you change the |
|
|
933 | descriptor even if the file descriptor number itself did not change. |
|
|
934 | |
|
|
935 | This is how one would do it normally anyway, the important point is that |
|
|
936 | the libev application should not optimise around libev but should leave |
|
|
937 | optimisations to libev. |
|
|
938 | |
|
|
939 | |
|
|
940 | =head3 Watcher-Specific Functions |
|
|
941 | |
913 | =over 4 |
942 | =over 4 |
914 | |
943 | |
915 | =item ev_io_init (ev_io *, callback, int fd, int events) |
944 | =item ev_io_init (ev_io *, callback, int fd, int events) |
916 | |
945 | |
917 | =item ev_io_set (ev_io *, int fd, int events) |
946 | =item ev_io_set (ev_io *, int fd, int events) |
… | |
… | |
969 | ev_timer_set (&timer, after + ev_now () - ev_time (), 0.); |
998 | ev_timer_set (&timer, after + ev_now () - ev_time (), 0.); |
970 | |
999 | |
971 | The callback is guarenteed to be invoked only when its timeout has passed, |
1000 | The callback is guarenteed to be invoked only when its timeout has passed, |
972 | but if multiple timers become ready during the same loop iteration then |
1001 | but if multiple timers become ready during the same loop iteration then |
973 | order of execution is undefined. |
1002 | order of execution is undefined. |
|
|
1003 | |
|
|
1004 | =head3 Watcher-Specific Functions and Data Members |
974 | |
1005 | |
975 | =over 4 |
1006 | =over 4 |
976 | |
1007 | |
977 | =item ev_timer_init (ev_timer *, callback, ev_tstamp after, ev_tstamp repeat) |
1008 | =item ev_timer_init (ev_timer *, callback, ev_tstamp after, ev_tstamp repeat) |
978 | |
1009 | |
… | |
… | |
1084 | |
1115 | |
1085 | As with timers, the callback is guarenteed to be invoked only when the |
1116 | As with timers, the callback is guarenteed to be invoked only when the |
1086 | time (C<at>) has been passed, but if multiple periodic timers become ready |
1117 | time (C<at>) has been passed, but if multiple periodic timers become ready |
1087 | during the same loop iteration then order of execution is undefined. |
1118 | during the same loop iteration then order of execution is undefined. |
1088 | |
1119 | |
|
|
1120 | =head3 Watcher-Specific Functions and Data Members |
|
|
1121 | |
1089 | =over 4 |
1122 | =over 4 |
1090 | |
1123 | |
1091 | =item ev_periodic_init (ev_periodic *, callback, ev_tstamp at, ev_tstamp interval, reschedule_cb) |
1124 | =item ev_periodic_init (ev_periodic *, callback, ev_tstamp at, ev_tstamp interval, reschedule_cb) |
1092 | |
1125 | |
1093 | =item ev_periodic_set (ev_periodic *, ev_tstamp after, ev_tstamp repeat, reschedule_cb) |
1126 | =item ev_periodic_set (ev_periodic *, ev_tstamp after, ev_tstamp repeat, reschedule_cb) |
… | |
… | |
1188 | =item ev_tstamp (*reschedule_cb)(struct ev_periodic *w, ev_tstamp now) [read-write] |
1221 | =item ev_tstamp (*reschedule_cb)(struct ev_periodic *w, ev_tstamp now) [read-write] |
1189 | |
1222 | |
1190 | The current reschedule callback, or C<0>, if this functionality is |
1223 | The current reschedule callback, or C<0>, if this functionality is |
1191 | switched off. Can be changed any time, but changes only take effect when |
1224 | switched off. Can be changed any time, but changes only take effect when |
1192 | the periodic timer fires or C<ev_periodic_again> is being called. |
1225 | the periodic timer fires or C<ev_periodic_again> is being called. |
|
|
1226 | |
|
|
1227 | =item ev_tstamp at [read-only] |
|
|
1228 | |
|
|
1229 | When active, contains the absolute time that the watcher is supposed to |
|
|
1230 | trigger next. |
1193 | |
1231 | |
1194 | =back |
1232 | =back |
1195 | |
1233 | |
1196 | Example: Call a callback every hour, or, more precisely, whenever the |
1234 | Example: Call a callback every hour, or, more precisely, whenever the |
1197 | system clock is divisible by 3600. The callback invocation times have |
1235 | system clock is divisible by 3600. The callback invocation times have |
… | |
… | |
1239 | with the kernel (thus it coexists with your own signal handlers as long |
1277 | with the kernel (thus it coexists with your own signal handlers as long |
1240 | as you don't register any with libev). Similarly, when the last signal |
1278 | as you don't register any with libev). Similarly, when the last signal |
1241 | watcher for a signal is stopped libev will reset the signal handler to |
1279 | watcher for a signal is stopped libev will reset the signal handler to |
1242 | SIG_DFL (regardless of what it was set to before). |
1280 | SIG_DFL (regardless of what it was set to before). |
1243 | |
1281 | |
|
|
1282 | =head3 Watcher-Specific Functions and Data Members |
|
|
1283 | |
1244 | =over 4 |
1284 | =over 4 |
1245 | |
1285 | |
1246 | =item ev_signal_init (ev_signal *, callback, int signum) |
1286 | =item ev_signal_init (ev_signal *, callback, int signum) |
1247 | |
1287 | |
1248 | =item ev_signal_set (ev_signal *, int signum) |
1288 | =item ev_signal_set (ev_signal *, int signum) |
… | |
… | |
1259 | |
1299 | |
1260 | =head2 C<ev_child> - watch out for process status changes |
1300 | =head2 C<ev_child> - watch out for process status changes |
1261 | |
1301 | |
1262 | Child watchers trigger when your process receives a SIGCHLD in response to |
1302 | Child watchers trigger when your process receives a SIGCHLD in response to |
1263 | some child status changes (most typically when a child of yours dies). |
1303 | some child status changes (most typically when a child of yours dies). |
|
|
1304 | |
|
|
1305 | =head3 Watcher-Specific Functions and Data Members |
1264 | |
1306 | |
1265 | =over 4 |
1307 | =over 4 |
1266 | |
1308 | |
1267 | =item ev_child_init (ev_child *, callback, int pid) |
1309 | =item ev_child_init (ev_child *, callback, int pid) |
1268 | |
1310 | |
… | |
… | |
1336 | reader). Inotify will be used to give hints only and should not change the |
1378 | reader). Inotify will be used to give hints only and should not change the |
1337 | semantics of C<ev_stat> watchers, which means that libev sometimes needs |
1379 | semantics of C<ev_stat> watchers, which means that libev sometimes needs |
1338 | to fall back to regular polling again even with inotify, but changes are |
1380 | to fall back to regular polling again even with inotify, but changes are |
1339 | usually detected immediately, and if the file exists there will be no |
1381 | usually detected immediately, and if the file exists there will be no |
1340 | polling. |
1382 | polling. |
|
|
1383 | |
|
|
1384 | =head3 Watcher-Specific Functions and Data Members |
1341 | |
1385 | |
1342 | =over 4 |
1386 | =over 4 |
1343 | |
1387 | |
1344 | =item ev_stat_init (ev_stat *, callback, const char *path, ev_tstamp interval) |
1388 | =item ev_stat_init (ev_stat *, callback, const char *path, ev_tstamp interval) |
1345 | |
1389 | |
… | |
… | |
1428 | Apart from keeping your process non-blocking (which is a useful |
1472 | Apart from keeping your process non-blocking (which is a useful |
1429 | effect on its own sometimes), idle watchers are a good place to do |
1473 | effect on its own sometimes), idle watchers are a good place to do |
1430 | "pseudo-background processing", or delay processing stuff to after the |
1474 | "pseudo-background processing", or delay processing stuff to after the |
1431 | event loop has handled all outstanding events. |
1475 | event loop has handled all outstanding events. |
1432 | |
1476 | |
|
|
1477 | =head3 Watcher-Specific Functions and Data Members |
|
|
1478 | |
1433 | =over 4 |
1479 | =over 4 |
1434 | |
1480 | |
1435 | =item ev_idle_init (ev_signal *, callback) |
1481 | =item ev_idle_init (ev_signal *, callback) |
1436 | |
1482 | |
1437 | Initialises and configures the idle watcher - it has no parameters of any |
1483 | Initialises and configures the idle watcher - it has no parameters of any |
… | |
… | |
1504 | their job. As C<ev_check> watchers are often used to embed other event |
1550 | their job. As C<ev_check> watchers are often used to embed other event |
1505 | loops those other event loops might be in an unusable state until their |
1551 | loops those other event loops might be in an unusable state until their |
1506 | C<ev_check> watcher ran (always remind yourself to coexist peacefully with |
1552 | C<ev_check> watcher ran (always remind yourself to coexist peacefully with |
1507 | others). |
1553 | others). |
1508 | |
1554 | |
|
|
1555 | =head3 Watcher-Specific Functions and Data Members |
|
|
1556 | |
1509 | =over 4 |
1557 | =over 4 |
1510 | |
1558 | |
1511 | =item ev_prepare_init (ev_prepare *, callback) |
1559 | =item ev_prepare_init (ev_prepare *, callback) |
1512 | |
1560 | |
1513 | =item ev_check_init (ev_check *, callback) |
1561 | =item ev_check_init (ev_check *, callback) |
… | |
… | |
1714 | ev_embed_start (loop_hi, &embed); |
1762 | ev_embed_start (loop_hi, &embed); |
1715 | } |
1763 | } |
1716 | else |
1764 | else |
1717 | loop_lo = loop_hi; |
1765 | loop_lo = loop_hi; |
1718 | |
1766 | |
|
|
1767 | =head3 Watcher-Specific Functions and Data Members |
|
|
1768 | |
1719 | =over 4 |
1769 | =over 4 |
1720 | |
1770 | |
1721 | =item ev_embed_init (ev_embed *, callback, struct ev_loop *embedded_loop) |
1771 | =item ev_embed_init (ev_embed *, callback, struct ev_loop *embedded_loop) |
1722 | |
1772 | |
1723 | =item ev_embed_set (ev_embed *, callback, struct ev_loop *embedded_loop) |
1773 | =item ev_embed_set (ev_embed *, callback, struct ev_loop *embedded_loop) |
… | |
… | |
1749 | event loop blocks next and before C<ev_check> watchers are being called, |
1799 | event loop blocks next and before C<ev_check> watchers are being called, |
1750 | and only in the child after the fork. If whoever good citizen calling |
1800 | and only in the child after the fork. If whoever good citizen calling |
1751 | C<ev_default_fork> cheats and calls it in the wrong process, the fork |
1801 | C<ev_default_fork> cheats and calls it in the wrong process, the fork |
1752 | handlers will be invoked, too, of course. |
1802 | handlers will be invoked, too, of course. |
1753 | |
1803 | |
|
|
1804 | =head3 Watcher-Specific Functions and Data Members |
|
|
1805 | |
1754 | =over 4 |
1806 | =over 4 |
1755 | |
1807 | |
1756 | =item ev_fork_init (ev_signal *, callback) |
1808 | =item ev_fork_init (ev_signal *, callback) |
1757 | |
1809 | |
1758 | Initialises and configures the fork watcher - it has no parameters of any |
1810 | Initialises and configures the fork watcher - it has no parameters of any |
… | |
… | |
1974 | |
2026 | |
1975 | =item w->stop () |
2027 | =item w->stop () |
1976 | |
2028 | |
1977 | Stops the watcher if it is active. Again, no C<loop> argument. |
2029 | Stops the watcher if it is active. Again, no C<loop> argument. |
1978 | |
2030 | |
1979 | =item w->again () C<ev::timer>, C<ev::periodic> only |
2031 | =item w->again () (C<ev::timer>, C<ev::periodic> only) |
1980 | |
2032 | |
1981 | For C<ev::timer> and C<ev::periodic>, this invokes the corresponding |
2033 | For C<ev::timer> and C<ev::periodic>, this invokes the corresponding |
1982 | C<ev_TYPE_again> function. |
2034 | C<ev_TYPE_again> function. |
1983 | |
2035 | |
1984 | =item w->sweep () C<ev::embed> only |
2036 | =item w->sweep () (C<ev::embed> only) |
1985 | |
2037 | |
1986 | Invokes C<ev_embed_sweep>. |
2038 | Invokes C<ev_embed_sweep>. |
1987 | |
2039 | |
1988 | =item w->update () C<ev::stat> only |
2040 | =item w->update () (C<ev::stat> only) |
1989 | |
2041 | |
1990 | Invokes C<ev_stat_stat>. |
2042 | Invokes C<ev_stat_stat>. |
1991 | |
2043 | |
1992 | =back |
2044 | =back |
1993 | |
2045 | |
… | |
… | |
2013 | } |
2065 | } |
2014 | |
2066 | |
2015 | |
2067 | |
2016 | =head1 MACRO MAGIC |
2068 | =head1 MACRO MAGIC |
2017 | |
2069 | |
2018 | Libev can be compiled with a variety of options, the most fundemantal is |
2070 | Libev can be compiled with a variety of options, the most fundamantal |
2019 | C<EV_MULTIPLICITY>. This option determines whether (most) functions and |
2071 | of which is C<EV_MULTIPLICITY>. This option determines whether (most) |
2020 | callbacks have an initial C<struct ev_loop *> argument. |
2072 | functions and callbacks have an initial C<struct ev_loop *> argument. |
2021 | |
2073 | |
2022 | To make it easier to write programs that cope with either variant, the |
2074 | To make it easier to write programs that cope with either variant, the |
2023 | following macros are defined: |
2075 | following macros are defined: |
2024 | |
2076 | |
2025 | =over 4 |
2077 | =over 4 |