… | |
… | |
1102 | |
1102 | |
1103 | Prepare and check watchers are usually (but not always) used in tandem: |
1103 | Prepare and check watchers are usually (but not always) used in tandem: |
1104 | prepare watchers get invoked before the process blocks and check watchers |
1104 | prepare watchers get invoked before the process blocks and check watchers |
1105 | afterwards. |
1105 | afterwards. |
1106 | |
1106 | |
|
|
1107 | You I<must not> call C<ev_loop> or similar functions that enter |
|
|
1108 | the current event loop from either C<ev_prepare> or C<ev_check> |
|
|
1109 | watchers. Other loops than the current one are fine, however. The |
|
|
1110 | rationale behind this is that you do not need to check for recursion in |
|
|
1111 | those watchers, i.e. the sequence will always be C<ev_prepare>, blocking, |
|
|
1112 | C<ev_check> so if you have one watcher of each kind they will always be |
|
|
1113 | called in pairs bracketing the blocking call. |
|
|
1114 | |
1107 | Their main purpose is to integrate other event mechanisms into libev and |
1115 | Their main purpose is to integrate other event mechanisms into libev and |
1108 | their use is somewhat advanced. This could be used, for example, to track |
1116 | their use is somewhat advanced. This could be used, for example, to track |
1109 | variable changes, implement your own watchers, integrate net-snmp or a |
1117 | variable changes, implement your own watchers, integrate net-snmp or a |
1110 | coroutine library and lots more. |
1118 | coroutine library and lots more. They are also occasionally useful if |
|
|
1119 | you cache some data and want to flush it before blocking (for example, |
|
|
1120 | in X programs you might want to do an C<XFlush ()> in an C<ev_prepare> |
|
|
1121 | watcher). |
1111 | |
1122 | |
1112 | This is done by examining in each prepare call which file descriptors need |
1123 | This is done by examining in each prepare call which file descriptors need |
1113 | to be watched by the other library, registering C<ev_io> watchers for |
1124 | to be watched by the other library, registering C<ev_io> watchers for |
1114 | them and starting an C<ev_timer> watcher for any timeouts (many libraries |
1125 | them and starting an C<ev_timer> watcher for any timeouts (many libraries |
1115 | provide just this functionality). Then, in the check watcher you check for |
1126 | provide just this functionality). Then, in the check watcher you check for |
… | |
… | |
1137 | parameters of any kind. There are C<ev_prepare_set> and C<ev_check_set> |
1148 | parameters of any kind. There are C<ev_prepare_set> and C<ev_check_set> |
1138 | macros, but using them is utterly, utterly and completely pointless. |
1149 | macros, but using them is utterly, utterly and completely pointless. |
1139 | |
1150 | |
1140 | =back |
1151 | =back |
1141 | |
1152 | |
1142 | Example: *TODO*. |
1153 | Example: To include a library such as adns, you would add IO watchers |
|
|
1154 | and a timeout watcher in a prepare handler, as required by libadns, and |
|
|
1155 | in a check watcher, destroy them and call into libadns. What follows is |
|
|
1156 | pseudo-code only of course: |
|
|
1157 | |
|
|
1158 | static ev_io iow [nfd]; |
|
|
1159 | static ev_timer tw; |
|
|
1160 | |
|
|
1161 | static void |
|
|
1162 | io_cb (ev_loop *loop, ev_io *w, int revents) |
|
|
1163 | { |
|
|
1164 | // set the relevant poll flags |
|
|
1165 | // could also call adns_processreadable etc. here |
|
|
1166 | struct pollfd *fd = (struct pollfd *)w->data; |
|
|
1167 | if (revents & EV_READ ) fd->revents |= fd->events & POLLIN; |
|
|
1168 | if (revents & EV_WRITE) fd->revents |= fd->events & POLLOUT; |
|
|
1169 | } |
|
|
1170 | |
|
|
1171 | // create io watchers for each fd and a timer before blocking |
|
|
1172 | static void |
|
|
1173 | adns_prepare_cb (ev_loop *loop, ev_prepare *w, int revents) |
|
|
1174 | { |
|
|
1175 | int timeout = 3600000;truct pollfd fds [nfd]; |
|
|
1176 | // actual code will need to loop here and realloc etc. |
|
|
1177 | adns_beforepoll (ads, fds, &nfd, &timeout, timeval_from (ev_time ())); |
|
|
1178 | |
|
|
1179 | /* the callback is illegal, but won't be called as we stop during check */ |
|
|
1180 | ev_timer_init (&tw, 0, timeout * 1e-3); |
|
|
1181 | ev_timer_start (loop, &tw); |
|
|
1182 | |
|
|
1183 | // create on ev_io per pollfd |
|
|
1184 | for (int i = 0; i < nfd; ++i) |
|
|
1185 | { |
|
|
1186 | ev_io_init (iow + i, io_cb, fds [i].fd, |
|
|
1187 | ((fds [i].events & POLLIN ? EV_READ : 0) |
|
|
1188 | | (fds [i].events & POLLOUT ? EV_WRITE : 0))); |
|
|
1189 | |
|
|
1190 | fds [i].revents = 0; |
|
|
1191 | iow [i].data = fds + i; |
|
|
1192 | ev_io_start (loop, iow + i); |
|
|
1193 | } |
|
|
1194 | } |
|
|
1195 | |
|
|
1196 | // stop all watchers after blocking |
|
|
1197 | static void |
|
|
1198 | adns_check_cb (ev_loop *loop, ev_check *w, int revents) |
|
|
1199 | { |
|
|
1200 | ev_timer_stop (loop, &tw); |
|
|
1201 | |
|
|
1202 | for (int i = 0; i < nfd; ++i) |
|
|
1203 | ev_io_stop (loop, iow + i); |
|
|
1204 | |
|
|
1205 | adns_afterpoll (adns, fds, nfd, timeval_from (ev_now (loop)); |
|
|
1206 | } |
1143 | |
1207 | |
1144 | |
1208 | |
1145 | =head2 C<ev_embed> - when one backend isn't enough... |
1209 | =head2 C<ev_embed> - when one backend isn't enough... |
1146 | |
1210 | |
1147 | This is a rather advanced watcher type that lets you embed one event loop |
1211 | This is a rather advanced watcher type that lets you embed one event loop |
… | |
… | |
1469 | ev_vars.h |
1533 | ev_vars.h |
1470 | ev_wrap.h |
1534 | ev_wrap.h |
1471 | |
1535 | |
1472 | ev_win32.c required on win32 platforms only |
1536 | ev_win32.c required on win32 platforms only |
1473 | |
1537 | |
1474 | ev_select.c only when select backend is enabled (which is is by default) |
1538 | ev_select.c only when select backend is enabled (which is by default) |
1475 | ev_poll.c only when poll backend is enabled (disabled by default) |
1539 | ev_poll.c only when poll backend is enabled (disabled by default) |
1476 | ev_epoll.c only when the epoll backend is enabled (disabled by default) |
1540 | ev_epoll.c only when the epoll backend is enabled (disabled by default) |
1477 | ev_kqueue.c only when the kqueue backend is enabled (disabled by default) |
1541 | ev_kqueue.c only when the kqueue backend is enabled (disabled by default) |
1478 | ev_port.c only when the solaris port backend is enabled (disabled by default) |
1542 | ev_port.c only when the solaris port backend is enabled (disabled by default) |
1479 | |
1543 | |
1480 | F<ev.c> includes the backend files directly when enabled, so you only need |
1544 | F<ev.c> includes the backend files directly when enabled, so you only need |
1481 | to compile a single file. |
1545 | to compile this single file. |
1482 | |
1546 | |
1483 | =head3 LIBEVENT COMPATIBILITY API |
1547 | =head3 LIBEVENT COMPATIBILITY API |
1484 | |
1548 | |
1485 | To include the libevent compatibility API, also include: |
1549 | To include the libevent compatibility API, also include: |
1486 | |
1550 | |
… | |
… | |
1499 | |
1563 | |
1500 | =head3 AUTOCONF SUPPORT |
1564 | =head3 AUTOCONF SUPPORT |
1501 | |
1565 | |
1502 | Instead of using C<EV_STANDALONE=1> and providing your config in |
1566 | Instead of using C<EV_STANDALONE=1> and providing your config in |
1503 | whatever way you want, you can also C<m4_include([libev.m4])> in your |
1567 | whatever way you want, you can also C<m4_include([libev.m4])> in your |
1504 | F<configure.ac> and leave C<EV_STANDALONE> off. F<ev.c> will then include |
1568 | F<configure.ac> and leave C<EV_STANDALONE> undefined. F<ev.c> will then |
1505 | F<config.h> and configure itself accordingly. |
1569 | include F<config.h> and configure itself accordingly. |
1506 | |
1570 | |
1507 | For this of course you need the m4 file: |
1571 | For this of course you need the m4 file: |
1508 | |
1572 | |
1509 | libev.m4 |
1573 | libev.m4 |
1510 | |
1574 | |
… | |
… | |
1636 | will have the C<struct ev_loop *> as first argument, and you can create |
1700 | will have the C<struct ev_loop *> as first argument, and you can create |
1637 | additional independent event loops. Otherwise there will be no support |
1701 | additional independent event loops. Otherwise there will be no support |
1638 | for multiple event loops and there is no first event loop pointer |
1702 | for multiple event loops and there is no first event loop pointer |
1639 | argument. Instead, all functions act on the single default loop. |
1703 | argument. Instead, all functions act on the single default loop. |
1640 | |
1704 | |
1641 | =item EV_PERIODICS |
1705 | =item EV_PERIODIC_ENABLE |
1642 | |
1706 | |
1643 | If undefined or defined to be C<1>, then periodic timers are supported, |
1707 | If undefined or defined to be C<1>, then periodic timers are supported. If |
1644 | otherwise not. This saves a few kb of code. |
1708 | defined to be C<0>, then they are not. Disabling them saves a few kB of |
|
|
1709 | code. |
|
|
1710 | |
|
|
1711 | =item EV_EMBED_ENABLE |
|
|
1712 | |
|
|
1713 | If undefined or defined to be C<1>, then embed watchers are supported. If |
|
|
1714 | defined to be C<0>, then they are not. |
|
|
1715 | |
|
|
1716 | =item EV_STAT_ENABLE |
|
|
1717 | |
|
|
1718 | If undefined or defined to be C<1>, then stat watchers are supported. If |
|
|
1719 | defined to be C<0>, then they are not. |
|
|
1720 | |
|
|
1721 | =item EV_MINIMAL |
|
|
1722 | |
|
|
1723 | If you need to shave off some kilobytes of code at the expense of some |
|
|
1724 | speed, define this symbol to C<1>. Currently only used for gcc to override |
|
|
1725 | some inlining decisions, saves roughly 30% codesize of amd64. |
1645 | |
1726 | |
1646 | =item EV_COMMON |
1727 | =item EV_COMMON |
1647 | |
1728 | |
1648 | By default, all watchers have a C<void *data> member. By redefining |
1729 | By default, all watchers have a C<void *data> member. By redefining |
1649 | this macro to a something else you can include more and other types of |
1730 | this macro to a something else you can include more and other types of |
… | |
… | |
1654 | |
1735 | |
1655 | #define EV_COMMON \ |
1736 | #define EV_COMMON \ |
1656 | SV *self; /* contains this struct */ \ |
1737 | SV *self; /* contains this struct */ \ |
1657 | SV *cb_sv, *fh /* note no trailing ";" */ |
1738 | SV *cb_sv, *fh /* note no trailing ";" */ |
1658 | |
1739 | |
1659 | =item EV_CB_DECLARE(type) |
1740 | =item EV_CB_DECLARE (type) |
1660 | |
1741 | |
1661 | =item EV_CB_INVOKE(watcher,revents) |
1742 | =item EV_CB_INVOKE (watcher, revents) |
1662 | |
1743 | |
1663 | =item ev_set_cb(ev,cb) |
1744 | =item ev_set_cb (ev, cb) |
1664 | |
1745 | |
1665 | Can be used to change the callback member declaration in each watcher, |
1746 | Can be used to change the callback member declaration in each watcher, |
1666 | and the way callbacks are invoked and set. Must expand to a struct member |
1747 | and the way callbacks are invoked and set. Must expand to a struct member |
1667 | definition and a statement, respectively. See the F<ev.v> header file for |
1748 | definition and a statement, respectively. See the F<ev.v> header file for |
1668 | their default definitions. One possible use for overriding these is to |
1749 | their default definitions. One possible use for overriding these is to |
1669 | avoid the ev_loop pointer as first argument in all cases, or to use method |
1750 | avoid the C<struct ev_loop *> as first argument in all cases, or to use |
1670 | calls instead of plain function calls in C++. |
1751 | method calls instead of plain function calls in C++. |
1671 | |
1752 | |
1672 | =head2 EXAMPLES |
1753 | =head2 EXAMPLES |
1673 | |
1754 | |
1674 | For a real-world example of a program the includes libev |
1755 | For a real-world example of a program the includes libev |
1675 | verbatim, you can have a look at the EV perl module |
1756 | verbatim, you can have a look at the EV perl module |
… | |
… | |
1692 | And a F<ev_cpp.C> implementation file that contains libev proper and is compiled: |
1773 | And a F<ev_cpp.C> implementation file that contains libev proper and is compiled: |
1693 | |
1774 | |
1694 | #include "ev_cpp.h" |
1775 | #include "ev_cpp.h" |
1695 | #include "ev.c" |
1776 | #include "ev.c" |
1696 | |
1777 | |
|
|
1778 | |
|
|
1779 | =head1 COMPLEXITIES |
|
|
1780 | |
|
|
1781 | In this section the complexities of (many of) the algorithms used inside |
|
|
1782 | libev will be explained. For complexity discussions about backends see the |
|
|
1783 | documentation for C<ev_default_init>. |
|
|
1784 | |
|
|
1785 | =over 4 |
|
|
1786 | |
|
|
1787 | =item Starting and stopping timer/periodic watchers: O(log skipped_other_timers) |
|
|
1788 | |
|
|
1789 | =item Changing timer/periodic watchers (by autorepeat, again): O(log skipped_other_timers) |
|
|
1790 | |
|
|
1791 | =item Starting io/check/prepare/idle/signal/child watchers: O(1) |
|
|
1792 | |
|
|
1793 | =item Stopping check/prepare/idle watchers: O(1) |
|
|
1794 | |
|
|
1795 | =item Stopping an io/signal/child watcher: O(number_of_watchers_for_this_(fd/signal/pid % 16)) |
|
|
1796 | |
|
|
1797 | =item Finding the next timer per loop iteration: O(1) |
|
|
1798 | |
|
|
1799 | =item Each change on a file descriptor per loop iteration: O(number_of_watchers_for_this_fd) |
|
|
1800 | |
|
|
1801 | =item Activating one watcher: O(1) |
|
|
1802 | |
|
|
1803 | =back |
|
|
1804 | |
|
|
1805 | |
1697 | =head1 AUTHOR |
1806 | =head1 AUTHOR |
1698 | |
1807 | |
1699 | Marc Lehmann <libev@schmorp.de>. |
1808 | Marc Lehmann <libev@schmorp.de>. |
1700 | |
1809 | |