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 |
.TH "<STANDARD INPUT>" 1 "2007-11-23" "perl v5.8.8" "User Contributed Perl Documentation" |
133 |
.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 |
to the double type in C. |
179 |
.SH "GLOBAL FUNCTIONS" |
180 |
.IX Header "GLOBAL FUNCTIONS" |
181 |
These functions can be called anytime, even before initialising the |
182 |
library in any way. |
183 |
.IP "ev_tstamp ev_time ()" 4 |
184 |
.IX Item "ev_tstamp ev_time ()" |
185 |
Returns the current time as libev would use it. Please note that the |
186 |
\&\f(CW\*(C`ev_now\*(C'\fR function is usually faster and also often returns the timestamp |
187 |
you actually want to know. |
188 |
.IP "int ev_version_major ()" 4 |
189 |
.IX Item "int ev_version_major ()" |
190 |
.PD 0 |
191 |
.IP "int ev_version_minor ()" 4 |
192 |
.IX Item "int ev_version_minor ()" |
193 |
.PD |
194 |
You can find out the major and minor version numbers of the library |
195 |
you linked against by calling the functions \f(CW\*(C`ev_version_major\*(C'\fR and |
196 |
\&\f(CW\*(C`ev_version_minor\*(C'\fR. If you want, you can compare against the global |
197 |
symbols \f(CW\*(C`EV_VERSION_MAJOR\*(C'\fR and \f(CW\*(C`EV_VERSION_MINOR\*(C'\fR, which specify the |
198 |
version of the library your program was compiled against. |
199 |
.Sp |
200 |
Usually, it's a good idea to terminate if the major versions mismatch, |
201 |
as this indicates an incompatible change. Minor versions are usually |
202 |
compatible to older versions, so a larger minor version alone is usually |
203 |
not a problem. |
204 |
.IP "unsigned int ev_supported_backends ()" 4 |
205 |
.IX Item "unsigned int ev_supported_backends ()" |
206 |
Return the set of all backends (i.e. their corresponding \f(CW\*(C`EV_BACKEND_*\*(C'\fR |
207 |
value) compiled into this binary of libev (independent of their |
208 |
availability on the system you are running on). See \f(CW\*(C`ev_default_loop\*(C'\fR for |
209 |
a description of the set values. |
210 |
.IP "unsigned int ev_recommended_backends ()" 4 |
211 |
.IX Item "unsigned int ev_recommended_backends ()" |
212 |
Return the set of all backends compiled into this binary of libev and also |
213 |
recommended for this platform. This set is often smaller than the one |
214 |
returned by \f(CW\*(C`ev_supported_backends\*(C'\fR, as for example kqueue is broken on |
215 |
most BSDs and will not be autodetected unless you explicitly request it |
216 |
(assuming you know what you are doing). This is the set of backends that |
217 |
libev will probe for if you specify no backends explicitly. |
218 |
.IP "ev_set_allocator (void *(*cb)(void *ptr, long size))" 4 |
219 |
.IX Item "ev_set_allocator (void *(*cb)(void *ptr, long size))" |
220 |
Sets the allocation function to use (the prototype is similar to the |
221 |
realloc C function, the semantics are identical). It is used to allocate |
222 |
and free memory (no surprises here). If it returns zero when memory |
223 |
needs to be allocated, the library might abort or take some potentially |
224 |
destructive action. The default is your system realloc function. |
225 |
.Sp |
226 |
You could override this function in high-availability programs to, say, |
227 |
free some memory if it cannot allocate memory, to use a special allocator, |
228 |
or even to sleep a while and retry until some memory is available. |
229 |
.IP "ev_set_syserr_cb (void (*cb)(const char *msg));" 4 |
230 |
.IX Item "ev_set_syserr_cb (void (*cb)(const char *msg));" |
231 |
Set the callback function to call on a retryable syscall error (such |
232 |
as failed select, poll, epoll_wait). The message is a printable string |
233 |
indicating the system call or subsystem causing the problem. If this |
234 |
callback is set, then libev will expect it to remedy the sitution, no |
235 |
matter what, when it returns. That is, libev will generally retry the |
236 |
requested operation, or, if the condition doesn't go away, do bad stuff |
237 |
(such as abort). |
238 |
.SH "FUNCTIONS CONTROLLING THE EVENT LOOP" |
239 |
.IX Header "FUNCTIONS CONTROLLING THE EVENT LOOP" |
240 |
An event loop is described by a \f(CW\*(C`struct ev_loop *\*(C'\fR. The library knows two |
241 |
types of such loops, the \fIdefault\fR loop, which supports signals and child |
242 |
events, and dynamically created loops which do not. |
243 |
.PP |
244 |
If you use threads, a common model is to run the default event loop |
245 |
in your main thread (or in a separate thread) and for each thread you |
246 |
create, you also create another event loop. Libev itself does no locking |
247 |
whatsoever, so if you mix calls to the same event loop in different |
248 |
threads, make sure you lock (this is usually a bad idea, though, even if |
249 |
done correctly, because it's hideous and inefficient). |
250 |
.IP "struct ev_loop *ev_default_loop (unsigned int flags)" 4 |
251 |
.IX Item "struct ev_loop *ev_default_loop (unsigned int flags)" |
252 |
This will initialise the default event loop if it hasn't been initialised |
253 |
yet and return it. If the default loop could not be initialised, returns |
254 |
false. If it already was initialised it simply returns it (and ignores the |
255 |
flags. If that is troubling you, check \f(CW\*(C`ev_backend ()\*(C'\fR afterwards). |
256 |
.Sp |
257 |
If you don't know what event loop to use, use the one returned from this |
258 |
function. |
259 |
.Sp |
260 |
The flags argument can be used to specify special behaviour or specific |
261 |
backends to use, and is usually specified as \f(CW0\fR (or \f(CW\*(C`EVFLAG_AUTO\*(C'\fR). |
262 |
.Sp |
263 |
The following flags are supported: |
264 |
.RS 4 |
265 |
.ie n .IP """EVFLAG_AUTO""" 4 |
266 |
.el .IP "\f(CWEVFLAG_AUTO\fR" 4 |
267 |
.IX Item "EVFLAG_AUTO" |
268 |
The default flags value. Use this if you have no clue (it's the right |
269 |
thing, believe me). |
270 |
.ie n .IP """EVFLAG_NOENV""" 4 |
271 |
.el .IP "\f(CWEVFLAG_NOENV\fR" 4 |
272 |
.IX Item "EVFLAG_NOENV" |
273 |
If this flag bit is ored into the flag value (or the program runs setuid |
274 |
or setgid) then libev will \fInot\fR look at the environment variable |
275 |
\&\f(CW\*(C`LIBEV_FLAGS\*(C'\fR. Otherwise (the default), this environment variable will |
276 |
override the flags completely if it is found in the environment. This is |
277 |
useful to try out specific backends to test their performance, or to work |
278 |
around bugs. |
279 |
.ie n .IP """EVBACKEND_SELECT"" (value 1, portable select backend)" 4 |
280 |
.el .IP "\f(CWEVBACKEND_SELECT\fR (value 1, portable select backend)" 4 |
281 |
.IX Item "EVBACKEND_SELECT (value 1, portable select backend)" |
282 |
This is your standard \fIselect\fR\|(2) backend. Not \fIcompletely\fR standard, as |
283 |
libev tries to roll its own fd_set with no limits on the number of fds, |
284 |
but if that fails, expect a fairly low limit on the number of fds when |
285 |
using this backend. It doesn't scale too well (O(highest_fd)), but its usually |
286 |
the fastest backend for a low number of fds. |
287 |
.ie n .IP """EVBACKEND_POLL"" (value 2, poll backend, available everywhere except on windows)" 4 |
288 |
.el .IP "\f(CWEVBACKEND_POLL\fR (value 2, poll backend, available everywhere except on windows)" 4 |
289 |
.IX Item "EVBACKEND_POLL (value 2, poll backend, available everywhere except on windows)" |
290 |
And this is your standard \fIpoll\fR\|(2) backend. It's more complicated than |
291 |
select, but handles sparse fds better and has no artificial limit on the |
292 |
number of fds you can use (except it will slow down considerably with a |
293 |
lot of inactive fds). It scales similarly to select, i.e. O(total_fds). |
294 |
.ie n .IP """EVBACKEND_EPOLL"" (value 4, Linux)" 4 |
295 |
.el .IP "\f(CWEVBACKEND_EPOLL\fR (value 4, Linux)" 4 |
296 |
.IX Item "EVBACKEND_EPOLL (value 4, Linux)" |
297 |
For few fds, this backend is a bit little slower than poll and select, |
298 |
but it scales phenomenally better. While poll and select usually scale like |
299 |
O(total_fds) where n is the total number of fds (or the highest fd), epoll scales |
300 |
either O(1) or O(active_fds). |
301 |
.Sp |
302 |
While stopping and starting an I/O watcher in the same iteration will |
303 |
result in some caching, there is still a syscall per such incident |
304 |
(because the fd could point to a different file description now), so its |
305 |
best to avoid that. Also, \fIdup()\fRed file descriptors might not work very |
306 |
well if you register events for both fds. |
307 |
.Sp |
308 |
Please note that epoll sometimes generates spurious notifications, so you |
309 |
need to use non-blocking I/O or other means to avoid blocking when no data |
310 |
(or space) is available. |
311 |
.ie n .IP """EVBACKEND_KQUEUE"" (value 8, most \s-1BSD\s0 clones)" 4 |
312 |
.el .IP "\f(CWEVBACKEND_KQUEUE\fR (value 8, most \s-1BSD\s0 clones)" 4 |
313 |
.IX Item "EVBACKEND_KQUEUE (value 8, most BSD clones)" |
314 |
Kqueue deserves special mention, as at the time of this writing, it |
315 |
was broken on all BSDs except NetBSD (usually it doesn't work with |
316 |
anything but sockets and pipes, except on Darwin, where of course its |
317 |
completely useless). For this reason its not being \*(L"autodetected\*(R" |
318 |
unless you explicitly specify it explicitly in the flags (i.e. using |
319 |
\&\f(CW\*(C`EVBACKEND_KQUEUE\*(C'\fR). |
320 |
.Sp |
321 |
It scales in the same way as the epoll backend, but the interface to the |
322 |
kernel is more efficient (which says nothing about its actual speed, of |
323 |
course). While starting and stopping an I/O watcher does not cause an |
324 |
extra syscall as with epoll, it still adds up to four event changes per |
325 |
incident, so its best to avoid that. |
326 |
.ie n .IP """EVBACKEND_DEVPOLL"" (value 16, Solaris 8)" 4 |
327 |
.el .IP "\f(CWEVBACKEND_DEVPOLL\fR (value 16, Solaris 8)" 4 |
328 |
.IX Item "EVBACKEND_DEVPOLL (value 16, Solaris 8)" |
329 |
This is not implemented yet (and might never be). |
330 |
.ie n .IP """EVBACKEND_PORT"" (value 32, Solaris 10)" 4 |
331 |
.el .IP "\f(CWEVBACKEND_PORT\fR (value 32, Solaris 10)" 4 |
332 |
.IX Item "EVBACKEND_PORT (value 32, Solaris 10)" |
333 |
This uses the Solaris 10 port mechanism. As with everything on Solaris, |
334 |
it's really slow, but it still scales very well (O(active_fds)). |
335 |
.Sp |
336 |
Please note that solaris ports can result in a lot of spurious |
337 |
notifications, so you need to use non-blocking I/O or other means to avoid |
338 |
blocking when no data (or space) is available. |
339 |
.ie n .IP """EVBACKEND_ALL""" 4 |
340 |
.el .IP "\f(CWEVBACKEND_ALL\fR" 4 |
341 |
.IX Item "EVBACKEND_ALL" |
342 |
Try all backends (even potentially broken ones that wouldn't be tried |
343 |
with \f(CW\*(C`EVFLAG_AUTO\*(C'\fR). Since this is a mask, you can do stuff such as |
344 |
\&\f(CW\*(C`EVBACKEND_ALL & ~EVBACKEND_KQUEUE\*(C'\fR. |
345 |
.RE |
346 |
.RS 4 |
347 |
.Sp |
348 |
If one or more of these are ored into the flags value, then only these |
349 |
backends will be tried (in the reverse order as given here). If none are |
350 |
specified, most compiled-in backend will be tried, usually in reverse |
351 |
order of their flag values :) |
352 |
.Sp |
353 |
The most typical usage is like this: |
354 |
.Sp |
355 |
.Vb 2 |
356 |
\& if (!ev_default_loop (0)) |
357 |
\& fatal ("could not initialise libev, bad $LIBEV_FLAGS in environment?"); |
358 |
.Ve |
359 |
.Sp |
360 |
Restrict libev to the select and poll backends, and do not allow |
361 |
environment settings to be taken into account: |
362 |
.Sp |
363 |
.Vb 1 |
364 |
\& ev_default_loop (EVBACKEND_POLL | EVBACKEND_SELECT | EVFLAG_NOENV); |
365 |
.Ve |
366 |
.Sp |
367 |
Use whatever libev has to offer, but make sure that kqueue is used if |
368 |
available (warning, breaks stuff, best use only with your own private |
369 |
event loop and only if you know the \s-1OS\s0 supports your types of fds): |
370 |
.Sp |
371 |
.Vb 1 |
372 |
\& ev_default_loop (ev_recommended_backends () | EVBACKEND_KQUEUE); |
373 |
.Ve |
374 |
.RE |
375 |
.IP "struct ev_loop *ev_loop_new (unsigned int flags)" 4 |
376 |
.IX Item "struct ev_loop *ev_loop_new (unsigned int flags)" |
377 |
Similar to \f(CW\*(C`ev_default_loop\*(C'\fR, but always creates a new event loop that is |
378 |
always distinct from the default loop. Unlike the default loop, it cannot |
379 |
handle signal and child watchers, and attempts to do so will be greeted by |
380 |
undefined behaviour (or a failed assertion if assertions are enabled). |
381 |
.IP "ev_default_destroy ()" 4 |
382 |
.IX Item "ev_default_destroy ()" |
383 |
Destroys the default loop again (frees all memory and kernel state |
384 |
etc.). This stops all registered event watchers (by not touching them in |
385 |
any way whatsoever, although you cannot rely on this :). |
386 |
.IP "ev_loop_destroy (loop)" 4 |
387 |
.IX Item "ev_loop_destroy (loop)" |
388 |
Like \f(CW\*(C`ev_default_destroy\*(C'\fR, but destroys an event loop created by an |
389 |
earlier call to \f(CW\*(C`ev_loop_new\*(C'\fR. |
390 |
.IP "ev_default_fork ()" 4 |
391 |
.IX Item "ev_default_fork ()" |
392 |
This function reinitialises the kernel state for backends that have |
393 |
one. Despite the name, you can call it anytime, but it makes most sense |
394 |
after forking, in either the parent or child process (or both, but that |
395 |
again makes little sense). |
396 |
.Sp |
397 |
You \fImust\fR call this function in the child process after forking if and |
398 |
only if you want to use the event library in both processes. If you just |
399 |
fork+exec, you don't have to call it. |
400 |
.Sp |
401 |
The function itself is quite fast and it's usually not a problem to call |
402 |
it just in case after a fork. To make this easy, the function will fit in |
403 |
quite nicely into a call to \f(CW\*(C`pthread_atfork\*(C'\fR: |
404 |
.Sp |
405 |
.Vb 1 |
406 |
\& pthread_atfork (0, 0, ev_default_fork); |
407 |
.Ve |
408 |
.Sp |
409 |
At the moment, \f(CW\*(C`EVBACKEND_SELECT\*(C'\fR and \f(CW\*(C`EVBACKEND_POLL\*(C'\fR are safe to use |
410 |
without calling this function, so if you force one of those backends you |
411 |
do not need to care. |
412 |
.IP "ev_loop_fork (loop)" 4 |
413 |
.IX Item "ev_loop_fork (loop)" |
414 |
Like \f(CW\*(C`ev_default_fork\*(C'\fR, but acts on an event loop created by |
415 |
\&\f(CW\*(C`ev_loop_new\*(C'\fR. Yes, you have to call this on every allocated event loop |
416 |
after fork, and how you do this is entirely your own problem. |
417 |
.IP "unsigned int ev_backend (loop)" 4 |
418 |
.IX Item "unsigned int ev_backend (loop)" |
419 |
Returns one of the \f(CW\*(C`EVBACKEND_*\*(C'\fR flags indicating the event backend in |
420 |
use. |
421 |
.IP "ev_tstamp ev_now (loop)" 4 |
422 |
.IX Item "ev_tstamp ev_now (loop)" |
423 |
Returns the current \*(L"event loop time\*(R", which is the time the event loop |
424 |
got events and started processing them. This timestamp does not change |
425 |
as long as callbacks are being processed, and this is also the base time |
426 |
used for relative timers. You can treat it as the timestamp of the event |
427 |
occuring (or more correctly, the mainloop finding out about it). |
428 |
.IP "ev_loop (loop, int flags)" 4 |
429 |
.IX Item "ev_loop (loop, int flags)" |
430 |
Finally, this is it, the event handler. This function usually is called |
431 |
after you initialised all your watchers and you want to start handling |
432 |
events. |
433 |
.Sp |
434 |
If the flags argument is specified as \f(CW0\fR, it will not return until |
435 |
either no event watchers are active anymore or \f(CW\*(C`ev_unloop\*(C'\fR was called. |
436 |
.Sp |
437 |
A flags value of \f(CW\*(C`EVLOOP_NONBLOCK\*(C'\fR will look for new events, will handle |
438 |
those events and any outstanding ones, but will not block your process in |
439 |
case there are no events and will return after one iteration of the loop. |
440 |
.Sp |
441 |
A flags value of \f(CW\*(C`EVLOOP_ONESHOT\*(C'\fR will look for new events (waiting if |
442 |
neccessary) and will handle those and any outstanding ones. It will block |
443 |
your process until at least one new event arrives, and will return after |
444 |
one iteration of the loop. This is useful if you are waiting for some |
445 |
external event in conjunction with something not expressible using other |
446 |
libev watchers. However, a pair of \f(CW\*(C`ev_prepare\*(C'\fR/\f(CW\*(C`ev_check\*(C'\fR watchers is |
447 |
usually a better approach for this kind of thing. |
448 |
.Sp |
449 |
Here are the gory details of what \f(CW\*(C`ev_loop\*(C'\fR does: |
450 |
.Sp |
451 |
.Vb 18 |
452 |
\& * If there are no active watchers (reference count is zero), return. |
453 |
\& - Queue prepare watchers and then call all outstanding watchers. |
454 |
\& - If we have been forked, recreate the kernel state. |
455 |
\& - Update the kernel state with all outstanding changes. |
456 |
\& - Update the "event loop time". |
457 |
\& - Calculate for how long to block. |
458 |
\& - Block the process, waiting for any events. |
459 |
\& - Queue all outstanding I/O (fd) events. |
460 |
\& - Update the "event loop time" and do time jump handling. |
461 |
\& - Queue all outstanding timers. |
462 |
\& - Queue all outstanding periodics. |
463 |
\& - If no events are pending now, queue all idle watchers. |
464 |
\& - Queue all check watchers. |
465 |
\& - Call all queued watchers in reverse order (i.e. check watchers first). |
466 |
\& Signals and child watchers are implemented as I/O watchers, and will |
467 |
\& be handled here by queueing them when their watcher gets executed. |
468 |
\& - If ev_unloop has been called or EVLOOP_ONESHOT or EVLOOP_NONBLOCK |
469 |
\& were used, return, otherwise continue with step *. |
470 |
.Ve |
471 |
.IP "ev_unloop (loop, how)" 4 |
472 |
.IX Item "ev_unloop (loop, how)" |
473 |
Can be used to make a call to \f(CW\*(C`ev_loop\*(C'\fR return early (but only after it |
474 |
has processed all outstanding events). The \f(CW\*(C`how\*(C'\fR argument must be either |
475 |
\&\f(CW\*(C`EVUNLOOP_ONE\*(C'\fR, which will make the innermost \f(CW\*(C`ev_loop\*(C'\fR call return, or |
476 |
\&\f(CW\*(C`EVUNLOOP_ALL\*(C'\fR, which will make all nested \f(CW\*(C`ev_loop\*(C'\fR calls return. |
477 |
.IP "ev_ref (loop)" 4 |
478 |
.IX Item "ev_ref (loop)" |
479 |
.PD 0 |
480 |
.IP "ev_unref (loop)" 4 |
481 |
.IX Item "ev_unref (loop)" |
482 |
.PD |
483 |
Ref/unref can be used to add or remove a reference count on the event |
484 |
loop: Every watcher keeps one reference, and as long as the reference |
485 |
count is nonzero, \f(CW\*(C`ev_loop\*(C'\fR will not return on its own. If you have |
486 |
a watcher you never unregister that should not keep \f(CW\*(C`ev_loop\*(C'\fR from |
487 |
returning, \fIev_unref()\fR after starting, and \fIev_ref()\fR before stopping it. For |
488 |
example, libev itself uses this for its internal signal pipe: It is not |
489 |
visible to the libev user and should not keep \f(CW\*(C`ev_loop\*(C'\fR from exiting if |
490 |
no event watchers registered by it are active. It is also an excellent |
491 |
way to do this for generic recurring timers or from within third-party |
492 |
libraries. Just remember to \fIunref after start\fR and \fIref before stop\fR. |
493 |
.SH "ANATOMY OF A WATCHER" |
494 |
.IX Header "ANATOMY OF A WATCHER" |
495 |
A watcher is a structure that you create and register to record your |
496 |
interest in some event. For instance, if you want to wait for \s-1STDIN\s0 to |
497 |
become readable, you would create an \f(CW\*(C`ev_io\*(C'\fR watcher for that: |
498 |
.PP |
499 |
.Vb 5 |
500 |
\& static void my_cb (struct ev_loop *loop, struct ev_io *w, int revents) |
501 |
\& { |
502 |
\& ev_io_stop (w); |
503 |
\& ev_unloop (loop, EVUNLOOP_ALL); |
504 |
\& } |
505 |
.Ve |
506 |
.PP |
507 |
.Vb 6 |
508 |
\& struct ev_loop *loop = ev_default_loop (0); |
509 |
\& struct ev_io stdin_watcher; |
510 |
\& ev_init (&stdin_watcher, my_cb); |
511 |
\& ev_io_set (&stdin_watcher, STDIN_FILENO, EV_READ); |
512 |
\& ev_io_start (loop, &stdin_watcher); |
513 |
\& ev_loop (loop, 0); |
514 |
.Ve |
515 |
.PP |
516 |
As you can see, you are responsible for allocating the memory for your |
517 |
watcher structures (and it is usually a bad idea to do this on the stack, |
518 |
although this can sometimes be quite valid). |
519 |
.PP |
520 |
Each watcher structure must be initialised by a call to \f(CW\*(C`ev_init |
521 |
(watcher *, callback)\*(C'\fR, which expects a callback to be provided. This |
522 |
callback gets invoked each time the event occurs (or, in the case of io |
523 |
watchers, each time the event loop detects that the file descriptor given |
524 |
is readable and/or writable). |
525 |
.PP |
526 |
Each watcher type has its own \f(CW\*(C`ev_<type>_set (watcher *, ...)\*(C'\fR macro |
527 |
with arguments specific to this watcher type. There is also a macro |
528 |
to combine initialisation and setting in one call: \f(CW\*(C`ev_<type>_init |
529 |
(watcher *, callback, ...)\*(C'\fR. |
530 |
.PP |
531 |
To make the watcher actually watch out for events, you have to start it |
532 |
with a watcher-specific start function (\f(CW\*(C`ev_<type>_start (loop, watcher |
533 |
*)\*(C'\fR), and you can stop watching for events at any time by calling the |
534 |
corresponding stop function (\f(CW\*(C`ev_<type>_stop (loop, watcher *)\*(C'\fR. |
535 |
.PP |
536 |
As long as your watcher is active (has been started but not stopped) you |
537 |
must not touch the values stored in it. Most specifically you must never |
538 |
reinitialise it or call its set macro. |
539 |
.PP |
540 |
You can check whether an event is active by calling the \f(CW\*(C`ev_is_active |
541 |
(watcher *)\*(C'\fR macro. To see whether an event is outstanding (but the |
542 |
callback for it has not been called yet) you can use the \f(CW\*(C`ev_is_pending |
543 |
(watcher *)\*(C'\fR macro. |
544 |
.PP |
545 |
Each and every callback receives the event loop pointer as first, the |
546 |
registered watcher structure as second, and a bitset of received events as |
547 |
third argument. |
548 |
.PP |
549 |
The received events usually include a single bit per event type received |
550 |
(you can receive multiple events at the same time). The possible bit masks |
551 |
are: |
552 |
.ie n .IP """EV_READ""" 4 |
553 |
.el .IP "\f(CWEV_READ\fR" 4 |
554 |
.IX Item "EV_READ" |
555 |
.PD 0 |
556 |
.ie n .IP """EV_WRITE""" 4 |
557 |
.el .IP "\f(CWEV_WRITE\fR" 4 |
558 |
.IX Item "EV_WRITE" |
559 |
.PD |
560 |
The file descriptor in the \f(CW\*(C`ev_io\*(C'\fR watcher has become readable and/or |
561 |
writable. |
562 |
.ie n .IP """EV_TIMEOUT""" 4 |
563 |
.el .IP "\f(CWEV_TIMEOUT\fR" 4 |
564 |
.IX Item "EV_TIMEOUT" |
565 |
The \f(CW\*(C`ev_timer\*(C'\fR watcher has timed out. |
566 |
.ie n .IP """EV_PERIODIC""" 4 |
567 |
.el .IP "\f(CWEV_PERIODIC\fR" 4 |
568 |
.IX Item "EV_PERIODIC" |
569 |
The \f(CW\*(C`ev_periodic\*(C'\fR watcher has timed out. |
570 |
.ie n .IP """EV_SIGNAL""" 4 |
571 |
.el .IP "\f(CWEV_SIGNAL\fR" 4 |
572 |
.IX Item "EV_SIGNAL" |
573 |
The signal specified in the \f(CW\*(C`ev_signal\*(C'\fR watcher has been received by a thread. |
574 |
.ie n .IP """EV_CHILD""" 4 |
575 |
.el .IP "\f(CWEV_CHILD\fR" 4 |
576 |
.IX Item "EV_CHILD" |
577 |
The pid specified in the \f(CW\*(C`ev_child\*(C'\fR watcher has received a status change. |
578 |
.ie n .IP """EV_IDLE""" 4 |
579 |
.el .IP "\f(CWEV_IDLE\fR" 4 |
580 |
.IX Item "EV_IDLE" |
581 |
The \f(CW\*(C`ev_idle\*(C'\fR watcher has determined that you have nothing better to do. |
582 |
.ie n .IP """EV_PREPARE""" 4 |
583 |
.el .IP "\f(CWEV_PREPARE\fR" 4 |
584 |
.IX Item "EV_PREPARE" |
585 |
.PD 0 |
586 |
.ie n .IP """EV_CHECK""" 4 |
587 |
.el .IP "\f(CWEV_CHECK\fR" 4 |
588 |
.IX Item "EV_CHECK" |
589 |
.PD |
590 |
All \f(CW\*(C`ev_prepare\*(C'\fR watchers are invoked just \fIbefore\fR \f(CW\*(C`ev_loop\*(C'\fR starts |
591 |
to gather new events, and all \f(CW\*(C`ev_check\*(C'\fR watchers are invoked just after |
592 |
\&\f(CW\*(C`ev_loop\*(C'\fR has gathered them, but before it invokes any callbacks for any |
593 |
received events. Callbacks of both watcher types can start and stop as |
594 |
many watchers as they want, and all of them will be taken into account |
595 |
(for example, a \f(CW\*(C`ev_prepare\*(C'\fR watcher might start an idle watcher to keep |
596 |
\&\f(CW\*(C`ev_loop\*(C'\fR from blocking). |
597 |
.ie n .IP """EV_ERROR""" 4 |
598 |
.el .IP "\f(CWEV_ERROR\fR" 4 |
599 |
.IX Item "EV_ERROR" |
600 |
An unspecified error has occured, the watcher has been stopped. This might |
601 |
happen because the watcher could not be properly started because libev |
602 |
ran out of memory, a file descriptor was found to be closed or any other |
603 |
problem. You best act on it by reporting the problem and somehow coping |
604 |
with the watcher being stopped. |
605 |
.Sp |
606 |
Libev will usually signal a few \*(L"dummy\*(R" events together with an error, |
607 |
for example it might indicate that a fd is readable or writable, and if |
608 |
your callbacks is well-written it can just attempt the operation and cope |
609 |
with the error from \fIread()\fR or \fIwrite()\fR. This will not work in multithreaded |
610 |
programs, though, so beware. |
611 |
.Sh "\s-1ASSOCIATING\s0 \s-1CUSTOM\s0 \s-1DATA\s0 \s-1WITH\s0 A \s-1WATCHER\s0" |
612 |
.IX Subsection "ASSOCIATING CUSTOM DATA WITH A WATCHER" |
613 |
Each watcher has, by default, a member \f(CW\*(C`void *data\*(C'\fR that you can change |
614 |
and read at any time, libev will completely ignore it. This can be used |
615 |
to associate arbitrary data with your watcher. If you need more data and |
616 |
don't want to allocate memory and store a pointer to it in that data |
617 |
member, you can also \*(L"subclass\*(R" the watcher type and provide your own |
618 |
data: |
619 |
.PP |
620 |
.Vb 7 |
621 |
\& struct my_io |
622 |
\& { |
623 |
\& struct ev_io io; |
624 |
\& int otherfd; |
625 |
\& void *somedata; |
626 |
\& struct whatever *mostinteresting; |
627 |
\& } |
628 |
.Ve |
629 |
.PP |
630 |
And since your callback will be called with a pointer to the watcher, you |
631 |
can cast it back to your own type: |
632 |
.PP |
633 |
.Vb 5 |
634 |
\& static void my_cb (struct ev_loop *loop, struct ev_io *w_, int revents) |
635 |
\& { |
636 |
\& struct my_io *w = (struct my_io *)w_; |
637 |
\& ... |
638 |
\& } |
639 |
.Ve |
640 |
.PP |
641 |
More interesting and less C\-conformant ways of catsing your callback type |
642 |
have been omitted.... |
643 |
.SH "WATCHER TYPES" |
644 |
.IX Header "WATCHER TYPES" |
645 |
This section describes each watcher in detail, but will not repeat |
646 |
information given in the last section. |
647 |
.ie n .Sh """ev_io"" \- is this file descriptor readable or writable" |
648 |
.el .Sh "\f(CWev_io\fP \- is this file descriptor readable or writable" |
649 |
.IX Subsection "ev_io - is this file descriptor readable or writable" |
650 |
I/O watchers check whether a file descriptor is readable or writable |
651 |
in each iteration of the event loop (This behaviour is called |
652 |
level-triggering because you keep receiving events as long as the |
653 |
condition persists. Remember you can stop the watcher if you don't want to |
654 |
act on the event and neither want to receive future events). |
655 |
.PP |
656 |
In general you can register as many read and/or write event watchers per |
657 |
fd as you want (as long as you don't confuse yourself). Setting all file |
658 |
descriptors to non-blocking mode is also usually a good idea (but not |
659 |
required if you know what you are doing). |
660 |
.PP |
661 |
You have to be careful with dup'ed file descriptors, though. Some backends |
662 |
(the linux epoll backend is a notable example) cannot handle dup'ed file |
663 |
descriptors correctly if you register interest in two or more fds pointing |
664 |
to the same underlying file/socket etc. description (that is, they share |
665 |
the same underlying \*(L"file open\*(R"). |
666 |
.PP |
667 |
If you must do this, then force the use of a known-to-be-good backend |
668 |
(at the time of this writing, this includes only \f(CW\*(C`EVBACKEND_SELECT\*(C'\fR and |
669 |
\&\f(CW\*(C`EVBACKEND_POLL\*(C'\fR). |
670 |
.IP "ev_io_init (ev_io *, callback, int fd, int events)" 4 |
671 |
.IX Item "ev_io_init (ev_io *, callback, int fd, int events)" |
672 |
.PD 0 |
673 |
.IP "ev_io_set (ev_io *, int fd, int events)" 4 |
674 |
.IX Item "ev_io_set (ev_io *, int fd, int events)" |
675 |
.PD |
676 |
Configures an \f(CW\*(C`ev_io\*(C'\fR watcher. The fd is the file descriptor to rceeive |
677 |
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 | |
678 |
EV_WRITE\*(C'\fR to receive the given events. |
679 |
.Sp |
680 |
Please note that most of the more scalable backend mechanisms (for example |
681 |
epoll and solaris ports) can result in spurious readyness notifications |
682 |
for file descriptors, so you practically need to use non-blocking I/O (and |
683 |
treat callback invocation as hint only), or retest separately with a safe |
684 |
interface before doing I/O (XLib can do this), or force the use of either |
685 |
\&\f(CW\*(C`EVBACKEND_SELECT\*(C'\fR or \f(CW\*(C`EVBACKEND_POLL\*(C'\fR, which don't suffer from this |
686 |
problem. Also note that it is quite easy to have your callback invoked |
687 |
when the readyness condition is no longer valid even when employing |
688 |
typical ways of handling events, so its a good idea to use non-blocking |
689 |
I/O unconditionally. |
690 |
.ie n .Sh """ev_timer"" \- relative and optionally recurring timeouts" |
691 |
.el .Sh "\f(CWev_timer\fP \- relative and optionally recurring timeouts" |
692 |
.IX Subsection "ev_timer - relative and optionally recurring timeouts" |
693 |
Timer watchers are simple relative timers that generate an event after a |
694 |
given time, and optionally repeating in regular intervals after that. |
695 |
.PP |
696 |
The timers are based on real time, that is, if you register an event that |
697 |
times out after an hour and you reset your system clock to last years |
698 |
time, it will still time out after (roughly) and hour. \*(L"Roughly\*(R" because |
699 |
detecting time jumps is hard, and some inaccuracies are unavoidable (the |
700 |
monotonic clock option helps a lot here). |
701 |
.PP |
702 |
The relative timeouts are calculated relative to the \f(CW\*(C`ev_now ()\*(C'\fR |
703 |
time. This is usually the right thing as this timestamp refers to the time |
704 |
of the event triggering whatever timeout you are modifying/starting. If |
705 |
you suspect event processing to be delayed and you \fIneed\fR to base the timeout |
706 |
on the current time, use something like this to adjust for this: |
707 |
.PP |
708 |
.Vb 1 |
709 |
\& ev_timer_set (&timer, after + ev_now () - ev_time (), 0.); |
710 |
.Ve |
711 |
.PP |
712 |
The callback is guarenteed to be invoked only when its timeout has passed, |
713 |
but if multiple timers become ready during the same loop iteration then |
714 |
order of execution is undefined. |
715 |
.IP "ev_timer_init (ev_timer *, callback, ev_tstamp after, ev_tstamp repeat)" 4 |
716 |
.IX Item "ev_timer_init (ev_timer *, callback, ev_tstamp after, ev_tstamp repeat)" |
717 |
.PD 0 |
718 |
.IP "ev_timer_set (ev_timer *, ev_tstamp after, ev_tstamp repeat)" 4 |
719 |
.IX Item "ev_timer_set (ev_timer *, ev_tstamp after, ev_tstamp repeat)" |
720 |
.PD |
721 |
Configure the timer to trigger after \f(CW\*(C`after\*(C'\fR seconds. If \f(CW\*(C`repeat\*(C'\fR is |
722 |
\&\f(CW0.\fR, then it will automatically be stopped. If it is positive, then the |
723 |
timer will automatically be configured to trigger again \f(CW\*(C`repeat\*(C'\fR seconds |
724 |
later, again, and again, until stopped manually. |
725 |
.Sp |
726 |
The timer itself will do a best-effort at avoiding drift, that is, if you |
727 |
configure a timer to trigger every 10 seconds, then it will trigger at |
728 |
exactly 10 second intervals. If, however, your program cannot keep up with |
729 |
the timer (because it takes longer than those 10 seconds to do stuff) the |
730 |
timer will not fire more than once per event loop iteration. |
731 |
.IP "ev_timer_again (loop)" 4 |
732 |
.IX Item "ev_timer_again (loop)" |
733 |
This will act as if the timer timed out and restart it again if it is |
734 |
repeating. The exact semantics are: |
735 |
.Sp |
736 |
If the timer is started but nonrepeating, stop it. |
737 |
.Sp |
738 |
If the timer is repeating, either start it if necessary (with the repeat |
739 |
value), or reset the running timer to the repeat value. |
740 |
.Sp |
741 |
This sounds a bit complicated, but here is a useful and typical |
742 |
example: Imagine you have a tcp connection and you want a so-called idle |
743 |
timeout, that is, you want to be called when there have been, say, 60 |
744 |
seconds of inactivity on the socket. The easiest way to do this is to |
745 |
configure an \f(CW\*(C`ev_timer\*(C'\fR with after=repeat=60 and calling ev_timer_again each |
746 |
time you successfully read or write some data. If you go into an idle |
747 |
state where you do not expect data to travel on the socket, you can stop |
748 |
the timer, and again will automatically restart it if need be. |
749 |
.ie n .Sh """ev_periodic"" \- to cron or not to cron" |
750 |
.el .Sh "\f(CWev_periodic\fP \- to cron or not to cron" |
751 |
.IX Subsection "ev_periodic - to cron or not to cron" |
752 |
Periodic watchers are also timers of a kind, but they are very versatile |
753 |
(and unfortunately a bit complex). |
754 |
.PP |
755 |
Unlike \f(CW\*(C`ev_timer\*(C'\fR's, they are not based on real time (or relative time) |
756 |
but on wallclock time (absolute time). You can tell a periodic watcher |
757 |
to trigger \*(L"at\*(R" some specific point in time. For example, if you tell a |
758 |
periodic watcher to trigger in 10 seconds (by specifiying e.g. c<ev_now () |
759 |
+ 10.>) and then reset your system clock to the last year, then it will |
760 |
take a year to trigger the event (unlike an \f(CW\*(C`ev_timer\*(C'\fR, which would trigger |
761 |
roughly 10 seconds later and of course not if you reset your system time |
762 |
again). |
763 |
.PP |
764 |
They can also be used to implement vastly more complex timers, such as |
765 |
triggering an event on eahc midnight, local time. |
766 |
.PP |
767 |
As with timers, the callback is guarenteed to be invoked only when the |
768 |
time (\f(CW\*(C`at\*(C'\fR) has been passed, but if multiple periodic timers become ready |
769 |
during the same loop iteration then order of execution is undefined. |
770 |
.IP "ev_periodic_init (ev_periodic *, callback, ev_tstamp at, ev_tstamp interval, reschedule_cb)" 4 |
771 |
.IX Item "ev_periodic_init (ev_periodic *, callback, ev_tstamp at, ev_tstamp interval, reschedule_cb)" |
772 |
.PD 0 |
773 |
.IP "ev_periodic_set (ev_periodic *, ev_tstamp after, ev_tstamp repeat, reschedule_cb)" 4 |
774 |
.IX Item "ev_periodic_set (ev_periodic *, ev_tstamp after, ev_tstamp repeat, reschedule_cb)" |
775 |
.PD |
776 |
Lots of arguments, lets sort it out... There are basically three modes of |
777 |
operation, and we will explain them from simplest to complex: |
778 |
.RS 4 |
779 |
.IP "* absolute timer (interval = reschedule_cb = 0)" 4 |
780 |
.IX Item "absolute timer (interval = reschedule_cb = 0)" |
781 |
In this configuration the watcher triggers an event at the wallclock time |
782 |
\&\f(CW\*(C`at\*(C'\fR and doesn't repeat. It will not adjust when a time jump occurs, |
783 |
that is, if it is to be run at January 1st 2011 then it will run when the |
784 |
system time reaches or surpasses this time. |
785 |
.IP "* non-repeating interval timer (interval > 0, reschedule_cb = 0)" 4 |
786 |
.IX Item "non-repeating interval timer (interval > 0, reschedule_cb = 0)" |
787 |
In this mode the watcher will always be scheduled to time out at the next |
788 |
\&\f(CW\*(C`at + N * interval\*(C'\fR time (for some integer N) and then repeat, regardless |
789 |
of any time jumps. |
790 |
.Sp |
791 |
This can be used to create timers that do not drift with respect to system |
792 |
time: |
793 |
.Sp |
794 |
.Vb 1 |
795 |
\& ev_periodic_set (&periodic, 0., 3600., 0); |
796 |
.Ve |
797 |
.Sp |
798 |
This doesn't mean there will always be 3600 seconds in between triggers, |
799 |
but only that the the callback will be called when the system time shows a |
800 |
full hour (\s-1UTC\s0), or more correctly, when the system time is evenly divisible |
801 |
by 3600. |
802 |
.Sp |
803 |
Another way to think about it (for the mathematically inclined) is that |
804 |
\&\f(CW\*(C`ev_periodic\*(C'\fR will try to run the callback in this mode at the next possible |
805 |
time where \f(CW\*(C`time = at (mod interval)\*(C'\fR, regardless of any time jumps. |
806 |
.IP "* manual reschedule mode (reschedule_cb = callback)" 4 |
807 |
.IX Item "manual reschedule mode (reschedule_cb = callback)" |
808 |
In this mode the values for \f(CW\*(C`interval\*(C'\fR and \f(CW\*(C`at\*(C'\fR are both being |
809 |
ignored. Instead, each time the periodic watcher gets scheduled, the |
810 |
reschedule callback will be called with the watcher as first, and the |
811 |
current time as second argument. |
812 |
.Sp |
813 |
\&\s-1NOTE:\s0 \fIThis callback \s-1MUST\s0 \s-1NOT\s0 stop or destroy any periodic watcher, |
814 |
ever, or make any event loop modifications\fR. If you need to stop it, |
815 |
return \f(CW\*(C`now + 1e30\*(C'\fR (or so, fudge fudge) and stop it afterwards (e.g. by |
816 |
starting a prepare watcher). |
817 |
.Sp |
818 |
Its prototype is \f(CW\*(C`ev_tstamp (*reschedule_cb)(struct ev_periodic *w, |
819 |
ev_tstamp now)\*(C'\fR, e.g.: |
820 |
.Sp |
821 |
.Vb 4 |
822 |
\& static ev_tstamp my_rescheduler (struct ev_periodic *w, ev_tstamp now) |
823 |
\& { |
824 |
\& return now + 60.; |
825 |
\& } |
826 |
.Ve |
827 |
.Sp |
828 |
It must return the next time to trigger, based on the passed time value |
829 |
(that is, the lowest time value larger than to the second argument). It |
830 |
will usually be called just before the callback will be triggered, but |
831 |
might be called at other times, too. |
832 |
.Sp |
833 |
\&\s-1NOTE:\s0 \fIThis callback must always return a time that is later than the |
834 |
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. |
835 |
.Sp |
836 |
This can be used to create very complex timers, such as a timer that |
837 |
triggers on each midnight, local time. To do this, you would calculate the |
838 |
next midnight after \f(CW\*(C`now\*(C'\fR and return the timestamp value for this. How |
839 |
you do this is, again, up to you (but it is not trivial, which is the main |
840 |
reason I omitted it as an example). |
841 |
.RE |
842 |
.RS 4 |
843 |
.RE |
844 |
.IP "ev_periodic_again (loop, ev_periodic *)" 4 |
845 |
.IX Item "ev_periodic_again (loop, ev_periodic *)" |
846 |
Simply stops and restarts the periodic watcher again. This is only useful |
847 |
when you changed some parameters or the reschedule callback would return |
848 |
a different time than the last time it was called (e.g. in a crond like |
849 |
program when the crontabs have changed). |
850 |
.ie n .Sh """ev_signal"" \- signal me when a signal gets signalled" |
851 |
.el .Sh "\f(CWev_signal\fP \- signal me when a signal gets signalled" |
852 |
.IX Subsection "ev_signal - signal me when a signal gets signalled" |
853 |
Signal watchers will trigger an event when the process receives a specific |
854 |
signal one or more times. Even though signals are very asynchronous, libev |
855 |
will try it's best to deliver signals synchronously, i.e. as part of the |
856 |
normal event processing, like any other event. |
857 |
.PP |
858 |
You can configure as many watchers as you like per signal. Only when the |
859 |
first watcher gets started will libev actually register a signal watcher |
860 |
with the kernel (thus it coexists with your own signal handlers as long |
861 |
as you don't register any with libev). Similarly, when the last signal |
862 |
watcher for a signal is stopped libev will reset the signal handler to |
863 |
\&\s-1SIG_DFL\s0 (regardless of what it was set to before). |
864 |
.IP "ev_signal_init (ev_signal *, callback, int signum)" 4 |
865 |
.IX Item "ev_signal_init (ev_signal *, callback, int signum)" |
866 |
.PD 0 |
867 |
.IP "ev_signal_set (ev_signal *, int signum)" 4 |
868 |
.IX Item "ev_signal_set (ev_signal *, int signum)" |
869 |
.PD |
870 |
Configures the watcher to trigger on the given signal number (usually one |
871 |
of the \f(CW\*(C`SIGxxx\*(C'\fR constants). |
872 |
.ie n .Sh """ev_child"" \- wait for pid status changes" |
873 |
.el .Sh "\f(CWev_child\fP \- wait for pid status changes" |
874 |
.IX Subsection "ev_child - wait for pid status changes" |
875 |
Child watchers trigger when your process receives a \s-1SIGCHLD\s0 in response to |
876 |
some child status changes (most typically when a child of yours dies). |
877 |
.IP "ev_child_init (ev_child *, callback, int pid)" 4 |
878 |
.IX Item "ev_child_init (ev_child *, callback, int pid)" |
879 |
.PD 0 |
880 |
.IP "ev_child_set (ev_child *, int pid)" 4 |
881 |
.IX Item "ev_child_set (ev_child *, int pid)" |
882 |
.PD |
883 |
Configures the watcher to wait for status changes of process \f(CW\*(C`pid\*(C'\fR (or |
884 |
\&\fIany\fR process if \f(CW\*(C`pid\*(C'\fR is specified as \f(CW0\fR). The callback can look |
885 |
at the \f(CW\*(C`rstatus\*(C'\fR member of the \f(CW\*(C`ev_child\*(C'\fR watcher structure to see |
886 |
the status word (use the macros from \f(CW\*(C`sys/wait.h\*(C'\fR and see your systems |
887 |
\&\f(CW\*(C`waitpid\*(C'\fR documentation). The \f(CW\*(C`rpid\*(C'\fR member contains the pid of the |
888 |
process causing the status change. |
889 |
.ie n .Sh """ev_idle"" \- when you've got nothing better to do" |
890 |
.el .Sh "\f(CWev_idle\fP \- when you've got nothing better to do" |
891 |
.IX Subsection "ev_idle - when you've got nothing better to do" |
892 |
Idle watchers trigger events when there are no other events are pending |
893 |
(prepare, check and other idle watchers do not count). That is, as long |
894 |
as your process is busy handling sockets or timeouts (or even signals, |
895 |
imagine) it will not be triggered. But when your process is idle all idle |
896 |
watchers are being called again and again, once per event loop iteration \- |
897 |
until stopped, that is, or your process receives more events and becomes |
898 |
busy. |
899 |
.PP |
900 |
The most noteworthy effect is that as long as any idle watchers are |
901 |
active, the process will not block when waiting for new events. |
902 |
.PP |
903 |
Apart from keeping your process non-blocking (which is a useful |
904 |
effect on its own sometimes), idle watchers are a good place to do |
905 |
\&\*(L"pseudo\-background processing\*(R", or delay processing stuff to after the |
906 |
event loop has handled all outstanding events. |
907 |
.IP "ev_idle_init (ev_signal *, callback)" 4 |
908 |
.IX Item "ev_idle_init (ev_signal *, callback)" |
909 |
Initialises and configures the idle watcher \- it has no parameters of any |
910 |
kind. There is a \f(CW\*(C`ev_idle_set\*(C'\fR macro, but using it is utterly pointless, |
911 |
believe me. |
912 |
.ie n .Sh """ev_prepare""\fP and \f(CW""ev_check"" \- customise your event loop" |
913 |
.el .Sh "\f(CWev_prepare\fP and \f(CWev_check\fP \- customise your event loop" |
914 |
.IX Subsection "ev_prepare and ev_check - customise your event loop" |
915 |
Prepare and check watchers are usually (but not always) used in tandem: |
916 |
prepare watchers get invoked before the process blocks and check watchers |
917 |
afterwards. |
918 |
.PP |
919 |
Their main purpose is to integrate other event mechanisms into libev. This |
920 |
could be used, for example, to track variable changes, implement your own |
921 |
watchers, integrate net-snmp or a coroutine library and lots more. |
922 |
.PP |
923 |
This is done by examining in each prepare call which file descriptors need |
924 |
to be watched by the other library, registering \f(CW\*(C`ev_io\*(C'\fR watchers for |
925 |
them and starting an \f(CW\*(C`ev_timer\*(C'\fR watcher for any timeouts (many libraries |
926 |
provide just this functionality). Then, in the check watcher you check for |
927 |
any events that occured (by checking the pending status of all watchers |
928 |
and stopping them) and call back into the library. The I/O and timer |
929 |
callbacks will never actually be called (but must be valid nevertheless, |
930 |
because you never know, you know?). |
931 |
.PP |
932 |
As another example, the Perl Coro module uses these hooks to integrate |
933 |
coroutines into libev programs, by yielding to other active coroutines |
934 |
during each prepare and only letting the process block if no coroutines |
935 |
are ready to run (it's actually more complicated: it only runs coroutines |
936 |
with priority higher than or equal to the event loop and one coroutine |
937 |
of lower priority, but only once, using idle watchers to keep the event |
938 |
loop from blocking if lower-priority coroutines are active, thus mapping |
939 |
low-priority coroutines to idle/background tasks). |
940 |
.IP "ev_prepare_init (ev_prepare *, callback)" 4 |
941 |
.IX Item "ev_prepare_init (ev_prepare *, callback)" |
942 |
.PD 0 |
943 |
.IP "ev_check_init (ev_check *, callback)" 4 |
944 |
.IX Item "ev_check_init (ev_check *, callback)" |
945 |
.PD |
946 |
Initialises and configures the prepare or check watcher \- they have no |
947 |
parameters of any kind. There are \f(CW\*(C`ev_prepare_set\*(C'\fR and \f(CW\*(C`ev_check_set\*(C'\fR |
948 |
macros, but using them is utterly, utterly and completely pointless. |
949 |
.SH "OTHER FUNCTIONS" |
950 |
.IX Header "OTHER FUNCTIONS" |
951 |
There are some other functions of possible interest. Described. Here. Now. |
952 |
.IP "ev_once (loop, int fd, int events, ev_tstamp timeout, callback)" 4 |
953 |
.IX Item "ev_once (loop, int fd, int events, ev_tstamp timeout, callback)" |
954 |
This function combines a simple timer and an I/O watcher, calls your |
955 |
callback on whichever event happens first and automatically stop both |
956 |
watchers. This is useful if you want to wait for a single event on an fd |
957 |
or timeout without having to allocate/configure/start/stop/free one or |
958 |
more watchers yourself. |
959 |
.Sp |
960 |
If \f(CW\*(C`fd\*(C'\fR is less than 0, then no I/O watcher will be started and events |
961 |
is being ignored. Otherwise, an \f(CW\*(C`ev_io\*(C'\fR watcher for the given \f(CW\*(C`fd\*(C'\fR and |
962 |
\&\f(CW\*(C`events\*(C'\fR set will be craeted and started. |
963 |
.Sp |
964 |
If \f(CW\*(C`timeout\*(C'\fR is less than 0, then no timeout watcher will be |
965 |
started. Otherwise an \f(CW\*(C`ev_timer\*(C'\fR watcher with after = \f(CW\*(C`timeout\*(C'\fR (and |
966 |
repeat = 0) will be started. While \f(CW0\fR is a valid timeout, it is of |
967 |
dubious value. |
968 |
.Sp |
969 |
The callback has the type \f(CW\*(C`void (*cb)(int revents, void *arg)\*(C'\fR and gets |
970 |
passed an \f(CW\*(C`revents\*(C'\fR set like normal event callbacks (a combination of |
971 |
\&\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 |
972 |
value passed to \f(CW\*(C`ev_once\*(C'\fR: |
973 |
.Sp |
974 |
.Vb 7 |
975 |
\& static void stdin_ready (int revents, void *arg) |
976 |
\& { |
977 |
\& if (revents & EV_TIMEOUT) |
978 |
\& /* doh, nothing entered */; |
979 |
\& else if (revents & EV_READ) |
980 |
\& /* stdin might have data for us, joy! */; |
981 |
\& } |
982 |
.Ve |
983 |
.Sp |
984 |
.Vb 1 |
985 |
\& ev_once (STDIN_FILENO, EV_READ, 10., stdin_ready, 0); |
986 |
.Ve |
987 |
.IP "ev_feed_event (loop, watcher, int events)" 4 |
988 |
.IX Item "ev_feed_event (loop, watcher, int events)" |
989 |
Feeds the given event set into the event loop, as if the specified event |
990 |
had happened for the specified watcher (which must be a pointer to an |
991 |
initialised but not necessarily started event watcher). |
992 |
.IP "ev_feed_fd_event (loop, int fd, int revents)" 4 |
993 |
.IX Item "ev_feed_fd_event (loop, int fd, int revents)" |
994 |
Feed an event on the given fd, as if a file descriptor backend detected |
995 |
the given events it. |
996 |
.IP "ev_feed_signal_event (loop, int signum)" 4 |
997 |
.IX Item "ev_feed_signal_event (loop, int signum)" |
998 |
Feed an event as if the given signal occured (loop must be the default loop!). |
999 |
.SH "LIBEVENT EMULATION" |
1000 |
.IX Header "LIBEVENT EMULATION" |
1001 |
Libev offers a compatibility emulation layer for libevent. It cannot |
1002 |
emulate the internals of libevent, so here are some usage hints: |
1003 |
.IP "* Use it by including <event.h>, as usual." 4 |
1004 |
.IX Item "Use it by including <event.h>, as usual." |
1005 |
.PD 0 |
1006 |
.IP "* The following members are fully supported: ev_base, ev_callback, ev_arg, ev_fd, ev_res, ev_events." 4 |
1007 |
.IX Item "The following members are fully supported: ev_base, ev_callback, ev_arg, ev_fd, ev_res, ev_events." |
1008 |
.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 |
1009 |
.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)." |
1010 |
.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 |
1011 |
.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." |
1012 |
.IP "* Other members are not supported." 4 |
1013 |
.IX Item "Other members are not supported." |
1014 |
.IP "* The libev emulation is \fInot\fR \s-1ABI\s0 compatible to libevent, you need to use the libev header file and library." 4 |
1015 |
.IX Item "The libev emulation is not ABI compatible to libevent, you need to use the libev header file and library." |
1016 |
.PD |
1017 |
.SH "\*(C+ SUPPORT" |
1018 |
.IX Header " SUPPORT" |
1019 |
\&\s-1TBD\s0. |
1020 |
.SH "AUTHOR" |
1021 |
.IX Header "AUTHOR" |
1022 |
Marc Lehmann <libev@schmorp.de>. |