ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/libev/ev.pod
(Generate patch)

Comparing libev/ev.pod (file contents):
Revision 1.43 by root, Sat Nov 24 16:33:23 2007 UTC vs.
Revision 1.47 by root, Mon Nov 26 19:49:36 2007 UTC

… …
1102 1102
1103Prepare and check watchers are usually (but not always) used in tandem: 1103Prepare and check watchers are usually (but not always) used in tandem:
1104prepare watchers get invoked before the process blocks and check watchers 1104prepare watchers get invoked before the process blocks and check watchers
1105afterwards. 1105afterwards.
1106 1106
1107You I<must not> call C<ev_loop> or similar functions that enter
1108the current event loop from either C<ev_prepare> or C<ev_check>
1109watchers. Other loops than the current one are fine, however. The
1110rationale behind this is that you do not need to check for recursion in
1111those watchers, i.e. the sequence will always be C<ev_prepare>, blocking,
1112C<ev_check> so if you have one watcher of each kind they will always be
1113called in pairs bracketing the blocking call.
1114
1107Their main purpose is to integrate other event mechanisms into libev and 1115Their main purpose is to integrate other event mechanisms into libev and
1108their use is somewhat advanced. This could be used, for example, to track 1116their use is somewhat advanced. This could be used, for example, to track
1109variable changes, implement your own watchers, integrate net-snmp or a 1117variable changes, implement your own watchers, integrate net-snmp or a
1110coroutine library and lots more. 1118coroutine library and lots more. They are also occasionally useful if
1119you cache some data and want to flush it before blocking (for example,
1120in X programs you might want to do an C<XFlush ()> in an C<ev_prepare>
1121watcher).
1111 1122
1112This is done by examining in each prepare call which file descriptors need 1123This is done by examining in each prepare call which file descriptors need
1113to be watched by the other library, registering C<ev_io> watchers for 1124to be watched by the other library, registering C<ev_io> watchers for
1114them and starting an C<ev_timer> watcher for any timeouts (many libraries 1125them and starting an C<ev_timer> watcher for any timeouts (many libraries
1115provide just this functionality). Then, in the check watcher you check for 1126provide just this functionality). Then, in the check watcher you check for
… …
1137parameters of any kind. There are C<ev_prepare_set> and C<ev_check_set> 1148parameters of any kind. There are C<ev_prepare_set> and C<ev_check_set>
1138macros, but using them is utterly, utterly and completely pointless. 1149macros, but using them is utterly, utterly and completely pointless.
1139 1150
1140=back 1151=back
1141 1152
1142Example: *TODO*. 1153Example: To include a library such as adns, you would add IO watchers
1154and a timeout watcher in a prepare handler, as required by libadns, and
1155in a check watcher, destroy them and call into libadns. What follows is
1156pseudo-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
1147This is a rather advanced watcher type that lets you embed one event loop 1211This is a rather advanced watcher type that lets you embed one event loop
… …
1636will have the C<struct ev_loop *> as first argument, and you can create 1700will have the C<struct ev_loop *> as first argument, and you can create
1637additional independent event loops. Otherwise there will be no support 1701additional independent event loops. Otherwise there will be no support
1638for multiple event loops and there is no first event loop pointer 1702for multiple event loops and there is no first event loop pointer
1639argument. Instead, all functions act on the single default loop. 1703argument. Instead, all functions act on the single default loop.
1640 1704
1641=item EV_PERIODICS 1705=item EV_PERIODIC_ENABLE
1642 1706
1643If undefined or defined to be C<1>, then periodic timers are supported, 1707If undefined or defined to be C<1>, then periodic timers are supported. If
1644otherwise not. This saves a few kb of code. 1708defined to be C<0>, then they are not. Disabling them saves a few kB of
1709code.
1710
1711=item EV_EMBED_ENABLE
1712
1713If undefined or defined to be C<1>, then embed watchers are supported. If
1714defined to be C<0>, then they are not.
1715
1716=item EV_STAT_ENABLE
1717
1718If undefined or defined to be C<1>, then stat watchers are supported. If
1719defined to be C<0>, then they are not.
1720
1721=item EV_MINIMAL
1722
1723If you need to shave off some kilobytes of code at the expense of some
1724speed, define this symbol to C<1>. Currently only used for gcc to override
1725some inlining decisions, saves roughly 30% codesize of amd64.
1645 1726
1646=item EV_COMMON 1727=item EV_COMMON
1647 1728
1648By default, all watchers have a C<void *data> member. By redefining 1729By default, all watchers have a C<void *data> member. By redefining
1649this macro to a something else you can include more and other types of 1730this 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
1665Can be used to change the callback member declaration in each watcher, 1746Can be used to change the callback member declaration in each watcher,
1666and the way callbacks are invoked and set. Must expand to a struct member 1747and the way callbacks are invoked and set. Must expand to a struct member
1667definition and a statement, respectively. See the F<ev.v> header file for 1748definition and a statement, respectively. See the F<ev.v> header file for
1668their default definitions. One possible use for overriding these is to 1749their default definitions. One possible use for overriding these is to
1669avoid the ev_loop pointer as first argument in all cases, or to use method 1750avoid the C<struct ev_loop *> as first argument in all cases, or to use
1670calls instead of plain function calls in C++. 1751method calls instead of plain function calls in C++.
1671 1752
1672=head2 EXAMPLES 1753=head2 EXAMPLES
1673 1754
1674For a real-world example of a program the includes libev 1755For a real-world example of a program the includes libev
1675verbatim, you can have a look at the EV perl module 1756verbatim, you can have a look at the EV perl module
… …
1692And a F<ev_cpp.C> implementation file that contains libev proper and is compiled: 1773And 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
1781In this section the complexities of (many of) the algorithms used inside
1782libev will be explained. For complexity discussions about backends see the
1783documentation 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
1699Marc Lehmann <libev@schmorp.de>. 1808Marc Lehmann <libev@schmorp.de>.
1700 1809

Diff Legend

– Removed lines
+ Added lines
< Changed lines
> Changed lines