]> git.llucax.com Git - software/libev.git/blobdiff - ev.html
projects / software / libev.git / blobdiff
? search:
summary | shortlog | log | commit | commitdiff | tree
raw | inline | side by side
*** empty log message ***
[software/libev.git] / ev.html
diff --git a/ev.html b/ev.html
index da28682760387a0c3787624ee05698fedf9a36b8..21f24d525a4c478deb6054dce3812f493be4975b 100644 (file)
--- a/ev.html
+++ b/ev.html
@@ -6,7 +6,7 @@
        <meta name="description" content="Pod documentation for libev" />
        <meta name="inputfile" content="&lt;standard input&gt;" />
        <meta name="outputfile" content="&lt;standard output&gt;" />
        <meta name="description" content="Pod documentation for libev" />
        <meta name="inputfile" content="&lt;standard input&gt;" />
        <meta name="outputfile" content="&lt;standard output&gt;" />
-       <meta name="created" content="Sat Dec  8 23:11:11 2007" />
+       <meta name="created" content="Wed Dec 12 05:53:55 2007" />
        <meta name="generator" content="Pod::Xhtml 1.57" />
 <link rel="stylesheet" href="http://res.tst.eu/pod.css"/></head>
 <body>
        <meta name="generator" content="Pod::Xhtml 1.57" />
 <link rel="stylesheet" href="http://res.tst.eu/pod.css"/></head>
 <body>
@@ -29,7 +29,10 @@
 </ul>
 </li>
 <li><a href="#WATCHER_TYPES">WATCHER TYPES</a>
 </ul>
 </li>
 <li><a href="#WATCHER_TYPES">WATCHER TYPES</a>
-<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>
+<ul><li><a href="#code_ev_io_code_is_this_file_descrip"><code>ev_io</code> - is this file descriptor readable or writable?</a>
+<ul><li><a href="#The_special_problem_of_disappearing_">The special problem of disappearing file descriptors</a></li>
+</ul>
+</li>
 <li><a href="#code_ev_timer_code_relative_and_opti"><code>ev_timer</code> - relative and optionally repeating timeouts</a></li>
 <li><a href="#code_ev_periodic_code_to_cron_or_not"><code>ev_periodic</code> - to cron or not to cron?</a></li>
 <li><a href="#code_ev_signal_code_signal_me_when_a"><code>ev_signal</code> - signal me when a signal gets signalled!</a></li>
 <li><a href="#code_ev_timer_code_relative_and_opti"><code>ev_timer</code> - relative and optionally repeating timeouts</a></li>
 <li><a href="#code_ev_periodic_code_to_cron_or_not"><code>ev_periodic</code> - to cron or not to cron?</a></li>
 <li><a href="#code_ev_signal_code_signal_me_when_a"><code>ev_signal</code> - signal me when a signal gets signalled!</a></li>
@@ -187,13 +190,15 @@ you actually want to know.</p>
        <dt>int ev_version_major ()</dt>
        <dt>int ev_version_minor ()</dt>
        <dd>
        <dt>int ev_version_major ()</dt>
        <dt>int ev_version_minor ()</dt>
        <dd>
-               <p>You can find out the major and minor version numbers of the library
+               <p>You can find out the major and minor ABI version numbers of the library
 you linked against by calling the functions <code>ev_version_major</code> and
 <code>ev_version_minor</code>. If you want, you can compare against the global
 symbols <code>EV_VERSION_MAJOR</code> and <code>EV_VERSION_MINOR</code>, which specify the
 version of the library your program was compiled against.</p>
 you linked against by calling the functions <code>ev_version_major</code> and
 <code>ev_version_minor</code>. If you want, you can compare against the global
 symbols <code>EV_VERSION_MAJOR</code> and <code>EV_VERSION_MINOR</code>, which specify the
 version of the library your program was compiled against.</p>
+               <p>These version numbers refer to the ABI version of the library, not the
+release version.</p>
                <p>Usually, it's a good idea to terminate if the major versions mismatch,
                <p>Usually, it's a good idea to terminate if the major versions mismatch,
-as this indicates an incompatible change.  Minor versions are usually
+as this indicates an incompatible change. Minor versions are usually
 compatible to older versions, so a larger minor version alone is usually
 not a problem.</p>
                <p>Example: Make sure we haven't accidentally been linked against the wrong
 compatible to older versions, so a larger minor version alone is usually
 not a problem.</p>
                <p>Example: Make sure we haven't accidentally been linked against the wrong
