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

Comparing libev/ev.html (file contents):
Revision 1.75 by root, Sun Dec 9 19:46:56 2007 UTC vs.
Revision 1.77 by root, Wed Dec 12 04:53:58 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="Sun Dec 9 20:45:16 2007" /> 9 <meta name="created" content="Wed Dec 12 05:53:55 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 -->
… …
27<ul><li><a href="#GENERIC_WATCHER_FUNCTIONS">GENERIC WATCHER FUNCTIONS</a></li> 27<ul><li><a href="#GENERIC_WATCHER_FUNCTIONS">GENERIC WATCHER FUNCTIONS</a></li>
28<li><a href="#ASSOCIATING_CUSTOM_DATA_WITH_A_WATCH">ASSOCIATING CUSTOM DATA WITH A WATCHER</a></li> 28<li><a href="#ASSOCIATING_CUSTOM_DATA_WITH_A_WATCH">ASSOCIATING CUSTOM DATA WITH A WATCHER</a></li>
29</ul> 29</ul>
30</li> 30</li>
31<li><a href="#WATCHER_TYPES">WATCHER TYPES</a> 31<li><a href="#WATCHER_TYPES">WATCHER TYPES</a>
32<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> 32<ul><li><a href="#code_ev_io_code_is_this_file_descrip"><code>ev_io</code> - is this file descriptor readable or writable?</a>
33<ul><li><a href="#The_special_problem_of_disappearing_">The special problem of disappearing file descriptors</a></li>
34</ul>
35</li>
33<li><a href="#code_ev_timer_code_relative_and_opti"><code>ev_timer</code> - relative and optionally repeating timeouts</a></li> 36<li><a href="#code_ev_timer_code_relative_and_opti"><code>ev_timer</code> - relative and optionally repeating timeouts</a></li>
34<li><a href="#code_ev_periodic_code_to_cron_or_not"><code>ev_periodic</code> - to cron or not to cron?</a></li> 37<li><a href="#code_ev_periodic_code_to_cron_or_not"><code>ev_periodic</code> - to cron or not to cron?</a></li>
35<li><a href="#code_ev_signal_code_signal_me_when_a"><code>ev_signal</code> - signal me when a signal gets signalled!</a></li> 38<li><a href="#code_ev_signal_code_signal_me_when_a"><code>ev_signal</code> - signal me when a signal gets signalled!</a></li>
36<li><a href="#code_ev_child_code_watch_out_for_pro"><code>ev_child</code> - watch out for process status changes</a></li> 39<li><a href="#code_ev_child_code_watch_out_for_pro"><code>ev_child</code> - watch out for process status changes</a></li>
37<li><a href="#code_ev_stat_code_did_the_file_attri"><code>ev_stat</code> - did the file attributes just change?</a></li> 40<li><a href="#code_ev_stat_code_did_the_file_attri"><code>ev_stat</code> - did the file attributes just change?</a></li>
… …
185you actually want to know.</p> 188you actually want to know.</p>
186 </dd> 189 </dd>
187 <dt>int ev_version_major ()</dt> 190 <dt>int ev_version_major ()</dt>
188 <dt>int ev_version_minor ()</dt> 191 <dt>int ev_version_minor ()</dt>
189 <dd> 192 <dd>
190 <p>You can find out the major and minor API/ABI version numbers of the library 193 <p>You can find out the major and minor ABI version numbers of the library
191you linked against by calling the functions <code>ev_version_major</code> and 194you linked against by calling the functions <code>ev_version_major</code> and
192<code>ev_version_minor</code>. If you want, you can compare against the global 195<code>ev_version_minor</code>. If you want, you can compare against the global
193symbols <code>EV_VERSION_MAJOR</code> and <code>EV_VERSION_MINOR</code>, which specify the 196symbols <code>EV_VERSION_MAJOR</code> and <code>EV_VERSION_MINOR</code>, which specify the
194version of the library your program was compiled against.</p> 197version of the library your program was compiled against.</p>
195 <p>These version numbers refer to the API and ABI version of the library, not 198 <p>These version numbers refer to the ABI version of the library, not the
196the release version.</p> 199release version.</p>
197 <p>Usually, it's a good idea to terminate if the major versions mismatch, 200 <p>Usually, it's a good idea to terminate if the major versions mismatch,
198as this indicates an incompatible change. Minor versions are usually 201as this indicates an incompatible change. Minor versions are usually
199compatible to older versions, so a larger minor version alone is usually 202compatible to older versions, so a larger minor version alone is usually
200not a problem.</p> 203not a problem.</p>
201 <p>Example: Make sure we haven't accidentally been linked against the wrong 204 <p>Example: Make sure we haven't accidentally been linked against the wrong
… …
941<p>If you cannot run the fd in non-blocking mode (for example you should not 944<p>If you cannot run the fd in non-blocking mode (for example you should not
942play around with an Xlib connection), then you have to seperately re-test 945play around with an Xlib connection), then you have to seperately re-test
943whether a file descriptor is really ready with a known-to-be good interface 946whether a file descriptor is really ready with a known-to-be good interface
944such as poll (fortunately in our Xlib example, Xlib already does this on 947such as poll (fortunately in our Xlib example, Xlib already does this on
945its own, so its quite safe to use).</p> 948its own, so its quite safe to use).</p>
949
950</div>
951<h3 id="The_special_problem_of_disappearing_">The special problem of disappearing file descriptors</h3>
952<div id="The_special_problem_of_disappearing_-2">
953<p>Some backends (e.g kqueue, epoll) need to be told about closing a file
954descriptor (either by calling <code>close</code> explicitly or by any other means,
955such as <code>dup</code>). The reason is that you register interest in some file
956descriptor, but when it goes away, the operating system will silently drop
957this interest. If another file descriptor with the same number then is
958registered with libev, there is no efficient way to see that this is, in
959fact, a different file descriptor.</p>
960<p>To avoid having to explicitly tell libev about such cases, libev follows
961the following policy: Each time <code>ev_io_set</code> is being called, libev
962will assume that this is potentially a new file descriptor, otherwise
963it is assumed that the file descriptor stays the same. That means that
964you <i>have</i> to call <code>ev_io_set</code> (or <code>ev_io_init</code>) when you change the
965descriptor even if the file descriptor number itself did not change.</p>
966<p>This is how one would do it normally anyway, the important point is that
967the libev application should not optimise around libev but should leave
968optimisations to libev.</p>
969
970
971
972
946<dl> 973<dl>
947 <dt>ev_io_init (ev_io *, callback, int fd, int events)</dt> 974 <dt>ev_io_init (ev_io *, callback, int fd, int events)</dt>
948 <dt>ev_io_set (ev_io *, int fd, int events)</dt> 975 <dt>ev_io_set (ev_io *, int fd, int events)</dt>
949 <dd> 976 <dd>
950 <p>Configures an <code>ev_io</code> watcher. The <code>fd</code> is the file descriptor to 977 <p>Configures an <code>ev_io</code> watcher. The <code>fd</code> is the file descriptor to

Diff Legend

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