summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--ev.pod57
1 files changed, 39 insertions, 18 deletions
diff --git a/ev.pod b/ev.pod
index b41cc3d..eee50c7 100644
--- a/ev.pod
+++ b/ev.pod
@@ -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