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

Comparing libev/ev.html (file contents):
Revision 1.36 by root, Sat Nov 24 06:23:27 2007 UTC vs.
Revision 1.41 by root, Sat Nov 24 10:15:16 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 05:58:35 2007" /> 9 <meta name="created" content="Sat Nov 24 11:15:15 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 -->
… …
21<li><a href="#CONVENTIONS">CONVENTIONS</a></li> 21<li><a href="#CONVENTIONS">CONVENTIONS</a></li>
22<li><a href="#TIME_REPRESENTATION">TIME REPRESENTATION</a></li> 22<li><a href="#TIME_REPRESENTATION">TIME REPRESENTATION</a></li>
23<li><a href="#GLOBAL_FUNCTIONS">GLOBAL FUNCTIONS</a></li> 23<li><a href="#GLOBAL_FUNCTIONS">GLOBAL FUNCTIONS</a></li>
24<li><a href="#FUNCTIONS_CONTROLLING_THE_EVENT_LOOP">FUNCTIONS CONTROLLING THE EVENT LOOP</a></li> 24<li><a href="#FUNCTIONS_CONTROLLING_THE_EVENT_LOOP">FUNCTIONS CONTROLLING THE EVENT LOOP</a></li>
25<li><a href="#ANATOMY_OF_A_WATCHER">ANATOMY OF A WATCHER</a> 25<li><a href="#ANATOMY_OF_A_WATCHER">ANATOMY OF A WATCHER</a>
26<ul><li><a href="#SUMMARY_OF_GENERIC_WATCHER_FUNCTIONS">SUMMARY OF GENERIC WATCHER FUNCTIONS</a></li>
26<ul><li><a href="#ASSOCIATING_CUSTOM_DATA_WITH_A_WATCH">ASSOCIATING CUSTOM DATA WITH A WATCHER</a></li> 27<li><a href="#ASSOCIATING_CUSTOM_DATA_WITH_A_WATCH">ASSOCIATING CUSTOM DATA WITH A WATCHER</a></li>
27</ul> 28</ul>
28</li> 29</li>
29<li><a href="#WATCHER_TYPES">WATCHER TYPES</a> 30<li><a href="#WATCHER_TYPES">WATCHER TYPES</a>
30<ul><li><a href="#code_ev_io_code_is_this_file_descrip"><code>ev_io</code> - is this file descriptor readable or writable</a></li> 31<ul><li><a href="#code_ev_io_code_is_this_file_descrip"><code>ev_io</code> - is this file descriptor readable or writable</a></li>
31<li><a href="#code_ev_timer_code_relative_and_opti"><code>ev_timer</code> - relative and optionally recurring timeouts</a></li> 32<li><a href="#code_ev_timer_code_relative_and_opti"><code>ev_timer</code> - relative and optionally recurring timeouts</a></li>
… …
38</ul> 39</ul>
39</li> 40</li>
40<li><a href="#OTHER_FUNCTIONS">OTHER FUNCTIONS</a></li> 41<li><a href="#OTHER_FUNCTIONS">OTHER FUNCTIONS</a></li>
41<li><a href="#LIBEVENT_EMULATION">LIBEVENT EMULATION</a></li> 42<li><a href="#LIBEVENT_EMULATION">LIBEVENT EMULATION</a></li>
42<li><a href="#C_SUPPORT">C++ SUPPORT</a></li> 43<li><a href="#C_SUPPORT">C++ SUPPORT</a></li>
44<li><a href="#EMBEDDING">EMBEDDING</a>
45<ul><li><a href="#FILESETS">FILESETS</a>
46<ul><li><a href="#CORE_EVENT_LOOP">CORE EVENT LOOP</a></li>
47<li><a href="#LIBEVENT_COMPATIBILITY_API">LIBEVENT COMPATIBILITY API</a></li>
48<li><a href="#AUTOCONF_SUPPORT">AUTOCONF SUPPORT</a></li>
49</ul>
50</li>
51<li><a href="#PREPROCESSOR_SYMBOLS_MACROS">PREPROCESSOR SYMBOLS/MACROS</a></li>
52<li><a href="#EXAMPLES">EXAMPLES</a></li>
53</ul>
54</li>
43<li><a href="#AUTHOR">AUTHOR</a> 55<li><a href="#AUTHOR">AUTHOR</a>
44</li> 56</li>
45</ul><hr /> 57</ul><hr />
46<!-- INDEX END --> 58<!-- INDEX END -->
47 59
… …
363</pre> 375</pre>
364 </dd> 376 </dd>
365 <dt>ev_default_destroy ()</dt> 377 <dt>ev_default_destroy ()</dt>
366 <dd> 378 <dd>
367 <p>Destroys the default loop again (frees all memory and kernel state 379 <p>Destroys the default loop again (frees all memory and kernel state
368etc.). This stops all registered event watchers (by not touching them in 380etc.). None of the active event watchers will be stopped in the normal
369any way whatsoever, although you cannot rely on this :).</p> 381sense, so e.g. <code>ev_is_active</code> might still return true. It is your
382responsibility to either stop all watchers cleanly yoursef <i>before</i>
383calling this function, or cope with the fact afterwards (which is usually
384the easiest thing, youc na just ignore the watchers and/or <code>free ()</code> them
385for example).</p>
370 </dd> 386 </dd>
371 <dt>ev_loop_destroy (loop)</dt> 387 <dt>ev_loop_destroy (loop)</dt>
372 <dd> 388 <dd>
373 <p>Like <code>ev_default_destroy</code>, but destroys an event loop created by an 389 <p>Like <code>ev_default_destroy</code>, but destroys an event loop created by an
374earlier call to <code>ev_loop_new</code>.</p> 390earlier call to <code>ev_loop_new</code>.</p>
… …
535with a watcher-specific start function (<code>ev_&lt;type&gt;_start (loop, watcher 551with a watcher-specific start function (<code>ev_&lt;type&gt;_start (loop, watcher
536*)</code>), and you can stop watching for events at any time by calling the 552*)</code>), and you can stop watching for events at any time by calling the
537corresponding stop function (<code>ev_&lt;type&gt;_stop (loop, watcher *)</code>.</p> 553corresponding stop function (<code>ev_&lt;type&gt;_stop (loop, watcher *)</code>.</p>
538<p>As long as your watcher is active (has been started but not stopped) you 554<p>As long as your watcher is active (has been started but not stopped) you
539must not touch the values stored in it. Most specifically you must never 555must not touch the values stored in it. Most specifically you must never
540reinitialise it or call its set macro.</p> 556reinitialise it or call its <code>set</code> macro.</p>
541<p>You can check whether an event is active by calling the <code>ev_is_active
542(watcher *)</code> macro. To see whether an event is outstanding (but the
543callback for it has not been called yet) you can use the <code>ev_is_pending
544(watcher *)</code> macro.</p>
545<p>Each and every callback receives the event loop pointer as first, the 557<p>Each and every callback receives the event loop pointer as first, the
546registered watcher structure as second, and a bitset of received events as 558registered watcher structure as second, and a bitset of received events as
547third argument.</p> 559third argument.</p>
548<p>The received events usually include a single bit per event type received 560<p>The received events usually include a single bit per event type received
549(you can receive multiple events at the same time). The possible bit masks 561(you can receive multiple events at the same time). The possible bit masks
… …
598your callbacks is well-written it can just attempt the operation and cope 610your callbacks is well-written it can just attempt the operation and cope
599with the error from read() or write(). This will not work in multithreaded 611with the error from read() or write(). This will not work in multithreaded
600programs, though, so beware.</p> 612programs, though, so beware.</p>
601 </dd> 613 </dd>
602</dl> 614</dl>
615
616</div>
617<h2 id="SUMMARY_OF_GENERIC_WATCHER_FUNCTIONS">SUMMARY OF GENERIC WATCHER FUNCTIONS</h2>
618<div id="SUMMARY_OF_GENERIC_WATCHER_FUNCTIONS-2">
619<p>In the following description, <code>TYPE</code> stands for the watcher type,
620e.g. <code>timer</code> for <code>ev_timer</code> watchers and <code>io</code> for <code>ev_io</code> watchers.</p>
621<dl>
622 <dt><code>ev_init</code> (ev_TYPE *watcher, callback)</dt>
623 <dd>
624 <p>This macro initialises the generic portion of a watcher. The contents
625of the watcher object can be arbitrary (so <code>malloc</code> will do). Only
626the generic parts of the watcher are initialised, you <i>need</i> to call
627the type-specific <code>ev_TYPE_set</code> macro afterwards to initialise the
628type-specific parts. For each type there is also a <code>ev_TYPE_init</code> macro
629which rolls both calls into one.</p>
630 <p>You can reinitialise a watcher at any time as long as it has been stopped
631(or never started) and there are no pending events outstanding.</p>
632 <p>The callbakc is always of type <code>void (*)(ev_loop *loop, ev_TYPE *watcher,
633int revents)</code>.</p>
634 </dd>
635 <dt><code>ev_TYPE_set</code> (ev_TYPE *, [args])</dt>
636 <dd>
637 <p>This macro initialises the type-specific parts of a watcher. You need to
638call <code>ev_init</code> at least once before you call this macro, but you can
639call <code>ev_TYPE_set</code> any number of times. You must not, however, call this
640macro on a watcher that is active (it can be pending, however, which is a
641difference to the <code>ev_init</code> macro).</p>
642 <p>Although some watcher types do not have type-specific arguments
643(e.g. <code>ev_prepare</code>) you still need to call its <code>set</code> macro.</p>
644 </dd>
645 <dt><code>ev_TYPE_init</code> (ev_TYPE *watcher, callback, [args])</dt>
646 <dd>
647 <p>This convinience macro rolls both <code>ev_init</code> and <code>ev_TYPE_set</code> macro
648calls into a single call. This is the most convinient method to initialise
649a watcher. The same limitations apply, of course.</p>
650 </dd>
651 <dt><code>ev_TYPE_start</code> (loop *, ev_TYPE *watcher)</dt>
652 <dd>
653 <p>Starts (activates) the given watcher. Only active watchers will receive
654events. If the watcher is already active nothing will happen.</p>
655 </dd>
656 <dt><code>ev_TYPE_stop</code> (loop *, ev_TYPE *watcher)</dt>
657 <dd>
658 <p>Stops the given watcher again (if active) and clears the pending
659status. It is possible that stopped watchers are pending (for example,
660non-repeating timers are being stopped when they become pending), but
661<code>ev_TYPE_stop</code> ensures that the watcher is neither active nor pending. If
662you want to free or reuse the memory used by the watcher it is therefore a
663good idea to always call its <code>ev_TYPE_stop</code> function.</p>
664 </dd>
665 <dt>bool ev_is_active (ev_TYPE *watcher)</dt>
666 <dd>
667 <p>Returns a true value iff the watcher is active (i.e. it has been started
668and not yet been stopped). As long as a watcher is active you must not modify
669it.</p>
670 </dd>
671 <dt>bool ev_is_pending (ev_TYPE *watcher)</dt>
672 <dd>
673 <p>Returns a true value iff the watcher is pending, (i.e. it has outstanding
674events but its callback has not yet been invoked). As long as a watcher
675is pending (but not active) you must not call an init function on it (but
676<code>ev_TYPE_set</code> is safe) and you must make sure the watcher is available to
677libev (e.g. you cnanot <code>free ()</code> it).</p>
678 </dd>
679 <dt>callback = ev_cb (ev_TYPE *watcher)</dt>
680 <dd>
681 <p>Returns the callback currently set on the watcher.</p>
682 </dd>
683 <dt>ev_cb_set (ev_TYPE *watcher, callback)</dt>
684 <dd>
685 <p>Change the callback. You can change the callback at virtually any time
686(modulo threads).</p>
687 </dd>
688</dl>
689
690
691
692
603 693
604</div> 694</div>
605<h2 id="ASSOCIATING_CUSTOM_DATA_WITH_A_WATCH">ASSOCIATING CUSTOM DATA WITH A WATCHER</h2> 695<h2 id="ASSOCIATING_CUSTOM_DATA_WITH_A_WATCH">ASSOCIATING CUSTOM DATA WITH A WATCHER</h2>
606<div id="ASSOCIATING_CUSTOM_DATA_WITH_A_WATCH-2"> 696<div id="ASSOCIATING_CUSTOM_DATA_WITH_A_WATCH-2">
607<p>Each watcher has, by default, a member <code>void *data</code> that you can change 697<p>Each watcher has, by default, a member <code>void *data</code> that you can change
… …
798<p>Periodic watchers are also timers of a kind, but they are very versatile 888<p>Periodic watchers are also timers of a kind, but they are very versatile
799(and unfortunately a bit complex).</p> 889(and unfortunately a bit complex).</p>
800<p>Unlike <code>ev_timer</code>'s, they are not based on real time (or relative time) 890<p>Unlike <code>ev_timer</code>'s, they are not based on real time (or relative time)
801but on wallclock time (absolute time). You can tell a periodic watcher 891but on wallclock time (absolute time). You can tell a periodic watcher
802to trigger &quot;at&quot; some specific point in time. For example, if you tell a 892to trigger &quot;at&quot; some specific point in time. For example, if you tell a
803periodic watcher to trigger in 10 seconds (by specifiying e.g. c&lt;ev_now () 893periodic watcher to trigger in 10 seconds (by specifiying e.g. <code>ev_now ()
804+ 10.&gt;) and then reset your system clock to the last year, then it will 894+ 10.</code>) and then reset your system clock to the last year, then it will
805take a year to trigger the event (unlike an <code>ev_timer</code>, which would trigger 895take a year to trigger the event (unlike an <code>ev_timer</code>, which would trigger
806roughly 10 seconds later and of course not if you reset your system time 896roughly 10 seconds later and of course not if you reset your system time
807again).</p> 897again).</p>
808<p>They can also be used to implement vastly more complex timers, such as 898<p>They can also be used to implement vastly more complex timers, such as
809triggering an event on eahc midnight, local time.</p> 899triggering an event on eahc midnight, local time.</p>
… …
1066 1156
1067</div> 1157</div>
1068<h2 id="code_ev_embed_code_when_one_backend_"><code>ev_embed</code> - when one backend isn't enough</h2> 1158<h2 id="code_ev_embed_code_when_one_backend_"><code>ev_embed</code> - when one backend isn't enough</h2>
1069<div id="code_ev_embed_code_when_one_backend_-2"> 1159<div id="code_ev_embed_code_when_one_backend_-2">
1070<p>This is a rather advanced watcher type that lets you embed one event loop 1160<p>This is a rather advanced watcher type that lets you embed one event loop
1071into another.</p> 1161into another (currently only <code>ev_io</code> events are supported in the embedded
1162loop, other types of watchers might be handled in a delayed or incorrect
1163fashion and must not be used).</p>
1072<p>There are primarily two reasons you would want that: work around bugs and 1164<p>There are primarily two reasons you would want that: work around bugs and
1073prioritise I/O.</p> 1165prioritise I/O.</p>
1074<p>As an example for a bug workaround, the kqueue backend might only support 1166<p>As an example for a bug workaround, the kqueue backend might only support
1075sockets on some platform, so it is unusable as generic backend, but you 1167sockets on some platform, so it is unusable as generic backend, but you
1076still want to make use of it because you have many sockets and it scales 1168still want to make use of it because you have many sockets and it scales
… …
1081<p>As for prioritising I/O: rarely you have the case where some fds have 1173<p>As for prioritising I/O: rarely you have the case where some fds have
1082to be watched and handled very quickly (with low latency), and even 1174to be watched and handled very quickly (with low latency), and even
1083priorities and idle watchers might have too much overhead. In this case 1175priorities and idle watchers might have too much overhead. In this case
1084you would put all the high priority stuff in one loop and all the rest in 1176you would put all the high priority stuff in one loop and all the rest in
1085a second one, and embed the second one in the first.</p> 1177a second one, and embed the second one in the first.</p>
1178<p>As long as the watcher is active, the callback will be invoked every time
1179there might be events pending in the embedded loop. The callback must then
1180call <code>ev_embed_sweep (mainloop, watcher)</code> to make a single sweep and invoke
1181their callbacks (you could also start an idle watcher to give the embedded
1182loop strictly lower priority for example). You can also set the callback
1183to <code>0</code>, in which case the embed watcher will automatically execute the
1184embedded loop sweep.</p>
1086<p>As long as the watcher is started it will automatically handle events. The 1185<p>As long as the watcher is started it will automatically handle events. The
1087callback will be invoked whenever some events have been handled. You can 1186callback will be invoked whenever some events have been handled. You can
1088set the callback to <code>0</code> to avoid having to specify one if you are not 1187set the callback to <code>0</code> to avoid having to specify one if you are not
1089interested in that.</p> 1188interested in that.</p>
1090<p>Also, there have not currently been made special provisions for forking: 1189<p>Also, there have not currently been made special provisions for forking:
… …
1117 else 1216 else
1118 loop_lo = loop_hi; 1217 loop_lo = loop_hi;
1119 1218
1120</pre> 1219</pre>
1121<dl> 1220<dl>
1122 <dt>ev_embed_init (ev_embed *, callback, struct ev_loop *loop)</dt> 1221 <dt>ev_embed_init (ev_embed *, callback, struct ev_loop *embedded_loop)</dt>
1123 <dt>ev_embed_set (ev_embed *, callback, struct ev_loop *loop)</dt> 1222 <dt>ev_embed_set (ev_embed *, callback, struct ev_loop *embedded_loop)</dt>
1223 <dd>
1224 <p>Configures the watcher to embed the given loop, which must be
1225embeddable. If the callback is <code>0</code>, then <code>ev_embed_sweep</code> will be
1226invoked automatically, otherwise it is the responsibility of the callback
1227to invoke it (it will continue to be called until the sweep has been done,
1228if you do not want thta, you need to temporarily stop the embed watcher).</p>
1124 <dd> 1229 </dd>
1125 <p>Configures the watcher to embed the given loop, which must be embeddable.</p> 1230 <dt>ev_embed_sweep (loop, ev_embed *)</dt>
1231 <dd>
1232 <p>Make a single, non-blocking sweep over the embedded loop. This works
1233similarly to <code>ev_loop (embedded_loop, EVLOOP_NONBLOCK)</code>, but in the most
1234apropriate way for embedded loops.</p>
1126 </dd> 1235 </dd>
1127</dl> 1236</dl>
1128 1237
1129 1238
1130 1239
… …
1163 1272
1164 ev_once (STDIN_FILENO, EV_READ, 10., stdin_ready, 0); 1273 ev_once (STDIN_FILENO, EV_READ, 10., stdin_ready, 0);
1165 1274
1166</pre> 1275</pre>
1167 </dd> 1276 </dd>
1168 <dt>ev_feed_event (loop, watcher, int events)</dt> 1277 <dt>ev_feed_event (ev_loop *, watcher *, int revents)</dt>
1169 <dd> 1278 <dd>
1170 <p>Feeds the given event set into the event loop, as if the specified event 1279 <p>Feeds the given event set into the event loop, as if the specified event
1171had happened for the specified watcher (which must be a pointer to an 1280had happened for the specified watcher (which must be a pointer to an
1172initialised but not necessarily started event watcher).</p> 1281initialised but not necessarily started event watcher).</p>
1173 </dd> 1282 </dd>
1174 <dt>ev_feed_fd_event (loop, int fd, int revents)</dt> 1283 <dt>ev_feed_fd_event (ev_loop *, int fd, int revents)</dt>
1175 <dd> 1284 <dd>
1176 <p>Feed an event on the given fd, as if a file descriptor backend detected 1285 <p>Feed an event on the given fd, as if a file descriptor backend detected
1177the given events it.</p> 1286the given events it.</p>
1178 </dd> 1287 </dd>
1179 <dt>ev_feed_signal_event (loop, int signum)</dt> 1288 <dt>ev_feed_signal_event (ev_loop *loop, int signum)</dt>
1180 <dd> 1289 <dd>
1181 <p>Feed an event as if the given signal occured (loop must be the default loop!).</p> 1290 <p>Feed an event as if the given signal occured (<code>loop</code> must be the default
1291loop!).</p>
1182 </dd> 1292 </dd>
1183</dl> 1293</dl>
1184 1294
1185 1295
1186 1296
… …
1207</dl> 1317</dl>
1208 1318
1209</div> 1319</div>
1210<h1 id="C_SUPPORT">C++ SUPPORT</h1><p><a href="#TOP" class="toplink">Top</a></p> 1320<h1 id="C_SUPPORT">C++ SUPPORT</h1><p><a href="#TOP" class="toplink">Top</a></p>
1211<div id="C_SUPPORT_CONTENT"> 1321<div id="C_SUPPORT_CONTENT">
1212<p>TBD.</p> 1322<p>Libev comes with some simplistic wrapper classes for C++ that mainly allow
1323you to use some convinience methods to start/stop watchers and also change
1324the callback model to a model using method callbacks on objects.</p>
1325<p>To use it,</p>
1326<pre> #include &lt;ev++.h&gt;
1327
1328</pre>
1329<p>(it is not installed by default). This automatically includes <cite>ev.h</cite>
1330and puts all of its definitions (many of them macros) into the global
1331namespace. All C++ specific things are put into the <code>ev</code> namespace.</p>
1332<p>It should support all the same embedding options as <cite>ev.h</cite>, most notably
1333<code>EV_MULTIPLICITY</code>.</p>
1334<p>Here is a list of things available in the <code>ev</code> namespace:</p>
1335<dl>
1336 <dt><code>ev::READ</code>, <code>ev::WRITE</code> etc.</dt>
1337 <dd>
1338 <p>These are just enum values with the same values as the <code>EV_READ</code> etc.
1339macros from <cite>ev.h</cite>.</p>
1340 </dd>
1341 <dt><code>ev::tstamp</code>, <code>ev::now</code></dt>
1342 <dd>
1343 <p>Aliases to the same types/functions as with the <code>ev_</code> prefix.</p>
1344 </dd>
1345 <dt><code>ev::io</code>, <code>ev::timer</code>, <code>ev::periodic</code>, <code>ev::idle</code>, <code>ev::sig</code> etc.</dt>
1346 <dd>
1347 <p>For each <code>ev_TYPE</code> watcher in <cite>ev.h</cite> there is a corresponding class of
1348the same name in the <code>ev</code> namespace, with the exception of <code>ev_signal</code>
1349which is called <code>ev::sig</code> to avoid clashes with the <code>signal</code> macro
1350defines by many implementations.</p>
1351 <p>All of those classes have these methods:</p>
1352 <p>
1353 <dl>
1354 <dt>ev::TYPE::TYPE (object *, object::method *)</dt>
1355 <dt>ev::TYPE::TYPE (object *, object::method *, struct ev_loop *)</dt>
1356 <dt>ev::TYPE::~TYPE</dt>
1357 <dd>
1358 <p>The constructor takes a pointer to an object and a method pointer to
1359the event handler callback to call in this class. The constructor calls
1360<code>ev_init</code> for you, which means you have to call the <code>set</code> method
1361before starting it. If you do not specify a loop then the constructor
1362automatically associates the default loop with this watcher.</p>
1363 <p>The destructor automatically stops the watcher if it is active.</p>
1364 </dd>
1365 <dt>w-&gt;set (struct ev_loop *)</dt>
1366 <dd>
1367 <p>Associates a different <code>struct ev_loop</code> with this watcher. You can only
1368do this when the watcher is inactive (and not pending either).</p>
1369 </dd>
1370 <dt>w-&gt;set ([args])</dt>
1371 <dd>
1372 <p>Basically the same as <code>ev_TYPE_set</code>, with the same args. Must be
1373called at least once. Unlike the C counterpart, an active watcher gets
1374automatically stopped and restarted.</p>
1375 </dd>
1376 <dt>w-&gt;start ()</dt>
1377 <dd>
1378 <p>Starts the watcher. Note that there is no <code>loop</code> argument as the
1379constructor already takes the loop.</p>
1380 </dd>
1381 <dt>w-&gt;stop ()</dt>
1382 <dd>
1383 <p>Stops the watcher if it is active. Again, no <code>loop</code> argument.</p>
1384 </dd>
1385 <dt>w-&gt;again () <code>ev::timer</code>, <code>ev::periodic</code> only</dt>
1386 <dd>
1387 <p>For <code>ev::timer</code> and <code>ev::periodic</code>, this invokes the corresponding
1388<code>ev_TYPE_again</code> function.</p>
1389 </dd>
1390 <dt>w-&gt;sweep () <code>ev::embed</code> only</dt>
1391 <dd>
1392 <p>Invokes <code>ev_embed_sweep</code>.</p>
1393 </dd>
1394 </dl>
1395 </p>
1396 </dd>
1397</dl>
1398<p>Example: Define a class with an IO and idle watcher, start one of them in
1399the constructor.</p>
1400<pre> class myclass
1401 {
1402 ev_io io; void io_cb (ev::io &amp;w, int revents);
1403 ev_idle idle void idle_cb (ev::idle &amp;w, int revents);
1404
1405 myclass ();
1406 }
1407
1408 myclass::myclass (int fd)
1409 : io (this, &amp;myclass::io_cb),
1410 idle (this, &amp;myclass::idle_cb)
1411 {
1412 io.start (fd, ev::READ);
1413 }
1414
1415</pre>
1416
1417</div>
1418<h1 id="EMBEDDING">EMBEDDING</h1><p><a href="#TOP" class="toplink">Top</a></p>
1419<div id="EMBEDDING_CONTENT">
1420<p>Libev can (and often is) directly embedded into host
1421applications. Examples of applications that embed it include the Deliantra
1422Game Server, the EV perl module, the GNU Virtual Private Ethernet (gvpe)
1423and rxvt-unicode.</p>
1424<p>The goal is to enable you to just copy the neecssary files into your
1425source directory without having to change even a single line in them, so
1426you can easily upgrade by simply copying (or having a checked-out copy of
1427libev somewhere in your source tree).</p>
1428
1429</div>
1430<h2 id="FILESETS">FILESETS</h2>
1431<div id="FILESETS_CONTENT">
1432<p>Depending on what features you need you need to include one or more sets of files
1433in your app.</p>
1434
1435</div>
1436<h3 id="CORE_EVENT_LOOP">CORE EVENT LOOP</h3>
1437<div id="CORE_EVENT_LOOP_CONTENT">
1438<p>To include only the libev core (all the <code>ev_*</code> functions), with manual
1439configuration (no autoconf):</p>
1440<pre> #define EV_STANDALONE 1
1441 #include &quot;ev.c&quot;
1442
1443</pre>
1444<p>This will automatically include <cite>ev.h</cite>, too, and should be done in a
1445single C source file only to provide the function implementations. To use
1446it, do the same for <cite>ev.h</cite> in all files wishing to use this API (best
1447done by writing a wrapper around <cite>ev.h</cite> that you can include instead and
1448where you can put other configuration options):</p>
1449<pre> #define EV_STANDALONE 1
1450 #include &quot;ev.h&quot;
1451
1452</pre>
1453<p>Both header files and implementation files can be compiled with a C++
1454compiler (at least, thats a stated goal, and breakage will be treated
1455as a bug).</p>
1456<p>You need the following files in your source tree, or in a directory
1457in your include path (e.g. in libev/ when using -Ilibev):</p>
1458<pre> ev.h
1459 ev.c
1460 ev_vars.h
1461 ev_wrap.h
1462
1463 ev_win32.c required on win32 platforms only
1464
1465 ev_select.c only when select backend is enabled (which is is by default)
1466 ev_poll.c only when poll backend is enabled (disabled by default)
1467 ev_epoll.c only when the epoll backend is enabled (disabled by default)
1468 ev_kqueue.c only when the kqueue backend is enabled (disabled by default)
1469 ev_port.c only when the solaris port backend is enabled (disabled by default)
1470
1471</pre>
1472<p><cite>ev.c</cite> includes the backend files directly when enabled, so you only need
1473to compile a single file.</p>
1474
1475</div>
1476<h3 id="LIBEVENT_COMPATIBILITY_API">LIBEVENT COMPATIBILITY API</h3>
1477<div id="LIBEVENT_COMPATIBILITY_API_CONTENT">
1478<p>To include the libevent compatibility API, also include:</p>
1479<pre> #include &quot;event.c&quot;
1480
1481</pre>
1482<p>in the file including <cite>ev.c</cite>, and:</p>
1483<pre> #include &quot;event.h&quot;
1484
1485</pre>
1486<p>in the files that want to use the libevent API. This also includes <cite>ev.h</cite>.</p>
1487<p>You need the following additional files for this:</p>
1488<pre> event.h
1489 event.c
1490
1491</pre>
1492
1493</div>
1494<h3 id="AUTOCONF_SUPPORT">AUTOCONF SUPPORT</h3>
1495<div id="AUTOCONF_SUPPORT_CONTENT">
1496<p>Instead of using <code>EV_STANDALONE=1</code> and providing your config in
1497whatever way you want, you can also <code>m4_include([libev.m4])</code> in your
1498<cite>configure.ac</cite> and leave <code>EV_STANDALONE</code> off. <cite>ev.c</cite> will then include
1499<cite>config.h</cite> and configure itself accordingly.</p>
1500<p>For this of course you need the m4 file:</p>
1501<pre> libev.m4
1502
1503</pre>
1504
1505</div>
1506<h2 id="PREPROCESSOR_SYMBOLS_MACROS">PREPROCESSOR SYMBOLS/MACROS</h2>
1507<div id="PREPROCESSOR_SYMBOLS_MACROS_CONTENT">
1508<p>Libev can be configured via a variety of preprocessor symbols you have to define
1509before including any of its files. The default is not to build for multiplicity
1510and only include the select backend.</p>
1511<dl>
1512 <dt>EV_STANDALONE</dt>
1513 <dd>
1514 <p>Must always be <code>1</code> if you do not use autoconf configuration, which
1515keeps libev from including <cite>config.h</cite>, and it also defines dummy
1516implementations for some libevent functions (such as logging, which is not
1517supported). It will also not define any of the structs usually found in
1518<cite>event.h</cite> that are not directly supported by the libev core alone.</p>
1519 </dd>
1520 <dt>EV_USE_MONOTONIC</dt>
1521 <dd>
1522 <p>If defined to be <code>1</code>, libev will try to detect the availability of the
1523monotonic clock option at both compiletime and runtime. Otherwise no use
1524of the monotonic clock option will be attempted. If you enable this, you
1525usually have to link against librt or something similar. Enabling it when
1526the functionality isn't available is safe, though, althoguh you have
1527to make sure you link against any libraries where the <code>clock_gettime</code>
1528function is hiding in (often <cite>-lrt</cite>).</p>
1529 </dd>
1530 <dt>EV_USE_REALTIME</dt>
1531 <dd>
1532 <p>If defined to be <code>1</code>, libev will try to detect the availability of the
1533realtime clock option at compiletime (and assume its availability at
1534runtime if successful). Otherwise no use of the realtime clock option will
1535be attempted. This effectively replaces <code>gettimeofday</code> by <code>clock_get
1536(CLOCK_REALTIME, ...)</code> and will not normally affect correctness. See tzhe note about libraries
1537in the description of <code>EV_USE_MONOTONIC</code>, though.</p>
1538 </dd>
1539 <dt>EV_USE_SELECT</dt>
1540 <dd>
1541 <p>If undefined or defined to be <code>1</code>, libev will compile in support for the
1542<code>select</code>(2) backend. No attempt at autodetection will be done: if no
1543other method takes over, select will be it. Otherwise the select backend
1544will not be compiled in.</p>
1545 </dd>
1546 <dt>EV_SELECT_USE_FD_SET</dt>
1547 <dd>
1548 <p>If defined to <code>1</code>, then the select backend will use the system <code>fd_set</code>
1549structure. This is useful if libev doesn't compile due to a missing
1550<code>NFDBITS</code> or <code>fd_mask</code> definition or it misguesses the bitset layout on
1551exotic systems. This usually limits the range of file descriptors to some
1552low limit such as 1024 or might have other limitations (winsocket only
1553allows 64 sockets). The <code>FD_SETSIZE</code> macro, set before compilation, might
1554influence the size of the <code>fd_set</code> used.</p>
1555 </dd>
1556 <dt>EV_SELECT_IS_WINSOCKET</dt>
1557 <dd>
1558 <p>When defined to <code>1</code>, the select backend will assume that
1559select/socket/connect etc. don't understand file descriptors but
1560wants osf handles on win32 (this is the case when the select to
1561be used is the winsock select). This means that it will call
1562<code>_get_osfhandle</code> on the fd to convert it to an OS handle. Otherwise,
1563it is assumed that all these functions actually work on fds, even
1564on win32. Should not be defined on non-win32 platforms.</p>
1565 </dd>
1566 <dt>EV_USE_POLL</dt>
1567 <dd>
1568 <p>If defined to be <code>1</code>, libev will compile in support for the <code>poll</code>(2)
1569backend. Otherwise it will be enabled on non-win32 platforms. It
1570takes precedence over select.</p>
1571 </dd>
1572 <dt>EV_USE_EPOLL</dt>
1573 <dd>
1574 <p>If defined to be <code>1</code>, libev will compile in support for the Linux
1575<code>epoll</code>(7) backend. Its availability will be detected at runtime,
1576otherwise another method will be used as fallback. This is the
1577preferred backend for GNU/Linux systems.</p>
1578 </dd>
1579 <dt>EV_USE_KQUEUE</dt>
1580 <dd>
1581 <p>If defined to be <code>1</code>, libev will compile in support for the BSD style
1582<code>kqueue</code>(2) backend. Its actual availability will be detected at runtime,
1583otherwise another method will be used as fallback. This is the preferred
1584backend for BSD and BSD-like systems, although on most BSDs kqueue only
1585supports some types of fds correctly (the only platform we found that
1586supports ptys for example was NetBSD), so kqueue might be compiled in, but
1587not be used unless explicitly requested. The best way to use it is to find
1588out wether kqueue supports your type of fd properly and use an embedded
1589kqueue loop.</p>
1590 </dd>
1591 <dt>EV_USE_PORT</dt>
1592 <dd>
1593 <p>If defined to be <code>1</code>, libev will compile in support for the Solaris
159410 port style backend. Its availability will be detected at runtime,
1595otherwise another method will be used as fallback. This is the preferred
1596backend for Solaris 10 systems.</p>
1597 </dd>
1598 <dt>EV_USE_DEVPOLL</dt>
1599 <dd>
1600 <p>reserved for future expansion, works like the USE symbols above.</p>
1601 </dd>
1602 <dt>EV_H</dt>
1603 <dd>
1604 <p>The name of the <cite>ev.h</cite> header file used to include it. The default if
1605undefined is <code>&lt;ev.h&gt;</code> in <cite>event.h</cite> and <code>&quot;ev.h&quot;</code> in <cite>ev.c</cite>. This
1606can be used to virtually rename the <cite>ev.h</cite> header file in case of conflicts.</p>
1607 </dd>
1608 <dt>EV_CONFIG_H</dt>
1609 <dd>
1610 <p>If <code>EV_STANDALONE</code> isn't <code>1</code>, this variable can be used to override
1611<cite>ev.c</cite>'s idea of where to find the <cite>config.h</cite> file, similarly to
1612<code>EV_H</code>, above.</p>
1613 </dd>
1614 <dt>EV_EVENT_H</dt>
1615 <dd>
1616 <p>Similarly to <code>EV_H</code>, this macro can be used to override <cite>event.c</cite>'s idea
1617of how the <cite>event.h</cite> header can be found.</p>
1618 </dd>
1619 <dt>EV_PROTOTYPES</dt>
1620 <dd>
1621 <p>If defined to be <code>0</code>, then <cite>ev.h</cite> will not define any function
1622prototypes, but still define all the structs and other symbols. This is
1623occasionally useful if you want to provide your own wrapper functions
1624around libev functions.</p>
1625 </dd>
1626 <dt>EV_MULTIPLICITY</dt>
1627 <dd>
1628 <p>If undefined or defined to <code>1</code>, then all event-loop-specific functions
1629will have the <code>struct ev_loop *</code> as first argument, and you can create
1630additional independent event loops. Otherwise there will be no support
1631for multiple event loops and there is no first event loop pointer
1632argument. Instead, all functions act on the single default loop.</p>
1633 </dd>
1634 <dt>EV_PERIODICS</dt>
1635 <dd>
1636 <p>If undefined or defined to be <code>1</code>, then periodic timers are supported,
1637otherwise not. This saves a few kb of code.</p>
1638 </dd>
1639 <dt>EV_COMMON</dt>
1640 <dd>
1641 <p>By default, all watchers have a <code>void *data</code> member. By redefining
1642this macro to a something else you can include more and other types of
1643members. You have to define it each time you include one of the files,
1644though, and it must be identical each time.</p>
1645 <p>For example, the perl EV module uses something like this:</p>
1646<pre> #define EV_COMMON \
1647 SV *self; /* contains this struct */ \
1648 SV *cb_sv, *fh /* note no trailing &quot;;&quot; */
1649
1650</pre>
1651 </dd>
1652 <dt>EV_CB_DECLARE(type)</dt>
1653 <dt>EV_CB_INVOKE(watcher,revents)</dt>
1654 <dt>ev_set_cb(ev,cb)</dt>
1655 <dd>
1656 <p>Can be used to change the callback member declaration in each watcher,
1657and the way callbacks are invoked and set. Must expand to a struct member
1658definition and a statement, respectively. See the <cite>ev.v</cite> header file for
1659their default definitions. One possible use for overriding these is to
1660avoid the ev_loop pointer as first argument in all cases, or to use method
1661calls instead of plain function calls in C++.</p>
1662
1663</div>
1664<h2 id="EXAMPLES">EXAMPLES</h2>
1665<div id="EXAMPLES_CONTENT">
1666 <p>For a real-world example of a program the includes libev
1667verbatim, you can have a look at the EV perl module
1668(<a href="http://software.schmorp.de/pkg/EV.html">http://software.schmorp.de/pkg/EV.html</a>). It has the libev files in
1669the <cite>libev/</cite> subdirectory and includes them in the <cite>EV/EVAPI.h</cite> (public
1670interface) and <cite>EV.xs</cite> (implementation) files. Only the <cite>EV.xs</cite> file
1671will be compiled. It is pretty complex because it provides its own header
1672file.</p>
1673 <p>The usage in rxvt-unicode is simpler. It has a <cite>ev_cpp.h</cite> header file
1674that everybody includes and which overrides some autoconf choices:</p>
1675<pre> #define EV_USE_POLL 0
1676 #define EV_MULTIPLICITY 0
1677 #define EV_PERIODICS 0
1678 #define EV_CONFIG_H &lt;config.h&gt;
1679
1680 #include &quot;ev++.h&quot;
1681
1682</pre>
1683 <p>And a <cite>ev_cpp.C</cite> implementation file that contains libev proper and is compiled:</p>
1684<pre> #include &quot;ev_cpp.h&quot;
1685 #include &quot;ev.c&quot;
1686
1687</pre>
1213 1688
1214</div> 1689</div>
1215<h1 id="AUTHOR">AUTHOR</h1><p><a href="#TOP" class="toplink">Top</a></p> 1690<h1 id="AUTHOR">AUTHOR</h1><p><a href="#TOP" class="toplink">Top</a></p>
1216<div id="AUTHOR_CONTENT"> 1691<div id="AUTHOR_CONTENT">
1217<p>Marc Lehmann &lt;libev@schmorp.de&gt;.</p> 1692 <p>Marc Lehmann &lt;libev@schmorp.de&gt;.</p>
1218 1693
1219</div> 1694</div>
1220</div></body> 1695</div></body>
1221</html> 1696</html>

Diff Legend

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