… | |
… | |
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 21:26:46 2007" /> |
9 | <meta name="created" content="Tue Nov 27 21:29:04 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 --> |
… | |
… | |
60 | <li><a href="#AUTHOR">AUTHOR</a> |
60 | <li><a href="#AUTHOR">AUTHOR</a> |
61 | </li> |
61 | </li> |
62 | </ul><hr /> |
62 | </ul><hr /> |
63 | <!-- INDEX END --> |
63 | <!-- INDEX END --> |
64 | |
64 | |
65 | <h1 id="NAME">NAME</h1><p><a href="#TOP" class="toplink">Top</a></p> |
65 | <h1 id="NAME">NAME</h1> |
66 | <div id="NAME_CONTENT"> |
66 | <div id="NAME_CONTENT"> |
67 | <p>libev - a high performance full-featured event loop written in C</p> |
67 | <p>libev - a high performance full-featured event loop written in C</p> |
68 | |
68 | |
69 | </div> |
69 | </div> |
70 | <h1 id="SYNOPSIS">SYNOPSIS</h1><p><a href="#TOP" class="toplink">Top</a></p> |
70 | <h1 id="SYNOPSIS">SYNOPSIS</h1> |
71 | <div id="SYNOPSIS_CONTENT"> |
71 | <div id="SYNOPSIS_CONTENT"> |
72 | <pre> #include <ev.h> |
72 | <pre> #include <ev.h> |
73 | |
73 | |
74 | </pre> |
74 | </pre> |
75 | |
75 | |
76 | </div> |
76 | </div> |
77 | <h1 id="EXAMPLE_PROGRAM">EXAMPLE PROGRAM</h1><p><a href="#TOP" class="toplink">Top</a></p> |
77 | <h1 id="EXAMPLE_PROGRAM">EXAMPLE PROGRAM</h1> |
78 | <div id="EXAMPLE_PROGRAM_CONTENT"> |
78 | <div id="EXAMPLE_PROGRAM_CONTENT"> |
79 | <pre> #include <ev.h> |
79 | <pre> #include <ev.h> |
80 | |
80 | |
81 | ev_io stdin_watcher; |
81 | ev_io stdin_watcher; |
82 | ev_timer timeout_watcher; |
82 | ev_timer timeout_watcher; |
… | |
… | |
117 | } |
117 | } |
118 | |
118 | |
119 | </pre> |
119 | </pre> |
120 | |
120 | |
121 | </div> |
121 | </div> |
122 | <h1 id="DESCRIPTION">DESCRIPTION</h1><p><a href="#TOP" class="toplink">Top</a></p> |
122 | <h1 id="DESCRIPTION">DESCRIPTION</h1> |
123 | <div id="DESCRIPTION_CONTENT"> |
123 | <div id="DESCRIPTION_CONTENT"> |
124 | <p>Libev is an event loop: you register interest in certain events (such as a |
124 | <p>Libev is an event loop: you register interest in certain events (such as a |
125 | file descriptor being readable or a timeout occuring), and it will manage |
125 | file descriptor being readable or a timeout occuring), and it will manage |
126 | these event sources and provide your program with events.</p> |
126 | these event sources and provide your program with events.</p> |
127 | <p>To do this, it must take more or less complete control over your process |
127 | <p>To do this, it must take more or less complete control over your process |
… | |
… | |
131 | watchers</i>, which are relatively small C structures you initialise with the |
131 | watchers</i>, which are relatively small C structures you initialise with the |
132 | details of the event, and then hand it over to libev by <i>starting</i> the |
132 | details of the event, and then hand it over to libev by <i>starting</i> the |
133 | watcher.</p> |
133 | watcher.</p> |
134 | |
134 | |
135 | </div> |
135 | </div> |
136 | <h1 id="FEATURES">FEATURES</h1><p><a href="#TOP" class="toplink">Top</a></p> |
136 | <h1 id="FEATURES">FEATURES</h1> |
137 | <div id="FEATURES_CONTENT"> |
137 | <div id="FEATURES_CONTENT"> |
138 | <p>Libev supports <code>select</code>, <code>poll</code>, the linux-specific <code>epoll</code>, the |
138 | <p>Libev supports <code>select</code>, <code>poll</code>, the linux-specific <code>epoll</code>, the |
139 | bsd-specific <code>kqueue</code> and the solaris-specific event port mechanisms |
139 | bsd-specific <code>kqueue</code> and the solaris-specific event port mechanisms |
140 | for file descriptor events (<code>ev_io</code>), relative timers (<code>ev_timer</code>), |
140 | for file descriptor events (<code>ev_io</code>), relative timers (<code>ev_timer</code>), |
141 | absolute timers with customised rescheduling (<code>ev_periodic</code>), synchronous |
141 | absolute timers with customised rescheduling (<code>ev_periodic</code>), synchronous |
… | |
… | |
147 | <p>It also is quite fast (see this |
147 | <p>It also is quite fast (see this |
148 | <a href="http://libev.schmorp.de/bench.html">benchmark</a> comparing it to libevent |
148 | <a href="http://libev.schmorp.de/bench.html">benchmark</a> comparing it to libevent |
149 | for example).</p> |
149 | for example).</p> |
150 | |
150 | |
151 | </div> |
151 | </div> |
152 | <h1 id="CONVENTIONS">CONVENTIONS</h1><p><a href="#TOP" class="toplink">Top</a></p> |
152 | <h1 id="CONVENTIONS">CONVENTIONS</h1> |
153 | <div id="CONVENTIONS_CONTENT"> |
153 | <div id="CONVENTIONS_CONTENT"> |
154 | <p>Libev is very configurable. In this manual the default configuration will |
154 | <p>Libev is very configurable. In this manual the default configuration will |
155 | be described, which supports multiple event loops. For more info about |
155 | be described, which supports multiple event loops. For more info about |
156 | various configuration options please have a look at <strong>EMBED</strong> section in |
156 | various configuration options please have a look at <strong>EMBED</strong> section in |
157 | this manual. If libev was configured without support for multiple event |
157 | this manual. If libev was configured without support for multiple event |
158 | loops, then all functions taking an initial argument of name <code>loop</code> |
158 | loops, then all functions taking an initial argument of name <code>loop</code> |
159 | (which is always of type <code>struct ev_loop *</code>) will not have this argument.</p> |
159 | (which is always of type <code>struct ev_loop *</code>) will not have this argument.</p> |
160 | |
160 | |
161 | </div> |
161 | </div> |
162 | <h1 id="TIME_REPRESENTATION">TIME REPRESENTATION</h1><p><a href="#TOP" class="toplink">Top</a></p> |
162 | <h1 id="TIME_REPRESENTATION">TIME REPRESENTATION</h1> |
163 | <div id="TIME_REPRESENTATION_CONTENT"> |
163 | <div id="TIME_REPRESENTATION_CONTENT"> |
164 | <p>Libev represents time as a single floating point number, representing the |
164 | <p>Libev represents time as a single floating point number, representing the |
165 | (fractional) number of seconds since the (POSIX) epoch (somewhere near |
165 | (fractional) number of seconds since the (POSIX) epoch (somewhere near |
166 | the beginning of 1970, details are complicated, don't ask). This type is |
166 | the beginning of 1970, details are complicated, don't ask). This type is |
167 | called <code>ev_tstamp</code>, which is what you should use too. It usually aliases |
167 | called <code>ev_tstamp</code>, which is what you should use too. It usually aliases |
168 | to the <code>double</code> type in C, and when you need to do any calculations on |
168 | to the <code>double</code> type in C, and when you need to do any calculations on |
169 | it, you should treat it as such.</p> |
169 | it, you should treat it as such.</p> |
170 | |
170 | |
171 | </div> |
171 | </div> |
172 | <h1 id="GLOBAL_FUNCTIONS">GLOBAL FUNCTIONS</h1><p><a href="#TOP" class="toplink">Top</a></p> |
172 | <h1 id="GLOBAL_FUNCTIONS">GLOBAL FUNCTIONS</h1> |
173 | <div id="GLOBAL_FUNCTIONS_CONTENT"> |
173 | <div id="GLOBAL_FUNCTIONS_CONTENT"> |
174 | <p>These functions can be called anytime, even before initialising the |
174 | <p>These functions can be called anytime, even before initialising the |
175 | library in any way.</p> |
175 | library in any way.</p> |
176 | <dl> |
176 | <dl> |
177 | <dt>ev_tstamp ev_time ()</dt> |
177 | <dt>ev_tstamp ev_time ()</dt> |
… | |
… | |
285 | </pre> |
285 | </pre> |
286 | </dd> |
286 | </dd> |
287 | </dl> |
287 | </dl> |
288 | |
288 | |
289 | </div> |
289 | </div> |
290 | <h1 id="FUNCTIONS_CONTROLLING_THE_EVENT_LOOP">FUNCTIONS CONTROLLING THE EVENT LOOP</h1><p><a href="#TOP" class="toplink">Top</a></p> |
290 | <h1 id="FUNCTIONS_CONTROLLING_THE_EVENT_LOOP">FUNCTIONS CONTROLLING THE EVENT LOOP</h1> |
291 | <div id="FUNCTIONS_CONTROLLING_THE_EVENT_LOOP-2"> |
291 | <div id="FUNCTIONS_CONTROLLING_THE_EVENT_LOOP-2"> |
292 | <p>An event loop is described by a <code>struct ev_loop *</code>. The library knows two |
292 | <p>An event loop is described by a <code>struct ev_loop *</code>. The library knows two |
293 | types of such loops, the <i>default</i> loop, which supports signals and child |
293 | types of such loops, the <i>default</i> loop, which supports signals and child |
294 | events, and dynamically created loops which do not.</p> |
294 | events, and dynamically created loops which do not.</p> |
295 | <p>If you use threads, a common model is to run the default event loop |
295 | <p>If you use threads, a common model is to run the default event loop |
… | |
… | |
568 | |
568 | |
569 | |
569 | |
570 | |
570 | |
571 | |
571 | |
572 | </div> |
572 | </div> |
573 | <h1 id="ANATOMY_OF_A_WATCHER">ANATOMY OF A WATCHER</h1><p><a href="#TOP" class="toplink">Top</a></p> |
573 | <h1 id="ANATOMY_OF_A_WATCHER">ANATOMY OF A WATCHER</h1> |
574 | <div id="ANATOMY_OF_A_WATCHER_CONTENT"> |
574 | <div id="ANATOMY_OF_A_WATCHER_CONTENT"> |
575 | <p>A watcher is a structure that you create and register to record your |
575 | <p>A watcher is a structure that you create and register to record your |
576 | interest in some event. For instance, if you want to wait for STDIN to |
576 | interest in some event. For instance, if you want to wait for STDIN to |
577 | become readable, you would create an <code>ev_io</code> watcher for that:</p> |
577 | become readable, you would create an <code>ev_io</code> watcher for that:</p> |
578 | <pre> static void my_cb (struct ev_loop *loop, struct ev_io *w, int revents) |
578 | <pre> static void my_cb (struct ev_loop *loop, struct ev_io *w, int revents) |
… | |
… | |
791 | |
791 | |
792 | |
792 | |
793 | |
793 | |
794 | |
794 | |
795 | </div> |
795 | </div> |
796 | <h1 id="WATCHER_TYPES">WATCHER TYPES</h1><p><a href="#TOP" class="toplink">Top</a></p> |
796 | <h1 id="WATCHER_TYPES">WATCHER TYPES</h1> |
797 | <div id="WATCHER_TYPES_CONTENT"> |
797 | <div id="WATCHER_TYPES_CONTENT"> |
798 | <p>This section describes each watcher in detail, but will not repeat |
798 | <p>This section describes each watcher in detail, but will not repeat |
799 | information given in the last section. Any initialisation/set macros, |
799 | information given in the last section. Any initialisation/set macros, |
800 | functions and members specific to the watcher type are explained.</p> |
800 | functions and members specific to the watcher type are explained.</p> |
801 | <p>Members are additionally marked with either <i>[read-only]</i>, meaning that, |
801 | <p>Members are additionally marked with either <i>[read-only]</i>, meaning that, |
… | |
… | |
1560 | |
1560 | |
1561 | |
1561 | |
1562 | |
1562 | |
1563 | |
1563 | |
1564 | </div> |
1564 | </div> |
1565 | <h1 id="OTHER_FUNCTIONS">OTHER FUNCTIONS</h1><p><a href="#TOP" class="toplink">Top</a></p> |
1565 | <h1 id="OTHER_FUNCTIONS">OTHER FUNCTIONS</h1> |
1566 | <div id="OTHER_FUNCTIONS_CONTENT"> |
1566 | <div id="OTHER_FUNCTIONS_CONTENT"> |
1567 | <p>There are some other functions of possible interest. Described. Here. Now.</p> |
1567 | <p>There are some other functions of possible interest. Described. Here. Now.</p> |
1568 | <dl> |
1568 | <dl> |
1569 | <dt>ev_once (loop, int fd, int events, ev_tstamp timeout, callback)</dt> |
1569 | <dt>ev_once (loop, int fd, int events, ev_tstamp timeout, callback)</dt> |
1570 | <dd> |
1570 | <dd> |
… | |
… | |
1617 | |
1617 | |
1618 | |
1618 | |
1619 | |
1619 | |
1620 | |
1620 | |
1621 | </div> |
1621 | </div> |
1622 | <h1 id="LIBEVENT_EMULATION">LIBEVENT EMULATION</h1><p><a href="#TOP" class="toplink">Top</a></p> |
1622 | <h1 id="LIBEVENT_EMULATION">LIBEVENT EMULATION</h1> |
1623 | <div id="LIBEVENT_EMULATION_CONTENT"> |
1623 | <div id="LIBEVENT_EMULATION_CONTENT"> |
1624 | <p>Libev offers a compatibility emulation layer for libevent. It cannot |
1624 | <p>Libev offers a compatibility emulation layer for libevent. It cannot |
1625 | emulate the internals of libevent, so here are some usage hints:</p> |
1625 | emulate the internals of libevent, so here are some usage hints:</p> |
1626 | <dl> |
1626 | <dl> |
1627 | <dt>* Use it by including <event.h>, as usual.</dt> |
1627 | <dt>* Use it by including <event.h>, as usual.</dt> |
… | |
… | |
1637 | <dt>* The libev emulation is <i>not</i> ABI compatible to libevent, you need |
1637 | <dt>* The libev emulation is <i>not</i> ABI compatible to libevent, you need |
1638 | to use the libev header file and library.</dt> |
1638 | to use the libev header file and library.</dt> |
1639 | </dl> |
1639 | </dl> |
1640 | |
1640 | |
1641 | </div> |
1641 | </div> |
1642 | <h1 id="C_SUPPORT">C++ SUPPORT</h1><p><a href="#TOP" class="toplink">Top</a></p> |
1642 | <h1 id="C_SUPPORT">C++ SUPPORT</h1> |
1643 | <div id="C_SUPPORT_CONTENT"> |
1643 | <div id="C_SUPPORT_CONTENT"> |
1644 | <p>Libev comes with some simplistic wrapper classes for C++ that mainly allow |
1644 | <p>Libev comes with some simplistic wrapper classes for C++ that mainly allow |
1645 | you to use some convinience methods to start/stop watchers and also change |
1645 | you to use some convinience methods to start/stop watchers and also change |
1646 | the callback model to a model using method callbacks on objects.</p> |
1646 | the callback model to a model using method callbacks on objects.</p> |
1647 | <p>To use it,</p> |
1647 | <p>To use it,</p> |
… | |
… | |
1742 | |
1742 | |
1743 | |
1743 | |
1744 | </pre> |
1744 | </pre> |
1745 | |
1745 | |
1746 | </div> |
1746 | </div> |
1747 | <h1 id="MACRO_MAGIC">MACRO MAGIC</h1><p><a href="#TOP" class="toplink">Top</a></p> |
1747 | <h1 id="MACRO_MAGIC">MACRO MAGIC</h1> |
1748 | <div id="MACRO_MAGIC_CONTENT"> |
1748 | <div id="MACRO_MAGIC_CONTENT"> |
1749 | <p>Libev can be compiled with a variety of options, the most fundemantal is |
1749 | <p>Libev can be compiled with a variety of options, the most fundemantal is |
1750 | <code>EV_MULTIPLICITY</code>. This option determines wether (most) functions and |
1750 | <code>EV_MULTIPLICITY</code>. This option determines wether (most) functions and |
1751 | callbacks have an initial <code>struct ev_loop *</code> argument.</p> |
1751 | callbacks have an initial <code>struct ev_loop *</code> argument.</p> |
1752 | <p>To make it easier to write programs that cope with either variant, the |
1752 | <p>To make it easier to write programs that cope with either variant, the |
… | |
… | |
1803 | |
1803 | |
1804 | |
1804 | |
1805 | </pre> |
1805 | </pre> |
1806 | |
1806 | |
1807 | </div> |
1807 | </div> |
1808 | <h1 id="EMBEDDING">EMBEDDING</h1><p><a href="#TOP" class="toplink">Top</a></p> |
1808 | <h1 id="EMBEDDING">EMBEDDING</h1> |
1809 | <div id="EMBEDDING_CONTENT"> |
1809 | <div id="EMBEDDING_CONTENT"> |
1810 | <p>Libev can (and often is) directly embedded into host |
1810 | <p>Libev can (and often is) directly embedded into host |
1811 | applications. Examples of applications that embed it include the Deliantra |
1811 | applications. Examples of applications that embed it include the Deliantra |
1812 | Game Server, the EV perl module, the GNU Virtual Private Ethernet (gvpe) |
1812 | Game Server, the EV perl module, the GNU Virtual Private Ethernet (gvpe) |
1813 | and rxvt-unicode.</p> |
1813 | and rxvt-unicode.</p> |
… | |
… | |
2107 | |
2107 | |
2108 | |
2108 | |
2109 | </pre> |
2109 | </pre> |
2110 | |
2110 | |
2111 | </div> |
2111 | </div> |
2112 | <h1 id="COMPLEXITIES">COMPLEXITIES</h1><p><a href="#TOP" class="toplink">Top</a></p> |
2112 | <h1 id="COMPLEXITIES">COMPLEXITIES</h1> |
2113 | <div id="COMPLEXITIES_CONTENT"> |
2113 | <div id="COMPLEXITIES_CONTENT"> |
2114 | <p>In this section the complexities of (many of) the algorithms used inside |
2114 | <p>In this section the complexities of (many of) the algorithms used inside |
2115 | libev will be explained. For complexity discussions about backends see the |
2115 | libev will be explained. For complexity discussions about backends see the |
2116 | documentation for <code>ev_default_init</code>.</p> |
2116 | documentation for <code>ev_default_init</code>.</p> |
2117 | <p> |
2117 | <p> |
… | |
… | |
2130 | |
2130 | |
2131 | |
2131 | |
2132 | |
2132 | |
2133 | |
2133 | |
2134 | </div> |
2134 | </div> |
2135 | <h1 id="AUTHOR">AUTHOR</h1><p><a href="#TOP" class="toplink">Top</a></p> |
2135 | <h1 id="AUTHOR">AUTHOR</h1> |
2136 | <div id="AUTHOR_CONTENT"> |
2136 | <div id="AUTHOR_CONTENT"> |
2137 | <p>Marc Lehmann <libev@schmorp.de>.</p> |
2137 | <p>Marc Lehmann <libev@schmorp.de>.</p> |
2138 | |
2138 | |
2139 | </div> |
2139 | </div> |
2140 | </div></body> |
2140 | </div></body> |