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

Comparing libev/ev.html (file contents):
Revision 1.1 by root, Mon Nov 12 07:58:13 2007 UTC vs.
Revision 1.7 by root, Mon Nov 12 08:16:02 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="Mon Nov 12 08:58:02 2007" /> 9 <meta name="created" content="Mon Nov 12 09:16:01 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 -->
… …
26</ul> 26</ul>
27</li> 27</li>
28<li><a href="#WATCHER_TYPES">WATCHER TYPES</a> 28<li><a href="#WATCHER_TYPES">WATCHER TYPES</a>
29<ul><li><a href="#struct_ev_io_is_my_file_descriptor_r">struct ev_io - is my file descriptor readable or writable</a></li> 29<ul><li><a href="#struct_ev_io_is_my_file_descriptor_r">struct ev_io - is my file descriptor readable or writable</a></li>
30<li><a href="#struct_ev_timer_relative_and_optiona">struct ev_timer - relative and optionally recurring timeouts</a></li> 30<li><a href="#struct_ev_timer_relative_and_optiona">struct ev_timer - relative and optionally recurring timeouts</a></li>
31<li><a href="#ev_periodic">ev_periodic</a></li> 31<li><a href="#ev_periodic_to_cron_or_not_to_cron_i">ev_periodic - to cron or not to cron it</a></li>
32<li><a href="#ev_signal_signal_me_when_a_signal_ge">ev_signal - signal me when a signal gets signalled</a></li> 32<li><a href="#ev_signal_signal_me_when_a_signal_ge">ev_signal - signal me when a signal gets signalled</a></li>
33<li><a href="#ev_child_wait_for_pid_status_changes">ev_child - wait for pid status changes</a></li> 33<li><a href="#ev_child_wait_for_pid_status_changes">ev_child - wait for pid status changes</a></li>
34<li><a href="#ev_idle_when_you_ve_got_nothing_bett">ev_idle - when you've got nothing better to do</a></li> 34<li><a href="#ev_idle_when_you_ve_got_nothing_bett">ev_idle - when you've got nothing better to do</a></li>
35<li><a href="#prepare_and_check_your_hooks_into_th">prepare and check - your hooks into the event loop</a></li> 35<li><a href="#prepare_and_check_your_hooks_into_th">prepare and check - your hooks into the event loop</a></li>
36</ul> 36</ul>
… …
55</div> 55</div>
56<h1 id="DESCRIPTION">DESCRIPTION</h1><p><a href="#TOP" class="toplink">Top</a></p> 56<h1 id="DESCRIPTION">DESCRIPTION</h1><p><a href="#TOP" class="toplink">Top</a></p>
57<div id="DESCRIPTION_CONTENT"> 57<div id="DESCRIPTION_CONTENT">
58<p>Libev is an event loop: you register interest in certain events (such as a 58<p>Libev is an event loop: you register interest in certain events (such as a
59file descriptor being readable or a timeout occuring), and it will manage 59file descriptor being readable or a timeout occuring), and it will manage
60these event sources and provide your program events.</p> 60these event sources and provide your program with events.</p>
61<p>To do this, it must take more or less complete control over your process 61<p>To do this, it must take more or less complete control over your process
62(or thread) by executing the <i>event loop</i> handler, and will then 62(or thread) by executing the <i>event loop</i> handler, and will then
63communicate events via a callback mechanism.</p> 63communicate events via a callback mechanism.</p>
64<p>You register interest in certain events by registering so-called <i>event 64<p>You register interest in certain events by registering so-called <i>event
65watchers</i>, which are relatively small C structures you initialise with the 65watchers</i>, which are relatively small C structures you initialise with the
… …
71<div id="FEATURES_CONTENT"> 71<div id="FEATURES_CONTENT">
72<p>Libev supports select, poll, the linux-specific epoll and the bsd-specific 72<p>Libev supports select, poll, the linux-specific epoll and the bsd-specific
73kqueue mechanisms for file descriptor events, relative timers, absolute 73kqueue mechanisms for file descriptor events, relative timers, absolute
74timers with customised rescheduling, signal events, process status change 74timers with customised rescheduling, signal events, process status change
75events (related to SIGCHLD), and event watchers dealing with the event 75events (related to SIGCHLD), and event watchers dealing with the event
76loop mechanism itself (idle, prepare and check watchers).</p> 76loop mechanism itself (idle, prepare and check watchers). It also is quite
77fast (see this <a href="http://libev.schmorp.de/bench.html">benchmark</a> comparing
78it to libevent for example).</p>
77 79
78</div> 80</div>
79<h1 id="CONVENTIONS">CONVENTIONS</h1><p><a href="#TOP" class="toplink">Top</a></p> 81<h1 id="CONVENTIONS">CONVENTIONS</h1><p><a href="#TOP" class="toplink">Top</a></p>
80<div id="CONVENTIONS_CONTENT"> 82<div id="CONVENTIONS_CONTENT">
81<p>Libev is very configurable. In this manual the default configuration 83<p>Libev is very configurable. In this manual the default configuration
82will be described, which supports multiple event loops. For more info 84will be described, which supports multiple event loops. For more info
83about various configuraiton options please have a look at the file 85about various configuration options please have a look at the file
84<cite>README.embed</cite> in the libev distribution. If libev was configured without 86<cite>README.embed</cite> in the libev distribution. If libev was configured without
85support for multiple event loops, then all functions taking an initial 87support for multiple event loops, then all functions taking an initial
86argument of name <code>loop</code> (which is always of type <code>struct ev_loop *</code>) 88argument of name <code>loop</code> (which is always of type <code>struct ev_loop *</code>)
87will not have this argument.</p> 89will not have this argument.</p>
88 90
89</div> 91</div>
90<h1 id="TIME_AND_OTHER_GLOBAL_FUNCTIONS">TIME AND OTHER GLOBAL FUNCTIONS</h1><p><a href="#TOP" class="toplink">Top</a></p> 92<h1 id="TIME_AND_OTHER_GLOBAL_FUNCTIONS">TIME AND OTHER GLOBAL FUNCTIONS</h1><p><a href="#TOP" class="toplink">Top</a></p>
91<div id="TIME_AND_OTHER_GLOBAL_FUNCTIONS_CONT"> 93<div id="TIME_AND_OTHER_GLOBAL_FUNCTIONS_CONT">
92<p>Libev represents time as a single floating point number. This type is 94<p>Libev represents time as a single floating point number, representing the
95(fractional) number of seconds since the (POSIX) epoch (somewhere near
96the beginning of 1970, details are complicated, don't ask). This type is
93called <code>ev_tstamp</code>, which is what you should use too. It usually aliases 97called <code>ev_tstamp</code>, which is what you should use too. It usually aliases
94to the double type in C.</p> 98to the double type in C.</p>
95<dl> 99<dl>
96 <dt>ev_tstamp ev_time ()</dt> 100 <dt>ev_tstamp ev_time ()</dt>
97 <dd> 101 <dd>
… …
111not a problem.</p> 115not a problem.</p>
112 </dd> 116 </dd>
113 <dt>ev_set_allocator (void *(*cb)(void *ptr, long size))</dt> 117 <dt>ev_set_allocator (void *(*cb)(void *ptr, long size))</dt>
114 <dd> 118 <dd>
115 <p>Sets the allocation function to use (the prototype is similar to the 119 <p>Sets the allocation function to use (the prototype is similar to the
116realloc function). It is used to allocate and free memory (no surprises 120realloc C function, the semantics are identical). It is used to allocate
117here). If it returns zero when memory needs to be allocated, the library 121and free memory (no surprises here). If it returns zero when memory
118might abort or take some potentially destructive action. The default is 122needs to be allocated, the library might abort or take some potentially
119your system realloc function.</p> 123destructive action. The default is your system realloc function.</p>
120 <p>You could override this function in high-availability programs to, say, 124 <p>You could override this function in high-availability programs to, say,
121free some memory if it cannot allocate memory, to use a special allocator, 125free some memory if it cannot allocate memory, to use a special allocator,
122or even to sleep a while and retry until some memory is available.</p> 126or even to sleep a while and retry until some memory is available.</p>
123 </dd> 127 </dd>
124 <dt>ev_set_syserr_cb (void (*cb)(const char *msg));</dt> 128 <dt>ev_set_syserr_cb (void (*cb)(const char *msg));</dt>
125 <dd> 129 <dd>
126 <p>Set the callback function to call on a retryable syscall error (such 130 <p>Set the callback function to call on a retryable syscall error (such
127as failed select, poll, epoll_wait). The message is a printable string 131as failed select, poll, epoll_wait). The message is a printable string
128indicating the system call or subsystem causing the problem. If this 132indicating the system call or subsystem causing the problem. If this
129callback is set, then libev will expect it to remedy the sitution, no 133callback is set, then libev will expect it to remedy the sitution, no
130matter what, when it returns. That is, libev will geenrally retry the 134matter what, when it returns. That is, libev will generally retry the
131requested operation, or, if the condition doesn't go away, do bad stuff 135requested operation, or, if the condition doesn't go away, do bad stuff
132(such as abort).</p> 136(such as abort).</p>
133 </dd> 137 </dd>
134</dl> 138</dl>
135 139
… …
139<p>An event loop is described by a <code>struct ev_loop *</code>. The library knows two 143<p>An event loop is described by a <code>struct ev_loop *</code>. The library knows two
140types of such loops, the <i>default</i> loop, which supports signals and child 144types of such loops, the <i>default</i> loop, which supports signals and child
141events, and dynamically created loops which do not.</p> 145events, and dynamically created loops which do not.</p>
142<p>If you use threads, a common model is to run the default event loop 146<p>If you use threads, a common model is to run the default event loop
143in your main thread (or in a separate thrad) and for each thread you 147in your main thread (or in a separate thrad) and for each thread you
144create, you also create another event loop. Libev itself does no lockign 148create, you also create another event loop. Libev itself does no locking
145whatsoever, so if you mix calls to different event loops, make sure you 149whatsoever, so if you mix calls to the same event loop in different
146lock (this is usually a bad idea, though, even if done right).</p> 150threads, make sure you lock (this is usually a bad idea, though, even if
151done correctly, because its hideous and inefficient).</p>
147<dl> 152<dl>
148 <dt>struct ev_loop *ev_default_loop (unsigned int flags)</dt> 153 <dt>struct ev_loop *ev_default_loop (unsigned int flags)</dt>
149 <dd> 154 <dd>
150 <p>This will initialise the default event loop if it hasn't been initialised 155 <p>This will initialise the default event loop if it hasn't been initialised
151yet and return it. If the default loop could not be initialised, returns 156yet and return it. If the default loop could not be initialised, returns
… …
314*)</code>), and you can stop watching for events at any time by calling the 319*)</code>), and you can stop watching for events at any time by calling the
315corresponding stop function (<code>ev_&lt;type&gt;_stop (loop, watcher *)</code>.</p> 320corresponding stop function (<code>ev_&lt;type&gt;_stop (loop, watcher *)</code>.</p>
316<p>As long as your watcher is active (has been started but not stopped) you 321<p>As long as your watcher is active (has been started but not stopped) you
317must not touch the values stored in it. Most specifically you must never 322must not touch the values stored in it. Most specifically you must never
318reinitialise it or call its set method.</p> 323reinitialise it or call its set method.</p>
319<p>You cna check wether an event is active by calling the <code>ev_is_active 324<p>You cna check whether an event is active by calling the <code>ev_is_active
320(watcher *)</code> macro. To see wether an event is outstanding (but the 325(watcher *)</code> macro. To see whether an event is outstanding (but the
321callback for it has not been called yet) you cna use the <code>ev_is_pending 326callback for it has not been called yet) you cna use the <code>ev_is_pending
322(watcher *)</code> macro.</p> 327(watcher *)</code> macro.</p>
323<p>Each and every callback receives the event loop pointer as first, the 328<p>Each and every callback receives the event loop pointer as first, the
324registered watcher structure as second, and a bitset of received events as 329registered watcher structure as second, and a bitset of received events as
325third argument.</p> 330third argument.</p>
… …
420information given in the last section.</p> 425information given in the last section.</p>
421 426
422</div> 427</div>
423<h2 id="struct_ev_io_is_my_file_descriptor_r">struct ev_io - is my file descriptor readable or writable</h2> 428<h2 id="struct_ev_io_is_my_file_descriptor_r">struct ev_io - is my file descriptor readable or writable</h2>
424<div id="struct_ev_io_is_my_file_descriptor_r-2"> 429<div id="struct_ev_io_is_my_file_descriptor_r-2">
425<p>I/O watchers check wether a file descriptor is readable or writable 430<p>I/O watchers check whether a file descriptor is readable or writable
426in each iteration of the event loop (This behaviour is called 431in each iteration of the event loop (This behaviour is called
427level-triggering because you keep receiving events as long as the 432level-triggering because you keep receiving events as long as the
428condition persists. Remember you cna stop the watcher if you don't want to 433condition persists. Remember you cna stop the watcher if you don't want to
429act on the event and neither want to receive future events).</p> 434act on the event and neither want to receive future events).</p>
430<dl> 435<dl>
… …
478the timer, and again will automatically restart it if need be.</p> 483the timer, and again will automatically restart it if need be.</p>
479 </dd> 484 </dd>
480</dl> 485</dl>
481 486
482</div> 487</div>
483<h2 id="ev_periodic">ev_periodic</h2> 488<h2 id="ev_periodic_to_cron_or_not_to_cron_i">ev_periodic - to cron or not to cron it</h2>
484<div id="ev_periodic_CONTENT"> 489<div id="ev_periodic_to_cron_or_not_to_cron_i-2">
485<p>Periodic watchers are also timers of a kind, but they are very versatile 490<p>Periodic watchers are also timers of a kind, but they are very versatile
486(and unfortunately a bit complex).</p> 491(and unfortunately a bit complex).</p>
487<p>Unlike ev_timer's, they are not based on real time (or relative time) 492<p>Unlike ev_timer's, they are not based on real time (or relative time)
488but on wallclock time (absolute time). You can tell a periodic watcher 493but on wallclock time (absolute time). You can tell a periodic watcher
489to trigger &quot;at&quot; some specific point in time. For example, if you tell a 494to trigger &quot;at&quot; some specific point in time. For example, if you tell a

Diff Legend

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