--- libev/ev.pod 2008/02/01 13:47:08 1.127 +++ libev/ev.pod 2008/05/11 11:47:27 1.154 @@ -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 @@ -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 @@ -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); @@ -508,6 +527,10 @@ C. Yes, you have to call this on every allocated event loop after fork, and how you do this is entirely your own problem. +=item int ev_is_default_loop (loop) + +Returns true when the given loop actually is the default loop, false otherwise. + =item unsigned int ev_loop_count (loop) Returns the count of loop iterations for the loop, which is identical to @@ -1068,6 +1091,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 @@ -1154,7 +1189,7 @@ 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) +=item ev_timer_again (loop, ev_timer *) This will act as if the timer timed out and restart it again if it is repeating. The exact semantics are: @@ -1273,7 +1308,7 @@ 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 (at = offset, interval > 0, reschedule_cb = 0) +=item * 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, which can also be negative) @@ -1340,6 +1375,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 @@ -1360,11 +1400,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 @@ -1417,6 +1452,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 @@ -1434,11 +1475,50 @@ =back +=head3 Examples + +Example: Try to exit cleanly on SIGINT and SIGTERM. + + static void + sigint_cb (struct ev_loop *loop, struct ev_signal *w, int revents) + { + ev_unloop (loop, EVUNLOOP_ALL); + } + + struct ev_signal signal_watcher; + ev_signal_init (&signal_watcher, sigint_cb, SIGINT); + ev_signal_start (loop, &sigint_cb); + =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 @@ -1474,17 +1554,32 @@ =head3 Examples -Example: Try to exit cleanly on SIGINT and SIGTERM. +Example: C a new process and install a child handler to wait for +its completion. + + ev_child cw; static void - sigint_cb (struct ev_loop *loop, struct ev_signal *w, int revents) + child_cb (EV_P_ struct ev_child *w, int revents) { - ev_unloop (loop, EVUNLOOP_ALL); + ev_child_stop (EV_A_ w); + printf ("process %d exited with status %x\n", w->rpid, w->rstatus); } - struct ev_signal signal_watcher; - ev_signal_init (&signal_watcher, sigint_cb, SIGINT); - ev_signal_start (loop, &sigint_cb); + 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? @@ -1517,11 +1612,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 @@ -1530,9 +1637,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 @@ -1545,16 +1652,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 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