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

Comparing libev/ev.html (file contents):
Revision 1.49 by root, Tue Nov 27 08:20:42 2007 UTC vs.
Revision 1.53 by root, Tue Nov 27 20:15:02 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="Tue Nov 27 09:20:40 2007" /> 9 <meta name="created" content="Tue Nov 27 21:14:27 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 -->
… …
35<li><a href="#code_ev_child_code_watch_out_for_pro"><code>ev_child</code> - watch out for process status changes</a></li> 35<li><a href="#code_ev_child_code_watch_out_for_pro"><code>ev_child</code> - watch out for process status changes</a></li>
36<li><a href="#code_ev_stat_code_did_the_file_attri"><code>ev_stat</code> - did the file attributes just change?</a></li> 36<li><a href="#code_ev_stat_code_did_the_file_attri"><code>ev_stat</code> - did the file attributes just change?</a></li>
37<li><a href="#code_ev_idle_code_when_you_ve_got_no"><code>ev_idle</code> - when you've got nothing better to do...</a></li> 37<li><a href="#code_ev_idle_code_when_you_ve_got_no"><code>ev_idle</code> - when you've got nothing better to do...</a></li>
38<li><a href="#code_ev_prepare_code_and_code_ev_che"><code>ev_prepare</code> and <code>ev_check</code> - customise your event loop!</a></li> 38<li><a href="#code_ev_prepare_code_and_code_ev_che"><code>ev_prepare</code> and <code>ev_check</code> - customise your event loop!</a></li>
39<li><a href="#code_ev_embed_code_when_one_backend_"><code>ev_embed</code> - when one backend isn't enough...</a></li> 39<li><a href="#code_ev_embed_code_when_one_backend_"><code>ev_embed</code> - when one backend isn't enough...</a></li>
40<li><a href="#code_ev_fork_code_the_audacity_to_re"><code>ev_fork</code> - the audacity to resume the event loop after a fork</a></li>
40</ul> 41</ul>
41</li> 42</li>
42<li><a href="#OTHER_FUNCTIONS">OTHER FUNCTIONS</a></li> 43<li><a href="#OTHER_FUNCTIONS">OTHER FUNCTIONS</a></li>
43<li><a href="#LIBEVENT_EMULATION">LIBEVENT EMULATION</a></li> 44<li><a href="#LIBEVENT_EMULATION">LIBEVENT EMULATION</a></li>
44<li><a href="#C_SUPPORT">C++ SUPPORT</a></li> 45<li><a href="#C_SUPPORT">C++ SUPPORT</a></li>
46<li><a href="#MACRO_MAGIC">MACRO MAGIC</a></li>
45<li><a href="#EMBEDDING">EMBEDDING</a> 47<li><a href="#EMBEDDING">EMBEDDING</a>
46<ul><li><a href="#FILESETS">FILESETS</a> 48<ul><li><a href="#FILESETS">FILESETS</a>
47<ul><li><a href="#CORE_EVENT_LOOP">CORE EVENT LOOP</a></li> 49<ul><li><a href="#CORE_EVENT_LOOP">CORE EVENT LOOP</a></li>
48<li><a href="#LIBEVENT_COMPATIBILITY_API">LIBEVENT COMPATIBILITY API</a></li> 50<li><a href="#LIBEVENT_COMPATIBILITY_API">LIBEVENT COMPATIBILITY API</a></li>
49<li><a href="#AUTOCONF_SUPPORT">AUTOCONF SUPPORT</a></li> 51<li><a href="#AUTOCONF_SUPPORT">AUTOCONF SUPPORT</a></li>
… …
64<p>libev - a high performance full-featured event loop written in C</p> 66<p>libev - a high performance full-featured event loop written in C</p>
65 67
66</div> 68</div>
67<h1 id="SYNOPSIS">SYNOPSIS</h1><p><a href="#TOP" class="toplink">Top</a></p> 69<h1 id="SYNOPSIS">SYNOPSIS</h1><p><a href="#TOP" class="toplink">Top</a></p>
68<div id="SYNOPSIS_CONTENT"> 70<div id="SYNOPSIS_CONTENT">
71<pre> /* this is the only header you need */
69<pre> #include &lt;ev.h&gt; 72 #include &lt;ev.h&gt;
73
74 /* what follows is a fully working example program */
75 ev_io stdin_watcher;
76 ev_timer timeout_watcher;
77
78 /* called when data readable on stdin */
79 static void
80 stdin_cb (EV_P_ struct ev_io *w, int revents)
81 {
82 /* puts (&quot;stdin ready&quot;); */
83 ev_io_stop (EV_A_ w); /* just a syntax example */
84 ev_unloop (EV_A_ EVUNLOOP_ALL); /* leave all loop calls */
85 }
86
87 static void
88 timeout_cb (EV_P_ struct ev_timer *w, int revents)
89 {
90 /* puts (&quot;timeout&quot;); */
91 ev_unloop (EV_A_ EVUNLOOP_ONE); /* leave one loop call */
92 }
93
94 int
95 main (void)
96 {
97 struct ev_loop *loop = ev_default_loop (0);
98
99 /* initialise an io watcher, then start it */
100 ev_io_init (&amp;stdin_watcher, stdin_cb, /*STDIN_FILENO*/ 0, EV_READ);
101 ev_io_start (loop, &amp;stdin_watcher);
102
103 /* simple non-repeating 5.5 second timeout */
104 ev_timer_init (&amp;timeout_watcher, timeout_cb, 5.5, 0.);
105 ev_timer_start (loop, &amp;timeout_watcher);
106
107 /* loop till timeout or data ready */
108 ev_loop (loop, 0);
109
110 return 0;
111 }
70 112
71</pre> 113</pre>
72 114
73</div> 115</div>
74<h1 id="DESCRIPTION">DESCRIPTION</h1><p><a href="#TOP" class="toplink">Top</a></p> 116<h1 id="DESCRIPTION">DESCRIPTION</h1><p><a href="#TOP" class="toplink">Top</a></p>
… …
113(fractional) number of seconds since the (POSIX) epoch (somewhere near 155(fractional) number of seconds since the (POSIX) epoch (somewhere near
114the beginning of 1970, details are complicated, don't ask). This type is 156the beginning of 1970, details are complicated, don't ask). This type is
115called <code>ev_tstamp</code>, which is what you should use too. It usually aliases 157called <code>ev_tstamp</code>, which is what you should use too. It usually aliases
116to the <code>double</code> type in C, and when you need to do any calculations on 158to the <code>double</code> type in C, and when you need to do any calculations on
117it, you should treat it as such.</p> 159it, you should treat it as such.</p>
118
119
120
121
122 160
123</div> 161</div>
124<h1 id="GLOBAL_FUNCTIONS">GLOBAL FUNCTIONS</h1><p><a href="#TOP" class="toplink">Top</a></p> 162<h1 id="GLOBAL_FUNCTIONS">GLOBAL FUNCTIONS</h1><p><a href="#TOP" class="toplink">Top</a></p>
125<div id="GLOBAL_FUNCTIONS_CONTENT"> 163<div id="GLOBAL_FUNCTIONS_CONTENT">
126<p>These functions can be called anytime, even before initialising the 164<p>These functions can be called anytime, even before initialising the
… …
181might be supported on the current system, you would need to look at 219might be supported on the current system, you would need to look at
182<code>ev_embeddable_backends () &amp; ev_supported_backends ()</code>, likewise for 220<code>ev_embeddable_backends () &amp; ev_supported_backends ()</code>, likewise for
183recommended ones.</p> 221recommended ones.</p>
184 <p>See the description of <code>ev_embed</code> watchers for more info.</p> 222 <p>See the description of <code>ev_embed</code> watchers for more info.</p>
185 </dd> 223 </dd>
186 <dt>ev_set_allocator (void *(*cb)(void *ptr, long size))</dt> 224 <dt>ev_set_allocator (void *(*cb)(void *ptr, size_t size))</dt>
187 <dd> 225 <dd>
188 <p>Sets the allocation function to use (the prototype is similar to the 226 <p>Sets the allocation function to use (the prototype and semantics are
189realloc C function, the semantics are identical). It is used to allocate 227identical to the realloc C function). It is used to allocate and free
190and free memory (no surprises here). If it returns zero when memory 228memory (no surprises here). If it returns zero when memory needs to be
191needs to be allocated, the library might abort or take some potentially 229allocated, the library might abort or take some potentially destructive
192destructive action. The default is your system realloc function.</p> 230action. The default is your system realloc function.</p>
193 <p>You could override this function in high-availability programs to, say, 231 <p>You could override this function in high-availability programs to, say,
194free some memory if it cannot allocate memory, to use a special allocator, 232free some memory if it cannot allocate memory, to use a special allocator,
195or even to sleep a while and retry until some memory is available.</p> 233or even to sleep a while and retry until some memory is available.</p>
196 <p>Example: replace the libev allocator with one that waits a bit and then 234 <p>Example: replace the libev allocator with one that waits a bit and then
197retries: better than mine).</p> 235retries: better than mine).</p>
198<pre> static void * 236<pre> static void *
199 persistent_realloc (void *ptr, long size) 237 persistent_realloc (void *ptr, size_t size)
200 { 238 {
201 for (;;) 239 for (;;)
202 { 240 {
203 void *newptr = realloc (ptr, size); 241 void *newptr = realloc (ptr, size);
204 242
… …
606received events. Callbacks of both watcher types can start and stop as 644received events. Callbacks of both watcher types can start and stop as
607many watchers as they want, and all of them will be taken into account 645many watchers as they want, and all of them will be taken into account
608(for example, a <code>ev_prepare</code> watcher might start an idle watcher to keep 646(for example, a <code>ev_prepare</code> watcher might start an idle watcher to keep
609<code>ev_loop</code> from blocking).</p> 647<code>ev_loop</code> from blocking).</p>
610 </dd> 648 </dd>
649 <dt><code>EV_EMBED</code></dt>
650 <dd>
651 <p>The embedded event loop specified in the <code>ev_embed</code> watcher needs attention.</p>
652 </dd>
653 <dt><code>EV_FORK</code></dt>
654 <dd>
655 <p>The event loop has been resumed in the child process after fork (see
656<code>ev_fork</code>).</p>
657 </dd>
611 <dt><code>EV_ERROR</code></dt> 658 <dt><code>EV_ERROR</code></dt>
612 <dd> 659 <dd>
613 <p>An unspecified error has occured, the watcher has been stopped. This might 660 <p>An unspecified error has occured, the watcher has been stopped. This might
614happen because the watcher could not be properly started because libev 661happen because the watcher could not be properly started because libev
615ran out of memory, a file descriptor was found to be closed or any other 662ran out of memory, a file descriptor was found to be closed or any other
… …
1472apropriate way for embedded loops.</p> 1519apropriate way for embedded loops.</p>
1473 </dd> 1520 </dd>
1474 <dt>struct ev_loop *loop [read-only]</dt> 1521 <dt>struct ev_loop *loop [read-only]</dt>
1475 <dd> 1522 <dd>
1476 <p>The embedded event loop.</p> 1523 <p>The embedded event loop.</p>
1524 </dd>
1525</dl>
1526
1527
1528
1529
1530
1531</div>
1532<h2 id="code_ev_fork_code_the_audacity_to_re"><code>ev_fork</code> - the audacity to resume the event loop after a fork</h2>
1533<div id="code_ev_fork_code_the_audacity_to_re-2">
1534<p>Fork watchers are called when a <code>fork ()</code> was detected (usually because
1535whoever is a good citizen cared to tell libev about it by calling
1536<code>ev_default_fork</code> or <code>ev_loop_fork</code>). The invocation is done before the
1537event loop blocks next and before <code>ev_check</code> watchers are being called,
1538and only in the child after the fork. If whoever good citizen calling
1539<code>ev_default_fork</code> cheats and calls it in the wrong process, the fork
1540handlers will be invoked, too, of course.</p>
1541<dl>
1542 <dt>ev_fork_init (ev_signal *, callback)</dt>
1543 <dd>
1544 <p>Initialises and configures the fork watcher - it has no parameters of any
1545kind. There is a <code>ev_fork_set</code> macro, but using it is utterly pointless,
1546believe me.</p>
1477 </dd> 1547 </dd>
1478</dl> 1548</dl>
1479 1549
1480 1550
1481 1551
… …
1656 idle (this, &amp;myclass::idle_cb) 1726 idle (this, &amp;myclass::idle_cb)
1657 { 1727 {
1658 io.start (fd, ev::READ); 1728 io.start (fd, ev::READ);
1659 } 1729 }
1660 1730
1731
1732
1733
1734</pre>
1735
1736</div>
1737<h1 id="MACRO_MAGIC">MACRO MAGIC</h1><p><a href="#TOP" class="toplink">Top</a></p>
1738<div id="MACRO_MAGIC_CONTENT">
1739<p>Libev can be compiled with a variety of options, the most fundemantal is
1740<code>EV_MULTIPLICITY</code>. This option determines wether (most) functions and
1741callbacks have an initial <code>struct ev_loop *</code> argument.</p>
1742<p>To make it easier to write programs that cope with either variant, the
1743following macros are defined:</p>
1744<dl>
1745 <dt><code>EV_A</code>, <code>EV_A_</code></dt>
1746 <dd>
1747 <p>This provides the loop <i>argument</i> for functions, if one is required (&quot;ev
1748loop argument&quot;). The <code>EV_A</code> form is used when this is the sole argument,
1749<code>EV_A_</code> is used when other arguments are following. Example:</p>
1750<pre> ev_unref (EV_A);
1751 ev_timer_add (EV_A_ watcher);
1752 ev_loop (EV_A_ 0);
1753
1754</pre>
1755 <p>It assumes the variable <code>loop</code> of type <code>struct ev_loop *</code> is in scope,
1756which is often provided by the following macro.</p>
1757 </dd>
1758 <dt><code>EV_P</code>, <code>EV_P_</code></dt>
1759 <dd>
1760 <p>This provides the loop <i>parameter</i> for functions, if one is required (&quot;ev
1761loop parameter&quot;). The <code>EV_P</code> form is used when this is the sole parameter,
1762<code>EV_P_</code> is used when other parameters are following. Example:</p>
1763<pre> // this is how ev_unref is being declared
1764 static void ev_unref (EV_P);
1765
1766 // this is how you can declare your typical callback
1767 static void cb (EV_P_ ev_timer *w, int revents)
1768
1769</pre>
1770 <p>It declares a parameter <code>loop</code> of type <code>struct ev_loop *</code>, quite
1771suitable for use with <code>EV_A</code>.</p>
1772 </dd>
1773 <dt><code>EV_DEFAULT</code>, <code>EV_DEFAULT_</code></dt>
1774 <dd>
1775 <p>Similar to the other two macros, this gives you the value of the default
1776loop, if multiple loops are supported (&quot;ev loop default&quot;).</p>
1777 </dd>
1778</dl>
1779<p>Example: Declare and initialise a check watcher, working regardless of
1780wether multiple loops are supported or not.</p>
1781<pre> static void
1782 check_cb (EV_P_ ev_timer *w, int revents)
1783 {
1784 ev_check_stop (EV_A_ w);
1785 }
1786
1787 ev_check check;
1788 ev_check_init (&amp;check, check_cb);
1789 ev_check_start (EV_DEFAULT_ &amp;check);
1790 ev_loop (EV_DEFAULT_ 0);
1791
1792
1793
1794
1661</pre> 1795</pre>
1662 1796
1663</div> 1797</div>
1664<h1 id="EMBEDDING">EMBEDDING</h1><p><a href="#TOP" class="toplink">Top</a></p> 1798<h1 id="EMBEDDING">EMBEDDING</h1><p><a href="#TOP" class="toplink">Top</a></p>
1665<div id="EMBEDDING_CONTENT"> 1799<div id="EMBEDDING_CONTENT">
… …
1891 <dt>EV_STAT_ENABLE</dt> 2025 <dt>EV_STAT_ENABLE</dt>
1892 <dd> 2026 <dd>
1893 <p>If undefined or defined to be <code>1</code>, then stat watchers are supported. If 2027 <p>If undefined or defined to be <code>1</code>, then stat watchers are supported. If
1894defined to be <code>0</code>, then they are not.</p> 2028defined to be <code>0</code>, then they are not.</p>
1895 </dd> 2029 </dd>
2030 <dt>EV_FORK_ENABLE</dt>
2031 <dd>
2032 <p>If undefined or defined to be <code>1</code>, then fork watchers are supported. If
2033defined to be <code>0</code>, then they are not.</p>
2034 </dd>
1896 <dt>EV_MINIMAL</dt> 2035 <dt>EV_MINIMAL</dt>
1897 <dd> 2036 <dd>
1898 <p>If you need to shave off some kilobytes of code at the expense of some 2037 <p>If you need to shave off some kilobytes of code at the expense of some
1899speed, define this symbol to <code>1</code>. Currently only used for gcc to override 2038speed, define this symbol to <code>1</code>. Currently only used for gcc to override
1900some inlining decisions, saves roughly 30% codesize of amd64.</p> 2039some inlining decisions, saves roughly 30% codesize of amd64.</p>
2040 </dd>
2041 <dt>EV_PID_HASHSIZE</dt>
2042 <dd>
2043 <p><code>ev_child</code> watchers use a small hash table to distribute workload by
2044pid. The default size is <code>16</code> (or <code>1</code> with <code>EV_MINIMAL</code>), usually more
2045than enough. If you need to manage thousands of children you might want to
2046increase this value.</p>
1901 </dd> 2047 </dd>
1902 <dt>EV_COMMON</dt> 2048 <dt>EV_COMMON</dt>
1903 <dd> 2049 <dd>
1904 <p>By default, all watchers have a <code>void *data</code> member. By redefining 2050 <p>By default, all watchers have a <code>void *data</code> member. By redefining
1905this macro to a something else you can include more and other types of 2051this macro to a something else you can include more and other types of

Diff Legend

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