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