… | |
… | |
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 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> |
… | |
… | |
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 | |
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 |
127 | library in any way.</p> |
125 | library in any way.</p> |
… | |
… | |
181 | might be supported on the current system, you would need to look at |
179 | might be supported on the current system, you would need to look at |
182 | <code>ev_embeddable_backends () & ev_supported_backends ()</code>, likewise for |
180 | <code>ev_embeddable_backends () & ev_supported_backends ()</code>, likewise for |
183 | recommended ones.</p> |
181 | recommended 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 |
189 | realloc C function, the semantics are identical). It is used to allocate |
187 | 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 |
188 | 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 |
189 | allocated, the library might abort or take some potentially destructive |
192 | destructive action. The default is your system realloc function.</p> |
190 | action. 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, |
194 | free some memory if it cannot allocate memory, to use a special allocator, |
192 | 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> |
193 | 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 |
194 | <p>Example: replace the libev allocator with one that waits a bit and then |
197 | retries: better than mine).</p> |
195 | retries: 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 | |
… | |
… | |
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"> |
… | |
… | |
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 |
1894 | defined to be <code>0</code>, then they are not.</p> |
1988 | defined to be <code>0</code>, then they are not.</p> |
1895 | </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 |
|
|
1993 | defined to be <code>0</code>, then they are not.</p> |
|
|
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 |
1899 | speed, define this symbol to <code>1</code>. Currently only used for gcc to override |
1998 | speed, define this symbol to <code>1</code>. Currently only used for gcc to override |
1900 | some inlining decisions, saves roughly 30% codesize of amd64.</p> |
1999 | some 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 |
|
|
2004 | pid. The default size is <code>16</code> (or <code>1</code> with <code>EV_MINIMAL</code>), usually more |
|
|
2005 | than enough. If you need to manage thousands of children you might want to |
|
|
2006 | increase this value.</p> |
1901 | </dd> |
2007 | </dd> |
1902 | <dt>EV_COMMON</dt> |
2008 | <dt>EV_COMMON</dt> |
1903 | <dd> |
2009 | <dd> |
1904 | <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 |
1905 | this macro to a something else you can include more and other types of |
2011 | this macro to a something else you can include more and other types of |