1 |
root |
1.1 |
=head1 NAME |
2 |
|
|
|
3 |
|
|
libev - a high performance full-featured event loop written in C |
4 |
|
|
|
5 |
|
|
=head1 SYNOPSIS |
6 |
|
|
|
7 |
root |
1.164 |
#include <ev.h> |
8 |
root |
1.1 |
|
9 |
root |
1.105 |
=head2 EXAMPLE PROGRAM |
10 |
root |
1.54 |
|
11 |
root |
1.164 |
// a single header file is required |
12 |
|
|
#include <ev.h> |
13 |
root |
1.54 |
|
14 |
root |
1.217 |
#include <stdio.h> // for puts |
15 |
|
|
|
16 |
root |
1.164 |
// every watcher type has its own typedef'd struct |
17 |
root |
1.200 |
// with the name ev_TYPE |
18 |
root |
1.164 |
ev_io stdin_watcher; |
19 |
|
|
ev_timer timeout_watcher; |
20 |
|
|
|
21 |
|
|
// all watcher callbacks have a similar signature |
22 |
|
|
// this callback is called when data is readable on stdin |
23 |
|
|
static void |
24 |
root |
1.198 |
stdin_cb (EV_P_ ev_io *w, int revents) |
25 |
root |
1.164 |
{ |
26 |
|
|
puts ("stdin ready"); |
27 |
|
|
// for one-shot events, one must manually stop the watcher |
28 |
|
|
// with its corresponding stop function. |
29 |
|
|
ev_io_stop (EV_A_ w); |
30 |
|
|
|
31 |
|
|
// this causes all nested ev_loop's to stop iterating |
32 |
|
|
ev_unloop (EV_A_ EVUNLOOP_ALL); |
33 |
|
|
} |
34 |
|
|
|
35 |
|
|
// another callback, this time for a time-out |
36 |
|
|
static void |
37 |
root |
1.198 |
timeout_cb (EV_P_ ev_timer *w, int revents) |
38 |
root |
1.164 |
{ |
39 |
|
|
puts ("timeout"); |
40 |
|
|
// this causes the innermost ev_loop to stop iterating |
41 |
|
|
ev_unloop (EV_A_ EVUNLOOP_ONE); |
42 |
|
|
} |
43 |
|
|
|
44 |
|
|
int |
45 |
|
|
main (void) |
46 |
|
|
{ |
47 |
|
|
// use the default event loop unless you have special needs |
48 |
root |
1.220 |
struct ev_loop *loop = ev_default_loop (0); |
49 |
root |
1.164 |
|
50 |
|
|
// initialise an io watcher, then start it |
51 |
|
|
// this one will watch for stdin to become readable |
52 |
|
|
ev_io_init (&stdin_watcher, stdin_cb, /*STDIN_FILENO*/ 0, EV_READ); |
53 |
|
|
ev_io_start (loop, &stdin_watcher); |
54 |
|
|
|
55 |
|
|
// initialise a timer watcher, then start it |
56 |
|
|
// simple non-repeating 5.5 second timeout |
57 |
|
|
ev_timer_init (&timeout_watcher, timeout_cb, 5.5, 0.); |
58 |
|
|
ev_timer_start (loop, &timeout_watcher); |
59 |
|
|
|
60 |
|
|
// now wait for events to arrive |
61 |
|
|
ev_loop (loop, 0); |
62 |
|
|
|
63 |
|
|
// unloop was called, so exit |
64 |
|
|
return 0; |
65 |
|
|
} |
66 |
root |
1.53 |
|
67 |
root |
1.236 |
=head1 ABOUT THIS DOCUMENT |
68 |
|
|
|
69 |
|
|
This document documents the libev software package. |
70 |
root |
1.1 |
|
71 |
root |
1.135 |
The newest version of this document is also available as an html-formatted |
72 |
root |
1.69 |
web page you might find easier to navigate when reading it for the first |
73 |
root |
1.154 |
time: L<http://pod.tst.eu/http://cvs.schmorp.de/libev/ev.pod>. |
74 |
root |
1.69 |
|
75 |
root |
1.236 |
While this document tries to be as complete as possible in documenting |
76 |
|
|
libev, its usage and the rationale behind its design, it is not a tutorial |
77 |
|
|
on event-based programming, nor will it introduce event-based programming |
78 |
|
|
with libev. |
79 |
|
|
|
80 |
|
|
Familarity with event based programming techniques in general is assumed |
81 |
|
|
throughout this document. |
82 |
|
|
|
83 |
|
|
=head1 ABOUT LIBEV |
84 |
|
|
|
85 |
root |
1.1 |
Libev is an event loop: you register interest in certain events (such as a |
86 |
root |
1.92 |
file descriptor being readable or a timeout occurring), and it will manage |
87 |
root |
1.4 |
these event sources and provide your program with events. |
88 |
root |
1.1 |
|
89 |
|
|
To do this, it must take more or less complete control over your process |
90 |
|
|
(or thread) by executing the I<event loop> handler, and will then |
91 |
|
|
communicate events via a callback mechanism. |
92 |
|
|
|
93 |
|
|
You register interest in certain events by registering so-called I<event |
94 |
|
|
watchers>, which are relatively small C structures you initialise with the |
95 |
|
|
details of the event, and then hand it over to libev by I<starting> the |
96 |
|
|
watcher. |
97 |
|
|
|
98 |
root |
1.105 |
=head2 FEATURES |
99 |
root |
1.1 |
|
100 |
root |
1.58 |
Libev supports C<select>, C<poll>, the Linux-specific C<epoll>, the |
101 |
|
|
BSD-specific C<kqueue> and the Solaris-specific event port mechanisms |
102 |
|
|
for file descriptor events (C<ev_io>), the Linux C<inotify> interface |
103 |
root |
1.261 |
(for C<ev_stat>), Linux eventfd/signalfd (for faster and cleaner |
104 |
|
|
inter-thread wakeup (C<ev_async>)/signal handling (C<ev_signal>)) relative |
105 |
|
|
timers (C<ev_timer>), absolute timers with customised rescheduling |
106 |
|
|
(C<ev_periodic>), synchronous signals (C<ev_signal>), process status |
107 |
|
|
change events (C<ev_child>), and event watchers dealing with the event |
108 |
|
|
loop mechanism itself (C<ev_idle>, C<ev_embed>, C<ev_prepare> and |
109 |
|
|
C<ev_check> watchers) as well as file watchers (C<ev_stat>) and even |
110 |
|
|
limited support for fork events (C<ev_fork>). |
111 |
root |
1.54 |
|
112 |
|
|
It also is quite fast (see this |
113 |
|
|
L<benchmark|http://libev.schmorp.de/bench.html> comparing it to libevent |
114 |
|
|
for example). |
115 |
root |
1.1 |
|
116 |
root |
1.105 |
=head2 CONVENTIONS |
117 |
root |
1.1 |
|
118 |
root |
1.135 |
Libev is very configurable. In this manual the default (and most common) |
119 |
|
|
configuration will be described, which supports multiple event loops. For |
120 |
|
|
more info about various configuration options please have a look at |
121 |
|
|
B<EMBED> section in this manual. If libev was configured without support |
122 |
|
|
for multiple event loops, then all functions taking an initial argument of |
123 |
root |
1.274 |
name C<loop> (which is always of type C<struct ev_loop *>) will not have |
124 |
root |
1.135 |
this argument. |
125 |
root |
1.1 |
|
126 |
root |
1.105 |
=head2 TIME REPRESENTATION |
127 |
root |
1.1 |
|
128 |
root |
1.237 |
Libev represents time as a single floating point number, representing |
129 |
|
|
the (fractional) number of seconds since the (POSIX) epoch (somewhere |
130 |
|
|
near the beginning of 1970, details are complicated, don't ask). This |
131 |
|
|
type is called C<ev_tstamp>, which is what you should use too. It usually |
132 |
|
|
aliases to the C<double> type in C. When you need to do any calculations |
133 |
|
|
on it, you should treat it as some floating point value. Unlike the name |
134 |
root |
1.86 |
component C<stamp> might indicate, it is also used for time differences |
135 |
|
|
throughout libev. |
136 |
root |
1.34 |
|
137 |
root |
1.160 |
=head1 ERROR HANDLING |
138 |
|
|
|
139 |
|
|
Libev knows three classes of errors: operating system errors, usage errors |
140 |
|
|
and internal errors (bugs). |
141 |
|
|
|
142 |
|
|
When libev catches an operating system error it cannot handle (for example |
143 |
root |
1.161 |
a system call indicating a condition libev cannot fix), it calls the callback |
144 |
root |
1.160 |
set via C<ev_set_syserr_cb>, which is supposed to fix the problem or |
145 |
|
|
abort. The default is to print a diagnostic message and to call C<abort |
146 |
|
|
()>. |
147 |
|
|
|
148 |
|
|
When libev detects a usage error such as a negative timer interval, then |
149 |
|
|
it will print a diagnostic message and abort (via the C<assert> mechanism, |
150 |
|
|
so C<NDEBUG> will disable this checking): these are programming errors in |
151 |
|
|
the libev caller and need to be fixed there. |
152 |
|
|
|
153 |
|
|
Libev also has a few internal error-checking C<assert>ions, and also has |
154 |
|
|
extensive consistency checking code. These do not trigger under normal |
155 |
|
|
circumstances, as they indicate either a bug in libev or worse. |
156 |
|
|
|
157 |
|
|
|
158 |
root |
1.17 |
=head1 GLOBAL FUNCTIONS |
159 |
|
|
|
160 |
root |
1.18 |
These functions can be called anytime, even before initialising the |
161 |
|
|
library in any way. |
162 |
|
|
|
163 |
root |
1.1 |
=over 4 |
164 |
|
|
|
165 |
|
|
=item ev_tstamp ev_time () |
166 |
|
|
|
167 |
root |
1.26 |
Returns the current time as libev would use it. Please note that the |
168 |
|
|
C<ev_now> function is usually faster and also often returns the timestamp |
169 |
|
|
you actually want to know. |
170 |
root |
1.1 |
|
171 |
root |
1.97 |
=item ev_sleep (ev_tstamp interval) |
172 |
|
|
|
173 |
|
|
Sleep for the given interval: The current thread will be blocked until |
174 |
|
|
either it is interrupted or the given time interval has passed. Basically |
175 |
root |
1.161 |
this is a sub-second-resolution C<sleep ()>. |
176 |
root |
1.97 |
|
177 |
root |
1.1 |
=item int ev_version_major () |
178 |
|
|
|
179 |
|
|
=item int ev_version_minor () |
180 |
|
|
|
181 |
root |
1.80 |
You can find out the major and minor ABI version numbers of the library |
182 |
root |
1.1 |
you linked against by calling the functions C<ev_version_major> and |
183 |
|
|
C<ev_version_minor>. If you want, you can compare against the global |
184 |
|
|
symbols C<EV_VERSION_MAJOR> and C<EV_VERSION_MINOR>, which specify the |
185 |
|
|
version of the library your program was compiled against. |
186 |
|
|
|
187 |
root |
1.80 |
These version numbers refer to the ABI version of the library, not the |
188 |
|
|
release version. |
189 |
root |
1.79 |
|
190 |
root |
1.9 |
Usually, it's a good idea to terminate if the major versions mismatch, |
191 |
root |
1.79 |
as this indicates an incompatible change. Minor versions are usually |
192 |
root |
1.1 |
compatible to older versions, so a larger minor version alone is usually |
193 |
|
|
not a problem. |
194 |
|
|
|
195 |
root |
1.54 |
Example: Make sure we haven't accidentally been linked against the wrong |
196 |
|
|
version. |
197 |
root |
1.34 |
|
198 |
root |
1.164 |
assert (("libev version mismatch", |
199 |
|
|
ev_version_major () == EV_VERSION_MAJOR |
200 |
|
|
&& ev_version_minor () >= EV_VERSION_MINOR)); |
201 |
root |
1.34 |
|
202 |
root |
1.31 |
=item unsigned int ev_supported_backends () |
203 |
|
|
|
204 |
|
|
Return the set of all backends (i.e. their corresponding C<EV_BACKEND_*> |
205 |
|
|
value) compiled into this binary of libev (independent of their |
206 |
|
|
availability on the system you are running on). See C<ev_default_loop> for |
207 |
|
|
a description of the set values. |
208 |
|
|
|
209 |
root |
1.34 |
Example: make sure we have the epoll method, because yeah this is cool and |
210 |
|
|
a must have and can we have a torrent of it please!!!11 |
211 |
|
|
|
212 |
root |
1.164 |
assert (("sorry, no epoll, no sex", |
213 |
|
|
ev_supported_backends () & EVBACKEND_EPOLL)); |
214 |
root |
1.34 |
|
215 |
root |
1.31 |
=item unsigned int ev_recommended_backends () |
216 |
|
|
|
217 |
|
|
Return the set of all backends compiled into this binary of libev and also |
218 |
|
|
recommended for this platform. This set is often smaller than the one |
219 |
|
|
returned by C<ev_supported_backends>, as for example kqueue is broken on |
220 |
root |
1.161 |
most BSDs and will not be auto-detected unless you explicitly request it |
221 |
root |
1.31 |
(assuming you know what you are doing). This is the set of backends that |
222 |
root |
1.33 |
libev will probe for if you specify no backends explicitly. |
223 |
root |
1.31 |
|
224 |
root |
1.35 |
=item unsigned int ev_embeddable_backends () |
225 |
|
|
|
226 |
|
|
Returns the set of backends that are embeddable in other event loops. This |
227 |
|
|
is the theoretical, all-platform, value. To find which backends |
228 |
|
|
might be supported on the current system, you would need to look at |
229 |
|
|
C<ev_embeddable_backends () & ev_supported_backends ()>, likewise for |
230 |
|
|
recommended ones. |
231 |
|
|
|
232 |
|
|
See the description of C<ev_embed> watchers for more info. |
233 |
|
|
|
234 |
root |
1.186 |
=item ev_set_allocator (void *(*cb)(void *ptr, long size)) [NOT REENTRANT] |
235 |
root |
1.1 |
|
236 |
root |
1.59 |
Sets the allocation function to use (the prototype is similar - the |
237 |
root |
1.145 |
semantics are identical to the C<realloc> C89/SuS/POSIX function). It is |
238 |
|
|
used to allocate and free memory (no surprises here). If it returns zero |
239 |
|
|
when memory needs to be allocated (C<size != 0>), the library might abort |
240 |
|
|
or take some potentially destructive action. |
241 |
|
|
|
242 |
|
|
Since some systems (at least OpenBSD and Darwin) fail to implement |
243 |
|
|
correct C<realloc> semantics, libev will use a wrapper around the system |
244 |
|
|
C<realloc> and C<free> functions by default. |
245 |
root |
1.1 |
|
246 |
|
|
You could override this function in high-availability programs to, say, |
247 |
|
|
free some memory if it cannot allocate memory, to use a special allocator, |
248 |
|
|
or even to sleep a while and retry until some memory is available. |
249 |
|
|
|
250 |
root |
1.54 |
Example: Replace the libev allocator with one that waits a bit and then |
251 |
root |
1.145 |
retries (example requires a standards-compliant C<realloc>). |
252 |
root |
1.34 |
|
253 |
|
|
static void * |
254 |
root |
1.52 |
persistent_realloc (void *ptr, size_t size) |
255 |
root |
1.34 |
{ |
256 |
|
|
for (;;) |
257 |
|
|
{ |
258 |
|
|
void *newptr = realloc (ptr, size); |
259 |
|
|
|
260 |
|
|
if (newptr) |
261 |
|
|
return newptr; |
262 |
|
|
|
263 |
|
|
sleep (60); |
264 |
|
|
} |
265 |
|
|
} |
266 |
|
|
|
267 |
|
|
... |
268 |
|
|
ev_set_allocator (persistent_realloc); |
269 |
|
|
|
270 |
root |
1.186 |
=item ev_set_syserr_cb (void (*cb)(const char *msg)); [NOT REENTRANT] |
271 |
root |
1.1 |
|
272 |
root |
1.161 |
Set the callback function to call on a retryable system call error (such |
273 |
root |
1.1 |
as failed select, poll, epoll_wait). The message is a printable string |
274 |
|
|
indicating the system call or subsystem causing the problem. If this |
275 |
root |
1.161 |
callback is set, then libev will expect it to remedy the situation, no |
276 |
root |
1.7 |
matter what, when it returns. That is, libev will generally retry the |
277 |
root |
1.1 |
requested operation, or, if the condition doesn't go away, do bad stuff |
278 |
|
|
(such as abort). |
279 |
|
|
|
280 |
root |
1.54 |
Example: This is basically the same thing that libev does internally, too. |
281 |
root |
1.34 |
|
282 |
|
|
static void |
283 |
|
|
fatal_error (const char *msg) |
284 |
|
|
{ |
285 |
|
|
perror (msg); |
286 |
|
|
abort (); |
287 |
|
|
} |
288 |
|
|
|
289 |
|
|
... |
290 |
|
|
ev_set_syserr_cb (fatal_error); |
291 |
|
|
|
292 |
root |
1.1 |
=back |
293 |
|
|
|
294 |
|
|
=head1 FUNCTIONS CONTROLLING THE EVENT LOOP |
295 |
|
|
|
296 |
root |
1.200 |
An event loop is described by a C<struct ev_loop *> (the C<struct> |
297 |
|
|
is I<not> optional in this case, as there is also an C<ev_loop> |
298 |
|
|
I<function>). |
299 |
|
|
|
300 |
|
|
The library knows two types of such loops, the I<default> loop, which |
301 |
|
|
supports signals and child events, and dynamically created loops which do |
302 |
|
|
not. |
303 |
root |
1.1 |
|
304 |
|
|
=over 4 |
305 |
|
|
|
306 |
|
|
=item struct ev_loop *ev_default_loop (unsigned int flags) |
307 |
|
|
|
308 |
|
|
This will initialise the default event loop if it hasn't been initialised |
309 |
|
|
yet and return it. If the default loop could not be initialised, returns |
310 |
|
|
false. If it already was initialised it simply returns it (and ignores the |
311 |
root |
1.31 |
flags. If that is troubling you, check C<ev_backend ()> afterwards). |
312 |
root |
1.1 |
|
313 |
|
|
If you don't know what event loop to use, use the one returned from this |
314 |
|
|
function. |
315 |
|
|
|
316 |
root |
1.139 |
Note that this function is I<not> thread-safe, so if you want to use it |
317 |
|
|
from multiple threads, you have to lock (note also that this is unlikely, |
318 |
root |
1.208 |
as loops cannot be shared easily between threads anyway). |
319 |
root |
1.139 |
|
320 |
root |
1.118 |
The default loop is the only loop that can handle C<ev_signal> and |
321 |
|
|
C<ev_child> watchers, and to do this, it always registers a handler |
322 |
root |
1.161 |
for C<SIGCHLD>. If this is a problem for your application you can either |
323 |
root |
1.118 |
create a dynamic loop with C<ev_loop_new> that doesn't do that, or you |
324 |
|
|
can simply overwrite the C<SIGCHLD> signal handler I<after> calling |
325 |
|
|
C<ev_default_init>. |
326 |
|
|
|
327 |
root |
1.1 |
The flags argument can be used to specify special behaviour or specific |
328 |
root |
1.33 |
backends to use, and is usually specified as C<0> (or C<EVFLAG_AUTO>). |
329 |
root |
1.1 |
|
330 |
root |
1.33 |
The following flags are supported: |
331 |
root |
1.1 |
|
332 |
|
|
=over 4 |
333 |
|
|
|
334 |
root |
1.10 |
=item C<EVFLAG_AUTO> |
335 |
root |
1.1 |
|
336 |
root |
1.9 |
The default flags value. Use this if you have no clue (it's the right |
337 |
root |
1.1 |
thing, believe me). |
338 |
|
|
|
339 |
root |
1.10 |
=item C<EVFLAG_NOENV> |
340 |
root |
1.1 |
|
341 |
root |
1.161 |
If this flag bit is or'ed into the flag value (or the program runs setuid |
342 |
root |
1.8 |
or setgid) then libev will I<not> look at the environment variable |
343 |
|
|
C<LIBEV_FLAGS>. Otherwise (the default), this environment variable will |
344 |
|
|
override the flags completely if it is found in the environment. This is |
345 |
|
|
useful to try out specific backends to test their performance, or to work |
346 |
|
|
around bugs. |
347 |
root |
1.1 |
|
348 |
root |
1.62 |
=item C<EVFLAG_FORKCHECK> |
349 |
|
|
|
350 |
|
|
Instead of calling C<ev_default_fork> or C<ev_loop_fork> manually after |
351 |
|
|
a fork, you can also make libev check for a fork in each iteration by |
352 |
|
|
enabling this flag. |
353 |
|
|
|
354 |
|
|
This works by calling C<getpid ()> on every iteration of the loop, |
355 |
|
|
and thus this might slow down your event loop if you do a lot of loop |
356 |
ayin |
1.65 |
iterations and little real work, but is usually not noticeable (on my |
357 |
root |
1.135 |
GNU/Linux system for example, C<getpid> is actually a simple 5-insn sequence |
358 |
root |
1.161 |
without a system call and thus I<very> fast, but my GNU/Linux system also has |
359 |
root |
1.62 |
C<pthread_atfork> which is even faster). |
360 |
|
|
|
361 |
|
|
The big advantage of this flag is that you can forget about fork (and |
362 |
|
|
forget about forgetting to tell libev about forking) when you use this |
363 |
|
|
flag. |
364 |
|
|
|
365 |
root |
1.161 |
This flag setting cannot be overridden or specified in the C<LIBEV_FLAGS> |
366 |
root |
1.62 |
environment variable. |
367 |
|
|
|
368 |
root |
1.260 |
=item C<EVFLAG_NOINOTIFY> |
369 |
|
|
|
370 |
|
|
When this flag is specified, then libev will not attempt to use the |
371 |
|
|
I<inotify> API for it's C<ev_stat> watchers. Apart from debugging and |
372 |
|
|
testing, this flag can be useful to conserve inotify file descriptors, as |
373 |
|
|
otherwise each loop using C<ev_stat> watchers consumes one inotify handle. |
374 |
|
|
|
375 |
root |
1.277 |
=item C<EVFLAG_SIGNALFD> |
376 |
root |
1.260 |
|
377 |
root |
1.277 |
When this flag is specified, then libev will attempt to use the |
378 |
|
|
I<signalfd> API for it's C<ev_signal> (and C<ev_child>) watchers. This API |
379 |
root |
1.278 |
delivers signals synchronously, which makes it both faster and might make |
380 |
|
|
it possible to get the queued signal data. It can also simplify signal |
381 |
|
|
handling with threads, as long as you properly block signals in your |
382 |
|
|
threads that are not interested in handling them. |
383 |
root |
1.277 |
|
384 |
|
|
Signalfd will not be used by default as this changes your signal mask, and |
385 |
|
|
there are a lot of shoddy libraries and programs (glib's threadpool for |
386 |
|
|
example) that can't properly initialise their signal masks. |
387 |
root |
1.260 |
|
388 |
root |
1.31 |
=item C<EVBACKEND_SELECT> (value 1, portable select backend) |
389 |
root |
1.1 |
|
390 |
root |
1.29 |
This is your standard select(2) backend. Not I<completely> standard, as |
391 |
|
|
libev tries to roll its own fd_set with no limits on the number of fds, |
392 |
|
|
but if that fails, expect a fairly low limit on the number of fds when |
393 |
root |
1.102 |
using this backend. It doesn't scale too well (O(highest_fd)), but its |
394 |
|
|
usually the fastest backend for a low number of (low-numbered :) fds. |
395 |
|
|
|
396 |
|
|
To get good performance out of this backend you need a high amount of |
397 |
root |
1.161 |
parallelism (most of the file descriptors should be busy). If you are |
398 |
root |
1.102 |
writing a server, you should C<accept ()> in a loop to accept as many |
399 |
|
|
connections as possible during one iteration. You might also want to have |
400 |
|
|
a look at C<ev_set_io_collect_interval ()> to increase the amount of |
401 |
root |
1.155 |
readiness notifications you get per iteration. |
402 |
root |
1.1 |
|
403 |
root |
1.179 |
This backend maps C<EV_READ> to the C<readfds> set and C<EV_WRITE> to the |
404 |
|
|
C<writefds> set (and to work around Microsoft Windows bugs, also onto the |
405 |
|
|
C<exceptfds> set on that platform). |
406 |
|
|
|
407 |
root |
1.31 |
=item C<EVBACKEND_POLL> (value 2, poll backend, available everywhere except on windows) |
408 |
root |
1.1 |
|
409 |
root |
1.102 |
And this is your standard poll(2) backend. It's more complicated |
410 |
|
|
than select, but handles sparse fds better and has no artificial |
411 |
|
|
limit on the number of fds you can use (except it will slow down |
412 |
|
|
considerably with a lot of inactive fds). It scales similarly to select, |
413 |
|
|
i.e. O(total_fds). See the entry for C<EVBACKEND_SELECT>, above, for |
414 |
|
|
performance tips. |
415 |
root |
1.1 |
|
416 |
root |
1.179 |
This backend maps C<EV_READ> to C<POLLIN | POLLERR | POLLHUP>, and |
417 |
|
|
C<EV_WRITE> to C<POLLOUT | POLLERR | POLLHUP>. |
418 |
|
|
|
419 |
root |
1.31 |
=item C<EVBACKEND_EPOLL> (value 4, Linux) |
420 |
root |
1.1 |
|
421 |
root |
1.272 |
Use the linux-specific epoll(7) interface (for both pre- and post-2.6.9 |
422 |
|
|
kernels). |
423 |
|
|
|
424 |
root |
1.29 |
For few fds, this backend is a bit little slower than poll and select, |
425 |
root |
1.94 |
but it scales phenomenally better. While poll and select usually scale |
426 |
|
|
like O(total_fds) where n is the total number of fds (or the highest fd), |
427 |
root |
1.205 |
epoll scales either O(1) or O(active_fds). |
428 |
|
|
|
429 |
root |
1.210 |
The epoll mechanism deserves honorable mention as the most misdesigned |
430 |
|
|
of the more advanced event mechanisms: mere annoyances include silently |
431 |
|
|
dropping file descriptors, requiring a system call per change per file |
432 |
|
|
descriptor (and unnecessary guessing of parameters), problems with dup and |
433 |
|
|
so on. The biggest issue is fork races, however - if a program forks then |
434 |
|
|
I<both> parent and child process have to recreate the epoll set, which can |
435 |
|
|
take considerable time (one syscall per file descriptor) and is of course |
436 |
|
|
hard to detect. |
437 |
root |
1.1 |
|
438 |
root |
1.210 |
Epoll is also notoriously buggy - embedding epoll fds I<should> work, but |
439 |
|
|
of course I<doesn't>, and epoll just loves to report events for totally |
440 |
root |
1.205 |
I<different> file descriptors (even already closed ones, so one cannot |
441 |
|
|
even remove them from the set) than registered in the set (especially |
442 |
|
|
on SMP systems). Libev tries to counter these spurious notifications by |
443 |
|
|
employing an additional generation counter and comparing that against the |
444 |
root |
1.210 |
events to filter out spurious ones, recreating the set when required. |
445 |
root |
1.204 |
|
446 |
root |
1.94 |
While stopping, setting and starting an I/O watcher in the same iteration |
447 |
root |
1.210 |
will result in some caching, there is still a system call per such |
448 |
|
|
incident (because the same I<file descriptor> could point to a different |
449 |
|
|
I<file description> now), so its best to avoid that. Also, C<dup ()>'ed |
450 |
|
|
file descriptors might not work very well if you register events for both |
451 |
|
|
file descriptors. |
452 |
root |
1.29 |
|
453 |
root |
1.102 |
Best performance from this backend is achieved by not unregistering all |
454 |
root |
1.183 |
watchers for a file descriptor until it has been closed, if possible, |
455 |
|
|
i.e. keep at least one watcher active per fd at all times. Stopping and |
456 |
|
|
starting a watcher (without re-setting it) also usually doesn't cause |
457 |
root |
1.206 |
extra overhead. A fork can both result in spurious notifications as well |
458 |
|
|
as in libev having to destroy and recreate the epoll object, which can |
459 |
|
|
take considerable time and thus should be avoided. |
460 |
root |
1.102 |
|
461 |
root |
1.215 |
All this means that, in practice, C<EVBACKEND_SELECT> can be as fast or |
462 |
|
|
faster than epoll for maybe up to a hundred file descriptors, depending on |
463 |
root |
1.214 |
the usage. So sad. |
464 |
root |
1.213 |
|
465 |
root |
1.161 |
While nominally embeddable in other event loops, this feature is broken in |
466 |
root |
1.102 |
all kernel versions tested so far. |
467 |
|
|
|
468 |
root |
1.179 |
This backend maps C<EV_READ> and C<EV_WRITE> in the same way as |
469 |
|
|
C<EVBACKEND_POLL>. |
470 |
|
|
|
471 |
root |
1.31 |
=item C<EVBACKEND_KQUEUE> (value 8, most BSD clones) |
472 |
root |
1.29 |
|
473 |
root |
1.210 |
Kqueue deserves special mention, as at the time of this writing, it |
474 |
|
|
was broken on all BSDs except NetBSD (usually it doesn't work reliably |
475 |
|
|
with anything but sockets and pipes, except on Darwin, where of course |
476 |
|
|
it's completely useless). Unlike epoll, however, whose brokenness |
477 |
|
|
is by design, these kqueue bugs can (and eventually will) be fixed |
478 |
|
|
without API changes to existing programs. For this reason it's not being |
479 |
|
|
"auto-detected" unless you explicitly specify it in the flags (i.e. using |
480 |
|
|
C<EVBACKEND_KQUEUE>) or libev was compiled on a known-to-be-good (-enough) |
481 |
|
|
system like NetBSD. |
482 |
root |
1.29 |
|
483 |
root |
1.100 |
You still can embed kqueue into a normal poll or select backend and use it |
484 |
|
|
only for sockets (after having made sure that sockets work with kqueue on |
485 |
|
|
the target platform). See C<ev_embed> watchers for more info. |
486 |
|
|
|
487 |
root |
1.29 |
It scales in the same way as the epoll backend, but the interface to the |
488 |
root |
1.100 |
kernel is more efficient (which says nothing about its actual speed, of |
489 |
|
|
course). While stopping, setting and starting an I/O watcher does never |
490 |
root |
1.161 |
cause an extra system call as with C<EVBACKEND_EPOLL>, it still adds up to |
491 |
root |
1.206 |
two event changes per incident. Support for C<fork ()> is very bad (but |
492 |
|
|
sane, unlike epoll) and it drops fds silently in similarly hard-to-detect |
493 |
|
|
cases |
494 |
root |
1.29 |
|
495 |
root |
1.102 |
This backend usually performs well under most conditions. |
496 |
|
|
|
497 |
|
|
While nominally embeddable in other event loops, this doesn't work |
498 |
|
|
everywhere, so you might need to test for this. And since it is broken |
499 |
|
|
almost everywhere, you should only use it when you have a lot of sockets |
500 |
|
|
(for which it usually works), by embedding it into another event loop |
501 |
root |
1.223 |
(e.g. C<EVBACKEND_SELECT> or C<EVBACKEND_POLL> (but C<poll> is of course |
502 |
|
|
also broken on OS X)) and, did I mention it, using it only for sockets. |
503 |
root |
1.102 |
|
504 |
root |
1.179 |
This backend maps C<EV_READ> into an C<EVFILT_READ> kevent with |
505 |
|
|
C<NOTE_EOF>, and C<EV_WRITE> into an C<EVFILT_WRITE> kevent with |
506 |
|
|
C<NOTE_EOF>. |
507 |
|
|
|
508 |
root |
1.31 |
=item C<EVBACKEND_DEVPOLL> (value 16, Solaris 8) |
509 |
root |
1.29 |
|
510 |
root |
1.102 |
This is not implemented yet (and might never be, unless you send me an |
511 |
|
|
implementation). According to reports, C</dev/poll> only supports sockets |
512 |
|
|
and is not embeddable, which would limit the usefulness of this backend |
513 |
|
|
immensely. |
514 |
root |
1.29 |
|
515 |
root |
1.31 |
=item C<EVBACKEND_PORT> (value 32, Solaris 10) |
516 |
root |
1.29 |
|
517 |
root |
1.94 |
This uses the Solaris 10 event port mechanism. As with everything on Solaris, |
518 |
root |
1.29 |
it's really slow, but it still scales very well (O(active_fds)). |
519 |
|
|
|
520 |
root |
1.161 |
Please note that Solaris event ports can deliver a lot of spurious |
521 |
root |
1.32 |
notifications, so you need to use non-blocking I/O or other means to avoid |
522 |
|
|
blocking when no data (or space) is available. |
523 |
|
|
|
524 |
root |
1.102 |
While this backend scales well, it requires one system call per active |
525 |
|
|
file descriptor per loop iteration. For small and medium numbers of file |
526 |
|
|
descriptors a "slow" C<EVBACKEND_SELECT> or C<EVBACKEND_POLL> backend |
527 |
|
|
might perform better. |
528 |
|
|
|
529 |
root |
1.183 |
On the positive side, with the exception of the spurious readiness |
530 |
|
|
notifications, this backend actually performed fully to specification |
531 |
|
|
in all tests and is fully embeddable, which is a rare feat among the |
532 |
root |
1.206 |
OS-specific backends (I vastly prefer correctness over speed hacks). |
533 |
root |
1.117 |
|
534 |
root |
1.179 |
This backend maps C<EV_READ> and C<EV_WRITE> in the same way as |
535 |
|
|
C<EVBACKEND_POLL>. |
536 |
|
|
|
537 |
root |
1.31 |
=item C<EVBACKEND_ALL> |
538 |
root |
1.29 |
|
539 |
|
|
Try all backends (even potentially broken ones that wouldn't be tried |
540 |
|
|
with C<EVFLAG_AUTO>). Since this is a mask, you can do stuff such as |
541 |
root |
1.31 |
C<EVBACKEND_ALL & ~EVBACKEND_KQUEUE>. |
542 |
root |
1.1 |
|
543 |
root |
1.102 |
It is definitely not recommended to use this flag. |
544 |
|
|
|
545 |
root |
1.1 |
=back |
546 |
|
|
|
547 |
root |
1.260 |
If one or more of the backend flags are or'ed into the flags value, |
548 |
|
|
then only these backends will be tried (in the reverse order as listed |
549 |
|
|
here). If none are specified, all backends in C<ev_recommended_backends |
550 |
|
|
()> will be tried. |
551 |
root |
1.29 |
|
552 |
root |
1.183 |
Example: This is the most typical usage. |
553 |
root |
1.33 |
|
554 |
root |
1.164 |
if (!ev_default_loop (0)) |
555 |
|
|
fatal ("could not initialise libev, bad $LIBEV_FLAGS in environment?"); |
556 |
root |
1.33 |
|
557 |
root |
1.183 |
Example: Restrict libev to the select and poll backends, and do not allow |
558 |
root |
1.33 |
environment settings to be taken into account: |
559 |
|
|
|
560 |
root |
1.164 |
ev_default_loop (EVBACKEND_POLL | EVBACKEND_SELECT | EVFLAG_NOENV); |
561 |
root |
1.33 |
|
562 |
root |
1.183 |
Example: Use whatever libev has to offer, but make sure that kqueue is |
563 |
|
|
used if available (warning, breaks stuff, best use only with your own |
564 |
|
|
private event loop and only if you know the OS supports your types of |
565 |
|
|
fds): |
566 |
root |
1.33 |
|
567 |
root |
1.164 |
ev_default_loop (ev_recommended_backends () | EVBACKEND_KQUEUE); |
568 |
root |
1.33 |
|
569 |
root |
1.1 |
=item struct ev_loop *ev_loop_new (unsigned int flags) |
570 |
|
|
|
571 |
|
|
Similar to C<ev_default_loop>, but always creates a new event loop that is |
572 |
|
|
always distinct from the default loop. Unlike the default loop, it cannot |
573 |
|
|
handle signal and child watchers, and attempts to do so will be greeted by |
574 |
|
|
undefined behaviour (or a failed assertion if assertions are enabled). |
575 |
|
|
|
576 |
root |
1.139 |
Note that this function I<is> thread-safe, and the recommended way to use |
577 |
|
|
libev with threads is indeed to create one loop per thread, and using the |
578 |
|
|
default loop in the "main" or "initial" thread. |
579 |
|
|
|
580 |
root |
1.54 |
Example: Try to create a event loop that uses epoll and nothing else. |
581 |
root |
1.34 |
|
582 |
root |
1.164 |
struct ev_loop *epoller = ev_loop_new (EVBACKEND_EPOLL | EVFLAG_NOENV); |
583 |
|
|
if (!epoller) |
584 |
|
|
fatal ("no epoll found here, maybe it hides under your chair"); |
585 |
root |
1.34 |
|
586 |
root |
1.1 |
=item ev_default_destroy () |
587 |
|
|
|
588 |
|
|
Destroys the default loop again (frees all memory and kernel state |
589 |
root |
1.37 |
etc.). None of the active event watchers will be stopped in the normal |
590 |
|
|
sense, so e.g. C<ev_is_active> might still return true. It is your |
591 |
root |
1.161 |
responsibility to either stop all watchers cleanly yourself I<before> |
592 |
root |
1.37 |
calling this function, or cope with the fact afterwards (which is usually |
593 |
root |
1.87 |
the easiest thing, you can just ignore the watchers and/or C<free ()> them |
594 |
root |
1.37 |
for example). |
595 |
root |
1.1 |
|
596 |
root |
1.203 |
Note that certain global state, such as signal state (and installed signal |
597 |
|
|
handlers), will not be freed by this function, and related watchers (such |
598 |
|
|
as signal and child watchers) would need to be stopped manually. |
599 |
root |
1.87 |
|
600 |
|
|
In general it is not advisable to call this function except in the |
601 |
|
|
rare occasion where you really need to free e.g. the signal handling |
602 |
|
|
pipe fds. If you need dynamically allocated loops it is better to use |
603 |
root |
1.269 |
C<ev_loop_new> and C<ev_loop_destroy>. |
604 |
root |
1.87 |
|
605 |
root |
1.1 |
=item ev_loop_destroy (loop) |
606 |
|
|
|
607 |
|
|
Like C<ev_default_destroy>, but destroys an event loop created by an |
608 |
|
|
earlier call to C<ev_loop_new>. |
609 |
|
|
|
610 |
|
|
=item ev_default_fork () |
611 |
|
|
|
612 |
root |
1.119 |
This function sets a flag that causes subsequent C<ev_loop> iterations |
613 |
|
|
to reinitialise the kernel state for backends that have one. Despite the |
614 |
|
|
name, you can call it anytime, but it makes most sense after forking, in |
615 |
|
|
the child process (or both child and parent, but that again makes little |
616 |
|
|
sense). You I<must> call it in the child before using any of the libev |
617 |
|
|
functions, and it will only take effect at the next C<ev_loop> iteration. |
618 |
|
|
|
619 |
|
|
On the other hand, you only need to call this function in the child |
620 |
|
|
process if and only if you want to use the event library in the child. If |
621 |
|
|
you just fork+exec, you don't have to call it at all. |
622 |
root |
1.1 |
|
623 |
root |
1.9 |
The function itself is quite fast and it's usually not a problem to call |
624 |
root |
1.1 |
it just in case after a fork. To make this easy, the function will fit in |
625 |
|
|
quite nicely into a call to C<pthread_atfork>: |
626 |
|
|
|
627 |
|
|
pthread_atfork (0, 0, ev_default_fork); |
628 |
|
|
|
629 |
|
|
=item ev_loop_fork (loop) |
630 |
|
|
|
631 |
|
|
Like C<ev_default_fork>, but acts on an event loop created by |
632 |
|
|
C<ev_loop_new>. Yes, you have to call this on every allocated event loop |
633 |
root |
1.183 |
after fork that you want to re-use in the child, and how you do this is |
634 |
|
|
entirely your own problem. |
635 |
root |
1.1 |
|
636 |
root |
1.131 |
=item int ev_is_default_loop (loop) |
637 |
|
|
|
638 |
root |
1.183 |
Returns true when the given loop is, in fact, the default loop, and false |
639 |
|
|
otherwise. |
640 |
root |
1.131 |
|
641 |
root |
1.66 |
=item unsigned int ev_loop_count (loop) |
642 |
|
|
|
643 |
|
|
Returns the count of loop iterations for the loop, which is identical to |
644 |
|
|
the number of times libev did poll for new events. It starts at C<0> and |
645 |
|
|
happily wraps around with enough iterations. |
646 |
|
|
|
647 |
|
|
This value can sometimes be useful as a generation counter of sorts (it |
648 |
|
|
"ticks" the number of loop iterations), as it roughly corresponds with |
649 |
|
|
C<ev_prepare> and C<ev_check> calls. |
650 |
|
|
|
651 |
root |
1.247 |
=item unsigned int ev_loop_depth (loop) |
652 |
|
|
|
653 |
|
|
Returns the number of times C<ev_loop> was entered minus the number of |
654 |
|
|
times C<ev_loop> was exited, in other words, the recursion depth. |
655 |
|
|
|
656 |
|
|
Outside C<ev_loop>, this number is zero. In a callback, this number is |
657 |
|
|
C<1>, unless C<ev_loop> was invoked recursively (or from another thread), |
658 |
|
|
in which case it is higher. |
659 |
|
|
|
660 |
|
|
Leaving C<ev_loop> abnormally (setjmp/longjmp, cancelling the thread |
661 |
|
|
etc.), doesn't count as exit. |
662 |
|
|
|
663 |
root |
1.31 |
=item unsigned int ev_backend (loop) |
664 |
root |
1.1 |
|
665 |
root |
1.31 |
Returns one of the C<EVBACKEND_*> flags indicating the event backend in |
666 |
root |
1.1 |
use. |
667 |
|
|
|
668 |
root |
1.9 |
=item ev_tstamp ev_now (loop) |
669 |
root |
1.1 |
|
670 |
|
|
Returns the current "event loop time", which is the time the event loop |
671 |
root |
1.34 |
received events and started processing them. This timestamp does not |
672 |
|
|
change as long as callbacks are being processed, and this is also the base |
673 |
|
|
time used for relative timers. You can treat it as the timestamp of the |
674 |
root |
1.92 |
event occurring (or more correctly, libev finding out about it). |
675 |
root |
1.1 |
|
676 |
root |
1.176 |
=item ev_now_update (loop) |
677 |
|
|
|
678 |
|
|
Establishes the current time by querying the kernel, updating the time |
679 |
|
|
returned by C<ev_now ()> in the progress. This is a costly operation and |
680 |
|
|
is usually done automatically within C<ev_loop ()>. |
681 |
|
|
|
682 |
|
|
This function is rarely useful, but when some event callback runs for a |
683 |
|
|
very long time without entering the event loop, updating libev's idea of |
684 |
|
|
the current time is a good idea. |
685 |
|
|
|
686 |
root |
1.238 |
See also L<The special problem of time updates> in the C<ev_timer> section. |
687 |
root |
1.176 |
|
688 |
root |
1.231 |
=item ev_suspend (loop) |
689 |
|
|
|
690 |
|
|
=item ev_resume (loop) |
691 |
|
|
|
692 |
|
|
These two functions suspend and resume a loop, for use when the loop is |
693 |
|
|
not used for a while and timeouts should not be processed. |
694 |
|
|
|
695 |
|
|
A typical use case would be an interactive program such as a game: When |
696 |
|
|
the user presses C<^Z> to suspend the game and resumes it an hour later it |
697 |
|
|
would be best to handle timeouts as if no time had actually passed while |
698 |
|
|
the program was suspended. This can be achieved by calling C<ev_suspend> |
699 |
|
|
in your C<SIGTSTP> handler, sending yourself a C<SIGSTOP> and calling |
700 |
|
|
C<ev_resume> directly afterwards to resume timer processing. |
701 |
|
|
|
702 |
|
|
Effectively, all C<ev_timer> watchers will be delayed by the time spend |
703 |
|
|
between C<ev_suspend> and C<ev_resume>, and all C<ev_periodic> watchers |
704 |
|
|
will be rescheduled (that is, they will lose any events that would have |
705 |
|
|
occured while suspended). |
706 |
|
|
|
707 |
|
|
After calling C<ev_suspend> you B<must not> call I<any> function on the |
708 |
|
|
given loop other than C<ev_resume>, and you B<must not> call C<ev_resume> |
709 |
|
|
without a previous call to C<ev_suspend>. |
710 |
|
|
|
711 |
|
|
Calling C<ev_suspend>/C<ev_resume> has the side effect of updating the |
712 |
|
|
event loop time (see C<ev_now_update>). |
713 |
|
|
|
714 |
root |
1.1 |
=item ev_loop (loop, int flags) |
715 |
|
|
|
716 |
|
|
Finally, this is it, the event handler. This function usually is called |
717 |
root |
1.268 |
after you have initialised all your watchers and you want to start |
718 |
|
|
handling events. |
719 |
root |
1.1 |
|
720 |
root |
1.33 |
If the flags argument is specified as C<0>, it will not return until |
721 |
|
|
either no event watchers are active anymore or C<ev_unloop> was called. |
722 |
root |
1.1 |
|
723 |
root |
1.34 |
Please note that an explicit C<ev_unloop> is usually better than |
724 |
|
|
relying on all watchers to be stopped when deciding when a program has |
725 |
root |
1.183 |
finished (especially in interactive programs), but having a program |
726 |
|
|
that automatically loops as long as it has to and no longer by virtue |
727 |
|
|
of relying on its watchers stopping correctly, that is truly a thing of |
728 |
|
|
beauty. |
729 |
root |
1.34 |
|
730 |
root |
1.1 |
A flags value of C<EVLOOP_NONBLOCK> will look for new events, will handle |
731 |
root |
1.183 |
those events and any already outstanding ones, but will not block your |
732 |
|
|
process in case there are no events and will return after one iteration of |
733 |
|
|
the loop. |
734 |
root |
1.1 |
|
735 |
|
|
A flags value of C<EVLOOP_ONESHOT> will look for new events (waiting if |
736 |
root |
1.183 |
necessary) and will handle those and any already outstanding ones. It |
737 |
|
|
will block your process until at least one new event arrives (which could |
738 |
root |
1.208 |
be an event internal to libev itself, so there is no guarantee that a |
739 |
root |
1.183 |
user-registered callback will be called), and will return after one |
740 |
|
|
iteration of the loop. |
741 |
|
|
|
742 |
|
|
This is useful if you are waiting for some external event in conjunction |
743 |
|
|
with something not expressible using other libev watchers (i.e. "roll your |
744 |
|
|
own C<ev_loop>"). However, a pair of C<ev_prepare>/C<ev_check> watchers is |
745 |
root |
1.33 |
usually a better approach for this kind of thing. |
746 |
|
|
|
747 |
|
|
Here are the gory details of what C<ev_loop> does: |
748 |
|
|
|
749 |
root |
1.77 |
- Before the first iteration, call any pending watchers. |
750 |
root |
1.113 |
* If EVFLAG_FORKCHECK was used, check for a fork. |
751 |
root |
1.171 |
- If a fork was detected (by any means), queue and call all fork watchers. |
752 |
root |
1.113 |
- Queue and call all prepare watchers. |
753 |
root |
1.171 |
- If we have been forked, detach and recreate the kernel state |
754 |
|
|
as to not disturb the other process. |
755 |
root |
1.33 |
- Update the kernel state with all outstanding changes. |
756 |
root |
1.171 |
- Update the "event loop time" (ev_now ()). |
757 |
root |
1.113 |
- Calculate for how long to sleep or block, if at all |
758 |
|
|
(active idle watchers, EVLOOP_NONBLOCK or not having |
759 |
|
|
any active watchers at all will result in not sleeping). |
760 |
|
|
- Sleep if the I/O and timer collect interval say so. |
761 |
root |
1.33 |
- Block the process, waiting for any events. |
762 |
|
|
- Queue all outstanding I/O (fd) events. |
763 |
root |
1.171 |
- Update the "event loop time" (ev_now ()), and do time jump adjustments. |
764 |
root |
1.183 |
- Queue all expired timers. |
765 |
|
|
- Queue all expired periodics. |
766 |
root |
1.171 |
- Unless any events are pending now, queue all idle watchers. |
767 |
root |
1.33 |
- Queue all check watchers. |
768 |
|
|
- Call all queued watchers in reverse order (i.e. check watchers first). |
769 |
|
|
Signals and child watchers are implemented as I/O watchers, and will |
770 |
|
|
be handled here by queueing them when their watcher gets executed. |
771 |
root |
1.113 |
- If ev_unloop has been called, or EVLOOP_ONESHOT or EVLOOP_NONBLOCK |
772 |
|
|
were used, or there are no active watchers, return, otherwise |
773 |
|
|
continue with step *. |
774 |
root |
1.27 |
|
775 |
root |
1.114 |
Example: Queue some jobs and then loop until no events are outstanding |
776 |
root |
1.34 |
anymore. |
777 |
|
|
|
778 |
|
|
... queue jobs here, make sure they register event watchers as long |
779 |
|
|
... as they still have work to do (even an idle watcher will do..) |
780 |
|
|
ev_loop (my_loop, 0); |
781 |
root |
1.171 |
... jobs done or somebody called unloop. yeah! |
782 |
root |
1.34 |
|
783 |
root |
1.1 |
=item ev_unloop (loop, how) |
784 |
|
|
|
785 |
root |
1.9 |
Can be used to make a call to C<ev_loop> return early (but only after it |
786 |
|
|
has processed all outstanding events). The C<how> argument must be either |
787 |
root |
1.25 |
C<EVUNLOOP_ONE>, which will make the innermost C<ev_loop> call return, or |
788 |
root |
1.9 |
C<EVUNLOOP_ALL>, which will make all nested C<ev_loop> calls return. |
789 |
root |
1.1 |
|
790 |
root |
1.115 |
This "unloop state" will be cleared when entering C<ev_loop> again. |
791 |
|
|
|
792 |
root |
1.194 |
It is safe to call C<ev_unloop> from otuside any C<ev_loop> calls. |
793 |
|
|
|
794 |
root |
1.1 |
=item ev_ref (loop) |
795 |
|
|
|
796 |
|
|
=item ev_unref (loop) |
797 |
|
|
|
798 |
root |
1.9 |
Ref/unref can be used to add or remove a reference count on the event |
799 |
|
|
loop: Every watcher keeps one reference, and as long as the reference |
800 |
root |
1.183 |
count is nonzero, C<ev_loop> will not return on its own. |
801 |
|
|
|
802 |
root |
1.276 |
This is useful when you have a watcher that you never intend to |
803 |
|
|
unregister, but that nevertheless should not keep C<ev_loop> from |
804 |
|
|
returning. In such a case, call C<ev_unref> after starting, and C<ev_ref> |
805 |
|
|
before stopping it. |
806 |
root |
1.183 |
|
807 |
root |
1.229 |
As an example, libev itself uses this for its internal signal pipe: It |
808 |
|
|
is not visible to the libev user and should not keep C<ev_loop> from |
809 |
|
|
exiting if no event watchers registered by it are active. It is also an |
810 |
|
|
excellent way to do this for generic recurring timers or from within |
811 |
|
|
third-party libraries. Just remember to I<unref after start> and I<ref |
812 |
|
|
before stop> (but only if the watcher wasn't active before, or was active |
813 |
|
|
before, respectively. Note also that libev might stop watchers itself |
814 |
|
|
(e.g. non-repeating timers) in which case you have to C<ev_ref> |
815 |
|
|
in the callback). |
816 |
root |
1.1 |
|
817 |
root |
1.54 |
Example: Create a signal watcher, but keep it from keeping C<ev_loop> |
818 |
root |
1.34 |
running when nothing else is active. |
819 |
|
|
|
820 |
root |
1.198 |
ev_signal exitsig; |
821 |
root |
1.164 |
ev_signal_init (&exitsig, sig_cb, SIGINT); |
822 |
|
|
ev_signal_start (loop, &exitsig); |
823 |
|
|
evf_unref (loop); |
824 |
root |
1.34 |
|
825 |
root |
1.54 |
Example: For some weird reason, unregister the above signal handler again. |
826 |
root |
1.34 |
|
827 |
root |
1.164 |
ev_ref (loop); |
828 |
|
|
ev_signal_stop (loop, &exitsig); |
829 |
root |
1.34 |
|
830 |
root |
1.97 |
=item ev_set_io_collect_interval (loop, ev_tstamp interval) |
831 |
|
|
|
832 |
|
|
=item ev_set_timeout_collect_interval (loop, ev_tstamp interval) |
833 |
|
|
|
834 |
|
|
These advanced functions influence the time that libev will spend waiting |
835 |
root |
1.171 |
for events. Both time intervals are by default C<0>, meaning that libev |
836 |
|
|
will try to invoke timer/periodic callbacks and I/O callbacks with minimum |
837 |
|
|
latency. |
838 |
root |
1.97 |
|
839 |
|
|
Setting these to a higher value (the C<interval> I<must> be >= C<0>) |
840 |
root |
1.171 |
allows libev to delay invocation of I/O and timer/periodic callbacks |
841 |
|
|
to increase efficiency of loop iterations (or to increase power-saving |
842 |
|
|
opportunities). |
843 |
root |
1.97 |
|
844 |
root |
1.183 |
The idea is that sometimes your program runs just fast enough to handle |
845 |
|
|
one (or very few) event(s) per loop iteration. While this makes the |
846 |
|
|
program responsive, it also wastes a lot of CPU time to poll for new |
847 |
root |
1.97 |
events, especially with backends like C<select ()> which have a high |
848 |
|
|
overhead for the actual polling but can deliver many events at once. |
849 |
|
|
|
850 |
|
|
By setting a higher I<io collect interval> you allow libev to spend more |
851 |
|
|
time collecting I/O events, so you can handle more events per iteration, |
852 |
|
|
at the cost of increasing latency. Timeouts (both C<ev_periodic> and |
853 |
ayin |
1.101 |
C<ev_timer>) will be not affected. Setting this to a non-null value will |
854 |
root |
1.245 |
introduce an additional C<ev_sleep ()> call into most loop iterations. The |
855 |
|
|
sleep time ensures that libev will not poll for I/O events more often then |
856 |
|
|
once per this interval, on average. |
857 |
root |
1.97 |
|
858 |
|
|
Likewise, by setting a higher I<timeout collect interval> you allow libev |
859 |
|
|
to spend more time collecting timeouts, at the expense of increased |
860 |
root |
1.183 |
latency/jitter/inexactness (the watcher callback will be called |
861 |
|
|
later). C<ev_io> watchers will not be affected. Setting this to a non-null |
862 |
|
|
value will not introduce any overhead in libev. |
863 |
root |
1.97 |
|
864 |
root |
1.161 |
Many (busy) programs can usually benefit by setting the I/O collect |
865 |
root |
1.98 |
interval to a value near C<0.1> or so, which is often enough for |
866 |
|
|
interactive servers (of course not for games), likewise for timeouts. It |
867 |
|
|
usually doesn't make much sense to set it to a lower value than C<0.01>, |
868 |
root |
1.245 |
as this approaches the timing granularity of most systems. Note that if |
869 |
|
|
you do transactions with the outside world and you can't increase the |
870 |
|
|
parallelity, then this setting will limit your transaction rate (if you |
871 |
|
|
need to poll once per transaction and the I/O collect interval is 0.01, |
872 |
|
|
then you can't do more than 100 transations per second). |
873 |
root |
1.97 |
|
874 |
root |
1.171 |
Setting the I<timeout collect interval> can improve the opportunity for |
875 |
|
|
saving power, as the program will "bundle" timer callback invocations that |
876 |
|
|
are "near" in time together, by delaying some, thus reducing the number of |
877 |
|
|
times the process sleeps and wakes up again. Another useful technique to |
878 |
|
|
reduce iterations/wake-ups is to use C<ev_periodic> watchers and make sure |
879 |
|
|
they fire on, say, one-second boundaries only. |
880 |
|
|
|
881 |
root |
1.245 |
Example: we only need 0.1s timeout granularity, and we wish not to poll |
882 |
|
|
more often than 100 times per second: |
883 |
|
|
|
884 |
|
|
ev_set_timeout_collect_interval (EV_DEFAULT_UC_ 0.1); |
885 |
|
|
ev_set_io_collect_interval (EV_DEFAULT_UC_ 0.01); |
886 |
|
|
|
887 |
root |
1.253 |
=item ev_invoke_pending (loop) |
888 |
|
|
|
889 |
|
|
This call will simply invoke all pending watchers while resetting their |
890 |
|
|
pending state. Normally, C<ev_loop> does this automatically when required, |
891 |
|
|
but when overriding the invoke callback this call comes handy. |
892 |
|
|
|
893 |
root |
1.256 |
=item int ev_pending_count (loop) |
894 |
|
|
|
895 |
|
|
Returns the number of pending watchers - zero indicates that no watchers |
896 |
|
|
are pending. |
897 |
|
|
|
898 |
root |
1.253 |
=item ev_set_invoke_pending_cb (loop, void (*invoke_pending_cb)(EV_P)) |
899 |
|
|
|
900 |
|
|
This overrides the invoke pending functionality of the loop: Instead of |
901 |
|
|
invoking all pending watchers when there are any, C<ev_loop> will call |
902 |
|
|
this callback instead. This is useful, for example, when you want to |
903 |
|
|
invoke the actual watchers inside another context (another thread etc.). |
904 |
|
|
|
905 |
|
|
If you want to reset the callback, use C<ev_invoke_pending> as new |
906 |
|
|
callback. |
907 |
|
|
|
908 |
|
|
=item ev_set_loop_release_cb (loop, void (*release)(EV_P), void (*acquire)(EV_P)) |
909 |
|
|
|
910 |
|
|
Sometimes you want to share the same loop between multiple threads. This |
911 |
|
|
can be done relatively simply by putting mutex_lock/unlock calls around |
912 |
|
|
each call to a libev function. |
913 |
|
|
|
914 |
|
|
However, C<ev_loop> can run an indefinite time, so it is not feasible to |
915 |
|
|
wait for it to return. One way around this is to wake up the loop via |
916 |
|
|
C<ev_unloop> and C<av_async_send>, another way is to set these I<release> |
917 |
|
|
and I<acquire> callbacks on the loop. |
918 |
|
|
|
919 |
|
|
When set, then C<release> will be called just before the thread is |
920 |
|
|
suspended waiting for new events, and C<acquire> is called just |
921 |
|
|
afterwards. |
922 |
|
|
|
923 |
|
|
Ideally, C<release> will just call your mutex_unlock function, and |
924 |
|
|
C<acquire> will just call the mutex_lock function again. |
925 |
|
|
|
926 |
root |
1.254 |
While event loop modifications are allowed between invocations of |
927 |
|
|
C<release> and C<acquire> (that's their only purpose after all), no |
928 |
|
|
modifications done will affect the event loop, i.e. adding watchers will |
929 |
|
|
have no effect on the set of file descriptors being watched, or the time |
930 |
root |
1.274 |
waited. Use an C<ev_async> watcher to wake up C<ev_loop> when you want it |
931 |
root |
1.254 |
to take note of any changes you made. |
932 |
|
|
|
933 |
|
|
In theory, threads executing C<ev_loop> will be async-cancel safe between |
934 |
|
|
invocations of C<release> and C<acquire>. |
935 |
|
|
|
936 |
|
|
See also the locking example in the C<THREADS> section later in this |
937 |
|
|
document. |
938 |
|
|
|
939 |
root |
1.253 |
=item ev_set_userdata (loop, void *data) |
940 |
|
|
|
941 |
|
|
=item ev_userdata (loop) |
942 |
|
|
|
943 |
|
|
Set and retrieve a single C<void *> associated with a loop. When |
944 |
|
|
C<ev_set_userdata> has never been called, then C<ev_userdata> returns |
945 |
|
|
C<0.> |
946 |
|
|
|
947 |
|
|
These two functions can be used to associate arbitrary data with a loop, |
948 |
|
|
and are intended solely for the C<invoke_pending_cb>, C<release> and |
949 |
|
|
C<acquire> callbacks described above, but of course can be (ab-)used for |
950 |
|
|
any other purpose as well. |
951 |
|
|
|
952 |
root |
1.159 |
=item ev_loop_verify (loop) |
953 |
|
|
|
954 |
|
|
This function only does something when C<EV_VERIFY> support has been |
955 |
root |
1.200 |
compiled in, which is the default for non-minimal builds. It tries to go |
956 |
root |
1.183 |
through all internal structures and checks them for validity. If anything |
957 |
|
|
is found to be inconsistent, it will print an error message to standard |
958 |
|
|
error and call C<abort ()>. |
959 |
root |
1.159 |
|
960 |
|
|
This can be used to catch bugs inside libev itself: under normal |
961 |
|
|
circumstances, this function will never abort as of course libev keeps its |
962 |
|
|
data structures consistent. |
963 |
|
|
|
964 |
root |
1.1 |
=back |
965 |
|
|
|
966 |
root |
1.42 |
|
967 |
root |
1.1 |
=head1 ANATOMY OF A WATCHER |
968 |
|
|
|
969 |
root |
1.200 |
In the following description, uppercase C<TYPE> in names stands for the |
970 |
|
|
watcher type, e.g. C<ev_TYPE_start> can mean C<ev_timer_start> for timer |
971 |
|
|
watchers and C<ev_io_start> for I/O watchers. |
972 |
|
|
|
973 |
root |
1.1 |
A watcher is a structure that you create and register to record your |
974 |
|
|
interest in some event. For instance, if you want to wait for STDIN to |
975 |
root |
1.10 |
become readable, you would create an C<ev_io> watcher for that: |
976 |
root |
1.1 |
|
977 |
root |
1.198 |
static void my_cb (struct ev_loop *loop, ev_io *w, int revents) |
978 |
root |
1.164 |
{ |
979 |
|
|
ev_io_stop (w); |
980 |
|
|
ev_unloop (loop, EVUNLOOP_ALL); |
981 |
|
|
} |
982 |
|
|
|
983 |
|
|
struct ev_loop *loop = ev_default_loop (0); |
984 |
root |
1.200 |
|
985 |
root |
1.198 |
ev_io stdin_watcher; |
986 |
root |
1.200 |
|
987 |
root |
1.164 |
ev_init (&stdin_watcher, my_cb); |
988 |
|
|
ev_io_set (&stdin_watcher, STDIN_FILENO, EV_READ); |
989 |
|
|
ev_io_start (loop, &stdin_watcher); |
990 |
root |
1.200 |
|
991 |
root |
1.164 |
ev_loop (loop, 0); |
992 |
root |
1.1 |
|
993 |
|
|
As you can see, you are responsible for allocating the memory for your |
994 |
root |
1.200 |
watcher structures (and it is I<usually> a bad idea to do this on the |
995 |
|
|
stack). |
996 |
|
|
|
997 |
|
|
Each watcher has an associated watcher structure (called C<struct ev_TYPE> |
998 |
|
|
or simply C<ev_TYPE>, as typedefs are provided for all watcher structs). |
999 |
root |
1.1 |
|
1000 |
|
|
Each watcher structure must be initialised by a call to C<ev_init |
1001 |
|
|
(watcher *, callback)>, which expects a callback to be provided. This |
1002 |
root |
1.161 |
callback gets invoked each time the event occurs (or, in the case of I/O |
1003 |
root |
1.1 |
watchers, each time the event loop detects that the file descriptor given |
1004 |
|
|
is readable and/or writable). |
1005 |
|
|
|
1006 |
root |
1.200 |
Each watcher type further has its own C<< ev_TYPE_set (watcher *, ...) >> |
1007 |
|
|
macro to configure it, with arguments specific to the watcher type. There |
1008 |
|
|
is also a macro to combine initialisation and setting in one call: C<< |
1009 |
|
|
ev_TYPE_init (watcher *, callback, ...) >>. |
1010 |
root |
1.1 |
|
1011 |
|
|
To make the watcher actually watch out for events, you have to start it |
1012 |
root |
1.200 |
with a watcher-specific start function (C<< ev_TYPE_start (loop, watcher |
1013 |
root |
1.1 |
*) >>), and you can stop watching for events at any time by calling the |
1014 |
root |
1.200 |
corresponding stop function (C<< ev_TYPE_stop (loop, watcher *) >>. |
1015 |
root |
1.1 |
|
1016 |
|
|
As long as your watcher is active (has been started but not stopped) you |
1017 |
|
|
must not touch the values stored in it. Most specifically you must never |
1018 |
root |
1.200 |
reinitialise it or call its C<ev_TYPE_set> macro. |
1019 |
root |
1.1 |
|
1020 |
|
|
Each and every callback receives the event loop pointer as first, the |
1021 |
|
|
registered watcher structure as second, and a bitset of received events as |
1022 |
|
|
third argument. |
1023 |
|
|
|
1024 |
root |
1.14 |
The received events usually include a single bit per event type received |
1025 |
root |
1.1 |
(you can receive multiple events at the same time). The possible bit masks |
1026 |
|
|
are: |
1027 |
|
|
|
1028 |
|
|
=over 4 |
1029 |
|
|
|
1030 |
root |
1.10 |
=item C<EV_READ> |
1031 |
root |
1.1 |
|
1032 |
root |
1.10 |
=item C<EV_WRITE> |
1033 |
root |
1.1 |
|
1034 |
root |
1.10 |
The file descriptor in the C<ev_io> watcher has become readable and/or |
1035 |
root |
1.1 |
writable. |
1036 |
|
|
|
1037 |
root |
1.10 |
=item C<EV_TIMEOUT> |
1038 |
root |
1.1 |
|
1039 |
root |
1.10 |
The C<ev_timer> watcher has timed out. |
1040 |
root |
1.1 |
|
1041 |
root |
1.10 |
=item C<EV_PERIODIC> |
1042 |
root |
1.1 |
|
1043 |
root |
1.10 |
The C<ev_periodic> watcher has timed out. |
1044 |
root |
1.1 |
|
1045 |
root |
1.10 |
=item C<EV_SIGNAL> |
1046 |
root |
1.1 |
|
1047 |
root |
1.10 |
The signal specified in the C<ev_signal> watcher has been received by a thread. |
1048 |
root |
1.1 |
|
1049 |
root |
1.10 |
=item C<EV_CHILD> |
1050 |
root |
1.1 |
|
1051 |
root |
1.10 |
The pid specified in the C<ev_child> watcher has received a status change. |
1052 |
root |
1.1 |
|
1053 |
root |
1.48 |
=item C<EV_STAT> |
1054 |
|
|
|
1055 |
|
|
The path specified in the C<ev_stat> watcher changed its attributes somehow. |
1056 |
|
|
|
1057 |
root |
1.10 |
=item C<EV_IDLE> |
1058 |
root |
1.1 |
|
1059 |
root |
1.10 |
The C<ev_idle> watcher has determined that you have nothing better to do. |
1060 |
root |
1.1 |
|
1061 |
root |
1.10 |
=item C<EV_PREPARE> |
1062 |
root |
1.1 |
|
1063 |
root |
1.10 |
=item C<EV_CHECK> |
1064 |
root |
1.1 |
|
1065 |
root |
1.10 |
All C<ev_prepare> watchers are invoked just I<before> C<ev_loop> starts |
1066 |
|
|
to gather new events, and all C<ev_check> watchers are invoked just after |
1067 |
root |
1.1 |
C<ev_loop> has gathered them, but before it invokes any callbacks for any |
1068 |
|
|
received events. Callbacks of both watcher types can start and stop as |
1069 |
|
|
many watchers as they want, and all of them will be taken into account |
1070 |
root |
1.10 |
(for example, a C<ev_prepare> watcher might start an idle watcher to keep |
1071 |
root |
1.1 |
C<ev_loop> from blocking). |
1072 |
|
|
|
1073 |
root |
1.50 |
=item C<EV_EMBED> |
1074 |
|
|
|
1075 |
|
|
The embedded event loop specified in the C<ev_embed> watcher needs attention. |
1076 |
|
|
|
1077 |
|
|
=item C<EV_FORK> |
1078 |
|
|
|
1079 |
|
|
The event loop has been resumed in the child process after fork (see |
1080 |
|
|
C<ev_fork>). |
1081 |
|
|
|
1082 |
root |
1.122 |
=item C<EV_ASYNC> |
1083 |
|
|
|
1084 |
|
|
The given async watcher has been asynchronously notified (see C<ev_async>). |
1085 |
|
|
|
1086 |
root |
1.229 |
=item C<EV_CUSTOM> |
1087 |
|
|
|
1088 |
|
|
Not ever sent (or otherwise used) by libev itself, but can be freely used |
1089 |
|
|
by libev users to signal watchers (e.g. via C<ev_feed_event>). |
1090 |
|
|
|
1091 |
root |
1.10 |
=item C<EV_ERROR> |
1092 |
root |
1.1 |
|
1093 |
root |
1.161 |
An unspecified error has occurred, the watcher has been stopped. This might |
1094 |
root |
1.1 |
happen because the watcher could not be properly started because libev |
1095 |
|
|
ran out of memory, a file descriptor was found to be closed or any other |
1096 |
root |
1.197 |
problem. Libev considers these application bugs. |
1097 |
|
|
|
1098 |
|
|
You best act on it by reporting the problem and somehow coping with the |
1099 |
|
|
watcher being stopped. Note that well-written programs should not receive |
1100 |
|
|
an error ever, so when your watcher receives it, this usually indicates a |
1101 |
|
|
bug in your program. |
1102 |
root |
1.1 |
|
1103 |
root |
1.183 |
Libev will usually signal a few "dummy" events together with an error, for |
1104 |
|
|
example it might indicate that a fd is readable or writable, and if your |
1105 |
|
|
callbacks is well-written it can just attempt the operation and cope with |
1106 |
|
|
the error from read() or write(). This will not work in multi-threaded |
1107 |
|
|
programs, though, as the fd could already be closed and reused for another |
1108 |
|
|
thing, so beware. |
1109 |
root |
1.1 |
|
1110 |
|
|
=back |
1111 |
|
|
|
1112 |
root |
1.42 |
=head2 GENERIC WATCHER FUNCTIONS |
1113 |
root |
1.36 |
|
1114 |
|
|
=over 4 |
1115 |
|
|
|
1116 |
|
|
=item C<ev_init> (ev_TYPE *watcher, callback) |
1117 |
|
|
|
1118 |
|
|
This macro initialises the generic portion of a watcher. The contents |
1119 |
|
|
of the watcher object can be arbitrary (so C<malloc> will do). Only |
1120 |
|
|
the generic parts of the watcher are initialised, you I<need> to call |
1121 |
|
|
the type-specific C<ev_TYPE_set> macro afterwards to initialise the |
1122 |
|
|
type-specific parts. For each type there is also a C<ev_TYPE_init> macro |
1123 |
|
|
which rolls both calls into one. |
1124 |
|
|
|
1125 |
|
|
You can reinitialise a watcher at any time as long as it has been stopped |
1126 |
|
|
(or never started) and there are no pending events outstanding. |
1127 |
|
|
|
1128 |
root |
1.198 |
The callback is always of type C<void (*)(struct ev_loop *loop, ev_TYPE *watcher, |
1129 |
root |
1.36 |
int revents)>. |
1130 |
|
|
|
1131 |
root |
1.183 |
Example: Initialise an C<ev_io> watcher in two steps. |
1132 |
|
|
|
1133 |
|
|
ev_io w; |
1134 |
|
|
ev_init (&w, my_cb); |
1135 |
|
|
ev_io_set (&w, STDIN_FILENO, EV_READ); |
1136 |
|
|
|
1137 |
root |
1.274 |
=item C<ev_TYPE_set> (ev_TYPE *watcher, [args]) |
1138 |
root |
1.36 |
|
1139 |
|
|
This macro initialises the type-specific parts of a watcher. You need to |
1140 |
|
|
call C<ev_init> at least once before you call this macro, but you can |
1141 |
|
|
call C<ev_TYPE_set> any number of times. You must not, however, call this |
1142 |
|
|
macro on a watcher that is active (it can be pending, however, which is a |
1143 |
|
|
difference to the C<ev_init> macro). |
1144 |
|
|
|
1145 |
|
|
Although some watcher types do not have type-specific arguments |
1146 |
|
|
(e.g. C<ev_prepare>) you still need to call its C<set> macro. |
1147 |
|
|
|
1148 |
root |
1.183 |
See C<ev_init>, above, for an example. |
1149 |
|
|
|
1150 |
root |
1.36 |
=item C<ev_TYPE_init> (ev_TYPE *watcher, callback, [args]) |
1151 |
|
|
|
1152 |
root |
1.161 |
This convenience macro rolls both C<ev_init> and C<ev_TYPE_set> macro |
1153 |
|
|
calls into a single call. This is the most convenient method to initialise |
1154 |
root |
1.36 |
a watcher. The same limitations apply, of course. |
1155 |
|
|
|
1156 |
root |
1.183 |
Example: Initialise and set an C<ev_io> watcher in one step. |
1157 |
|
|
|
1158 |
|
|
ev_io_init (&w, my_cb, STDIN_FILENO, EV_READ); |
1159 |
|
|
|
1160 |
root |
1.274 |
=item C<ev_TYPE_start> (loop, ev_TYPE *watcher) |
1161 |
root |
1.36 |
|
1162 |
|
|
Starts (activates) the given watcher. Only active watchers will receive |
1163 |
|
|
events. If the watcher is already active nothing will happen. |
1164 |
|
|
|
1165 |
root |
1.183 |
Example: Start the C<ev_io> watcher that is being abused as example in this |
1166 |
|
|
whole section. |
1167 |
|
|
|
1168 |
|
|
ev_io_start (EV_DEFAULT_UC, &w); |
1169 |
|
|
|
1170 |
root |
1.274 |
=item C<ev_TYPE_stop> (loop, ev_TYPE *watcher) |
1171 |
root |
1.36 |
|
1172 |
root |
1.195 |
Stops the given watcher if active, and clears the pending status (whether |
1173 |
|
|
the watcher was active or not). |
1174 |
|
|
|
1175 |
|
|
It is possible that stopped watchers are pending - for example, |
1176 |
|
|
non-repeating timers are being stopped when they become pending - but |
1177 |
|
|
calling C<ev_TYPE_stop> ensures that the watcher is neither active nor |
1178 |
|
|
pending. If you want to free or reuse the memory used by the watcher it is |
1179 |
|
|
therefore a good idea to always call its C<ev_TYPE_stop> function. |
1180 |
root |
1.36 |
|
1181 |
|
|
=item bool ev_is_active (ev_TYPE *watcher) |
1182 |
|
|
|
1183 |
|
|
Returns a true value iff the watcher is active (i.e. it has been started |
1184 |
|
|
and not yet been stopped). As long as a watcher is active you must not modify |
1185 |
|
|
it. |
1186 |
|
|
|
1187 |
|
|
=item bool ev_is_pending (ev_TYPE *watcher) |
1188 |
|
|
|
1189 |
|
|
Returns a true value iff the watcher is pending, (i.e. it has outstanding |
1190 |
|
|
events but its callback has not yet been invoked). As long as a watcher |
1191 |
|
|
is pending (but not active) you must not call an init function on it (but |
1192 |
root |
1.73 |
C<ev_TYPE_set> is safe), you must not change its priority, and you must |
1193 |
|
|
make sure the watcher is available to libev (e.g. you cannot C<free ()> |
1194 |
|
|
it). |
1195 |
root |
1.36 |
|
1196 |
root |
1.55 |
=item callback ev_cb (ev_TYPE *watcher) |
1197 |
root |
1.36 |
|
1198 |
|
|
Returns the callback currently set on the watcher. |
1199 |
|
|
|
1200 |
|
|
=item ev_cb_set (ev_TYPE *watcher, callback) |
1201 |
|
|
|
1202 |
|
|
Change the callback. You can change the callback at virtually any time |
1203 |
|
|
(modulo threads). |
1204 |
|
|
|
1205 |
root |
1.274 |
=item ev_set_priority (ev_TYPE *watcher, int priority) |
1206 |
root |
1.67 |
|
1207 |
|
|
=item int ev_priority (ev_TYPE *watcher) |
1208 |
|
|
|
1209 |
|
|
Set and query the priority of the watcher. The priority is a small |
1210 |
|
|
integer between C<EV_MAXPRI> (default: C<2>) and C<EV_MINPRI> |
1211 |
|
|
(default: C<-2>). Pending watchers with higher priority will be invoked |
1212 |
|
|
before watchers with lower priority, but priority will not keep watchers |
1213 |
|
|
from being executed (except for C<ev_idle> watchers). |
1214 |
|
|
|
1215 |
|
|
If you need to suppress invocation when higher priority events are pending |
1216 |
|
|
you need to look at C<ev_idle> watchers, which provide this functionality. |
1217 |
|
|
|
1218 |
root |
1.73 |
You I<must not> change the priority of a watcher as long as it is active or |
1219 |
|
|
pending. |
1220 |
|
|
|
1221 |
root |
1.233 |
Setting a priority outside the range of C<EV_MINPRI> to C<EV_MAXPRI> is |
1222 |
|
|
fine, as long as you do not mind that the priority value you query might |
1223 |
|
|
or might not have been clamped to the valid range. |
1224 |
|
|
|
1225 |
root |
1.67 |
The default priority used by watchers when no priority has been set is |
1226 |
|
|
always C<0>, which is supposed to not be too high and not be too low :). |
1227 |
|
|
|
1228 |
root |
1.235 |
See L<WATCHER PRIORITY MODELS>, below, for a more thorough treatment of |
1229 |
root |
1.233 |
priorities. |
1230 |
root |
1.67 |
|
1231 |
root |
1.74 |
=item ev_invoke (loop, ev_TYPE *watcher, int revents) |
1232 |
|
|
|
1233 |
|
|
Invoke the C<watcher> with the given C<loop> and C<revents>. Neither |
1234 |
|
|
C<loop> nor C<revents> need to be valid as long as the watcher callback |
1235 |
root |
1.183 |
can deal with that fact, as both are simply passed through to the |
1236 |
|
|
callback. |
1237 |
root |
1.74 |
|
1238 |
|
|
=item int ev_clear_pending (loop, ev_TYPE *watcher) |
1239 |
|
|
|
1240 |
root |
1.183 |
If the watcher is pending, this function clears its pending status and |
1241 |
|
|
returns its C<revents> bitset (as if its callback was invoked). If the |
1242 |
root |
1.74 |
watcher isn't pending it does nothing and returns C<0>. |
1243 |
|
|
|
1244 |
root |
1.183 |
Sometimes it can be useful to "poll" a watcher instead of waiting for its |
1245 |
|
|
callback to be invoked, which can be accomplished with this function. |
1246 |
|
|
|
1247 |
root |
1.274 |
=item ev_feed_event (loop, ev_TYPE *watcher, int revents) |
1248 |
root |
1.273 |
|
1249 |
|
|
Feeds the given event set into the event loop, as if the specified event |
1250 |
|
|
had happened for the specified watcher (which must be a pointer to an |
1251 |
|
|
initialised but not necessarily started event watcher). Obviously you must |
1252 |
|
|
not free the watcher as long as it has pending events. |
1253 |
|
|
|
1254 |
|
|
Stopping the watcher, letting libev invoke it, or calling |
1255 |
|
|
C<ev_clear_pending> will clear the pending event, even if the watcher was |
1256 |
|
|
not started in the first place. |
1257 |
|
|
|
1258 |
|
|
See also C<ev_feed_fd_event> and C<ev_feed_signal_event> for related |
1259 |
|
|
functions that do not need a watcher. |
1260 |
|
|
|
1261 |
root |
1.36 |
=back |
1262 |
|
|
|
1263 |
|
|
|
1264 |
root |
1.1 |
=head2 ASSOCIATING CUSTOM DATA WITH A WATCHER |
1265 |
|
|
|
1266 |
|
|
Each watcher has, by default, a member C<void *data> that you can change |
1267 |
root |
1.183 |
and read at any time: libev will completely ignore it. This can be used |
1268 |
root |
1.1 |
to associate arbitrary data with your watcher. If you need more data and |
1269 |
|
|
don't want to allocate memory and store a pointer to it in that data |
1270 |
|
|
member, you can also "subclass" the watcher type and provide your own |
1271 |
|
|
data: |
1272 |
|
|
|
1273 |
root |
1.164 |
struct my_io |
1274 |
|
|
{ |
1275 |
root |
1.198 |
ev_io io; |
1276 |
root |
1.164 |
int otherfd; |
1277 |
|
|
void *somedata; |
1278 |
|
|
struct whatever *mostinteresting; |
1279 |
root |
1.178 |
}; |
1280 |
|
|
|
1281 |
|
|
... |
1282 |
|
|
struct my_io w; |
1283 |
|
|
ev_io_init (&w.io, my_cb, fd, EV_READ); |
1284 |
root |
1.1 |
|
1285 |
|
|
And since your callback will be called with a pointer to the watcher, you |
1286 |
|
|
can cast it back to your own type: |
1287 |
|
|
|
1288 |
root |
1.198 |
static void my_cb (struct ev_loop *loop, ev_io *w_, int revents) |
1289 |
root |
1.164 |
{ |
1290 |
|
|
struct my_io *w = (struct my_io *)w_; |
1291 |
|
|
... |
1292 |
|
|
} |
1293 |
root |
1.1 |
|
1294 |
root |
1.55 |
More interesting and less C-conformant ways of casting your callback type |
1295 |
|
|
instead have been omitted. |
1296 |
|
|
|
1297 |
root |
1.178 |
Another common scenario is to use some data structure with multiple |
1298 |
|
|
embedded watchers: |
1299 |
root |
1.55 |
|
1300 |
root |
1.164 |
struct my_biggy |
1301 |
|
|
{ |
1302 |
|
|
int some_data; |
1303 |
|
|
ev_timer t1; |
1304 |
|
|
ev_timer t2; |
1305 |
|
|
} |
1306 |
root |
1.55 |
|
1307 |
root |
1.178 |
In this case getting the pointer to C<my_biggy> is a bit more |
1308 |
|
|
complicated: Either you store the address of your C<my_biggy> struct |
1309 |
root |
1.183 |
in the C<data> member of the watcher (for woozies), or you need to use |
1310 |
|
|
some pointer arithmetic using C<offsetof> inside your watchers (for real |
1311 |
|
|
programmers): |
1312 |
root |
1.55 |
|
1313 |
root |
1.164 |
#include <stddef.h> |
1314 |
|
|
|
1315 |
|
|
static void |
1316 |
root |
1.198 |
t1_cb (EV_P_ ev_timer *w, int revents) |
1317 |
root |
1.164 |
{ |
1318 |
root |
1.242 |
struct my_biggy big = (struct my_biggy *) |
1319 |
root |
1.164 |
(((char *)w) - offsetof (struct my_biggy, t1)); |
1320 |
|
|
} |
1321 |
root |
1.55 |
|
1322 |
root |
1.164 |
static void |
1323 |
root |
1.198 |
t2_cb (EV_P_ ev_timer *w, int revents) |
1324 |
root |
1.164 |
{ |
1325 |
root |
1.242 |
struct my_biggy big = (struct my_biggy *) |
1326 |
root |
1.164 |
(((char *)w) - offsetof (struct my_biggy, t2)); |
1327 |
|
|
} |
1328 |
root |
1.1 |
|
1329 |
root |
1.233 |
=head2 WATCHER PRIORITY MODELS |
1330 |
|
|
|
1331 |
|
|
Many event loops support I<watcher priorities>, which are usually small |
1332 |
|
|
integers that influence the ordering of event callback invocation |
1333 |
|
|
between watchers in some way, all else being equal. |
1334 |
|
|
|
1335 |
|
|
In libev, Watcher priorities can be set using C<ev_set_priority>. See its |
1336 |
|
|
description for the more technical details such as the actual priority |
1337 |
|
|
range. |
1338 |
|
|
|
1339 |
|
|
There are two common ways how these these priorities are being interpreted |
1340 |
|
|
by event loops: |
1341 |
|
|
|
1342 |
|
|
In the more common lock-out model, higher priorities "lock out" invocation |
1343 |
|
|
of lower priority watchers, which means as long as higher priority |
1344 |
|
|
watchers receive events, lower priority watchers are not being invoked. |
1345 |
|
|
|
1346 |
|
|
The less common only-for-ordering model uses priorities solely to order |
1347 |
|
|
callback invocation within a single event loop iteration: Higher priority |
1348 |
|
|
watchers are invoked before lower priority ones, but they all get invoked |
1349 |
|
|
before polling for new events. |
1350 |
|
|
|
1351 |
|
|
Libev uses the second (only-for-ordering) model for all its watchers |
1352 |
|
|
except for idle watchers (which use the lock-out model). |
1353 |
|
|
|
1354 |
|
|
The rationale behind this is that implementing the lock-out model for |
1355 |
|
|
watchers is not well supported by most kernel interfaces, and most event |
1356 |
|
|
libraries will just poll for the same events again and again as long as |
1357 |
|
|
their callbacks have not been executed, which is very inefficient in the |
1358 |
|
|
common case of one high-priority watcher locking out a mass of lower |
1359 |
|
|
priority ones. |
1360 |
|
|
|
1361 |
|
|
Static (ordering) priorities are most useful when you have two or more |
1362 |
|
|
watchers handling the same resource: a typical usage example is having an |
1363 |
|
|
C<ev_io> watcher to receive data, and an associated C<ev_timer> to handle |
1364 |
|
|
timeouts. Under load, data might be received while the program handles |
1365 |
|
|
other jobs, but since timers normally get invoked first, the timeout |
1366 |
|
|
handler will be executed before checking for data. In that case, giving |
1367 |
|
|
the timer a lower priority than the I/O watcher ensures that I/O will be |
1368 |
|
|
handled first even under adverse conditions (which is usually, but not |
1369 |
|
|
always, what you want). |
1370 |
|
|
|
1371 |
|
|
Since idle watchers use the "lock-out" model, meaning that idle watchers |
1372 |
|
|
will only be executed when no same or higher priority watchers have |
1373 |
|
|
received events, they can be used to implement the "lock-out" model when |
1374 |
|
|
required. |
1375 |
|
|
|
1376 |
|
|
For example, to emulate how many other event libraries handle priorities, |
1377 |
|
|
you can associate an C<ev_idle> watcher to each such watcher, and in |
1378 |
|
|
the normal watcher callback, you just start the idle watcher. The real |
1379 |
|
|
processing is done in the idle watcher callback. This causes libev to |
1380 |
|
|
continously poll and process kernel event data for the watcher, but when |
1381 |
|
|
the lock-out case is known to be rare (which in turn is rare :), this is |
1382 |
|
|
workable. |
1383 |
|
|
|
1384 |
|
|
Usually, however, the lock-out model implemented that way will perform |
1385 |
|
|
miserably under the type of load it was designed to handle. In that case, |
1386 |
|
|
it might be preferable to stop the real watcher before starting the |
1387 |
|
|
idle watcher, so the kernel will not have to process the event in case |
1388 |
|
|
the actual processing will be delayed for considerable time. |
1389 |
|
|
|
1390 |
|
|
Here is an example of an I/O watcher that should run at a strictly lower |
1391 |
|
|
priority than the default, and which should only process data when no |
1392 |
|
|
other events are pending: |
1393 |
|
|
|
1394 |
|
|
ev_idle idle; // actual processing watcher |
1395 |
|
|
ev_io io; // actual event watcher |
1396 |
|
|
|
1397 |
|
|
static void |
1398 |
|
|
io_cb (EV_P_ ev_io *w, int revents) |
1399 |
|
|
{ |
1400 |
|
|
// stop the I/O watcher, we received the event, but |
1401 |
|
|
// are not yet ready to handle it. |
1402 |
|
|
ev_io_stop (EV_A_ w); |
1403 |
|
|
|
1404 |
|
|
// start the idle watcher to ahndle the actual event. |
1405 |
|
|
// it will not be executed as long as other watchers |
1406 |
|
|
// with the default priority are receiving events. |
1407 |
|
|
ev_idle_start (EV_A_ &idle); |
1408 |
|
|
} |
1409 |
|
|
|
1410 |
|
|
static void |
1411 |
root |
1.242 |
idle_cb (EV_P_ ev_idle *w, int revents) |
1412 |
root |
1.233 |
{ |
1413 |
|
|
// actual processing |
1414 |
|
|
read (STDIN_FILENO, ...); |
1415 |
|
|
|
1416 |
|
|
// have to start the I/O watcher again, as |
1417 |
|
|
// we have handled the event |
1418 |
|
|
ev_io_start (EV_P_ &io); |
1419 |
|
|
} |
1420 |
|
|
|
1421 |
|
|
// initialisation |
1422 |
|
|
ev_idle_init (&idle, idle_cb); |
1423 |
|
|
ev_io_init (&io, io_cb, STDIN_FILENO, EV_READ); |
1424 |
|
|
ev_io_start (EV_DEFAULT_ &io); |
1425 |
|
|
|
1426 |
|
|
In the "real" world, it might also be beneficial to start a timer, so that |
1427 |
|
|
low-priority connections can not be locked out forever under load. This |
1428 |
|
|
enables your program to keep a lower latency for important connections |
1429 |
|
|
during short periods of high load, while not completely locking out less |
1430 |
|
|
important ones. |
1431 |
|
|
|
1432 |
root |
1.1 |
|
1433 |
|
|
=head1 WATCHER TYPES |
1434 |
|
|
|
1435 |
|
|
This section describes each watcher in detail, but will not repeat |
1436 |
root |
1.48 |
information given in the last section. Any initialisation/set macros, |
1437 |
|
|
functions and members specific to the watcher type are explained. |
1438 |
|
|
|
1439 |
|
|
Members are additionally marked with either I<[read-only]>, meaning that, |
1440 |
|
|
while the watcher is active, you can look at the member and expect some |
1441 |
|
|
sensible content, but you must not modify it (you can modify it while the |
1442 |
|
|
watcher is stopped to your hearts content), or I<[read-write]>, which |
1443 |
|
|
means you can expect it to have some sensible content while the watcher |
1444 |
|
|
is active, but you can also modify it. Modifying it may not do something |
1445 |
|
|
sensible or take immediate effect (or do anything at all), but libev will |
1446 |
|
|
not crash or malfunction in any way. |
1447 |
root |
1.1 |
|
1448 |
root |
1.34 |
|
1449 |
root |
1.42 |
=head2 C<ev_io> - is this file descriptor readable or writable? |
1450 |
root |
1.1 |
|
1451 |
root |
1.4 |
I/O watchers check whether a file descriptor is readable or writable |
1452 |
root |
1.42 |
in each iteration of the event loop, or, more precisely, when reading |
1453 |
|
|
would not block the process and writing would at least be able to write |
1454 |
|
|
some data. This behaviour is called level-triggering because you keep |
1455 |
|
|
receiving events as long as the condition persists. Remember you can stop |
1456 |
|
|
the watcher if you don't want to act on the event and neither want to |
1457 |
|
|
receive future events. |
1458 |
root |
1.1 |
|
1459 |
root |
1.23 |
In general you can register as many read and/or write event watchers per |
1460 |
root |
1.8 |
fd as you want (as long as you don't confuse yourself). Setting all file |
1461 |
|
|
descriptors to non-blocking mode is also usually a good idea (but not |
1462 |
|
|
required if you know what you are doing). |
1463 |
|
|
|
1464 |
root |
1.183 |
If you cannot use non-blocking mode, then force the use of a |
1465 |
|
|
known-to-be-good backend (at the time of this writing, this includes only |
1466 |
root |
1.239 |
C<EVBACKEND_SELECT> and C<EVBACKEND_POLL>). The same applies to file |
1467 |
|
|
descriptors for which non-blocking operation makes no sense (such as |
1468 |
|
|
files) - libev doesn't guarentee any specific behaviour in that case. |
1469 |
root |
1.8 |
|
1470 |
root |
1.42 |
Another thing you have to watch out for is that it is quite easy to |
1471 |
root |
1.155 |
receive "spurious" readiness notifications, that is your callback might |
1472 |
root |
1.42 |
be called with C<EV_READ> but a subsequent C<read>(2) will actually block |
1473 |
|
|
because there is no data. Not only are some backends known to create a |
1474 |
root |
1.161 |
lot of those (for example Solaris ports), it is very easy to get into |
1475 |
root |
1.42 |
this situation even with a relatively standard program structure. Thus |
1476 |
|
|
it is best to always use non-blocking I/O: An extra C<read>(2) returning |
1477 |
|
|
C<EAGAIN> is far preferable to a program hanging until some data arrives. |
1478 |
|
|
|
1479 |
root |
1.183 |
If you cannot run the fd in non-blocking mode (for example you should |
1480 |
|
|
not play around with an Xlib connection), then you have to separately |
1481 |
|
|
re-test whether a file descriptor is really ready with a known-to-be good |
1482 |
|
|
interface such as poll (fortunately in our Xlib example, Xlib already |
1483 |
|
|
does this on its own, so its quite safe to use). Some people additionally |
1484 |
|
|
use C<SIGALRM> and an interval timer, just to be sure you won't block |
1485 |
|
|
indefinitely. |
1486 |
|
|
|
1487 |
|
|
But really, best use non-blocking mode. |
1488 |
root |
1.42 |
|
1489 |
root |
1.81 |
=head3 The special problem of disappearing file descriptors |
1490 |
|
|
|
1491 |
root |
1.94 |
Some backends (e.g. kqueue, epoll) need to be told about closing a file |
1492 |
root |
1.183 |
descriptor (either due to calling C<close> explicitly or any other means, |
1493 |
|
|
such as C<dup2>). The reason is that you register interest in some file |
1494 |
root |
1.81 |
descriptor, but when it goes away, the operating system will silently drop |
1495 |
|
|
this interest. If another file descriptor with the same number then is |
1496 |
|
|
registered with libev, there is no efficient way to see that this is, in |
1497 |
|
|
fact, a different file descriptor. |
1498 |
|
|
|
1499 |
|
|
To avoid having to explicitly tell libev about such cases, libev follows |
1500 |
|
|
the following policy: Each time C<ev_io_set> is being called, libev |
1501 |
|
|
will assume that this is potentially a new file descriptor, otherwise |
1502 |
|
|
it is assumed that the file descriptor stays the same. That means that |
1503 |
|
|
you I<have> to call C<ev_io_set> (or C<ev_io_init>) when you change the |
1504 |
|
|
descriptor even if the file descriptor number itself did not change. |
1505 |
|
|
|
1506 |
|
|
This is how one would do it normally anyway, the important point is that |
1507 |
|
|
the libev application should not optimise around libev but should leave |
1508 |
|
|
optimisations to libev. |
1509 |
|
|
|
1510 |
root |
1.95 |
=head3 The special problem of dup'ed file descriptors |
1511 |
root |
1.94 |
|
1512 |
|
|
Some backends (e.g. epoll), cannot register events for file descriptors, |
1513 |
root |
1.103 |
but only events for the underlying file descriptions. That means when you |
1514 |
root |
1.109 |
have C<dup ()>'ed file descriptors or weirder constellations, and register |
1515 |
|
|
events for them, only one file descriptor might actually receive events. |
1516 |
root |
1.94 |
|
1517 |
root |
1.103 |
There is no workaround possible except not registering events |
1518 |
|
|
for potentially C<dup ()>'ed file descriptors, or to resort to |
1519 |
root |
1.94 |
C<EVBACKEND_SELECT> or C<EVBACKEND_POLL>. |
1520 |
|
|
|
1521 |
|
|
=head3 The special problem of fork |
1522 |
|
|
|
1523 |
|
|
Some backends (epoll, kqueue) do not support C<fork ()> at all or exhibit |
1524 |
|
|
useless behaviour. Libev fully supports fork, but needs to be told about |
1525 |
|
|
it in the child. |
1526 |
|
|
|
1527 |
|
|
To support fork in your programs, you either have to call |
1528 |
|
|
C<ev_default_fork ()> or C<ev_loop_fork ()> after a fork in the child, |
1529 |
|
|
enable C<EVFLAG_FORKCHECK>, or resort to C<EVBACKEND_SELECT> or |
1530 |
|
|
C<EVBACKEND_POLL>. |
1531 |
|
|
|
1532 |
root |
1.138 |
=head3 The special problem of SIGPIPE |
1533 |
|
|
|
1534 |
root |
1.183 |
While not really specific to libev, it is easy to forget about C<SIGPIPE>: |
1535 |
root |
1.174 |
when writing to a pipe whose other end has been closed, your program gets |
1536 |
root |
1.183 |
sent a SIGPIPE, which, by default, aborts your program. For most programs |
1537 |
root |
1.174 |
this is sensible behaviour, for daemons, this is usually undesirable. |
1538 |
root |
1.138 |
|
1539 |
|
|
So when you encounter spurious, unexplained daemon exits, make sure you |
1540 |
|
|
ignore SIGPIPE (and maybe make sure you log the exit status of your daemon |
1541 |
|
|
somewhere, as that would have given you a big clue). |
1542 |
|
|
|
1543 |
root |
1.81 |
|
1544 |
root |
1.82 |
=head3 Watcher-Specific Functions |
1545 |
|
|
|
1546 |
root |
1.1 |
=over 4 |
1547 |
|
|
|
1548 |
|
|
=item ev_io_init (ev_io *, callback, int fd, int events) |
1549 |
|
|
|
1550 |
|
|
=item ev_io_set (ev_io *, int fd, int events) |
1551 |
|
|
|
1552 |
root |
1.42 |
Configures an C<ev_io> watcher. The C<fd> is the file descriptor to |
1553 |
root |
1.183 |
receive events for and C<events> is either C<EV_READ>, C<EV_WRITE> or |
1554 |
|
|
C<EV_READ | EV_WRITE>, to express the desire to receive the given events. |
1555 |
root |
1.32 |
|
1556 |
root |
1.48 |
=item int fd [read-only] |
1557 |
|
|
|
1558 |
|
|
The file descriptor being watched. |
1559 |
|
|
|
1560 |
|
|
=item int events [read-only] |
1561 |
|
|
|
1562 |
|
|
The events being watched. |
1563 |
|
|
|
1564 |
root |
1.1 |
=back |
1565 |
|
|
|
1566 |
root |
1.111 |
=head3 Examples |
1567 |
|
|
|
1568 |
root |
1.54 |
Example: Call C<stdin_readable_cb> when STDIN_FILENO has become, well |
1569 |
root |
1.34 |
readable, but only once. Since it is likely line-buffered, you could |
1570 |
root |
1.54 |
attempt to read a whole line in the callback. |
1571 |
root |
1.34 |
|
1572 |
root |
1.164 |
static void |
1573 |
root |
1.198 |
stdin_readable_cb (struct ev_loop *loop, ev_io *w, int revents) |
1574 |
root |
1.164 |
{ |
1575 |
|
|
ev_io_stop (loop, w); |
1576 |
root |
1.183 |
.. read from stdin here (or from w->fd) and handle any I/O errors |
1577 |
root |
1.164 |
} |
1578 |
|
|
|
1579 |
|
|
... |
1580 |
|
|
struct ev_loop *loop = ev_default_init (0); |
1581 |
root |
1.198 |
ev_io stdin_readable; |
1582 |
root |
1.164 |
ev_io_init (&stdin_readable, stdin_readable_cb, STDIN_FILENO, EV_READ); |
1583 |
|
|
ev_io_start (loop, &stdin_readable); |
1584 |
|
|
ev_loop (loop, 0); |
1585 |
root |
1.34 |
|
1586 |
|
|
|
1587 |
root |
1.42 |
=head2 C<ev_timer> - relative and optionally repeating timeouts |
1588 |
root |
1.1 |
|
1589 |
|
|
Timer watchers are simple relative timers that generate an event after a |
1590 |
|
|
given time, and optionally repeating in regular intervals after that. |
1591 |
|
|
|
1592 |
|
|
The timers are based on real time, that is, if you register an event that |
1593 |
root |
1.161 |
times out after an hour and you reset your system clock to January last |
1594 |
root |
1.183 |
year, it will still time out after (roughly) one hour. "Roughly" because |
1595 |
root |
1.28 |
detecting time jumps is hard, and some inaccuracies are unavoidable (the |
1596 |
root |
1.1 |
monotonic clock option helps a lot here). |
1597 |
|
|
|
1598 |
root |
1.183 |
The callback is guaranteed to be invoked only I<after> its timeout has |
1599 |
root |
1.240 |
passed (not I<at>, so on systems with very low-resolution clocks this |
1600 |
|
|
might introduce a small delay). If multiple timers become ready during the |
1601 |
|
|
same loop iteration then the ones with earlier time-out values are invoked |
1602 |
root |
1.248 |
before ones of the same priority with later time-out values (but this is |
1603 |
|
|
no longer true when a callback calls C<ev_loop> recursively). |
1604 |
root |
1.175 |
|
1605 |
root |
1.198 |
=head3 Be smart about timeouts |
1606 |
|
|
|
1607 |
root |
1.199 |
Many real-world problems involve some kind of timeout, usually for error |
1608 |
root |
1.198 |
recovery. A typical example is an HTTP request - if the other side hangs, |
1609 |
|
|
you want to raise some error after a while. |
1610 |
|
|
|
1611 |
root |
1.199 |
What follows are some ways to handle this problem, from obvious and |
1612 |
|
|
inefficient to smart and efficient. |
1613 |
root |
1.198 |
|
1614 |
root |
1.199 |
In the following, a 60 second activity timeout is assumed - a timeout that |
1615 |
|
|
gets reset to 60 seconds each time there is activity (e.g. each time some |
1616 |
|
|
data or other life sign was received). |
1617 |
root |
1.198 |
|
1618 |
|
|
=over 4 |
1619 |
|
|
|
1620 |
root |
1.199 |
=item 1. Use a timer and stop, reinitialise and start it on activity. |
1621 |
root |
1.198 |
|
1622 |
|
|
This is the most obvious, but not the most simple way: In the beginning, |
1623 |
|
|
start the watcher: |
1624 |
|
|
|
1625 |
|
|
ev_timer_init (timer, callback, 60., 0.); |
1626 |
|
|
ev_timer_start (loop, timer); |
1627 |
|
|
|
1628 |
root |
1.199 |
Then, each time there is some activity, C<ev_timer_stop> it, initialise it |
1629 |
|
|
and start it again: |
1630 |
root |
1.198 |
|
1631 |
|
|
ev_timer_stop (loop, timer); |
1632 |
|
|
ev_timer_set (timer, 60., 0.); |
1633 |
|
|
ev_timer_start (loop, timer); |
1634 |
|
|
|
1635 |
root |
1.199 |
This is relatively simple to implement, but means that each time there is |
1636 |
|
|
some activity, libev will first have to remove the timer from its internal |
1637 |
|
|
data structure and then add it again. Libev tries to be fast, but it's |
1638 |
|
|
still not a constant-time operation. |
1639 |
root |
1.198 |
|
1640 |
|
|
=item 2. Use a timer and re-start it with C<ev_timer_again> inactivity. |
1641 |
|
|
|
1642 |
|
|
This is the easiest way, and involves using C<ev_timer_again> instead of |
1643 |
|
|
C<ev_timer_start>. |
1644 |
|
|
|
1645 |
root |
1.199 |
To implement this, configure an C<ev_timer> with a C<repeat> value |
1646 |
|
|
of C<60> and then call C<ev_timer_again> at start and each time you |
1647 |
|
|
successfully read or write some data. If you go into an idle state where |
1648 |
|
|
you do not expect data to travel on the socket, you can C<ev_timer_stop> |
1649 |
|
|
the timer, and C<ev_timer_again> will automatically restart it if need be. |
1650 |
|
|
|
1651 |
|
|
That means you can ignore both the C<ev_timer_start> function and the |
1652 |
|
|
C<after> argument to C<ev_timer_set>, and only ever use the C<repeat> |
1653 |
|
|
member and C<ev_timer_again>. |
1654 |
root |
1.198 |
|
1655 |
|
|
At start: |
1656 |
|
|
|
1657 |
root |
1.243 |
ev_init (timer, callback); |
1658 |
root |
1.199 |
timer->repeat = 60.; |
1659 |
root |
1.198 |
ev_timer_again (loop, timer); |
1660 |
|
|
|
1661 |
root |
1.199 |
Each time there is some activity: |
1662 |
root |
1.198 |
|
1663 |
|
|
ev_timer_again (loop, timer); |
1664 |
|
|
|
1665 |
root |
1.199 |
It is even possible to change the time-out on the fly, regardless of |
1666 |
|
|
whether the watcher is active or not: |
1667 |
root |
1.198 |
|
1668 |
|
|
timer->repeat = 30.; |
1669 |
|
|
ev_timer_again (loop, timer); |
1670 |
|
|
|
1671 |
|
|
This is slightly more efficient then stopping/starting the timer each time |
1672 |
|
|
you want to modify its timeout value, as libev does not have to completely |
1673 |
root |
1.199 |
remove and re-insert the timer from/into its internal data structure. |
1674 |
|
|
|
1675 |
|
|
It is, however, even simpler than the "obvious" way to do it. |
1676 |
root |
1.198 |
|
1677 |
|
|
=item 3. Let the timer time out, but then re-arm it as required. |
1678 |
|
|
|
1679 |
|
|
This method is more tricky, but usually most efficient: Most timeouts are |
1680 |
root |
1.199 |
relatively long compared to the intervals between other activity - in |
1681 |
|
|
our example, within 60 seconds, there are usually many I/O events with |
1682 |
|
|
associated activity resets. |
1683 |
root |
1.198 |
|
1684 |
|
|
In this case, it would be more efficient to leave the C<ev_timer> alone, |
1685 |
|
|
but remember the time of last activity, and check for a real timeout only |
1686 |
|
|
within the callback: |
1687 |
|
|
|
1688 |
|
|
ev_tstamp last_activity; // time of last activity |
1689 |
|
|
|
1690 |
|
|
static void |
1691 |
|
|
callback (EV_P_ ev_timer *w, int revents) |
1692 |
|
|
{ |
1693 |
root |
1.199 |
ev_tstamp now = ev_now (EV_A); |
1694 |
root |
1.198 |
ev_tstamp timeout = last_activity + 60.; |
1695 |
|
|
|
1696 |
root |
1.199 |
// if last_activity + 60. is older than now, we did time out |
1697 |
root |
1.198 |
if (timeout < now) |
1698 |
|
|
{ |
1699 |
|
|
// timeout occured, take action |
1700 |
|
|
} |
1701 |
|
|
else |
1702 |
|
|
{ |
1703 |
|
|
// callback was invoked, but there was some activity, re-arm |
1704 |
root |
1.199 |
// the watcher to fire in last_activity + 60, which is |
1705 |
|
|
// guaranteed to be in the future, so "again" is positive: |
1706 |
root |
1.216 |
w->repeat = timeout - now; |
1707 |
root |
1.198 |
ev_timer_again (EV_A_ w); |
1708 |
|
|
} |
1709 |
|
|
} |
1710 |
|
|
|
1711 |
root |
1.199 |
To summarise the callback: first calculate the real timeout (defined |
1712 |
|
|
as "60 seconds after the last activity"), then check if that time has |
1713 |
|
|
been reached, which means something I<did>, in fact, time out. Otherwise |
1714 |
|
|
the callback was invoked too early (C<timeout> is in the future), so |
1715 |
|
|
re-schedule the timer to fire at that future time, to see if maybe we have |
1716 |
|
|
a timeout then. |
1717 |
root |
1.198 |
|
1718 |
|
|
Note how C<ev_timer_again> is used, taking advantage of the |
1719 |
|
|
C<ev_timer_again> optimisation when the timer is already running. |
1720 |
|
|
|
1721 |
root |
1.199 |
This scheme causes more callback invocations (about one every 60 seconds |
1722 |
|
|
minus half the average time between activity), but virtually no calls to |
1723 |
|
|
libev to change the timeout. |
1724 |
|
|
|
1725 |
|
|
To start the timer, simply initialise the watcher and set C<last_activity> |
1726 |
|
|
to the current time (meaning we just have some activity :), then call the |
1727 |
|
|
callback, which will "do the right thing" and start the timer: |
1728 |
root |
1.198 |
|
1729 |
root |
1.243 |
ev_init (timer, callback); |
1730 |
root |
1.198 |
last_activity = ev_now (loop); |
1731 |
|
|
callback (loop, timer, EV_TIMEOUT); |
1732 |
|
|
|
1733 |
root |
1.199 |
And when there is some activity, simply store the current time in |
1734 |
|
|
C<last_activity>, no libev calls at all: |
1735 |
root |
1.198 |
|
1736 |
|
|
last_actiivty = ev_now (loop); |
1737 |
|
|
|
1738 |
|
|
This technique is slightly more complex, but in most cases where the |
1739 |
|
|
time-out is unlikely to be triggered, much more efficient. |
1740 |
|
|
|
1741 |
root |
1.199 |
Changing the timeout is trivial as well (if it isn't hard-coded in the |
1742 |
|
|
callback :) - just change the timeout and invoke the callback, which will |
1743 |
|
|
fix things for you. |
1744 |
|
|
|
1745 |
root |
1.200 |
=item 4. Wee, just use a double-linked list for your timeouts. |
1746 |
root |
1.199 |
|
1747 |
root |
1.200 |
If there is not one request, but many thousands (millions...), all |
1748 |
|
|
employing some kind of timeout with the same timeout value, then one can |
1749 |
|
|
do even better: |
1750 |
root |
1.199 |
|
1751 |
|
|
When starting the timeout, calculate the timeout value and put the timeout |
1752 |
|
|
at the I<end> of the list. |
1753 |
|
|
|
1754 |
|
|
Then use an C<ev_timer> to fire when the timeout at the I<beginning> of |
1755 |
|
|
the list is expected to fire (for example, using the technique #3). |
1756 |
|
|
|
1757 |
|
|
When there is some activity, remove the timer from the list, recalculate |
1758 |
|
|
the timeout, append it to the end of the list again, and make sure to |
1759 |
|
|
update the C<ev_timer> if it was taken from the beginning of the list. |
1760 |
|
|
|
1761 |
|
|
This way, one can manage an unlimited number of timeouts in O(1) time for |
1762 |
|
|
starting, stopping and updating the timers, at the expense of a major |
1763 |
|
|
complication, and having to use a constant timeout. The constant timeout |
1764 |
|
|
ensures that the list stays sorted. |
1765 |
|
|
|
1766 |
root |
1.198 |
=back |
1767 |
|
|
|
1768 |
root |
1.200 |
So which method the best? |
1769 |
root |
1.199 |
|
1770 |
root |
1.200 |
Method #2 is a simple no-brain-required solution that is adequate in most |
1771 |
|
|
situations. Method #3 requires a bit more thinking, but handles many cases |
1772 |
|
|
better, and isn't very complicated either. In most case, choosing either |
1773 |
|
|
one is fine, with #3 being better in typical situations. |
1774 |
root |
1.199 |
|
1775 |
|
|
Method #1 is almost always a bad idea, and buys you nothing. Method #4 is |
1776 |
|
|
rather complicated, but extremely efficient, something that really pays |
1777 |
root |
1.200 |
off after the first million or so of active timers, i.e. it's usually |
1778 |
root |
1.199 |
overkill :) |
1779 |
|
|
|
1780 |
root |
1.175 |
=head3 The special problem of time updates |
1781 |
|
|
|
1782 |
root |
1.176 |
Establishing the current time is a costly operation (it usually takes at |
1783 |
|
|
least two system calls): EV therefore updates its idea of the current |
1784 |
root |
1.183 |
time only before and after C<ev_loop> collects new events, which causes a |
1785 |
|
|
growing difference between C<ev_now ()> and C<ev_time ()> when handling |
1786 |
|
|
lots of events in one iteration. |
1787 |
root |
1.175 |
|
1788 |
root |
1.9 |
The relative timeouts are calculated relative to the C<ev_now ()> |
1789 |
|
|
time. This is usually the right thing as this timestamp refers to the time |
1790 |
root |
1.28 |
of the event triggering whatever timeout you are modifying/starting. If |
1791 |
root |
1.175 |
you suspect event processing to be delayed and you I<need> to base the |
1792 |
|
|
timeout on the current time, use something like this to adjust for this: |
1793 |
root |
1.9 |
|
1794 |
|
|
ev_timer_set (&timer, after + ev_now () - ev_time (), 0.); |
1795 |
|
|
|
1796 |
root |
1.177 |
If the event loop is suspended for a long time, you can also force an |
1797 |
root |
1.176 |
update of the time returned by C<ev_now ()> by calling C<ev_now_update |
1798 |
|
|
()>. |
1799 |
|
|
|
1800 |
root |
1.257 |
=head3 The special problems of suspended animation |
1801 |
|
|
|
1802 |
|
|
When you leave the server world it is quite customary to hit machines that |
1803 |
|
|
can suspend/hibernate - what happens to the clocks during such a suspend? |
1804 |
|
|
|
1805 |
|
|
Some quick tests made with a Linux 2.6.28 indicate that a suspend freezes |
1806 |
|
|
all processes, while the clocks (C<times>, C<CLOCK_MONOTONIC>) continue |
1807 |
|
|
to run until the system is suspended, but they will not advance while the |
1808 |
|
|
system is suspended. That means, on resume, it will be as if the program |
1809 |
|
|
was frozen for a few seconds, but the suspend time will not be counted |
1810 |
|
|
towards C<ev_timer> when a monotonic clock source is used. The real time |
1811 |
|
|
clock advanced as expected, but if it is used as sole clocksource, then a |
1812 |
|
|
long suspend would be detected as a time jump by libev, and timers would |
1813 |
|
|
be adjusted accordingly. |
1814 |
|
|
|
1815 |
|
|
I would not be surprised to see different behaviour in different between |
1816 |
|
|
operating systems, OS versions or even different hardware. |
1817 |
|
|
|
1818 |
|
|
The other form of suspend (job control, or sending a SIGSTOP) will see a |
1819 |
|
|
time jump in the monotonic clocks and the realtime clock. If the program |
1820 |
|
|
is suspended for a very long time, and monotonic clock sources are in use, |
1821 |
|
|
then you can expect C<ev_timer>s to expire as the full suspension time |
1822 |
|
|
will be counted towards the timers. When no monotonic clock source is in |
1823 |
|
|
use, then libev will again assume a timejump and adjust accordingly. |
1824 |
|
|
|
1825 |
|
|
It might be beneficial for this latter case to call C<ev_suspend> |
1826 |
|
|
and C<ev_resume> in code that handles C<SIGTSTP>, to at least get |
1827 |
|
|
deterministic behaviour in this case (you can do nothing against |
1828 |
|
|
C<SIGSTOP>). |
1829 |
|
|
|
1830 |
root |
1.82 |
=head3 Watcher-Specific Functions and Data Members |
1831 |
|
|
|
1832 |
root |
1.1 |
=over 4 |
1833 |
|
|
|
1834 |
|
|
=item ev_timer_init (ev_timer *, callback, ev_tstamp after, ev_tstamp repeat) |
1835 |
|
|
|
1836 |
|
|
=item ev_timer_set (ev_timer *, ev_tstamp after, ev_tstamp repeat) |
1837 |
|
|
|
1838 |
root |
1.157 |
Configure the timer to trigger after C<after> seconds. If C<repeat> |
1839 |
|
|
is C<0.>, then it will automatically be stopped once the timeout is |
1840 |
|
|
reached. If it is positive, then the timer will automatically be |
1841 |
|
|
configured to trigger again C<repeat> seconds later, again, and again, |
1842 |
|
|
until stopped manually. |
1843 |
|
|
|
1844 |
|
|
The timer itself will do a best-effort at avoiding drift, that is, if |
1845 |
|
|
you configure a timer to trigger every 10 seconds, then it will normally |
1846 |
|
|
trigger at exactly 10 second intervals. If, however, your program cannot |
1847 |
|
|
keep up with the timer (because it takes longer than those 10 seconds to |
1848 |
|
|
do stuff) the timer will not fire more than once per event loop iteration. |
1849 |
root |
1.1 |
|
1850 |
root |
1.132 |
=item ev_timer_again (loop, ev_timer *) |
1851 |
root |
1.1 |
|
1852 |
|
|
This will act as if the timer timed out and restart it again if it is |
1853 |
|
|
repeating. The exact semantics are: |
1854 |
|
|
|
1855 |
root |
1.61 |
If the timer is pending, its pending status is cleared. |
1856 |
root |
1.1 |
|
1857 |
root |
1.161 |
If the timer is started but non-repeating, stop it (as if it timed out). |
1858 |
root |
1.61 |
|
1859 |
|
|
If the timer is repeating, either start it if necessary (with the |
1860 |
|
|
C<repeat> value), or reset the running timer to the C<repeat> value. |
1861 |
root |
1.1 |
|
1862 |
root |
1.232 |
This sounds a bit complicated, see L<Be smart about timeouts>, above, for a |
1863 |
root |
1.198 |
usage example. |
1864 |
root |
1.183 |
|
1865 |
root |
1.275 |
=item ev_tstamp ev_timer_remaining (loop, ev_timer *) |
1866 |
root |
1.258 |
|
1867 |
|
|
Returns the remaining time until a timer fires. If the timer is active, |
1868 |
|
|
then this time is relative to the current event loop time, otherwise it's |
1869 |
|
|
the timeout value currently configured. |
1870 |
|
|
|
1871 |
|
|
That is, after an C<ev_timer_set (w, 5, 7)>, C<ev_timer_remaining> returns |
1872 |
|
|
C<5>. When the timer is started and one second passes, C<ev_timer_remain> |
1873 |
|
|
will return C<4>. When the timer expires and is restarted, it will return |
1874 |
|
|
roughly C<7> (likely slightly less as callback invocation takes some time, |
1875 |
|
|
too), and so on. |
1876 |
|
|
|
1877 |
root |
1.48 |
=item ev_tstamp repeat [read-write] |
1878 |
|
|
|
1879 |
|
|
The current C<repeat> value. Will be used each time the watcher times out |
1880 |
root |
1.183 |
or C<ev_timer_again> is called, and determines the next timeout (if any), |
1881 |
root |
1.48 |
which is also when any modifications are taken into account. |
1882 |
root |
1.1 |
|
1883 |
|
|
=back |
1884 |
|
|
|
1885 |
root |
1.111 |
=head3 Examples |
1886 |
|
|
|
1887 |
root |
1.54 |
Example: Create a timer that fires after 60 seconds. |
1888 |
root |
1.34 |
|
1889 |
root |
1.164 |
static void |
1890 |
root |
1.198 |
one_minute_cb (struct ev_loop *loop, ev_timer *w, int revents) |
1891 |
root |
1.164 |
{ |
1892 |
|
|
.. one minute over, w is actually stopped right here |
1893 |
|
|
} |
1894 |
|
|
|
1895 |
root |
1.198 |
ev_timer mytimer; |
1896 |
root |
1.164 |
ev_timer_init (&mytimer, one_minute_cb, 60., 0.); |
1897 |
|
|
ev_timer_start (loop, &mytimer); |
1898 |
root |
1.34 |
|
1899 |
root |
1.54 |
Example: Create a timeout timer that times out after 10 seconds of |
1900 |
root |
1.34 |
inactivity. |
1901 |
|
|
|
1902 |
root |
1.164 |
static void |
1903 |
root |
1.198 |
timeout_cb (struct ev_loop *loop, ev_timer *w, int revents) |
1904 |
root |
1.164 |
{ |
1905 |
|
|
.. ten seconds without any activity |
1906 |
|
|
} |
1907 |
|
|
|
1908 |
root |
1.198 |
ev_timer mytimer; |
1909 |
root |
1.164 |
ev_timer_init (&mytimer, timeout_cb, 0., 10.); /* note, only repeat used */ |
1910 |
|
|
ev_timer_again (&mytimer); /* start timer */ |
1911 |
|
|
ev_loop (loop, 0); |
1912 |
|
|
|
1913 |
|
|
// and in some piece of code that gets executed on any "activity": |
1914 |
|
|
// reset the timeout to start ticking again at 10 seconds |
1915 |
|
|
ev_timer_again (&mytimer); |
1916 |
root |
1.34 |
|
1917 |
|
|
|
1918 |
root |
1.42 |
=head2 C<ev_periodic> - to cron or not to cron? |
1919 |
root |
1.1 |
|
1920 |
|
|
Periodic watchers are also timers of a kind, but they are very versatile |
1921 |
|
|
(and unfortunately a bit complex). |
1922 |
|
|
|
1923 |
root |
1.227 |
Unlike C<ev_timer>, periodic watchers are not based on real time (or |
1924 |
|
|
relative time, the physical time that passes) but on wall clock time |
1925 |
|
|
(absolute time, the thing you can read on your calender or clock). The |
1926 |
|
|
difference is that wall clock time can run faster or slower than real |
1927 |
|
|
time, and time jumps are not uncommon (e.g. when you adjust your |
1928 |
|
|
wrist-watch). |
1929 |
|
|
|
1930 |
|
|
You can tell a periodic watcher to trigger after some specific point |
1931 |
|
|
in time: for example, if you tell a periodic watcher to trigger "in 10 |
1932 |
|
|
seconds" (by specifying e.g. C<ev_now () + 10.>, that is, an absolute time |
1933 |
|
|
not a delay) and then reset your system clock to January of the previous |
1934 |
|
|
year, then it will take a year or more to trigger the event (unlike an |
1935 |
|
|
C<ev_timer>, which would still trigger roughly 10 seconds after starting |
1936 |
|
|
it, as it uses a relative timeout). |
1937 |
|
|
|
1938 |
|
|
C<ev_periodic> watchers can also be used to implement vastly more complex |
1939 |
|
|
timers, such as triggering an event on each "midnight, local time", or |
1940 |
|
|
other complicated rules. This cannot be done with C<ev_timer> watchers, as |
1941 |
|
|
those cannot react to time jumps. |
1942 |
root |
1.1 |
|
1943 |
root |
1.161 |
As with timers, the callback is guaranteed to be invoked only when the |
1944 |
root |
1.230 |
point in time where it is supposed to trigger has passed. If multiple |
1945 |
|
|
timers become ready during the same loop iteration then the ones with |
1946 |
|
|
earlier time-out values are invoked before ones with later time-out values |
1947 |
|
|
(but this is no longer true when a callback calls C<ev_loop> recursively). |
1948 |
root |
1.28 |
|
1949 |
root |
1.82 |
=head3 Watcher-Specific Functions and Data Members |
1950 |
|
|
|
1951 |
root |
1.1 |
=over 4 |
1952 |
|
|
|
1953 |
root |
1.227 |
=item ev_periodic_init (ev_periodic *, callback, ev_tstamp offset, ev_tstamp interval, reschedule_cb) |
1954 |
root |
1.1 |
|
1955 |
root |
1.227 |
=item ev_periodic_set (ev_periodic *, ev_tstamp offset, ev_tstamp interval, reschedule_cb) |
1956 |
root |
1.1 |
|
1957 |
root |
1.227 |
Lots of arguments, let's sort it out... There are basically three modes of |
1958 |
root |
1.183 |
operation, and we will explain them from simplest to most complex: |
1959 |
root |
1.1 |
|
1960 |
|
|
=over 4 |
1961 |
|
|
|
1962 |
root |
1.227 |
=item * absolute timer (offset = absolute time, interval = 0, reschedule_cb = 0) |
1963 |
root |
1.1 |
|
1964 |
root |
1.161 |
In this configuration the watcher triggers an event after the wall clock |
1965 |
root |
1.227 |
time C<offset> has passed. It will not repeat and will not adjust when a |
1966 |
|
|
time jump occurs, that is, if it is to be run at January 1st 2011 then it |
1967 |
|
|
will be stopped and invoked when the system clock reaches or surpasses |
1968 |
|
|
this point in time. |
1969 |
root |
1.1 |
|
1970 |
root |
1.227 |
=item * repeating interval timer (offset = offset within interval, interval > 0, reschedule_cb = 0) |
1971 |
root |
1.1 |
|
1972 |
|
|
In this mode the watcher will always be scheduled to time out at the next |
1973 |
root |
1.227 |
C<offset + N * interval> time (for some integer N, which can also be |
1974 |
|
|
negative) and then repeat, regardless of any time jumps. The C<offset> |
1975 |
|
|
argument is merely an offset into the C<interval> periods. |
1976 |
root |
1.1 |
|
1977 |
root |
1.183 |
This can be used to create timers that do not drift with respect to the |
1978 |
root |
1.227 |
system clock, for example, here is an C<ev_periodic> that triggers each |
1979 |
|
|
hour, on the hour (with respect to UTC): |
1980 |
root |
1.1 |
|
1981 |
|
|
ev_periodic_set (&periodic, 0., 3600., 0); |
1982 |
|
|
|
1983 |
|
|
This doesn't mean there will always be 3600 seconds in between triggers, |
1984 |
root |
1.161 |
but only that the callback will be called when the system time shows a |
1985 |
root |
1.12 |
full hour (UTC), or more correctly, when the system time is evenly divisible |
1986 |
root |
1.1 |
by 3600. |
1987 |
|
|
|
1988 |
|
|
Another way to think about it (for the mathematically inclined) is that |
1989 |
root |
1.10 |
C<ev_periodic> will try to run the callback in this mode at the next possible |
1990 |
root |
1.227 |
time where C<time = offset (mod interval)>, regardless of any time jumps. |
1991 |
root |
1.1 |
|
1992 |
root |
1.227 |
For numerical stability it is preferable that the C<offset> value is near |
1993 |
root |
1.78 |
C<ev_now ()> (the current time), but there is no range requirement for |
1994 |
root |
1.157 |
this value, and in fact is often specified as zero. |
1995 |
root |
1.78 |
|
1996 |
root |
1.161 |
Note also that there is an upper limit to how often a timer can fire (CPU |
1997 |
root |
1.158 |
speed for example), so if C<interval> is very small then timing stability |
1998 |
root |
1.161 |
will of course deteriorate. Libev itself tries to be exact to be about one |
1999 |
root |
1.158 |
millisecond (if the OS supports it and the machine is fast enough). |
2000 |
|
|
|
2001 |
root |
1.227 |
=item * manual reschedule mode (offset ignored, interval ignored, reschedule_cb = callback) |
2002 |
root |
1.1 |
|
2003 |
root |
1.227 |
In this mode the values for C<interval> and C<offset> are both being |
2004 |
root |
1.1 |
ignored. Instead, each time the periodic watcher gets scheduled, the |
2005 |
|
|
reschedule callback will be called with the watcher as first, and the |
2006 |
|
|
current time as second argument. |
2007 |
|
|
|
2008 |
root |
1.227 |
NOTE: I<This callback MUST NOT stop or destroy any periodic watcher, ever, |
2009 |
|
|
or make ANY other event loop modifications whatsoever, unless explicitly |
2010 |
|
|
allowed by documentation here>. |
2011 |
root |
1.1 |
|
2012 |
root |
1.157 |
If you need to stop it, return C<now + 1e30> (or so, fudge fudge) and stop |
2013 |
|
|
it afterwards (e.g. by starting an C<ev_prepare> watcher, which is the |
2014 |
|
|
only event loop modification you are allowed to do). |
2015 |
|
|
|
2016 |
root |
1.198 |
The callback prototype is C<ev_tstamp (*reschedule_cb)(ev_periodic |
2017 |
root |
1.157 |
*w, ev_tstamp now)>, e.g.: |
2018 |
root |
1.1 |
|
2019 |
root |
1.198 |
static ev_tstamp |
2020 |
|
|
my_rescheduler (ev_periodic *w, ev_tstamp now) |
2021 |
root |
1.1 |
{ |
2022 |
|
|
return now + 60.; |
2023 |
|
|
} |
2024 |
|
|
|
2025 |
|
|
It must return the next time to trigger, based on the passed time value |
2026 |
|
|
(that is, the lowest time value larger than to the second argument). It |
2027 |
|
|
will usually be called just before the callback will be triggered, but |
2028 |
|
|
might be called at other times, too. |
2029 |
|
|
|
2030 |
root |
1.157 |
NOTE: I<< This callback must always return a time that is higher than or |
2031 |
|
|
equal to the passed C<now> value >>. |
2032 |
root |
1.18 |
|
2033 |
root |
1.1 |
This can be used to create very complex timers, such as a timer that |
2034 |
root |
1.157 |
triggers on "next midnight, local time". To do this, you would calculate the |
2035 |
root |
1.19 |
next midnight after C<now> and return the timestamp value for this. How |
2036 |
|
|
you do this is, again, up to you (but it is not trivial, which is the main |
2037 |
|
|
reason I omitted it as an example). |
2038 |
root |
1.1 |
|
2039 |
|
|
=back |
2040 |
|
|
|
2041 |
|
|
=item ev_periodic_again (loop, ev_periodic *) |
2042 |
|
|
|
2043 |
|
|
Simply stops and restarts the periodic watcher again. This is only useful |
2044 |
|
|
when you changed some parameters or the reschedule callback would return |
2045 |
|
|
a different time than the last time it was called (e.g. in a crond like |
2046 |
|
|
program when the crontabs have changed). |
2047 |
|
|
|
2048 |
root |
1.149 |
=item ev_tstamp ev_periodic_at (ev_periodic *) |
2049 |
|
|
|
2050 |
root |
1.227 |
When active, returns the absolute time that the watcher is supposed |
2051 |
|
|
to trigger next. This is not the same as the C<offset> argument to |
2052 |
|
|
C<ev_periodic_set>, but indeed works even in interval and manual |
2053 |
|
|
rescheduling modes. |
2054 |
root |
1.149 |
|
2055 |
root |
1.78 |
=item ev_tstamp offset [read-write] |
2056 |
|
|
|
2057 |
|
|
When repeating, this contains the offset value, otherwise this is the |
2058 |
root |
1.227 |
absolute point in time (the C<offset> value passed to C<ev_periodic_set>, |
2059 |
|
|
although libev might modify this value for better numerical stability). |
2060 |
root |
1.78 |
|
2061 |
|
|
Can be modified any time, but changes only take effect when the periodic |
2062 |
|
|
timer fires or C<ev_periodic_again> is being called. |
2063 |
|
|
|
2064 |
root |
1.48 |
=item ev_tstamp interval [read-write] |
2065 |
|
|
|
2066 |
|
|
The current interval value. Can be modified any time, but changes only |
2067 |
|
|
take effect when the periodic timer fires or C<ev_periodic_again> is being |
2068 |
|
|
called. |
2069 |
|
|
|
2070 |
root |
1.198 |
=item ev_tstamp (*reschedule_cb)(ev_periodic *w, ev_tstamp now) [read-write] |
2071 |
root |
1.48 |
|
2072 |
|
|
The current reschedule callback, or C<0>, if this functionality is |
2073 |
|
|
switched off. Can be changed any time, but changes only take effect when |
2074 |
|
|
the periodic timer fires or C<ev_periodic_again> is being called. |
2075 |
|
|
|
2076 |
root |
1.1 |
=back |
2077 |
|
|
|
2078 |
root |
1.111 |
=head3 Examples |
2079 |
|
|
|
2080 |
root |
1.54 |
Example: Call a callback every hour, or, more precisely, whenever the |
2081 |
root |
1.183 |
system time is divisible by 3600. The callback invocation times have |
2082 |
root |
1.161 |
potentially a lot of jitter, but good long-term stability. |
2083 |
root |
1.34 |
|
2084 |
root |
1.164 |
static void |
2085 |
root |
1.198 |
clock_cb (struct ev_loop *loop, ev_io *w, int revents) |
2086 |
root |
1.164 |
{ |
2087 |
|
|
... its now a full hour (UTC, or TAI or whatever your clock follows) |
2088 |
|
|
} |
2089 |
|
|
|
2090 |
root |
1.198 |
ev_periodic hourly_tick; |
2091 |
root |
1.164 |
ev_periodic_init (&hourly_tick, clock_cb, 0., 3600., 0); |
2092 |
|
|
ev_periodic_start (loop, &hourly_tick); |
2093 |
root |
1.34 |
|
2094 |
root |
1.54 |
Example: The same as above, but use a reschedule callback to do it: |
2095 |
root |
1.34 |
|
2096 |
root |
1.164 |
#include <math.h> |
2097 |
root |
1.34 |
|
2098 |
root |
1.164 |
static ev_tstamp |
2099 |
root |
1.198 |
my_scheduler_cb (ev_periodic *w, ev_tstamp now) |
2100 |
root |
1.164 |
{ |
2101 |
root |
1.183 |
return now + (3600. - fmod (now, 3600.)); |
2102 |
root |
1.164 |
} |
2103 |
root |
1.34 |
|
2104 |
root |
1.164 |
ev_periodic_init (&hourly_tick, clock_cb, 0., 0., my_scheduler_cb); |
2105 |
root |
1.34 |
|
2106 |
root |
1.54 |
Example: Call a callback every hour, starting now: |
2107 |
root |
1.34 |
|
2108 |
root |
1.198 |
ev_periodic hourly_tick; |
2109 |
root |
1.164 |
ev_periodic_init (&hourly_tick, clock_cb, |
2110 |
|
|
fmod (ev_now (loop), 3600.), 3600., 0); |
2111 |
|
|
ev_periodic_start (loop, &hourly_tick); |
2112 |
root |
1.34 |
|
2113 |
|
|
|
2114 |
root |
1.42 |
=head2 C<ev_signal> - signal me when a signal gets signalled! |
2115 |
root |
1.1 |
|
2116 |
|
|
Signal watchers will trigger an event when the process receives a specific |
2117 |
|
|
signal one or more times. Even though signals are very asynchronous, libev |
2118 |
root |
1.9 |
will try it's best to deliver signals synchronously, i.e. as part of the |
2119 |
root |
1.1 |
normal event processing, like any other event. |
2120 |
|
|
|
2121 |
root |
1.260 |
If you want signals to be delivered truly asynchronously, just use |
2122 |
|
|
C<sigaction> as you would do without libev and forget about sharing |
2123 |
|
|
the signal. You can even use C<ev_async> from a signal handler to |
2124 |
|
|
synchronously wake up an event loop. |
2125 |
|
|
|
2126 |
|
|
You can configure as many watchers as you like for the same signal, but |
2127 |
|
|
only within the same loop, i.e. you can watch for C<SIGINT> in your |
2128 |
|
|
default loop and for C<SIGIO> in another loop, but you cannot watch for |
2129 |
|
|
C<SIGINT> in both the default loop and another loop at the same time. At |
2130 |
|
|
the moment, C<SIGCHLD> is permanently tied to the default loop. |
2131 |
|
|
|
2132 |
|
|
When the first watcher gets started will libev actually register something |
2133 |
|
|
with the kernel (thus it coexists with your own signal handlers as long as |
2134 |
|
|
you don't register any with libev for the same signal). |
2135 |
root |
1.259 |
|
2136 |
root |
1.135 |
If possible and supported, libev will install its handlers with |
2137 |
root |
1.259 |
C<SA_RESTART> (or equivalent) behaviour enabled, so system calls should |
2138 |
|
|
not be unduly interrupted. If you have a problem with system calls getting |
2139 |
|
|
interrupted by signals you can block all signals in an C<ev_check> watcher |
2140 |
|
|
and unblock them in an C<ev_prepare> watcher. |
2141 |
root |
1.135 |
|
2142 |
root |
1.277 |
=head3 The special problem of inheritance over fork/execve/pthread_create |
2143 |
root |
1.265 |
|
2144 |
|
|
Both the signal mask (C<sigprocmask>) and the signal disposition |
2145 |
|
|
(C<sigaction>) are unspecified after starting a signal watcher (and after |
2146 |
|
|
stopping it again), that is, libev might or might not block the signal, |
2147 |
|
|
and might or might not set or restore the installed signal handler. |
2148 |
|
|
|
2149 |
|
|
While this does not matter for the signal disposition (libev never |
2150 |
|
|
sets signals to C<SIG_IGN>, so handlers will be reset to C<SIG_DFL> on |
2151 |
|
|
C<execve>), this matters for the signal mask: many programs do not expect |
2152 |
root |
1.266 |
certain signals to be blocked. |
2153 |
root |
1.265 |
|
2154 |
|
|
This means that before calling C<exec> (from the child) you should reset |
2155 |
|
|
the signal mask to whatever "default" you expect (all clear is a good |
2156 |
|
|
choice usually). |
2157 |
|
|
|
2158 |
root |
1.267 |
The simplest way to ensure that the signal mask is reset in the child is |
2159 |
|
|
to install a fork handler with C<pthread_atfork> that resets it. That will |
2160 |
|
|
catch fork calls done by libraries (such as the libc) as well. |
2161 |
|
|
|
2162 |
root |
1.277 |
In current versions of libev, the signal will not be blocked indefinitely |
2163 |
|
|
unless you use the C<signalfd> API (C<EV_SIGNALFD>). While this reduces |
2164 |
|
|
the window of opportunity for problems, it will not go away, as libev |
2165 |
|
|
I<has> to modify the signal mask, at least temporarily. |
2166 |
|
|
|
2167 |
root |
1.278 |
So I can't stress this enough: I<If you do not reset your signal mask when |
2168 |
|
|
you expect it to be empty, you have a race condition in your code>. This |
2169 |
|
|
is not a libev-specific thing, this is true for most event libraries. |
2170 |
root |
1.266 |
|
2171 |
root |
1.82 |
=head3 Watcher-Specific Functions and Data Members |
2172 |
|
|
|
2173 |
root |
1.1 |
=over 4 |
2174 |
|
|
|
2175 |
|
|
=item ev_signal_init (ev_signal *, callback, int signum) |
2176 |
|
|
|
2177 |
|
|
=item ev_signal_set (ev_signal *, int signum) |
2178 |
|
|
|
2179 |
|
|
Configures the watcher to trigger on the given signal number (usually one |
2180 |
|
|
of the C<SIGxxx> constants). |
2181 |
|
|
|
2182 |
root |
1.48 |
=item int signum [read-only] |
2183 |
|
|
|
2184 |
|
|
The signal the watcher watches out for. |
2185 |
|
|
|
2186 |
root |
1.1 |
=back |
2187 |
|
|
|
2188 |
root |
1.132 |
=head3 Examples |
2189 |
|
|
|
2190 |
root |
1.188 |
Example: Try to exit cleanly on SIGINT. |
2191 |
root |
1.132 |
|
2192 |
root |
1.164 |
static void |
2193 |
root |
1.198 |
sigint_cb (struct ev_loop *loop, ev_signal *w, int revents) |
2194 |
root |
1.164 |
{ |
2195 |
|
|
ev_unloop (loop, EVUNLOOP_ALL); |
2196 |
|
|
} |
2197 |
|
|
|
2198 |
root |
1.198 |
ev_signal signal_watcher; |
2199 |
root |
1.164 |
ev_signal_init (&signal_watcher, sigint_cb, SIGINT); |
2200 |
root |
1.188 |
ev_signal_start (loop, &signal_watcher); |
2201 |
root |
1.132 |
|
2202 |
root |
1.35 |
|
2203 |
root |
1.42 |
=head2 C<ev_child> - watch out for process status changes |
2204 |
root |
1.1 |
|
2205 |
|
|
Child watchers trigger when your process receives a SIGCHLD in response to |
2206 |
root |
1.183 |
some child status changes (most typically when a child of yours dies or |
2207 |
|
|
exits). It is permissible to install a child watcher I<after> the child |
2208 |
|
|
has been forked (which implies it might have already exited), as long |
2209 |
|
|
as the event loop isn't entered (or is continued from a watcher), i.e., |
2210 |
|
|
forking and then immediately registering a watcher for the child is fine, |
2211 |
root |
1.244 |
but forking and registering a watcher a few event loop iterations later or |
2212 |
|
|
in the next callback invocation is not. |
2213 |
root |
1.134 |
|
2214 |
|
|
Only the default event loop is capable of handling signals, and therefore |
2215 |
root |
1.161 |
you can only register child watchers in the default event loop. |
2216 |
root |
1.134 |
|
2217 |
root |
1.248 |
Due to some design glitches inside libev, child watchers will always be |
2218 |
root |
1.249 |
handled at maximum priority (their priority is set to C<EV_MAXPRI> by |
2219 |
|
|
libev) |
2220 |
root |
1.248 |
|
2221 |
root |
1.134 |
=head3 Process Interaction |
2222 |
|
|
|
2223 |
|
|
Libev grabs C<SIGCHLD> as soon as the default event loop is |
2224 |
root |
1.259 |
initialised. This is necessary to guarantee proper behaviour even if the |
2225 |
|
|
first child watcher is started after the child exits. The occurrence |
2226 |
root |
1.134 |
of C<SIGCHLD> is recorded asynchronously, but child reaping is done |
2227 |
|
|
synchronously as part of the event loop processing. Libev always reaps all |
2228 |
|
|
children, even ones not watched. |
2229 |
|
|
|
2230 |
|
|
=head3 Overriding the Built-In Processing |
2231 |
|
|
|
2232 |
|
|
Libev offers no special support for overriding the built-in child |
2233 |
|
|
processing, but if your application collides with libev's default child |
2234 |
|
|
handler, you can override it easily by installing your own handler for |
2235 |
|
|
C<SIGCHLD> after initialising the default loop, and making sure the |
2236 |
|
|
default loop never gets destroyed. You are encouraged, however, to use an |
2237 |
|
|
event-based approach to child reaping and thus use libev's support for |
2238 |
|
|
that, so other libev users can use C<ev_child> watchers freely. |
2239 |
root |
1.1 |
|
2240 |
root |
1.173 |
=head3 Stopping the Child Watcher |
2241 |
|
|
|
2242 |
|
|
Currently, the child watcher never gets stopped, even when the |
2243 |
|
|
child terminates, so normally one needs to stop the watcher in the |
2244 |
|
|
callback. Future versions of libev might stop the watcher automatically |
2245 |
root |
1.259 |
when a child exit is detected (calling C<ev_child_stop> twice is not a |
2246 |
|
|
problem). |
2247 |
root |
1.173 |
|
2248 |
root |
1.82 |
=head3 Watcher-Specific Functions and Data Members |
2249 |
|
|
|
2250 |
root |
1.1 |
=over 4 |
2251 |
|
|
|
2252 |
root |
1.120 |
=item ev_child_init (ev_child *, callback, int pid, int trace) |
2253 |
root |
1.1 |
|
2254 |
root |
1.120 |
=item ev_child_set (ev_child *, int pid, int trace) |
2255 |
root |
1.1 |
|
2256 |
|
|
Configures the watcher to wait for status changes of process C<pid> (or |
2257 |
|
|
I<any> process if C<pid> is specified as C<0>). The callback can look |
2258 |
|
|
at the C<rstatus> member of the C<ev_child> watcher structure to see |
2259 |
root |
1.14 |
the status word (use the macros from C<sys/wait.h> and see your systems |
2260 |
|
|
C<waitpid> documentation). The C<rpid> member contains the pid of the |
2261 |
root |
1.120 |
process causing the status change. C<trace> must be either C<0> (only |
2262 |
|
|
activate the watcher when the process terminates) or C<1> (additionally |
2263 |
|
|
activate the watcher when the process is stopped or continued). |
2264 |
root |
1.1 |
|
2265 |
root |
1.48 |
=item int pid [read-only] |
2266 |
|
|
|
2267 |
|
|
The process id this watcher watches out for, or C<0>, meaning any process id. |
2268 |
|
|
|
2269 |
|
|
=item int rpid [read-write] |
2270 |
|
|
|
2271 |
|
|
The process id that detected a status change. |
2272 |
|
|
|
2273 |
|
|
=item int rstatus [read-write] |
2274 |
|
|
|
2275 |
|
|
The process exit/trace status caused by C<rpid> (see your systems |
2276 |
|
|
C<waitpid> and C<sys/wait.h> documentation for details). |
2277 |
|
|
|
2278 |
root |
1.1 |
=back |
2279 |
|
|
|
2280 |
root |
1.134 |
=head3 Examples |
2281 |
|
|
|
2282 |
|
|
Example: C<fork()> a new process and install a child handler to wait for |
2283 |
|
|
its completion. |
2284 |
|
|
|
2285 |
root |
1.164 |
ev_child cw; |
2286 |
|
|
|
2287 |
|
|
static void |
2288 |
root |
1.198 |
child_cb (EV_P_ ev_child *w, int revents) |
2289 |
root |
1.164 |
{ |
2290 |
|
|
ev_child_stop (EV_A_ w); |
2291 |
|
|
printf ("process %d exited with status %x\n", w->rpid, w->rstatus); |
2292 |
|
|
} |
2293 |
|
|
|
2294 |
|
|
pid_t pid = fork (); |
2295 |
root |
1.134 |
|
2296 |
root |
1.164 |
if (pid < 0) |
2297 |
|
|
// error |
2298 |
|
|
else if (pid == 0) |
2299 |
|
|
{ |
2300 |
|
|
// the forked child executes here |
2301 |
|
|
exit (1); |
2302 |
|
|
} |
2303 |
|
|
else |
2304 |
|
|
{ |
2305 |
|
|
ev_child_init (&cw, child_cb, pid, 0); |
2306 |
|
|
ev_child_start (EV_DEFAULT_ &cw); |
2307 |
|
|
} |
2308 |
root |
1.134 |
|
2309 |
root |
1.34 |
|
2310 |
root |
1.48 |
=head2 C<ev_stat> - did the file attributes just change? |
2311 |
|
|
|
2312 |
root |
1.161 |
This watches a file system path for attribute changes. That is, it calls |
2313 |
root |
1.207 |
C<stat> on that path in regular intervals (or when the OS says it changed) |
2314 |
|
|
and sees if it changed compared to the last time, invoking the callback if |
2315 |
|
|
it did. |
2316 |
root |
1.48 |
|
2317 |
|
|
The path does not need to exist: changing from "path exists" to "path does |
2318 |
root |
1.211 |
not exist" is a status change like any other. The condition "path does not |
2319 |
|
|
exist" (or more correctly "path cannot be stat'ed") is signified by the |
2320 |
|
|
C<st_nlink> field being zero (which is otherwise always forced to be at |
2321 |
|
|
least one) and all the other fields of the stat buffer having unspecified |
2322 |
|
|
contents. |
2323 |
root |
1.48 |
|
2324 |
root |
1.207 |
The path I<must not> end in a slash or contain special components such as |
2325 |
|
|
C<.> or C<..>. The path I<should> be absolute: If it is relative and |
2326 |
|
|
your working directory changes, then the behaviour is undefined. |
2327 |
|
|
|
2328 |
|
|
Since there is no portable change notification interface available, the |
2329 |
|
|
portable implementation simply calls C<stat(2)> regularly on the path |
2330 |
|
|
to see if it changed somehow. You can specify a recommended polling |
2331 |
|
|
interval for this case. If you specify a polling interval of C<0> (highly |
2332 |
|
|
recommended!) then a I<suitable, unspecified default> value will be used |
2333 |
|
|
(which you can expect to be around five seconds, although this might |
2334 |
|
|
change dynamically). Libev will also impose a minimum interval which is |
2335 |
root |
1.208 |
currently around C<0.1>, but that's usually overkill. |
2336 |
root |
1.48 |
|
2337 |
|
|
This watcher type is not meant for massive numbers of stat watchers, |
2338 |
|
|
as even with OS-supported change notifications, this can be |
2339 |
|
|
resource-intensive. |
2340 |
|
|
|
2341 |
root |
1.183 |
At the time of this writing, the only OS-specific interface implemented |
2342 |
root |
1.211 |
is the Linux inotify interface (implementing kqueue support is left as an |
2343 |
|
|
exercise for the reader. Note, however, that the author sees no way of |
2344 |
|
|
implementing C<ev_stat> semantics with kqueue, except as a hint). |
2345 |
root |
1.48 |
|
2346 |
root |
1.137 |
=head3 ABI Issues (Largefile Support) |
2347 |
|
|
|
2348 |
|
|
Libev by default (unless the user overrides this) uses the default |
2349 |
root |
1.169 |
compilation environment, which means that on systems with large file |
2350 |
|
|
support disabled by default, you get the 32 bit version of the stat |
2351 |
root |
1.137 |
structure. When using the library from programs that change the ABI to |
2352 |
|
|
use 64 bit file offsets the programs will fail. In that case you have to |
2353 |
|
|
compile libev with the same flags to get binary compatibility. This is |
2354 |
|
|
obviously the case with any flags that change the ABI, but the problem is |
2355 |
root |
1.207 |
most noticeably displayed with ev_stat and large file support. |
2356 |
root |
1.169 |
|
2357 |
|
|
The solution for this is to lobby your distribution maker to make large |
2358 |
|
|
file interfaces available by default (as e.g. FreeBSD does) and not |
2359 |
|
|
optional. Libev cannot simply switch on large file support because it has |
2360 |
|
|
to exchange stat structures with application programs compiled using the |
2361 |
|
|
default compilation environment. |
2362 |
root |
1.137 |
|
2363 |
root |
1.183 |
=head3 Inotify and Kqueue |
2364 |
root |
1.108 |
|
2365 |
root |
1.211 |
When C<inotify (7)> support has been compiled into libev and present at |
2366 |
|
|
runtime, it will be used to speed up change detection where possible. The |
2367 |
|
|
inotify descriptor will be created lazily when the first C<ev_stat> |
2368 |
|
|
watcher is being started. |
2369 |
root |
1.108 |
|
2370 |
root |
1.147 |
Inotify presence does not change the semantics of C<ev_stat> watchers |
2371 |
root |
1.108 |
except that changes might be detected earlier, and in some cases, to avoid |
2372 |
root |
1.147 |
making regular C<stat> calls. Even in the presence of inotify support |
2373 |
root |
1.183 |
there are many cases where libev has to resort to regular C<stat> polling, |
2374 |
root |
1.211 |
but as long as kernel 2.6.25 or newer is used (2.6.24 and older have too |
2375 |
|
|
many bugs), the path exists (i.e. stat succeeds), and the path resides on |
2376 |
|
|
a local filesystem (libev currently assumes only ext2/3, jfs, reiserfs and |
2377 |
|
|
xfs are fully working) libev usually gets away without polling. |
2378 |
root |
1.108 |
|
2379 |
root |
1.183 |
There is no support for kqueue, as apparently it cannot be used to |
2380 |
root |
1.108 |
implement this functionality, due to the requirement of having a file |
2381 |
root |
1.183 |
descriptor open on the object at all times, and detecting renames, unlinks |
2382 |
|
|
etc. is difficult. |
2383 |
root |
1.108 |
|
2384 |
root |
1.212 |
=head3 C<stat ()> is a synchronous operation |
2385 |
|
|
|
2386 |
|
|
Libev doesn't normally do any kind of I/O itself, and so is not blocking |
2387 |
|
|
the process. The exception are C<ev_stat> watchers - those call C<stat |
2388 |
|
|
()>, which is a synchronous operation. |
2389 |
|
|
|
2390 |
|
|
For local paths, this usually doesn't matter: unless the system is very |
2391 |
|
|
busy or the intervals between stat's are large, a stat call will be fast, |
2392 |
root |
1.222 |
as the path data is usually in memory already (except when starting the |
2393 |
root |
1.212 |
watcher). |
2394 |
|
|
|
2395 |
|
|
For networked file systems, calling C<stat ()> can block an indefinite |
2396 |
|
|
time due to network issues, and even under good conditions, a stat call |
2397 |
|
|
often takes multiple milliseconds. |
2398 |
|
|
|
2399 |
|
|
Therefore, it is best to avoid using C<ev_stat> watchers on networked |
2400 |
|
|
paths, although this is fully supported by libev. |
2401 |
|
|
|
2402 |
root |
1.107 |
=head3 The special problem of stat time resolution |
2403 |
|
|
|
2404 |
root |
1.207 |
The C<stat ()> system call only supports full-second resolution portably, |
2405 |
|
|
and even on systems where the resolution is higher, most file systems |
2406 |
|
|
still only support whole seconds. |
2407 |
root |
1.107 |
|
2408 |
root |
1.150 |
That means that, if the time is the only thing that changes, you can |
2409 |
|
|
easily miss updates: on the first update, C<ev_stat> detects a change and |
2410 |
|
|
calls your callback, which does something. When there is another update |
2411 |
root |
1.183 |
within the same second, C<ev_stat> will be unable to detect unless the |
2412 |
|
|
stat data does change in other ways (e.g. file size). |
2413 |
root |
1.150 |
|
2414 |
|
|
The solution to this is to delay acting on a change for slightly more |
2415 |
root |
1.155 |
than a second (or till slightly after the next full second boundary), using |
2416 |
root |
1.150 |
a roughly one-second-delay C<ev_timer> (e.g. C<ev_timer_set (w, 0., 1.02); |
2417 |
|
|
ev_timer_again (loop, w)>). |
2418 |
|
|
|
2419 |
|
|
The C<.02> offset is added to work around small timing inconsistencies |
2420 |
|
|
of some operating systems (where the second counter of the current time |
2421 |
|
|
might be be delayed. One such system is the Linux kernel, where a call to |
2422 |
|
|
C<gettimeofday> might return a timestamp with a full second later than |
2423 |
|
|
a subsequent C<time> call - if the equivalent of C<time ()> is used to |
2424 |
|
|
update file times then there will be a small window where the kernel uses |
2425 |
|
|
the previous second to update file times but libev might already execute |
2426 |
|
|
the timer callback). |
2427 |
root |
1.107 |
|
2428 |
root |
1.82 |
=head3 Watcher-Specific Functions and Data Members |
2429 |
|
|
|
2430 |
root |
1.48 |
=over 4 |
2431 |
|
|
|
2432 |
|
|
=item ev_stat_init (ev_stat *, callback, const char *path, ev_tstamp interval) |
2433 |
|
|
|
2434 |
|
|
=item ev_stat_set (ev_stat *, const char *path, ev_tstamp interval) |
2435 |
|
|
|
2436 |
|
|
Configures the watcher to wait for status changes of the given |
2437 |
|
|
C<path>. The C<interval> is a hint on how quickly a change is expected to |
2438 |
|
|
be detected and should normally be specified as C<0> to let libev choose |
2439 |
|
|
a suitable value. The memory pointed to by C<path> must point to the same |
2440 |
|
|
path for as long as the watcher is active. |
2441 |
|
|
|
2442 |
root |
1.183 |
The callback will receive an C<EV_STAT> event when a change was detected, |
2443 |
|
|
relative to the attributes at the time the watcher was started (or the |
2444 |
|
|
last change was detected). |
2445 |
root |
1.48 |
|
2446 |
root |
1.132 |
=item ev_stat_stat (loop, ev_stat *) |
2447 |
root |
1.48 |
|
2448 |
|
|
Updates the stat buffer immediately with new values. If you change the |
2449 |
root |
1.150 |
watched path in your callback, you could call this function to avoid |
2450 |
|
|
detecting this change (while introducing a race condition if you are not |
2451 |
|
|
the only one changing the path). Can also be useful simply to find out the |
2452 |
|
|
new values. |
2453 |
root |
1.48 |
|
2454 |
|
|
=item ev_statdata attr [read-only] |
2455 |
|
|
|
2456 |
root |
1.150 |
The most-recently detected attributes of the file. Although the type is |
2457 |
root |
1.48 |
C<ev_statdata>, this is usually the (or one of the) C<struct stat> types |
2458 |
root |
1.150 |
suitable for your system, but you can only rely on the POSIX-standardised |
2459 |
|
|
members to be present. If the C<st_nlink> member is C<0>, then there was |
2460 |
|
|
some error while C<stat>ing the file. |
2461 |
root |
1.48 |
|
2462 |
|
|
=item ev_statdata prev [read-only] |
2463 |
|
|
|
2464 |
|
|
The previous attributes of the file. The callback gets invoked whenever |
2465 |
root |
1.150 |
C<prev> != C<attr>, or, more precisely, one or more of these members |
2466 |
|
|
differ: C<st_dev>, C<st_ino>, C<st_mode>, C<st_nlink>, C<st_uid>, |
2467 |
|
|
C<st_gid>, C<st_rdev>, C<st_size>, C<st_atime>, C<st_mtime>, C<st_ctime>. |
2468 |
root |
1.48 |
|
2469 |
|
|
=item ev_tstamp interval [read-only] |
2470 |
|
|
|
2471 |
|
|
The specified interval. |
2472 |
|
|
|
2473 |
|
|
=item const char *path [read-only] |
2474 |
|
|
|
2475 |
root |
1.161 |
The file system path that is being watched. |
2476 |
root |
1.48 |
|
2477 |
|
|
=back |
2478 |
|
|
|
2479 |
root |
1.108 |
=head3 Examples |
2480 |
|
|
|
2481 |
root |
1.48 |
Example: Watch C</etc/passwd> for attribute changes. |
2482 |
|
|
|
2483 |
root |
1.164 |
static void |
2484 |
|
|
passwd_cb (struct ev_loop *loop, ev_stat *w, int revents) |
2485 |
|
|
{ |
2486 |
|
|
/* /etc/passwd changed in some way */ |
2487 |
|
|
if (w->attr.st_nlink) |
2488 |
|
|
{ |
2489 |
|
|
printf ("passwd current size %ld\n", (long)w->attr.st_size); |
2490 |
|
|
printf ("passwd current atime %ld\n", (long)w->attr.st_mtime); |
2491 |
|
|
printf ("passwd current mtime %ld\n", (long)w->attr.st_mtime); |
2492 |
|
|
} |
2493 |
|
|
else |
2494 |
|
|
/* you shalt not abuse printf for puts */ |
2495 |
|
|
puts ("wow, /etc/passwd is not there, expect problems. " |
2496 |
|
|
"if this is windows, they already arrived\n"); |
2497 |
|
|
} |
2498 |
root |
1.48 |
|
2499 |
root |
1.164 |
... |
2500 |
|
|
ev_stat passwd; |
2501 |
root |
1.48 |
|
2502 |
root |
1.164 |
ev_stat_init (&passwd, passwd_cb, "/etc/passwd", 0.); |
2503 |
|
|
ev_stat_start (loop, &passwd); |
2504 |
root |
1.107 |
|
2505 |
|
|
Example: Like above, but additionally use a one-second delay so we do not |
2506 |
|
|
miss updates (however, frequent updates will delay processing, too, so |
2507 |
|
|
one might do the work both on C<ev_stat> callback invocation I<and> on |
2508 |
|
|
C<ev_timer> callback invocation). |
2509 |
|
|
|
2510 |
root |
1.164 |
static ev_stat passwd; |
2511 |
|
|
static ev_timer timer; |
2512 |
root |
1.107 |
|
2513 |
root |
1.164 |
static void |
2514 |
|
|
timer_cb (EV_P_ ev_timer *w, int revents) |
2515 |
|
|
{ |
2516 |
|
|
ev_timer_stop (EV_A_ w); |
2517 |
|
|
|
2518 |
|
|
/* now it's one second after the most recent passwd change */ |
2519 |
|
|
} |
2520 |
|
|
|
2521 |
|
|
static void |
2522 |
|
|
stat_cb (EV_P_ ev_stat *w, int revents) |
2523 |
|
|
{ |
2524 |
|
|
/* reset the one-second timer */ |
2525 |
|
|
ev_timer_again (EV_A_ &timer); |
2526 |
|
|
} |
2527 |
|
|
|
2528 |
|
|
... |
2529 |
|
|
ev_stat_init (&passwd, stat_cb, "/etc/passwd", 0.); |
2530 |
|
|
ev_stat_start (loop, &passwd); |
2531 |
|
|
ev_timer_init (&timer, timer_cb, 0., 1.02); |
2532 |
root |
1.48 |
|
2533 |
|
|
|
2534 |
root |
1.42 |
=head2 C<ev_idle> - when you've got nothing better to do... |
2535 |
root |
1.1 |
|
2536 |
root |
1.67 |
Idle watchers trigger events when no other events of the same or higher |
2537 |
root |
1.183 |
priority are pending (prepare, check and other idle watchers do not count |
2538 |
|
|
as receiving "events"). |
2539 |
root |
1.67 |
|
2540 |
|
|
That is, as long as your process is busy handling sockets or timeouts |
2541 |
|
|
(or even signals, imagine) of the same or higher priority it will not be |
2542 |
|
|
triggered. But when your process is idle (or only lower-priority watchers |
2543 |
|
|
are pending), the idle watchers are being called once per event loop |
2544 |
|
|
iteration - until stopped, that is, or your process receives more events |
2545 |
|
|
and becomes busy again with higher priority stuff. |
2546 |
root |
1.1 |
|
2547 |
|
|
The most noteworthy effect is that as long as any idle watchers are |
2548 |
|
|
active, the process will not block when waiting for new events. |
2549 |
|
|
|
2550 |
|
|
Apart from keeping your process non-blocking (which is a useful |
2551 |
|
|
effect on its own sometimes), idle watchers are a good place to do |
2552 |
|
|
"pseudo-background processing", or delay processing stuff to after the |
2553 |
|
|
event loop has handled all outstanding events. |
2554 |
|
|
|
2555 |
root |
1.82 |
=head3 Watcher-Specific Functions and Data Members |
2556 |
|
|
|
2557 |
root |
1.1 |
=over 4 |
2558 |
|
|
|
2559 |
root |
1.226 |
=item ev_idle_init (ev_idle *, callback) |
2560 |
root |
1.1 |
|
2561 |
|
|
Initialises and configures the idle watcher - it has no parameters of any |
2562 |
|
|
kind. There is a C<ev_idle_set> macro, but using it is utterly pointless, |
2563 |
|
|
believe me. |
2564 |
|
|
|
2565 |
|
|
=back |
2566 |
|
|
|
2567 |
root |
1.111 |
=head3 Examples |
2568 |
|
|
|
2569 |
root |
1.54 |
Example: Dynamically allocate an C<ev_idle> watcher, start it, and in the |
2570 |
|
|
callback, free it. Also, use no error checking, as usual. |
2571 |
root |
1.34 |
|
2572 |
root |
1.164 |
static void |
2573 |
root |
1.198 |
idle_cb (struct ev_loop *loop, ev_idle *w, int revents) |
2574 |
root |
1.164 |
{ |
2575 |
|
|
free (w); |
2576 |
|
|
// now do something you wanted to do when the program has |
2577 |
|
|
// no longer anything immediate to do. |
2578 |
|
|
} |
2579 |
|
|
|
2580 |
root |
1.198 |
ev_idle *idle_watcher = malloc (sizeof (ev_idle)); |
2581 |
root |
1.164 |
ev_idle_init (idle_watcher, idle_cb); |
2582 |
root |
1.242 |
ev_idle_start (loop, idle_watcher); |
2583 |
root |
1.34 |
|
2584 |
|
|
|
2585 |
root |
1.42 |
=head2 C<ev_prepare> and C<ev_check> - customise your event loop! |
2586 |
root |
1.1 |
|
2587 |
root |
1.183 |
Prepare and check watchers are usually (but not always) used in pairs: |
2588 |
root |
1.20 |
prepare watchers get invoked before the process blocks and check watchers |
2589 |
root |
1.14 |
afterwards. |
2590 |
root |
1.1 |
|
2591 |
root |
1.45 |
You I<must not> call C<ev_loop> or similar functions that enter |
2592 |
|
|
the current event loop from either C<ev_prepare> or C<ev_check> |
2593 |
|
|
watchers. Other loops than the current one are fine, however. The |
2594 |
|
|
rationale behind this is that you do not need to check for recursion in |
2595 |
|
|
those watchers, i.e. the sequence will always be C<ev_prepare>, blocking, |
2596 |
|
|
C<ev_check> so if you have one watcher of each kind they will always be |
2597 |
|
|
called in pairs bracketing the blocking call. |
2598 |
|
|
|
2599 |
root |
1.35 |
Their main purpose is to integrate other event mechanisms into libev and |
2600 |
root |
1.183 |
their use is somewhat advanced. They could be used, for example, to track |
2601 |
root |
1.35 |
variable changes, implement your own watchers, integrate net-snmp or a |
2602 |
root |
1.45 |
coroutine library and lots more. They are also occasionally useful if |
2603 |
|
|
you cache some data and want to flush it before blocking (for example, |
2604 |
|
|
in X programs you might want to do an C<XFlush ()> in an C<ev_prepare> |
2605 |
|
|
watcher). |
2606 |
root |
1.1 |
|
2607 |
root |
1.183 |
This is done by examining in each prepare call which file descriptors |
2608 |
|
|
need to be watched by the other library, registering C<ev_io> watchers |
2609 |
|
|
for them and starting an C<ev_timer> watcher for any timeouts (many |
2610 |
|
|
libraries provide exactly this functionality). Then, in the check watcher, |
2611 |
|
|
you check for any events that occurred (by checking the pending status |
2612 |
|
|
of all watchers and stopping them) and call back into the library. The |
2613 |
|
|
I/O and timer callbacks will never actually be called (but must be valid |
2614 |
|
|
nevertheless, because you never know, you know?). |
2615 |
root |
1.1 |
|
2616 |
root |
1.14 |
As another example, the Perl Coro module uses these hooks to integrate |
2617 |
root |
1.1 |
coroutines into libev programs, by yielding to other active coroutines |
2618 |
|
|
during each prepare and only letting the process block if no coroutines |
2619 |
root |
1.20 |
are ready to run (it's actually more complicated: it only runs coroutines |
2620 |
|
|
with priority higher than or equal to the event loop and one coroutine |
2621 |
|
|
of lower priority, but only once, using idle watchers to keep the event |
2622 |
|
|
loop from blocking if lower-priority coroutines are active, thus mapping |
2623 |
|
|
low-priority coroutines to idle/background tasks). |
2624 |
root |
1.1 |
|
2625 |
root |
1.77 |
It is recommended to give C<ev_check> watchers highest (C<EV_MAXPRI>) |
2626 |
|
|
priority, to ensure that they are being run before any other watchers |
2627 |
root |
1.183 |
after the poll (this doesn't matter for C<ev_prepare> watchers). |
2628 |
|
|
|
2629 |
|
|
Also, C<ev_check> watchers (and C<ev_prepare> watchers, too) should not |
2630 |
|
|
activate ("feed") events into libev. While libev fully supports this, they |
2631 |
|
|
might get executed before other C<ev_check> watchers did their job. As |
2632 |
|
|
C<ev_check> watchers are often used to embed other (non-libev) event |
2633 |
|
|
loops those other event loops might be in an unusable state until their |
2634 |
|
|
C<ev_check> watcher ran (always remind yourself to coexist peacefully with |
2635 |
|
|
others). |
2636 |
root |
1.77 |
|
2637 |
root |
1.82 |
=head3 Watcher-Specific Functions and Data Members |
2638 |
|
|
|
2639 |
root |
1.1 |
=over 4 |
2640 |
|
|
|
2641 |
|
|
=item ev_prepare_init (ev_prepare *, callback) |
2642 |
|
|
|
2643 |
|
|
=item ev_check_init (ev_check *, callback) |
2644 |
|
|
|
2645 |
|
|
Initialises and configures the prepare or check watcher - they have no |
2646 |
|
|
parameters of any kind. There are C<ev_prepare_set> and C<ev_check_set> |
2647 |
root |
1.183 |
macros, but using them is utterly, utterly, utterly and completely |
2648 |
|
|
pointless. |
2649 |
root |
1.1 |
|
2650 |
|
|
=back |
2651 |
|
|
|
2652 |
root |
1.111 |
=head3 Examples |
2653 |
|
|
|
2654 |
root |
1.76 |
There are a number of principal ways to embed other event loops or modules |
2655 |
|
|
into libev. Here are some ideas on how to include libadns into libev |
2656 |
|
|
(there is a Perl module named C<EV::ADNS> that does this, which you could |
2657 |
root |
1.150 |
use as a working example. Another Perl module named C<EV::Glib> embeds a |
2658 |
|
|
Glib main context into libev, and finally, C<Glib::EV> embeds EV into the |
2659 |
|
|
Glib event loop). |
2660 |
root |
1.76 |
|
2661 |
|
|
Method 1: Add IO watchers and a timeout watcher in a prepare handler, |
2662 |
|
|
and in a check watcher, destroy them and call into libadns. What follows |
2663 |
|
|
is pseudo-code only of course. This requires you to either use a low |
2664 |
|
|
priority for the check watcher or use C<ev_clear_pending> explicitly, as |
2665 |
|
|
the callbacks for the IO/timeout watchers might not have been called yet. |
2666 |
root |
1.45 |
|
2667 |
root |
1.164 |
static ev_io iow [nfd]; |
2668 |
|
|
static ev_timer tw; |
2669 |
root |
1.45 |
|
2670 |
root |
1.164 |
static void |
2671 |
root |
1.198 |
io_cb (struct ev_loop *loop, ev_io *w, int revents) |
2672 |
root |
1.164 |
{ |
2673 |
|
|
} |
2674 |
root |
1.45 |
|
2675 |
root |
1.164 |
// create io watchers for each fd and a timer before blocking |
2676 |
|
|
static void |
2677 |
root |
1.198 |
adns_prepare_cb (struct ev_loop *loop, ev_prepare *w, int revents) |
2678 |
root |
1.164 |
{ |
2679 |
|
|
int timeout = 3600000; |
2680 |
|
|
struct pollfd fds [nfd]; |
2681 |
|
|
// actual code will need to loop here and realloc etc. |
2682 |
|
|
adns_beforepoll (ads, fds, &nfd, &timeout, timeval_from (ev_time ())); |
2683 |
|
|
|
2684 |
|
|
/* the callback is illegal, but won't be called as we stop during check */ |
2685 |
root |
1.243 |
ev_timer_init (&tw, 0, timeout * 1e-3, 0.); |
2686 |
root |
1.164 |
ev_timer_start (loop, &tw); |
2687 |
|
|
|
2688 |
|
|
// create one ev_io per pollfd |
2689 |
|
|
for (int i = 0; i < nfd; ++i) |
2690 |
|
|
{ |
2691 |
|
|
ev_io_init (iow + i, io_cb, fds [i].fd, |
2692 |
|
|
((fds [i].events & POLLIN ? EV_READ : 0) |
2693 |
|
|
| (fds [i].events & POLLOUT ? EV_WRITE : 0))); |
2694 |
|
|
|
2695 |
|
|
fds [i].revents = 0; |
2696 |
|
|
ev_io_start (loop, iow + i); |
2697 |
|
|
} |
2698 |
|
|
} |
2699 |
|
|
|
2700 |
|
|
// stop all watchers after blocking |
2701 |
|
|
static void |
2702 |
root |
1.198 |
adns_check_cb (struct ev_loop *loop, ev_check *w, int revents) |
2703 |
root |
1.164 |
{ |
2704 |
|
|
ev_timer_stop (loop, &tw); |
2705 |
|
|
|
2706 |
|
|
for (int i = 0; i < nfd; ++i) |
2707 |
|
|
{ |
2708 |
|
|
// set the relevant poll flags |
2709 |
|
|
// could also call adns_processreadable etc. here |
2710 |
|
|
struct pollfd *fd = fds + i; |
2711 |
|
|
int revents = ev_clear_pending (iow + i); |
2712 |
|
|
if (revents & EV_READ ) fd->revents |= fd->events & POLLIN; |
2713 |
|
|
if (revents & EV_WRITE) fd->revents |= fd->events & POLLOUT; |
2714 |
|
|
|
2715 |
|
|
// now stop the watcher |
2716 |
|
|
ev_io_stop (loop, iow + i); |
2717 |
|
|
} |
2718 |
|
|
|
2719 |
|
|
adns_afterpoll (adns, fds, nfd, timeval_from (ev_now (loop)); |
2720 |
|
|
} |
2721 |
root |
1.34 |
|
2722 |
root |
1.76 |
Method 2: This would be just like method 1, but you run C<adns_afterpoll> |
2723 |
|
|
in the prepare watcher and would dispose of the check watcher. |
2724 |
|
|
|
2725 |
|
|
Method 3: If the module to be embedded supports explicit event |
2726 |
root |
1.161 |
notification (libadns does), you can also make use of the actual watcher |
2727 |
root |
1.76 |
callbacks, and only destroy/create the watchers in the prepare watcher. |
2728 |
|
|
|
2729 |
root |
1.164 |
static void |
2730 |
|
|
timer_cb (EV_P_ ev_timer *w, int revents) |
2731 |
|
|
{ |
2732 |
|
|
adns_state ads = (adns_state)w->data; |
2733 |
|
|
update_now (EV_A); |
2734 |
|
|
|
2735 |
|
|
adns_processtimeouts (ads, &tv_now); |
2736 |
|
|
} |
2737 |
|
|
|
2738 |
|
|
static void |
2739 |
|
|
io_cb (EV_P_ ev_io *w, int revents) |
2740 |
|
|
{ |
2741 |
|
|
adns_state ads = (adns_state)w->data; |
2742 |
|
|
update_now (EV_A); |
2743 |
|
|
|
2744 |
|
|
if (revents & EV_READ ) adns_processreadable (ads, w->fd, &tv_now); |
2745 |
|
|
if (revents & EV_WRITE) adns_processwriteable (ads, w->fd, &tv_now); |
2746 |
|
|
} |
2747 |
root |
1.76 |
|
2748 |
root |
1.164 |
// do not ever call adns_afterpoll |
2749 |
root |
1.76 |
|
2750 |
|
|
Method 4: Do not use a prepare or check watcher because the module you |
2751 |
root |
1.183 |
want to embed is not flexible enough to support it. Instead, you can |
2752 |
|
|
override their poll function. The drawback with this solution is that the |
2753 |
|
|
main loop is now no longer controllable by EV. The C<Glib::EV> module uses |
2754 |
|
|
this approach, effectively embedding EV as a client into the horrible |
2755 |
|
|
libglib event loop. |
2756 |
root |
1.76 |
|
2757 |
root |
1.164 |
static gint |
2758 |
|
|
event_poll_func (GPollFD *fds, guint nfds, gint timeout) |
2759 |
|
|
{ |
2760 |
|
|
int got_events = 0; |
2761 |
|
|
|
2762 |
|
|
for (n = 0; n < nfds; ++n) |
2763 |
|
|
// create/start io watcher that sets the relevant bits in fds[n] and increment got_events |
2764 |
|
|
|
2765 |
|
|
if (timeout >= 0) |
2766 |
|
|
// create/start timer |
2767 |
|
|
|
2768 |
|
|
// poll |
2769 |
|
|
ev_loop (EV_A_ 0); |
2770 |
root |
1.76 |
|
2771 |
root |
1.164 |
// stop timer again |
2772 |
|
|
if (timeout >= 0) |
2773 |
|
|
ev_timer_stop (EV_A_ &to); |
2774 |
|
|
|
2775 |
|
|
// stop io watchers again - their callbacks should have set |
2776 |
|
|
for (n = 0; n < nfds; ++n) |
2777 |
|
|
ev_io_stop (EV_A_ iow [n]); |
2778 |
|
|
|
2779 |
|
|
return got_events; |
2780 |
|
|
} |
2781 |
root |
1.76 |
|
2782 |
root |
1.34 |
|
2783 |
root |
1.42 |
=head2 C<ev_embed> - when one backend isn't enough... |
2784 |
root |
1.35 |
|
2785 |
|
|
This is a rather advanced watcher type that lets you embed one event loop |
2786 |
root |
1.36 |
into another (currently only C<ev_io> events are supported in the embedded |
2787 |
|
|
loop, other types of watchers might be handled in a delayed or incorrect |
2788 |
root |
1.100 |
fashion and must not be used). |
2789 |
root |
1.35 |
|
2790 |
|
|
There are primarily two reasons you would want that: work around bugs and |
2791 |
|
|
prioritise I/O. |
2792 |
|
|
|
2793 |
|
|
As an example for a bug workaround, the kqueue backend might only support |
2794 |
|
|
sockets on some platform, so it is unusable as generic backend, but you |
2795 |
|
|
still want to make use of it because you have many sockets and it scales |
2796 |
root |
1.183 |
so nicely. In this case, you would create a kqueue-based loop and embed |
2797 |
|
|
it into your default loop (which might use e.g. poll). Overall operation |
2798 |
|
|
will be a bit slower because first libev has to call C<poll> and then |
2799 |
|
|
C<kevent>, but at least you can use both mechanisms for what they are |
2800 |
|
|
best: C<kqueue> for scalable sockets and C<poll> if you want it to work :) |
2801 |
|
|
|
2802 |
|
|
As for prioritising I/O: under rare circumstances you have the case where |
2803 |
|
|
some fds have to be watched and handled very quickly (with low latency), |
2804 |
|
|
and even priorities and idle watchers might have too much overhead. In |
2805 |
|
|
this case you would put all the high priority stuff in one loop and all |
2806 |
|
|
the rest in a second one, and embed the second one in the first. |
2807 |
root |
1.35 |
|
2808 |
root |
1.223 |
As long as the watcher is active, the callback will be invoked every |
2809 |
|
|
time there might be events pending in the embedded loop. The callback |
2810 |
|
|
must then call C<ev_embed_sweep (mainloop, watcher)> to make a single |
2811 |
|
|
sweep and invoke their callbacks (the callback doesn't need to invoke the |
2812 |
|
|
C<ev_embed_sweep> function directly, it could also start an idle watcher |
2813 |
|
|
to give the embedded loop strictly lower priority for example). |
2814 |
|
|
|
2815 |
|
|
You can also set the callback to C<0>, in which case the embed watcher |
2816 |
|
|
will automatically execute the embedded loop sweep whenever necessary. |
2817 |
|
|
|
2818 |
|
|
Fork detection will be handled transparently while the C<ev_embed> watcher |
2819 |
|
|
is active, i.e., the embedded loop will automatically be forked when the |
2820 |
|
|
embedding loop forks. In other cases, the user is responsible for calling |
2821 |
|
|
C<ev_loop_fork> on the embedded loop. |
2822 |
root |
1.35 |
|
2823 |
root |
1.184 |
Unfortunately, not all backends are embeddable: only the ones returned by |
2824 |
root |
1.35 |
C<ev_embeddable_backends> are, which, unfortunately, does not include any |
2825 |
|
|
portable one. |
2826 |
|
|
|
2827 |
|
|
So when you want to use this feature you will always have to be prepared |
2828 |
|
|
that you cannot get an embeddable loop. The recommended way to get around |
2829 |
|
|
this is to have a separate variables for your embeddable loop, try to |
2830 |
root |
1.111 |
create it, and if that fails, use the normal loop for everything. |
2831 |
root |
1.35 |
|
2832 |
root |
1.187 |
=head3 C<ev_embed> and fork |
2833 |
|
|
|
2834 |
|
|
While the C<ev_embed> watcher is running, forks in the embedding loop will |
2835 |
|
|
automatically be applied to the embedded loop as well, so no special |
2836 |
|
|
fork handling is required in that case. When the watcher is not running, |
2837 |
|
|
however, it is still the task of the libev user to call C<ev_loop_fork ()> |
2838 |
|
|
as applicable. |
2839 |
|
|
|
2840 |
root |
1.82 |
=head3 Watcher-Specific Functions and Data Members |
2841 |
|
|
|
2842 |
root |
1.35 |
=over 4 |
2843 |
|
|
|
2844 |
root |
1.36 |
=item ev_embed_init (ev_embed *, callback, struct ev_loop *embedded_loop) |
2845 |
|
|
|
2846 |
|
|
=item ev_embed_set (ev_embed *, callback, struct ev_loop *embedded_loop) |
2847 |
|
|
|
2848 |
|
|
Configures the watcher to embed the given loop, which must be |
2849 |
|
|
embeddable. If the callback is C<0>, then C<ev_embed_sweep> will be |
2850 |
|
|
invoked automatically, otherwise it is the responsibility of the callback |
2851 |
|
|
to invoke it (it will continue to be called until the sweep has been done, |
2852 |
root |
1.161 |
if you do not want that, you need to temporarily stop the embed watcher). |
2853 |
root |
1.35 |
|
2854 |
root |
1.36 |
=item ev_embed_sweep (loop, ev_embed *) |
2855 |
root |
1.35 |
|
2856 |
root |
1.36 |
Make a single, non-blocking sweep over the embedded loop. This works |
2857 |
|
|
similarly to C<ev_loop (embedded_loop, EVLOOP_NONBLOCK)>, but in the most |
2858 |
root |
1.161 |
appropriate way for embedded loops. |
2859 |
root |
1.35 |
|
2860 |
root |
1.91 |
=item struct ev_loop *other [read-only] |
2861 |
root |
1.48 |
|
2862 |
|
|
The embedded event loop. |
2863 |
|
|
|
2864 |
root |
1.35 |
=back |
2865 |
|
|
|
2866 |
root |
1.111 |
=head3 Examples |
2867 |
|
|
|
2868 |
|
|
Example: Try to get an embeddable event loop and embed it into the default |
2869 |
|
|
event loop. If that is not possible, use the default loop. The default |
2870 |
root |
1.161 |
loop is stored in C<loop_hi>, while the embeddable loop is stored in |
2871 |
|
|
C<loop_lo> (which is C<loop_hi> in the case no embeddable loop can be |
2872 |
root |
1.111 |
used). |
2873 |
|
|
|
2874 |
root |
1.164 |
struct ev_loop *loop_hi = ev_default_init (0); |
2875 |
|
|
struct ev_loop *loop_lo = 0; |
2876 |
root |
1.198 |
ev_embed embed; |
2877 |
root |
1.164 |
|
2878 |
|
|
// see if there is a chance of getting one that works |
2879 |
|
|
// (remember that a flags value of 0 means autodetection) |
2880 |
|
|
loop_lo = ev_embeddable_backends () & ev_recommended_backends () |
2881 |
|
|
? ev_loop_new (ev_embeddable_backends () & ev_recommended_backends ()) |
2882 |
|
|
: 0; |
2883 |
|
|
|
2884 |
|
|
// if we got one, then embed it, otherwise default to loop_hi |
2885 |
|
|
if (loop_lo) |
2886 |
|
|
{ |
2887 |
|
|
ev_embed_init (&embed, 0, loop_lo); |
2888 |
|
|
ev_embed_start (loop_hi, &embed); |
2889 |
|
|
} |
2890 |
|
|
else |
2891 |
|
|
loop_lo = loop_hi; |
2892 |
root |
1.111 |
|
2893 |
|
|
Example: Check if kqueue is available but not recommended and create |
2894 |
|
|
a kqueue backend for use with sockets (which usually work with any |
2895 |
|
|
kqueue implementation). Store the kqueue/socket-only event loop in |
2896 |
|
|
C<loop_socket>. (One might optionally use C<EVFLAG_NOENV>, too). |
2897 |
|
|
|
2898 |
root |
1.164 |
struct ev_loop *loop = ev_default_init (0); |
2899 |
|
|
struct ev_loop *loop_socket = 0; |
2900 |
root |
1.198 |
ev_embed embed; |
2901 |
root |
1.164 |
|
2902 |
|
|
if (ev_supported_backends () & ~ev_recommended_backends () & EVBACKEND_KQUEUE) |
2903 |
|
|
if ((loop_socket = ev_loop_new (EVBACKEND_KQUEUE)) |
2904 |
|
|
{ |
2905 |
|
|
ev_embed_init (&embed, 0, loop_socket); |
2906 |
|
|
ev_embed_start (loop, &embed); |
2907 |
|
|
} |
2908 |
root |
1.111 |
|
2909 |
root |
1.164 |
if (!loop_socket) |
2910 |
|
|
loop_socket = loop; |
2911 |
root |
1.111 |
|
2912 |
root |
1.164 |
// now use loop_socket for all sockets, and loop for everything else |
2913 |
root |
1.111 |
|
2914 |
root |
1.35 |
|
2915 |
root |
1.50 |
=head2 C<ev_fork> - the audacity to resume the event loop after a fork |
2916 |
|
|
|
2917 |
|
|
Fork watchers are called when a C<fork ()> was detected (usually because |
2918 |
|
|
whoever is a good citizen cared to tell libev about it by calling |
2919 |
|
|
C<ev_default_fork> or C<ev_loop_fork>). The invocation is done before the |
2920 |
|
|
event loop blocks next and before C<ev_check> watchers are being called, |
2921 |
|
|
and only in the child after the fork. If whoever good citizen calling |
2922 |
|
|
C<ev_default_fork> cheats and calls it in the wrong process, the fork |
2923 |
|
|
handlers will be invoked, too, of course. |
2924 |
|
|
|
2925 |
root |
1.238 |
=head3 The special problem of life after fork - how is it possible? |
2926 |
|
|
|
2927 |
|
|
Most uses of C<fork()> consist of forking, then some simple calls to ste |
2928 |
|
|
up/change the process environment, followed by a call to C<exec()>. This |
2929 |
|
|
sequence should be handled by libev without any problems. |
2930 |
|
|
|
2931 |
|
|
This changes when the application actually wants to do event handling |
2932 |
|
|
in the child, or both parent in child, in effect "continuing" after the |
2933 |
|
|
fork. |
2934 |
|
|
|
2935 |
|
|
The default mode of operation (for libev, with application help to detect |
2936 |
|
|
forks) is to duplicate all the state in the child, as would be expected |
2937 |
|
|
when I<either> the parent I<or> the child process continues. |
2938 |
|
|
|
2939 |
|
|
When both processes want to continue using libev, then this is usually the |
2940 |
|
|
wrong result. In that case, usually one process (typically the parent) is |
2941 |
|
|
supposed to continue with all watchers in place as before, while the other |
2942 |
|
|
process typically wants to start fresh, i.e. without any active watchers. |
2943 |
|
|
|
2944 |
|
|
The cleanest and most efficient way to achieve that with libev is to |
2945 |
|
|
simply create a new event loop, which of course will be "empty", and |
2946 |
|
|
use that for new watchers. This has the advantage of not touching more |
2947 |
|
|
memory than necessary, and thus avoiding the copy-on-write, and the |
2948 |
|
|
disadvantage of having to use multiple event loops (which do not support |
2949 |
|
|
signal watchers). |
2950 |
|
|
|
2951 |
|
|
When this is not possible, or you want to use the default loop for |
2952 |
|
|
other reasons, then in the process that wants to start "fresh", call |
2953 |
|
|
C<ev_default_destroy ()> followed by C<ev_default_loop (...)>. Destroying |
2954 |
|
|
the default loop will "orphan" (not stop) all registered watchers, so you |
2955 |
|
|
have to be careful not to execute code that modifies those watchers. Note |
2956 |
|
|
also that in that case, you have to re-register any signal watchers. |
2957 |
|
|
|
2958 |
root |
1.83 |
=head3 Watcher-Specific Functions and Data Members |
2959 |
|
|
|
2960 |
root |
1.50 |
=over 4 |
2961 |
|
|
|
2962 |
|
|
=item ev_fork_init (ev_signal *, callback) |
2963 |
|
|
|
2964 |
|
|
Initialises and configures the fork watcher - it has no parameters of any |
2965 |
|
|
kind. There is a C<ev_fork_set> macro, but using it is utterly pointless, |
2966 |
|
|
believe me. |
2967 |
|
|
|
2968 |
|
|
=back |
2969 |
|
|
|
2970 |
|
|
|
2971 |
root |
1.122 |
=head2 C<ev_async> - how to wake up another event loop |
2972 |
|
|
|
2973 |
|
|
In general, you cannot use an C<ev_loop> from multiple threads or other |
2974 |
|
|
asynchronous sources such as signal handlers (as opposed to multiple event |
2975 |
|
|
loops - those are of course safe to use in different threads). |
2976 |
|
|
|
2977 |
|
|
Sometimes, however, you need to wake up another event loop you do not |
2978 |
|
|
control, for example because it belongs to another thread. This is what |
2979 |
|
|
C<ev_async> watchers do: as long as the C<ev_async> watcher is active, you |
2980 |
|
|
can signal it by calling C<ev_async_send>, which is thread- and signal |
2981 |
|
|
safe. |
2982 |
|
|
|
2983 |
|
|
This functionality is very similar to C<ev_signal> watchers, as signals, |
2984 |
|
|
too, are asynchronous in nature, and signals, too, will be compressed |
2985 |
|
|
(i.e. the number of callback invocations may be less than the number of |
2986 |
|
|
C<ev_async_sent> calls). |
2987 |
|
|
|
2988 |
|
|
Unlike C<ev_signal> watchers, C<ev_async> works with any event loop, not |
2989 |
|
|
just the default loop. |
2990 |
|
|
|
2991 |
root |
1.124 |
=head3 Queueing |
2992 |
|
|
|
2993 |
|
|
C<ev_async> does not support queueing of data in any way. The reason |
2994 |
|
|
is that the author does not know of a simple (or any) algorithm for a |
2995 |
|
|
multiple-writer-single-reader queue that works in all cases and doesn't |
2996 |
root |
1.274 |
need elaborate support such as pthreads or unportable memory access |
2997 |
|
|
semantics. |
2998 |
root |
1.124 |
|
2999 |
|
|
That means that if you want to queue data, you have to provide your own |
3000 |
root |
1.184 |
queue. But at least I can tell you how to implement locking around your |
3001 |
root |
1.130 |
queue: |
3002 |
root |
1.124 |
|
3003 |
|
|
=over 4 |
3004 |
|
|
|
3005 |
|
|
=item queueing from a signal handler context |
3006 |
|
|
|
3007 |
|
|
To implement race-free queueing, you simply add to the queue in the signal |
3008 |
root |
1.191 |
handler but you block the signal handler in the watcher callback. Here is |
3009 |
|
|
an example that does that for some fictitious SIGUSR1 handler: |
3010 |
root |
1.124 |
|
3011 |
|
|
static ev_async mysig; |
3012 |
|
|
|
3013 |
|
|
static void |
3014 |
|
|
sigusr1_handler (void) |
3015 |
|
|
{ |
3016 |
|
|
sometype data; |
3017 |
|
|
|
3018 |
|
|
// no locking etc. |
3019 |
|
|
queue_put (data); |
3020 |
root |
1.133 |
ev_async_send (EV_DEFAULT_ &mysig); |
3021 |
root |
1.124 |
} |
3022 |
|
|
|
3023 |
|
|
static void |
3024 |
|
|
mysig_cb (EV_P_ ev_async *w, int revents) |
3025 |
|
|
{ |
3026 |
|
|
sometype data; |
3027 |
|
|
sigset_t block, prev; |
3028 |
|
|
|
3029 |
|
|
sigemptyset (&block); |
3030 |
|
|
sigaddset (&block, SIGUSR1); |
3031 |
|
|
sigprocmask (SIG_BLOCK, &block, &prev); |
3032 |
|
|
|
3033 |
|
|
while (queue_get (&data)) |
3034 |
|
|
process (data); |
3035 |
|
|
|
3036 |
|
|
if (sigismember (&prev, SIGUSR1) |
3037 |
|
|
sigprocmask (SIG_UNBLOCK, &block, 0); |
3038 |
|
|
} |
3039 |
|
|
|
3040 |
|
|
(Note: pthreads in theory requires you to use C<pthread_setmask> |
3041 |
|
|
instead of C<sigprocmask> when you use threads, but libev doesn't do it |
3042 |
|
|
either...). |
3043 |
|
|
|
3044 |
|
|
=item queueing from a thread context |
3045 |
|
|
|
3046 |
|
|
The strategy for threads is different, as you cannot (easily) block |
3047 |
|
|
threads but you can easily preempt them, so to queue safely you need to |
3048 |
root |
1.130 |
employ a traditional mutex lock, such as in this pthread example: |
3049 |
root |
1.124 |
|
3050 |
|
|
static ev_async mysig; |
3051 |
|
|
static pthread_mutex_t mymutex = PTHREAD_MUTEX_INITIALIZER; |
3052 |
|
|
|
3053 |
|
|
static void |
3054 |
|
|
otherthread (void) |
3055 |
|
|
{ |
3056 |
|
|
// only need to lock the actual queueing operation |
3057 |
|
|
pthread_mutex_lock (&mymutex); |
3058 |
|
|
queue_put (data); |
3059 |
|
|
pthread_mutex_unlock (&mymutex); |
3060 |
|
|
|
3061 |
root |
1.133 |
ev_async_send (EV_DEFAULT_ &mysig); |
3062 |
root |
1.124 |
} |
3063 |
|
|
|
3064 |
|
|
static void |
3065 |
|
|
mysig_cb (EV_P_ ev_async *w, int revents) |
3066 |
|
|
{ |
3067 |
|
|
pthread_mutex_lock (&mymutex); |
3068 |
|
|
|
3069 |
|
|
while (queue_get (&data)) |
3070 |
|
|
process (data); |
3071 |
|
|
|
3072 |
|
|
pthread_mutex_unlock (&mymutex); |
3073 |
|
|
} |
3074 |
|
|
|
3075 |
|
|
=back |
3076 |
|
|
|
3077 |
|
|
|
3078 |
root |
1.122 |
=head3 Watcher-Specific Functions and Data Members |
3079 |
|
|
|
3080 |
|
|
=over 4 |
3081 |
|
|
|
3082 |
|
|
=item ev_async_init (ev_async *, callback) |
3083 |
|
|
|
3084 |
|
|
Initialises and configures the async watcher - it has no parameters of any |
3085 |
root |
1.208 |
kind. There is a C<ev_async_set> macro, but using it is utterly pointless, |
3086 |
root |
1.184 |
trust me. |
3087 |
root |
1.122 |
|
3088 |
|
|
=item ev_async_send (loop, ev_async *) |
3089 |
|
|
|
3090 |
|
|
Sends/signals/activates the given C<ev_async> watcher, that is, feeds |
3091 |
|
|
an C<EV_ASYNC> event on the watcher into the event loop. Unlike |
3092 |
root |
1.184 |
C<ev_feed_event>, this call is safe to do from other threads, signal or |
3093 |
root |
1.161 |
similar contexts (see the discussion of C<EV_ATOMIC_T> in the embedding |
3094 |
root |
1.122 |
section below on what exactly this means). |
3095 |
|
|
|
3096 |
root |
1.227 |
Note that, as with other watchers in libev, multiple events might get |
3097 |
|
|
compressed into a single callback invocation (another way to look at this |
3098 |
|
|
is that C<ev_async> watchers are level-triggered, set on C<ev_async_send>, |
3099 |
|
|
reset when the event loop detects that). |
3100 |
|
|
|
3101 |
|
|
This call incurs the overhead of a system call only once per event loop |
3102 |
|
|
iteration, so while the overhead might be noticeable, it doesn't apply to |
3103 |
|
|
repeated calls to C<ev_async_send> for the same event loop. |
3104 |
root |
1.122 |
|
3105 |
root |
1.140 |
=item bool = ev_async_pending (ev_async *) |
3106 |
|
|
|
3107 |
|
|
Returns a non-zero value when C<ev_async_send> has been called on the |
3108 |
|
|
watcher but the event has not yet been processed (or even noted) by the |
3109 |
|
|
event loop. |
3110 |
|
|
|
3111 |
|
|
C<ev_async_send> sets a flag in the watcher and wakes up the loop. When |
3112 |
|
|
the loop iterates next and checks for the watcher to have become active, |
3113 |
|
|
it will reset the flag again. C<ev_async_pending> can be used to very |
3114 |
root |
1.161 |
quickly check whether invoking the loop might be a good idea. |
3115 |
root |
1.140 |
|
3116 |
root |
1.227 |
Not that this does I<not> check whether the watcher itself is pending, |
3117 |
|
|
only whether it has been requested to make this watcher pending: there |
3118 |
|
|
is a time window between the event loop checking and resetting the async |
3119 |
|
|
notification, and the callback being invoked. |
3120 |
root |
1.140 |
|
3121 |
root |
1.122 |
=back |
3122 |
|
|
|
3123 |
|
|
|
3124 |
root |
1.1 |
=head1 OTHER FUNCTIONS |
3125 |
|
|
|
3126 |
root |
1.14 |
There are some other functions of possible interest. Described. Here. Now. |
3127 |
root |
1.1 |
|
3128 |
|
|
=over 4 |
3129 |
|
|
|
3130 |
|
|
=item ev_once (loop, int fd, int events, ev_tstamp timeout, callback) |
3131 |
|
|
|
3132 |
|
|
This function combines a simple timer and an I/O watcher, calls your |
3133 |
root |
1.192 |
callback on whichever event happens first and automatically stops both |
3134 |
root |
1.1 |
watchers. This is useful if you want to wait for a single event on an fd |
3135 |
root |
1.22 |
or timeout without having to allocate/configure/start/stop/free one or |
3136 |
root |
1.1 |
more watchers yourself. |
3137 |
|
|
|
3138 |
root |
1.192 |
If C<fd> is less than 0, then no I/O watcher will be started and the |
3139 |
|
|
C<events> argument is being ignored. Otherwise, an C<ev_io> watcher for |
3140 |
|
|
the given C<fd> and C<events> set will be created and started. |
3141 |
root |
1.1 |
|
3142 |
|
|
If C<timeout> is less than 0, then no timeout watcher will be |
3143 |
root |
1.14 |
started. Otherwise an C<ev_timer> watcher with after = C<timeout> (and |
3144 |
root |
1.193 |
repeat = 0) will be started. C<0> is a valid timeout. |
3145 |
root |
1.14 |
|
3146 |
|
|
The callback has the type C<void (*cb)(int revents, void *arg)> and gets |
3147 |
root |
1.21 |
passed an C<revents> set like normal event callbacks (a combination of |
3148 |
root |
1.14 |
C<EV_ERROR>, C<EV_READ>, C<EV_WRITE> or C<EV_TIMEOUT>) and the C<arg> |
3149 |
root |
1.193 |
value passed to C<ev_once>. Note that it is possible to receive I<both> |
3150 |
|
|
a timeout and an io event at the same time - you probably should give io |
3151 |
|
|
events precedence. |
3152 |
|
|
|
3153 |
|
|
Example: wait up to ten seconds for data to appear on STDIN_FILENO. |
3154 |
root |
1.1 |
|
3155 |
root |
1.164 |
static void stdin_ready (int revents, void *arg) |
3156 |
|
|
{ |
3157 |
root |
1.193 |
if (revents & EV_READ) |
3158 |
|
|
/* stdin might have data for us, joy! */; |
3159 |
|
|
else if (revents & EV_TIMEOUT) |
3160 |
root |
1.164 |
/* doh, nothing entered */; |
3161 |
|
|
} |
3162 |
root |
1.1 |
|
3163 |
root |
1.164 |
ev_once (STDIN_FILENO, EV_READ, 10., stdin_ready, 0); |
3164 |
root |
1.1 |
|
3165 |
root |
1.274 |
=item ev_feed_fd_event (loop, int fd, int revents) |
3166 |
root |
1.1 |
|
3167 |
root |
1.14 |
Feed an event on the given fd, as if a file descriptor backend detected |
3168 |
|
|
the given events it. |
3169 |
root |
1.1 |
|
3170 |
root |
1.274 |
=item ev_feed_signal_event (loop, int signum) |
3171 |
root |
1.1 |
|
3172 |
root |
1.161 |
Feed an event as if the given signal occurred (C<loop> must be the default |
3173 |
root |
1.36 |
loop!). |
3174 |
root |
1.1 |
|
3175 |
|
|
=back |
3176 |
|
|
|
3177 |
root |
1.34 |
|
3178 |
root |
1.20 |
=head1 LIBEVENT EMULATION |
3179 |
|
|
|
3180 |
root |
1.24 |
Libev offers a compatibility emulation layer for libevent. It cannot |
3181 |
|
|
emulate the internals of libevent, so here are some usage hints: |
3182 |
|
|
|
3183 |
|
|
=over 4 |
3184 |
|
|
|
3185 |
|
|
=item * Use it by including <event.h>, as usual. |
3186 |
|
|
|
3187 |
|
|
=item * The following members are fully supported: ev_base, ev_callback, |
3188 |
|
|
ev_arg, ev_fd, ev_res, ev_events. |
3189 |
|
|
|
3190 |
|
|
=item * Avoid using ev_flags and the EVLIST_*-macros, while it is |
3191 |
|
|
maintained by libev, it does not work exactly the same way as in libevent (consider |
3192 |
|
|
it a private API). |
3193 |
|
|
|
3194 |
|
|
=item * Priorities are not currently supported. Initialising priorities |
3195 |
|
|
will fail and all watchers will have the same priority, even though there |
3196 |
|
|
is an ev_pri field. |
3197 |
|
|
|
3198 |
root |
1.146 |
=item * In libevent, the last base created gets the signals, in libev, the |
3199 |
|
|
first base created (== the default loop) gets the signals. |
3200 |
|
|
|
3201 |
root |
1.24 |
=item * Other members are not supported. |
3202 |
|
|
|
3203 |
|
|
=item * The libev emulation is I<not> ABI compatible to libevent, you need |
3204 |
|
|
to use the libev header file and library. |
3205 |
|
|
|
3206 |
|
|
=back |
3207 |
root |
1.20 |
|
3208 |
|
|
=head1 C++ SUPPORT |
3209 |
|
|
|
3210 |
root |
1.38 |
Libev comes with some simplistic wrapper classes for C++ that mainly allow |
3211 |
root |
1.161 |
you to use some convenience methods to start/stop watchers and also change |
3212 |
root |
1.38 |
the callback model to a model using method callbacks on objects. |
3213 |
|
|
|
3214 |
|
|
To use it, |
3215 |
|
|
|
3216 |
root |
1.164 |
#include <ev++.h> |
3217 |
root |
1.38 |
|
3218 |
root |
1.71 |
This automatically includes F<ev.h> and puts all of its definitions (many |
3219 |
|
|
of them macros) into the global namespace. All C++ specific things are |
3220 |
|
|
put into the C<ev> namespace. It should support all the same embedding |
3221 |
|
|
options as F<ev.h>, most notably C<EV_MULTIPLICITY>. |
3222 |
|
|
|
3223 |
root |
1.72 |
Care has been taken to keep the overhead low. The only data member the C++ |
3224 |
|
|
classes add (compared to plain C-style watchers) is the event loop pointer |
3225 |
|
|
that the watcher is associated with (or no additional members at all if |
3226 |
|
|
you disable C<EV_MULTIPLICITY> when embedding libev). |
3227 |
root |
1.71 |
|
3228 |
root |
1.72 |
Currently, functions, and static and non-static member functions can be |
3229 |
root |
1.71 |
used as callbacks. Other types should be easy to add as long as they only |
3230 |
|
|
need one additional pointer for context. If you need support for other |
3231 |
|
|
types of functors please contact the author (preferably after implementing |
3232 |
|
|
it). |
3233 |
root |
1.38 |
|
3234 |
|
|
Here is a list of things available in the C<ev> namespace: |
3235 |
|
|
|
3236 |
|
|
=over 4 |
3237 |
|
|
|
3238 |
|
|
=item C<ev::READ>, C<ev::WRITE> etc. |
3239 |
|
|
|
3240 |
|
|
These are just enum values with the same values as the C<EV_READ> etc. |
3241 |
|
|
macros from F<ev.h>. |
3242 |
|
|
|
3243 |
|
|
=item C<ev::tstamp>, C<ev::now> |
3244 |
|
|
|
3245 |
|
|
Aliases to the same types/functions as with the C<ev_> prefix. |
3246 |
|
|
|
3247 |
|
|
=item C<ev::io>, C<ev::timer>, C<ev::periodic>, C<ev::idle>, C<ev::sig> etc. |
3248 |
|
|
|
3249 |
|
|
For each C<ev_TYPE> watcher in F<ev.h> there is a corresponding class of |
3250 |
|
|
the same name in the C<ev> namespace, with the exception of C<ev_signal> |
3251 |
|
|
which is called C<ev::sig> to avoid clashes with the C<signal> macro |
3252 |
|
|
defines by many implementations. |
3253 |
|
|
|
3254 |
|
|
All of those classes have these methods: |
3255 |
|
|
|
3256 |
|
|
=over 4 |
3257 |
|
|
|
3258 |
root |
1.71 |
=item ev::TYPE::TYPE () |
3259 |
root |
1.38 |
|
3260 |
root |
1.274 |
=item ev::TYPE::TYPE (loop) |
3261 |
root |
1.38 |
|
3262 |
|
|
=item ev::TYPE::~TYPE |
3263 |
|
|
|
3264 |
root |
1.71 |
The constructor (optionally) takes an event loop to associate the watcher |
3265 |
|
|
with. If it is omitted, it will use C<EV_DEFAULT>. |
3266 |
|
|
|
3267 |
|
|
The constructor calls C<ev_init> for you, which means you have to call the |
3268 |
|
|
C<set> method before starting it. |
3269 |
|
|
|
3270 |
|
|
It will not set a callback, however: You have to call the templated C<set> |
3271 |
|
|
method to set a callback before you can start the watcher. |
3272 |
|
|
|
3273 |
|
|
(The reason why you have to use a method is a limitation in C++ which does |
3274 |
|
|
not allow explicit template arguments for constructors). |
3275 |
root |
1.38 |
|
3276 |
|
|
The destructor automatically stops the watcher if it is active. |
3277 |
|
|
|
3278 |
root |
1.71 |
=item w->set<class, &class::method> (object *) |
3279 |
|
|
|
3280 |
|
|
This method sets the callback method to call. The method has to have a |
3281 |
|
|
signature of C<void (*)(ev_TYPE &, int)>, it receives the watcher as |
3282 |
|
|
first argument and the C<revents> as second. The object must be given as |
3283 |
|
|
parameter and is stored in the C<data> member of the watcher. |
3284 |
|
|
|
3285 |
|
|
This method synthesizes efficient thunking code to call your method from |
3286 |
|
|
the C callback that libev requires. If your compiler can inline your |
3287 |
|
|
callback (i.e. it is visible to it at the place of the C<set> call and |
3288 |
|
|
your compiler is good :), then the method will be fully inlined into the |
3289 |
|
|
thunking function, making it as fast as a direct C callback. |
3290 |
|
|
|
3291 |
|
|
Example: simple class declaration and watcher initialisation |
3292 |
|
|
|
3293 |
root |
1.164 |
struct myclass |
3294 |
|
|
{ |
3295 |
|
|
void io_cb (ev::io &w, int revents) { } |
3296 |
|
|
} |
3297 |
|
|
|
3298 |
|
|
myclass obj; |
3299 |
|
|
ev::io iow; |
3300 |
|
|
iow.set <myclass, &myclass::io_cb> (&obj); |
3301 |
root |
1.71 |
|
3302 |
root |
1.221 |
=item w->set (object *) |
3303 |
|
|
|
3304 |
|
|
This is an B<experimental> feature that might go away in a future version. |
3305 |
|
|
|
3306 |
|
|
This is a variation of a method callback - leaving out the method to call |
3307 |
|
|
will default the method to C<operator ()>, which makes it possible to use |
3308 |
|
|
functor objects without having to manually specify the C<operator ()> all |
3309 |
|
|
the time. Incidentally, you can then also leave out the template argument |
3310 |
|
|
list. |
3311 |
|
|
|
3312 |
|
|
The C<operator ()> method prototype must be C<void operator ()(watcher &w, |
3313 |
|
|
int revents)>. |
3314 |
|
|
|
3315 |
|
|
See the method-C<set> above for more details. |
3316 |
|
|
|
3317 |
|
|
Example: use a functor object as callback. |
3318 |
|
|
|
3319 |
|
|
struct myfunctor |
3320 |
|
|
{ |
3321 |
|
|
void operator() (ev::io &w, int revents) |
3322 |
|
|
{ |
3323 |
|
|
... |
3324 |
|
|
} |
3325 |
|
|
} |
3326 |
|
|
|
3327 |
|
|
myfunctor f; |
3328 |
|
|
|
3329 |
|
|
ev::io w; |
3330 |
|
|
w.set (&f); |
3331 |
|
|
|
3332 |
root |
1.75 |
=item w->set<function> (void *data = 0) |
3333 |
root |
1.71 |
|
3334 |
|
|
Also sets a callback, but uses a static method or plain function as |
3335 |
|
|
callback. The optional C<data> argument will be stored in the watcher's |
3336 |
|
|
C<data> member and is free for you to use. |
3337 |
|
|
|
3338 |
root |
1.75 |
The prototype of the C<function> must be C<void (*)(ev::TYPE &w, int)>. |
3339 |
|
|
|
3340 |
root |
1.71 |
See the method-C<set> above for more details. |
3341 |
|
|
|
3342 |
root |
1.184 |
Example: Use a plain function as callback. |
3343 |
root |
1.75 |
|
3344 |
root |
1.164 |
static void io_cb (ev::io &w, int revents) { } |
3345 |
|
|
iow.set <io_cb> (); |
3346 |
root |
1.75 |
|
3347 |
root |
1.274 |
=item w->set (loop) |
3348 |
root |
1.38 |
|
3349 |
|
|
Associates a different C<struct ev_loop> with this watcher. You can only |
3350 |
|
|
do this when the watcher is inactive (and not pending either). |
3351 |
|
|
|
3352 |
root |
1.161 |
=item w->set ([arguments]) |
3353 |
root |
1.38 |
|
3354 |
root |
1.161 |
Basically the same as C<ev_TYPE_set>, with the same arguments. Must be |
3355 |
root |
1.71 |
called at least once. Unlike the C counterpart, an active watcher gets |
3356 |
|
|
automatically stopped and restarted when reconfiguring it with this |
3357 |
|
|
method. |
3358 |
root |
1.38 |
|
3359 |
|
|
=item w->start () |
3360 |
|
|
|
3361 |
root |
1.71 |
Starts the watcher. Note that there is no C<loop> argument, as the |
3362 |
|
|
constructor already stores the event loop. |
3363 |
root |
1.38 |
|
3364 |
|
|
=item w->stop () |
3365 |
|
|
|
3366 |
|
|
Stops the watcher if it is active. Again, no C<loop> argument. |
3367 |
|
|
|
3368 |
root |
1.84 |
=item w->again () (C<ev::timer>, C<ev::periodic> only) |
3369 |
root |
1.38 |
|
3370 |
|
|
For C<ev::timer> and C<ev::periodic>, this invokes the corresponding |
3371 |
|
|
C<ev_TYPE_again> function. |
3372 |
|
|
|
3373 |
root |
1.84 |
=item w->sweep () (C<ev::embed> only) |
3374 |
root |
1.38 |
|
3375 |
|
|
Invokes C<ev_embed_sweep>. |
3376 |
|
|
|
3377 |
root |
1.84 |
=item w->update () (C<ev::stat> only) |
3378 |
root |
1.49 |
|
3379 |
|
|
Invokes C<ev_stat_stat>. |
3380 |
|
|
|
3381 |
root |
1.38 |
=back |
3382 |
|
|
|
3383 |
|
|
=back |
3384 |
|
|
|
3385 |
|
|
Example: Define a class with an IO and idle watcher, start one of them in |
3386 |
|
|
the constructor. |
3387 |
|
|
|
3388 |
root |
1.164 |
class myclass |
3389 |
|
|
{ |
3390 |
root |
1.184 |
ev::io io ; void io_cb (ev::io &w, int revents); |
3391 |
|
|
ev::idle idle; void idle_cb (ev::idle &w, int revents); |
3392 |
root |
1.164 |
|
3393 |
|
|
myclass (int fd) |
3394 |
|
|
{ |
3395 |
|
|
io .set <myclass, &myclass::io_cb > (this); |
3396 |
|
|
idle.set <myclass, &myclass::idle_cb> (this); |
3397 |
|
|
|
3398 |
|
|
io.start (fd, ev::READ); |
3399 |
|
|
} |
3400 |
|
|
}; |
3401 |
root |
1.20 |
|
3402 |
root |
1.50 |
|
3403 |
root |
1.136 |
=head1 OTHER LANGUAGE BINDINGS |
3404 |
|
|
|
3405 |
|
|
Libev does not offer other language bindings itself, but bindings for a |
3406 |
root |
1.161 |
number of languages exist in the form of third-party packages. If you know |
3407 |
root |
1.136 |
any interesting language binding in addition to the ones listed here, drop |
3408 |
|
|
me a note. |
3409 |
|
|
|
3410 |
|
|
=over 4 |
3411 |
|
|
|
3412 |
|
|
=item Perl |
3413 |
|
|
|
3414 |
|
|
The EV module implements the full libev API and is actually used to test |
3415 |
|
|
libev. EV is developed together with libev. Apart from the EV core module, |
3416 |
|
|
there are additional modules that implement libev-compatible interfaces |
3417 |
root |
1.184 |
to C<libadns> (C<EV::ADNS>, but C<AnyEvent::DNS> is preferred nowadays), |
3418 |
|
|
C<Net::SNMP> (C<Net::SNMP::EV>) and the C<libglib> event core (C<Glib::EV> |
3419 |
|
|
and C<EV::Glib>). |
3420 |
root |
1.136 |
|
3421 |
root |
1.166 |
It can be found and installed via CPAN, its homepage is at |
3422 |
root |
1.136 |
L<http://software.schmorp.de/pkg/EV>. |
3423 |
|
|
|
3424 |
root |
1.166 |
=item Python |
3425 |
|
|
|
3426 |
|
|
Python bindings can be found at L<http://code.google.com/p/pyev/>. It |
3427 |
root |
1.228 |
seems to be quite complete and well-documented. |
3428 |
root |
1.166 |
|
3429 |
root |
1.136 |
=item Ruby |
3430 |
|
|
|
3431 |
|
|
Tony Arcieri has written a ruby extension that offers access to a subset |
3432 |
root |
1.161 |
of the libev API and adds file handle abstractions, asynchronous DNS and |
3433 |
root |
1.136 |
more on top of it. It can be found via gem servers. Its homepage is at |
3434 |
|
|
L<http://rev.rubyforge.org/>. |
3435 |
|
|
|
3436 |
root |
1.218 |
Roger Pack reports that using the link order C<-lws2_32 -lmsvcrt-ruby-190> |
3437 |
|
|
makes rev work even on mingw. |
3438 |
|
|
|
3439 |
root |
1.228 |
=item Haskell |
3440 |
|
|
|
3441 |
|
|
A haskell binding to libev is available at |
3442 |
|
|
L<http://hackage.haskell.org/cgi-bin/hackage-scripts/package/hlibev>. |
3443 |
|
|
|
3444 |
root |
1.136 |
=item D |
3445 |
|
|
|
3446 |
|
|
Leandro Lucarella has written a D language binding (F<ev.d>) for libev, to |
3447 |
root |
1.172 |
be found at L<http://proj.llucax.com.ar/wiki/evd>. |
3448 |
root |
1.136 |
|
3449 |
root |
1.201 |
=item Ocaml |
3450 |
|
|
|
3451 |
|
|
Erkki Seppala has written Ocaml bindings for libev, to be found at |
3452 |
|
|
L<http://modeemi.cs.tut.fi/~flux/software/ocaml-ev/>. |
3453 |
|
|
|
3454 |
root |
1.263 |
=item Lua |
3455 |
|
|
|
3456 |
root |
1.279 |
Brian Maher has written a partial interface to libev for lua (at the |
3457 |
|
|
time of this writing, only C<ev_io> and C<ev_timer>), to be found at |
3458 |
root |
1.263 |
L<http://github.com/brimworks/lua-ev>. |
3459 |
|
|
|
3460 |
root |
1.136 |
=back |
3461 |
|
|
|
3462 |
|
|
|
3463 |
root |
1.50 |
=head1 MACRO MAGIC |
3464 |
|
|
|
3465 |
root |
1.161 |
Libev can be compiled with a variety of options, the most fundamental |
3466 |
root |
1.84 |
of which is C<EV_MULTIPLICITY>. This option determines whether (most) |
3467 |
|
|
functions and callbacks have an initial C<struct ev_loop *> argument. |
3468 |
root |
1.50 |
|
3469 |
|
|
To make it easier to write programs that cope with either variant, the |
3470 |
|
|
following macros are defined: |
3471 |
|
|
|
3472 |
|
|
=over 4 |
3473 |
|
|
|
3474 |
|
|
=item C<EV_A>, C<EV_A_> |
3475 |
|
|
|
3476 |
|
|
This provides the loop I<argument> for functions, if one is required ("ev |
3477 |
|
|
loop argument"). The C<EV_A> form is used when this is the sole argument, |
3478 |
|
|
C<EV_A_> is used when other arguments are following. Example: |
3479 |
|
|
|
3480 |
root |
1.164 |
ev_unref (EV_A); |
3481 |
|
|
ev_timer_add (EV_A_ watcher); |
3482 |
|
|
ev_loop (EV_A_ 0); |
3483 |
root |
1.50 |
|
3484 |
|
|
It assumes the variable C<loop> of type C<struct ev_loop *> is in scope, |
3485 |
|
|
which is often provided by the following macro. |
3486 |
|
|
|
3487 |
|
|
=item C<EV_P>, C<EV_P_> |
3488 |
|
|
|
3489 |
|
|
This provides the loop I<parameter> for functions, if one is required ("ev |
3490 |
|
|
loop parameter"). The C<EV_P> form is used when this is the sole parameter, |
3491 |
|
|
C<EV_P_> is used when other parameters are following. Example: |
3492 |
|
|
|
3493 |
root |
1.164 |
// this is how ev_unref is being declared |
3494 |
|
|
static void ev_unref (EV_P); |
3495 |
root |
1.50 |
|
3496 |
root |
1.164 |
// this is how you can declare your typical callback |
3497 |
|
|
static void cb (EV_P_ ev_timer *w, int revents) |
3498 |
root |
1.50 |
|
3499 |
|
|
It declares a parameter C<loop> of type C<struct ev_loop *>, quite |
3500 |
|
|
suitable for use with C<EV_A>. |
3501 |
|
|
|
3502 |
|
|
=item C<EV_DEFAULT>, C<EV_DEFAULT_> |
3503 |
|
|
|
3504 |
|
|
Similar to the other two macros, this gives you the value of the default |
3505 |
|
|
loop, if multiple loops are supported ("ev loop default"). |
3506 |
|
|
|
3507 |
root |
1.143 |
=item C<EV_DEFAULT_UC>, C<EV_DEFAULT_UC_> |
3508 |
|
|
|
3509 |
|
|
Usage identical to C<EV_DEFAULT> and C<EV_DEFAULT_>, but requires that the |
3510 |
|
|
default loop has been initialised (C<UC> == unchecked). Their behaviour |
3511 |
|
|
is undefined when the default loop has not been initialised by a previous |
3512 |
|
|
execution of C<EV_DEFAULT>, C<EV_DEFAULT_> or C<ev_default_init (...)>. |
3513 |
|
|
|
3514 |
|
|
It is often prudent to use C<EV_DEFAULT> when initialising the first |
3515 |
|
|
watcher in a function but use C<EV_DEFAULT_UC> afterwards. |
3516 |
|
|
|
3517 |
root |
1.50 |
=back |
3518 |
|
|
|
3519 |
root |
1.63 |
Example: Declare and initialise a check watcher, utilising the above |
3520 |
root |
1.68 |
macros so it will work regardless of whether multiple loops are supported |
3521 |
root |
1.63 |
or not. |
3522 |
root |
1.50 |
|
3523 |
root |
1.164 |
static void |
3524 |
|
|
check_cb (EV_P_ ev_timer *w, int revents) |
3525 |
|
|
{ |
3526 |
|
|
ev_check_stop (EV_A_ w); |
3527 |
|
|
} |
3528 |
|
|
|
3529 |
|
|
ev_check check; |
3530 |
|
|
ev_check_init (&check, check_cb); |
3531 |
|
|
ev_check_start (EV_DEFAULT_ &check); |
3532 |
|
|
ev_loop (EV_DEFAULT_ 0); |
3533 |
root |
1.50 |
|
3534 |
root |
1.39 |
=head1 EMBEDDING |
3535 |
|
|
|
3536 |
|
|
Libev can (and often is) directly embedded into host |
3537 |
|
|
applications. Examples of applications that embed it include the Deliantra |
3538 |
|
|
Game Server, the EV perl module, the GNU Virtual Private Ethernet (gvpe) |
3539 |
|
|
and rxvt-unicode. |
3540 |
|
|
|
3541 |
root |
1.91 |
The goal is to enable you to just copy the necessary files into your |
3542 |
root |
1.39 |
source directory without having to change even a single line in them, so |
3543 |
|
|
you can easily upgrade by simply copying (or having a checked-out copy of |
3544 |
|
|
libev somewhere in your source tree). |
3545 |
|
|
|
3546 |
|
|
=head2 FILESETS |
3547 |
|
|
|
3548 |
|
|
Depending on what features you need you need to include one or more sets of files |
3549 |
root |
1.161 |
in your application. |
3550 |
root |
1.39 |
|
3551 |
|
|
=head3 CORE EVENT LOOP |
3552 |
|
|
|
3553 |
|
|
To include only the libev core (all the C<ev_*> functions), with manual |
3554 |
|
|
configuration (no autoconf): |
3555 |
|
|
|
3556 |
root |
1.164 |
#define EV_STANDALONE 1 |
3557 |
|
|
#include "ev.c" |
3558 |
root |
1.39 |
|
3559 |
|
|
This will automatically include F<ev.h>, too, and should be done in a |
3560 |
|
|
single C source file only to provide the function implementations. To use |
3561 |
|
|
it, do the same for F<ev.h> in all files wishing to use this API (best |
3562 |
|
|
done by writing a wrapper around F<ev.h> that you can include instead and |
3563 |
|
|
where you can put other configuration options): |
3564 |
|
|
|
3565 |
root |
1.164 |
#define EV_STANDALONE 1 |
3566 |
|
|
#include "ev.h" |
3567 |
root |
1.39 |
|
3568 |
|
|
Both header files and implementation files can be compiled with a C++ |
3569 |
root |
1.208 |
compiler (at least, that's a stated goal, and breakage will be treated |
3570 |
root |
1.39 |
as a bug). |
3571 |
|
|
|
3572 |
|
|
You need the following files in your source tree, or in a directory |
3573 |
|
|
in your include path (e.g. in libev/ when using -Ilibev): |
3574 |
|
|
|
3575 |
root |
1.164 |
ev.h |
3576 |
|
|
ev.c |
3577 |
|
|
ev_vars.h |
3578 |
|
|
ev_wrap.h |
3579 |
|
|
|
3580 |
|
|
ev_win32.c required on win32 platforms only |
3581 |
|
|
|
3582 |
|
|
ev_select.c only when select backend is enabled (which is enabled by default) |
3583 |
|
|
ev_poll.c only when poll backend is enabled (disabled by default) |
3584 |
|
|
ev_epoll.c only when the epoll backend is enabled (disabled by default) |
3585 |
|
|
ev_kqueue.c only when the kqueue backend is enabled (disabled by default) |
3586 |
|
|
ev_port.c only when the solaris port backend is enabled (disabled by default) |
3587 |
root |
1.39 |
|
3588 |
|
|
F<ev.c> includes the backend files directly when enabled, so you only need |
3589 |
root |
1.43 |
to compile this single file. |
3590 |
root |
1.39 |
|
3591 |
|
|
=head3 LIBEVENT COMPATIBILITY API |
3592 |
|
|
|
3593 |
|
|
To include the libevent compatibility API, also include: |
3594 |
|
|
|
3595 |
root |
1.164 |
#include "event.c" |
3596 |
root |
1.39 |
|
3597 |
|
|
in the file including F<ev.c>, and: |
3598 |
|
|
|
3599 |
root |
1.164 |
#include "event.h" |
3600 |
root |
1.39 |
|
3601 |
|
|
in the files that want to use the libevent API. This also includes F<ev.h>. |
3602 |
|
|
|
3603 |
|
|
You need the following additional files for this: |
3604 |
|
|
|
3605 |
root |
1.164 |
event.h |
3606 |
|
|
event.c |
3607 |
root |
1.39 |
|
3608 |
|
|
=head3 AUTOCONF SUPPORT |
3609 |
|
|
|
3610 |
root |
1.161 |
Instead of using C<EV_STANDALONE=1> and providing your configuration in |
3611 |
root |
1.39 |
whatever way you want, you can also C<m4_include([libev.m4])> in your |
3612 |
root |
1.43 |
F<configure.ac> and leave C<EV_STANDALONE> undefined. F<ev.c> will then |
3613 |
|
|
include F<config.h> and configure itself accordingly. |
3614 |
root |
1.39 |
|
3615 |
|
|
For this of course you need the m4 file: |
3616 |
|
|
|
3617 |
root |
1.164 |
libev.m4 |
3618 |
root |
1.39 |
|
3619 |
|
|
=head2 PREPROCESSOR SYMBOLS/MACROS |
3620 |
|
|
|
3621 |
root |
1.142 |
Libev can be configured via a variety of preprocessor symbols you have to |
3622 |
root |
1.161 |
define before including any of its files. The default in the absence of |
3623 |
root |
1.184 |
autoconf is documented for every option. |
3624 |
root |
1.39 |
|
3625 |
|
|
=over 4 |
3626 |
|
|
|
3627 |
|
|
=item EV_STANDALONE |
3628 |
|
|
|
3629 |
|
|
Must always be C<1> if you do not use autoconf configuration, which |
3630 |
|
|
keeps libev from including F<config.h>, and it also defines dummy |
3631 |
|
|
implementations for some libevent functions (such as logging, which is not |
3632 |
|
|
supported). It will also not define any of the structs usually found in |
3633 |
|
|
F<event.h> that are not directly supported by the libev core alone. |
3634 |
|
|
|
3635 |
root |
1.262 |
In standalone mode, libev will still try to automatically deduce the |
3636 |
root |
1.218 |
configuration, but has to be more conservative. |
3637 |
|
|
|
3638 |
root |
1.39 |
=item EV_USE_MONOTONIC |
3639 |
|
|
|
3640 |
|
|
If defined to be C<1>, libev will try to detect the availability of the |
3641 |
root |
1.218 |
monotonic clock option at both compile time and runtime. Otherwise no |
3642 |
|
|
use of the monotonic clock option will be attempted. If you enable this, |
3643 |
|
|
you usually have to link against librt or something similar. Enabling it |
3644 |
|
|
when the functionality isn't available is safe, though, although you have |
3645 |
root |
1.39 |
to make sure you link against any libraries where the C<clock_gettime> |
3646 |
root |
1.218 |
function is hiding in (often F<-lrt>). See also C<EV_USE_CLOCK_SYSCALL>. |
3647 |
root |
1.39 |
|
3648 |
|
|
=item EV_USE_REALTIME |
3649 |
|
|
|
3650 |
|
|
If defined to be C<1>, libev will try to detect the availability of the |
3651 |
root |
1.224 |
real-time clock option at compile time (and assume its availability |
3652 |
|
|
at runtime if successful). Otherwise no use of the real-time clock |
3653 |
|
|
option will be attempted. This effectively replaces C<gettimeofday> |
3654 |
|
|
by C<clock_get (CLOCK_REALTIME, ...)> and will not normally affect |
3655 |
|
|
correctness. See the note about libraries in the description of |
3656 |
|
|
C<EV_USE_MONOTONIC>, though. Defaults to the opposite value of |
3657 |
|
|
C<EV_USE_CLOCK_SYSCALL>. |
3658 |
root |
1.39 |
|
3659 |
root |
1.218 |
=item EV_USE_CLOCK_SYSCALL |
3660 |
|
|
|
3661 |
|
|
If defined to be C<1>, libev will try to use a direct syscall instead |
3662 |
|
|
of calling the system-provided C<clock_gettime> function. This option |
3663 |
|
|
exists because on GNU/Linux, C<clock_gettime> is in C<librt>, but C<librt> |
3664 |
|
|
unconditionally pulls in C<libpthread>, slowing down single-threaded |
3665 |
root |
1.219 |
programs needlessly. Using a direct syscall is slightly slower (in |
3666 |
|
|
theory), because no optimised vdso implementation can be used, but avoids |
3667 |
|
|
the pthread dependency. Defaults to C<1> on GNU/Linux with glibc 2.x or |
3668 |
|
|
higher, as it simplifies linking (no need for C<-lrt>). |
3669 |
root |
1.218 |
|
3670 |
root |
1.97 |
=item EV_USE_NANOSLEEP |
3671 |
|
|
|
3672 |
|
|
If defined to be C<1>, libev will assume that C<nanosleep ()> is available |
3673 |
|
|
and will use it for delays. Otherwise it will use C<select ()>. |
3674 |
|
|
|
3675 |
root |
1.142 |
=item EV_USE_EVENTFD |
3676 |
|
|
|
3677 |
|
|
If defined to be C<1>, then libev will assume that C<eventfd ()> is |
3678 |
|
|
available and will probe for kernel support at runtime. This will improve |
3679 |
|
|
C<ev_signal> and C<ev_async> performance and reduce resource consumption. |
3680 |
|
|
If undefined, it will be enabled if the headers indicate GNU/Linux + Glibc |
3681 |
|
|
2.7 or newer, otherwise disabled. |
3682 |
|
|
|
3683 |
root |
1.39 |
=item EV_USE_SELECT |
3684 |
|
|
|
3685 |
|
|
If undefined or defined to be C<1>, libev will compile in support for the |
3686 |
root |
1.161 |
C<select>(2) backend. No attempt at auto-detection will be done: if no |
3687 |
root |
1.39 |
other method takes over, select will be it. Otherwise the select backend |
3688 |
|
|
will not be compiled in. |
3689 |
|
|
|
3690 |
|
|
=item EV_SELECT_USE_FD_SET |
3691 |
|
|
|
3692 |
|
|
If defined to C<1>, then the select backend will use the system C<fd_set> |
3693 |
|
|
structure. This is useful if libev doesn't compile due to a missing |
3694 |
root |
1.218 |
C<NFDBITS> or C<fd_mask> definition or it mis-guesses the bitset layout |
3695 |
|
|
on exotic systems. This usually limits the range of file descriptors to |
3696 |
|
|
some low limit such as 1024 or might have other limitations (winsocket |
3697 |
|
|
only allows 64 sockets). The C<FD_SETSIZE> macro, set before compilation, |
3698 |
|
|
configures the maximum size of the C<fd_set>. |
3699 |
root |
1.39 |
|
3700 |
|
|
=item EV_SELECT_IS_WINSOCKET |
3701 |
|
|
|
3702 |
|
|
When defined to C<1>, the select backend will assume that |
3703 |
|
|
select/socket/connect etc. don't understand file descriptors but |
3704 |
|
|
wants osf handles on win32 (this is the case when the select to |
3705 |
|
|
be used is the winsock select). This means that it will call |
3706 |
|
|
C<_get_osfhandle> on the fd to convert it to an OS handle. Otherwise, |
3707 |
|
|
it is assumed that all these functions actually work on fds, even |
3708 |
|
|
on win32. Should not be defined on non-win32 platforms. |
3709 |
|
|
|
3710 |
root |
1.264 |
=item EV_FD_TO_WIN32_HANDLE(fd) |
3711 |
root |
1.112 |
|
3712 |
|
|
If C<EV_SELECT_IS_WINSOCKET> is enabled, then libev needs a way to map |
3713 |
|
|
file descriptors to socket handles. When not defining this symbol (the |
3714 |
|
|
default), then libev will call C<_get_osfhandle>, which is usually |
3715 |
|
|
correct. In some cases, programs use their own file descriptor management, |
3716 |
|
|
in which case they can provide this function to map fds to socket handles. |
3717 |
|
|
|
3718 |
root |
1.264 |
=item EV_WIN32_HANDLE_TO_FD(handle) |
3719 |
|
|
|
3720 |
|
|
If C<EV_SELECT_IS_WINSOCKET> then libev maps handles to file descriptors |
3721 |
|
|
using the standard C<_open_osfhandle> function. For programs implementing |
3722 |
|
|
their own fd to handle mapping, overwriting this function makes it easier |
3723 |
|
|
to do so. This can be done by defining this macro to an appropriate value. |
3724 |
|
|
|
3725 |
|
|
=item EV_WIN32_CLOSE_FD(fd) |
3726 |
|
|
|
3727 |
|
|
If programs implement their own fd to handle mapping on win32, then this |
3728 |
|
|
macro can be used to override the C<close> function, useful to unregister |
3729 |
|
|
file descriptors again. Note that the replacement function has to close |
3730 |
|
|
the underlying OS handle. |
3731 |
|
|
|
3732 |
root |
1.39 |
=item EV_USE_POLL |
3733 |
|
|
|
3734 |
|
|
If defined to be C<1>, libev will compile in support for the C<poll>(2) |
3735 |
|
|
backend. Otherwise it will be enabled on non-win32 platforms. It |
3736 |
|
|
takes precedence over select. |
3737 |
|
|
|
3738 |
|
|
=item EV_USE_EPOLL |
3739 |
|
|
|
3740 |
|
|
If defined to be C<1>, libev will compile in support for the Linux |
3741 |
|
|
C<epoll>(7) backend. Its availability will be detected at runtime, |
3742 |
root |
1.142 |
otherwise another method will be used as fallback. This is the preferred |
3743 |
|
|
backend for GNU/Linux systems. If undefined, it will be enabled if the |
3744 |
|
|
headers indicate GNU/Linux + Glibc 2.4 or newer, otherwise disabled. |
3745 |
root |
1.39 |
|
3746 |
|
|
=item EV_USE_KQUEUE |
3747 |
|
|
|
3748 |
|
|
If defined to be C<1>, libev will compile in support for the BSD style |
3749 |
|
|
C<kqueue>(2) backend. Its actual availability will be detected at runtime, |
3750 |
|
|
otherwise another method will be used as fallback. This is the preferred |
3751 |
|
|
backend for BSD and BSD-like systems, although on most BSDs kqueue only |
3752 |
|
|
supports some types of fds correctly (the only platform we found that |
3753 |
|
|
supports ptys for example was NetBSD), so kqueue might be compiled in, but |
3754 |
|
|
not be used unless explicitly requested. The best way to use it is to find |
3755 |
root |
1.41 |
out whether kqueue supports your type of fd properly and use an embedded |
3756 |
root |
1.39 |
kqueue loop. |
3757 |
|
|
|
3758 |
|
|
=item EV_USE_PORT |
3759 |
|
|
|
3760 |
|
|
If defined to be C<1>, libev will compile in support for the Solaris |
3761 |
|
|
10 port style backend. Its availability will be detected at runtime, |
3762 |
|
|
otherwise another method will be used as fallback. This is the preferred |
3763 |
|
|
backend for Solaris 10 systems. |
3764 |
|
|
|
3765 |
|
|
=item EV_USE_DEVPOLL |
3766 |
|
|
|
3767 |
root |
1.161 |
Reserved for future expansion, works like the USE symbols above. |
3768 |
root |
1.39 |
|
3769 |
root |
1.56 |
=item EV_USE_INOTIFY |
3770 |
|
|
|
3771 |
|
|
If defined to be C<1>, libev will compile in support for the Linux inotify |
3772 |
|
|
interface to speed up C<ev_stat> watchers. Its actual availability will |
3773 |
root |
1.142 |
be detected at runtime. If undefined, it will be enabled if the headers |
3774 |
|
|
indicate GNU/Linux + Glibc 2.4 or newer, otherwise disabled. |
3775 |
root |
1.56 |
|
3776 |
root |
1.123 |
=item EV_ATOMIC_T |
3777 |
|
|
|
3778 |
|
|
Libev requires an integer type (suitable for storing C<0> or C<1>) whose |
3779 |
root |
1.126 |
access is atomic with respect to other threads or signal contexts. No such |
3780 |
|
|
type is easily found in the C language, so you can provide your own type |
3781 |
root |
1.127 |
that you know is safe for your purposes. It is used both for signal handler "locking" |
3782 |
|
|
as well as for signal and thread safety in C<ev_async> watchers. |
3783 |
root |
1.123 |
|
3784 |
root |
1.161 |
In the absence of this define, libev will use C<sig_atomic_t volatile> |
3785 |
root |
1.126 |
(from F<signal.h>), which is usually good enough on most platforms. |
3786 |
root |
1.123 |
|
3787 |
root |
1.39 |
=item EV_H |
3788 |
|
|
|
3789 |
|
|
The name of the F<ev.h> header file used to include it. The default if |
3790 |
root |
1.118 |
undefined is C<"ev.h"> in F<event.h>, F<ev.c> and F<ev++.h>. This can be |
3791 |
|
|
used to virtually rename the F<ev.h> header file in case of conflicts. |
3792 |
root |
1.39 |
|
3793 |
|
|
=item EV_CONFIG_H |
3794 |
|
|
|
3795 |
|
|
If C<EV_STANDALONE> isn't C<1>, this variable can be used to override |
3796 |
|
|
F<ev.c>'s idea of where to find the F<config.h> file, similarly to |
3797 |
|
|
C<EV_H>, above. |
3798 |
|
|
|
3799 |
|
|
=item EV_EVENT_H |
3800 |
|
|
|
3801 |
|
|
Similarly to C<EV_H>, this macro can be used to override F<event.c>'s idea |
3802 |
root |
1.118 |
of how the F<event.h> header can be found, the default is C<"event.h">. |
3803 |
root |
1.39 |
|
3804 |
|
|
=item EV_PROTOTYPES |
3805 |
|
|
|
3806 |
|
|
If defined to be C<0>, then F<ev.h> will not define any function |
3807 |
|
|
prototypes, but still define all the structs and other symbols. This is |
3808 |
|
|
occasionally useful if you want to provide your own wrapper functions |
3809 |
|
|
around libev functions. |
3810 |
|
|
|
3811 |
|
|
=item EV_MULTIPLICITY |
3812 |
|
|
|
3813 |
|
|
If undefined or defined to C<1>, then all event-loop-specific functions |
3814 |
|
|
will have the C<struct ev_loop *> as first argument, and you can create |
3815 |
|
|
additional independent event loops. Otherwise there will be no support |
3816 |
|
|
for multiple event loops and there is no first event loop pointer |
3817 |
|
|
argument. Instead, all functions act on the single default loop. |
3818 |
|
|
|
3819 |
root |
1.69 |
=item EV_MINPRI |
3820 |
|
|
|
3821 |
|
|
=item EV_MAXPRI |
3822 |
|
|
|
3823 |
|
|
The range of allowed priorities. C<EV_MINPRI> must be smaller or equal to |
3824 |
|
|
C<EV_MAXPRI>, but otherwise there are no non-obvious limitations. You can |
3825 |
|
|
provide for more priorities by overriding those symbols (usually defined |
3826 |
|
|
to be C<-2> and C<2>, respectively). |
3827 |
|
|
|
3828 |
|
|
When doing priority-based operations, libev usually has to linearly search |
3829 |
|
|
all the priorities, so having many of them (hundreds) uses a lot of space |
3830 |
|
|
and time, so using the defaults of five priorities (-2 .. +2) is usually |
3831 |
|
|
fine. |
3832 |
|
|
|
3833 |
root |
1.184 |
If your embedding application does not need any priorities, defining these |
3834 |
|
|
both to C<0> will save some memory and CPU. |
3835 |
root |
1.69 |
|
3836 |
root |
1.47 |
=item EV_PERIODIC_ENABLE |
3837 |
root |
1.39 |
|
3838 |
root |
1.47 |
If undefined or defined to be C<1>, then periodic timers are supported. If |
3839 |
|
|
defined to be C<0>, then they are not. Disabling them saves a few kB of |
3840 |
|
|
code. |
3841 |
|
|
|
3842 |
root |
1.67 |
=item EV_IDLE_ENABLE |
3843 |
|
|
|
3844 |
|
|
If undefined or defined to be C<1>, then idle watchers are supported. If |
3845 |
|
|
defined to be C<0>, then they are not. Disabling them saves a few kB of |
3846 |
|
|
code. |
3847 |
|
|
|
3848 |
root |
1.47 |
=item EV_EMBED_ENABLE |
3849 |
|
|
|
3850 |
|
|
If undefined or defined to be C<1>, then embed watchers are supported. If |
3851 |
root |
1.184 |
defined to be C<0>, then they are not. Embed watchers rely on most other |
3852 |
|
|
watcher types, which therefore must not be disabled. |
3853 |
root |
1.47 |
|
3854 |
|
|
=item EV_STAT_ENABLE |
3855 |
|
|
|
3856 |
|
|
If undefined or defined to be C<1>, then stat watchers are supported. If |
3857 |
|
|
defined to be C<0>, then they are not. |
3858 |
|
|
|
3859 |
root |
1.50 |
=item EV_FORK_ENABLE |
3860 |
|
|
|
3861 |
|
|
If undefined or defined to be C<1>, then fork watchers are supported. If |
3862 |
|
|
defined to be C<0>, then they are not. |
3863 |
|
|
|
3864 |
root |
1.123 |
=item EV_ASYNC_ENABLE |
3865 |
|
|
|
3866 |
|
|
If undefined or defined to be C<1>, then async watchers are supported. If |
3867 |
|
|
defined to be C<0>, then they are not. |
3868 |
|
|
|
3869 |
root |
1.47 |
=item EV_MINIMAL |
3870 |
|
|
|
3871 |
|
|
If you need to shave off some kilobytes of code at the expense of some |
3872 |
root |
1.250 |
speed (but with the full API), define this symbol to C<1>. Currently this |
3873 |
|
|
is used to override some inlining decisions, saves roughly 30% code size |
3874 |
|
|
on amd64. It also selects a much smaller 2-heap for timer management over |
3875 |
|
|
the default 4-heap. |
3876 |
|
|
|
3877 |
root |
1.252 |
You can save even more by disabling watcher types you do not need |
3878 |
|
|
and setting C<EV_MAXPRI> == C<EV_MINPRI>. Also, disabling C<assert> |
3879 |
|
|
(C<-DNDEBUG>) will usually reduce code size a lot. |
3880 |
root |
1.39 |
|
3881 |
root |
1.251 |
Defining C<EV_MINIMAL> to C<2> will additionally reduce the core API to |
3882 |
|
|
provide a bare-bones event library. See C<ev.h> for details on what parts |
3883 |
|
|
of the API are still available, and do not complain if this subset changes |
3884 |
|
|
over time. |
3885 |
|
|
|
3886 |
root |
1.260 |
=item EV_NSIG |
3887 |
|
|
|
3888 |
|
|
The highest supported signal number, +1 (or, the number of |
3889 |
|
|
signals): Normally, libev tries to deduce the maximum number of signals |
3890 |
|
|
automatically, but sometimes this fails, in which case it can be |
3891 |
|
|
specified. Also, using a lower number than detected (C<32> should be |
3892 |
|
|
good for about any system in existance) can save some memory, as libev |
3893 |
|
|
statically allocates some 12-24 bytes per signal number. |
3894 |
|
|
|
3895 |
root |
1.51 |
=item EV_PID_HASHSIZE |
3896 |
|
|
|
3897 |
|
|
C<ev_child> watchers use a small hash table to distribute workload by |
3898 |
|
|
pid. The default size is C<16> (or C<1> with C<EV_MINIMAL>), usually more |
3899 |
|
|
than enough. If you need to manage thousands of children you might want to |
3900 |
root |
1.56 |
increase this value (I<must> be a power of two). |
3901 |
|
|
|
3902 |
|
|
=item EV_INOTIFY_HASHSIZE |
3903 |
|
|
|
3904 |
root |
1.104 |
C<ev_stat> watchers use a small hash table to distribute workload by |
3905 |
root |
1.56 |
inotify watch id. The default size is C<16> (or C<1> with C<EV_MINIMAL>), |
3906 |
|
|
usually more than enough. If you need to manage thousands of C<ev_stat> |
3907 |
|
|
watchers you might want to increase this value (I<must> be a power of |
3908 |
|
|
two). |
3909 |
root |
1.51 |
|
3910 |
root |
1.153 |
=item EV_USE_4HEAP |
3911 |
|
|
|
3912 |
|
|
Heaps are not very cache-efficient. To improve the cache-efficiency of the |
3913 |
root |
1.184 |
timer and periodics heaps, libev uses a 4-heap when this symbol is defined |
3914 |
|
|
to C<1>. The 4-heap uses more complicated (longer) code but has noticeably |
3915 |
|
|
faster performance with many (thousands) of watchers. |
3916 |
root |
1.153 |
|
3917 |
|
|
The default is C<1> unless C<EV_MINIMAL> is set in which case it is C<0> |
3918 |
|
|
(disabled). |
3919 |
|
|
|
3920 |
|
|
=item EV_HEAP_CACHE_AT |
3921 |
|
|
|
3922 |
|
|
Heaps are not very cache-efficient. To improve the cache-efficiency of the |
3923 |
root |
1.184 |
timer and periodics heaps, libev can cache the timestamp (I<at>) within |
3924 |
root |
1.153 |
the heap structure (selected by defining C<EV_HEAP_CACHE_AT> to C<1>), |
3925 |
|
|
which uses 8-12 bytes more per watcher and a few hundred bytes more code, |
3926 |
root |
1.155 |
but avoids random read accesses on heap changes. This improves performance |
3927 |
root |
1.184 |
noticeably with many (hundreds) of watchers. |
3928 |
root |
1.153 |
|
3929 |
|
|
The default is C<1> unless C<EV_MINIMAL> is set in which case it is C<0> |
3930 |
|
|
(disabled). |
3931 |
|
|
|
3932 |
root |
1.159 |
=item EV_VERIFY |
3933 |
|
|
|
3934 |
|
|
Controls how much internal verification (see C<ev_loop_verify ()>) will |
3935 |
|
|
be done: If set to C<0>, no internal verification code will be compiled |
3936 |
|
|
in. If set to C<1>, then verification code will be compiled in, but not |
3937 |
|
|
called. If set to C<2>, then the internal verification code will be |
3938 |
|
|
called once per loop, which can slow down libev. If set to C<3>, then the |
3939 |
|
|
verification code will be called very frequently, which will slow down |
3940 |
|
|
libev considerably. |
3941 |
|
|
|
3942 |
|
|
The default is C<1>, unless C<EV_MINIMAL> is set, in which case it will be |
3943 |
root |
1.184 |
C<0>. |
3944 |
root |
1.159 |
|
3945 |
root |
1.39 |
=item EV_COMMON |
3946 |
|
|
|
3947 |
|
|
By default, all watchers have a C<void *data> member. By redefining |
3948 |
|
|
this macro to a something else you can include more and other types of |
3949 |
|
|
members. You have to define it each time you include one of the files, |
3950 |
|
|
though, and it must be identical each time. |
3951 |
|
|
|
3952 |
|
|
For example, the perl EV module uses something like this: |
3953 |
|
|
|
3954 |
root |
1.164 |
#define EV_COMMON \ |
3955 |
|
|
SV *self; /* contains this struct */ \ |
3956 |
|
|
SV *cb_sv, *fh /* note no trailing ";" */ |
3957 |
root |
1.39 |
|
3958 |
root |
1.44 |
=item EV_CB_DECLARE (type) |
3959 |
root |
1.39 |
|
3960 |
root |
1.44 |
=item EV_CB_INVOKE (watcher, revents) |
3961 |
root |
1.39 |
|
3962 |
root |
1.44 |
=item ev_set_cb (ev, cb) |
3963 |
root |
1.39 |
|
3964 |
|
|
Can be used to change the callback member declaration in each watcher, |
3965 |
|
|
and the way callbacks are invoked and set. Must expand to a struct member |
3966 |
root |
1.93 |
definition and a statement, respectively. See the F<ev.h> header file for |
3967 |
root |
1.39 |
their default definitions. One possible use for overriding these is to |
3968 |
root |
1.44 |
avoid the C<struct ev_loop *> as first argument in all cases, or to use |
3969 |
|
|
method calls instead of plain function calls in C++. |
3970 |
root |
1.39 |
|
3971 |
root |
1.185 |
=back |
3972 |
|
|
|
3973 |
root |
1.89 |
=head2 EXPORTED API SYMBOLS |
3974 |
|
|
|
3975 |
root |
1.161 |
If you need to re-export the API (e.g. via a DLL) and you need a list of |
3976 |
root |
1.89 |
exported symbols, you can use the provided F<Symbol.*> files which list |
3977 |
|
|
all public symbols, one per line: |
3978 |
|
|
|
3979 |
root |
1.164 |
Symbols.ev for libev proper |
3980 |
|
|
Symbols.event for the libevent emulation |
3981 |
root |
1.89 |
|
3982 |
|
|
This can also be used to rename all public symbols to avoid clashes with |
3983 |
|
|
multiple versions of libev linked together (which is obviously bad in |
3984 |
root |
1.161 |
itself, but sometimes it is inconvenient to avoid this). |
3985 |
root |
1.89 |
|
3986 |
root |
1.92 |
A sed command like this will create wrapper C<#define>'s that you need to |
3987 |
root |
1.89 |
include before including F<ev.h>: |
3988 |
|
|
|
3989 |
|
|
<Symbols.ev sed -e "s/.*/#define & myprefix_&/" >wrap.h |
3990 |
|
|
|
3991 |
|
|
This would create a file F<wrap.h> which essentially looks like this: |
3992 |
|
|
|
3993 |
|
|
#define ev_backend myprefix_ev_backend |
3994 |
|
|
#define ev_check_start myprefix_ev_check_start |
3995 |
|
|
#define ev_check_stop myprefix_ev_check_stop |
3996 |
|
|
... |
3997 |
|
|
|
3998 |
root |
1.39 |
=head2 EXAMPLES |
3999 |
|
|
|
4000 |
|
|
For a real-world example of a program the includes libev |
4001 |
|
|
verbatim, you can have a look at the EV perl module |
4002 |
|
|
(L<http://software.schmorp.de/pkg/EV.html>). It has the libev files in |
4003 |
|
|
the F<libev/> subdirectory and includes them in the F<EV/EVAPI.h> (public |
4004 |
|
|
interface) and F<EV.xs> (implementation) files. Only the F<EV.xs> file |
4005 |
|
|
will be compiled. It is pretty complex because it provides its own header |
4006 |
|
|
file. |
4007 |
|
|
|
4008 |
|
|
The usage in rxvt-unicode is simpler. It has a F<ev_cpp.h> header file |
4009 |
root |
1.63 |
that everybody includes and which overrides some configure choices: |
4010 |
root |
1.39 |
|
4011 |
root |
1.164 |
#define EV_MINIMAL 1 |
4012 |
|
|
#define EV_USE_POLL 0 |
4013 |
|
|
#define EV_MULTIPLICITY 0 |
4014 |
|
|
#define EV_PERIODIC_ENABLE 0 |
4015 |
|
|
#define EV_STAT_ENABLE 0 |
4016 |
|
|
#define EV_FORK_ENABLE 0 |
4017 |
|
|
#define EV_CONFIG_H <config.h> |
4018 |
|
|
#define EV_MINPRI 0 |
4019 |
|
|
#define EV_MAXPRI 0 |
4020 |
root |
1.39 |
|
4021 |
root |
1.164 |
#include "ev++.h" |
4022 |
root |
1.39 |
|
4023 |
|
|
And a F<ev_cpp.C> implementation file that contains libev proper and is compiled: |
4024 |
|
|
|
4025 |
root |
1.164 |
#include "ev_cpp.h" |
4026 |
|
|
#include "ev.c" |
4027 |
root |
1.39 |
|
4028 |
root |
1.189 |
=head1 INTERACTION WITH OTHER PROGRAMS OR LIBRARIES |
4029 |
root |
1.46 |
|
4030 |
root |
1.189 |
=head2 THREADS AND COROUTINES |
4031 |
root |
1.144 |
|
4032 |
root |
1.189 |
=head3 THREADS |
4033 |
root |
1.144 |
|
4034 |
root |
1.186 |
All libev functions are reentrant and thread-safe unless explicitly |
4035 |
root |
1.191 |
documented otherwise, but libev implements no locking itself. This means |
4036 |
|
|
that you can use as many loops as you want in parallel, as long as there |
4037 |
|
|
are no concurrent calls into any libev function with the same loop |
4038 |
|
|
parameter (C<ev_default_*> calls have an implicit default loop parameter, |
4039 |
|
|
of course): libev guarantees that different event loops share no data |
4040 |
root |
1.186 |
structures that need any locking. |
4041 |
root |
1.180 |
|
4042 |
|
|
Or to put it differently: calls with different loop parameters can be done |
4043 |
|
|
concurrently from multiple threads, calls with the same loop parameter |
4044 |
|
|
must be done serially (but can be done from different threads, as long as |
4045 |
|
|
only one thread ever is inside a call at any point in time, e.g. by using |
4046 |
|
|
a mutex per loop). |
4047 |
|
|
|
4048 |
|
|
Specifically to support threads (and signal handlers), libev implements |
4049 |
|
|
so-called C<ev_async> watchers, which allow some limited form of |
4050 |
root |
1.186 |
concurrency on the same event loop, namely waking it up "from the |
4051 |
|
|
outside". |
4052 |
root |
1.144 |
|
4053 |
root |
1.170 |
If you want to know which design (one loop, locking, or multiple loops |
4054 |
|
|
without or something else still) is best for your problem, then I cannot |
4055 |
root |
1.186 |
help you, but here is some generic advice: |
4056 |
root |
1.144 |
|
4057 |
|
|
=over 4 |
4058 |
|
|
|
4059 |
|
|
=item * most applications have a main thread: use the default libev loop |
4060 |
root |
1.161 |
in that thread, or create a separate thread running only the default loop. |
4061 |
root |
1.144 |
|
4062 |
|
|
This helps integrating other libraries or software modules that use libev |
4063 |
|
|
themselves and don't care/know about threading. |
4064 |
|
|
|
4065 |
|
|
=item * one loop per thread is usually a good model. |
4066 |
|
|
|
4067 |
|
|
Doing this is almost never wrong, sometimes a better-performance model |
4068 |
|
|
exists, but it is always a good start. |
4069 |
|
|
|
4070 |
|
|
=item * other models exist, such as the leader/follower pattern, where one |
4071 |
root |
1.161 |
loop is handed through multiple threads in a kind of round-robin fashion. |
4072 |
root |
1.144 |
|
4073 |
root |
1.161 |
Choosing a model is hard - look around, learn, know that usually you can do |
4074 |
root |
1.144 |
better than you currently do :-) |
4075 |
|
|
|
4076 |
|
|
=item * often you need to talk to some other thread which blocks in the |
4077 |
root |
1.182 |
event loop. |
4078 |
root |
1.144 |
|
4079 |
root |
1.182 |
C<ev_async> watchers can be used to wake them up from other threads safely |
4080 |
|
|
(or from signal contexts...). |
4081 |
|
|
|
4082 |
|
|
An example use would be to communicate signals or other events that only |
4083 |
|
|
work in the default loop by registering the signal watcher with the |
4084 |
|
|
default loop and triggering an C<ev_async> watcher from the default loop |
4085 |
|
|
watcher callback into the event loop interested in the signal. |
4086 |
root |
1.180 |
|
4087 |
root |
1.144 |
=back |
4088 |
|
|
|
4089 |
root |
1.253 |
=head4 THREAD LOCKING EXAMPLE |
4090 |
|
|
|
4091 |
root |
1.254 |
Here is a fictitious example of how to run an event loop in a different |
4092 |
|
|
thread than where callbacks are being invoked and watchers are |
4093 |
|
|
created/added/removed. |
4094 |
|
|
|
4095 |
|
|
For a real-world example, see the C<EV::Loop::Async> perl module, |
4096 |
|
|
which uses exactly this technique (which is suited for many high-level |
4097 |
|
|
languages). |
4098 |
|
|
|
4099 |
|
|
The example uses a pthread mutex to protect the loop data, a condition |
4100 |
|
|
variable to wait for callback invocations, an async watcher to notify the |
4101 |
|
|
event loop thread and an unspecified mechanism to wake up the main thread. |
4102 |
|
|
|
4103 |
|
|
First, you need to associate some data with the event loop: |
4104 |
|
|
|
4105 |
|
|
typedef struct { |
4106 |
|
|
mutex_t lock; /* global loop lock */ |
4107 |
|
|
ev_async async_w; |
4108 |
|
|
thread_t tid; |
4109 |
|
|
cond_t invoke_cv; |
4110 |
|
|
} userdata; |
4111 |
|
|
|
4112 |
|
|
void prepare_loop (EV_P) |
4113 |
|
|
{ |
4114 |
|
|
// for simplicity, we use a static userdata struct. |
4115 |
|
|
static userdata u; |
4116 |
|
|
|
4117 |
|
|
ev_async_init (&u->async_w, async_cb); |
4118 |
|
|
ev_async_start (EV_A_ &u->async_w); |
4119 |
|
|
|
4120 |
|
|
pthread_mutex_init (&u->lock, 0); |
4121 |
|
|
pthread_cond_init (&u->invoke_cv, 0); |
4122 |
|
|
|
4123 |
|
|
// now associate this with the loop |
4124 |
|
|
ev_set_userdata (EV_A_ u); |
4125 |
|
|
ev_set_invoke_pending_cb (EV_A_ l_invoke); |
4126 |
|
|
ev_set_loop_release_cb (EV_A_ l_release, l_acquire); |
4127 |
|
|
|
4128 |
|
|
// then create the thread running ev_loop |
4129 |
|
|
pthread_create (&u->tid, 0, l_run, EV_A); |
4130 |
|
|
} |
4131 |
|
|
|
4132 |
|
|
The callback for the C<ev_async> watcher does nothing: the watcher is used |
4133 |
|
|
solely to wake up the event loop so it takes notice of any new watchers |
4134 |
|
|
that might have been added: |
4135 |
|
|
|
4136 |
|
|
static void |
4137 |
|
|
async_cb (EV_P_ ev_async *w, int revents) |
4138 |
|
|
{ |
4139 |
|
|
// just used for the side effects |
4140 |
|
|
} |
4141 |
|
|
|
4142 |
|
|
The C<l_release> and C<l_acquire> callbacks simply unlock/lock the mutex |
4143 |
|
|
protecting the loop data, respectively. |
4144 |
|
|
|
4145 |
|
|
static void |
4146 |
|
|
l_release (EV_P) |
4147 |
|
|
{ |
4148 |
root |
1.255 |
userdata *u = ev_userdata (EV_A); |
4149 |
root |
1.254 |
pthread_mutex_unlock (&u->lock); |
4150 |
|
|
} |
4151 |
|
|
|
4152 |
|
|
static void |
4153 |
|
|
l_acquire (EV_P) |
4154 |
|
|
{ |
4155 |
root |
1.255 |
userdata *u = ev_userdata (EV_A); |
4156 |
root |
1.254 |
pthread_mutex_lock (&u->lock); |
4157 |
|
|
} |
4158 |
|
|
|
4159 |
|
|
The event loop thread first acquires the mutex, and then jumps straight |
4160 |
|
|
into C<ev_loop>: |
4161 |
|
|
|
4162 |
|
|
void * |
4163 |
|
|
l_run (void *thr_arg) |
4164 |
|
|
{ |
4165 |
|
|
struct ev_loop *loop = (struct ev_loop *)thr_arg; |
4166 |
|
|
|
4167 |
|
|
l_acquire (EV_A); |
4168 |
|
|
pthread_setcanceltype (PTHREAD_CANCEL_ASYNCHRONOUS, 0); |
4169 |
|
|
ev_loop (EV_A_ 0); |
4170 |
|
|
l_release (EV_A); |
4171 |
|
|
|
4172 |
|
|
return 0; |
4173 |
|
|
} |
4174 |
|
|
|
4175 |
|
|
Instead of invoking all pending watchers, the C<l_invoke> callback will |
4176 |
|
|
signal the main thread via some unspecified mechanism (signals? pipe |
4177 |
|
|
writes? C<Async::Interrupt>?) and then waits until all pending watchers |
4178 |
root |
1.256 |
have been called (in a while loop because a) spurious wakeups are possible |
4179 |
|
|
and b) skipping inter-thread-communication when there are no pending |
4180 |
|
|
watchers is very beneficial): |
4181 |
root |
1.254 |
|
4182 |
|
|
static void |
4183 |
|
|
l_invoke (EV_P) |
4184 |
|
|
{ |
4185 |
root |
1.255 |
userdata *u = ev_userdata (EV_A); |
4186 |
root |
1.254 |
|
4187 |
root |
1.256 |
while (ev_pending_count (EV_A)) |
4188 |
|
|
{ |
4189 |
|
|
wake_up_other_thread_in_some_magic_or_not_so_magic_way (); |
4190 |
|
|
pthread_cond_wait (&u->invoke_cv, &u->lock); |
4191 |
|
|
} |
4192 |
root |
1.254 |
} |
4193 |
|
|
|
4194 |
|
|
Now, whenever the main thread gets told to invoke pending watchers, it |
4195 |
|
|
will grab the lock, call C<ev_invoke_pending> and then signal the loop |
4196 |
|
|
thread to continue: |
4197 |
|
|
|
4198 |
|
|
static void |
4199 |
|
|
real_invoke_pending (EV_P) |
4200 |
|
|
{ |
4201 |
root |
1.255 |
userdata *u = ev_userdata (EV_A); |
4202 |
root |
1.254 |
|
4203 |
|
|
pthread_mutex_lock (&u->lock); |
4204 |
|
|
ev_invoke_pending (EV_A); |
4205 |
|
|
pthread_cond_signal (&u->invoke_cv); |
4206 |
|
|
pthread_mutex_unlock (&u->lock); |
4207 |
|
|
} |
4208 |
|
|
|
4209 |
|
|
Whenever you want to start/stop a watcher or do other modifications to an |
4210 |
|
|
event loop, you will now have to lock: |
4211 |
|
|
|
4212 |
|
|
ev_timer timeout_watcher; |
4213 |
root |
1.255 |
userdata *u = ev_userdata (EV_A); |
4214 |
root |
1.254 |
|
4215 |
|
|
ev_timer_init (&timeout_watcher, timeout_cb, 5.5, 0.); |
4216 |
|
|
|
4217 |
|
|
pthread_mutex_lock (&u->lock); |
4218 |
|
|
ev_timer_start (EV_A_ &timeout_watcher); |
4219 |
|
|
ev_async_send (EV_A_ &u->async_w); |
4220 |
|
|
pthread_mutex_unlock (&u->lock); |
4221 |
|
|
|
4222 |
|
|
Note that sending the C<ev_async> watcher is required because otherwise |
4223 |
|
|
an event loop currently blocking in the kernel will have no knowledge |
4224 |
|
|
about the newly added timer. By waking up the loop it will pick up any new |
4225 |
|
|
watchers in the next event loop iteration. |
4226 |
|
|
|
4227 |
root |
1.189 |
=head3 COROUTINES |
4228 |
root |
1.144 |
|
4229 |
root |
1.191 |
Libev is very accommodating to coroutines ("cooperative threads"): |
4230 |
|
|
libev fully supports nesting calls to its functions from different |
4231 |
root |
1.144 |
coroutines (e.g. you can call C<ev_loop> on the same loop from two |
4232 |
root |
1.255 |
different coroutines, and switch freely between both coroutines running |
4233 |
|
|
the loop, as long as you don't confuse yourself). The only exception is |
4234 |
|
|
that you must not do this from C<ev_periodic> reschedule callbacks. |
4235 |
root |
1.144 |
|
4236 |
root |
1.181 |
Care has been taken to ensure that libev does not keep local state inside |
4237 |
root |
1.191 |
C<ev_loop>, and other calls do not usually allow for coroutine switches as |
4238 |
root |
1.208 |
they do not call any callbacks. |
4239 |
root |
1.144 |
|
4240 |
root |
1.189 |
=head2 COMPILER WARNINGS |
4241 |
|
|
|
4242 |
|
|
Depending on your compiler and compiler settings, you might get no or a |
4243 |
|
|
lot of warnings when compiling libev code. Some people are apparently |
4244 |
|
|
scared by this. |
4245 |
|
|
|
4246 |
|
|
However, these are unavoidable for many reasons. For one, each compiler |
4247 |
|
|
has different warnings, and each user has different tastes regarding |
4248 |
|
|
warning options. "Warn-free" code therefore cannot be a goal except when |
4249 |
|
|
targeting a specific compiler and compiler-version. |
4250 |
|
|
|
4251 |
|
|
Another reason is that some compiler warnings require elaborate |
4252 |
|
|
workarounds, or other changes to the code that make it less clear and less |
4253 |
|
|
maintainable. |
4254 |
|
|
|
4255 |
|
|
And of course, some compiler warnings are just plain stupid, or simply |
4256 |
|
|
wrong (because they don't actually warn about the condition their message |
4257 |
|
|
seems to warn about). For example, certain older gcc versions had some |
4258 |
|
|
warnings that resulted an extreme number of false positives. These have |
4259 |
|
|
been fixed, but some people still insist on making code warn-free with |
4260 |
|
|
such buggy versions. |
4261 |
|
|
|
4262 |
|
|
While libev is written to generate as few warnings as possible, |
4263 |
|
|
"warn-free" code is not a goal, and it is recommended not to build libev |
4264 |
|
|
with any compiler warnings enabled unless you are prepared to cope with |
4265 |
|
|
them (e.g. by ignoring them). Remember that warnings are just that: |
4266 |
|
|
warnings, not errors, or proof of bugs. |
4267 |
|
|
|
4268 |
|
|
|
4269 |
root |
1.190 |
=head2 VALGRIND |
4270 |
root |
1.189 |
|
4271 |
|
|
Valgrind has a special section here because it is a popular tool that is |
4272 |
|
|
highly useful. Unfortunately, valgrind reports are very hard to interpret. |
4273 |
|
|
|
4274 |
|
|
If you think you found a bug (memory leak, uninitialised data access etc.) |
4275 |
|
|
in libev, then check twice: If valgrind reports something like: |
4276 |
|
|
|
4277 |
|
|
==2274== definitely lost: 0 bytes in 0 blocks. |
4278 |
|
|
==2274== possibly lost: 0 bytes in 0 blocks. |
4279 |
|
|
==2274== still reachable: 256 bytes in 1 blocks. |
4280 |
|
|
|
4281 |
|
|
Then there is no memory leak, just as memory accounted to global variables |
4282 |
root |
1.208 |
is not a memleak - the memory is still being referenced, and didn't leak. |
4283 |
root |
1.189 |
|
4284 |
|
|
Similarly, under some circumstances, valgrind might report kernel bugs |
4285 |
|
|
as if it were a bug in libev (e.g. in realloc or in the poll backend, |
4286 |
|
|
although an acceptable workaround has been found here), or it might be |
4287 |
|
|
confused. |
4288 |
|
|
|
4289 |
|
|
Keep in mind that valgrind is a very good tool, but only a tool. Don't |
4290 |
|
|
make it into some kind of religion. |
4291 |
|
|
|
4292 |
|
|
If you are unsure about something, feel free to contact the mailing list |
4293 |
|
|
with the full valgrind report and an explanation on why you think this |
4294 |
|
|
is a bug in libev (best check the archives, too :). However, don't be |
4295 |
|
|
annoyed when you get a brisk "this is no bug" answer and take the chance |
4296 |
|
|
of learning how to interpret valgrind properly. |
4297 |
|
|
|
4298 |
|
|
If you need, for some reason, empty reports from valgrind for your project |
4299 |
|
|
I suggest using suppression lists. |
4300 |
|
|
|
4301 |
|
|
|
4302 |
root |
1.190 |
=head1 PORTABILITY NOTES |
4303 |
root |
1.189 |
|
4304 |
|
|
=head2 WIN32 PLATFORM LIMITATIONS AND WORKAROUNDS |
4305 |
root |
1.112 |
|
4306 |
|
|
Win32 doesn't support any of the standards (e.g. POSIX) that libev |
4307 |
|
|
requires, and its I/O model is fundamentally incompatible with the POSIX |
4308 |
|
|
model. Libev still offers limited functionality on this platform in |
4309 |
|
|
the form of the C<EVBACKEND_SELECT> backend, and only supports socket |
4310 |
|
|
descriptors. This only applies when using Win32 natively, not when using |
4311 |
|
|
e.g. cygwin. |
4312 |
|
|
|
4313 |
root |
1.150 |
Lifting these limitations would basically require the full |
4314 |
|
|
re-implementation of the I/O system. If you are into these kinds of |
4315 |
|
|
things, then note that glib does exactly that for you in a very portable |
4316 |
|
|
way (note also that glib is the slowest event library known to man). |
4317 |
|
|
|
4318 |
root |
1.112 |
There is no supported compilation method available on windows except |
4319 |
|
|
embedding it into other applications. |
4320 |
|
|
|
4321 |
root |
1.241 |
Sensible signal handling is officially unsupported by Microsoft - libev |
4322 |
|
|
tries its best, but under most conditions, signals will simply not work. |
4323 |
|
|
|
4324 |
root |
1.162 |
Not a libev limitation but worth mentioning: windows apparently doesn't |
4325 |
|
|
accept large writes: instead of resulting in a partial write, windows will |
4326 |
|
|
either accept everything or return C<ENOBUFS> if the buffer is too large, |
4327 |
|
|
so make sure you only write small amounts into your sockets (less than a |
4328 |
root |
1.184 |
megabyte seems safe, but this apparently depends on the amount of memory |
4329 |
root |
1.162 |
available). |
4330 |
|
|
|
4331 |
root |
1.150 |
Due to the many, low, and arbitrary limits on the win32 platform and |
4332 |
|
|
the abysmal performance of winsockets, using a large number of sockets |
4333 |
|
|
is not recommended (and not reasonable). If your program needs to use |
4334 |
|
|
more than a hundred or so sockets, then likely it needs to use a totally |
4335 |
root |
1.155 |
different implementation for windows, as libev offers the POSIX readiness |
4336 |
root |
1.150 |
notification model, which cannot be implemented efficiently on windows |
4337 |
root |
1.241 |
(due to Microsoft monopoly games). |
4338 |
root |
1.112 |
|
4339 |
root |
1.167 |
A typical way to use libev under windows is to embed it (see the embedding |
4340 |
|
|
section for details) and use the following F<evwrap.h> header file instead |
4341 |
|
|
of F<ev.h>: |
4342 |
|
|
|
4343 |
|
|
#define EV_STANDALONE /* keeps ev from requiring config.h */ |
4344 |
|
|
#define EV_SELECT_IS_WINSOCKET 1 /* configure libev for windows select */ |
4345 |
|
|
|
4346 |
|
|
#include "ev.h" |
4347 |
|
|
|
4348 |
|
|
And compile the following F<evwrap.c> file into your project (make sure |
4349 |
root |
1.184 |
you do I<not> compile the F<ev.c> or any other embedded source files!): |
4350 |
root |
1.167 |
|
4351 |
|
|
#include "evwrap.h" |
4352 |
|
|
#include "ev.c" |
4353 |
|
|
|
4354 |
root |
1.112 |
=over 4 |
4355 |
|
|
|
4356 |
|
|
=item The winsocket select function |
4357 |
|
|
|
4358 |
root |
1.160 |
The winsocket C<select> function doesn't follow POSIX in that it |
4359 |
|
|
requires socket I<handles> and not socket I<file descriptors> (it is |
4360 |
|
|
also extremely buggy). This makes select very inefficient, and also |
4361 |
root |
1.167 |
requires a mapping from file descriptors to socket handles (the Microsoft |
4362 |
|
|
C runtime provides the function C<_open_osfhandle> for this). See the |
4363 |
root |
1.160 |
discussion of the C<EV_SELECT_USE_FD_SET>, C<EV_SELECT_IS_WINSOCKET> and |
4364 |
|
|
C<EV_FD_TO_WIN32_HANDLE> preprocessor symbols for more info. |
4365 |
root |
1.112 |
|
4366 |
root |
1.161 |
The configuration for a "naked" win32 using the Microsoft runtime |
4367 |
root |
1.112 |
libraries and raw winsocket select is: |
4368 |
|
|
|
4369 |
root |
1.164 |
#define EV_USE_SELECT 1 |
4370 |
|
|
#define EV_SELECT_IS_WINSOCKET 1 /* forces EV_SELECT_USE_FD_SET, too */ |
4371 |
root |
1.112 |
|
4372 |
|
|
Note that winsockets handling of fd sets is O(n), so you can easily get a |
4373 |
|
|
complexity in the O(n²) range when using win32. |
4374 |
|
|
|
4375 |
|
|
=item Limited number of file descriptors |
4376 |
|
|
|
4377 |
root |
1.150 |
Windows has numerous arbitrary (and low) limits on things. |
4378 |
|
|
|
4379 |
|
|
Early versions of winsocket's select only supported waiting for a maximum |
4380 |
|
|
of C<64> handles (probably owning to the fact that all windows kernels |
4381 |
root |
1.161 |
can only wait for C<64> things at the same time internally; Microsoft |
4382 |
root |
1.150 |
recommends spawning a chain of threads and wait for 63 handles and the |
4383 |
root |
1.241 |
previous thread in each. Sounds great!). |
4384 |
root |
1.112 |
|
4385 |
|
|
Newer versions support more handles, but you need to define C<FD_SETSIZE> |
4386 |
|
|
to some high number (e.g. C<2048>) before compiling the winsocket select |
4387 |
root |
1.241 |
call (which might be in libev or elsewhere, for example, perl and many |
4388 |
|
|
other interpreters do their own select emulation on windows). |
4389 |
root |
1.112 |
|
4390 |
root |
1.161 |
Another limit is the number of file descriptors in the Microsoft runtime |
4391 |
root |
1.241 |
libraries, which by default is C<64> (there must be a hidden I<64> |
4392 |
|
|
fetish or something like this inside Microsoft). You can increase this |
4393 |
|
|
by calling C<_setmaxstdio>, which can increase this limit to C<2048> |
4394 |
|
|
(another arbitrary limit), but is broken in many versions of the Microsoft |
4395 |
|
|
runtime libraries. This might get you to about C<512> or C<2048> sockets |
4396 |
|
|
(depending on windows version and/or the phase of the moon). To get more, |
4397 |
|
|
you need to wrap all I/O functions and provide your own fd management, but |
4398 |
|
|
the cost of calling select (O(n²)) will likely make this unworkable. |
4399 |
root |
1.112 |
|
4400 |
|
|
=back |
4401 |
|
|
|
4402 |
root |
1.189 |
=head2 PORTABILITY REQUIREMENTS |
4403 |
root |
1.112 |
|
4404 |
root |
1.189 |
In addition to a working ISO-C implementation and of course the |
4405 |
|
|
backend-specific APIs, libev relies on a few additional extensions: |
4406 |
root |
1.148 |
|
4407 |
|
|
=over 4 |
4408 |
|
|
|
4409 |
root |
1.165 |
=item C<void (*)(ev_watcher_type *, int revents)> must have compatible |
4410 |
|
|
calling conventions regardless of C<ev_watcher_type *>. |
4411 |
|
|
|
4412 |
|
|
Libev assumes not only that all watcher pointers have the same internal |
4413 |
|
|
structure (guaranteed by POSIX but not by ISO C for example), but it also |
4414 |
|
|
assumes that the same (machine) code can be used to call any watcher |
4415 |
|
|
callback: The watcher callbacks have different type signatures, but libev |
4416 |
|
|
calls them using an C<ev_watcher *> internally. |
4417 |
|
|
|
4418 |
root |
1.148 |
=item C<sig_atomic_t volatile> must be thread-atomic as well |
4419 |
|
|
|
4420 |
|
|
The type C<sig_atomic_t volatile> (or whatever is defined as |
4421 |
root |
1.184 |
C<EV_ATOMIC_T>) must be atomic with respect to accesses from different |
4422 |
root |
1.148 |
threads. This is not part of the specification for C<sig_atomic_t>, but is |
4423 |
|
|
believed to be sufficiently portable. |
4424 |
|
|
|
4425 |
|
|
=item C<sigprocmask> must work in a threaded environment |
4426 |
|
|
|
4427 |
|
|
Libev uses C<sigprocmask> to temporarily block signals. This is not |
4428 |
|
|
allowed in a threaded program (C<pthread_sigmask> has to be used). Typical |
4429 |
|
|
pthread implementations will either allow C<sigprocmask> in the "main |
4430 |
|
|
thread" or will block signals process-wide, both behaviours would |
4431 |
|
|
be compatible with libev. Interaction between C<sigprocmask> and |
4432 |
|
|
C<pthread_sigmask> could complicate things, however. |
4433 |
|
|
|
4434 |
|
|
The most portable way to handle signals is to block signals in all threads |
4435 |
|
|
except the initial one, and run the default loop in the initial thread as |
4436 |
|
|
well. |
4437 |
|
|
|
4438 |
root |
1.150 |
=item C<long> must be large enough for common memory allocation sizes |
4439 |
|
|
|
4440 |
root |
1.189 |
To improve portability and simplify its API, libev uses C<long> internally |
4441 |
|
|
instead of C<size_t> when allocating its data structures. On non-POSIX |
4442 |
|
|
systems (Microsoft...) this might be unexpectedly low, but is still at |
4443 |
|
|
least 31 bits everywhere, which is enough for hundreds of millions of |
4444 |
|
|
watchers. |
4445 |
root |
1.150 |
|
4446 |
|
|
=item C<double> must hold a time value in seconds with enough accuracy |
4447 |
|
|
|
4448 |
root |
1.151 |
The type C<double> is used to represent timestamps. It is required to |
4449 |
|
|
have at least 51 bits of mantissa (and 9 bits of exponent), which is good |
4450 |
|
|
enough for at least into the year 4000. This requirement is fulfilled by |
4451 |
root |
1.246 |
implementations implementing IEEE 754, which is basically all existing |
4452 |
|
|
ones. With IEEE 754 doubles, you get microsecond accuracy until at least |
4453 |
|
|
2200. |
4454 |
root |
1.150 |
|
4455 |
root |
1.148 |
=back |
4456 |
|
|
|
4457 |
|
|
If you know of other additional requirements drop me a note. |
4458 |
|
|
|
4459 |
|
|
|
4460 |
root |
1.191 |
=head1 ALGORITHMIC COMPLEXITIES |
4461 |
|
|
|
4462 |
|
|
In this section the complexities of (many of) the algorithms used inside |
4463 |
|
|
libev will be documented. For complexity discussions about backends see |
4464 |
|
|
the documentation for C<ev_default_init>. |
4465 |
|
|
|
4466 |
|
|
All of the following are about amortised time: If an array needs to be |
4467 |
|
|
extended, libev needs to realloc and move the whole array, but this |
4468 |
|
|
happens asymptotically rarer with higher number of elements, so O(1) might |
4469 |
|
|
mean that libev does a lengthy realloc operation in rare cases, but on |
4470 |
|
|
average it is much faster and asymptotically approaches constant time. |
4471 |
|
|
|
4472 |
|
|
=over 4 |
4473 |
|
|
|
4474 |
|
|
=item Starting and stopping timer/periodic watchers: O(log skipped_other_timers) |
4475 |
|
|
|
4476 |
|
|
This means that, when you have a watcher that triggers in one hour and |
4477 |
|
|
there are 100 watchers that would trigger before that, then inserting will |
4478 |
|
|
have to skip roughly seven (C<ld 100>) of these watchers. |
4479 |
|
|
|
4480 |
|
|
=item Changing timer/periodic watchers (by autorepeat or calling again): O(log skipped_other_timers) |
4481 |
|
|
|
4482 |
|
|
That means that changing a timer costs less than removing/adding them, |
4483 |
|
|
as only the relative motion in the event queue has to be paid for. |
4484 |
|
|
|
4485 |
|
|
=item Starting io/check/prepare/idle/signal/child/fork/async watchers: O(1) |
4486 |
|
|
|
4487 |
|
|
These just add the watcher into an array or at the head of a list. |
4488 |
|
|
|
4489 |
|
|
=item Stopping check/prepare/idle/fork/async watchers: O(1) |
4490 |
|
|
|
4491 |
|
|
=item Stopping an io/signal/child watcher: O(number_of_watchers_for_this_(fd/signal/pid % EV_PID_HASHSIZE)) |
4492 |
|
|
|
4493 |
|
|
These watchers are stored in lists, so they need to be walked to find the |
4494 |
|
|
correct watcher to remove. The lists are usually short (you don't usually |
4495 |
|
|
have many watchers waiting for the same fd or signal: one is typical, two |
4496 |
|
|
is rare). |
4497 |
|
|
|
4498 |
|
|
=item Finding the next timer in each loop iteration: O(1) |
4499 |
|
|
|
4500 |
|
|
By virtue of using a binary or 4-heap, the next timer is always found at a |
4501 |
|
|
fixed position in the storage array. |
4502 |
|
|
|
4503 |
|
|
=item Each change on a file descriptor per loop iteration: O(number_of_watchers_for_this_fd) |
4504 |
|
|
|
4505 |
|
|
A change means an I/O watcher gets started or stopped, which requires |
4506 |
|
|
libev to recalculate its status (and possibly tell the kernel, depending |
4507 |
|
|
on backend and whether C<ev_io_set> was used). |
4508 |
|
|
|
4509 |
|
|
=item Activating one watcher (putting it into the pending state): O(1) |
4510 |
|
|
|
4511 |
|
|
=item Priority handling: O(number_of_priorities) |
4512 |
|
|
|
4513 |
|
|
Priorities are implemented by allocating some space for each |
4514 |
|
|
priority. When doing priority-based operations, libev usually has to |
4515 |
|
|
linearly search all the priorities, but starting/stopping and activating |
4516 |
|
|
watchers becomes O(1) with respect to priority handling. |
4517 |
|
|
|
4518 |
|
|
=item Sending an ev_async: O(1) |
4519 |
|
|
|
4520 |
|
|
=item Processing ev_async_send: O(number_of_async_watchers) |
4521 |
|
|
|
4522 |
|
|
=item Processing signals: O(max_signal_number) |
4523 |
|
|
|
4524 |
|
|
Sending involves a system call I<iff> there were no other C<ev_async_send> |
4525 |
|
|
calls in the current loop iteration. Checking for async and signal events |
4526 |
|
|
involves iterating over all running async watchers or all signal numbers. |
4527 |
|
|
|
4528 |
|
|
=back |
4529 |
|
|
|
4530 |
|
|
|
4531 |
root |
1.234 |
=head1 GLOSSARY |
4532 |
|
|
|
4533 |
|
|
=over 4 |
4534 |
|
|
|
4535 |
|
|
=item active |
4536 |
|
|
|
4537 |
|
|
A watcher is active as long as it has been started (has been attached to |
4538 |
|
|
an event loop) but not yet stopped (disassociated from the event loop). |
4539 |
|
|
|
4540 |
|
|
=item application |
4541 |
|
|
|
4542 |
|
|
In this document, an application is whatever is using libev. |
4543 |
|
|
|
4544 |
|
|
=item callback |
4545 |
|
|
|
4546 |
|
|
The address of a function that is called when some event has been |
4547 |
|
|
detected. Callbacks are being passed the event loop, the watcher that |
4548 |
|
|
received the event, and the actual event bitset. |
4549 |
|
|
|
4550 |
|
|
=item callback invocation |
4551 |
|
|
|
4552 |
|
|
The act of calling the callback associated with a watcher. |
4553 |
|
|
|
4554 |
|
|
=item event |
4555 |
|
|
|
4556 |
|
|
A change of state of some external event, such as data now being available |
4557 |
|
|
for reading on a file descriptor, time having passed or simply not having |
4558 |
|
|
any other events happening anymore. |
4559 |
|
|
|
4560 |
|
|
In libev, events are represented as single bits (such as C<EV_READ> or |
4561 |
|
|
C<EV_TIMEOUT>). |
4562 |
|
|
|
4563 |
|
|
=item event library |
4564 |
|
|
|
4565 |
|
|
A software package implementing an event model and loop. |
4566 |
|
|
|
4567 |
|
|
=item event loop |
4568 |
|
|
|
4569 |
|
|
An entity that handles and processes external events and converts them |
4570 |
|
|
into callback invocations. |
4571 |
|
|
|
4572 |
|
|
=item event model |
4573 |
|
|
|
4574 |
|
|
The model used to describe how an event loop handles and processes |
4575 |
|
|
watchers and events. |
4576 |
|
|
|
4577 |
|
|
=item pending |
4578 |
|
|
|
4579 |
|
|
A watcher is pending as soon as the corresponding event has been detected, |
4580 |
|
|
and stops being pending as soon as the watcher will be invoked or its |
4581 |
|
|
pending status is explicitly cleared by the application. |
4582 |
|
|
|
4583 |
|
|
A watcher can be pending, but not active. Stopping a watcher also clears |
4584 |
|
|
its pending status. |
4585 |
|
|
|
4586 |
|
|
=item real time |
4587 |
|
|
|
4588 |
|
|
The physical time that is observed. It is apparently strictly monotonic :) |
4589 |
|
|
|
4590 |
|
|
=item wall-clock time |
4591 |
|
|
|
4592 |
|
|
The time and date as shown on clocks. Unlike real time, it can actually |
4593 |
|
|
be wrong and jump forwards and backwards, e.g. when the you adjust your |
4594 |
|
|
clock. |
4595 |
|
|
|
4596 |
|
|
=item watcher |
4597 |
|
|
|
4598 |
|
|
A data structure that describes interest in certain events. Watchers need |
4599 |
|
|
to be started (attached to an event loop) before they can receive events. |
4600 |
|
|
|
4601 |
|
|
=item watcher invocation |
4602 |
|
|
|
4603 |
|
|
The act of calling the callback associated with a watcher. |
4604 |
|
|
|
4605 |
|
|
=back |
4606 |
|
|
|
4607 |
root |
1.1 |
=head1 AUTHOR |
4608 |
|
|
|
4609 |
root |
1.209 |
Marc Lehmann <libev@schmorp.de>, with repeated corrections by Mikael Magnusson. |
4610 |
root |
1.1 |
|