ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/libev/ev.pod
(Generate patch)

Comparing libev/ev.pod (file contents):
Revision 1.134 by root, Sat Mar 8 07:04:56 2008 UTC vs.
Revision 1.135 by root, Sat Mar 8 10:38:40 2008 UTC

… …
6 6
7 #include <ev.h> 7 #include <ev.h>
8 8
9=head2 EXAMPLE PROGRAM 9=head2 EXAMPLE PROGRAM
10 10
11 // a single header file is required
11 #include <ev.h> 12 #include <ev.h>
12 13
14 // every watcher type has its own typedef'd struct
15 // with the name ev_<type>
13 ev_io stdin_watcher; 16 ev_io stdin_watcher;
14 ev_timer timeout_watcher; 17 ev_timer timeout_watcher;
15 18
19 // all watcher callbacks have a similar signature
16 /* called when data readable on stdin */ 20 // this callback is called when data is readable on stdin
17 static void 21 static void
18 stdin_cb (EV_P_ struct ev_io *w, int revents) 22 stdin_cb (EV_P_ struct ev_io *w, int revents)
19 { 23 {
20 /* puts ("stdin ready"); */ 24 puts ("stdin ready");
21 ev_io_stop (EV_A_ w); /* just a syntax example */ 25 // for one-shot events, one must manually stop the watcher
22 ev_unloop (EV_A_ EVUNLOOP_ALL); /* leave all loop calls */ 26 // with its corresponding stop function.
27 ev_io_stop (EV_A_ w);
28
29 // this causes all nested ev_loop's to stop iterating
30 ev_unloop (EV_A_ EVUNLOOP_ALL);
23 } 31 }
24 32
33 // another callback, this time for a time-out
25 static void 34 static void
26 timeout_cb (EV_P_ struct ev_timer *w, int revents) 35 timeout_cb (EV_P_ struct ev_timer *w, int revents)
27 { 36 {
28 /* puts ("timeout"); */ 37 puts ("timeout");
29 ev_unloop (EV_A_ EVUNLOOP_ONE); /* leave one loop call */ 38 // this causes the innermost ev_loop to stop iterating
39 ev_unloop (EV_A_ EVUNLOOP_ONE);
30 } 40 }
31 41
32 int 42 int
33 main (void) 43 main (void)
34 { 44 {
45 // use the default event loop unless you have special needs
35 struct ev_loop *loop = ev_default_loop (0); 46 struct ev_loop *loop = ev_default_loop (0);
36 47
37 /* initialise an io watcher, then start it */ 48 // initialise an io watcher, then start it
49 // this one will watch for stdin to become readable
38 ev_io_init (&stdin_watcher, stdin_cb, /*STDIN_FILENO*/ 0, EV_READ); 50 ev_io_init (&stdin_watcher, stdin_cb, /*STDIN_FILENO*/ 0, EV_READ);
39 ev_io_start (loop, &stdin_watcher); 51 ev_io_start (loop, &stdin_watcher);
40 52
53 // initialise a timer watcher, then start it
41 /* simple non-repeating 5.5 second timeout */ 54 // simple non-repeating 5.5 second timeout
42 ev_timer_init (&timeout_watcher, timeout_cb, 5.5, 0.); 55 ev_timer_init (&timeout_watcher, timeout_cb, 5.5, 0.);
43 ev_timer_start (loop, &timeout_watcher); 56 ev_timer_start (loop, &timeout_watcher);
44 57
45 /* loop till timeout or data ready */ 58 // now wait for events to arrive
46 ev_loop (loop, 0); 59 ev_loop (loop, 0);
47 60
61 // unloop was called, so exit
48 return 0; 62 return 0;
49 } 63 }
50 64
51=head1 DESCRIPTION 65=head1 DESCRIPTION
52 66
53The newest version of this document is also available as a html-formatted 67The newest version of this document is also available as an html-formatted
54web page you might find easier to navigate when reading it for the first 68web page you might find easier to navigate when reading it for the first
55time: L<http://cvs.schmorp.de/libev/ev.html>. 69time: L<http://cvs.schmorp.de/libev/ev.html>.
56 70
57Libev is an event loop: you register interest in certain events (such as a 71Libev is an event loop: you register interest in certain events (such as a
58file descriptor being readable or a timeout occurring), and it will manage 72file descriptor being readable or a timeout occurring), and it will manage
… …
84L<benchmark|http://libev.schmorp.de/bench.html> comparing it to libevent 98L<benchmark|http://libev.schmorp.de/bench.html> comparing it to libevent
85for example). 99for example).
86 100
87=head2 CONVENTIONS 101=head2 CONVENTIONS
88 102
89Libev is very configurable. In this manual the default configuration will 103Libev is very configurable. In this manual the default (and most common)
90be described, which supports multiple event loops. For more info about 104configuration will be described, which supports multiple event loops. For
91various configuration options please have a look at B<EMBED> section in 105more info about various configuration options please have a look at
92this manual. If libev was configured without support for multiple event 106B<EMBED> section in this manual. If libev was configured without support
93loops, then all functions taking an initial argument of name C<loop> 107for multiple event loops, then all functions taking an initial argument of
94(which is always of type C<struct ev_loop *>) will not have this argument. 108name C<loop> (which is always of type C<struct ev_loop *>) will not have
109this argument.
95 110
96=head2 TIME REPRESENTATION 111=head2 TIME REPRESENTATION
97 112
98Libev represents time as a single floating point number, representing the 113Libev represents time as a single floating point number, representing the
99(fractional) number of seconds since the (POSIX) epoch (somewhere near 114(fractional) number of seconds since the (POSIX) epoch (somewhere near
… …
297enabling this flag. 312enabling this flag.
298 313
299This works by calling C<getpid ()> on every iteration of the loop, 314This works by calling C<getpid ()> on every iteration of the loop,
300and thus this might slow down your event loop if you do a lot of loop 315and thus this might slow down your event loop if you do a lot of loop
301iterations and little real work, but is usually not noticeable (on my 316iterations and little real work, but is usually not noticeable (on my
302Linux system for example, C<getpid> is actually a simple 5-insn sequence 317GNU/Linux system for example, C<getpid> is actually a simple 5-insn sequence
303without a syscall and thus I<very> fast, but my Linux system also has 318without a syscall and thus I<very> fast, but my GNU/Linux system also has
304C<pthread_atfork> which is even faster). 319C<pthread_atfork> which is even faster).
305 320
306The big advantage of this flag is that you can forget about fork (and 321The big advantage of this flag is that you can forget about fork (and
307forget about forgetting to tell libev about forking) when you use this 322forget about forgetting to tell libev about forking) when you use this
308flag. 323flag.
… …
1419with the kernel (thus it coexists with your own signal handlers as long 1434with the kernel (thus it coexists with your own signal handlers as long
1420as you don't register any with libev). Similarly, when the last signal 1435as you don't register any with libev). Similarly, when the last signal
1421watcher for a signal is stopped libev will reset the signal handler to 1436watcher for a signal is stopped libev will reset the signal handler to
1422SIG_DFL (regardless of what it was set to before). 1437SIG_DFL (regardless of what it was set to before).
1423 1438
1439If possible and supported, libev will install its handlers with
1440C<SA_RESTART> behaviour enabled, so syscalls should not be unduly
1441interrupted. If you have a problem with syscalls getting interrupted by
1442signals you can block all signals in an C<ev_check> watcher and unblock
1443them in an C<ev_prepare> watcher.
1444
1424=head3 Watcher-Specific Functions and Data Members 1445=head3 Watcher-Specific Functions and Data Members
1425 1446
1426=over 4 1447=over 4
1427 1448
1428=item ev_signal_init (ev_signal *, callback, int signum) 1449=item ev_signal_init (ev_signal *, callback, int signum)

Diff Legend

– Removed lines
+ Added lines
< Changed lines
> Changed lines