ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/libev/ev.pod
Revision: 1.30
Committed: Fri Nov 23 04:36:03 2007 UTC (16 years, 5 months ago) by root
Branch: MAIN
Changes since 1.29: +3 -3 lines
Log Message:
*** empty log message ***

File Contents

# User Rev Content
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     #include <ev.h>
8    
9     =head1 DESCRIPTION
10    
11     Libev is an event loop: you register interest in certain events (such as a
12     file descriptor being readable or a timeout occuring), and it will manage
13 root 1.4 these event sources and provide your program with events.
14 root 1.1
15     To do this, it must take more or less complete control over your process
16     (or thread) by executing the I<event loop> handler, and will then
17     communicate events via a callback mechanism.
18    
19     You register interest in certain events by registering so-called I<event
20     watchers>, which are relatively small C structures you initialise with the
21     details of the event, and then hand it over to libev by I<starting> the
22     watcher.
23    
24     =head1 FEATURES
25    
26     Libev supports select, poll, the linux-specific epoll and the bsd-specific
27     kqueue mechanisms for file descriptor events, relative timers, absolute
28     timers with customised rescheduling, signal events, process status change
29     events (related to SIGCHLD), and event watchers dealing with the event
30 root 1.5 loop mechanism itself (idle, prepare and check watchers). It also is quite
31 root 1.7 fast (see this L<benchmark|http://libev.schmorp.de/bench.html> comparing
32     it to libevent for example).
33 root 1.1
34     =head1 CONVENTIONS
35    
36     Libev is very configurable. In this manual the default configuration
37     will be described, which supports multiple event loops. For more info
38 root 1.7 about various configuration options please have a look at the file
39 root 1.1 F<README.embed> in the libev distribution. If libev was configured without
40     support for multiple event loops, then all functions taking an initial
41     argument of name C<loop> (which is always of type C<struct ev_loop *>)
42     will not have this argument.
43    
44 root 1.17 =head1 TIME REPRESENTATION
45 root 1.1
46 root 1.2 Libev represents time as a single floating point number, representing the
47     (fractional) number of seconds since the (POSIX) epoch (somewhere near
48     the beginning of 1970, details are complicated, don't ask). This type is
49 root 1.1 called C<ev_tstamp>, which is what you should use too. It usually aliases
50     to the double type in C.
51    
52 root 1.17 =head1 GLOBAL FUNCTIONS
53    
54 root 1.18 These functions can be called anytime, even before initialising the
55     library in any way.
56    
57 root 1.1 =over 4
58    
59     =item ev_tstamp ev_time ()
60    
61 root 1.26 Returns the current time as libev would use it. Please note that the
62     C<ev_now> function is usually faster and also often returns the timestamp
63     you actually want to know.
64 root 1.1
65     =item int ev_version_major ()
66    
67     =item int ev_version_minor ()
68    
69     You can find out the major and minor version numbers of the library
70     you linked against by calling the functions C<ev_version_major> and
71     C<ev_version_minor>. If you want, you can compare against the global
72     symbols C<EV_VERSION_MAJOR> and C<EV_VERSION_MINOR>, which specify the
73     version of the library your program was compiled against.
74    
75 root 1.9 Usually, it's a good idea to terminate if the major versions mismatch,
76 root 1.1 as this indicates an incompatible change. Minor versions are usually
77     compatible to older versions, so a larger minor version alone is usually
78     not a problem.
79    
80     =item ev_set_allocator (void *(*cb)(void *ptr, long size))
81    
82     Sets the allocation function to use (the prototype is similar to the
83 root 1.7 realloc C function, the semantics are identical). It is used to allocate
84     and free memory (no surprises here). If it returns zero when memory
85     needs to be allocated, the library might abort or take some potentially
86     destructive action. The default is your system realloc function.
87 root 1.1
88     You could override this function in high-availability programs to, say,
89     free some memory if it cannot allocate memory, to use a special allocator,
90     or even to sleep a while and retry until some memory is available.
91    
92     =item ev_set_syserr_cb (void (*cb)(const char *msg));
93    
94     Set the callback function to call on a retryable syscall error (such
95     as failed select, poll, epoll_wait). The message is a printable string
96     indicating the system call or subsystem causing the problem. If this
97     callback is set, then libev will expect it to remedy the sitution, no
98 root 1.7 matter what, when it returns. That is, libev will generally retry the
99 root 1.1 requested operation, or, if the condition doesn't go away, do bad stuff
100     (such as abort).
101    
102     =back
103    
104     =head1 FUNCTIONS CONTROLLING THE EVENT LOOP
105    
106     An event loop is described by a C<struct ev_loop *>. The library knows two
107     types of such loops, the I<default> loop, which supports signals and child
108     events, and dynamically created loops which do not.
109    
110     If you use threads, a common model is to run the default event loop
111 root 1.17 in your main thread (or in a separate thread) and for each thread you
112 root 1.7 create, you also create another event loop. Libev itself does no locking
113     whatsoever, so if you mix calls to the same event loop in different
114     threads, make sure you lock (this is usually a bad idea, though, even if
115 root 1.9 done correctly, because it's hideous and inefficient).
116 root 1.1
117     =over 4
118    
119     =item struct ev_loop *ev_default_loop (unsigned int flags)
120    
121     This will initialise the default event loop if it hasn't been initialised
122     yet and return it. If the default loop could not be initialised, returns
123     false. If it already was initialised it simply returns it (and ignores the
124     flags).
125    
126     If you don't know what event loop to use, use the one returned from this
127     function.
128    
129     The flags argument can be used to specify special behaviour or specific
130 root 1.8 backends to use, and is usually specified as 0 (or EVFLAG_AUTO).
131 root 1.1
132     It supports the following flags:
133    
134     =over 4
135    
136 root 1.10 =item C<EVFLAG_AUTO>
137 root 1.1
138 root 1.9 The default flags value. Use this if you have no clue (it's the right
139 root 1.1 thing, believe me).
140    
141 root 1.10 =item C<EVFLAG_NOENV>
142 root 1.1
143 root 1.8 If this flag bit is ored into the flag value (or the program runs setuid
144     or setgid) then libev will I<not> look at the environment variable
145     C<LIBEV_FLAGS>. Otherwise (the default), this environment variable will
146     override the flags completely if it is found in the environment. This is
147     useful to try out specific backends to test their performance, or to work
148     around bugs.
149 root 1.1
150 root 1.29 =item C<EVMETHOD_SELECT> (value 1, portable select backend)
151 root 1.1
152 root 1.29 This is your standard select(2) backend. Not I<completely> standard, as
153     libev tries to roll its own fd_set with no limits on the number of fds,
154     but if that fails, expect a fairly low limit on the number of fds when
155     using this backend. It doesn't scale too well (O(highest_fd)), but its usually
156     the fastest backend for a low number of fds.
157 root 1.1
158 root 1.29 =item C<EVMETHOD_POLL> (value 2, poll backend, available everywhere except on windows)
159 root 1.1
160 root 1.29 And this is your standard poll(2) backend. It's more complicated than
161     select, but handles sparse fds better and has no artificial limit on the
162     number of fds you can use (except it will slow down considerably with a
163     lot of inactive fds). It scales similarly to select, i.e. O(total_fds).
164 root 1.1
165 root 1.29 =item C<EVMETHOD_EPOLL> (value 4, Linux)
166 root 1.1
167 root 1.29 For few fds, this backend is a bit little slower than poll and select,
168     but it scales phenomenally better. While poll and select usually scale like
169     O(total_fds) where n is the total number of fds (or the highest fd), epoll scales
170     either O(1) or O(active_fds).
171 root 1.1
172 root 1.29 While stopping and starting an I/O watcher in the same iteration will
173     result in some caching, there is still a syscall per such incident
174     (because the fd could point to a different file description now), so its
175     best to avoid that. Also, dup()ed file descriptors might not work very
176     well if you register events for both fds.
177    
178     =item C<EVMETHOD_KQUEUE> (value 8, most BSD clones)
179    
180     Kqueue deserves special mention, as at the time of this writing, it
181     was broken on all BSDs except NetBSD (usually it doesn't work with
182     anything but sockets and pipes, except on Darwin, where of course its
183     completely useless). For this reason its not being "autodetected" unless
184     you explicitly specify the flags (i.e. you don't use EVFLAG_AUTO).
185    
186     It scales in the same way as the epoll backend, but the interface to the
187     kernel is more efficient (which says nothing about its actual speed, of
188     course). While starting and stopping an I/O watcher does not cause an
189     extra syscall as with epoll, it still adds up to four event changes per
190     incident, so its best to avoid that.
191    
192     =item C<EVMETHOD_DEVPOLL> (value 16, Solaris 8)
193    
194     This is not implemented yet (and might never be).
195    
196     =item C<EVMETHOD_PORT> (value 32, Solaris 10)
197    
198     This uses the Solaris 10 port mechanism. As with everything on Solaris,
199     it's really slow, but it still scales very well (O(active_fds)).
200    
201     =item C<EVMETHOD_ALL>
202    
203     Try all backends (even potentially broken ones that wouldn't be tried
204     with C<EVFLAG_AUTO>). Since this is a mask, you can do stuff such as
205     C<EVMETHOD_ALL & ~EVMETHOD_KQUEUE>.
206 root 1.1
207     =back
208    
209 root 1.29 If one or more of these are ored into the flags value, then only these
210     backends will be tried (in the reverse order as given here). If none are
211     specified, most compiled-in backend will be tried, usually in reverse
212     order of their flag values :)
213    
214 root 1.1 =item struct ev_loop *ev_loop_new (unsigned int flags)
215    
216     Similar to C<ev_default_loop>, but always creates a new event loop that is
217     always distinct from the default loop. Unlike the default loop, it cannot
218     handle signal and child watchers, and attempts to do so will be greeted by
219     undefined behaviour (or a failed assertion if assertions are enabled).
220    
221     =item ev_default_destroy ()
222    
223     Destroys the default loop again (frees all memory and kernel state
224     etc.). This stops all registered event watchers (by not touching them in
225 root 1.9 any way whatsoever, although you cannot rely on this :).
226 root 1.1
227     =item ev_loop_destroy (loop)
228    
229     Like C<ev_default_destroy>, but destroys an event loop created by an
230     earlier call to C<ev_loop_new>.
231    
232     =item ev_default_fork ()
233    
234     This function reinitialises the kernel state for backends that have
235     one. Despite the name, you can call it anytime, but it makes most sense
236     after forking, in either the parent or child process (or both, but that
237     again makes little sense).
238    
239 root 1.30 You I<must> call this function in the child process after forking if and
240     only if you want to use the event library in both processes. If you just
241     fork+exec, you don't have to call it.
242 root 1.1
243 root 1.9 The function itself is quite fast and it's usually not a problem to call
244 root 1.1 it just in case after a fork. To make this easy, the function will fit in
245     quite nicely into a call to C<pthread_atfork>:
246    
247     pthread_atfork (0, 0, ev_default_fork);
248    
249     =item ev_loop_fork (loop)
250    
251     Like C<ev_default_fork>, but acts on an event loop created by
252     C<ev_loop_new>. Yes, you have to call this on every allocated event loop
253     after fork, and how you do this is entirely your own problem.
254    
255     =item unsigned int ev_method (loop)
256    
257     Returns one of the C<EVMETHOD_*> flags indicating the event backend in
258     use.
259    
260 root 1.9 =item ev_tstamp ev_now (loop)
261 root 1.1
262     Returns the current "event loop time", which is the time the event loop
263     got events and started processing them. This timestamp does not change
264     as long as callbacks are being processed, and this is also the base time
265     used for relative timers. You can treat it as the timestamp of the event
266     occuring (or more correctly, the mainloop finding out about it).
267    
268     =item ev_loop (loop, int flags)
269    
270     Finally, this is it, the event handler. This function usually is called
271     after you initialised all your watchers and you want to start handling
272     events.
273    
274     If the flags argument is specified as 0, it will not return until either
275     no event watchers are active anymore or C<ev_unloop> was called.
276    
277     A flags value of C<EVLOOP_NONBLOCK> will look for new events, will handle
278     those events and any outstanding ones, but will not block your process in
279 root 1.9 case there are no events and will return after one iteration of the loop.
280 root 1.1
281     A flags value of C<EVLOOP_ONESHOT> will look for new events (waiting if
282     neccessary) and will handle those and any outstanding ones. It will block
283 root 1.9 your process until at least one new event arrives, and will return after
284     one iteration of the loop.
285 root 1.1
286     This flags value could be used to implement alternative looping
287     constructs, but the C<prepare> and C<check> watchers provide a better and
288     more generic mechanism.
289    
290 root 1.27 Here are the gory details of what ev_loop does:
291    
292     1. If there are no active watchers (reference count is zero), return.
293     2. Queue and immediately call all prepare watchers.
294     3. If we have been forked, recreate the kernel state.
295     4. Update the kernel state with all outstanding changes.
296     5. Update the "event loop time".
297     6. Calculate for how long to block.
298     7. Block the process, waiting for events.
299     8. Update the "event loop time" and do time jump handling.
300     9. Queue all outstanding timers.
301     10. Queue all outstanding periodics.
302     11. If no events are pending now, queue all idle watchers.
303     12. Queue all check watchers.
304     13. Call all queued watchers in reverse order (i.e. check watchers first).
305     14. If ev_unloop has been called or EVLOOP_ONESHOT or EVLOOP_NONBLOCK
306     was used, return, otherwise continue with step #1.
307    
308 root 1.1 =item ev_unloop (loop, how)
309    
310 root 1.9 Can be used to make a call to C<ev_loop> return early (but only after it
311     has processed all outstanding events). The C<how> argument must be either
312 root 1.25 C<EVUNLOOP_ONE>, which will make the innermost C<ev_loop> call return, or
313 root 1.9 C<EVUNLOOP_ALL>, which will make all nested C<ev_loop> calls return.
314 root 1.1
315     =item ev_ref (loop)
316    
317     =item ev_unref (loop)
318    
319 root 1.9 Ref/unref can be used to add or remove a reference count on the event
320     loop: Every watcher keeps one reference, and as long as the reference
321     count is nonzero, C<ev_loop> will not return on its own. If you have
322     a watcher you never unregister that should not keep C<ev_loop> from
323     returning, ev_unref() after starting, and ev_ref() before stopping it. For
324     example, libev itself uses this for its internal signal pipe: It is not
325     visible to the libev user and should not keep C<ev_loop> from exiting if
326     no event watchers registered by it are active. It is also an excellent
327     way to do this for generic recurring timers or from within third-party
328     libraries. Just remember to I<unref after start> and I<ref before stop>.
329 root 1.1
330     =back
331    
332     =head1 ANATOMY OF A WATCHER
333    
334     A watcher is a structure that you create and register to record your
335     interest in some event. For instance, if you want to wait for STDIN to
336 root 1.10 become readable, you would create an C<ev_io> watcher for that:
337 root 1.1
338     static void my_cb (struct ev_loop *loop, struct ev_io *w, int revents)
339     {
340     ev_io_stop (w);
341     ev_unloop (loop, EVUNLOOP_ALL);
342     }
343    
344     struct ev_loop *loop = ev_default_loop (0);
345     struct ev_io stdin_watcher;
346     ev_init (&stdin_watcher, my_cb);
347     ev_io_set (&stdin_watcher, STDIN_FILENO, EV_READ);
348     ev_io_start (loop, &stdin_watcher);
349     ev_loop (loop, 0);
350    
351     As you can see, you are responsible for allocating the memory for your
352     watcher structures (and it is usually a bad idea to do this on the stack,
353     although this can sometimes be quite valid).
354    
355     Each watcher structure must be initialised by a call to C<ev_init
356     (watcher *, callback)>, which expects a callback to be provided. This
357     callback gets invoked each time the event occurs (or, in the case of io
358     watchers, each time the event loop detects that the file descriptor given
359     is readable and/or writable).
360    
361     Each watcher type has its own C<< ev_<type>_set (watcher *, ...) >> macro
362     with arguments specific to this watcher type. There is also a macro
363     to combine initialisation and setting in one call: C<< ev_<type>_init
364     (watcher *, callback, ...) >>.
365    
366     To make the watcher actually watch out for events, you have to start it
367     with a watcher-specific start function (C<< ev_<type>_start (loop, watcher
368     *) >>), and you can stop watching for events at any time by calling the
369     corresponding stop function (C<< ev_<type>_stop (loop, watcher *) >>.
370    
371     As long as your watcher is active (has been started but not stopped) you
372     must not touch the values stored in it. Most specifically you must never
373     reinitialise it or call its set method.
374    
375 root 1.14 You can check whether an event is active by calling the C<ev_is_active
376 root 1.4 (watcher *)> macro. To see whether an event is outstanding (but the
377 root 1.14 callback for it has not been called yet) you can use the C<ev_is_pending
378 root 1.1 (watcher *)> macro.
379    
380     Each and every callback receives the event loop pointer as first, the
381     registered watcher structure as second, and a bitset of received events as
382     third argument.
383    
384 root 1.14 The received events usually include a single bit per event type received
385 root 1.1 (you can receive multiple events at the same time). The possible bit masks
386     are:
387    
388     =over 4
389    
390 root 1.10 =item C<EV_READ>
391 root 1.1
392 root 1.10 =item C<EV_WRITE>
393 root 1.1
394 root 1.10 The file descriptor in the C<ev_io> watcher has become readable and/or
395 root 1.1 writable.
396    
397 root 1.10 =item C<EV_TIMEOUT>
398 root 1.1
399 root 1.10 The C<ev_timer> watcher has timed out.
400 root 1.1
401 root 1.10 =item C<EV_PERIODIC>
402 root 1.1
403 root 1.10 The C<ev_periodic> watcher has timed out.
404 root 1.1
405 root 1.10 =item C<EV_SIGNAL>
406 root 1.1
407 root 1.10 The signal specified in the C<ev_signal> watcher has been received by a thread.
408 root 1.1
409 root 1.10 =item C<EV_CHILD>
410 root 1.1
411 root 1.10 The pid specified in the C<ev_child> watcher has received a status change.
412 root 1.1
413 root 1.10 =item C<EV_IDLE>
414 root 1.1
415 root 1.10 The C<ev_idle> watcher has determined that you have nothing better to do.
416 root 1.1
417 root 1.10 =item C<EV_PREPARE>
418 root 1.1
419 root 1.10 =item C<EV_CHECK>
420 root 1.1
421 root 1.10 All C<ev_prepare> watchers are invoked just I<before> C<ev_loop> starts
422     to gather new events, and all C<ev_check> watchers are invoked just after
423 root 1.1 C<ev_loop> has gathered them, but before it invokes any callbacks for any
424     received events. Callbacks of both watcher types can start and stop as
425     many watchers as they want, and all of them will be taken into account
426 root 1.10 (for example, a C<ev_prepare> watcher might start an idle watcher to keep
427 root 1.1 C<ev_loop> from blocking).
428    
429 root 1.10 =item C<EV_ERROR>
430 root 1.1
431     An unspecified error has occured, the watcher has been stopped. This might
432     happen because the watcher could not be properly started because libev
433     ran out of memory, a file descriptor was found to be closed or any other
434     problem. You best act on it by reporting the problem and somehow coping
435     with the watcher being stopped.
436    
437     Libev will usually signal a few "dummy" events together with an error,
438     for example it might indicate that a fd is readable or writable, and if
439     your callbacks is well-written it can just attempt the operation and cope
440     with the error from read() or write(). This will not work in multithreaded
441     programs, though, so beware.
442    
443     =back
444    
445     =head2 ASSOCIATING CUSTOM DATA WITH A WATCHER
446    
447     Each watcher has, by default, a member C<void *data> that you can change
448 root 1.14 and read at any time, libev will completely ignore it. This can be used
449 root 1.1 to associate arbitrary data with your watcher. If you need more data and
450     don't want to allocate memory and store a pointer to it in that data
451     member, you can also "subclass" the watcher type and provide your own
452     data:
453    
454     struct my_io
455     {
456     struct ev_io io;
457     int otherfd;
458     void *somedata;
459     struct whatever *mostinteresting;
460     }
461    
462     And since your callback will be called with a pointer to the watcher, you
463     can cast it back to your own type:
464    
465     static void my_cb (struct ev_loop *loop, struct ev_io *w_, int revents)
466     {
467     struct my_io *w = (struct my_io *)w_;
468     ...
469     }
470    
471     More interesting and less C-conformant ways of catsing your callback type
472     have been omitted....
473    
474    
475     =head1 WATCHER TYPES
476    
477     This section describes each watcher in detail, but will not repeat
478     information given in the last section.
479    
480 root 1.11 =head2 C<ev_io> - is this file descriptor readable or writable
481 root 1.1
482 root 1.4 I/O watchers check whether a file descriptor is readable or writable
483 root 1.1 in each iteration of the event loop (This behaviour is called
484     level-triggering because you keep receiving events as long as the
485 root 1.14 condition persists. Remember you can stop the watcher if you don't want to
486 root 1.1 act on the event and neither want to receive future events).
487    
488 root 1.23 In general you can register as many read and/or write event watchers per
489 root 1.8 fd as you want (as long as you don't confuse yourself). Setting all file
490     descriptors to non-blocking mode is also usually a good idea (but not
491     required if you know what you are doing).
492    
493     You have to be careful with dup'ed file descriptors, though. Some backends
494     (the linux epoll backend is a notable example) cannot handle dup'ed file
495     descriptors correctly if you register interest in two or more fds pointing
496 root 1.24 to the same underlying file/socket etc. description (that is, they share
497     the same underlying "file open").
498 root 1.8
499     If you must do this, then force the use of a known-to-be-good backend
500     (at the time of this writing, this includes only EVMETHOD_SELECT and
501     EVMETHOD_POLL).
502    
503 root 1.1 =over 4
504    
505     =item ev_io_init (ev_io *, callback, int fd, int events)
506    
507     =item ev_io_set (ev_io *, int fd, int events)
508    
509 root 1.10 Configures an C<ev_io> watcher. The fd is the file descriptor to rceeive
510 root 1.1 events for and events is either C<EV_READ>, C<EV_WRITE> or C<EV_READ |
511     EV_WRITE> to receive the given events.
512    
513     =back
514    
515 root 1.10 =head2 C<ev_timer> - relative and optionally recurring timeouts
516 root 1.1
517     Timer watchers are simple relative timers that generate an event after a
518     given time, and optionally repeating in regular intervals after that.
519    
520     The timers are based on real time, that is, if you register an event that
521 root 1.22 times out after an hour and you reset your system clock to last years
522 root 1.1 time, it will still time out after (roughly) and hour. "Roughly" because
523 root 1.28 detecting time jumps is hard, and some inaccuracies are unavoidable (the
524 root 1.1 monotonic clock option helps a lot here).
525    
526 root 1.9 The relative timeouts are calculated relative to the C<ev_now ()>
527     time. This is usually the right thing as this timestamp refers to the time
528 root 1.28 of the event triggering whatever timeout you are modifying/starting. If
529     you suspect event processing to be delayed and you I<need> to base the timeout
530 root 1.22 on the current time, use something like this to adjust for this:
531 root 1.9
532     ev_timer_set (&timer, after + ev_now () - ev_time (), 0.);
533    
534 root 1.28 The callback is guarenteed to be invoked only when its timeout has passed,
535     but if multiple timers become ready during the same loop iteration then
536     order of execution is undefined.
537    
538 root 1.1 =over 4
539    
540     =item ev_timer_init (ev_timer *, callback, ev_tstamp after, ev_tstamp repeat)
541    
542     =item ev_timer_set (ev_timer *, ev_tstamp after, ev_tstamp repeat)
543    
544     Configure the timer to trigger after C<after> seconds. If C<repeat> is
545     C<0.>, then it will automatically be stopped. If it is positive, then the
546     timer will automatically be configured to trigger again C<repeat> seconds
547     later, again, and again, until stopped manually.
548    
549     The timer itself will do a best-effort at avoiding drift, that is, if you
550     configure a timer to trigger every 10 seconds, then it will trigger at
551     exactly 10 second intervals. If, however, your program cannot keep up with
552 root 1.22 the timer (because it takes longer than those 10 seconds to do stuff) the
553 root 1.1 timer will not fire more than once per event loop iteration.
554    
555     =item ev_timer_again (loop)
556    
557     This will act as if the timer timed out and restart it again if it is
558     repeating. The exact semantics are:
559    
560     If the timer is started but nonrepeating, stop it.
561    
562     If the timer is repeating, either start it if necessary (with the repeat
563     value), or reset the running timer to the repeat value.
564    
565     This sounds a bit complicated, but here is a useful and typical
566     example: Imagine you have a tcp connection and you want a so-called idle
567     timeout, that is, you want to be called when there have been, say, 60
568     seconds of inactivity on the socket. The easiest way to do this is to
569 root 1.10 configure an C<ev_timer> with after=repeat=60 and calling ev_timer_again each
570 root 1.1 time you successfully read or write some data. If you go into an idle
571     state where you do not expect data to travel on the socket, you can stop
572     the timer, and again will automatically restart it if need be.
573    
574     =back
575    
576 root 1.14 =head2 C<ev_periodic> - to cron or not to cron
577 root 1.1
578     Periodic watchers are also timers of a kind, but they are very versatile
579     (and unfortunately a bit complex).
580    
581 root 1.10 Unlike C<ev_timer>'s, they are not based on real time (or relative time)
582 root 1.1 but on wallclock time (absolute time). You can tell a periodic watcher
583     to trigger "at" some specific point in time. For example, if you tell a
584     periodic watcher to trigger in 10 seconds (by specifiying e.g. c<ev_now ()
585     + 10.>) and then reset your system clock to the last year, then it will
586 root 1.10 take a year to trigger the event (unlike an C<ev_timer>, which would trigger
587 root 1.1 roughly 10 seconds later and of course not if you reset your system time
588     again).
589    
590     They can also be used to implement vastly more complex timers, such as
591     triggering an event on eahc midnight, local time.
592    
593 root 1.28 As with timers, the callback is guarenteed to be invoked only when the
594     time (C<at>) has been passed, but if multiple periodic timers become ready
595     during the same loop iteration then order of execution is undefined.
596    
597 root 1.1 =over 4
598    
599     =item ev_periodic_init (ev_periodic *, callback, ev_tstamp at, ev_tstamp interval, reschedule_cb)
600    
601     =item ev_periodic_set (ev_periodic *, ev_tstamp after, ev_tstamp repeat, reschedule_cb)
602    
603     Lots of arguments, lets sort it out... There are basically three modes of
604     operation, and we will explain them from simplest to complex:
605    
606     =over 4
607    
608     =item * absolute timer (interval = reschedule_cb = 0)
609    
610     In this configuration the watcher triggers an event at the wallclock time
611     C<at> and doesn't repeat. It will not adjust when a time jump occurs,
612     that is, if it is to be run at January 1st 2011 then it will run when the
613     system time reaches or surpasses this time.
614    
615     =item * non-repeating interval timer (interval > 0, reschedule_cb = 0)
616    
617     In this mode the watcher will always be scheduled to time out at the next
618     C<at + N * interval> time (for some integer N) and then repeat, regardless
619     of any time jumps.
620    
621     This can be used to create timers that do not drift with respect to system
622     time:
623    
624     ev_periodic_set (&periodic, 0., 3600., 0);
625    
626     This doesn't mean there will always be 3600 seconds in between triggers,
627     but only that the the callback will be called when the system time shows a
628 root 1.12 full hour (UTC), or more correctly, when the system time is evenly divisible
629 root 1.1 by 3600.
630    
631     Another way to think about it (for the mathematically inclined) is that
632 root 1.10 C<ev_periodic> will try to run the callback in this mode at the next possible
633 root 1.1 time where C<time = at (mod interval)>, regardless of any time jumps.
634    
635     =item * manual reschedule mode (reschedule_cb = callback)
636    
637     In this mode the values for C<interval> and C<at> are both being
638     ignored. Instead, each time the periodic watcher gets scheduled, the
639     reschedule callback will be called with the watcher as first, and the
640     current time as second argument.
641    
642 root 1.18 NOTE: I<This callback MUST NOT stop or destroy any periodic watcher,
643     ever, or make any event loop modifications>. If you need to stop it,
644     return C<now + 1e30> (or so, fudge fudge) and stop it afterwards (e.g. by
645     starting a prepare watcher).
646 root 1.1
647 root 1.13 Its prototype is C<ev_tstamp (*reschedule_cb)(struct ev_periodic *w,
648 root 1.1 ev_tstamp now)>, e.g.:
649    
650     static ev_tstamp my_rescheduler (struct ev_periodic *w, ev_tstamp now)
651     {
652     return now + 60.;
653     }
654    
655     It must return the next time to trigger, based on the passed time value
656     (that is, the lowest time value larger than to the second argument). It
657     will usually be called just before the callback will be triggered, but
658     might be called at other times, too.
659    
660 root 1.18 NOTE: I<< This callback must always return a time that is later than the
661 root 1.19 passed C<now> value >>. Not even C<now> itself will do, it I<must> be larger.
662 root 1.18
663 root 1.1 This can be used to create very complex timers, such as a timer that
664     triggers on each midnight, local time. To do this, you would calculate the
665 root 1.19 next midnight after C<now> and return the timestamp value for this. How
666     you do this is, again, up to you (but it is not trivial, which is the main
667     reason I omitted it as an example).
668 root 1.1
669     =back
670    
671     =item ev_periodic_again (loop, ev_periodic *)
672    
673     Simply stops and restarts the periodic watcher again. This is only useful
674     when you changed some parameters or the reschedule callback would return
675     a different time than the last time it was called (e.g. in a crond like
676     program when the crontabs have changed).
677    
678     =back
679    
680 root 1.10 =head2 C<ev_signal> - signal me when a signal gets signalled
681 root 1.1
682     Signal watchers will trigger an event when the process receives a specific
683     signal one or more times. Even though signals are very asynchronous, libev
684 root 1.9 will try it's best to deliver signals synchronously, i.e. as part of the
685 root 1.1 normal event processing, like any other event.
686    
687 root 1.14 You can configure as many watchers as you like per signal. Only when the
688 root 1.1 first watcher gets started will libev actually register a signal watcher
689     with the kernel (thus it coexists with your own signal handlers as long
690     as you don't register any with libev). Similarly, when the last signal
691     watcher for a signal is stopped libev will reset the signal handler to
692     SIG_DFL (regardless of what it was set to before).
693    
694     =over 4
695    
696     =item ev_signal_init (ev_signal *, callback, int signum)
697    
698     =item ev_signal_set (ev_signal *, int signum)
699    
700     Configures the watcher to trigger on the given signal number (usually one
701     of the C<SIGxxx> constants).
702    
703     =back
704    
705 root 1.10 =head2 C<ev_child> - wait for pid status changes
706 root 1.1
707     Child watchers trigger when your process receives a SIGCHLD in response to
708     some child status changes (most typically when a child of yours dies).
709    
710     =over 4
711    
712     =item ev_child_init (ev_child *, callback, int pid)
713    
714     =item ev_child_set (ev_child *, int pid)
715    
716     Configures the watcher to wait for status changes of process C<pid> (or
717     I<any> process if C<pid> is specified as C<0>). The callback can look
718     at the C<rstatus> member of the C<ev_child> watcher structure to see
719 root 1.14 the status word (use the macros from C<sys/wait.h> and see your systems
720     C<waitpid> documentation). The C<rpid> member contains the pid of the
721     process causing the status change.
722 root 1.1
723     =back
724    
725 root 1.10 =head2 C<ev_idle> - when you've got nothing better to do
726 root 1.1
727 root 1.14 Idle watchers trigger events when there are no other events are pending
728     (prepare, check and other idle watchers do not count). That is, as long
729     as your process is busy handling sockets or timeouts (or even signals,
730     imagine) it will not be triggered. But when your process is idle all idle
731     watchers are being called again and again, once per event loop iteration -
732     until stopped, that is, or your process receives more events and becomes
733     busy.
734 root 1.1
735     The most noteworthy effect is that as long as any idle watchers are
736     active, the process will not block when waiting for new events.
737    
738     Apart from keeping your process non-blocking (which is a useful
739     effect on its own sometimes), idle watchers are a good place to do
740     "pseudo-background processing", or delay processing stuff to after the
741     event loop has handled all outstanding events.
742    
743     =over 4
744    
745     =item ev_idle_init (ev_signal *, callback)
746    
747     Initialises and configures the idle watcher - it has no parameters of any
748     kind. There is a C<ev_idle_set> macro, but using it is utterly pointless,
749     believe me.
750    
751     =back
752    
753 root 1.16 =head2 C<ev_prepare> and C<ev_check> - customise your event loop
754 root 1.1
755 root 1.14 Prepare and check watchers are usually (but not always) used in tandem:
756 root 1.20 prepare watchers get invoked before the process blocks and check watchers
757 root 1.14 afterwards.
758 root 1.1
759     Their main purpose is to integrate other event mechanisms into libev. This
760     could be used, for example, to track variable changes, implement your own
761     watchers, integrate net-snmp or a coroutine library and lots more.
762    
763     This is done by examining in each prepare call which file descriptors need
764 root 1.14 to be watched by the other library, registering C<ev_io> watchers for
765     them and starting an C<ev_timer> watcher for any timeouts (many libraries
766     provide just this functionality). Then, in the check watcher you check for
767     any events that occured (by checking the pending status of all watchers
768     and stopping them) and call back into the library. The I/O and timer
769 root 1.20 callbacks will never actually be called (but must be valid nevertheless,
770 root 1.14 because you never know, you know?).
771 root 1.1
772 root 1.14 As another example, the Perl Coro module uses these hooks to integrate
773 root 1.1 coroutines into libev programs, by yielding to other active coroutines
774     during each prepare and only letting the process block if no coroutines
775 root 1.20 are ready to run (it's actually more complicated: it only runs coroutines
776     with priority higher than or equal to the event loop and one coroutine
777     of lower priority, but only once, using idle watchers to keep the event
778     loop from blocking if lower-priority coroutines are active, thus mapping
779     low-priority coroutines to idle/background tasks).
780 root 1.1
781     =over 4
782    
783     =item ev_prepare_init (ev_prepare *, callback)
784    
785     =item ev_check_init (ev_check *, callback)
786    
787     Initialises and configures the prepare or check watcher - they have no
788     parameters of any kind. There are C<ev_prepare_set> and C<ev_check_set>
789 root 1.14 macros, but using them is utterly, utterly and completely pointless.
790 root 1.1
791     =back
792    
793     =head1 OTHER FUNCTIONS
794    
795 root 1.14 There are some other functions of possible interest. Described. Here. Now.
796 root 1.1
797     =over 4
798    
799     =item ev_once (loop, int fd, int events, ev_tstamp timeout, callback)
800    
801     This function combines a simple timer and an I/O watcher, calls your
802     callback on whichever event happens first and automatically stop both
803     watchers. This is useful if you want to wait for a single event on an fd
804 root 1.22 or timeout without having to allocate/configure/start/stop/free one or
805 root 1.1 more watchers yourself.
806    
807 root 1.14 If C<fd> is less than 0, then no I/O watcher will be started and events
808     is being ignored. Otherwise, an C<ev_io> watcher for the given C<fd> and
809     C<events> set will be craeted and started.
810 root 1.1
811     If C<timeout> is less than 0, then no timeout watcher will be
812 root 1.14 started. Otherwise an C<ev_timer> watcher with after = C<timeout> (and
813     repeat = 0) will be started. While C<0> is a valid timeout, it is of
814     dubious value.
815    
816     The callback has the type C<void (*cb)(int revents, void *arg)> and gets
817 root 1.21 passed an C<revents> set like normal event callbacks (a combination of
818 root 1.14 C<EV_ERROR>, C<EV_READ>, C<EV_WRITE> or C<EV_TIMEOUT>) and the C<arg>
819     value passed to C<ev_once>:
820 root 1.1
821     static void stdin_ready (int revents, void *arg)
822     {
823     if (revents & EV_TIMEOUT)
824 root 1.14 /* doh, nothing entered */;
825 root 1.1 else if (revents & EV_READ)
826 root 1.14 /* stdin might have data for us, joy! */;
827 root 1.1 }
828    
829 root 1.14 ev_once (STDIN_FILENO, EV_READ, 10., stdin_ready, 0);
830 root 1.1
831     =item ev_feed_event (loop, watcher, int events)
832    
833     Feeds the given event set into the event loop, as if the specified event
834 root 1.14 had happened for the specified watcher (which must be a pointer to an
835     initialised but not necessarily started event watcher).
836 root 1.1
837     =item ev_feed_fd_event (loop, int fd, int revents)
838    
839 root 1.14 Feed an event on the given fd, as if a file descriptor backend detected
840     the given events it.
841 root 1.1
842     =item ev_feed_signal_event (loop, int signum)
843    
844     Feed an event as if the given signal occured (loop must be the default loop!).
845    
846     =back
847    
848 root 1.20 =head1 LIBEVENT EMULATION
849    
850 root 1.24 Libev offers a compatibility emulation layer for libevent. It cannot
851     emulate the internals of libevent, so here are some usage hints:
852    
853     =over 4
854    
855     =item * Use it by including <event.h>, as usual.
856    
857     =item * The following members are fully supported: ev_base, ev_callback,
858     ev_arg, ev_fd, ev_res, ev_events.
859    
860     =item * Avoid using ev_flags and the EVLIST_*-macros, while it is
861     maintained by libev, it does not work exactly the same way as in libevent (consider
862     it a private API).
863    
864     =item * Priorities are not currently supported. Initialising priorities
865     will fail and all watchers will have the same priority, even though there
866     is an ev_pri field.
867    
868     =item * Other members are not supported.
869    
870     =item * The libev emulation is I<not> ABI compatible to libevent, you need
871     to use the libev header file and library.
872    
873     =back
874 root 1.20
875     =head1 C++ SUPPORT
876    
877     TBD.
878    
879 root 1.1 =head1 AUTHOR
880    
881     Marc Lehmann <libev@schmorp.de>.
882