… | |
… | |
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:11:42 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 <ev.h> |
72 | #include <ev.h> |
|
|
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 ("stdin ready"); */ |
|
|
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 ("timeout"); */ |
|
|
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 (&stdin_watcher, stdin_cb, /*STDIN_FILENO*/ 0, EV_READ); |
|
|
101 | ev_io_start (loop, &stdin_watcher); |
|
|
102 | |
|
|
103 | /* simple non-repeating 5.5 second timeout */ |
|
|
104 | ev_timer_init (&timeout_watcher, timeout_cb, 5.5, 0.); |
|
|
105 | ev_timer_start (loop, &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 |
114 | the beginning of 1970, details are complicated, don't ask). This type is |
156 | 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 |
157 | 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 |
158 | 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> |
159 | it, 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 |
… | |
… | |
181 | might be supported on the current system, you would need to look at |
219 | might be supported on the current system, you would need to look at |
182 | <code>ev_embeddable_backends () & ev_supported_backends ()</code>, likewise for |
220 | <code>ev_embeddable_backends () & ev_supported_backends ()</code>, likewise for |
183 | recommended ones.</p> |
221 | recommended 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 |
189 | realloc C function, the semantics are identical). It is used to allocate |
227 | identical to the realloc C function). It is used to allocate and free |
190 | and free memory (no surprises here). If it returns zero when memory |
228 | memory (no surprises here). If it returns zero when memory needs to be |
191 | needs to be allocated, the library might abort or take some potentially |
229 | allocated, the library might abort or take some potentially destructive |
192 | destructive action. The default is your system realloc function.</p> |
230 | action. 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, |
194 | free some memory if it cannot allocate memory, to use a special allocator, |
232 | free some memory if it cannot allocate memory, to use a special allocator, |
195 | or even to sleep a while and retry until some memory is available.</p> |
233 | or 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 |
197 | retries: better than mine).</p> |
235 | retries: 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 | |
… | |
… | |
606 | received events. Callbacks of both watcher types can start and stop as |
644 | 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 |
645 | 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 |
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 |
614 | happen because the watcher could not be properly started because libev |
661 | 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 |
662 | ran out of memory, a file descriptor was found to be closed or any other |
… | |
… | |
1472 | apropriate way for embedded loops.</p> |
1519 | apropriate 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 |
|
|
1535 | whoever 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 |
|
|
1537 | event loop blocks next and before <code>ev_check</code> watchers are being called, |
|
|
1538 | and 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 |
|
|
1540 | handlers 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 |
|
|
1545 | kind. There is a <code>ev_fork_set</code> macro, but using it is utterly pointless, |
|
|
1546 | believe me.</p> |
1477 | </dd> |
1547 | </dd> |
1478 | </dl> |
1548 | </dl> |
1479 | |
1549 | |
1480 | |
1550 | |
1481 | |
1551 | |
… | |
… | |
1631 | </dd> |
1701 | </dd> |
1632 | <dt>w->sweep () <code>ev::embed</code> only</dt> |
1702 | <dt>w->sweep () <code>ev::embed</code> only</dt> |
1633 | <dd> |
1703 | <dd> |
1634 | <p>Invokes <code>ev_embed_sweep</code>.</p> |
1704 | <p>Invokes <code>ev_embed_sweep</code>.</p> |
1635 | </dd> |
1705 | </dd> |
|
|
1706 | <dt>w->update () <code>ev::stat</code> only</dt> |
|
|
1707 | <dd> |
|
|
1708 | <p>Invokes <code>ev_stat_stat</code>.</p> |
|
|
1709 | </dd> |
1636 | </dl> |
1710 | </dl> |
1637 | </p> |
1711 | </p> |
1638 | </dd> |
1712 | </dd> |
1639 | </dl> |
1713 | </dl> |
1640 | <p>Example: Define a class with an IO and idle watcher, start one of them in |
1714 | <p>Example: Define a class with an IO and idle watcher, start one of them in |
… | |
… | |
1651 | : io (this, &myclass::io_cb), |
1725 | : io (this, &myclass::io_cb), |
1652 | idle (this, &myclass::idle_cb) |
1726 | idle (this, &myclass::idle_cb) |
1653 | { |
1727 | { |
1654 | io.start (fd, ev::READ); |
1728 | io.start (fd, ev::READ); |
1655 | } |
1729 | } |
|
|
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 |
|
|
1741 | callbacks 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 |
|
|
1743 | following 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 ("ev |
|
|
1748 | loop argument"). 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, |
|
|
1756 | which 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 ("ev |
|
|
1761 | loop parameter"). 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 |
|
|
1771 | suitable 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 |
|
|
1776 | loop, if multiple loops are supported ("ev loop default").</p> |
|
|
1777 | </dd> |
|
|
1778 | </dl> |
|
|
1779 | <p>Example: Declare and initialise a check watcher, working regardless of |
|
|
1780 | wether 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 (&check, check_cb); |
|
|
1789 | ev_check_start (EV_DEFAULT_ &check); |
|
|
1790 | ev_loop (EV_DEFAULT_ 0); |
|
|
1791 | |
|
|
1792 | |
|
|
1793 | |
1656 | |
1794 | |
1657 | </pre> |
1795 | </pre> |
1658 | |
1796 | |
1659 | </div> |
1797 | </div> |
1660 | <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> |
… | |
… | |
1887 | <dt>EV_STAT_ENABLE</dt> |
2025 | <dt>EV_STAT_ENABLE</dt> |
1888 | <dd> |
2026 | <dd> |
1889 | <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 |
1890 | defined to be <code>0</code>, then they are not.</p> |
2028 | defined to be <code>0</code>, then they are not.</p> |
1891 | </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 |
|
|
2033 | defined to be <code>0</code>, then they are not.</p> |
|
|
2034 | </dd> |
1892 | <dt>EV_MINIMAL</dt> |
2035 | <dt>EV_MINIMAL</dt> |
1893 | <dd> |
2036 | <dd> |
1894 | <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 |
1895 | speed, define this symbol to <code>1</code>. Currently only used for gcc to override |
2038 | speed, define this symbol to <code>1</code>. Currently only used for gcc to override |
1896 | some inlining decisions, saves roughly 30% codesize of amd64.</p> |
2039 | some 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 |
|
|
2044 | pid. The default size is <code>16</code> (or <code>1</code> with <code>EV_MINIMAL</code>), usually more |
|
|
2045 | than enough. If you need to manage thousands of children you might want to |
|
|
2046 | increase this value.</p> |
1897 | </dd> |
2047 | </dd> |
1898 | <dt>EV_COMMON</dt> |
2048 | <dt>EV_COMMON</dt> |
1899 | <dd> |
2049 | <dd> |
1900 | <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 |
1901 | this macro to a something else you can include more and other types of |
2051 | this macro to a something else you can include more and other types of |