--- libev/ev.pod 2007/11/12 09:01:12 1.18 +++ libev/ev.pod 2008/01/28 12:13:54 1.121 @@ -6,10 +6,56 @@ #include +=head2 EXAMPLE PROGRAM + + #include + + ev_io stdin_watcher; + ev_timer timeout_watcher; + + /* called when data readable on stdin */ + static void + stdin_cb (EV_P_ struct ev_io *w, int revents) + { + /* puts ("stdin ready"); */ + ev_io_stop (EV_A_ w); /* just a syntax example */ + ev_unloop (EV_A_ EVUNLOOP_ALL); /* leave all loop calls */ + } + + static void + timeout_cb (EV_P_ struct ev_timer *w, int revents) + { + /* puts ("timeout"); */ + ev_unloop (EV_A_ EVUNLOOP_ONE); /* leave one loop call */ + } + + int + main (void) + { + struct ev_loop *loop = ev_default_loop (0); + + /* initialise an io watcher, then start it */ + ev_io_init (&stdin_watcher, stdin_cb, /*STDIN_FILENO*/ 0, EV_READ); + ev_io_start (loop, &stdin_watcher); + + /* simple non-repeating 5.5 second timeout */ + ev_timer_init (&timeout_watcher, timeout_cb, 5.5, 0.); + ev_timer_start (loop, &timeout_watcher); + + /* loop till timeout or data ready */ + ev_loop (loop, 0); + + return 0; + } + =head1 DESCRIPTION +The newest version of this document is also available as a html-formatted +web page you might find easier to navigate when reading it for the first +time: L. + Libev is an event loop: you register interest in certain events (such as a -file descriptor being readable or a timeout occuring), and it will manage +file descriptor being readable or a timeout occurring), and it will manage these event sources and provide your program with events. To do this, it must take more or less complete control over your process @@ -21,33 +67,42 @@ details of the event, and then hand it over to libev by I the watcher. -=head1 FEATURES +=head2 FEATURES -Libev supports select, poll, the linux-specific epoll and the bsd-specific -kqueue mechanisms for file descriptor events, relative timers, absolute -timers with customised rescheduling, signal events, process status change -events (related to SIGCHLD), and event watchers dealing with the event -loop mechanism itself (idle, prepare and check watchers). It also is quite -fast (see this L comparing -it to libevent for example). - -=head1 CONVENTIONS - -Libev is very configurable. In this manual the default configuration -will be described, which supports multiple event loops. For more info -about various configuration options please have a look at the file -F in the libev distribution. If libev was configured without -support for multiple event loops, then all functions taking an initial -argument of name C (which is always of type C) -will not have this argument. +Libev supports C which have a high +overhead for the actual polling but can deliver many events at once. + +By setting a higher I you allow libev to spend more +time collecting I/O events, so you can handle more events per iteration, +at the cost of increasing latency. Timeouts (both C and +C) will be not affected. Setting this to a non-null value will +introduce an additional C call into most loop iterations. + +Likewise, by setting a higher I you allow libev +to spend more time collecting timeouts, at the expense of increased +latency (the watcher callback will be called later). C watchers +will not be affected. Setting this to a non-null value will not introduce +any overhead in libev. + +Many (busy) programs can usually benefit by setting the io collect +interval to a value near C<0.1> or so, which is often enough for +interactive servers (of course not for games), likewise for timeouts. It +usually doesn't make much sense to set it to a lower value than C<0.01>, +as this approsaches the timing granularity of most systems. =back + =head1 ANATOMY OF A WATCHER A watcher is a structure that you create and register to record your @@ -304,12 +712,7 @@ As long as your watcher is active (has been started but not stopped) you must not touch the values stored in it. Most specifically you must never -reinitialise it or call its set method. - -You can check whether an event is active by calling the C macro. To see whether an event is outstanding (but the -callback for it has not been called yet) you can use the C macro. +reinitialise it or call its C macro. Each and every callback receives the event loop pointer as first, the registered watcher structure as second, and a bitset of received events as @@ -344,6 +747,10 @@ The pid specified in the C watcher has received a status change. +=item C + +The path specified in the C watcher changed its attributes somehow. + =item C The C watcher has determined that you have nothing better to do. @@ -360,6 +767,15 @@ (for example, a C watcher might start an idle watcher to keep C from blocking). +=item C + +The embedded event loop specified in the C watcher needs attention. + +=item C + +The event loop has been resumed in the child process after fork (see +C). + =item C An unspecified error has occured, the watcher has been stopped. This might @@ -376,6 +792,126 @@ =back +=head2 GENERIC WATCHER FUNCTIONS + +In the following description, C stands for the watcher type, +e.g. C for C watchers and C for C watchers. + +=over 4 + +=item C (ev_TYPE *watcher, callback) + +This macro initialises the generic portion of a watcher. The contents +of the watcher object can be arbitrary (so C will do). Only +the generic parts of the watcher are initialised, you I to call +the type-specific C macro afterwards to initialise the +type-specific parts. For each type there is also a C macro +which rolls both calls into one. + +You can reinitialise a watcher at any time as long as it has been stopped +(or never started) and there are no pending events outstanding. + +The callback is always of type C. + +=item C (ev_TYPE *, [args]) + +This macro initialises the type-specific parts of a watcher. You need to +call C at least once before you call this macro, but you can +call C any number of times. You must not, however, call this +macro on a watcher that is active (it can be pending, however, which is a +difference to the C macro). + +Although some watcher types do not have type-specific arguments +(e.g. C) you still need to call its C macro. + +=item C (ev_TYPE *watcher, callback, [args]) + +This convinience macro rolls both C and C macro +calls into a single call. This is the most convinient method to initialise +a watcher. The same limitations apply, of course. + +=item C (loop *, ev_TYPE *watcher) + +Starts (activates) the given watcher. Only active watchers will receive +events. If the watcher is already active nothing will happen. + +=item C (loop *, ev_TYPE *watcher) + +Stops the given watcher again (if active) and clears the pending +status. It is possible that stopped watchers are pending (for example, +non-repeating timers are being stopped when they become pending), but +C ensures that the watcher is neither active nor pending. If +you want to free or reuse the memory used by the watcher it is therefore a +good idea to always call its C function. + +=item bool ev_is_active (ev_TYPE *watcher) + +Returns a true value iff the watcher is active (i.e. it has been started +and not yet been stopped). As long as a watcher is active you must not modify +it. + +=item bool ev_is_pending (ev_TYPE *watcher) + +Returns a true value iff the watcher is pending, (i.e. it has outstanding +events but its callback has not yet been invoked). As long as a watcher +is pending (but not active) you must not call an init function on it (but +C is safe), you must not change its priority, and you must +make sure the watcher is available to libev (e.g. you cannot C +it). + +=item callback ev_cb (ev_TYPE *watcher) + +Returns the callback currently set on the watcher. + +=item ev_cb_set (ev_TYPE *watcher, callback) + +Change the callback. You can change the callback at virtually any time +(modulo threads). + +=item ev_set_priority (ev_TYPE *watcher, priority) + +=item int ev_priority (ev_TYPE *watcher) + +Set and query the priority of the watcher. The priority is a small +integer between C (default: C<2>) and C +(default: C<-2>). Pending watchers with higher priority will be invoked +before watchers with lower priority, but priority will not keep watchers +from being executed (except for C watchers). + +This means that priorities are I used for ordering callback +invocation after new events have been received. This is useful, for +example, to reduce latency after idling, or more often, to bind two +watchers on the same event and make sure one is called first. + +If you need to suppress invocation when higher priority events are pending +you need to look at C watchers, which provide this functionality. + +You I change the priority of a watcher as long as it is active or +pending. + +The default priority used by watchers when no priority has been set is +always C<0>, which is supposed to not be too high and not be too low :). + +Setting a priority outside the range of C to C is +fine, as long as you do not mind that the priority value you query might +or might not have been adjusted to be within valid range. + +=item ev_invoke (loop, ev_TYPE *watcher, int revents) + +Invoke the C with the given C and C. Neither +C nor C need to be valid as long as the watcher callback +can deal with that fact. + +=item int ev_clear_pending (loop, ev_TYPE *watcher) + +If the watcher is pending, this function returns clears its pending status +and returns its C bitset (as if its callback was invoked). If the +watcher isn't pending it does nothing and returns C<0>. + +=back + + =head2 ASSOCIATING CUSTOM DATA WITH A WATCHER Each watcher has, by default, a member C that you can change @@ -402,36 +938,134 @@ ... } -More interesting and less C-conformant ways of catsing your callback type -have been omitted.... +More interesting and less C-conformant ways of casting your callback type +instead have been omitted. + +Another common scenario is having some data structure with multiple +watchers: + + struct my_biggy + { + int some_data; + ev_timer t1; + ev_timer t2; + } + +In this case getting the pointer to C is a bit more complicated, +you need to use C: + + #include + + static void + t1_cb (EV_P_ struct ev_timer *w, int revents) + { + struct my_biggy big = (struct my_biggy * + (((char *)w) - offsetof (struct my_biggy, t1)); + } + + static void + t2_cb (EV_P_ struct ev_timer *w, int revents) + { + struct my_biggy big = (struct my_biggy * + (((char *)w) - offsetof (struct my_biggy, t2)); + } =head1 WATCHER TYPES This section describes each watcher in detail, but will not repeat -information given in the last section. +information given in the last section. Any initialisation/set macros, +functions and members specific to the watcher type are explained. + +Members are additionally marked with either I<[read-only]>, meaning that, +while the watcher is active, you can look at the member and expect some +sensible content, but you must not modify it (you can modify it while the +watcher is stopped to your hearts content), or I<[read-write]>, which +means you can expect it to have some sensible content while the watcher +is active, but you can also modify it. Modifying it may not do something +sensible or take immediate effect (or do anything at all), but libev will +not crash or malfunction in any way. -=head2 C - is this file descriptor readable or writable + +=head2 C - is this file descriptor readable or writable? I/O watchers check whether a file descriptor is readable or writable -in each iteration of the event loop (This behaviour is called -level-triggering because you keep receiving events as long as the -condition persists. Remember you can stop the watcher if you don't want to -act on the event and neither want to receive future events). +in each iteration of the event loop, or, more precisely, when reading +would not block the process and writing would at least be able to write +some data. This behaviour is called level-triggering because you keep +receiving events as long as the condition persists. Remember you can stop +the watcher if you don't want to act on the event and neither want to +receive future events. -In general you can register as many read and/or write event watchers oer +In general you can register as many read and/or write event watchers per fd as you want (as long as you don't confuse yourself). Setting all file descriptors to non-blocking mode is also usually a good idea (but not required if you know what you are doing). -You have to be careful with dup'ed file descriptors, though. Some backends -(the linux epoll backend is a notable example) cannot handle dup'ed file -descriptors correctly if you register interest in two or more fds pointing -to the same file/socket etc. description. - If you must do this, then force the use of a known-to-be-good backend -(at the time of this writing, this includes only EVMETHOD_SELECT and -EVMETHOD_POLL). +(at the time of this writing, this includes only C and +C). + +Another thing you have to watch out for is that it is quite easy to +receive "spurious" readyness notifications, that is your callback might +be called with C but a subsequent C(2) will actually block +because there is no data. Not only are some backends known to create a +lot of those (for example solaris ports), it is very easy to get into +this situation even with a relatively standard program structure. Thus +it is best to always use non-blocking I/O: An extra C(2) returning +C is far preferable to a program hanging until some data arrives. + +If you cannot run the fd in non-blocking mode (for example you should not +play around with an Xlib connection), then you have to seperately re-test +whether a file descriptor is really ready with a known-to-be good interface +such as poll (fortunately in our Xlib example, Xlib already does this on +its own, so its quite safe to use). + +=head3 The special problem of disappearing file descriptors + +Some backends (e.g. kqueue, epoll) need to be told about closing a file +descriptor (either by calling C explicitly or by any other means, +such as C). The reason is that you register interest in some file +descriptor, but when it goes away, the operating system will silently drop +this interest. If another file descriptor with the same number then is +registered with libev, there is no efficient way to see that this is, in +fact, a different file descriptor. + +To avoid having to explicitly tell libev about such cases, libev follows +the following policy: Each time C is being called, libev +will assume that this is potentially a new file descriptor, otherwise +it is assumed that the file descriptor stays the same. That means that +you I to call C (or C) when you change the +descriptor even if the file descriptor number itself did not change. + +This is how one would do it normally anyway, the important point is that +the libev application should not optimise around libev but should leave +optimisations to libev. + +=head3 The special problem of dup'ed file descriptors + +Some backends (e.g. epoll), cannot register events for file descriptors, +but only events for the underlying file descriptions. That means when you +have C'ed file descriptors or weirder constellations, and register +events for them, only one file descriptor might actually receive events. + +There is no workaround possible except not registering events +for potentially C'ed file descriptors, or to resort to +C or C. + +=head3 The special problem of fork + +Some backends (epoll, kqueue) do not support C at all or exhibit +useless behaviour. Libev fully supports fork, but needs to be told about +it in the child. + +To support fork in your programs, you either have to call +C or C after a fork in the child, +enable C, or resort to C or +C. + + +=head3 Watcher-Specific Functions =over 4 @@ -439,31 +1073,66 @@ =item ev_io_set (ev_io *, int fd, int events) -Configures an C watcher. The fd is the file descriptor to rceeive -events for and events is either C, C or C to receive the given events. +Configures an C watcher. The C is the file descriptor to +rceeive events for and events is either C, C or +C to receive the given events. + +=item int fd [read-only] + +The file descriptor being watched. + +=item int events [read-only] + +The events being watched. =back -=head2 C - relative and optionally recurring timeouts +=head3 Examples + +Example: Call C when STDIN_FILENO has become, well +readable, but only once. Since it is likely line-buffered, you could +attempt to read a whole line in the callback. + + static void + stdin_readable_cb (struct ev_loop *loop, struct ev_io *w, int revents) + { + ev_io_stop (loop, w); + .. read from stdin here (or from w->fd) and haqndle any I/O errors + } + + ... + struct ev_loop *loop = ev_default_init (0); + struct ev_io stdin_readable; + ev_io_init (&stdin_readable, stdin_readable_cb, STDIN_FILENO, EV_READ); + ev_io_start (loop, &stdin_readable); + ev_loop (loop, 0); + + +=head2 C - relative and optionally repeating timeouts Timer watchers are simple relative timers that generate an event after a given time, and optionally repeating in regular intervals after that. The timers are based on real time, that is, if you register an event that -times out after an hour and youreset your system clock to last years +times out after an hour and you reset your system clock to last years time, it will still time out after (roughly) and hour. "Roughly" because -detecting time jumps is hard, and soem inaccuracies are unavoidable (the +detecting time jumps is hard, and some inaccuracies are unavoidable (the monotonic clock option helps a lot here). The relative timeouts are calculated relative to the C time. This is usually the right thing as this timestamp refers to the time -of the event triggering whatever timeout you are modifying/starting. If -you suspect event processing to be delayed and you *need* to base the timeout -ion the current time, use something like this to adjust for this: +of the event triggering whatever timeout you are modifying/starting. If +you suspect event processing to be delayed and you I to base the timeout +on the current time, use something like this to adjust for this: ev_timer_set (&timer, after + ev_now () - ev_time (), 0.); +The callback is guarenteed to be invoked only when its timeout has passed, +but if multiple timers become ready during the same loop iteration then +order of execution is undefined. + +=head3 Watcher-Specific Functions and Data Members + =over 4 =item ev_timer_init (ev_timer *, callback, ev_tstamp after, ev_tstamp repeat) @@ -478,7 +1147,7 @@ The timer itself will do a best-effort at avoiding drift, that is, if you configure a timer to trigger every 10 seconds, then it will trigger at exactly 10 second intervals. If, however, your program cannot keep up with -the timer (ecause it takes longer than those 10 seconds to do stuff) the +the timer (because it takes longer than those 10 seconds to do stuff) the timer will not fire more than once per event loop iteration. =item ev_timer_again (loop) @@ -486,23 +1155,80 @@ This will act as if the timer timed out and restart it again if it is repeating. The exact semantics are: -If the timer is started but nonrepeating, stop it. +If the timer is pending, its pending status is cleared. + +If the timer is started but nonrepeating, stop it (as if it timed out). -If the timer is repeating, either start it if necessary (with the repeat -value), or reset the running timer to the repeat value. +If the timer is repeating, either start it if necessary (with the +C value), or reset the running timer to the C value. This sounds a bit complicated, but here is a useful and typical example: Imagine you have a tcp connection and you want a so-called idle timeout, that is, you want to be called when there have been, say, 60 seconds of inactivity on the socket. The easiest way to do this is to -configure an C with after=repeat=60 and calling ev_timer_again each -time you successfully read or write some data. If you go into an idle -state where you do not expect data to travel on the socket, you can stop -the timer, and again will automatically restart it if need be. +configure an C with a C value of C<60> and then call +C each time you successfully read or write some data. If +you go into an idle state where you do not expect data to travel on the +socket, you can C the timer, and C will +automatically restart it if need be. + +That means you can ignore the C value and C +altogether and only ever use the C value and C: + + ev_timer_init (timer, callback, 0., 5.); + ev_timer_again (loop, timer); + ... + timer->again = 17.; + ev_timer_again (loop, timer); + ... + timer->again = 10.; + ev_timer_again (loop, timer); + +This is more slightly efficient then stopping/starting the timer each time +you want to modify its timeout value. + +=item ev_tstamp repeat [read-write] + +The current C value. Will be used each time the watcher times out +or C is called and determines the next timeout (if any), +which is also when any modifications are taken into account. =back -=head2 C - to cron or not to cron +=head3 Examples + +Example: Create a timer that fires after 60 seconds. + + static void + one_minute_cb (struct ev_loop *loop, struct ev_timer *w, int revents) + { + .. one minute over, w is actually stopped right here + } + + struct ev_timer mytimer; + ev_timer_init (&mytimer, one_minute_cb, 60., 0.); + ev_timer_start (loop, &mytimer); + +Example: Create a timeout timer that times out after 10 seconds of +inactivity. + + static void + timeout_cb (struct ev_loop *loop, struct ev_timer *w, int revents) + { + .. ten seconds without any activity + } + + struct ev_timer mytimer; + ev_timer_init (&mytimer, timeout_cb, 0., 10.); /* note, only repeat used */ + ev_timer_again (&mytimer); /* start timer */ + ev_loop (loop, 0); + + // and in some piece of code that gets executed on any "activity": + // reset the timeout to start ticking again at 10 seconds + ev_timer_again (&mytimer); + + +=head2 C - to cron or not to cron? Periodic watchers are also timers of a kind, but they are very versatile (and unfortunately a bit complex). @@ -510,14 +1236,20 @@ Unlike C's, they are not based on real time (or relative time) but on wallclock time (absolute time). You can tell a periodic watcher to trigger "at" some specific point in time. For example, if you tell a -periodic watcher to trigger in 10 seconds (by specifiying e.g. c) and then reset your system clock to the last year, then it will take a year to trigger the event (unlike an C, which would trigger -roughly 10 seconds later and of course not if you reset your system time -again). +roughly 10 seconds later). They can also be used to implement vastly more complex timers, such as -triggering an event on eahc midnight, local time. +triggering an event on each midnight, local time or other, complicated, +rules. + +As with timers, the callback is guarenteed to be invoked only when the +time (C) has been passed, but if multiple periodic timers become ready +during the same loop iteration then order of execution is undefined. + +=head3 Watcher-Specific Functions and Data Members =over 4 @@ -528,21 +1260,20 @@ Lots of arguments, lets sort it out... There are basically three modes of operation, and we will explain them from simplest to complex: - =over 4 -=item * absolute timer (interval = reschedule_cb = 0) +=item * absolute timer (at = time, interval = reschedule_cb = 0) In this configuration the watcher triggers an event at the wallclock time C and doesn't repeat. It will not adjust when a time jump occurs, that is, if it is to be run at January 1st 2011 then it will run when the system time reaches or surpasses this time. -=item * non-repeating interval timer (interval > 0, reschedule_cb = 0) +=item * non-repeating interval timer (at = offset, interval > 0, reschedule_cb = 0) In this mode the watcher will always be scheduled to time out at the next -C time (for some integer N) and then repeat, regardless -of any time jumps. +C time (for some integer N, which can also be negative) +and then repeat, regardless of any time jumps. This can be used to create timers that do not drift with respect to system time: @@ -558,7 +1289,11 @@ C will try to run the callback in this mode at the next possible time where C