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

Comparing libev/ev.html (file contents):
Revision 1.48 by root, Tue Nov 27 08:11:52 2007 UTC vs.
Revision 1.52 by root, Tue Nov 27 19:41:52 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:11:42 2007" /> 9 <meta name="created" content="Tue Nov 27 20:38:24 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>
… …
114the beginning of 1970, details are complicated, don't ask). This type is 116the 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 117called <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 118to the <code>double</code> type in C, and when you need to do any calculations on
117it, you should treat it as such.</p> 119it, you should treat it as such.</p>
118 120
119
120
121
122
123</div> 121</div>
124<h1 id="GLOBAL_FUNCTIONS">GLOBAL FUNCTIONS</h1><p><a href="#TOP" class="toplink">Top</a></p> 122<h1 id="GLOBAL_FUNCTIONS">GLOBAL FUNCTIONS</h1><p><a href="#TOP" class="toplink">Top</a></p>
125<div id="GLOBAL_FUNCTIONS_CONTENT"> 123<div id="GLOBAL_FUNCTIONS_CONTENT">
126<p>These functions can be called anytime, even before initialising the 124<p>These functions can be called anytime, even before initialising the
127library in any way.</p> 125library in any way.</p>
… …
181might be supported on the current system, you would need to look at 179might be supported on the current system, you would need to look at
182<code>ev_embeddable_backends () &amp; ev_supported_backends ()</code>, likewise for 180<code>ev_embeddable_backends () &amp; ev_supported_backends ()</code>, likewise for
183recommended ones.</p> 181recommended ones.</p>
184 <p>See the description of <code>ev_embed</code> watchers for more info.</p> 182 <p>See the description of <code>ev_embed</code> watchers for more info.</p>
185 </dd> 183 </dd>
186 <dt>ev_set_allocator (void *(*cb)(void *ptr, long size))</dt> 184 <dt>ev_set_allocator (void *(*cb)(void *ptr, size_t size))</dt>
187 <dd> 185 <dd>
188 <p>Sets the allocation function to use (the prototype is similar to the 186 <p>Sets the allocation function to use (the prototype and semantics are
189realloc C function, the semantics are identical). It is used to allocate 187identical to the realloc C function). It is used to allocate and free
190and free memory (no surprises here). If it returns zero when memory 188memory (no surprises here). If it returns zero when memory needs to be
191needs to be allocated, the library might abort or take some potentially 189allocated, the library might abort or take some potentially destructive
192destructive action. The default is your system realloc function.</p> 190action. The default is your system realloc function.</p>
193 <p>You could override this function in high-availability programs to, say, 191 <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, 192free 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> 193or 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 194 <p>Example: replace the libev allocator with one that waits a bit and then
197retries: better than mine).</p> 195retries: better than mine).</p>
198<pre> static void * 196<pre> static void *
199 persistent_realloc (void *ptr, long size) 197 persistent_realloc (void *ptr, size_t size)
200 { 198 {
201 for (;;) 199 for (;;)
202 { 200 {
203 void *newptr = realloc (ptr, size); 201 void *newptr = realloc (ptr, size);
204 202
… …
606received events. Callbacks of both watcher types can start and stop as 604received 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 605many 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 606(for example, a <code>ev_prepare</code> watcher might start an idle watcher to keep
609<code>ev_loop</code> from blocking).</p> 607<code>ev_loop</code> from blocking).</p>
610 </dd> 608 </dd>
609 <dt><code>EV_EMBED</code></dt>
610 <dd>
611 <p>The embedded event loop specified in the <code>ev_embed</code> watcher needs attention.</p>
612 </dd>
613 <dt><code>EV_FORK</code></dt>
614 <dd>
615 <p>The event loop has been resumed in the child process after fork (see
616<code>ev_fork</code>).</p>
617 </dd>
611 <dt><code>EV_ERROR</code></dt> 618 <dt><code>EV_ERROR</code></dt>
612 <dd> 619 <dd>
613 <p>An unspecified error has occured, the watcher has been stopped. This might 620 <p>An unspecified error has occured, the watcher has been stopped. This might
614happen because the watcher could not be properly started because libev 621happen 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 622ran out of memory, a file descriptor was found to be closed or any other
… …
1472apropriate way for embedded loops.</p> 1479apropriate way for embedded loops.</p>
1473 </dd> 1480 </dd>
1474 <dt>struct ev_loop *loop [read-only]</dt> 1481 <dt>struct ev_loop *loop [read-only]</dt>
1475 <dd> 1482 <dd>
1476 <p>The embedded event loop.</p> 1483 <p>The embedded event loop.</p>
1484 </dd>
1485</dl>
1486
1487
1488
1489
1490
1491</div>
1492<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>
1493<div id="code_ev_fork_code_the_audacity_to_re-2">
1494<p>Fork watchers are called when a <code>fork ()</code> was detected (usually because
1495whoever is a good citizen cared to tell libev about it by calling
1496<code>ev_default_fork</code> or <code>ev_loop_fork</code>). The invocation is done before the
1497event loop blocks next and before <code>ev_check</code> watchers are being called,
1498and only in the child after the fork. If whoever good citizen calling
1499<code>ev_default_fork</code> cheats and calls it in the wrong process, the fork
1500handlers will be invoked, too, of course.</p>
1501<dl>
1502 <dt>ev_fork_init (ev_signal *, callback)</dt>
1503 <dd>
1504 <p>Initialises and configures the fork watcher - it has no parameters of any
1505kind. There is a <code>ev_fork_set</code> macro, but using it is utterly pointless,
1506believe me.</p>
1477 </dd> 1507 </dd>
1478</dl> 1508</dl>
1479 1509
1480 1510
1481 1511
… …
1631 </dd> 1661 </dd>
1632 <dt>w-&gt;sweep () <code>ev::embed</code> only</dt> 1662 <dt>w-&gt;sweep () <code>ev::embed</code> only</dt>
1633 <dd> 1663 <dd>
1634 <p>Invokes <code>ev_embed_sweep</code>.</p> 1664 <p>Invokes <code>ev_embed_sweep</code>.</p>
1635 </dd> 1665 </dd>
1666 <dt>w-&gt;update () <code>ev::stat</code> only</dt>
1667 <dd>
1668 <p>Invokes <code>ev_stat_stat</code>.</p>
1669 </dd>
1636 </dl> 1670 </dl>
1637 </p> 1671 </p>
1638 </dd> 1672 </dd>
1639</dl> 1673</dl>
1640<p>Example: Define a class with an IO and idle watcher, start one of them in 1674<p>Example: Define a class with an IO and idle watcher, start one of them in
… …
1651 : io (this, &amp;myclass::io_cb), 1685 : io (this, &amp;myclass::io_cb),
1652 idle (this, &amp;myclass::idle_cb) 1686 idle (this, &amp;myclass::idle_cb)
1653 { 1687 {
1654 io.start (fd, ev::READ); 1688 io.start (fd, ev::READ);
1655 } 1689 }
1690
1691
1692
1693
1694</pre>
1695
1696</div>
1697<h1 id="MACRO_MAGIC">MACRO MAGIC</h1><p><a href="#TOP" class="toplink">Top</a></p>
1698<div id="MACRO_MAGIC_CONTENT">
1699<p>Libev can be compiled with a variety of options, the most fundemantal is
1700<code>EV_MULTIPLICITY</code>. This option determines wether (most) functions and
1701callbacks have an initial <code>struct ev_loop *</code> argument.</p>
1702<p>To make it easier to write programs that cope with either variant, the
1703following macros are defined:</p>
1704<dl>
1705 <dt><code>EV_A</code>, <code>EV_A_</code></dt>
1706 <dd>
1707 <p>This provides the loop <i>argument</i> for functions, if one is required (&quot;ev
1708loop argument&quot;). The <code>EV_A</code> form is used when this is the sole argument,
1709<code>EV_A_</code> is used when other arguments are following. Example:</p>
1710<pre> ev_unref (EV_A);
1711 ev_timer_add (EV_A_ watcher);
1712 ev_loop (EV_A_ 0);
1713
1714</pre>
1715 <p>It assumes the variable <code>loop</code> of type <code>struct ev_loop *</code> is in scope,
1716which is often provided by the following macro.</p>
1717 </dd>
1718 <dt><code>EV_P</code>, <code>EV_P_</code></dt>
1719 <dd>
1720 <p>This provides the loop <i>parameter</i> for functions, if one is required (&quot;ev
1721loop parameter&quot;). The <code>EV_P</code> form is used when this is the sole parameter,
1722<code>EV_P_</code> is used when other parameters are following. Example:</p>
1723<pre> // this is how ev_unref is being declared
1724 static void ev_unref (EV_P);
1725
1726 // this is how you can declare your typical callback
1727 static void cb (EV_P_ ev_timer *w, int revents)
1728
1729</pre>
1730 <p>It declares a parameter <code>loop</code> of type <code>struct ev_loop *</code>, quite
1731suitable for use with <code>EV_A</code>.</p>
1732 </dd>
1733 <dt><code>EV_DEFAULT</code>, <code>EV_DEFAULT_</code></dt>
1734 <dd>
1735 <p>Similar to the other two macros, this gives you the value of the default
1736loop, if multiple loops are supported (&quot;ev loop default&quot;).</p>
1737 </dd>
1738</dl>
1739<p>Example: Declare and initialise a check watcher, working regardless of
1740wether multiple loops are supported or not.</p>
1741<pre> static void
1742 check_cb (EV_P_ ev_timer *w, int revents)
1743 {
1744 ev_check_stop (EV_A_ w);
1745 }
1746
1747 ev_check check;
1748 ev_check_init (&amp;check, check_cb);
1749 ev_check_start (EV_DEFAULT_ &amp;check);
1750 ev_loop (EV_DEFAULT_ 0);
1751
1752
1753
1656 1754
1657</pre> 1755</pre>
1658 1756
1659</div> 1757</div>
1660<h1 id="EMBEDDING">EMBEDDING</h1><p><a href="#TOP" class="toplink">Top</a></p> 1758<h1 id="EMBEDDING">EMBEDDING</h1><p><a href="#TOP" class="toplink">Top</a></p>
… …
1887 <dt>EV_STAT_ENABLE</dt> 1985 <dt>EV_STAT_ENABLE</dt>
1888 <dd> 1986 <dd>
1889 <p>If undefined or defined to be <code>1</code>, then stat watchers are supported. If 1987 <p>If undefined or defined to be <code>1</code>, then stat watchers are supported. If
1890defined to be <code>0</code>, then they are not.</p> 1988defined to be <code>0</code>, then they are not.</p>
1891 </dd> 1989 </dd>
1990 <dt>EV_FORK_ENABLE</dt>
1991 <dd>
1992 <p>If undefined or defined to be <code>1</code>, then fork watchers are supported. If
1993defined to be <code>0</code>, then they are not.</p>
1994 </dd>
1892 <dt>EV_MINIMAL</dt> 1995 <dt>EV_MINIMAL</dt>
1893 <dd> 1996 <dd>
1894 <p>If you need to shave off some kilobytes of code at the expense of some 1997 <p>If you need to shave off some kilobytes of code at the expense of some
1895speed, define this symbol to <code>1</code>. Currently only used for gcc to override 1998speed, define this symbol to <code>1</code>. Currently only used for gcc to override
1896some inlining decisions, saves roughly 30% codesize of amd64.</p> 1999some inlining decisions, saves roughly 30% codesize of amd64.</p>
2000 </dd>
2001 <dt>EV_PID_HASHSIZE</dt>
2002 <dd>
2003 <p><code>ev_child</code> watchers use a small hash table to distribute workload by
2004pid. The default size is <code>16</code> (or <code>1</code> with <code>EV_MINIMAL</code>), usually more
2005than enough. If you need to manage thousands of children you might want to
2006increase this value.</p>
1897 </dd> 2007 </dd>
1898 <dt>EV_COMMON</dt> 2008 <dt>EV_COMMON</dt>
1899 <dd> 2009 <dd>
1900 <p>By default, all watchers have a <code>void *data</code> member. By redefining 2010 <p>By default, all watchers have a <code>void *data</code> member. By redefining
1901this macro to a something else you can include more and other types of 2011this macro to a something else you can include more and other types of

Diff Legend

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