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.46 by root, Mon Nov 26 10:20:43 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
… …
1654 1718
1655 #define EV_COMMON \ 1719 #define EV_COMMON \
1656 SV *self; /* contains this struct */ \ 1720 SV *self; /* contains this struct */ \
1657 SV *cb_sv, *fh /* note no trailing ";" */ 1721 SV *cb_sv, *fh /* note no trailing ";" */
1658 1722
1659=item EV_CB_DECLARE(type) 1723=item EV_CB_DECLARE (type)
1660 1724
1661=item EV_CB_INVOKE(watcher,revents) 1725=item EV_CB_INVOKE (watcher, revents)
1662 1726
1663=item ev_set_cb(ev,cb) 1727=item ev_set_cb (ev, cb)
1664 1728
1665Can be used to change the callback member declaration in each watcher, 1729Can 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 1730and 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 1731definition and a statement, respectively. See the F<ev.v> header file for
1668their default definitions. One possible use for overriding these is to 1732their 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 1733avoid the C<struct ev_loop *> as first argument in all cases, or to use
1670calls instead of plain function calls in C++. 1734method calls instead of plain function calls in C++.
1671 1735
1672=head2 EXAMPLES 1736=head2 EXAMPLES
1673 1737
1674For a real-world example of a program the includes libev 1738For a real-world example of a program the includes libev
1675verbatim, you can have a look at the EV perl module 1739verbatim, 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: 1756And a F<ev_cpp.C> implementation file that contains libev proper and is compiled:
1693 1757
1694 #include "ev_cpp.h" 1758 #include "ev_cpp.h"
1695 #include "ev.c" 1759 #include "ev.c"
1696 1760
1761
1762=head1 COMPLEXITIES
1763
1764In this section the complexities of (many of) the algorithms used inside
1765libev will be explained. For complexity discussions about backends see the
1766documentation for C<ev_default_init>.
1767
1768=over 4
1769
1770=item Starting and stopping timer/periodic watchers: O(log skipped_other_timers)
1771
1772=item Changing timer/periodic watchers (by autorepeat, again): O(log skipped_other_timers)
1773
1774=item Starting io/check/prepare/idle/signal/child watchers: O(1)
1775
1776=item Stopping check/prepare/idle watchers: O(1)
1777
1778=item Stopping an io/signal/child watcher: O(number_of_watchers_for_this_(fd/signal/pid % 16))
1779
1780=item Finding the next timer per loop iteration: O(1)
1781
1782=item Each change on a file descriptor per loop iteration: O(number_of_watchers_for_this_fd)
1783
1784=item Activating one watcher: O(1)
1785
1786=back
1787
1788
1697=head1 AUTHOR 1789=head1 AUTHOR
1698 1790
1699Marc Lehmann <libev@schmorp.de>. 1791Marc Lehmann <libev@schmorp.de>.
1700 1792

Diff Legend

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