ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/libev/ev.pod
Revision: 1.5
Committed: Mon Nov 12 08:11:57 2007 UTC (16 years, 6 months ago) by root
Branch: MAIN
Changes since 1.4: +3 -1 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     fast (see a L<http://libev.schmorp.de/bench.html|benchmark> comparing it
32     to libevent).
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     about various configuraiton options please have a look at the file
39     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     =head1 TIME AND OTHER GLOBAL FUNCTIONS
45    
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     =over 4
53    
54     =item ev_tstamp ev_time ()
55    
56     Returns the current time as libev would use it.
57    
58     =item int ev_version_major ()
59    
60     =item int ev_version_minor ()
61    
62     You can find out the major and minor version numbers of the library
63     you linked against by calling the functions C<ev_version_major> and
64     C<ev_version_minor>. If you want, you can compare against the global
65     symbols C<EV_VERSION_MAJOR> and C<EV_VERSION_MINOR>, which specify the
66     version of the library your program was compiled against.
67    
68     Usually, its a good idea to terminate if the major versions mismatch,
69     as this indicates an incompatible change. Minor versions are usually
70     compatible to older versions, so a larger minor version alone is usually
71     not a problem.
72    
73     =item ev_set_allocator (void *(*cb)(void *ptr, long size))
74    
75     Sets the allocation function to use (the prototype is similar to the
76     realloc function). It is used to allocate and free memory (no surprises
77     here). If it returns zero when memory needs to be allocated, the library
78     might abort or take some potentially destructive action. The default is
79     your system realloc function.
80    
81     You could override this function in high-availability programs to, say,
82     free some memory if it cannot allocate memory, to use a special allocator,
83     or even to sleep a while and retry until some memory is available.
84    
85     =item ev_set_syserr_cb (void (*cb)(const char *msg));
86    
87     Set the callback function to call on a retryable syscall error (such
88     as failed select, poll, epoll_wait). The message is a printable string
89     indicating the system call or subsystem causing the problem. If this
90     callback is set, then libev will expect it to remedy the sitution, no
91     matter what, when it returns. That is, libev will geenrally retry the
92     requested operation, or, if the condition doesn't go away, do bad stuff
93     (such as abort).
94    
95     =back
96    
97     =head1 FUNCTIONS CONTROLLING THE EVENT LOOP
98    
99     An event loop is described by a C<struct ev_loop *>. The library knows two
100     types of such loops, the I<default> loop, which supports signals and child
101     events, and dynamically created loops which do not.
102    
103     If you use threads, a common model is to run the default event loop
104     in your main thread (or in a separate thrad) and for each thread you
105     create, you also create another event loop. Libev itself does no lockign
106     whatsoever, so if you mix calls to different event loops, make sure you
107     lock (this is usually a bad idea, though, even if done right).
108    
109     =over 4
110    
111     =item struct ev_loop *ev_default_loop (unsigned int flags)
112    
113     This will initialise the default event loop if it hasn't been initialised
114     yet and return it. If the default loop could not be initialised, returns
115     false. If it already was initialised it simply returns it (and ignores the
116     flags).
117    
118     If you don't know what event loop to use, use the one returned from this
119     function.
120    
121     The flags argument can be used to specify special behaviour or specific
122     backends to use, and is usually specified as 0 (or EVFLAG_AUTO)
123    
124     It supports the following flags:
125    
126     =over 4
127    
128     =item EVFLAG_AUTO
129    
130     The default flags value. Use this if you have no clue (its the right
131     thing, believe me).
132    
133     =item EVFLAG_NOENV
134    
135     If this flag bit is ored into the flag value then libev will I<not> look
136     at the environment variable C<LIBEV_FLAGS>. Otherwise (the default), this
137     environment variable will override the flags completely. This is useful
138     to try out specific backends to tets their performance, or to work around
139     bugs.
140    
141     =item EVMETHOD_SELECT portable select backend
142    
143     =item EVMETHOD_POLL poll backend (everywhere except windows)
144    
145     =item EVMETHOD_EPOLL linux only
146    
147     =item EVMETHOD_KQUEUE some bsds only
148    
149     =item EVMETHOD_DEVPOLL solaris 8 only
150    
151     =item EVMETHOD_PORT solaris 10 only
152    
153     If one or more of these are ored into the flags value, then only these
154     backends will be tried (in the reverse order as given here). If one are
155     specified, any backend will do.
156    
157     =back
158    
159     =item struct ev_loop *ev_loop_new (unsigned int flags)
160    
161     Similar to C<ev_default_loop>, but always creates a new event loop that is
162     always distinct from the default loop. Unlike the default loop, it cannot
163     handle signal and child watchers, and attempts to do so will be greeted by
164     undefined behaviour (or a failed assertion if assertions are enabled).
165    
166     =item ev_default_destroy ()
167    
168     Destroys the default loop again (frees all memory and kernel state
169     etc.). This stops all registered event watchers (by not touching them in
170     any way whatsoever, although you cnanot rely on this :).
171    
172     =item ev_loop_destroy (loop)
173    
174     Like C<ev_default_destroy>, but destroys an event loop created by an
175     earlier call to C<ev_loop_new>.
176    
177     =item ev_default_fork ()
178    
179     This function reinitialises the kernel state for backends that have
180     one. Despite the name, you can call it anytime, but it makes most sense
181     after forking, in either the parent or child process (or both, but that
182     again makes little sense).
183    
184     You I<must> call this function after forking if and only if you want to
185     use the event library in both processes. If you just fork+exec, you don't
186     have to call it.
187    
188     The function itself is quite fast and its usually not a problem to call
189     it just in case after a fork. To make this easy, the function will fit in
190     quite nicely into a call to C<pthread_atfork>:
191    
192     pthread_atfork (0, 0, ev_default_fork);
193    
194     =item ev_loop_fork (loop)
195    
196     Like C<ev_default_fork>, but acts on an event loop created by
197     C<ev_loop_new>. Yes, you have to call this on every allocated event loop
198     after fork, and how you do this is entirely your own problem.
199    
200     =item unsigned int ev_method (loop)
201    
202     Returns one of the C<EVMETHOD_*> flags indicating the event backend in
203     use.
204    
205     =item ev_tstamp = ev_now (loop)
206    
207     Returns the current "event loop time", which is the time the event loop
208     got events and started processing them. This timestamp does not change
209     as long as callbacks are being processed, and this is also the base time
210     used for relative timers. You can treat it as the timestamp of the event
211     occuring (or more correctly, the mainloop finding out about it).
212    
213     =item ev_loop (loop, int flags)
214    
215     Finally, this is it, the event handler. This function usually is called
216     after you initialised all your watchers and you want to start handling
217     events.
218    
219     If the flags argument is specified as 0, it will not return until either
220     no event watchers are active anymore or C<ev_unloop> was called.
221    
222     A flags value of C<EVLOOP_NONBLOCK> will look for new events, will handle
223     those events and any outstanding ones, but will not block your process in
224     case there are no events.
225    
226     A flags value of C<EVLOOP_ONESHOT> will look for new events (waiting if
227     neccessary) and will handle those and any outstanding ones. It will block
228     your process until at least one new event arrives.
229    
230     This flags value could be used to implement alternative looping
231     constructs, but the C<prepare> and C<check> watchers provide a better and
232     more generic mechanism.
233    
234     =item ev_unloop (loop, how)
235    
236     Can be used to make a call to C<ev_loop> return early. The C<how> argument
237     must be either C<EVUNLOOP_ONCE>, which will make the innermost C<ev_loop>
238     call return, or C<EVUNLOOP_ALL>, which will make all nested C<ev_loop>
239     calls return.
240    
241     =item ev_ref (loop)
242    
243     =item ev_unref (loop)
244    
245     Ref/unref can be used to add or remove a refcount on the event loop: Every
246     watcher keeps one reference. If you have a long-runing watcher you never
247     unregister that should not keep ev_loop from running, ev_unref() after
248     starting, and ev_ref() before stopping it. Libev itself uses this for
249     example for its internal signal pipe: It is not visible to you as a user
250     and should not keep C<ev_loop> from exiting if the work is done. It is
251     also an excellent way to do this for generic recurring timers or from
252     within third-party libraries. Just remember to unref after start and ref
253     before stop.
254    
255     =back
256    
257     =head1 ANATOMY OF A WATCHER
258    
259     A watcher is a structure that you create and register to record your
260     interest in some event. For instance, if you want to wait for STDIN to
261     become readable, you would create an ev_io watcher for that:
262    
263     static void my_cb (struct ev_loop *loop, struct ev_io *w, int revents)
264     {
265     ev_io_stop (w);
266     ev_unloop (loop, EVUNLOOP_ALL);
267     }
268    
269     struct ev_loop *loop = ev_default_loop (0);
270     struct ev_io stdin_watcher;
271     ev_init (&stdin_watcher, my_cb);
272     ev_io_set (&stdin_watcher, STDIN_FILENO, EV_READ);
273     ev_io_start (loop, &stdin_watcher);
274     ev_loop (loop, 0);
275    
276     As you can see, you are responsible for allocating the memory for your
277     watcher structures (and it is usually a bad idea to do this on the stack,
278     although this can sometimes be quite valid).
279    
280     Each watcher structure must be initialised by a call to C<ev_init
281     (watcher *, callback)>, which expects a callback to be provided. This
282     callback gets invoked each time the event occurs (or, in the case of io
283     watchers, each time the event loop detects that the file descriptor given
284     is readable and/or writable).
285    
286     Each watcher type has its own C<< ev_<type>_set (watcher *, ...) >> macro
287     with arguments specific to this watcher type. There is also a macro
288     to combine initialisation and setting in one call: C<< ev_<type>_init
289     (watcher *, callback, ...) >>.
290    
291     To make the watcher actually watch out for events, you have to start it
292     with a watcher-specific start function (C<< ev_<type>_start (loop, watcher
293     *) >>), and you can stop watching for events at any time by calling the
294     corresponding stop function (C<< ev_<type>_stop (loop, watcher *) >>.
295    
296     As long as your watcher is active (has been started but not stopped) you
297     must not touch the values stored in it. Most specifically you must never
298     reinitialise it or call its set method.
299    
300 root 1.4 You cna check whether an event is active by calling the C<ev_is_active
301     (watcher *)> macro. To see whether an event is outstanding (but the
302 root 1.1 callback for it has not been called yet) you cna use the C<ev_is_pending
303     (watcher *)> macro.
304    
305     Each and every callback receives the event loop pointer as first, the
306     registered watcher structure as second, and a bitset of received events as
307     third argument.
308    
309     The rceeived events usually include a single bit per event type received
310     (you can receive multiple events at the same time). The possible bit masks
311     are:
312    
313     =over 4
314    
315     =item EV_READ
316    
317     =item EV_WRITE
318    
319     The file descriptor in the ev_io watcher has become readable and/or
320     writable.
321    
322     =item EV_TIMEOUT
323    
324     The ev_timer watcher has timed out.
325    
326     =item EV_PERIODIC
327    
328     The ev_periodic watcher has timed out.
329    
330     =item EV_SIGNAL
331    
332     The signal specified in the ev_signal watcher has been received by a thread.
333    
334     =item EV_CHILD
335    
336     The pid specified in the ev_child watcher has received a status change.
337    
338     =item EV_IDLE
339    
340     The ev_idle watcher has determined that you have nothing better to do.
341    
342     =item EV_PREPARE
343    
344     =item EV_CHECK
345    
346     All ev_prepare watchers are invoked just I<before> C<ev_loop> starts
347     to gather new events, and all ev_check watchers are invoked just after
348     C<ev_loop> has gathered them, but before it invokes any callbacks for any
349     received events. Callbacks of both watcher types can start and stop as
350     many watchers as they want, and all of them will be taken into account
351     (for example, a ev_prepare watcher might start an idle watcher to keep
352     C<ev_loop> from blocking).
353    
354     =item EV_ERROR
355    
356     An unspecified error has occured, the watcher has been stopped. This might
357     happen because the watcher could not be properly started because libev
358     ran out of memory, a file descriptor was found to be closed or any other
359     problem. You best act on it by reporting the problem and somehow coping
360     with the watcher being stopped.
361    
362     Libev will usually signal a few "dummy" events together with an error,
363     for example it might indicate that a fd is readable or writable, and if
364     your callbacks is well-written it can just attempt the operation and cope
365     with the error from read() or write(). This will not work in multithreaded
366     programs, though, so beware.
367    
368     =back
369    
370     =head2 ASSOCIATING CUSTOM DATA WITH A WATCHER
371    
372     Each watcher has, by default, a member C<void *data> that you can change
373     and read at any time, libev will completely ignore it. This cna be used
374     to associate arbitrary data with your watcher. If you need more data and
375     don't want to allocate memory and store a pointer to it in that data
376     member, you can also "subclass" the watcher type and provide your own
377     data:
378    
379     struct my_io
380     {
381     struct ev_io io;
382     int otherfd;
383     void *somedata;
384     struct whatever *mostinteresting;
385     }
386    
387     And since your callback will be called with a pointer to the watcher, you
388     can cast it back to your own type:
389    
390     static void my_cb (struct ev_loop *loop, struct ev_io *w_, int revents)
391     {
392     struct my_io *w = (struct my_io *)w_;
393     ...
394     }
395    
396     More interesting and less C-conformant ways of catsing your callback type
397     have been omitted....
398    
399    
400     =head1 WATCHER TYPES
401    
402     This section describes each watcher in detail, but will not repeat
403     information given in the last section.
404    
405     =head2 struct ev_io - is my file descriptor readable or writable
406    
407 root 1.4 I/O watchers check whether a file descriptor is readable or writable
408 root 1.1 in each iteration of the event loop (This behaviour is called
409     level-triggering because you keep receiving events as long as the
410     condition persists. Remember you cna stop the watcher if you don't want to
411     act on the event and neither want to receive future events).
412    
413     =over 4
414    
415     =item ev_io_init (ev_io *, callback, int fd, int events)
416    
417     =item ev_io_set (ev_io *, int fd, int events)
418    
419     Configures an ev_io watcher. The fd is the file descriptor to rceeive
420     events for and events is either C<EV_READ>, C<EV_WRITE> or C<EV_READ |
421     EV_WRITE> to receive the given events.
422    
423     =back
424    
425     =head2 struct ev_timer - relative and optionally recurring timeouts
426    
427     Timer watchers are simple relative timers that generate an event after a
428     given time, and optionally repeating in regular intervals after that.
429    
430     The timers are based on real time, that is, if you register an event that
431     times out after an hour and youreset your system clock to last years
432     time, it will still time out after (roughly) and hour. "Roughly" because
433     detecting time jumps is hard, and soem inaccuracies are unavoidable (the
434     monotonic clock option helps a lot here).
435    
436     =over 4
437    
438     =item ev_timer_init (ev_timer *, callback, ev_tstamp after, ev_tstamp repeat)
439    
440     =item ev_timer_set (ev_timer *, ev_tstamp after, ev_tstamp repeat)
441    
442     Configure the timer to trigger after C<after> seconds. If C<repeat> is
443     C<0.>, then it will automatically be stopped. If it is positive, then the
444     timer will automatically be configured to trigger again C<repeat> seconds
445     later, again, and again, until stopped manually.
446    
447     The timer itself will do a best-effort at avoiding drift, that is, if you
448     configure a timer to trigger every 10 seconds, then it will trigger at
449     exactly 10 second intervals. If, however, your program cannot keep up with
450     the timer (ecause it takes longer than those 10 seconds to do stuff) the
451     timer will not fire more than once per event loop iteration.
452    
453     =item ev_timer_again (loop)
454    
455     This will act as if the timer timed out and restart it again if it is
456     repeating. The exact semantics are:
457    
458     If the timer is started but nonrepeating, stop it.
459    
460     If the timer is repeating, either start it if necessary (with the repeat
461     value), or reset the running timer to the repeat value.
462    
463     This sounds a bit complicated, but here is a useful and typical
464     example: Imagine you have a tcp connection and you want a so-called idle
465     timeout, that is, you want to be called when there have been, say, 60
466     seconds of inactivity on the socket. The easiest way to do this is to
467     configure an ev_timer with after=repeat=60 and calling ev_timer_again each
468     time you successfully read or write some data. If you go into an idle
469     state where you do not expect data to travel on the socket, you can stop
470     the timer, and again will automatically restart it if need be.
471    
472     =back
473    
474 root 1.3 =head2 ev_periodic - to cron or not to cron it
475 root 1.1
476     Periodic watchers are also timers of a kind, but they are very versatile
477     (and unfortunately a bit complex).
478    
479     Unlike ev_timer's, they are not based on real time (or relative time)
480     but on wallclock time (absolute time). You can tell a periodic watcher
481     to trigger "at" some specific point in time. For example, if you tell a
482     periodic watcher to trigger in 10 seconds (by specifiying e.g. c<ev_now ()
483     + 10.>) and then reset your system clock to the last year, then it will
484     take a year to trigger the event (unlike an ev_timer, which would trigger
485     roughly 10 seconds later and of course not if you reset your system time
486     again).
487    
488     They can also be used to implement vastly more complex timers, such as
489     triggering an event on eahc midnight, local time.
490    
491     =over 4
492    
493     =item ev_periodic_init (ev_periodic *, callback, ev_tstamp at, ev_tstamp interval, reschedule_cb)
494    
495     =item ev_periodic_set (ev_periodic *, ev_tstamp after, ev_tstamp repeat, reschedule_cb)
496    
497     Lots of arguments, lets sort it out... There are basically three modes of
498     operation, and we will explain them from simplest to complex:
499    
500    
501     =over 4
502    
503     =item * absolute timer (interval = reschedule_cb = 0)
504    
505     In this configuration the watcher triggers an event at the wallclock time
506     C<at> and doesn't repeat. It will not adjust when a time jump occurs,
507     that is, if it is to be run at January 1st 2011 then it will run when the
508     system time reaches or surpasses this time.
509    
510     =item * non-repeating interval timer (interval > 0, reschedule_cb = 0)
511    
512     In this mode the watcher will always be scheduled to time out at the next
513     C<at + N * interval> time (for some integer N) and then repeat, regardless
514     of any time jumps.
515    
516     This can be used to create timers that do not drift with respect to system
517     time:
518    
519     ev_periodic_set (&periodic, 0., 3600., 0);
520    
521     This doesn't mean there will always be 3600 seconds in between triggers,
522     but only that the the callback will be called when the system time shows a
523     full hour (UTC), or more correct, when the system time is evenly divisible
524     by 3600.
525    
526     Another way to think about it (for the mathematically inclined) is that
527     ev_periodic will try to run the callback in this mode at the next possible
528     time where C<time = at (mod interval)>, regardless of any time jumps.
529    
530     =item * manual reschedule mode (reschedule_cb = callback)
531    
532     In this mode the values for C<interval> and C<at> are both being
533     ignored. Instead, each time the periodic watcher gets scheduled, the
534     reschedule callback will be called with the watcher as first, and the
535     current time as second argument.
536    
537     NOTE: I<This callback MUST NOT stop or destroy the periodic or any other
538     periodic watcher, ever, or make any event loop modificstions>. If you need
539     to stop it, return 1e30 (or so, fudge fudge) and stop it afterwards.
540    
541     Its prototype is c<ev_tstamp (*reschedule_cb)(struct ev_periodic *w,
542     ev_tstamp now)>, e.g.:
543    
544     static ev_tstamp my_rescheduler (struct ev_periodic *w, ev_tstamp now)
545     {
546     return now + 60.;
547     }
548    
549     It must return the next time to trigger, based on the passed time value
550     (that is, the lowest time value larger than to the second argument). It
551     will usually be called just before the callback will be triggered, but
552     might be called at other times, too.
553    
554     This can be used to create very complex timers, such as a timer that
555     triggers on each midnight, local time. To do this, you would calculate the
556     next midnight after C<now> and return the timestamp value for this. How you do this
557     is, again, up to you (but it is not trivial).
558    
559     =back
560    
561     =item ev_periodic_again (loop, ev_periodic *)
562    
563     Simply stops and restarts the periodic watcher again. This is only useful
564     when you changed some parameters or the reschedule callback would return
565     a different time than the last time it was called (e.g. in a crond like
566     program when the crontabs have changed).
567    
568     =back
569    
570     =head2 ev_signal - signal me when a signal gets signalled
571    
572     Signal watchers will trigger an event when the process receives a specific
573     signal one or more times. Even though signals are very asynchronous, libev
574     will try its best to deliver signals synchronously, i.e. as part of the
575     normal event processing, like any other event.
576    
577     You cna configure as many watchers as you like per signal. Only when the
578     first watcher gets started will libev actually register a signal watcher
579     with the kernel (thus it coexists with your own signal handlers as long
580     as you don't register any with libev). Similarly, when the last signal
581     watcher for a signal is stopped libev will reset the signal handler to
582     SIG_DFL (regardless of what it was set to before).
583    
584     =over 4
585    
586     =item ev_signal_init (ev_signal *, callback, int signum)
587    
588     =item ev_signal_set (ev_signal *, int signum)
589    
590     Configures the watcher to trigger on the given signal number (usually one
591     of the C<SIGxxx> constants).
592    
593     =back
594    
595     =head2 ev_child - wait for pid status changes
596    
597     Child watchers trigger when your process receives a SIGCHLD in response to
598     some child status changes (most typically when a child of yours dies).
599    
600     =over 4
601    
602     =item ev_child_init (ev_child *, callback, int pid)
603    
604     =item ev_child_set (ev_child *, int pid)
605    
606     Configures the watcher to wait for status changes of process C<pid> (or
607     I<any> process if C<pid> is specified as C<0>). The callback can look
608     at the C<rstatus> member of the C<ev_child> watcher structure to see
609     the status word (use the macros from C<sys/wait.h>). The C<rpid> member
610     contains the pid of the process causing the status change.
611    
612     =back
613    
614     =head2 ev_idle - when you've got nothing better to do
615    
616     Idle watchers trigger events when there are no other I/O or timer (or
617     periodic) events pending. That is, as long as your process is busy
618     handling sockets or timeouts it will not be called. But when your process
619     is idle all idle watchers are being called again and again - until
620     stopped, that is, or your process receives more events.
621    
622     The most noteworthy effect is that as long as any idle watchers are
623     active, the process will not block when waiting for new events.
624    
625     Apart from keeping your process non-blocking (which is a useful
626     effect on its own sometimes), idle watchers are a good place to do
627     "pseudo-background processing", or delay processing stuff to after the
628     event loop has handled all outstanding events.
629    
630     =over 4
631    
632     =item ev_idle_init (ev_signal *, callback)
633    
634     Initialises and configures the idle watcher - it has no parameters of any
635     kind. There is a C<ev_idle_set> macro, but using it is utterly pointless,
636     believe me.
637    
638     =back
639    
640     =head2 prepare and check - your hooks into the event loop
641    
642     Prepare and check watchers usually (but not always) are used in
643     tandom. Prepare watchers get invoked before the process blocks and check
644     watchers afterwards.
645    
646     Their main purpose is to integrate other event mechanisms into libev. This
647     could be used, for example, to track variable changes, implement your own
648     watchers, integrate net-snmp or a coroutine library and lots more.
649    
650     This is done by examining in each prepare call which file descriptors need
651     to be watched by the other library, registering ev_io watchers for them
652     and starting an ev_timer watcher for any timeouts (many libraries provide
653     just this functionality). Then, in the check watcher you check for any
654     events that occured (by making your callbacks set soem flags for example)
655     and call back into the library.
656    
657     As another example, the perl Coro module uses these hooks to integrate
658     coroutines into libev programs, by yielding to other active coroutines
659     during each prepare and only letting the process block if no coroutines
660     are ready to run.
661    
662     =over 4
663    
664     =item ev_prepare_init (ev_prepare *, callback)
665    
666     =item ev_check_init (ev_check *, callback)
667    
668     Initialises and configures the prepare or check watcher - they have no
669     parameters of any kind. There are C<ev_prepare_set> and C<ev_check_set>
670     macros, but using them is utterly, utterly pointless.
671    
672     =back
673    
674     =head1 OTHER FUNCTIONS
675    
676     There are some other fucntions of possible interest. Described. Here. Now.
677    
678     =over 4
679    
680     =item ev_once (loop, int fd, int events, ev_tstamp timeout, callback)
681    
682     This function combines a simple timer and an I/O watcher, calls your
683     callback on whichever event happens first and automatically stop both
684     watchers. This is useful if you want to wait for a single event on an fd
685     or timeout without havign to allocate/configure/start/stop/free one or
686     more watchers yourself.
687    
688     If C<fd> is less than 0, then no I/O watcher will be started and events is
689     ignored. Otherwise, an ev_io watcher for the given C<fd> and C<events> set
690     will be craeted and started.
691    
692     If C<timeout> is less than 0, then no timeout watcher will be
693     started. Otherwise an ev_timer watcher with after = C<timeout> (and repeat
694     = 0) will be started.
695    
696     The callback has the type C<void (*cb)(int revents, void *arg)> and
697     gets passed an events set (normally a combination of EV_ERROR, EV_READ,
698     EV_WRITE or EV_TIMEOUT) and the C<arg> value passed to C<ev_once>:
699    
700     static void stdin_ready (int revents, void *arg)
701     {
702     if (revents & EV_TIMEOUT)
703     /* doh, nothing entered */
704     else if (revents & EV_READ)
705     /* stdin might have data for us, joy! */
706     }
707    
708     ev_once (STDIN_FILENO, EV_READm 10., stdin_ready, 0);
709    
710     =item ev_feed_event (loop, watcher, int events)
711    
712     Feeds the given event set into the event loop, as if the specified event
713     has happened for the specified watcher (which must be a pointer to an
714     initialised but not necessarily active event watcher).
715    
716     =item ev_feed_fd_event (loop, int fd, int revents)
717    
718     Feed an event on the given fd, as if a file descriptor backend detected it.
719    
720     =item ev_feed_signal_event (loop, int signum)
721    
722     Feed an event as if the given signal occured (loop must be the default loop!).
723    
724     =back
725    
726     =head1 AUTHOR
727    
728     Marc Lehmann <libev@schmorp.de>.
729