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

Comparing libev/ev.html (file contents):
Revision 1.39 by root, Sat Nov 24 09:48:38 2007 UTC vs.
Revision 1.40 by root, Sat Nov 24 10:10:26 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="Sat Nov 24 10:48:32 2007" /> 9 <meta name="created" content="Sat Nov 24 11:10:25 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 -->
… …
39</ul> 39</ul>
40</li> 40</li>
41<li><a href="#OTHER_FUNCTIONS">OTHER FUNCTIONS</a></li> 41<li><a href="#OTHER_FUNCTIONS">OTHER FUNCTIONS</a></li>
42<li><a href="#LIBEVENT_EMULATION">LIBEVENT EMULATION</a></li> 42<li><a href="#LIBEVENT_EMULATION">LIBEVENT EMULATION</a></li>
43<li><a href="#C_SUPPORT">C++ SUPPORT</a></li> 43<li><a href="#C_SUPPORT">C++ SUPPORT</a></li>
44<li><a href="#EMBEDDING">EMBEDDING</a>
45<ul><li><a href="#FILESETS">FILESETS</a>
46<ul><li><a href="#CORE_EVENT_LOOP">CORE EVENT LOOP</a></li>
47<li><a href="#LIBEVENT_COMPATIBILITY_API">LIBEVENT COMPATIBILITY API</a></li>
48<li><a href="#AUTOCONF_SUPPORT">AUTOCONF SUPPORT</a></li>
49</ul>
50</li>
51<li><a href="#PREPROCESSOR_SYMBOLS_MACROS">PREPROCESSOR SYMBOLS/MACROS</a></li>
52<li><a href="#EXAMPLES">EXAMPLES</a></li>
53</ul>
54</li>
44<li><a href="#AUTHOR">AUTHOR</a> 55<li><a href="#AUTHOR">AUTHOR</a>
45</li> 56</li>
46</ul><hr /> 57</ul><hr />
47<!-- INDEX END --> 58<!-- INDEX END -->
48 59
… …
1402 } 1413 }
1403 1414
1404</pre> 1415</pre>
1405 1416
1406</div> 1417</div>
1418<h1 id="EMBEDDING">EMBEDDING</h1><p><a href="#TOP" class="toplink">Top</a></p>
1419<div id="EMBEDDING_CONTENT">
1420<p>Libev can (and often is) directly embedded into host
1421applications. Examples of applications that embed it include the Deliantra
1422Game Server, the EV perl module, the GNU Virtual Private Ethernet (gvpe)
1423and rxvt-unicode.</p>
1424<p>The goal is to enable you to just copy the neecssary files into your
1425source directory without having to change even a single line in them, so
1426you can easily upgrade by simply copying (or having a checked-out copy of
1427libev somewhere in your source tree).</p>
1428
1429</div>
1430<h2 id="FILESETS">FILESETS</h2>
1431<div id="FILESETS_CONTENT">
1432<p>Depending on what features you need you need to include one or more sets of files
1433in your app.</p>
1434
1435</div>
1436<h3 id="CORE_EVENT_LOOP">CORE EVENT LOOP</h3>
1437<div id="CORE_EVENT_LOOP_CONTENT">
1438<p>To include only the libev core (all the <code>ev_*</code> functions), with manual
1439configuration (no autoconf):</p>
1440<pre> #define EV_STANDALONE 1
1441 #include &quot;ev.c&quot;
1442
1443</pre>
1444<p>This will automatically include <cite>ev.h</cite>, too, and should be done in a
1445single C source file only to provide the function implementations. To use
1446it, do the same for <cite>ev.h</cite> in all files wishing to use this API (best
1447done by writing a wrapper around <cite>ev.h</cite> that you can include instead and
1448where you can put other configuration options):</p>
1449<pre> #define EV_STANDALONE 1
1450 #include &quot;ev.h&quot;
1451
1452</pre>
1453<p>Both header files and implementation files can be compiled with a C++
1454compiler (at least, thats a stated goal, and breakage will be treated
1455as a bug).</p>
1456<p>You need the following files in your source tree, or in a directory
1457in your include path (e.g. in libev/ when using -Ilibev):</p>
1458<pre> ev.h
1459 ev.c
1460 ev_vars.h
1461 ev_wrap.h
1462
1463 ev_win32.c required on win32 platforms only
1464
1465 ev_select.c only when select backend is enabled (which is is by default)
1466 ev_poll.c only when poll backend is enabled (disabled by default)
1467 ev_epoll.c only when the epoll backend is enabled (disabled by default)
1468 ev_kqueue.c only when the kqueue backend is enabled (disabled by default)
1469 ev_port.c only when the solaris port backend is enabled (disabled by default)
1470
1471</pre>
1472<p><cite>ev.c</cite> includes the backend files directly when enabled, so you only need
1473to compile a single file.</p>
1474
1475</div>
1476<h3 id="LIBEVENT_COMPATIBILITY_API">LIBEVENT COMPATIBILITY API</h3>
1477<div id="LIBEVENT_COMPATIBILITY_API_CONTENT">
1478<p>To include the libevent compatibility API, also include:</p>
1479<pre> #include &quot;event.c&quot;
1480
1481</pre>
1482<p>in the file including <cite>ev.c</cite>, and:</p>
1483<pre> #include &quot;event.h&quot;
1484
1485</pre>
1486<p>in the files that want to use the libevent API. This also includes <cite>ev.h</cite>.</p>
1487<p>You need the following additional files for this:</p>
1488<pre> event.h
1489 event.c
1490
1491</pre>
1492
1493</div>
1494<h3 id="AUTOCONF_SUPPORT">AUTOCONF SUPPORT</h3>
1495<div id="AUTOCONF_SUPPORT_CONTENT">
1496<p>Instead of using <code>EV_STANDALONE=1</code> and providing your config in
1497whatever way you want, you can also <code>m4_include([libev.m4])</code> in your
1498<cite>configure.ac</cite> and leave <code>EV_STANDALONE</code> off. <cite>ev.c</cite> will then include
1499<cite>config.h</cite> and configure itself accordingly.</p>
1500<p>For this of course you need the m4 file:</p>
1501<pre> libev.m4
1502
1503</pre>
1504
1505</div>
1506<h2 id="PREPROCESSOR_SYMBOLS_MACROS">PREPROCESSOR SYMBOLS/MACROS</h2>
1507<div id="PREPROCESSOR_SYMBOLS_MACROS_CONTENT">
1508<p>Libev can be configured via a variety of preprocessor symbols you have to define
1509before including any of its files. The default is not to build for multiplicity
1510and only include the select backend.</p>
1511<dl>
1512 <dt>EV_STANDALONE</dt>
1513 <dd>
1514 <p>Must always be <code>1</code> if you do not use autoconf configuration, which
1515keeps libev from including <cite>config.h</cite>, and it also defines dummy
1516implementations for some libevent functions (such as logging, which is not
1517supported). It will also not define any of the structs usually found in
1518<cite>event.h</cite> that are not directly supported by the libev core alone.</p>
1519 </dd>
1520 <dt>EV_USE_MONOTONIC</dt>
1521 <dd>
1522 <p>If defined to be <code>1</code>, libev will try to detect the availability of the
1523monotonic clock option at both compiletime and runtime. Otherwise no use
1524of the monotonic clock option will be attempted. If you enable this, you
1525usually have to link against librt or something similar. Enabling it when
1526the functionality isn't available is safe, though, althoguh you have
1527to make sure you link against any libraries where the <code>clock_gettime</code>
1528function is hiding in (often <cite>-lrt</cite>).</p>
1529 </dd>
1530 <dt>EV_USE_REALTIME</dt>
1531 <dd>
1532 <p>If defined to be <code>1</code>, libev will try to detect the availability of the
1533realtime clock option at compiletime (and assume its availability at
1534runtime if successful). Otherwise no use of the realtime clock option will
1535be attempted. This effectively replaces <code>gettimeofday</code> by <code>clock_get
1536(CLOCK_REALTIME, ...)</code> and will not normally affect correctness. See tzhe note about libraries
1537in the description of <code>EV_USE_MONOTONIC</code>, though.</p>
1538 </dd>
1539 <dt>EV_USE_SELECT</dt>
1540 <dd>
1541 <p>If undefined or defined to be <code>1</code>, libev will compile in support for the
1542<code>select</code>(2) backend. No attempt at autodetection will be done: if no
1543other method takes over, select will be it. Otherwise the select backend
1544will not be compiled in.</p>
1545 </dd>
1546 <dt>EV_SELECT_USE_FD_SET</dt>
1547 <dd>
1548 <p>If defined to <code>1</code>, then the select backend will use the system <code>fd_set</code>
1549structure. This is useful if libev doesn't compile due to a missing
1550<code>NFDBITS</code> or <code>fd_mask</code> definition or it misguesses the bitset layout on
1551exotic systems. This usually limits the range of file descriptors to some
1552low limit such as 1024 or might have other limitations (winsocket only
1553allows 64 sockets). The <code>FD_SETSIZE</code> macro, set before compilation, might
1554influence the size of the <code>fd_set</code> used.</p>
1555 </dd>
1556 <dt>EV_SELECT_IS_WINSOCKET</dt>
1557 <dd>
1558 <p>When defined to <code>1</code>, the select backend will assume that
1559select/socket/connect etc. don't understand file descriptors but
1560wants osf handles on win32 (this is the case when the select to
1561be used is the winsock select). This means that it will call
1562<code>_get_osfhandle</code> on the fd to convert it to an OS handle. Otherwise,
1563it is assumed that all these functions actually work on fds, even
1564on win32. Should not be defined on non-win32 platforms.</p>
1565 </dd>
1566 <dt>EV_USE_POLL</dt>
1567 <dd>
1568 <p>If defined to be <code>1</code>, libev will compile in support for the <code>poll</code>(2)
1569backend. Otherwise it will be enabled on non-win32 platforms. It
1570takes precedence over select.</p>
1571 </dd>
1572 <dt>EV_USE_EPOLL</dt>
1573 <dd>
1574 <p>If defined to be <code>1</code>, libev will compile in support for the Linux
1575<code>epoll</code>(7) backend. Its availability will be detected at runtime,
1576otherwise another method will be used as fallback. This is the
1577preferred backend for GNU/Linux systems.</p>
1578 </dd>
1579 <dt>EV_USE_KQUEUE</dt>
1580 <dd>
1581 <p>If defined to be <code>1</code>, libev will compile in support for the BSD style
1582<code>kqueue</code>(2) backend. Its actual availability will be detected at runtime,
1583otherwise another method will be used as fallback. This is the preferred
1584backend for BSD and BSD-like systems, although on most BSDs kqueue only
1585supports some types of fds correctly (the only platform we found that
1586supports ptys for example was NetBSD), so kqueue might be compiled in, but
1587not be used unless explicitly requested. The best way to use it is to find
1588out wether kqueue supports your type of fd properly and use an embedded
1589kqueue loop.</p>
1590 </dd>
1591 <dt>EV_USE_PORT</dt>
1592 <dd>
1593 <p>If defined to be <code>1</code>, libev will compile in support for the Solaris
159410 port style backend. Its availability will be detected at runtime,
1595otherwise another method will be used as fallback. This is the preferred
1596backend for Solaris 10 systems.</p>
1597 </dd>
1598 <dt>EV_USE_DEVPOLL</dt>
1599 <dd>
1600 <p>reserved for future expansion, works like the USE symbols above.</p>
1601 </dd>
1602 <dt>EV_H</dt>
1603 <dd>
1604 <p>The name of the <cite>ev.h</cite> header file used to include it. The default if
1605undefined is <code>&lt;ev.h&gt;</code> in <cite>event.h</cite> and <code>&quot;ev.h&quot;</code> in <cite>ev.c</cite>. This
1606can be used to virtually rename the <cite>ev.h</cite> header file in case of conflicts.</p>
1607 </dd>
1608 <dt>EV_CONFIG_H</dt>
1609 <dd>
1610 <p>If <code>EV_STANDALONE</code> isn't <code>1</code>, this variable can be used to override
1611<cite>ev.c</cite>'s idea of where to find the <cite>config.h</cite> file, similarly to
1612<code>EV_H</code>, above.</p>
1613 </dd>
1614 <dt>EV_EVENT_H</dt>
1615 <dd>
1616 <p>Similarly to <code>EV_H</code>, this macro can be used to override <cite>event.c</cite>'s idea
1617of how the <cite>event.h</cite> header can be found.</p>
1618 </dd>
1619 <dt>EV_PROTOTYPES</dt>
1620 <dd>
1621 <p>If defined to be <code>0</code>, then <cite>ev.h</cite> will not define any function
1622prototypes, but still define all the structs and other symbols. This is
1623occasionally useful if you want to provide your own wrapper functions
1624around libev functions.</p>
1625 </dd>
1626 <dt>EV_MULTIPLICITY</dt>
1627 <dd>
1628 <p>If undefined or defined to <code>1</code>, then all event-loop-specific functions
1629will have the <code>struct ev_loop *</code> as first argument, and you can create
1630additional independent event loops. Otherwise there will be no support
1631for multiple event loops and there is no first event loop pointer
1632argument. Instead, all functions act on the single default loop.</p>
1633 </dd>
1634 <dt>EV_PERIODICS</dt>
1635 <dd>
1636 <p>If undefined or defined to be <code>1</code>, then periodic timers are supported,
1637otherwise not. This saves a few kb of code.</p>
1638 </dd>
1639 <dt>EV_COMMON</dt>
1640 <dd>
1641 <p>By default, all watchers have a <code>void *data</code> member. By redefining
1642this macro to a something else you can include more and other types of
1643members. You have to define it each time you include one of the files,
1644though, and it must be identical each time.</p>
1645 <p>For example, the perl EV module uses something like this:</p>
1646<pre> #define EV_COMMON \
1647 SV *self; /* contains this struct */ \
1648 SV *cb_sv, *fh /* note no trailing &quot;;&quot; */
1649
1650</pre>
1651 </dd>
1652 <dt>EV_CB_DECLARE(type)</dt>
1653 <dt>EV_CB_INVOKE(watcher,revents)</dt>
1654 <dt>ev_set_cb(ev,cb)</dt>
1655 <dd>
1656 <p>Can be used to change the callback member declaration in each watcher,
1657and the way callbacks are invoked and set. Must expand to a struct member
1658definition and a statement, respectively. See the <cite>ev.v</cite> header file for
1659their default definitions. One possible use for overriding these is to
1660avoid the ev_loop pointer as first argument in all cases, or to use method
1661calls instead of plain function calls in C++.</p>
1662
1663</div>
1664<h2 id="EXAMPLES">EXAMPLES</h2>
1665<div id="EXAMPLES_CONTENT">
1666 <p>For a real-world example of a program the includes libev
1667verbatim, you can have a look at the EV perl module
1668(<a href="http://software.schmorp.de/pkg/EV.html">http://software.schmorp.de/pkg/EV.html</a>). It has the libev files in
1669the <cite>libev/</cite> subdirectory and includes them in the <cite>EV/EVAPI.h</cite> (public
1670interface) and <cite>EV.xs</cite> (implementation) files. Only the <cite>EV.xs</cite> file
1671will be compiled. It is pretty complex because it provides its own header
1672file.</p>
1673 <p>The usage in rxvt-unicode is simpler. It has a <cite>ev_cpp.h</cite> header file
1674that everybody includes and which overrides some autoconf choices:</p>
1675<pre> #define EV_USE_POLL 0
1676 #define EV_MULTIPLICITY 0
1677 #define EV_PERIODICS 0
1678 #define EV_CONFIG_H &lt;config.h&gt;
1679
1680 #include &quot;ev++.h&quot;
1681
1682</pre>
1683 <p>And a <cite>ev_cpp.C</cite> implementation file that contains libev proper and is compiled:</p>
1684<pre> #include &quot;rxvttoolkit.h&quot;
1685
1686 /* darwin has problems with its header files in C++, requiring this namespace juggling */
1687 using namespace ev;
1688
1689 #include &quot;ev.c&quot;
1690
1691
1692
1693
1694</pre>
1695
1696</div>
1407<h1 id="AUTHOR">AUTHOR</h1><p><a href="#TOP" class="toplink">Top</a></p> 1697<h1 id="AUTHOR">AUTHOR</h1><p><a href="#TOP" class="toplink">Top</a></p>
1408<div id="AUTHOR_CONTENT"> 1698<div id="AUTHOR_CONTENT">
1409<p>Marc Lehmann &lt;libev@schmorp.de&gt;.</p> 1699 <p>Marc Lehmann &lt;libev@schmorp.de&gt;.</p>
1410 1700
1411</div> 1701</div>
1412</div></body> 1702</div></body>
1413</html> 1703</html>

Diff Legend

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