… | |
… | |
911 | play around with an Xlib connection), then you have to seperately re-test |
911 | play around with an Xlib connection), then you have to seperately re-test |
912 | whether a file descriptor is really ready with a known-to-be good interface |
912 | whether a file descriptor is really ready with a known-to-be good interface |
913 | such as poll (fortunately in our Xlib example, Xlib already does this on |
913 | such as poll (fortunately in our Xlib example, Xlib already does this on |
914 | its own, so its quite safe to use). |
914 | its own, so its quite safe to use). |
915 | |
915 | |
|
|
916 | =head3 The special problem of disappearing file descriptors |
|
|
917 | |
|
|
918 | Some backends (e.g kqueue, epoll) need to be told about closing a file |
|
|
919 | descriptor (either by calling C<close> explicitly or by any other means, |
|
|
920 | such as C<dup>). The reason is that you register interest in some file |
|
|
921 | descriptor, but when it goes away, the operating system will silently drop |
|
|
922 | this interest. If another file descriptor with the same number then is |
|
|
923 | registered with libev, there is no efficient way to see that this is, in |
|
|
924 | fact, a different file descriptor. |
|
|
925 | |
|
|
926 | To avoid having to explicitly tell libev about such cases, libev follows |
|
|
927 | the following policy: Each time C<ev_io_set> is being called, libev |
|
|
928 | will assume that this is potentially a new file descriptor, otherwise |
|
|
929 | it is assumed that the file descriptor stays the same. That means that |
|
|
930 | you I<have> to call C<ev_io_set> (or C<ev_io_init>) when you change the |
|
|
931 | descriptor even if the file descriptor number itself did not change. |
|
|
932 | |
|
|
933 | 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 |
|
|
935 | optimisations to libev. |
|
|
936 | |
|
|
937 | |
|
|
938 | =head3 Watcher-Specific Functions |
|
|
939 | |
916 | =over 4 |
940 | =over 4 |
917 | |
941 | |
918 | =item ev_io_init (ev_io *, callback, int fd, int events) |
942 | =item ev_io_init (ev_io *, callback, int fd, int events) |
919 | |
943 | |
920 | =item ev_io_set (ev_io *, int fd, int events) |
944 | =item ev_io_set (ev_io *, int fd, int events) |
… | |
… | |
972 | ev_timer_set (&timer, after + ev_now () - ev_time (), 0.); |
996 | ev_timer_set (&timer, after + ev_now () - ev_time (), 0.); |
973 | |
997 | |
974 | The callback is guarenteed to be invoked only when its timeout has passed, |
998 | The callback is guarenteed to be invoked only when its timeout has passed, |
975 | but if multiple timers become ready during the same loop iteration then |
999 | but if multiple timers become ready during the same loop iteration then |
976 | order of execution is undefined. |
1000 | order of execution is undefined. |
|
|
1001 | |
|
|
1002 | =head3 Watcher-Specific Functions and Data Members |
977 | |
1003 | |
978 | =over 4 |
1004 | =over 4 |
979 | |
1005 | |
980 | =item ev_timer_init (ev_timer *, callback, ev_tstamp after, ev_tstamp repeat) |
1006 | =item ev_timer_init (ev_timer *, callback, ev_tstamp after, ev_tstamp repeat) |
981 | |
1007 | |
… | |
… | |
1087 | |
1113 | |
1088 | As with timers, the callback is guarenteed to be invoked only when the |
1114 | As with timers, the callback is guarenteed to be invoked only when the |
1089 | time (C<at>) has been passed, but if multiple periodic timers become ready |
1115 | time (C<at>) has been passed, but if multiple periodic timers become ready |
1090 | during the same loop iteration then order of execution is undefined. |
1116 | during the same loop iteration then order of execution is undefined. |
1091 | |
1117 | |
|
|
1118 | =head3 Watcher-Specific Functions and Data Members |
|
|
1119 | |
1092 | =over 4 |
1120 | =over 4 |
1093 | |
1121 | |
1094 | =item ev_periodic_init (ev_periodic *, callback, ev_tstamp at, ev_tstamp interval, reschedule_cb) |
1122 | =item ev_periodic_init (ev_periodic *, callback, ev_tstamp at, ev_tstamp interval, reschedule_cb) |
1095 | |
1123 | |
1096 | =item ev_periodic_set (ev_periodic *, ev_tstamp after, ev_tstamp repeat, reschedule_cb) |
1124 | =item ev_periodic_set (ev_periodic *, ev_tstamp after, ev_tstamp repeat, reschedule_cb) |
… | |
… | |
1242 | with the kernel (thus it coexists with your own signal handlers as long |
1270 | with the kernel (thus it coexists with your own signal handlers as long |
1243 | as you don't register any with libev). Similarly, when the last signal |
1271 | as you don't register any with libev). Similarly, when the last signal |
1244 | watcher for a signal is stopped libev will reset the signal handler to |
1272 | watcher for a signal is stopped libev will reset the signal handler to |
1245 | SIG_DFL (regardless of what it was set to before). |
1273 | SIG_DFL (regardless of what it was set to before). |
1246 | |
1274 | |
|
|
1275 | =head3 Watcher-Specific Functions and Data Members |
|
|
1276 | |
1247 | =over 4 |
1277 | =over 4 |
1248 | |
1278 | |
1249 | =item ev_signal_init (ev_signal *, callback, int signum) |
1279 | =item ev_signal_init (ev_signal *, callback, int signum) |
1250 | |
1280 | |
1251 | =item ev_signal_set (ev_signal *, int signum) |
1281 | =item ev_signal_set (ev_signal *, int signum) |
… | |
… | |
1262 | |
1292 | |
1263 | =head2 C<ev_child> - watch out for process status changes |
1293 | =head2 C<ev_child> - watch out for process status changes |
1264 | |
1294 | |
1265 | Child watchers trigger when your process receives a SIGCHLD in response to |
1295 | Child watchers trigger when your process receives a SIGCHLD in response to |
1266 | some child status changes (most typically when a child of yours dies). |
1296 | some child status changes (most typically when a child of yours dies). |
|
|
1297 | |
|
|
1298 | =head3 Watcher-Specific Functions and Data Members |
1267 | |
1299 | |
1268 | =over 4 |
1300 | =over 4 |
1269 | |
1301 | |
1270 | =item ev_child_init (ev_child *, callback, int pid) |
1302 | =item ev_child_init (ev_child *, callback, int pid) |
1271 | |
1303 | |
… | |
… | |
1339 | reader). Inotify will be used to give hints only and should not change the |
1371 | reader). Inotify will be used to give hints only and should not change the |
1340 | semantics of C<ev_stat> watchers, which means that libev sometimes needs |
1372 | semantics of C<ev_stat> watchers, which means that libev sometimes needs |
1341 | to fall back to regular polling again even with inotify, but changes are |
1373 | to fall back to regular polling again even with inotify, but changes are |
1342 | usually detected immediately, and if the file exists there will be no |
1374 | usually detected immediately, and if the file exists there will be no |
1343 | polling. |
1375 | polling. |
|
|
1376 | |
|
|
1377 | =head3 Watcher-Specific Functions and Data Members |
1344 | |
1378 | |
1345 | =over 4 |
1379 | =over 4 |
1346 | |
1380 | |
1347 | =item ev_stat_init (ev_stat *, callback, const char *path, ev_tstamp interval) |
1381 | =item ev_stat_init (ev_stat *, callback, const char *path, ev_tstamp interval) |
1348 | |
1382 | |
… | |
… | |
1431 | Apart from keeping your process non-blocking (which is a useful |
1465 | Apart from keeping your process non-blocking (which is a useful |
1432 | effect on its own sometimes), idle watchers are a good place to do |
1466 | effect on its own sometimes), idle watchers are a good place to do |
1433 | "pseudo-background processing", or delay processing stuff to after the |
1467 | "pseudo-background processing", or delay processing stuff to after the |
1434 | event loop has handled all outstanding events. |
1468 | event loop has handled all outstanding events. |
1435 | |
1469 | |
|
|
1470 | =head3 Watcher-Specific Functions and Data Members |
|
|
1471 | |
1436 | =over 4 |
1472 | =over 4 |
1437 | |
1473 | |
1438 | =item ev_idle_init (ev_signal *, callback) |
1474 | =item ev_idle_init (ev_signal *, callback) |
1439 | |
1475 | |
1440 | Initialises and configures the idle watcher - it has no parameters of any |
1476 | Initialises and configures the idle watcher - it has no parameters of any |
… | |
… | |
1507 | their job. As C<ev_check> watchers are often used to embed other event |
1543 | their job. As C<ev_check> watchers are often used to embed other event |
1508 | loops those other event loops might be in an unusable state until their |
1544 | loops those other event loops might be in an unusable state until their |
1509 | C<ev_check> watcher ran (always remind yourself to coexist peacefully with |
1545 | C<ev_check> watcher ran (always remind yourself to coexist peacefully with |
1510 | others). |
1546 | others). |
1511 | |
1547 | |
|
|
1548 | =head3 Watcher-Specific Functions and Data Members |
|
|
1549 | |
1512 | =over 4 |
1550 | =over 4 |
1513 | |
1551 | |
1514 | =item ev_prepare_init (ev_prepare *, callback) |
1552 | =item ev_prepare_init (ev_prepare *, callback) |
1515 | |
1553 | |
1516 | =item ev_check_init (ev_check *, callback) |
1554 | =item ev_check_init (ev_check *, callback) |
… | |
… | |
1717 | ev_embed_start (loop_hi, &embed); |
1755 | ev_embed_start (loop_hi, &embed); |
1718 | } |
1756 | } |
1719 | else |
1757 | else |
1720 | loop_lo = loop_hi; |
1758 | loop_lo = loop_hi; |
1721 | |
1759 | |
|
|
1760 | =head3 Watcher-Specific Functions and Data Members |
|
|
1761 | |
1722 | =over 4 |
1762 | =over 4 |
1723 | |
1763 | |
1724 | =item ev_embed_init (ev_embed *, callback, struct ev_loop *embedded_loop) |
1764 | =item ev_embed_init (ev_embed *, callback, struct ev_loop *embedded_loop) |
1725 | |
1765 | |
1726 | =item ev_embed_set (ev_embed *, callback, struct ev_loop *embedded_loop) |
1766 | =item ev_embed_set (ev_embed *, callback, struct ev_loop *embedded_loop) |