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

Comparing libev/ev.html (file contents):
Revision 1.45 by root, Sat Nov 24 16:57:39 2007 UTC vs.
Revision 1.47 by root, Mon Nov 26 10:20:43 2007 UTC

… …
4<head> 4<head>
5 <title>libev</title> 5 <title>libev</title>
6 <meta name="description" content="Pod documentation for libev" /> 6 <meta name="description" content="Pod documentation for libev" />
7 <meta name="inputfile" content="&lt;standard input&gt;" /> 7 <meta name="inputfile" content="&lt;standard input&gt;" />
8 <meta name="outputfile" content="&lt;standard output&gt;" /> 8 <meta name="outputfile" content="&lt;standard output&gt;" />
9 <meta name="created" content="Sat Nov 24 17:57:37 2007" /> 9 <meta name="created" content="Mon Nov 26 11:20:35 2007" />
10 <meta name="generator" content="Pod::Xhtml 1.57" /> 10 <meta name="generator" content="Pod::Xhtml 1.57" />
11<link rel="stylesheet" href="http://res.tst.eu/pod.css"/></head> 11<link rel="stylesheet" href="http://res.tst.eu/pod.css"/></head>
12<body> 12<body>
13<div class="pod"> 13<div class="pod">
14<!-- INDEX START --> 14<!-- INDEX START -->
… …
50</li> 50</li>
51<li><a href="#PREPROCESSOR_SYMBOLS_MACROS">PREPROCESSOR SYMBOLS/MACROS</a></li> 51<li><a href="#PREPROCESSOR_SYMBOLS_MACROS">PREPROCESSOR SYMBOLS/MACROS</a></li>
52<li><a href="#EXAMPLES">EXAMPLES</a></li> 52<li><a href="#EXAMPLES">EXAMPLES</a></li>
53</ul> 53</ul>
54</li> 54</li>
55<li><a href="#COMPLEXITIES">COMPLEXITIES</a></li>
55<li><a href="#AUTHOR">AUTHOR</a> 56<li><a href="#AUTHOR">AUTHOR</a>
56</li> 57</li>
57</ul><hr /> 58</ul><hr />
58<!-- INDEX END --> 59<!-- INDEX END -->
59 60
… …
1126<h2 id="code_ev_prepare_code_and_code_ev_che"><code>ev_prepare</code> and <code>ev_check</code> - customise your event loop!</h2> 1127<h2 id="code_ev_prepare_code_and_code_ev_che"><code>ev_prepare</code> and <code>ev_check</code> - customise your event loop!</h2>
1127<div id="code_ev_prepare_code_and_code_ev_che-2"> 1128<div id="code_ev_prepare_code_and_code_ev_che-2">
1128<p>Prepare and check watchers are usually (but not always) used in tandem: 1129<p>Prepare and check watchers are usually (but not always) used in tandem:
1129prepare watchers get invoked before the process blocks and check watchers 1130prepare watchers get invoked before the process blocks and check watchers
1130afterwards.</p> 1131afterwards.</p>
1132<p>You <i>must not</i> call <code>ev_loop</code> or similar functions that enter
1133the current event loop from either <code>ev_prepare</code> or <code>ev_check</code>
1134watchers. Other loops than the current one are fine, however. The
1135rationale behind this is that you do not need to check for recursion in
1136those watchers, i.e. the sequence will always be <code>ev_prepare</code>, blocking,
1137<code>ev_check</code> so if you have one watcher of each kind they will always be
1138called in pairs bracketing the blocking call.</p>
1131<p>Their main purpose is to integrate other event mechanisms into libev and 1139<p>Their main purpose is to integrate other event mechanisms into libev and
1132their use is somewhat advanced. This could be used, for example, to track 1140their use is somewhat advanced. This could be used, for example, to track
1133variable changes, implement your own watchers, integrate net-snmp or a 1141variable changes, implement your own watchers, integrate net-snmp or a
1134coroutine library and lots more.</p> 1142coroutine library and lots more. They are also occasionally useful if
1143you cache some data and want to flush it before blocking (for example,
1144in X programs you might want to do an <code>XFlush ()</code> in an <code>ev_prepare</code>
1145watcher).</p>
1135<p>This is done by examining in each prepare call which file descriptors need 1146<p>This is done by examining in each prepare call which file descriptors need
1136to be watched by the other library, registering <code>ev_io</code> watchers for 1147to be watched by the other library, registering <code>ev_io</code> watchers for
1137them and starting an <code>ev_timer</code> watcher for any timeouts (many libraries 1148them and starting an <code>ev_timer</code> watcher for any timeouts (many libraries
1138provide just this functionality). Then, in the check watcher you check for 1149provide just this functionality). Then, in the check watcher you check for
1139any events that occured (by checking the pending status of all watchers 1150any events that occured (by checking the pending status of all watchers
… …
1155 <p>Initialises and configures the prepare or check watcher - they have no 1166 <p>Initialises and configures the prepare or check watcher - they have no
1156parameters of any kind. There are <code>ev_prepare_set</code> and <code>ev_check_set</code> 1167parameters of any kind. There are <code>ev_prepare_set</code> and <code>ev_check_set</code>
1157macros, but using them is utterly, utterly and completely pointless.</p> 1168macros, but using them is utterly, utterly and completely pointless.</p>
1158 </dd> 1169 </dd>
1159</dl> 1170</dl>
1160<p>Example: *TODO*.</p> 1171<p>Example: To include a library such as adns, you would add IO watchers
1172and a timeout watcher in a prepare handler, as required by libadns, and
1173in a check watcher, destroy them and call into libadns. What follows is
1174pseudo-code only of course:</p>
1175<pre> static ev_io iow [nfd];
1176 static ev_timer tw;
1161 1177
1178 static void
1179 io_cb (ev_loop *loop, ev_io *w, int revents)
1180 {
1181 // set the relevant poll flags
1182 // could also call adns_processreadable etc. here
1183 struct pollfd *fd = (struct pollfd *)w-&gt;data;
1184 if (revents &amp; EV_READ ) fd-&gt;revents |= fd-&gt;events &amp; POLLIN;
1185 if (revents &amp; EV_WRITE) fd-&gt;revents |= fd-&gt;events &amp; POLLOUT;
1186 }
1162 1187
1188 // create io watchers for each fd and a timer before blocking
1189 static void
1190 adns_prepare_cb (ev_loop *loop, ev_prepare *w, int revents)
1191 {
1192 int timeout = 3600000;truct pollfd fds [nfd];
1193 // actual code will need to loop here and realloc etc.
1194 adns_beforepoll (ads, fds, &amp;nfd, &amp;timeout, timeval_from (ev_time ()));
1163 1195
1196 /* the callback is illegal, but won't be called as we stop during check */
1197 ev_timer_init (&amp;tw, 0, timeout * 1e-3);
1198 ev_timer_start (loop, &amp;tw);
1164 1199
1200 // create on ev_io per pollfd
1201 for (int i = 0; i &lt; nfd; ++i)
1202 {
1203 ev_io_init (iow + i, io_cb, fds [i].fd,
1204 ((fds [i].events &amp; POLLIN ? EV_READ : 0)
1205 | (fds [i].events &amp; POLLOUT ? EV_WRITE : 0)));
1206
1207 fds [i].revents = 0;
1208 iow [i].data = fds + i;
1209 ev_io_start (loop, iow + i);
1210 }
1211 }
1212
1213 // stop all watchers after blocking
1214 static void
1215 adns_check_cb (ev_loop *loop, ev_check *w, int revents)
1216 {
1217 ev_timer_stop (loop, &amp;tw);
1218
1219 for (int i = 0; i &lt; nfd; ++i)
1220 ev_io_stop (loop, iow + i);
1221
1222 adns_afterpoll (adns, fds, nfd, timeval_from (ev_now (loop));
1223 }
1224
1225
1226
1227
1228</pre>
1165 1229
1166</div> 1230</div>
1167<h2 id="code_ev_embed_code_when_one_backend_"><code>ev_embed</code> - when one backend isn't enough...</h2> 1231<h2 id="code_ev_embed_code_when_one_backend_"><code>ev_embed</code> - when one backend isn't enough...</h2>
1168<div id="code_ev_embed_code_when_one_backend_-2"> 1232<div id="code_ev_embed_code_when_one_backend_-2">
1169<p>This is a rather advanced watcher type that lets you embed one event loop 1233<p>This is a rather advanced watcher type that lets you embed one event loop
… …
1691</pre> 1755</pre>
1692 <p>And a <cite>ev_cpp.C</cite> implementation file that contains libev proper and is compiled:</p> 1756 <p>And a <cite>ev_cpp.C</cite> implementation file that contains libev proper and is compiled:</p>
1693<pre> #include &quot;ev_cpp.h&quot; 1757<pre> #include &quot;ev_cpp.h&quot;
1694 #include &quot;ev.c&quot; 1758 #include &quot;ev.c&quot;
1695 1759
1760
1761
1762
1696</pre> 1763</pre>
1764
1765</div>
1766<h1 id="COMPLEXITIES">COMPLEXITIES</h1><p><a href="#TOP" class="toplink">Top</a></p>
1767<div id="COMPLEXITIES_CONTENT">
1768 <p>In this section the complexities of (many of) the algorithms used inside
1769libev will be explained. For complexity discussions about backends see the
1770documentation for <code>ev_default_init</code>.</p>
1771 <p>
1772 <dl>
1773 <dt>Starting and stopping timer/periodic watchers: O(log skipped_other_timers)</dt>
1774 <dt>Changing timer/periodic watchers (by autorepeat, again): O(log skipped_other_timers)</dt>
1775 <dt>Starting io/check/prepare/idle/signal/child watchers: O(1)</dt>
1776 <dt>Stopping check/prepare/idle watchers: O(1)</dt>
1777 <dt>Stopping an io/signal/child watcher: O(number_of_watchers_for_this_(fd/signal/pid % 16))</dt>
1778 <dt>Finding the next timer per loop iteration: O(1)</dt>
1779 <dt>Each change on a file descriptor per loop iteration: O(number_of_watchers_for_this_fd)</dt>
1780 <dt>Activating one watcher: O(1)</dt>
1781 </dl>
1782 </p>
1783
1784
1785
1786
1697 1787
1698</div> 1788</div>
1699<h1 id="AUTHOR">AUTHOR</h1><p><a href="#TOP" class="toplink">Top</a></p> 1789<h1 id="AUTHOR">AUTHOR</h1><p><a href="#TOP" class="toplink">Top</a></p>
1700<div id="AUTHOR_CONTENT"> 1790<div id="AUTHOR_CONTENT">
1701 <p>Marc Lehmann &lt;libev@schmorp.de&gt;.</p> 1791 <p>Marc Lehmann &lt;libev@schmorp.de&gt;.</p>

Diff Legend

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