1 |
root |
1.1 |
.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.35 |
2 |
|
|
.\" |
3 |
|
|
.\" Standard preamble: |
4 |
|
|
.\" ======================================================================== |
5 |
|
|
.de Sh \" Subsection heading |
6 |
|
|
.br |
7 |
|
|
.if t .Sp |
8 |
|
|
.ne 5 |
9 |
|
|
.PP |
10 |
|
|
\fB\\$1\fR |
11 |
|
|
.PP |
12 |
|
|
.. |
13 |
|
|
.de Sp \" Vertical space (when we can't use .PP) |
14 |
|
|
.if t .sp .5v |
15 |
|
|
.if n .sp |
16 |
|
|
.. |
17 |
|
|
.de Vb \" Begin verbatim text |
18 |
|
|
.ft CW |
19 |
|
|
.nf |
20 |
|
|
.ne \\$1 |
21 |
|
|
.. |
22 |
|
|
.de Ve \" End verbatim text |
23 |
|
|
.ft R |
24 |
|
|
.fi |
25 |
|
|
.. |
26 |
|
|
.\" Set up some character translations and predefined strings. \*(-- will |
27 |
|
|
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left |
28 |
|
|
.\" double quote, and \*(R" will give a right double quote. | will give a |
29 |
|
|
.\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to |
30 |
|
|
.\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C' |
31 |
|
|
.\" expand to `' in nroff, nothing in troff, for use with C<>. |
32 |
|
|
.tr \(*W-|\(bv\*(Tr |
33 |
|
|
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' |
34 |
|
|
.ie n \{\ |
35 |
|
|
. ds -- \(*W- |
36 |
|
|
. ds PI pi |
37 |
|
|
. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch |
38 |
|
|
. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch |
39 |
|
|
. ds L" "" |
40 |
|
|
. ds R" "" |
41 |
|
|
. ds C` "" |
42 |
|
|
. ds C' "" |
43 |
|
|
'br\} |
44 |
|
|
.el\{\ |
45 |
|
|
. ds -- \|\(em\| |
46 |
|
|
. ds PI \(*p |
47 |
|
|
. ds L" `` |
48 |
|
|
. ds R" '' |
49 |
|
|
'br\} |
50 |
|
|
.\" |
51 |
|
|
.\" If the F register is turned on, we'll generate index entries on stderr for |
52 |
|
|
.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index |
53 |
|
|
.\" entries marked with X<> in POD. Of course, you'll have to process the |
54 |
|
|
.\" output yourself in some meaningful fashion. |
55 |
|
|
.if \nF \{\ |
56 |
|
|
. de IX |
57 |
|
|
. tm Index:\\$1\t\\n%\t"\\$2" |
58 |
|
|
.. |
59 |
|
|
. nr % 0 |
60 |
|
|
. rr F |
61 |
|
|
.\} |
62 |
|
|
.\" |
63 |
|
|
.\" For nroff, turn off justification. Always turn off hyphenation; it makes |
64 |
|
|
.\" way too many mistakes in technical documents. |
65 |
|
|
.hy 0 |
66 |
|
|
.if n .na |
67 |
|
|
.\" |
68 |
|
|
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). |
69 |
|
|
.\" Fear. Run. Save yourself. No user-serviceable parts. |
70 |
|
|
. \" fudge factors for nroff and troff |
71 |
|
|
.if n \{\ |
72 |
|
|
. ds #H 0 |
73 |
|
|
. ds #V .8m |
74 |
|
|
. ds #F .3m |
75 |
|
|
. ds #[ \f1 |
76 |
|
|
. ds #] \fP |
77 |
|
|
.\} |
78 |
|
|
.if t \{\ |
79 |
|
|
. ds #H ((1u-(\\\\n(.fu%2u))*.13m) |
80 |
|
|
. ds #V .6m |
81 |
|
|
. ds #F 0 |
82 |
|
|
. ds #[ \& |
83 |
|
|
. ds #] \& |
84 |
|
|
.\} |
85 |
|
|
. \" simple accents for nroff and troff |
86 |
|
|
.if n \{\ |
87 |
|
|
. ds ' \& |
88 |
|
|
. ds ` \& |
89 |
|
|
. ds ^ \& |
90 |
|
|
. ds , \& |
91 |
|
|
. ds ~ ~ |
92 |
|
|
. ds / |
93 |
|
|
.\} |
94 |
|
|
.if t \{\ |
95 |
|
|
. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" |
96 |
|
|
. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' |
97 |
|
|
. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' |
98 |
|
|
. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' |
99 |
|
|
. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' |
100 |
|
|
. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' |
101 |
|
|
.\} |
102 |
|
|
. \" troff and (daisy-wheel) nroff accents |
103 |
|
|
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' |
104 |
|
|
.ds 8 \h'\*(#H'\(*b\h'-\*(#H' |
105 |
|
|
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] |
106 |
|
|
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' |
107 |
|
|
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' |
108 |
|
|
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] |
109 |
|
|
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] |
110 |
|
|
.ds ae a\h'-(\w'a'u*4/10)'e |
111 |
|
|
.ds Ae A\h'-(\w'A'u*4/10)'E |
112 |
|
|
. \" corrections for vroff |
113 |
|
|
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' |
114 |
|
|
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' |
115 |
|
|
. \" for low resolution devices (crt and lpr) |
116 |
|
|
.if \n(.H>23 .if \n(.V>19 \ |
117 |
|
|
\{\ |
118 |
|
|
. ds : e |
119 |
|
|
. ds 8 ss |
120 |
|
|
. ds o a |
121 |
|
|
. ds d- d\h'-1'\(ga |
122 |
|
|
. ds D- D\h'-1'\(hy |
123 |
|
|
. ds th \o'bp' |
124 |
|
|
. ds Th \o'LP' |
125 |
|
|
. ds ae ae |
126 |
|
|
. ds Ae AE |
127 |
|
|
.\} |
128 |
|
|
.rm #[ #] #H #V #F C |
129 |
|
|
.\" ======================================================================== |
130 |
|
|
.\" |
131 |
|
|
.IX Title ""<STANDARD INPUT>" 1" |
132 |
root |
1.10 |
.TH "<STANDARD INPUT>" 1 "2007-11-24" "perl v5.8.8" "User Contributed Perl Documentation" |
133 |
root |
1.1 |
.SH "NAME" |
134 |
|
|
libev \- a high performance full\-featured event loop written in C |
135 |
|
|
.SH "SYNOPSIS" |
136 |
|
|
.IX Header "SYNOPSIS" |
137 |
|
|
.Vb 1 |
138 |
|
|
\& #include <ev.h> |
139 |
|
|
.Ve |
140 |
|
|
.SH "DESCRIPTION" |
141 |
|
|
.IX Header "DESCRIPTION" |
142 |
|
|
Libev is an event loop: you register interest in certain events (such as a |
143 |
|
|
file descriptor being readable or a timeout occuring), and it will manage |
144 |
|
|
these event sources and provide your program with events. |
145 |
|
|
.PP |
146 |
|
|
To do this, it must take more or less complete control over your process |
147 |
|
|
(or thread) by executing the \fIevent loop\fR handler, and will then |
148 |
|
|
communicate events via a callback mechanism. |
149 |
|
|
.PP |
150 |
|
|
You register interest in certain events by registering so-called \fIevent |
151 |
|
|
watchers\fR, which are relatively small C structures you initialise with the |
152 |
|
|
details of the event, and then hand it over to libev by \fIstarting\fR the |
153 |
|
|
watcher. |
154 |
|
|
.SH "FEATURES" |
155 |
|
|
.IX Header "FEATURES" |
156 |
|
|
Libev supports select, poll, the linux-specific epoll and the bsd-specific |
157 |
|
|
kqueue mechanisms for file descriptor events, relative timers, absolute |
158 |
|
|
timers with customised rescheduling, signal events, process status change |
159 |
|
|
events (related to \s-1SIGCHLD\s0), and event watchers dealing with the event |
160 |
|
|
loop mechanism itself (idle, prepare and check watchers). It also is quite |
161 |
|
|
fast (see this benchmark comparing |
162 |
|
|
it to libevent for example). |
163 |
|
|
.SH "CONVENTIONS" |
164 |
|
|
.IX Header "CONVENTIONS" |
165 |
|
|
Libev is very configurable. In this manual the default configuration |
166 |
|
|
will be described, which supports multiple event loops. For more info |
167 |
|
|
about various configuration options please have a look at the file |
168 |
|
|
\&\fI\s-1README\s0.embed\fR in the libev distribution. If libev was configured without |
169 |
|
|
support for multiple event loops, then all functions taking an initial |
170 |
|
|
argument of name \f(CW\*(C`loop\*(C'\fR (which is always of type \f(CW\*(C`struct ev_loop *\*(C'\fR) |
171 |
|
|
will not have this argument. |
172 |
|
|
.SH "TIME REPRESENTATION" |
173 |
|
|
.IX Header "TIME REPRESENTATION" |
174 |
|
|
Libev represents time as a single floating point number, representing the |
175 |
|
|
(fractional) number of seconds since the (\s-1POSIX\s0) epoch (somewhere near |
176 |
|
|
the beginning of 1970, details are complicated, don't ask). This type is |
177 |
|
|
called \f(CW\*(C`ev_tstamp\*(C'\fR, which is what you should use too. It usually aliases |
178 |
root |
1.9 |
to the \f(CW\*(C`double\*(C'\fR type in C, and when you need to do any calculations on |
179 |
|
|
it, you should treat it as such. |
180 |
root |
1.1 |
.SH "GLOBAL FUNCTIONS" |
181 |
|
|
.IX Header "GLOBAL FUNCTIONS" |
182 |
|
|
These functions can be called anytime, even before initialising the |
183 |
|
|
library in any way. |
184 |
|
|
.IP "ev_tstamp ev_time ()" 4 |
185 |
|
|
.IX Item "ev_tstamp ev_time ()" |
186 |
root |
1.2 |
Returns the current time as libev would use it. Please note that the |
187 |
|
|
\&\f(CW\*(C`ev_now\*(C'\fR function is usually faster and also often returns the timestamp |
188 |
|
|
you actually want to know. |
189 |
root |
1.1 |
.IP "int ev_version_major ()" 4 |
190 |
|
|
.IX Item "int ev_version_major ()" |
191 |
|
|
.PD 0 |
192 |
|
|
.IP "int ev_version_minor ()" 4 |
193 |
|
|
.IX Item "int ev_version_minor ()" |
194 |
|
|
.PD |
195 |
|
|
You can find out the major and minor version numbers of the library |
196 |
|
|
you linked against by calling the functions \f(CW\*(C`ev_version_major\*(C'\fR and |
197 |
|
|
\&\f(CW\*(C`ev_version_minor\*(C'\fR. If you want, you can compare against the global |
198 |
|
|
symbols \f(CW\*(C`EV_VERSION_MAJOR\*(C'\fR and \f(CW\*(C`EV_VERSION_MINOR\*(C'\fR, which specify the |
199 |
|
|
version of the library your program was compiled against. |
200 |
|
|
.Sp |
201 |
|
|
Usually, it's a good idea to terminate if the major versions mismatch, |
202 |
|
|
as this indicates an incompatible change. Minor versions are usually |
203 |
|
|
compatible to older versions, so a larger minor version alone is usually |
204 |
|
|
not a problem. |
205 |
root |
1.9 |
.Sp |
206 |
|
|
Example: make sure we haven't accidentally been linked against the wrong |
207 |
|
|
version: |
208 |
|
|
.Sp |
209 |
|
|
.Vb 3 |
210 |
|
|
\& assert (("libev version mismatch", |
211 |
|
|
\& ev_version_major () == EV_VERSION_MAJOR |
212 |
|
|
\& && ev_version_minor () >= EV_VERSION_MINOR)); |
213 |
|
|
.Ve |
214 |
root |
1.6 |
.IP "unsigned int ev_supported_backends ()" 4 |
215 |
|
|
.IX Item "unsigned int ev_supported_backends ()" |
216 |
|
|
Return the set of all backends (i.e. their corresponding \f(CW\*(C`EV_BACKEND_*\*(C'\fR |
217 |
|
|
value) compiled into this binary of libev (independent of their |
218 |
|
|
availability on the system you are running on). See \f(CW\*(C`ev_default_loop\*(C'\fR for |
219 |
|
|
a description of the set values. |
220 |
root |
1.9 |
.Sp |
221 |
|
|
Example: make sure we have the epoll method, because yeah this is cool and |
222 |
|
|
a must have and can we have a torrent of it please!!!11 |
223 |
|
|
.Sp |
224 |
|
|
.Vb 2 |
225 |
|
|
\& assert (("sorry, no epoll, no sex", |
226 |
|
|
\& ev_supported_backends () & EVBACKEND_EPOLL)); |
227 |
|
|
.Ve |
228 |
root |
1.6 |
.IP "unsigned int ev_recommended_backends ()" 4 |
229 |
|
|
.IX Item "unsigned int ev_recommended_backends ()" |
230 |
|
|
Return the set of all backends compiled into this binary of libev and also |
231 |
|
|
recommended for this platform. This set is often smaller than the one |
232 |
|
|
returned by \f(CW\*(C`ev_supported_backends\*(C'\fR, as for example kqueue is broken on |
233 |
|
|
most BSDs and will not be autodetected unless you explicitly request it |
234 |
|
|
(assuming you know what you are doing). This is the set of backends that |
235 |
root |
1.8 |
libev will probe for if you specify no backends explicitly. |
236 |
root |
1.10 |
.IP "unsigned int ev_embeddable_backends ()" 4 |
237 |
|
|
.IX Item "unsigned int ev_embeddable_backends ()" |
238 |
|
|
Returns the set of backends that are embeddable in other event loops. This |
239 |
|
|
is the theoretical, all\-platform, value. To find which backends |
240 |
|
|
might be supported on the current system, you would need to look at |
241 |
|
|
\&\f(CW\*(C`ev_embeddable_backends () & ev_supported_backends ()\*(C'\fR, likewise for |
242 |
|
|
recommended ones. |
243 |
|
|
.Sp |
244 |
|
|
See the description of \f(CW\*(C`ev_embed\*(C'\fR watchers for more info. |
245 |
root |
1.1 |
.IP "ev_set_allocator (void *(*cb)(void *ptr, long size))" 4 |
246 |
|
|
.IX Item "ev_set_allocator (void *(*cb)(void *ptr, long size))" |
247 |
|
|
Sets the allocation function to use (the prototype is similar to the |
248 |
|
|
realloc C function, the semantics are identical). It is used to allocate |
249 |
|
|
and free memory (no surprises here). If it returns zero when memory |
250 |
|
|
needs to be allocated, the library might abort or take some potentially |
251 |
|
|
destructive action. The default is your system realloc function. |
252 |
|
|
.Sp |
253 |
|
|
You could override this function in high-availability programs to, say, |
254 |
|
|
free some memory if it cannot allocate memory, to use a special allocator, |
255 |
|
|
or even to sleep a while and retry until some memory is available. |
256 |
root |
1.9 |
.Sp |
257 |
|
|
Example: replace the libev allocator with one that waits a bit and then |
258 |
|
|
retries: better than mine). |
259 |
|
|
.Sp |
260 |
|
|
.Vb 6 |
261 |
|
|
\& static void * |
262 |
|
|
\& persistent_realloc (void *ptr, long size) |
263 |
|
|
\& { |
264 |
|
|
\& for (;;) |
265 |
|
|
\& { |
266 |
|
|
\& void *newptr = realloc (ptr, size); |
267 |
|
|
.Ve |
268 |
|
|
.Sp |
269 |
|
|
.Vb 2 |
270 |
|
|
\& if (newptr) |
271 |
|
|
\& return newptr; |
272 |
|
|
.Ve |
273 |
|
|
.Sp |
274 |
|
|
.Vb 3 |
275 |
|
|
\& sleep (60); |
276 |
|
|
\& } |
277 |
|
|
\& } |
278 |
|
|
.Ve |
279 |
|
|
.Sp |
280 |
|
|
.Vb 2 |
281 |
|
|
\& ... |
282 |
|
|
\& ev_set_allocator (persistent_realloc); |
283 |
|
|
.Ve |
284 |
root |
1.1 |
.IP "ev_set_syserr_cb (void (*cb)(const char *msg));" 4 |
285 |
|
|
.IX Item "ev_set_syserr_cb (void (*cb)(const char *msg));" |
286 |
|
|
Set the callback function to call on a retryable syscall error (such |
287 |
|
|
as failed select, poll, epoll_wait). The message is a printable string |
288 |
|
|
indicating the system call or subsystem causing the problem. If this |
289 |
|
|
callback is set, then libev will expect it to remedy the sitution, no |
290 |
|
|
matter what, when it returns. That is, libev will generally retry the |
291 |
|
|
requested operation, or, if the condition doesn't go away, do bad stuff |
292 |
|
|
(such as abort). |
293 |
root |
1.9 |
.Sp |
294 |
|
|
Example: do the same thing as libev does internally: |
295 |
|
|
.Sp |
296 |
|
|
.Vb 6 |
297 |
|
|
\& static void |
298 |
|
|
\& fatal_error (const char *msg) |
299 |
|
|
\& { |
300 |
|
|
\& perror (msg); |
301 |
|
|
\& abort (); |
302 |
|
|
\& } |
303 |
|
|
.Ve |
304 |
|
|
.Sp |
305 |
|
|
.Vb 2 |
306 |
|
|
\& ... |
307 |
|
|
\& ev_set_syserr_cb (fatal_error); |
308 |
|
|
.Ve |
309 |
root |
1.1 |
.SH "FUNCTIONS CONTROLLING THE EVENT LOOP" |
310 |
|
|
.IX Header "FUNCTIONS CONTROLLING THE EVENT LOOP" |
311 |
|
|
An event loop is described by a \f(CW\*(C`struct ev_loop *\*(C'\fR. The library knows two |
312 |
|
|
types of such loops, the \fIdefault\fR loop, which supports signals and child |
313 |
|
|
events, and dynamically created loops which do not. |
314 |
|
|
.PP |
315 |
|
|
If you use threads, a common model is to run the default event loop |
316 |
|
|
in your main thread (or in a separate thread) and for each thread you |
317 |
|
|
create, you also create another event loop. Libev itself does no locking |
318 |
|
|
whatsoever, so if you mix calls to the same event loop in different |
319 |
|
|
threads, make sure you lock (this is usually a bad idea, though, even if |
320 |
|
|
done correctly, because it's hideous and inefficient). |
321 |
|
|
.IP "struct ev_loop *ev_default_loop (unsigned int flags)" 4 |
322 |
|
|
.IX Item "struct ev_loop *ev_default_loop (unsigned int flags)" |
323 |
|
|
This will initialise the default event loop if it hasn't been initialised |
324 |
|
|
yet and return it. If the default loop could not be initialised, returns |
325 |
|
|
false. If it already was initialised it simply returns it (and ignores the |
326 |
root |
1.6 |
flags. If that is troubling you, check \f(CW\*(C`ev_backend ()\*(C'\fR afterwards). |
327 |
root |
1.1 |
.Sp |
328 |
|
|
If you don't know what event loop to use, use the one returned from this |
329 |
|
|
function. |
330 |
|
|
.Sp |
331 |
|
|
The flags argument can be used to specify special behaviour or specific |
332 |
root |
1.8 |
backends to use, and is usually specified as \f(CW0\fR (or \f(CW\*(C`EVFLAG_AUTO\*(C'\fR). |
333 |
root |
1.1 |
.Sp |
334 |
root |
1.8 |
The following flags are supported: |
335 |
root |
1.1 |
.RS 4 |
336 |
|
|
.ie n .IP """EVFLAG_AUTO""" 4 |
337 |
|
|
.el .IP "\f(CWEVFLAG_AUTO\fR" 4 |
338 |
|
|
.IX Item "EVFLAG_AUTO" |
339 |
|
|
The default flags value. Use this if you have no clue (it's the right |
340 |
|
|
thing, believe me). |
341 |
|
|
.ie n .IP """EVFLAG_NOENV""" 4 |
342 |
|
|
.el .IP "\f(CWEVFLAG_NOENV\fR" 4 |
343 |
|
|
.IX Item "EVFLAG_NOENV" |
344 |
|
|
If this flag bit is ored into the flag value (or the program runs setuid |
345 |
|
|
or setgid) then libev will \fInot\fR look at the environment variable |
346 |
|
|
\&\f(CW\*(C`LIBEV_FLAGS\*(C'\fR. Otherwise (the default), this environment variable will |
347 |
|
|
override the flags completely if it is found in the environment. This is |
348 |
|
|
useful to try out specific backends to test their performance, or to work |
349 |
|
|
around bugs. |
350 |
root |
1.6 |
.ie n .IP """EVBACKEND_SELECT"" (value 1, portable select backend)" 4 |
351 |
|
|
.el .IP "\f(CWEVBACKEND_SELECT\fR (value 1, portable select backend)" 4 |
352 |
|
|
.IX Item "EVBACKEND_SELECT (value 1, portable select backend)" |
353 |
root |
1.3 |
This is your standard \fIselect\fR\|(2) backend. Not \fIcompletely\fR standard, as |
354 |
|
|
libev tries to roll its own fd_set with no limits on the number of fds, |
355 |
|
|
but if that fails, expect a fairly low limit on the number of fds when |
356 |
|
|
using this backend. It doesn't scale too well (O(highest_fd)), but its usually |
357 |
|
|
the fastest backend for a low number of fds. |
358 |
root |
1.6 |
.ie n .IP """EVBACKEND_POLL"" (value 2, poll backend, available everywhere except on windows)" 4 |
359 |
|
|
.el .IP "\f(CWEVBACKEND_POLL\fR (value 2, poll backend, available everywhere except on windows)" 4 |
360 |
|
|
.IX Item "EVBACKEND_POLL (value 2, poll backend, available everywhere except on windows)" |
361 |
root |
1.3 |
And this is your standard \fIpoll\fR\|(2) backend. It's more complicated than |
362 |
|
|
select, but handles sparse fds better and has no artificial limit on the |
363 |
|
|
number of fds you can use (except it will slow down considerably with a |
364 |
|
|
lot of inactive fds). It scales similarly to select, i.e. O(total_fds). |
365 |
root |
1.6 |
.ie n .IP """EVBACKEND_EPOLL"" (value 4, Linux)" 4 |
366 |
|
|
.el .IP "\f(CWEVBACKEND_EPOLL\fR (value 4, Linux)" 4 |
367 |
|
|
.IX Item "EVBACKEND_EPOLL (value 4, Linux)" |
368 |
root |
1.3 |
For few fds, this backend is a bit little slower than poll and select, |
369 |
|
|
but it scales phenomenally better. While poll and select usually scale like |
370 |
|
|
O(total_fds) where n is the total number of fds (or the highest fd), epoll scales |
371 |
|
|
either O(1) or O(active_fds). |
372 |
|
|
.Sp |
373 |
|
|
While stopping and starting an I/O watcher in the same iteration will |
374 |
|
|
result in some caching, there is still a syscall per such incident |
375 |
|
|
(because the fd could point to a different file description now), so its |
376 |
|
|
best to avoid that. Also, \fIdup()\fRed file descriptors might not work very |
377 |
|
|
well if you register events for both fds. |
378 |
root |
1.7 |
.Sp |
379 |
|
|
Please note that epoll sometimes generates spurious notifications, so you |
380 |
|
|
need to use non-blocking I/O or other means to avoid blocking when no data |
381 |
|
|
(or space) is available. |
382 |
root |
1.6 |
.ie n .IP """EVBACKEND_KQUEUE"" (value 8, most \s-1BSD\s0 clones)" 4 |
383 |
|
|
.el .IP "\f(CWEVBACKEND_KQUEUE\fR (value 8, most \s-1BSD\s0 clones)" 4 |
384 |
|
|
.IX Item "EVBACKEND_KQUEUE (value 8, most BSD clones)" |
385 |
root |
1.3 |
Kqueue deserves special mention, as at the time of this writing, it |
386 |
|
|
was broken on all BSDs except NetBSD (usually it doesn't work with |
387 |
|
|
anything but sockets and pipes, except on Darwin, where of course its |
388 |
root |
1.8 |
completely useless). For this reason its not being \*(L"autodetected\*(R" |
389 |
|
|
unless you explicitly specify it explicitly in the flags (i.e. using |
390 |
|
|
\&\f(CW\*(C`EVBACKEND_KQUEUE\*(C'\fR). |
391 |
root |
1.3 |
.Sp |
392 |
|
|
It scales in the same way as the epoll backend, but the interface to the |
393 |
|
|
kernel is more efficient (which says nothing about its actual speed, of |
394 |
|
|
course). While starting and stopping an I/O watcher does not cause an |
395 |
|
|
extra syscall as with epoll, it still adds up to four event changes per |
396 |
|
|
incident, so its best to avoid that. |
397 |
root |
1.6 |
.ie n .IP """EVBACKEND_DEVPOLL"" (value 16, Solaris 8)" 4 |
398 |
|
|
.el .IP "\f(CWEVBACKEND_DEVPOLL\fR (value 16, Solaris 8)" 4 |
399 |
|
|
.IX Item "EVBACKEND_DEVPOLL (value 16, Solaris 8)" |
400 |
root |
1.3 |
This is not implemented yet (and might never be). |
401 |
root |
1.6 |
.ie n .IP """EVBACKEND_PORT"" (value 32, Solaris 10)" 4 |
402 |
|
|
.el .IP "\f(CWEVBACKEND_PORT\fR (value 32, Solaris 10)" 4 |
403 |
|
|
.IX Item "EVBACKEND_PORT (value 32, Solaris 10)" |
404 |
root |
1.3 |
This uses the Solaris 10 port mechanism. As with everything on Solaris, |
405 |
|
|
it's really slow, but it still scales very well (O(active_fds)). |
406 |
root |
1.7 |
.Sp |
407 |
|
|
Please note that solaris ports can result in a lot of spurious |
408 |
|
|
notifications, so you need to use non-blocking I/O or other means to avoid |
409 |
|
|
blocking when no data (or space) is available. |
410 |
root |
1.6 |
.ie n .IP """EVBACKEND_ALL""" 4 |
411 |
|
|
.el .IP "\f(CWEVBACKEND_ALL\fR" 4 |
412 |
|
|
.IX Item "EVBACKEND_ALL" |
413 |
root |
1.4 |
Try all backends (even potentially broken ones that wouldn't be tried |
414 |
|
|
with \f(CW\*(C`EVFLAG_AUTO\*(C'\fR). Since this is a mask, you can do stuff such as |
415 |
root |
1.6 |
\&\f(CW\*(C`EVBACKEND_ALL & ~EVBACKEND_KQUEUE\*(C'\fR. |
416 |
root |
1.1 |
.RE |
417 |
|
|
.RS 4 |
418 |
root |
1.3 |
.Sp |
419 |
|
|
If one or more of these are ored into the flags value, then only these |
420 |
|
|
backends will be tried (in the reverse order as given here). If none are |
421 |
|
|
specified, most compiled-in backend will be tried, usually in reverse |
422 |
|
|
order of their flag values :) |
423 |
root |
1.8 |
.Sp |
424 |
|
|
The most typical usage is like this: |
425 |
|
|
.Sp |
426 |
|
|
.Vb 2 |
427 |
|
|
\& if (!ev_default_loop (0)) |
428 |
|
|
\& fatal ("could not initialise libev, bad $LIBEV_FLAGS in environment?"); |
429 |
|
|
.Ve |
430 |
|
|
.Sp |
431 |
|
|
Restrict libev to the select and poll backends, and do not allow |
432 |
|
|
environment settings to be taken into account: |
433 |
|
|
.Sp |
434 |
|
|
.Vb 1 |
435 |
|
|
\& ev_default_loop (EVBACKEND_POLL | EVBACKEND_SELECT | EVFLAG_NOENV); |
436 |
|
|
.Ve |
437 |
|
|
.Sp |
438 |
|
|
Use whatever libev has to offer, but make sure that kqueue is used if |
439 |
|
|
available (warning, breaks stuff, best use only with your own private |
440 |
|
|
event loop and only if you know the \s-1OS\s0 supports your types of fds): |
441 |
|
|
.Sp |
442 |
|
|
.Vb 1 |
443 |
|
|
\& ev_default_loop (ev_recommended_backends () | EVBACKEND_KQUEUE); |
444 |
|
|
.Ve |
445 |
root |
1.1 |
.RE |
446 |
|
|
.IP "struct ev_loop *ev_loop_new (unsigned int flags)" 4 |
447 |
|
|
.IX Item "struct ev_loop *ev_loop_new (unsigned int flags)" |
448 |
|
|
Similar to \f(CW\*(C`ev_default_loop\*(C'\fR, but always creates a new event loop that is |
449 |
|
|
always distinct from the default loop. Unlike the default loop, it cannot |
450 |
|
|
handle signal and child watchers, and attempts to do so will be greeted by |
451 |
|
|
undefined behaviour (or a failed assertion if assertions are enabled). |
452 |
root |
1.9 |
.Sp |
453 |
|
|
Example: try to create a event loop that uses epoll and nothing else. |
454 |
|
|
.Sp |
455 |
|
|
.Vb 3 |
456 |
|
|
\& struct ev_loop *epoller = ev_loop_new (EVBACKEND_EPOLL | EVFLAG_NOENV); |
457 |
|
|
\& if (!epoller) |
458 |
|
|
\& fatal ("no epoll found here, maybe it hides under your chair"); |
459 |
|
|
.Ve |
460 |
root |
1.1 |
.IP "ev_default_destroy ()" 4 |
461 |
|
|
.IX Item "ev_default_destroy ()" |
462 |
|
|
Destroys the default loop again (frees all memory and kernel state |
463 |
|
|
etc.). This stops all registered event watchers (by not touching them in |
464 |
|
|
any way whatsoever, although you cannot rely on this :). |
465 |
|
|
.IP "ev_loop_destroy (loop)" 4 |
466 |
|
|
.IX Item "ev_loop_destroy (loop)" |
467 |
|
|
Like \f(CW\*(C`ev_default_destroy\*(C'\fR, but destroys an event loop created by an |
468 |
|
|
earlier call to \f(CW\*(C`ev_loop_new\*(C'\fR. |
469 |
|
|
.IP "ev_default_fork ()" 4 |
470 |
|
|
.IX Item "ev_default_fork ()" |
471 |
|
|
This function reinitialises the kernel state for backends that have |
472 |
|
|
one. Despite the name, you can call it anytime, but it makes most sense |
473 |
|
|
after forking, in either the parent or child process (or both, but that |
474 |
|
|
again makes little sense). |
475 |
|
|
.Sp |
476 |
root |
1.5 |
You \fImust\fR call this function in the child process after forking if and |
477 |
|
|
only if you want to use the event library in both processes. If you just |
478 |
|
|
fork+exec, you don't have to call it. |
479 |
root |
1.1 |
.Sp |
480 |
|
|
The function itself is quite fast and it's usually not a problem to call |
481 |
|
|
it just in case after a fork. To make this easy, the function will fit in |
482 |
|
|
quite nicely into a call to \f(CW\*(C`pthread_atfork\*(C'\fR: |
483 |
|
|
.Sp |
484 |
|
|
.Vb 1 |
485 |
|
|
\& pthread_atfork (0, 0, ev_default_fork); |
486 |
|
|
.Ve |
487 |
root |
1.6 |
.Sp |
488 |
|
|
At the moment, \f(CW\*(C`EVBACKEND_SELECT\*(C'\fR and \f(CW\*(C`EVBACKEND_POLL\*(C'\fR are safe to use |
489 |
|
|
without calling this function, so if you force one of those backends you |
490 |
|
|
do not need to care. |
491 |
root |
1.1 |
.IP "ev_loop_fork (loop)" 4 |
492 |
|
|
.IX Item "ev_loop_fork (loop)" |
493 |
|
|
Like \f(CW\*(C`ev_default_fork\*(C'\fR, but acts on an event loop created by |
494 |
|
|
\&\f(CW\*(C`ev_loop_new\*(C'\fR. Yes, you have to call this on every allocated event loop |
495 |
|
|
after fork, and how you do this is entirely your own problem. |
496 |
root |
1.6 |
.IP "unsigned int ev_backend (loop)" 4 |
497 |
|
|
.IX Item "unsigned int ev_backend (loop)" |
498 |
|
|
Returns one of the \f(CW\*(C`EVBACKEND_*\*(C'\fR flags indicating the event backend in |
499 |
root |
1.1 |
use. |
500 |
|
|
.IP "ev_tstamp ev_now (loop)" 4 |
501 |
|
|
.IX Item "ev_tstamp ev_now (loop)" |
502 |
|
|
Returns the current \*(L"event loop time\*(R", which is the time the event loop |
503 |
root |
1.9 |
received events and started processing them. This timestamp does not |
504 |
|
|
change as long as callbacks are being processed, and this is also the base |
505 |
|
|
time used for relative timers. You can treat it as the timestamp of the |
506 |
|
|
event occuring (or more correctly, libev finding out about it). |
507 |
root |
1.1 |
.IP "ev_loop (loop, int flags)" 4 |
508 |
|
|
.IX Item "ev_loop (loop, int flags)" |
509 |
|
|
Finally, this is it, the event handler. This function usually is called |
510 |
|
|
after you initialised all your watchers and you want to start handling |
511 |
|
|
events. |
512 |
|
|
.Sp |
513 |
root |
1.8 |
If the flags argument is specified as \f(CW0\fR, it will not return until |
514 |
|
|
either no event watchers are active anymore or \f(CW\*(C`ev_unloop\*(C'\fR was called. |
515 |
root |
1.1 |
.Sp |
516 |
root |
1.9 |
Please note that an explicit \f(CW\*(C`ev_unloop\*(C'\fR is usually better than |
517 |
|
|
relying on all watchers to be stopped when deciding when a program has |
518 |
|
|
finished (especially in interactive programs), but having a program that |
519 |
|
|
automatically loops as long as it has to and no longer by virtue of |
520 |
|
|
relying on its watchers stopping correctly is a thing of beauty. |
521 |
|
|
.Sp |
522 |
root |
1.1 |
A flags value of \f(CW\*(C`EVLOOP_NONBLOCK\*(C'\fR will look for new events, will handle |
523 |
|
|
those events and any outstanding ones, but will not block your process in |
524 |
|
|
case there are no events and will return after one iteration of the loop. |
525 |
|
|
.Sp |
526 |
|
|
A flags value of \f(CW\*(C`EVLOOP_ONESHOT\*(C'\fR will look for new events (waiting if |
527 |
|
|
neccessary) and will handle those and any outstanding ones. It will block |
528 |
|
|
your process until at least one new event arrives, and will return after |
529 |
root |
1.8 |
one iteration of the loop. This is useful if you are waiting for some |
530 |
|
|
external event in conjunction with something not expressible using other |
531 |
|
|
libev watchers. However, a pair of \f(CW\*(C`ev_prepare\*(C'\fR/\f(CW\*(C`ev_check\*(C'\fR watchers is |
532 |
|
|
usually a better approach for this kind of thing. |
533 |
|
|
.Sp |
534 |
|
|
Here are the gory details of what \f(CW\*(C`ev_loop\*(C'\fR does: |
535 |
|
|
.Sp |
536 |
|
|
.Vb 18 |
537 |
|
|
\& * If there are no active watchers (reference count is zero), return. |
538 |
|
|
\& - Queue prepare watchers and then call all outstanding watchers. |
539 |
|
|
\& - If we have been forked, recreate the kernel state. |
540 |
|
|
\& - Update the kernel state with all outstanding changes. |
541 |
|
|
\& - Update the "event loop time". |
542 |
|
|
\& - Calculate for how long to block. |
543 |
|
|
\& - Block the process, waiting for any events. |
544 |
|
|
\& - Queue all outstanding I/O (fd) events. |
545 |
|
|
\& - Update the "event loop time" and do time jump handling. |
546 |
|
|
\& - Queue all outstanding timers. |
547 |
|
|
\& - Queue all outstanding periodics. |
548 |
|
|
\& - If no events are pending now, queue all idle watchers. |
549 |
|
|
\& - Queue all check watchers. |
550 |
|
|
\& - Call all queued watchers in reverse order (i.e. check watchers first). |
551 |
|
|
\& Signals and child watchers are implemented as I/O watchers, and will |
552 |
|
|
\& be handled here by queueing them when their watcher gets executed. |
553 |
|
|
\& - If ev_unloop has been called or EVLOOP_ONESHOT or EVLOOP_NONBLOCK |
554 |
|
|
\& were used, return, otherwise continue with step *. |
555 |
root |
1.2 |
.Ve |
556 |
root |
1.9 |
.Sp |
557 |
|
|
Example: queue some jobs and then loop until no events are outsanding |
558 |
|
|
anymore. |
559 |
|
|
.Sp |
560 |
|
|
.Vb 4 |
561 |
|
|
\& ... queue jobs here, make sure they register event watchers as long |
562 |
|
|
\& ... as they still have work to do (even an idle watcher will do..) |
563 |
|
|
\& ev_loop (my_loop, 0); |
564 |
|
|
\& ... jobs done. yeah! |
565 |
|
|
.Ve |
566 |
root |
1.1 |
.IP "ev_unloop (loop, how)" 4 |
567 |
|
|
.IX Item "ev_unloop (loop, how)" |
568 |
|
|
Can be used to make a call to \f(CW\*(C`ev_loop\*(C'\fR return early (but only after it |
569 |
|
|
has processed all outstanding events). The \f(CW\*(C`how\*(C'\fR argument must be either |
570 |
|
|
\&\f(CW\*(C`EVUNLOOP_ONE\*(C'\fR, which will make the innermost \f(CW\*(C`ev_loop\*(C'\fR call return, or |
571 |
|
|
\&\f(CW\*(C`EVUNLOOP_ALL\*(C'\fR, which will make all nested \f(CW\*(C`ev_loop\*(C'\fR calls return. |
572 |
|
|
.IP "ev_ref (loop)" 4 |
573 |
|
|
.IX Item "ev_ref (loop)" |
574 |
|
|
.PD 0 |
575 |
|
|
.IP "ev_unref (loop)" 4 |
576 |
|
|
.IX Item "ev_unref (loop)" |
577 |
|
|
.PD |
578 |
|
|
Ref/unref can be used to add or remove a reference count on the event |
579 |
|
|
loop: Every watcher keeps one reference, and as long as the reference |
580 |
|
|
count is nonzero, \f(CW\*(C`ev_loop\*(C'\fR will not return on its own. If you have |
581 |
|
|
a watcher you never unregister that should not keep \f(CW\*(C`ev_loop\*(C'\fR from |
582 |
|
|
returning, \fIev_unref()\fR after starting, and \fIev_ref()\fR before stopping it. For |
583 |
|
|
example, libev itself uses this for its internal signal pipe: It is not |
584 |
|
|
visible to the libev user and should not keep \f(CW\*(C`ev_loop\*(C'\fR from exiting if |
585 |
|
|
no event watchers registered by it are active. It is also an excellent |
586 |
|
|
way to do this for generic recurring timers or from within third-party |
587 |
|
|
libraries. Just remember to \fIunref after start\fR and \fIref before stop\fR. |
588 |
root |
1.9 |
.Sp |
589 |
|
|
Example: create a signal watcher, but keep it from keeping \f(CW\*(C`ev_loop\*(C'\fR |
590 |
|
|
running when nothing else is active. |
591 |
|
|
.Sp |
592 |
|
|
.Vb 4 |
593 |
|
|
\& struct dv_signal exitsig; |
594 |
|
|
\& ev_signal_init (&exitsig, sig_cb, SIGINT); |
595 |
|
|
\& ev_signal_start (myloop, &exitsig); |
596 |
|
|
\& evf_unref (myloop); |
597 |
|
|
.Ve |
598 |
|
|
.Sp |
599 |
|
|
Example: for some weird reason, unregister the above signal handler again. |
600 |
|
|
.Sp |
601 |
|
|
.Vb 2 |
602 |
|
|
\& ev_ref (myloop); |
603 |
|
|
\& ev_signal_stop (myloop, &exitsig); |
604 |
|
|
.Ve |
605 |
root |
1.1 |
.SH "ANATOMY OF A WATCHER" |
606 |
|
|
.IX Header "ANATOMY OF A WATCHER" |
607 |
|
|
A watcher is a structure that you create and register to record your |
608 |
|
|
interest in some event. For instance, if you want to wait for \s-1STDIN\s0 to |
609 |
|
|
become readable, you would create an \f(CW\*(C`ev_io\*(C'\fR watcher for that: |
610 |
|
|
.PP |
611 |
|
|
.Vb 5 |
612 |
|
|
\& static void my_cb (struct ev_loop *loop, struct ev_io *w, int revents) |
613 |
|
|
\& { |
614 |
|
|
\& ev_io_stop (w); |
615 |
|
|
\& ev_unloop (loop, EVUNLOOP_ALL); |
616 |
|
|
\& } |
617 |
|
|
.Ve |
618 |
|
|
.PP |
619 |
|
|
.Vb 6 |
620 |
|
|
\& struct ev_loop *loop = ev_default_loop (0); |
621 |
|
|
\& struct ev_io stdin_watcher; |
622 |
|
|
\& ev_init (&stdin_watcher, my_cb); |
623 |
|
|
\& ev_io_set (&stdin_watcher, STDIN_FILENO, EV_READ); |
624 |
|
|
\& ev_io_start (loop, &stdin_watcher); |
625 |
|
|
\& ev_loop (loop, 0); |
626 |
|
|
.Ve |
627 |
|
|
.PP |
628 |
|
|
As you can see, you are responsible for allocating the memory for your |
629 |
|
|
watcher structures (and it is usually a bad idea to do this on the stack, |
630 |
|
|
although this can sometimes be quite valid). |
631 |
|
|
.PP |
632 |
|
|
Each watcher structure must be initialised by a call to \f(CW\*(C`ev_init |
633 |
|
|
(watcher *, callback)\*(C'\fR, which expects a callback to be provided. This |
634 |
|
|
callback gets invoked each time the event occurs (or, in the case of io |
635 |
|
|
watchers, each time the event loop detects that the file descriptor given |
636 |
|
|
is readable and/or writable). |
637 |
|
|
.PP |
638 |
|
|
Each watcher type has its own \f(CW\*(C`ev_<type>_set (watcher *, ...)\*(C'\fR macro |
639 |
|
|
with arguments specific to this watcher type. There is also a macro |
640 |
|
|
to combine initialisation and setting in one call: \f(CW\*(C`ev_<type>_init |
641 |
|
|
(watcher *, callback, ...)\*(C'\fR. |
642 |
|
|
.PP |
643 |
|
|
To make the watcher actually watch out for events, you have to start it |
644 |
|
|
with a watcher-specific start function (\f(CW\*(C`ev_<type>_start (loop, watcher |
645 |
|
|
*)\*(C'\fR), and you can stop watching for events at any time by calling the |
646 |
|
|
corresponding stop function (\f(CW\*(C`ev_<type>_stop (loop, watcher *)\*(C'\fR. |
647 |
|
|
.PP |
648 |
|
|
As long as your watcher is active (has been started but not stopped) you |
649 |
|
|
must not touch the values stored in it. Most specifically you must never |
650 |
root |
1.6 |
reinitialise it or call its set macro. |
651 |
root |
1.1 |
.PP |
652 |
|
|
You can check whether an event is active by calling the \f(CW\*(C`ev_is_active |
653 |
|
|
(watcher *)\*(C'\fR macro. To see whether an event is outstanding (but the |
654 |
|
|
callback for it has not been called yet) you can use the \f(CW\*(C`ev_is_pending |
655 |
|
|
(watcher *)\*(C'\fR macro. |
656 |
|
|
.PP |
657 |
|
|
Each and every callback receives the event loop pointer as first, the |
658 |
|
|
registered watcher structure as second, and a bitset of received events as |
659 |
|
|
third argument. |
660 |
|
|
.PP |
661 |
|
|
The received events usually include a single bit per event type received |
662 |
|
|
(you can receive multiple events at the same time). The possible bit masks |
663 |
|
|
are: |
664 |
|
|
.ie n .IP """EV_READ""" 4 |
665 |
|
|
.el .IP "\f(CWEV_READ\fR" 4 |
666 |
|
|
.IX Item "EV_READ" |
667 |
|
|
.PD 0 |
668 |
|
|
.ie n .IP """EV_WRITE""" 4 |
669 |
|
|
.el .IP "\f(CWEV_WRITE\fR" 4 |
670 |
|
|
.IX Item "EV_WRITE" |
671 |
|
|
.PD |
672 |
|
|
The file descriptor in the \f(CW\*(C`ev_io\*(C'\fR watcher has become readable and/or |
673 |
|
|
writable. |
674 |
|
|
.ie n .IP """EV_TIMEOUT""" 4 |
675 |
|
|
.el .IP "\f(CWEV_TIMEOUT\fR" 4 |
676 |
|
|
.IX Item "EV_TIMEOUT" |
677 |
|
|
The \f(CW\*(C`ev_timer\*(C'\fR watcher has timed out. |
678 |
|
|
.ie n .IP """EV_PERIODIC""" 4 |
679 |
|
|
.el .IP "\f(CWEV_PERIODIC\fR" 4 |
680 |
|
|
.IX Item "EV_PERIODIC" |
681 |
|
|
The \f(CW\*(C`ev_periodic\*(C'\fR watcher has timed out. |
682 |
|
|
.ie n .IP """EV_SIGNAL""" 4 |
683 |
|
|
.el .IP "\f(CWEV_SIGNAL\fR" 4 |
684 |
|
|
.IX Item "EV_SIGNAL" |
685 |
|
|
The signal specified in the \f(CW\*(C`ev_signal\*(C'\fR watcher has been received by a thread. |
686 |
|
|
.ie n .IP """EV_CHILD""" 4 |
687 |
|
|
.el .IP "\f(CWEV_CHILD\fR" 4 |
688 |
|
|
.IX Item "EV_CHILD" |
689 |
|
|
The pid specified in the \f(CW\*(C`ev_child\*(C'\fR watcher has received a status change. |
690 |
|
|
.ie n .IP """EV_IDLE""" 4 |
691 |
|
|
.el .IP "\f(CWEV_IDLE\fR" 4 |
692 |
|
|
.IX Item "EV_IDLE" |
693 |
|
|
The \f(CW\*(C`ev_idle\*(C'\fR watcher has determined that you have nothing better to do. |
694 |
|
|
.ie n .IP """EV_PREPARE""" 4 |
695 |
|
|
.el .IP "\f(CWEV_PREPARE\fR" 4 |
696 |
|
|
.IX Item "EV_PREPARE" |
697 |
|
|
.PD 0 |
698 |
|
|
.ie n .IP """EV_CHECK""" 4 |
699 |
|
|
.el .IP "\f(CWEV_CHECK\fR" 4 |
700 |
|
|
.IX Item "EV_CHECK" |
701 |
|
|
.PD |
702 |
|
|
All \f(CW\*(C`ev_prepare\*(C'\fR watchers are invoked just \fIbefore\fR \f(CW\*(C`ev_loop\*(C'\fR starts |
703 |
|
|
to gather new events, and all \f(CW\*(C`ev_check\*(C'\fR watchers are invoked just after |
704 |
|
|
\&\f(CW\*(C`ev_loop\*(C'\fR has gathered them, but before it invokes any callbacks for any |
705 |
|
|
received events. Callbacks of both watcher types can start and stop as |
706 |
|
|
many watchers as they want, and all of them will be taken into account |
707 |
|
|
(for example, a \f(CW\*(C`ev_prepare\*(C'\fR watcher might start an idle watcher to keep |
708 |
|
|
\&\f(CW\*(C`ev_loop\*(C'\fR from blocking). |
709 |
|
|
.ie n .IP """EV_ERROR""" 4 |
710 |
|
|
.el .IP "\f(CWEV_ERROR\fR" 4 |
711 |
|
|
.IX Item "EV_ERROR" |
712 |
|
|
An unspecified error has occured, the watcher has been stopped. This might |
713 |
|
|
happen because the watcher could not be properly started because libev |
714 |
|
|
ran out of memory, a file descriptor was found to be closed or any other |
715 |
|
|
problem. You best act on it by reporting the problem and somehow coping |
716 |
|
|
with the watcher being stopped. |
717 |
|
|
.Sp |
718 |
|
|
Libev will usually signal a few \*(L"dummy\*(R" events together with an error, |
719 |
|
|
for example it might indicate that a fd is readable or writable, and if |
720 |
|
|
your callbacks is well-written it can just attempt the operation and cope |
721 |
|
|
with the error from \fIread()\fR or \fIwrite()\fR. This will not work in multithreaded |
722 |
|
|
programs, though, so beware. |
723 |
|
|
.Sh "\s-1ASSOCIATING\s0 \s-1CUSTOM\s0 \s-1DATA\s0 \s-1WITH\s0 A \s-1WATCHER\s0" |
724 |
|
|
.IX Subsection "ASSOCIATING CUSTOM DATA WITH A WATCHER" |
725 |
|
|
Each watcher has, by default, a member \f(CW\*(C`void *data\*(C'\fR that you can change |
726 |
|
|
and read at any time, libev will completely ignore it. This can be used |
727 |
|
|
to associate arbitrary data with your watcher. If you need more data and |
728 |
|
|
don't want to allocate memory and store a pointer to it in that data |
729 |
|
|
member, you can also \*(L"subclass\*(R" the watcher type and provide your own |
730 |
|
|
data: |
731 |
|
|
.PP |
732 |
|
|
.Vb 7 |
733 |
|
|
\& struct my_io |
734 |
|
|
\& { |
735 |
|
|
\& struct ev_io io; |
736 |
|
|
\& int otherfd; |
737 |
|
|
\& void *somedata; |
738 |
|
|
\& struct whatever *mostinteresting; |
739 |
|
|
\& } |
740 |
|
|
.Ve |
741 |
|
|
.PP |
742 |
|
|
And since your callback will be called with a pointer to the watcher, you |
743 |
|
|
can cast it back to your own type: |
744 |
|
|
.PP |
745 |
|
|
.Vb 5 |
746 |
|
|
\& static void my_cb (struct ev_loop *loop, struct ev_io *w_, int revents) |
747 |
|
|
\& { |
748 |
|
|
\& struct my_io *w = (struct my_io *)w_; |
749 |
|
|
\& ... |
750 |
|
|
\& } |
751 |
|
|
.Ve |
752 |
|
|
.PP |
753 |
|
|
More interesting and less C\-conformant ways of catsing your callback type |
754 |
|
|
have been omitted.... |
755 |
|
|
.SH "WATCHER TYPES" |
756 |
|
|
.IX Header "WATCHER TYPES" |
757 |
|
|
This section describes each watcher in detail, but will not repeat |
758 |
|
|
information given in the last section. |
759 |
|
|
.ie n .Sh """ev_io"" \- is this file descriptor readable or writable" |
760 |
|
|
.el .Sh "\f(CWev_io\fP \- is this file descriptor readable or writable" |
761 |
|
|
.IX Subsection "ev_io - is this file descriptor readable or writable" |
762 |
|
|
I/O watchers check whether a file descriptor is readable or writable |
763 |
|
|
in each iteration of the event loop (This behaviour is called |
764 |
|
|
level-triggering because you keep receiving events as long as the |
765 |
|
|
condition persists. Remember you can stop the watcher if you don't want to |
766 |
|
|
act on the event and neither want to receive future events). |
767 |
|
|
.PP |
768 |
|
|
In general you can register as many read and/or write event watchers per |
769 |
|
|
fd as you want (as long as you don't confuse yourself). Setting all file |
770 |
|
|
descriptors to non-blocking mode is also usually a good idea (but not |
771 |
|
|
required if you know what you are doing). |
772 |
|
|
.PP |
773 |
|
|
You have to be careful with dup'ed file descriptors, though. Some backends |
774 |
|
|
(the linux epoll backend is a notable example) cannot handle dup'ed file |
775 |
|
|
descriptors correctly if you register interest in two or more fds pointing |
776 |
|
|
to the same underlying file/socket etc. description (that is, they share |
777 |
|
|
the same underlying \*(L"file open\*(R"). |
778 |
|
|
.PP |
779 |
|
|
If you must do this, then force the use of a known-to-be-good backend |
780 |
root |
1.6 |
(at the time of this writing, this includes only \f(CW\*(C`EVBACKEND_SELECT\*(C'\fR and |
781 |
|
|
\&\f(CW\*(C`EVBACKEND_POLL\*(C'\fR). |
782 |
root |
1.1 |
.IP "ev_io_init (ev_io *, callback, int fd, int events)" 4 |
783 |
|
|
.IX Item "ev_io_init (ev_io *, callback, int fd, int events)" |
784 |
|
|
.PD 0 |
785 |
|
|
.IP "ev_io_set (ev_io *, int fd, int events)" 4 |
786 |
|
|
.IX Item "ev_io_set (ev_io *, int fd, int events)" |
787 |
|
|
.PD |
788 |
|
|
Configures an \f(CW\*(C`ev_io\*(C'\fR watcher. The fd is the file descriptor to rceeive |
789 |
|
|
events for and events is either \f(CW\*(C`EV_READ\*(C'\fR, \f(CW\*(C`EV_WRITE\*(C'\fR or \f(CW\*(C`EV_READ | |
790 |
|
|
EV_WRITE\*(C'\fR to receive the given events. |
791 |
root |
1.7 |
.Sp |
792 |
|
|
Please note that most of the more scalable backend mechanisms (for example |
793 |
|
|
epoll and solaris ports) can result in spurious readyness notifications |
794 |
|
|
for file descriptors, so you practically need to use non-blocking I/O (and |
795 |
|
|
treat callback invocation as hint only), or retest separately with a safe |
796 |
|
|
interface before doing I/O (XLib can do this), or force the use of either |
797 |
|
|
\&\f(CW\*(C`EVBACKEND_SELECT\*(C'\fR or \f(CW\*(C`EVBACKEND_POLL\*(C'\fR, which don't suffer from this |
798 |
|
|
problem. Also note that it is quite easy to have your callback invoked |
799 |
|
|
when the readyness condition is no longer valid even when employing |
800 |
|
|
typical ways of handling events, so its a good idea to use non-blocking |
801 |
|
|
I/O unconditionally. |
802 |
root |
1.9 |
.PP |
803 |
|
|
Example: call \f(CW\*(C`stdin_readable_cb\*(C'\fR when \s-1STDIN_FILENO\s0 has become, well |
804 |
|
|
readable, but only once. Since it is likely line\-buffered, you could |
805 |
|
|
attempt to read a whole line in the callback: |
806 |
|
|
.PP |
807 |
|
|
.Vb 6 |
808 |
|
|
\& static void |
809 |
|
|
\& stdin_readable_cb (struct ev_loop *loop, struct ev_io *w, int revents) |
810 |
|
|
\& { |
811 |
|
|
\& ev_io_stop (loop, w); |
812 |
|
|
\& .. read from stdin here (or from w->fd) and haqndle any I/O errors |
813 |
|
|
\& } |
814 |
|
|
.Ve |
815 |
|
|
.PP |
816 |
|
|
.Vb 6 |
817 |
|
|
\& ... |
818 |
|
|
\& struct ev_loop *loop = ev_default_init (0); |
819 |
|
|
\& struct ev_io stdin_readable; |
820 |
|
|
\& ev_io_init (&stdin_readable, stdin_readable_cb, STDIN_FILENO, EV_READ); |
821 |
|
|
\& ev_io_start (loop, &stdin_readable); |
822 |
|
|
\& ev_loop (loop, 0); |
823 |
|
|
.Ve |
824 |
root |
1.1 |
.ie n .Sh """ev_timer"" \- relative and optionally recurring timeouts" |
825 |
|
|
.el .Sh "\f(CWev_timer\fP \- relative and optionally recurring timeouts" |
826 |
|
|
.IX Subsection "ev_timer - relative and optionally recurring timeouts" |
827 |
|
|
Timer watchers are simple relative timers that generate an event after a |
828 |
|
|
given time, and optionally repeating in regular intervals after that. |
829 |
|
|
.PP |
830 |
|
|
The timers are based on real time, that is, if you register an event that |
831 |
|
|
times out after an hour and you reset your system clock to last years |
832 |
|
|
time, it will still time out after (roughly) and hour. \*(L"Roughly\*(R" because |
833 |
root |
1.2 |
detecting time jumps is hard, and some inaccuracies are unavoidable (the |
834 |
root |
1.1 |
monotonic clock option helps a lot here). |
835 |
|
|
.PP |
836 |
|
|
The relative timeouts are calculated relative to the \f(CW\*(C`ev_now ()\*(C'\fR |
837 |
|
|
time. This is usually the right thing as this timestamp refers to the time |
838 |
root |
1.2 |
of the event triggering whatever timeout you are modifying/starting. If |
839 |
|
|
you suspect event processing to be delayed and you \fIneed\fR to base the timeout |
840 |
root |
1.1 |
on the current time, use something like this to adjust for this: |
841 |
|
|
.PP |
842 |
|
|
.Vb 1 |
843 |
|
|
\& ev_timer_set (&timer, after + ev_now () - ev_time (), 0.); |
844 |
|
|
.Ve |
845 |
root |
1.2 |
.PP |
846 |
|
|
The callback is guarenteed to be invoked only when its timeout has passed, |
847 |
|
|
but if multiple timers become ready during the same loop iteration then |
848 |
|
|
order of execution is undefined. |
849 |
root |
1.1 |
.IP "ev_timer_init (ev_timer *, callback, ev_tstamp after, ev_tstamp repeat)" 4 |
850 |
|
|
.IX Item "ev_timer_init (ev_timer *, callback, ev_tstamp after, ev_tstamp repeat)" |
851 |
|
|
.PD 0 |
852 |
|
|
.IP "ev_timer_set (ev_timer *, ev_tstamp after, ev_tstamp repeat)" 4 |
853 |
|
|
.IX Item "ev_timer_set (ev_timer *, ev_tstamp after, ev_tstamp repeat)" |
854 |
|
|
.PD |
855 |
|
|
Configure the timer to trigger after \f(CW\*(C`after\*(C'\fR seconds. If \f(CW\*(C`repeat\*(C'\fR is |
856 |
|
|
\&\f(CW0.\fR, then it will automatically be stopped. If it is positive, then the |
857 |
|
|
timer will automatically be configured to trigger again \f(CW\*(C`repeat\*(C'\fR seconds |
858 |
|
|
later, again, and again, until stopped manually. |
859 |
|
|
.Sp |
860 |
|
|
The timer itself will do a best-effort at avoiding drift, that is, if you |
861 |
|
|
configure a timer to trigger every 10 seconds, then it will trigger at |
862 |
|
|
exactly 10 second intervals. If, however, your program cannot keep up with |
863 |
|
|
the timer (because it takes longer than those 10 seconds to do stuff) the |
864 |
|
|
timer will not fire more than once per event loop iteration. |
865 |
|
|
.IP "ev_timer_again (loop)" 4 |
866 |
|
|
.IX Item "ev_timer_again (loop)" |
867 |
|
|
This will act as if the timer timed out and restart it again if it is |
868 |
|
|
repeating. The exact semantics are: |
869 |
|
|
.Sp |
870 |
|
|
If the timer is started but nonrepeating, stop it. |
871 |
|
|
.Sp |
872 |
|
|
If the timer is repeating, either start it if necessary (with the repeat |
873 |
|
|
value), or reset the running timer to the repeat value. |
874 |
|
|
.Sp |
875 |
|
|
This sounds a bit complicated, but here is a useful and typical |
876 |
|
|
example: Imagine you have a tcp connection and you want a so-called idle |
877 |
|
|
timeout, that is, you want to be called when there have been, say, 60 |
878 |
|
|
seconds of inactivity on the socket. The easiest way to do this is to |
879 |
|
|
configure an \f(CW\*(C`ev_timer\*(C'\fR with after=repeat=60 and calling ev_timer_again each |
880 |
|
|
time you successfully read or write some data. If you go into an idle |
881 |
|
|
state where you do not expect data to travel on the socket, you can stop |
882 |
|
|
the timer, and again will automatically restart it if need be. |
883 |
root |
1.9 |
.PP |
884 |
|
|
Example: create a timer that fires after 60 seconds. |
885 |
|
|
.PP |
886 |
|
|
.Vb 5 |
887 |
|
|
\& static void |
888 |
|
|
\& one_minute_cb (struct ev_loop *loop, struct ev_timer *w, int revents) |
889 |
|
|
\& { |
890 |
|
|
\& .. one minute over, w is actually stopped right here |
891 |
|
|
\& } |
892 |
|
|
.Ve |
893 |
|
|
.PP |
894 |
|
|
.Vb 3 |
895 |
|
|
\& struct ev_timer mytimer; |
896 |
|
|
\& ev_timer_init (&mytimer, one_minute_cb, 60., 0.); |
897 |
|
|
\& ev_timer_start (loop, &mytimer); |
898 |
|
|
.Ve |
899 |
|
|
.PP |
900 |
|
|
Example: create a timeout timer that times out after 10 seconds of |
901 |
|
|
inactivity. |
902 |
|
|
.PP |
903 |
|
|
.Vb 5 |
904 |
|
|
\& static void |
905 |
|
|
\& timeout_cb (struct ev_loop *loop, struct ev_timer *w, int revents) |
906 |
|
|
\& { |
907 |
|
|
\& .. ten seconds without any activity |
908 |
|
|
\& } |
909 |
|
|
.Ve |
910 |
|
|
.PP |
911 |
|
|
.Vb 4 |
912 |
|
|
\& struct ev_timer mytimer; |
913 |
|
|
\& ev_timer_init (&mytimer, timeout_cb, 0., 10.); /* note, only repeat used */ |
914 |
|
|
\& ev_timer_again (&mytimer); /* start timer */ |
915 |
|
|
\& ev_loop (loop, 0); |
916 |
|
|
.Ve |
917 |
|
|
.PP |
918 |
|
|
.Vb 3 |
919 |
|
|
\& // and in some piece of code that gets executed on any "activity": |
920 |
|
|
\& // reset the timeout to start ticking again at 10 seconds |
921 |
|
|
\& ev_timer_again (&mytimer); |
922 |
|
|
.Ve |
923 |
root |
1.1 |
.ie n .Sh """ev_periodic"" \- to cron or not to cron" |
924 |
|
|
.el .Sh "\f(CWev_periodic\fP \- to cron or not to cron" |
925 |
|
|
.IX Subsection "ev_periodic - to cron or not to cron" |
926 |
|
|
Periodic watchers are also timers of a kind, but they are very versatile |
927 |
|
|
(and unfortunately a bit complex). |
928 |
|
|
.PP |
929 |
|
|
Unlike \f(CW\*(C`ev_timer\*(C'\fR's, they are not based on real time (or relative time) |
930 |
|
|
but on wallclock time (absolute time). You can tell a periodic watcher |
931 |
|
|
to trigger \*(L"at\*(R" some specific point in time. For example, if you tell a |
932 |
|
|
periodic watcher to trigger in 10 seconds (by specifiying e.g. c<ev_now () |
933 |
|
|
+ 10.>) and then reset your system clock to the last year, then it will |
934 |
|
|
take a year to trigger the event (unlike an \f(CW\*(C`ev_timer\*(C'\fR, which would trigger |
935 |
|
|
roughly 10 seconds later and of course not if you reset your system time |
936 |
|
|
again). |
937 |
|
|
.PP |
938 |
|
|
They can also be used to implement vastly more complex timers, such as |
939 |
|
|
triggering an event on eahc midnight, local time. |
940 |
root |
1.2 |
.PP |
941 |
|
|
As with timers, the callback is guarenteed to be invoked only when the |
942 |
|
|
time (\f(CW\*(C`at\*(C'\fR) has been passed, but if multiple periodic timers become ready |
943 |
|
|
during the same loop iteration then order of execution is undefined. |
944 |
root |
1.1 |
.IP "ev_periodic_init (ev_periodic *, callback, ev_tstamp at, ev_tstamp interval, reschedule_cb)" 4 |
945 |
|
|
.IX Item "ev_periodic_init (ev_periodic *, callback, ev_tstamp at, ev_tstamp interval, reschedule_cb)" |
946 |
|
|
.PD 0 |
947 |
|
|
.IP "ev_periodic_set (ev_periodic *, ev_tstamp after, ev_tstamp repeat, reschedule_cb)" 4 |
948 |
|
|
.IX Item "ev_periodic_set (ev_periodic *, ev_tstamp after, ev_tstamp repeat, reschedule_cb)" |
949 |
|
|
.PD |
950 |
|
|
Lots of arguments, lets sort it out... There are basically three modes of |
951 |
|
|
operation, and we will explain them from simplest to complex: |
952 |
|
|
.RS 4 |
953 |
|
|
.IP "* absolute timer (interval = reschedule_cb = 0)" 4 |
954 |
|
|
.IX Item "absolute timer (interval = reschedule_cb = 0)" |
955 |
|
|
In this configuration the watcher triggers an event at the wallclock time |
956 |
|
|
\&\f(CW\*(C`at\*(C'\fR and doesn't repeat. It will not adjust when a time jump occurs, |
957 |
|
|
that is, if it is to be run at January 1st 2011 then it will run when the |
958 |
|
|
system time reaches or surpasses this time. |
959 |
|
|
.IP "* non-repeating interval timer (interval > 0, reschedule_cb = 0)" 4 |
960 |
|
|
.IX Item "non-repeating interval timer (interval > 0, reschedule_cb = 0)" |
961 |
|
|
In this mode the watcher will always be scheduled to time out at the next |
962 |
|
|
\&\f(CW\*(C`at + N * interval\*(C'\fR time (for some integer N) and then repeat, regardless |
963 |
|
|
of any time jumps. |
964 |
|
|
.Sp |
965 |
|
|
This can be used to create timers that do not drift with respect to system |
966 |
|
|
time: |
967 |
|
|
.Sp |
968 |
|
|
.Vb 1 |
969 |
|
|
\& ev_periodic_set (&periodic, 0., 3600., 0); |
970 |
|
|
.Ve |
971 |
|
|
.Sp |
972 |
|
|
This doesn't mean there will always be 3600 seconds in between triggers, |
973 |
|
|
but only that the the callback will be called when the system time shows a |
974 |
|
|
full hour (\s-1UTC\s0), or more correctly, when the system time is evenly divisible |
975 |
|
|
by 3600. |
976 |
|
|
.Sp |
977 |
|
|
Another way to think about it (for the mathematically inclined) is that |
978 |
|
|
\&\f(CW\*(C`ev_periodic\*(C'\fR will try to run the callback in this mode at the next possible |
979 |
|
|
time where \f(CW\*(C`time = at (mod interval)\*(C'\fR, regardless of any time jumps. |
980 |
|
|
.IP "* manual reschedule mode (reschedule_cb = callback)" 4 |
981 |
|
|
.IX Item "manual reschedule mode (reschedule_cb = callback)" |
982 |
|
|
In this mode the values for \f(CW\*(C`interval\*(C'\fR and \f(CW\*(C`at\*(C'\fR are both being |
983 |
|
|
ignored. Instead, each time the periodic watcher gets scheduled, the |
984 |
|
|
reschedule callback will be called with the watcher as first, and the |
985 |
|
|
current time as second argument. |
986 |
|
|
.Sp |
987 |
|
|
\&\s-1NOTE:\s0 \fIThis callback \s-1MUST\s0 \s-1NOT\s0 stop or destroy any periodic watcher, |
988 |
|
|
ever, or make any event loop modifications\fR. If you need to stop it, |
989 |
|
|
return \f(CW\*(C`now + 1e30\*(C'\fR (or so, fudge fudge) and stop it afterwards (e.g. by |
990 |
|
|
starting a prepare watcher). |
991 |
|
|
.Sp |
992 |
|
|
Its prototype is \f(CW\*(C`ev_tstamp (*reschedule_cb)(struct ev_periodic *w, |
993 |
|
|
ev_tstamp now)\*(C'\fR, e.g.: |
994 |
|
|
.Sp |
995 |
|
|
.Vb 4 |
996 |
|
|
\& static ev_tstamp my_rescheduler (struct ev_periodic *w, ev_tstamp now) |
997 |
|
|
\& { |
998 |
|
|
\& return now + 60.; |
999 |
|
|
\& } |
1000 |
|
|
.Ve |
1001 |
|
|
.Sp |
1002 |
|
|
It must return the next time to trigger, based on the passed time value |
1003 |
|
|
(that is, the lowest time value larger than to the second argument). It |
1004 |
|
|
will usually be called just before the callback will be triggered, but |
1005 |
|
|
might be called at other times, too. |
1006 |
|
|
.Sp |
1007 |
|
|
\&\s-1NOTE:\s0 \fIThis callback must always return a time that is later than the |
1008 |
|
|
passed \f(CI\*(C`now\*(C'\fI value\fR. Not even \f(CW\*(C`now\*(C'\fR itself will do, it \fImust\fR be larger. |
1009 |
|
|
.Sp |
1010 |
|
|
This can be used to create very complex timers, such as a timer that |
1011 |
|
|
triggers on each midnight, local time. To do this, you would calculate the |
1012 |
|
|
next midnight after \f(CW\*(C`now\*(C'\fR and return the timestamp value for this. How |
1013 |
|
|
you do this is, again, up to you (but it is not trivial, which is the main |
1014 |
|
|
reason I omitted it as an example). |
1015 |
|
|
.RE |
1016 |
|
|
.RS 4 |
1017 |
|
|
.RE |
1018 |
|
|
.IP "ev_periodic_again (loop, ev_periodic *)" 4 |
1019 |
|
|
.IX Item "ev_periodic_again (loop, ev_periodic *)" |
1020 |
|
|
Simply stops and restarts the periodic watcher again. This is only useful |
1021 |
|
|
when you changed some parameters or the reschedule callback would return |
1022 |
|
|
a different time than the last time it was called (e.g. in a crond like |
1023 |
|
|
program when the crontabs have changed). |
1024 |
root |
1.9 |
.PP |
1025 |
|
|
Example: call a callback every hour, or, more precisely, whenever the |
1026 |
|
|
system clock is divisible by 3600. The callback invocation times have |
1027 |
|
|
potentially a lot of jittering, but good long-term stability. |
1028 |
|
|
.PP |
1029 |
|
|
.Vb 5 |
1030 |
|
|
\& static void |
1031 |
|
|
\& clock_cb (struct ev_loop *loop, struct ev_io *w, int revents) |
1032 |
|
|
\& { |
1033 |
|
|
\& ... its now a full hour (UTC, or TAI or whatever your clock follows) |
1034 |
|
|
\& } |
1035 |
|
|
.Ve |
1036 |
|
|
.PP |
1037 |
|
|
.Vb 3 |
1038 |
|
|
\& struct ev_periodic hourly_tick; |
1039 |
|
|
\& ev_periodic_init (&hourly_tick, clock_cb, 0., 3600., 0); |
1040 |
|
|
\& ev_periodic_start (loop, &hourly_tick); |
1041 |
|
|
.Ve |
1042 |
|
|
.PP |
1043 |
|
|
Example: the same as above, but use a reschedule callback to do it: |
1044 |
|
|
.PP |
1045 |
|
|
.Vb 1 |
1046 |
|
|
\& #include <math.h> |
1047 |
|
|
.Ve |
1048 |
|
|
.PP |
1049 |
|
|
.Vb 5 |
1050 |
|
|
\& static ev_tstamp |
1051 |
|
|
\& my_scheduler_cb (struct ev_periodic *w, ev_tstamp now) |
1052 |
|
|
\& { |
1053 |
|
|
\& return fmod (now, 3600.) + 3600.; |
1054 |
|
|
\& } |
1055 |
|
|
.Ve |
1056 |
|
|
.PP |
1057 |
|
|
.Vb 1 |
1058 |
|
|
\& ev_periodic_init (&hourly_tick, clock_cb, 0., 0., my_scheduler_cb); |
1059 |
|
|
.Ve |
1060 |
|
|
.PP |
1061 |
|
|
Example: call a callback every hour, starting now: |
1062 |
|
|
.PP |
1063 |
|
|
.Vb 4 |
1064 |
|
|
\& struct ev_periodic hourly_tick; |
1065 |
|
|
\& ev_periodic_init (&hourly_tick, clock_cb, |
1066 |
|
|
\& fmod (ev_now (loop), 3600.), 3600., 0); |
1067 |
|
|
\& ev_periodic_start (loop, &hourly_tick); |
1068 |
|
|
.Ve |
1069 |
root |
1.1 |
.ie n .Sh """ev_signal"" \- signal me when a signal gets signalled" |
1070 |
|
|
.el .Sh "\f(CWev_signal\fP \- signal me when a signal gets signalled" |
1071 |
|
|
.IX Subsection "ev_signal - signal me when a signal gets signalled" |
1072 |
|
|
Signal watchers will trigger an event when the process receives a specific |
1073 |
|
|
signal one or more times. Even though signals are very asynchronous, libev |
1074 |
|
|
will try it's best to deliver signals synchronously, i.e. as part of the |
1075 |
|
|
normal event processing, like any other event. |
1076 |
|
|
.PP |
1077 |
|
|
You can configure as many watchers as you like per signal. Only when the |
1078 |
|
|
first watcher gets started will libev actually register a signal watcher |
1079 |
|
|
with the kernel (thus it coexists with your own signal handlers as long |
1080 |
|
|
as you don't register any with libev). Similarly, when the last signal |
1081 |
|
|
watcher for a signal is stopped libev will reset the signal handler to |
1082 |
|
|
\&\s-1SIG_DFL\s0 (regardless of what it was set to before). |
1083 |
|
|
.IP "ev_signal_init (ev_signal *, callback, int signum)" 4 |
1084 |
|
|
.IX Item "ev_signal_init (ev_signal *, callback, int signum)" |
1085 |
|
|
.PD 0 |
1086 |
|
|
.IP "ev_signal_set (ev_signal *, int signum)" 4 |
1087 |
|
|
.IX Item "ev_signal_set (ev_signal *, int signum)" |
1088 |
|
|
.PD |
1089 |
|
|
Configures the watcher to trigger on the given signal number (usually one |
1090 |
|
|
of the \f(CW\*(C`SIGxxx\*(C'\fR constants). |
1091 |
|
|
.ie n .Sh """ev_child"" \- wait for pid status changes" |
1092 |
|
|
.el .Sh "\f(CWev_child\fP \- wait for pid status changes" |
1093 |
|
|
.IX Subsection "ev_child - wait for pid status changes" |
1094 |
|
|
Child watchers trigger when your process receives a \s-1SIGCHLD\s0 in response to |
1095 |
|
|
some child status changes (most typically when a child of yours dies). |
1096 |
|
|
.IP "ev_child_init (ev_child *, callback, int pid)" 4 |
1097 |
|
|
.IX Item "ev_child_init (ev_child *, callback, int pid)" |
1098 |
|
|
.PD 0 |
1099 |
|
|
.IP "ev_child_set (ev_child *, int pid)" 4 |
1100 |
|
|
.IX Item "ev_child_set (ev_child *, int pid)" |
1101 |
|
|
.PD |
1102 |
|
|
Configures the watcher to wait for status changes of process \f(CW\*(C`pid\*(C'\fR (or |
1103 |
|
|
\&\fIany\fR process if \f(CW\*(C`pid\*(C'\fR is specified as \f(CW0\fR). The callback can look |
1104 |
|
|
at the \f(CW\*(C`rstatus\*(C'\fR member of the \f(CW\*(C`ev_child\*(C'\fR watcher structure to see |
1105 |
|
|
the status word (use the macros from \f(CW\*(C`sys/wait.h\*(C'\fR and see your systems |
1106 |
|
|
\&\f(CW\*(C`waitpid\*(C'\fR documentation). The \f(CW\*(C`rpid\*(C'\fR member contains the pid of the |
1107 |
|
|
process causing the status change. |
1108 |
root |
1.9 |
.PP |
1109 |
|
|
Example: try to exit cleanly on \s-1SIGINT\s0 and \s-1SIGTERM\s0. |
1110 |
|
|
.PP |
1111 |
|
|
.Vb 5 |
1112 |
|
|
\& static void |
1113 |
|
|
\& sigint_cb (struct ev_loop *loop, struct ev_signal *w, int revents) |
1114 |
|
|
\& { |
1115 |
|
|
\& ev_unloop (loop, EVUNLOOP_ALL); |
1116 |
|
|
\& } |
1117 |
|
|
.Ve |
1118 |
|
|
.PP |
1119 |
|
|
.Vb 3 |
1120 |
|
|
\& struct ev_signal signal_watcher; |
1121 |
|
|
\& ev_signal_init (&signal_watcher, sigint_cb, SIGINT); |
1122 |
|
|
\& ev_signal_start (loop, &sigint_cb); |
1123 |
|
|
.Ve |
1124 |
root |
1.1 |
.ie n .Sh """ev_idle"" \- when you've got nothing better to do" |
1125 |
|
|
.el .Sh "\f(CWev_idle\fP \- when you've got nothing better to do" |
1126 |
|
|
.IX Subsection "ev_idle - when you've got nothing better to do" |
1127 |
|
|
Idle watchers trigger events when there are no other events are pending |
1128 |
|
|
(prepare, check and other idle watchers do not count). That is, as long |
1129 |
|
|
as your process is busy handling sockets or timeouts (or even signals, |
1130 |
|
|
imagine) it will not be triggered. But when your process is idle all idle |
1131 |
|
|
watchers are being called again and again, once per event loop iteration \- |
1132 |
|
|
until stopped, that is, or your process receives more events and becomes |
1133 |
|
|
busy. |
1134 |
|
|
.PP |
1135 |
|
|
The most noteworthy effect is that as long as any idle watchers are |
1136 |
|
|
active, the process will not block when waiting for new events. |
1137 |
|
|
.PP |
1138 |
|
|
Apart from keeping your process non-blocking (which is a useful |
1139 |
|
|
effect on its own sometimes), idle watchers are a good place to do |
1140 |
|
|
\&\*(L"pseudo\-background processing\*(R", or delay processing stuff to after the |
1141 |
|
|
event loop has handled all outstanding events. |
1142 |
|
|
.IP "ev_idle_init (ev_signal *, callback)" 4 |
1143 |
|
|
.IX Item "ev_idle_init (ev_signal *, callback)" |
1144 |
|
|
Initialises and configures the idle watcher \- it has no parameters of any |
1145 |
|
|
kind. There is a \f(CW\*(C`ev_idle_set\*(C'\fR macro, but using it is utterly pointless, |
1146 |
|
|
believe me. |
1147 |
root |
1.9 |
.PP |
1148 |
|
|
Example: dynamically allocate an \f(CW\*(C`ev_idle\*(C'\fR, start it, and in the |
1149 |
|
|
callback, free it. Alos, use no error checking, as usual. |
1150 |
|
|
.PP |
1151 |
|
|
.Vb 7 |
1152 |
|
|
\& static void |
1153 |
|
|
\& idle_cb (struct ev_loop *loop, struct ev_idle *w, int revents) |
1154 |
|
|
\& { |
1155 |
|
|
\& free (w); |
1156 |
|
|
\& // now do something you wanted to do when the program has |
1157 |
|
|
\& // no longer asnything immediate to do. |
1158 |
|
|
\& } |
1159 |
|
|
.Ve |
1160 |
|
|
.PP |
1161 |
|
|
.Vb 3 |
1162 |
|
|
\& struct ev_idle *idle_watcher = malloc (sizeof (struct ev_idle)); |
1163 |
|
|
\& ev_idle_init (idle_watcher, idle_cb); |
1164 |
|
|
\& ev_idle_start (loop, idle_cb); |
1165 |
|
|
.Ve |
1166 |
root |
1.1 |
.ie n .Sh """ev_prepare""\fP and \f(CW""ev_check"" \- customise your event loop" |
1167 |
|
|
.el .Sh "\f(CWev_prepare\fP and \f(CWev_check\fP \- customise your event loop" |
1168 |
|
|
.IX Subsection "ev_prepare and ev_check - customise your event loop" |
1169 |
|
|
Prepare and check watchers are usually (but not always) used in tandem: |
1170 |
|
|
prepare watchers get invoked before the process blocks and check watchers |
1171 |
|
|
afterwards. |
1172 |
|
|
.PP |
1173 |
root |
1.10 |
Their main purpose is to integrate other event mechanisms into libev and |
1174 |
|
|
their use is somewhat advanced. This could be used, for example, to track |
1175 |
|
|
variable changes, implement your own watchers, integrate net-snmp or a |
1176 |
|
|
coroutine library and lots more. |
1177 |
root |
1.1 |
.PP |
1178 |
|
|
This is done by examining in each prepare call which file descriptors need |
1179 |
|
|
to be watched by the other library, registering \f(CW\*(C`ev_io\*(C'\fR watchers for |
1180 |
|
|
them and starting an \f(CW\*(C`ev_timer\*(C'\fR watcher for any timeouts (many libraries |
1181 |
|
|
provide just this functionality). Then, in the check watcher you check for |
1182 |
|
|
any events that occured (by checking the pending status of all watchers |
1183 |
|
|
and stopping them) and call back into the library. The I/O and timer |
1184 |
|
|
callbacks will never actually be called (but must be valid nevertheless, |
1185 |
|
|
because you never know, you know?). |
1186 |
|
|
.PP |
1187 |
|
|
As another example, the Perl Coro module uses these hooks to integrate |
1188 |
|
|
coroutines into libev programs, by yielding to other active coroutines |
1189 |
|
|
during each prepare and only letting the process block if no coroutines |
1190 |
|
|
are ready to run (it's actually more complicated: it only runs coroutines |
1191 |
|
|
with priority higher than or equal to the event loop and one coroutine |
1192 |
|
|
of lower priority, but only once, using idle watchers to keep the event |
1193 |
|
|
loop from blocking if lower-priority coroutines are active, thus mapping |
1194 |
|
|
low-priority coroutines to idle/background tasks). |
1195 |
|
|
.IP "ev_prepare_init (ev_prepare *, callback)" 4 |
1196 |
|
|
.IX Item "ev_prepare_init (ev_prepare *, callback)" |
1197 |
|
|
.PD 0 |
1198 |
|
|
.IP "ev_check_init (ev_check *, callback)" 4 |
1199 |
|
|
.IX Item "ev_check_init (ev_check *, callback)" |
1200 |
|
|
.PD |
1201 |
|
|
Initialises and configures the prepare or check watcher \- they have no |
1202 |
|
|
parameters of any kind. There are \f(CW\*(C`ev_prepare_set\*(C'\fR and \f(CW\*(C`ev_check_set\*(C'\fR |
1203 |
|
|
macros, but using them is utterly, utterly and completely pointless. |
1204 |
root |
1.9 |
.PP |
1205 |
|
|
Example: *TODO*. |
1206 |
root |
1.10 |
.ie n .Sh """ev_embed"" \- when one backend isn't enough" |
1207 |
|
|
.el .Sh "\f(CWev_embed\fP \- when one backend isn't enough" |
1208 |
|
|
.IX Subsection "ev_embed - when one backend isn't enough" |
1209 |
|
|
This is a rather advanced watcher type that lets you embed one event loop |
1210 |
|
|
into another. |
1211 |
|
|
.PP |
1212 |
|
|
There are primarily two reasons you would want that: work around bugs and |
1213 |
|
|
prioritise I/O. |
1214 |
|
|
.PP |
1215 |
|
|
As an example for a bug workaround, the kqueue backend might only support |
1216 |
|
|
sockets on some platform, so it is unusable as generic backend, but you |
1217 |
|
|
still want to make use of it because you have many sockets and it scales |
1218 |
|
|
so nicely. In this case, you would create a kqueue-based loop and embed it |
1219 |
|
|
into your default loop (which might use e.g. poll). Overall operation will |
1220 |
|
|
be a bit slower because first libev has to poll and then call kevent, but |
1221 |
|
|
at least you can use both at what they are best. |
1222 |
|
|
.PP |
1223 |
|
|
As for prioritising I/O: rarely you have the case where some fds have |
1224 |
|
|
to be watched and handled very quickly (with low latency), and even |
1225 |
|
|
priorities and idle watchers might have too much overhead. In this case |
1226 |
|
|
you would put all the high priority stuff in one loop and all the rest in |
1227 |
|
|
a second one, and embed the second one in the first. |
1228 |
|
|
.PP |
1229 |
|
|
As long as the watcher is started it will automatically handle events. The |
1230 |
|
|
callback will be invoked whenever some events have been handled. You can |
1231 |
|
|
set the callback to \f(CW0\fR to avoid having to specify one if you are not |
1232 |
|
|
interested in that. |
1233 |
|
|
.PP |
1234 |
|
|
Also, there have not currently been made special provisions for forking: |
1235 |
|
|
when you fork, you not only have to call \f(CW\*(C`ev_loop_fork\*(C'\fR on both loops, |
1236 |
|
|
but you will also have to stop and restart any \f(CW\*(C`ev_embed\*(C'\fR watchers |
1237 |
|
|
yourself. |
1238 |
|
|
.PP |
1239 |
|
|
Unfortunately, not all backends are embeddable, only the ones returned by |
1240 |
|
|
\&\f(CW\*(C`ev_embeddable_backends\*(C'\fR are, which, unfortunately, does not include any |
1241 |
|
|
portable one. |
1242 |
|
|
.PP |
1243 |
|
|
So when you want to use this feature you will always have to be prepared |
1244 |
|
|
that you cannot get an embeddable loop. The recommended way to get around |
1245 |
|
|
this is to have a separate variables for your embeddable loop, try to |
1246 |
|
|
create it, and if that fails, use the normal loop for everything: |
1247 |
|
|
.PP |
1248 |
|
|
.Vb 3 |
1249 |
|
|
\& struct ev_loop *loop_hi = ev_default_init (0); |
1250 |
|
|
\& struct ev_loop *loop_lo = 0; |
1251 |
|
|
\& struct ev_embed embed; |
1252 |
|
|
.Ve |
1253 |
|
|
.PP |
1254 |
|
|
.Vb 5 |
1255 |
|
|
\& // see if there is a chance of getting one that works |
1256 |
|
|
\& // (remember that a flags value of 0 means autodetection) |
1257 |
|
|
\& loop_lo = ev_embeddable_backends () & ev_recommended_backends () |
1258 |
|
|
\& ? ev_loop_new (ev_embeddable_backends () & ev_recommended_backends ()) |
1259 |
|
|
\& : 0; |
1260 |
|
|
.Ve |
1261 |
|
|
.PP |
1262 |
|
|
.Vb 8 |
1263 |
|
|
\& // if we got one, then embed it, otherwise default to loop_hi |
1264 |
|
|
\& if (loop_lo) |
1265 |
|
|
\& { |
1266 |
|
|
\& ev_embed_init (&embed, 0, loop_lo); |
1267 |
|
|
\& ev_embed_start (loop_hi, &embed); |
1268 |
|
|
\& } |
1269 |
|
|
\& else |
1270 |
|
|
\& loop_lo = loop_hi; |
1271 |
|
|
.Ve |
1272 |
|
|
.IP "ev_embed_init (ev_embed *, callback, struct ev_loop *loop)" 4 |
1273 |
|
|
.IX Item "ev_embed_init (ev_embed *, callback, struct ev_loop *loop)" |
1274 |
|
|
.PD 0 |
1275 |
|
|
.IP "ev_embed_set (ev_embed *, callback, struct ev_loop *loop)" 4 |
1276 |
|
|
.IX Item "ev_embed_set (ev_embed *, callback, struct ev_loop *loop)" |
1277 |
|
|
.PD |
1278 |
|
|
Configures the watcher to embed the given loop, which must be embeddable. |
1279 |
root |
1.1 |
.SH "OTHER FUNCTIONS" |
1280 |
|
|
.IX Header "OTHER FUNCTIONS" |
1281 |
|
|
There are some other functions of possible interest. Described. Here. Now. |
1282 |
|
|
.IP "ev_once (loop, int fd, int events, ev_tstamp timeout, callback)" 4 |
1283 |
|
|
.IX Item "ev_once (loop, int fd, int events, ev_tstamp timeout, callback)" |
1284 |
|
|
This function combines a simple timer and an I/O watcher, calls your |
1285 |
|
|
callback on whichever event happens first and automatically stop both |
1286 |
|
|
watchers. This is useful if you want to wait for a single event on an fd |
1287 |
|
|
or timeout without having to allocate/configure/start/stop/free one or |
1288 |
|
|
more watchers yourself. |
1289 |
|
|
.Sp |
1290 |
|
|
If \f(CW\*(C`fd\*(C'\fR is less than 0, then no I/O watcher will be started and events |
1291 |
|
|
is being ignored. Otherwise, an \f(CW\*(C`ev_io\*(C'\fR watcher for the given \f(CW\*(C`fd\*(C'\fR and |
1292 |
|
|
\&\f(CW\*(C`events\*(C'\fR set will be craeted and started. |
1293 |
|
|
.Sp |
1294 |
|
|
If \f(CW\*(C`timeout\*(C'\fR is less than 0, then no timeout watcher will be |
1295 |
|
|
started. Otherwise an \f(CW\*(C`ev_timer\*(C'\fR watcher with after = \f(CW\*(C`timeout\*(C'\fR (and |
1296 |
|
|
repeat = 0) will be started. While \f(CW0\fR is a valid timeout, it is of |
1297 |
|
|
dubious value. |
1298 |
|
|
.Sp |
1299 |
|
|
The callback has the type \f(CW\*(C`void (*cb)(int revents, void *arg)\*(C'\fR and gets |
1300 |
|
|
passed an \f(CW\*(C`revents\*(C'\fR set like normal event callbacks (a combination of |
1301 |
|
|
\&\f(CW\*(C`EV_ERROR\*(C'\fR, \f(CW\*(C`EV_READ\*(C'\fR, \f(CW\*(C`EV_WRITE\*(C'\fR or \f(CW\*(C`EV_TIMEOUT\*(C'\fR) and the \f(CW\*(C`arg\*(C'\fR |
1302 |
|
|
value passed to \f(CW\*(C`ev_once\*(C'\fR: |
1303 |
|
|
.Sp |
1304 |
|
|
.Vb 7 |
1305 |
|
|
\& static void stdin_ready (int revents, void *arg) |
1306 |
|
|
\& { |
1307 |
|
|
\& if (revents & EV_TIMEOUT) |
1308 |
|
|
\& /* doh, nothing entered */; |
1309 |
|
|
\& else if (revents & EV_READ) |
1310 |
|
|
\& /* stdin might have data for us, joy! */; |
1311 |
|
|
\& } |
1312 |
|
|
.Ve |
1313 |
|
|
.Sp |
1314 |
|
|
.Vb 1 |
1315 |
|
|
\& ev_once (STDIN_FILENO, EV_READ, 10., stdin_ready, 0); |
1316 |
|
|
.Ve |
1317 |
|
|
.IP "ev_feed_event (loop, watcher, int events)" 4 |
1318 |
|
|
.IX Item "ev_feed_event (loop, watcher, int events)" |
1319 |
|
|
Feeds the given event set into the event loop, as if the specified event |
1320 |
|
|
had happened for the specified watcher (which must be a pointer to an |
1321 |
|
|
initialised but not necessarily started event watcher). |
1322 |
|
|
.IP "ev_feed_fd_event (loop, int fd, int revents)" 4 |
1323 |
|
|
.IX Item "ev_feed_fd_event (loop, int fd, int revents)" |
1324 |
|
|
Feed an event on the given fd, as if a file descriptor backend detected |
1325 |
|
|
the given events it. |
1326 |
|
|
.IP "ev_feed_signal_event (loop, int signum)" 4 |
1327 |
|
|
.IX Item "ev_feed_signal_event (loop, int signum)" |
1328 |
|
|
Feed an event as if the given signal occured (loop must be the default loop!). |
1329 |
|
|
.SH "LIBEVENT EMULATION" |
1330 |
|
|
.IX Header "LIBEVENT EMULATION" |
1331 |
|
|
Libev offers a compatibility emulation layer for libevent. It cannot |
1332 |
|
|
emulate the internals of libevent, so here are some usage hints: |
1333 |
|
|
.IP "* Use it by including <event.h>, as usual." 4 |
1334 |
|
|
.IX Item "Use it by including <event.h>, as usual." |
1335 |
|
|
.PD 0 |
1336 |
|
|
.IP "* The following members are fully supported: ev_base, ev_callback, ev_arg, ev_fd, ev_res, ev_events." 4 |
1337 |
|
|
.IX Item "The following members are fully supported: ev_base, ev_callback, ev_arg, ev_fd, ev_res, ev_events." |
1338 |
|
|
.IP "* Avoid using ev_flags and the EVLIST_*\-macros, while it is maintained by libev, it does not work exactly the same way as in libevent (consider it a private \s-1API\s0)." 4 |
1339 |
|
|
.IX Item "Avoid using ev_flags and the EVLIST_*-macros, while it is maintained by libev, it does not work exactly the same way as in libevent (consider it a private API)." |
1340 |
|
|
.IP "* Priorities are not currently supported. Initialising priorities will fail and all watchers will have the same priority, even though there is an ev_pri field." 4 |
1341 |
|
|
.IX Item "Priorities are not currently supported. Initialising priorities will fail and all watchers will have the same priority, even though there is an ev_pri field." |
1342 |
|
|
.IP "* Other members are not supported." 4 |
1343 |
|
|
.IX Item "Other members are not supported." |
1344 |
|
|
.IP "* The libev emulation is \fInot\fR \s-1ABI\s0 compatible to libevent, you need to use the libev header file and library." 4 |
1345 |
|
|
.IX Item "The libev emulation is not ABI compatible to libevent, you need to use the libev header file and library." |
1346 |
|
|
.PD |
1347 |
|
|
.SH "\*(C+ SUPPORT" |
1348 |
|
|
.IX Header " SUPPORT" |
1349 |
|
|
\&\s-1TBD\s0. |
1350 |
|
|
.SH "AUTHOR" |
1351 |
|
|
.IX Header "AUTHOR" |
1352 |
|
|
Marc Lehmann <libev@schmorp.de>. |