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.50 by root, Tue Nov 27 10:59:11 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 11:59:06 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>
… …
113(fractional) number of seconds since the (POSIX) epoch (somewhere near 115(fractional) number of seconds since the (POSIX) epoch (somewhere near
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
119
120
121
122 120
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
… …
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
… …
1656 idle (this, &amp;myclass::idle_cb) 1686 idle (this, &amp;myclass::idle_cb)
1657 { 1687 {
1658 io.start (fd, ev::READ); 1688 io.start (fd, ev::READ);
1659 } 1689 }
1660 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
1754
1661</pre> 1755</pre>
1662 1756
1663</div> 1757</div>
1664<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>
1665<div id="EMBEDDING_CONTENT"> 1759<div id="EMBEDDING_CONTENT">
… …
1889defined to be <code>0</code>, then they are not.</p> 1983defined to be <code>0</code>, then they are not.</p>
1890 </dd> 1984 </dd>
1891 <dt>EV_STAT_ENABLE</dt> 1985 <dt>EV_STAT_ENABLE</dt>
1892 <dd> 1986 <dd>
1893 <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
1988defined to be <code>0</code>, then they are not.</p>
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
1894defined to be <code>0</code>, then they are not.</p> 1993defined to be <code>0</code>, then they are not.</p>
1895 </dd> 1994 </dd>
1896 <dt>EV_MINIMAL</dt> 1995 <dt>EV_MINIMAL</dt>
1897 <dd> 1996 <dd>
1898 <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

Diff Legend

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