@@ -941,6 +946,30 @@ play around with an Xlib connection), then you have to seperately re-test
 whether a file descriptor is really ready with a known-to-be good interface
 such as poll (fortunately in our Xlib example, Xlib already does this on
 its own, so its quite safe to use).</p>
 whether a file descriptor is really ready with a known-to-be good interface
 such as poll (fortunately in our Xlib example, Xlib already does this on
 its own, so its quite safe to use).</p>
+
+</div>
+<h3 id="The_special_problem_of_disappearing_">The special problem of disappearing file descriptors</h3>
+<div id="The_special_problem_of_disappearing_-2">
+<p>Some backends (e.g kqueue, epoll) need to be told about closing a file
+descriptor (either by calling <code>close</code> explicitly or by any other means,
+such as <code>dup</code>). The reason is that you register interest in some file
+descriptor, but when it goes away, the operating system will silently drop
+this interest. If another file descriptor with the same number then is
+registered with libev, there is no efficient way to see that this is, in
+fact, a different file descriptor.</p>
+<p>To avoid having to explicitly tell libev about such cases, libev follows
+the following policy:  Each time <code>ev_io_set</code> is being called, libev
+will assume that this is potentially a new file descriptor, otherwise
+it is assumed that the file descriptor stays the same. That means that
+you <i>have</i> to call <code>ev_io_set</code> (or <code>ev_io_init</code>) when you change the
+descriptor even if the file descriptor number itself did not change.</p>
+<p>This is how one would do it normally anyway, the important point is that
+the libev application should not optimise around libev but should leave
+optimisations to libev.</p>
+
+
+
+
 <dl>
        <dt>ev_io_init (ev_io *, callback, int fd, int events)</dt>
        <dt>ev_io_set (ev_io *, int fd, int events)</dt>
 <dl>
        <dt>ev_io_init (ev_io *, callback, int fd, int events)</dt>
        <dt>ev_io_set (ev_io *, int fd, int events)</dt>
@@ -1099,10 +1128,10 @@ to trigger &quot;at&quot; some specific point in time. For example, if you tell
 periodic watcher to trigger in 10 seconds (by specifiying e.g. <code>ev_now ()
 + 10.</code>) and then reset your system clock to the last year, then it will
 take a year to trigger the event (unlike an <code>ev_timer</code>, which would trigger
 periodic watcher to trigger in 10 seconds (by specifiying e.g. <code>ev_now ()
 + 10.</code>) and then reset your system clock to the last year, then it will
 take a year to trigger the event (unlike an <code>ev_timer</code>, which would trigger
-roughly 10 seconds later and of course not if you reset your system time
-again).</p>
+roughly 10 seconds later).</p>
 <p>They can also be used to implement vastly more complex timers, such as
 <p>They can also be used to implement vastly more complex timers, such as
-triggering an event on eahc midnight, local time.</p>
+triggering an event on each midnight, local time or other, complicated,
+rules.</p>
 <p>As with timers, the callback is guarenteed to be invoked only when the
 time (<code>at</code>) has been passed, but if multiple periodic timers become ready
 during the same loop iteration then order of execution is undefined.</p>
 <p>As with timers, the callback is guarenteed to be invoked only when the
 time (<code>at</code>) has been passed, but if multiple periodic timers become ready
 during the same loop iteration then order of execution is undefined.</p>
@@ -1114,18 +1143,18 @@ during the same loop iteration then order of execution is undefined.</p>
 operation, and we will explain them from simplest to complex:</p>
                <p>
                        <dl>
 operation, and we will explain them from simplest to complex:</p>
                <p>
                        <dl>
-                               <dt>* absolute timer (interval = reschedule_cb = 0)</dt>
+                               <dt>* absolute timer (at = time, interval = reschedule_cb = 0)</dt>
                                <dd>
                                        <p>In this configuration the watcher triggers an event at the wallclock time
 <code>at</code> and doesn't repeat. It will not adjust when a time jump occurs,
 that is, if it is to be run at January 1st 2011 then it will run when the
 system time reaches or surpasses this time.</p>
                                </dd>
                                <dd>
                                        <p>In this configuration the watcher triggers an event at the wallclock time
 <code>at</code> and doesn't repeat. It will not adjust when a time jump occurs,
 that is, if it is to be run at January 1st 2011 then it will run when the
 system time reaches or surpasses this time.</p>
                                </dd>
