… | |
… | |
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="<standard input>" /> |
7 | <meta name="inputfile" content="<standard input>" /> |
8 | <meta name="outputfile" content="<standard output>" /> |
8 | <meta name="outputfile" content="<standard output>" /> |
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 |
114 | the beginning of 1970, details are complicated, don't ask). This type is |
116 | the beginning of 1970, details are complicated, don't ask). This type is |
115 | called <code>ev_tstamp</code>, which is what you should use too. It usually aliases |
117 | called <code>ev_tstamp</code>, which is what you should use too. It usually aliases |
116 | to the <code>double</code> type in C, and when you need to do any calculations on |
118 | to the <code>double</code> type in C, and when you need to do any calculations on |
117 | it, you should treat it as such.</p> |
119 | it, 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 |
… | |
… | |
606 | received events. Callbacks of both watcher types can start and stop as |
604 | received events. Callbacks of both watcher types can start and stop as |
607 | many watchers as they want, and all of them will be taken into account |
605 | many 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 |
614 | happen because the watcher could not be properly started because libev |
621 | happen because the watcher could not be properly started because libev |
615 | ran out of memory, a file descriptor was found to be closed or any other |
622 | ran out of memory, a file descriptor was found to be closed or any other |
… | |
… | |
1472 | apropriate way for embedded loops.</p> |
1479 | apropriate 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 |
|
|
1495 | whoever 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 |
|
|
1497 | event loop blocks next and before <code>ev_check</code> watchers are being called, |
|
|
1498 | and 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 |
|
|
1500 | handlers 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 |
|
|
1505 | kind. There is a <code>ev_fork_set</code> macro, but using it is utterly pointless, |
|
|
1506 | believe me.</p> |
1477 | </dd> |
1507 | </dd> |
1478 | </dl> |
1508 | </dl> |
1479 | |
1509 | |
1480 | |
1510 | |
1481 | |
1511 | |
… | |
… | |
1656 | idle (this, &myclass::idle_cb) |
1686 | idle (this, &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 |
|
|
1701 | callbacks 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 |
|
|
1703 | following 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 ("ev |
|
|
1708 | loop argument"). 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, |
|
|
1716 | which 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 ("ev |
|
|
1721 | loop parameter"). 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 |
|
|
1731 | suitable 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 |
|
|
1736 | loop, if multiple loops are supported ("ev loop default").</p> |
|
|
1737 | </dd> |
|
|
1738 | </dl> |
|
|
1739 | <p>Example: Declare and initialise a check watcher, working regardless of |
|
|
1740 | wether 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 (&check, check_cb); |
|
|
1749 | ev_check_start (EV_DEFAULT_ &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"> |
… | |
… | |
1889 | defined to be <code>0</code>, then they are not.</p> |
1983 | defined 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 |
|
|
1988 | defined 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 |
1894 | defined to be <code>0</code>, then they are not.</p> |
1993 | defined 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 |