--- libev/ev.pod 2008/02/20 17:45:29 1.132 +++ libev/ev.pod 2008/05/22 02:44:57 1.159 @@ -8,51 +8,65 @@ =head2 EXAMPLE PROGRAM + // a single header file is required #include + // every watcher type has its own typedef'd struct + // with the name ev_ ev_io stdin_watcher; ev_timer timeout_watcher; - /* called when data readable on stdin */ + // all watcher callbacks have a similar signature + // this callback is called when data is 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 */ + puts ("stdin ready"); + // for one-shot events, one must manually stop the watcher + // with its corresponding stop function. + ev_io_stop (EV_A_ w); + + // this causes all nested ev_loop's to stop iterating + ev_unloop (EV_A_ EVUNLOOP_ALL); } + // another callback, this time for a time-out static void timeout_cb (EV_P_ struct ev_timer *w, int revents) { - /* puts ("timeout"); */ - ev_unloop (EV_A_ EVUNLOOP_ONE); /* leave one loop call */ + puts ("timeout"); + // this causes the innermost ev_loop to stop iterating + ev_unloop (EV_A_ EVUNLOOP_ONE); } int main (void) { + // use the default event loop unless you have special needs struct ev_loop *loop = ev_default_loop (0); - /* initialise an io watcher, then start it */ + // initialise an io watcher, then start it + // this one will watch for stdin to become readable 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 */ + // initialise a timer watcher, then start it + // 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 */ + // now wait for events to arrive ev_loop (loop, 0); + // unloop was called, so exit return 0; } =head1 DESCRIPTION -The newest version of this document is also available as a html-formatted +The newest version of this document is also available as an html-formatted web page you might find easier to navigate when reading it for the first -time: L. +time: L. Libev is an event loop: you register interest in certain events (such as a file descriptor being readable or a timeout occurring), and it will manage @@ -86,12 +100,13 @@ =head2 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 B section in -this manual. 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 is very configurable. In this manual the default (and most common) +configuration will be described, which supports multiple event loops. For +more info about various configuration options please have a look at +B section in this manual. 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. =head2 TIME REPRESENTATION @@ -183,18 +198,21 @@ =item ev_set_allocator (void *(*cb)(void *ptr, long size)) Sets the allocation function to use (the prototype is similar - the -semantics is identical - to the realloc C function). It is used to -allocate and free memory (no surprises here). If it returns zero when -memory needs to be allocated, the library might abort or take some -potentially destructive action. The default is your system realloc -function. +semantics are identical to the C C89/SuS/POSIX function). It is +used to allocate and free memory (no surprises here). If it returns zero +when memory needs to be allocated (C), the library might abort +or take some potentially destructive action. + +Since some systems (at least OpenBSD and Darwin) fail to implement +correct C semantics, libev will use a wrapper around the system +C and C functions by default. You could override this function in high-availability programs to, say, free some memory if it cannot allocate memory, to use a special allocator, or even to sleep a while and retry until some memory is available. Example: Replace the libev allocator with one that waits a bit and then -retries). +retries (example requires a standards-compliant C). static void * persistent_realloc (void *ptr, size_t size) @@ -243,13 +261,6 @@ types of such loops, the I loop, which supports signals and child events, and dynamically created loops which do not. -If you use threads, a common model is to run the default event loop -in your main thread (or in a separate thread) and for each thread you -create, you also create another event loop. Libev itself does no locking -whatsoever, so if you mix calls to the same event loop in different -threads, make sure you lock (this is usually a bad idea, though, even if -done correctly, because it's hideous and inefficient). - =over 4 =item struct ev_loop *ev_default_loop (unsigned int flags) @@ -262,6 +273,10 @@ If you don't know what event loop to use, use the one returned from this function. +Note that this function is I thread-safe, so if you want to use it +from multiple threads, you have to lock (note also that this is unlikely, +as loops cannot bes hared easily between threads anyway). + The default loop is the only loop that can handle C and C watchers, and to do this, it always registers a handler for C. If this is a problem for your app you can either @@ -299,8 +314,8 @@ This works by calling C on every iteration of the loop, and thus this might slow down your event loop if you do a lot of loop iterations and little real work, but is usually not noticeable (on my -Linux system for example, C is actually a simple 5-insn sequence -without a syscall and thus I fast, but my Linux system also has +GNU/Linux system for example, C is actually a simple 5-insn sequence +without a syscall and thus I fast, but my GNU/Linux system also has C which is even faster). The big advantage of this flag is that you can forget about fork (and @@ -323,7 +338,7 @@ writing a server, you should C in a loop to accept as many connections as possible during one iteration. You might also want to have a look at C to increase the amount of -readyness notifications you get per iteration. +readiness notifications you get per iteration. =item C (value 2, poll backend, available everywhere except on windows) @@ -341,7 +356,7 @@ like O(total_fds) where n is the total number of fds (or the highest fd), epoll scales either O(1) or O(active_fds). The epoll design has a number of shortcomings, such as silently dropping events in some hard-to-detect -cases and rewiring a syscall per fd change, no fork support and bad +cases and requiring a syscall per fd change, no fork support and bad support for dup. While stopping, setting and starting an I/O watcher in the same iteration @@ -412,7 +427,7 @@ descriptors a "slow" C or C backend might perform better. -On the positive side, ignoring the spurious readyness notifications, this +On the positive side, ignoring the spurious readiness notifications, this backend actually performed to specification in all tests and is fully embeddable, which is a rare feat among the OS-specific backends. @@ -453,6 +468,10 @@ handle signal and child watchers, and attempts to do so will be greeted by undefined behaviour (or a failed assertion if assertions are enabled). +Note that this function I thread-safe, and the recommended way to use +libev with threads is indeed to create one loop per thread, and using the +default loop in the "main" or "initial" thread. + Example: Try to create a event loop that uses epoll and nothing else. struct ev_loop *epoller = ev_loop_new (EVBACKEND_EPOLL | EVFLAG_NOENV); @@ -672,6 +691,17 @@ 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. +=item ev_loop_verify (loop) + +This function only does something when C support has been +compiled in. It tries to go through all internal structures and checks +them for validity. If anything is found to be inconsistent, it will print +an error message to standard error and call C. + +This can be used to catch bugs inside libev itself: under normal +circumstances, this function will never abort as of course libev keeps its +data structures consistent. + =back @@ -1015,7 +1045,7 @@ 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 +receive "spurious" readiness 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 @@ -1072,6 +1102,18 @@ enable C, or resort to C or C. +=head3 The special problem of SIGPIPE + +While not really specific to libev, it is easy to forget about SIGPIPE: +when reading from a pipe whose other end has been closed, your program +gets send a SIGPIPE, which, by default, aborts your program. For most +programs this is sensible behaviour, for daemons, this is usually +undesirable. + +So when you encounter spurious, unexplained daemon exits, make sure you +ignore SIGPIPE (and maybe make sure you log the exit status of your daemon +somewhere, as that would have given you a big clue). + =head3 Watcher-Specific Functions @@ -1122,8 +1164,8 @@ 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 you reset your system clock to last years -time, it will still time out after (roughly) and hour. "Roughly" because +times out after an hour and you reset your system clock to january last +year, it will still time out after (roughly) and hour. "Roughly" because detecting time jumps is hard, and some inaccuracies are unavoidable (the monotonic clock option helps a lot here). @@ -1135,7 +1177,7 @@ ev_timer_set (&timer, after + ev_now () - ev_time (), 0.); -The callback is guarenteed to be invoked only when its timeout has passed, +The callback is guarenteed to be invoked only after its timeout has passed, but if multiple timers become ready during the same loop iteration then order of execution is undefined. @@ -1147,16 +1189,17 @@ =item ev_timer_set (ev_timer *, ev_tstamp after, ev_tstamp repeat) -Configure the timer to trigger after C seconds. If C is -C<0.>, then it will automatically be stopped. If it is positive, then the -timer will automatically be configured to trigger again C seconds -later, again, and again, until stopped manually. - -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 (because it takes longer than those 10 seconds to do stuff) the -timer will not fire more than once per event loop iteration. +Configure the timer to trigger after C seconds. If C +is C<0.>, then it will automatically be stopped once the timeout is +reached. If it is positive, then the timer will automatically be +configured to trigger again C seconds later, again, and again, +until stopped manually. + +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 normally +trigger at exactly 10 second intervals. If, however, your program cannot +keep up with 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, ev_timer *) @@ -1243,18 +1286,19 @@ 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 +to trigger after 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). - -They can also be used to implement vastly more complex timers, such as -triggering an event on each midnight, local time or other, complicated, -rules. ++ 10.>, that is, an absolute time not a delay) and then reset your system +clock to january of the previous year, then it will take more than year +to trigger the event (unlike an C, which would still trigger +roughly 10 seconds later as it uses a relative timeout). + +Cs can also be used to implement vastly more complex timers, +such as 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 +time (C) has 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 @@ -1272,10 +1316,10 @@ =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. +In this configuration the watcher triggers an event after the wallclock +time C has passed 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 * repeating interval timer (at = offset, interval > 0, reschedule_cb = 0) @@ -1284,7 +1328,8 @@ and then repeat, regardless of any time jumps. This can be used to create timers that do not drift with respect to system -time: +time, for example, here is a C that triggers each hour, on +the hour: ev_periodic_set (&periodic, 0., 3600., 0); @@ -1299,7 +1344,12 @@ For numerical stability it is preferable that the C value is near C (the current time), but there is no range requirement for -this value. +this value, and in fact is often specified as zero. + +Note also that there is an upper limit to how often a timer can fire (cpu +speed for example), so if C is very small then timing stability +will of course detoriate. Libev itself tries to be exact to be about one +millisecond (if the OS supports it and the machine is fast enough). =item * manual reschedule mode (at and interval ignored, reschedule_cb = callback) @@ -1309,12 +1359,14 @@ current time as second argument. NOTE: I. If you need to stop it, -return C (or so, fudge fudge) and stop it afterwards (e.g. by -starting an C watcher, which is legal). +ever, or make ANY event loop modifications whatsoever>. + +If you need to stop it, return C (or so, fudge fudge) and stop +it afterwards (e.g. by starting an C watcher, which is the +only event loop modification you are allowed to do). -Its prototype is C, e.g.: +The callback prototype is C, e.g.: static ev_tstamp my_rescheduler (struct ev_periodic *w, ev_tstamp now) { @@ -1326,11 +1378,11 @@ will usually be called just before the callback will be triggered, but might be called at other times, too. -NOTE: I<< This callback must always return a time that is later than the -passed C value >>. Not even C itself will do, it I be larger. +NOTE: I<< This callback must always return a time that is higher than or +equal to the passed C value >>. This can be used to create very complex timers, such as a timer that -triggers on each midnight, local time. To do this, you would calculate the +triggers on "next midnight, local time". To do this, you would calculate the next midnight after C and return the timestamp value for this. How you do this is, again, up to you (but it is not trivial, which is the main reason I omitted it as an example). @@ -1344,6 +1396,11 @@ a different time than the last time it was called (e.g. in a crond like program when the crontabs have changed). +=item ev_tstamp ev_periodic_at (ev_periodic *) + +When active, returns the absolute time that the watcher is supposed to +trigger next. + =item ev_tstamp offset [read-write] When repeating, this contains the offset value, otherwise this is the @@ -1364,11 +1421,6 @@ switched off. Can be changed any time, but changes only take effect when the periodic timer fires or C is being called. -=item ev_tstamp at [read-only] - -When active, contains the absolute time that the watcher is supposed to -trigger next. - =back =head3 Examples @@ -1421,6 +1473,12 @@ watcher for a signal is stopped libev will reset the signal handler to SIG_DFL (regardless of what it was set to before). +If possible and supported, libev will install its handlers with +C behaviour enabled, so syscalls should not be unduly +interrupted. If you have a problem with syscalls getting interrupted by +signals you can block all signals in an C watcher and unblock +them in an C watcher. + =head3 Watcher-Specific Functions and Data Members =over 4 @@ -1456,7 +1514,32 @@ =head2 C - watch out for process status changes Child watchers trigger when your process receives a SIGCHLD in response to -some child status changes (most typically when a child of yours dies). +some child status changes (most typically when a child of yours dies). It +is permissible to install a child watcher I the child has been +forked (which implies it might have already exited), as long as the event +loop isn't entered (or is continued from a watcher). + +Only the default event loop is capable of handling signals, and therefore +you can only rgeister child watchers in the default event loop. + +=head3 Process Interaction + +Libev grabs C as soon as the default event loop is +initialised. This is necessary to guarantee proper behaviour even if +the first child watcher is started after the child exits. The occurance +of C is recorded asynchronously, but child reaping is done +synchronously as part of the event loop processing. Libev always reaps all +children, even ones not watched. + +=head3 Overriding the Built-In Processing + +Libev offers no special support for overriding the built-in child +processing, but if your application collides with libev's default child +handler, you can override it easily by installing your own handler for +C after initialising the default loop, and making sure the +default loop never gets destroyed. You are encouraged, however, to use an +event-based approach to child reaping and thus use libev's support for +that, so other libev users can use C watchers freely. =head3 Watcher-Specific Functions and Data Members @@ -1490,6 +1573,35 @@ =back +=head3 Examples + +Example: C a new process and install a child handler to wait for +its completion. + + ev_child cw; + + static void + child_cb (EV_P_ struct ev_child *w, int revents) + { + ev_child_stop (EV_A_ w); + printf ("process %d exited with status %x\n", w->rpid, w->rstatus); + } + + pid_t pid = fork (); + + if (pid < 0) + // error + else if (pid == 0) + { + // the forked child executes here + exit (1); + } + else + { + ev_child_init (&cw, child_cb, pid, 0); + ev_child_start (EV_DEFAULT_ &cw); + } + =head2 C - did the file attributes just change? @@ -1521,11 +1633,23 @@ At the time of this writing, only the Linux inotify interface is implemented (implementing kqueue support is left as an exercise for the -reader). Inotify will be used to give hints only and should not change the -semantics of C watchers, which means that libev sometimes needs -to fall back to regular polling again even with inotify, but changes are -usually detected immediately, and if the file exists there will be no -polling. +reader, note, however, that the author sees no way of implementing ev_stat +semantics with kqueue). Inotify will be used to give hints only and should +not change the semantics of C watchers, which means that libev +sometimes needs to fall back to regular polling again even with inotify, +but changes are usually detected immediately, and if the file exists there +will be no polling. + +=head3 ABI Issues (Largefile Support) + +Libev by default (unless the user overrides this) uses the default +compilation environment, which means that on systems with optionally +disabled large file support, you get the 32 bit version of the stat +structure. When using the library from programs that change the ABI to +use 64 bit file offsets the programs will fail. In that case you have to +compile libev with the same flags to get binary compatibility. This is +obviously the case with any flags that change the ABI, but the problem is +most noticably with ev_stat and largefile support. =head3 Inotify @@ -1534,9 +1658,9 @@ change detection where possible. The inotify descriptor will be created lazily when the first C watcher is being started. -Inotify presense does not change the semantics of C watchers +Inotify presence does not change the semantics of C watchers except that changes might be detected earlier, and in some cases, to avoid -making regular C calls. Even in the presense of inotify support +making regular C calls. Even in the presence of inotify support there are many cases where libev has to resort to regular C polling. (There is no support for kqueue, as apparently it cannot be used to @@ -1549,16 +1673,25 @@ even on systems where the resolution is higher, many filesystems still only support whole seconds. -That means that, if the time is the only thing that changes, you might -miss updates: on the first update, C detects a change and calls -your callback, which does something. When there is another update within -the same second, C will be unable to detect it. - -The solution to this is to delay acting on a change for a second (or till -the next second boundary), using a roughly one-second delay C -(C). The C<.01> -is added to work around small timing inconsistencies of some operating -systems. +That means that, if the time is the only thing that changes, you can +easily miss updates: on the first update, C detects a change and +calls your callback, which does something. When there is another update +within the same second, C will be unable to detect it as the stat +data does not change. + +The solution to this is to delay acting on a change for slightly more +than a second (or till slightly after the next full second boundary), using +a roughly one-second-delay C (e.g. C). + +The C<.02> offset is added to work around small timing inconsistencies +of some operating systems (where the second counter of the current time +might be be delayed. One such system is the Linux kernel, where a call to +C might return a timestamp with a full second later than +a subsequent C