-                               <dt>* non-repeating interval timer (interval &gt; 0, reschedule_cb = 0)</dt>
+                               <dt>* non-repeating interval timer (at = offset, interval &gt; 0, reschedule_cb = 0)</dt>
                                <dd>
                                        <p>In this mode the watcher will always be scheduled to time out at the next
                                <dd>
                                        <p>In this mode the watcher will always be scheduled to time out at the next
-<code>at + N * interval</code> time (for some integer N) and then repeat, regardless
-of any time jumps.</p>
+<code>at + N * interval</code> time (for some integer N, which can also be negative)
+and then repeat, regardless of any time jumps.</p>
                                        <p>This can be used to create timers that do not drift with respect to system
 time:</p>
 <pre>   ev_periodic_set (&amp;periodic, 0., 3600., 0);
                                        <p>This can be used to create timers that do not drift with respect to system
 time:</p>
 <pre>   ev_periodic_set (&amp;periodic, 0., 3600., 0);
@@ -1138,8 +1167,11 @@ by 3600.</p>
                                        <p>Another way to think about it (for the mathematically inclined) is that
 <code>ev_periodic</code> will try to run the callback in this mode at the next possible
 time where <code>time = at (mod interval)</code>, regardless of any time jumps.</p>
                                        <p>Another way to think about it (for the mathematically inclined) is that
 <code>ev_periodic</code> will try to run the callback in this mode at the next possible
 time where <code>time = at (mod interval)</code>, regardless of any time jumps.</p>
+                                       <p>For numerical stability it is preferable that the <code>at</code> value is near
+<code>ev_now ()</code> (the current time), but there is no range requirement for
+this value.</p>
                                </dd>
                                </dd>
-                               <dt>* manual reschedule mode (reschedule_cb = callback)</dt>
+                               <dt>* manual reschedule mode (at and interval ignored, reschedule_cb = callback)</dt>
                                <dd>
                                        <p>In this mode the values for <code>interval</code> and <code>at</code> are both being
 ignored. Instead, each time the periodic watcher gets scheduled, the
                                <dd>
                                        <p>In this mode the values for <code>interval</code> and <code>at</code> are both being
 ignored. Instead, each time the periodic watcher gets scheduled, the
@@ -1148,7 +1180,7 @@ current time as second argument.</p>
                                        <p>NOTE: <i>This callback MUST NOT stop or destroy any periodic watcher,
 ever, or make any event loop modifications</i>. If you need to stop it,
 return <code>now + 1e30</code> (or so, fudge fudge) and stop it afterwards (e.g. by
                                        <p>NOTE: <i>This callback MUST NOT stop or destroy any periodic watcher,
 ever, or make any event loop modifications</i>. If you need to stop it,
 return <code>now + 1e30</code> (or so, fudge fudge) and stop it afterwards (e.g. by
-starting a prepare watcher).</p>
+starting an <code>ev_prepare</code> watcher, which is legal).</p>
                                        <p>Its prototype is <code>ev_tstamp (*reschedule_cb)(struct ev_periodic *w,
 ev_tstamp now)</code>, e.g.:</p>
 <pre>   static ev_tstamp my_rescheduler (struct ev_periodic *w, ev_tstamp now)
                                        <p>Its prototype is <code>ev_tstamp (*reschedule_cb)(struct ev_periodic *w,
 ev_tstamp now)</code>, e.g.:</p>
 <pre>   static ev_tstamp my_rescheduler (struct ev_periodic *w, ev_tstamp now)
@@ -1178,6 +1210,13 @@ reason I omitted it as an example).</p>
 when you changed some parameters or the reschedule callback would return
 a different time than the last time it was called (e.g. in a crond like
 program when the crontabs have changed).</p>
 when you changed some parameters or the reschedule callback would return
 a different time than the last time it was called (e.g. in a crond like
 program when the crontabs have changed).</p>
+       </dd>
+       <dt>ev_tstamp offset [read-write]</dt>
+       <dd>
+               <p>When repeating, this contains the offset value, otherwise this is the
+absolute point in time (the <code>at</code> value passed to <code>ev_periodic_set</code>).</p>
+               <p>Can be modified any time, but changes only take effect when the periodic
+timer fires or <code>ev_periodic_again</code> is being called.</p>
        </dd>
        <dt>ev_tstamp interval [read-write]</dt>
        <dd>
        </dd>
        <dt>ev_tstamp interval [read-write]</dt>
        <dd>
High-performance event loop/event model with lots of features.