… | |
… | |
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. |
… | |
… | |
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>. |
… | |
… | |
933 | This is how one would do it normally anyway, the important point is that |
944 | This is how one would do it normally anyway, the important point is that |
934 | the libev application should not optimise around libev but should leave |
945 | the libev application should not optimise around libev but should leave |
935 | optimisations to libev. |
946 | optimisations to libev. |
936 | |
947 | |
937 | |
948 | |
|
|
949 | =head3 Watcher-Specific Functions |
|
|
950 | |
938 | =over 4 |
951 | =over 4 |
939 | |
952 | |
940 | =item ev_io_init (ev_io *, callback, int fd, int events) |
953 | =item ev_io_init (ev_io *, callback, int fd, int events) |
941 | |
954 | |
942 | =item ev_io_set (ev_io *, int fd, int events) |
955 | =item ev_io_set (ev_io *, int fd, int events) |
… | |
… | |
994 | ev_timer_set (&timer, after + ev_now () - ev_time (), 0.); |
1007 | ev_timer_set (&timer, after + ev_now () - ev_time (), 0.); |
995 | |
1008 | |
996 | The callback is guarenteed to be invoked only when its timeout has passed, |
1009 | The callback is guarenteed to be invoked only when its timeout has passed, |
997 | but if multiple timers become ready during the same loop iteration then |
1010 | but if multiple timers become ready during the same loop iteration then |
998 | order of execution is undefined. |
1011 | order of execution is undefined. |
|
|
1012 | |
|
|
1013 | =head3 Watcher-Specific Functions and Data Members |
999 | |
1014 | |
1000 | =over 4 |
1015 | =over 4 |
1001 | |
1016 | |
1002 | =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) |
1003 | |
1018 | |
… | |
… | |
1109 | |
1124 | |
1110 | As with timers, the callback is guarenteed to be invoked only when the |
1125 | As with timers, the callback is guarenteed to be invoked only when the |
1111 | time (C<at>) has been passed, but if multiple periodic timers become ready |
1126 | time (C<at>) has been passed, but if multiple periodic timers become ready |
1112 | during the same loop iteration then order of execution is undefined. |
1127 | during the same loop iteration then order of execution is undefined. |
1113 | |
1128 | |
|
|
1129 | =head3 Watcher-Specific Functions and Data Members |
|
|
1130 | |
1114 | =over 4 |
1131 | =over 4 |
1115 | |
1132 | |
1116 | =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) |
1117 | |
1134 | |
1118 | =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) |
… | |
… | |
1213 | =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] |
1214 | |
1231 | |
1215 | The current reschedule callback, or C<0>, if this functionality is |
1232 | The current reschedule callback, or C<0>, if this functionality is |
1216 | 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 |
1217 | 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. |
|
|
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. |
1218 | |
1240 | |
1219 | =back |
1241 | =back |
1220 | |
1242 | |
1221 | Example: Call a callback every hour, or, more precisely, whenever the |
1243 | Example: Call a callback every hour, or, more precisely, whenever the |
1222 | system clock is divisible by 3600. The callback invocation times have |
1244 | system clock is divisible by 3600. The callback invocation times have |
… | |
… | |
1264 | with the kernel (thus it coexists with your own signal handlers as long |
1286 | with the kernel (thus it coexists with your own signal handlers as long |
1265 | as you don't register any with libev). Similarly, when the last signal |
1287 | as you don't register any with libev). Similarly, when the last signal |
1266 | watcher for a signal is stopped libev will reset the signal handler to |
1288 | watcher for a signal is stopped libev will reset the signal handler to |
1267 | SIG_DFL (regardless of what it was set to before). |
1289 | SIG_DFL (regardless of what it was set to before). |
1268 | |
1290 | |
|
|
1291 | =head3 Watcher-Specific Functions and Data Members |
|
|
1292 | |
1269 | =over 4 |
1293 | =over 4 |
1270 | |
1294 | |
1271 | =item ev_signal_init (ev_signal *, callback, int signum) |
1295 | =item ev_signal_init (ev_signal *, callback, int signum) |
1272 | |
1296 | |
1273 | =item ev_signal_set (ev_signal *, int signum) |
1297 | =item ev_signal_set (ev_signal *, int signum) |
… | |
… | |
1284 | |
1308 | |
1285 | =head2 C<ev_child> - watch out for process status changes |
1309 | =head2 C<ev_child> - watch out for process status changes |
1286 | |
1310 | |
1287 | Child watchers trigger when your process receives a SIGCHLD in response to |
1311 | Child watchers trigger when your process receives a SIGCHLD in response to |
1288 | some child status changes (most typically when a child of yours dies). |
1312 | some child status changes (most typically when a child of yours dies). |
|
|
1313 | |
|
|
1314 | =head3 Watcher-Specific Functions and Data Members |
1289 | |
1315 | |
1290 | =over 4 |
1316 | =over 4 |
1291 | |
1317 | |
1292 | =item ev_child_init (ev_child *, callback, int pid) |
1318 | =item ev_child_init (ev_child *, callback, int pid) |
1293 | |
1319 | |
… | |
… | |
1361 | reader). Inotify will be used to give hints only and should not change the |
1387 | reader). Inotify will be used to give hints only and should not change the |
1362 | semantics of C<ev_stat> watchers, which means that libev sometimes needs |
1388 | semantics of C<ev_stat> watchers, which means that libev sometimes needs |
1363 | to fall back to regular polling again even with inotify, but changes are |
1389 | to fall back to regular polling again even with inotify, but changes are |
1364 | usually detected immediately, and if the file exists there will be no |
1390 | usually detected immediately, and if the file exists there will be no |
1365 | polling. |
1391 | polling. |
|
|
1392 | |
|
|
1393 | =head3 Watcher-Specific Functions and Data Members |
1366 | |
1394 | |
1367 | =over 4 |
1395 | =over 4 |
1368 | |
1396 | |
1369 | =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) |
1370 | |
1398 | |
… | |
… | |
1453 | Apart from keeping your process non-blocking (which is a useful |
1481 | Apart from keeping your process non-blocking (which is a useful |
1454 | effect on its own sometimes), idle watchers are a good place to do |
1482 | effect on its own sometimes), idle watchers are a good place to do |
1455 | "pseudo-background processing", or delay processing stuff to after the |
1483 | "pseudo-background processing", or delay processing stuff to after the |
1456 | event loop has handled all outstanding events. |
1484 | event loop has handled all outstanding events. |
1457 | |
1485 | |
|
|
1486 | =head3 Watcher-Specific Functions and Data Members |
|
|
1487 | |
1458 | =over 4 |
1488 | =over 4 |
1459 | |
1489 | |
1460 | =item ev_idle_init (ev_signal *, callback) |
1490 | =item ev_idle_init (ev_signal *, callback) |
1461 | |
1491 | |
1462 | Initialises and configures the idle watcher - it has no parameters of any |
1492 | Initialises and configures the idle watcher - it has no parameters of any |
… | |
… | |
1529 | their job. As C<ev_check> watchers are often used to embed other event |
1559 | their job. As C<ev_check> watchers are often used to embed other event |
1530 | loops those other event loops might be in an unusable state until their |
1560 | loops those other event loops might be in an unusable state until their |
1531 | C<ev_check> watcher ran (always remind yourself to coexist peacefully with |
1561 | C<ev_check> watcher ran (always remind yourself to coexist peacefully with |
1532 | others). |
1562 | others). |
1533 | |
1563 | |
|
|
1564 | =head3 Watcher-Specific Functions and Data Members |
|
|
1565 | |
1534 | =over 4 |
1566 | =over 4 |
1535 | |
1567 | |
1536 | =item ev_prepare_init (ev_prepare *, callback) |
1568 | =item ev_prepare_init (ev_prepare *, callback) |
1537 | |
1569 | |
1538 | =item ev_check_init (ev_check *, callback) |
1570 | =item ev_check_init (ev_check *, callback) |
… | |
… | |
1739 | ev_embed_start (loop_hi, &embed); |
1771 | ev_embed_start (loop_hi, &embed); |
1740 | } |
1772 | } |
1741 | else |
1773 | else |
1742 | loop_lo = loop_hi; |
1774 | loop_lo = loop_hi; |
1743 | |
1775 | |
|
|
1776 | =head3 Watcher-Specific Functions and Data Members |
|
|
1777 | |
1744 | =over 4 |
1778 | =over 4 |
1745 | |
1779 | |
1746 | =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) |
1747 | |
1781 | |
1748 | =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) |
… | |
… | |
1774 | 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, |
1775 | 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 |
1776 | 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 |
1777 | handlers will be invoked, too, of course. |
1811 | handlers will be invoked, too, of course. |
1778 | |
1812 | |
|
|
1813 | =head3 Watcher-Specific Functions and Data Members |
|
|
1814 | |
1779 | =over 4 |
1815 | =over 4 |
1780 | |
1816 | |
1781 | =item ev_fork_init (ev_signal *, callback) |
1817 | =item ev_fork_init (ev_signal *, callback) |
1782 | |
1818 | |
1783 | 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 |
… | |
… | |
1999 | |
2035 | |
2000 | =item w->stop () |
2036 | =item w->stop () |
2001 | |
2037 | |
2002 | 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. |
2003 | |
2039 | |
2004 | =item w->again () C<ev::timer>, C<ev::periodic> only |
2040 | =item w->again () (C<ev::timer>, C<ev::periodic> only) |
2005 | |
2041 | |
2006 | 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 |
2007 | C<ev_TYPE_again> function. |
2043 | C<ev_TYPE_again> function. |
2008 | |
2044 | |
2009 | =item w->sweep () C<ev::embed> only |
2045 | =item w->sweep () (C<ev::embed> only) |
2010 | |
2046 | |
2011 | Invokes C<ev_embed_sweep>. |
2047 | Invokes C<ev_embed_sweep>. |
2012 | |
2048 | |
2013 | =item w->update () C<ev::stat> only |
2049 | =item w->update () (C<ev::stat> only) |
2014 | |
2050 | |
2015 | Invokes C<ev_stat_stat>. |
2051 | Invokes C<ev_stat_stat>. |
2016 | |
2052 | |
2017 | =back |
2053 | =back |
2018 | |
2054 | |
… | |
… | |
2038 | } |
2074 | } |
2039 | |
2075 | |
2040 | |
2076 | |
2041 | =head1 MACRO MAGIC |
2077 | =head1 MACRO MAGIC |
2042 | |
2078 | |
2043 | 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 |
2044 | C<EV_MULTIPLICITY>. This option determines whether (most) functions and |
2080 | of which is C<EV_MULTIPLICITY>. This option determines whether (most) |
2045 | callbacks have an initial C<struct ev_loop *> argument. |
2081 | functions and callbacks have an initial C<struct ev_loop *> argument. |
2046 | |
2082 | |
2047 | 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 |
2048 | following macros are defined: |
2084 | following macros are defined: |
2049 | |
2085 | |
2050 | =over 4 |
2086 | =over 4 |
… | |
… | |
2409 | 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 |
2410 | their default definitions. One possible use for overriding these is to |
2446 | their default definitions. One possible use for overriding these is to |
2411 | 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 |
2412 | method calls instead of plain function calls in C++. |
2448 | method calls instead of plain function calls in C++. |
2413 | |
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 | |
2414 | =head2 EXAMPLES |
2475 | =head2 EXAMPLES |
2415 | |
2476 | |
2416 | For a real-world example of a program the includes libev |
2477 | For a real-world example of a program the includes libev |
2417 | verbatim, you can have a look at the EV perl module |
2478 | verbatim, you can have a look at the EV perl module |
2418 | (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 |