diff options
| -rw-r--r-- | ev.pod | 57 |
1 files changed, 39 insertions, 18 deletions
@@ -8,49 +8,63 @@ libev - a high performance full-featured event loop written in C =head2 EXAMPLE PROGRAM + // a single header file is required #include <ev.h> + // every watcher type has its own typedef'd struct + // with the name ev_<type> 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<http://cvs.schmorp.de/libev/ev.html>. @@ -86,12 +100,13 @@ for example). =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<EMBED> section in -this manual. If libev was configured without support for multiple event -loops, then all functions taking an initial argument of name C<loop> -(which is always of type C<struct ev_loop *>) 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<EMBED> section in this manual. If libev was configured without support +for multiple event loops, then all functions taking an initial argument of +name C<loop> (which is always of type C<struct ev_loop *>) will not have +this argument. =head2 TIME REPRESENTATION @@ -299,8 +314,8 @@ enabling this flag. This works by calling C<getpid ()> 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<getpid> is actually a simple 5-insn sequence -without a syscall and thus I<very> fast, but my Linux system also has +GNU/Linux system for example, C<getpid> is actually a simple 5-insn sequence +without a syscall and thus I<very> fast, but my GNU/Linux system also has C<pthread_atfork> which is even faster). The big advantage of this flag is that you can forget about fork (and @@ -1421,6 +1436,12 @@ as you don't register any with libev). Similarly, when the last signal 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<SA_RESTART> 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<ev_check> watcher and unblock +them in an C<ev_prepare> watcher. + =head3 Watcher-Specific Functions and Data Members =over 4 |