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

Comparing libev/ev.3 (file contents):
Revision 1.72 by root, Tue Oct 21 20:06:52 2008 UTC vs.
Revision 1.74 by root, Wed Nov 19 10:33:32 2008 UTC

… …
130.\} 130.\}
131.rm #[ #] #H #V #F C 131.rm #[ #] #H #V #F C
132.\" ======================================================================== 132.\" ========================================================================
133.\" 133.\"
134.IX Title "LIBEV 3" 134.IX Title "LIBEV 3"
135.TH LIBEV 3 "2008-10-21" "libev-3.45" "libev - high performance full featured event loop" 135.TH LIBEV 3 "2008-11-17" "libev-3.49" "libev - high performance full featured event loop"
136.\" For nroff, turn off justification. Always turn off hyphenation; it makes 136.\" For nroff, turn off justification. Always turn off hyphenation; it makes
137.\" way too many mistakes in technical documents. 137.\" way too many mistakes in technical documents.
138.if n .ad l 138.if n .ad l
139.nh 139.nh
140.SH "NAME" 140.SH "NAME"
… …
148.IX Subsection "EXAMPLE PROGRAM" 148.IX Subsection "EXAMPLE PROGRAM"
149.Vb 2 149.Vb 2
150\& // a single header file is required 150\& // a single header file is required
151\& #include <ev.h> 151\& #include <ev.h>
152\& 152\&
153\& #include <stdio.h> // for puts
154\&
153\& // every watcher type has its own typedef\*(Aqd struct 155\& // every watcher type has its own typedef\*(Aqd struct
154\& // with the name ev_<type> 156\& // with the name ev_TYPE
155\& ev_io stdin_watcher; 157\& ev_io stdin_watcher;
156\& ev_timer timeout_watcher; 158\& ev_timer timeout_watcher;
157\& 159\&
158\& // all watcher callbacks have a similar signature 160\& // all watcher callbacks have a similar signature
159\& // this callback is called when data is readable on stdin 161\& // this callback is called when data is readable on stdin
160\& static void 162\& static void
161\& stdin_cb (EV_P_ struct ev_io *w, int revents) 163\& stdin_cb (EV_P_ ev_io *w, int revents)
162\& { 164\& {
163\& puts ("stdin ready"); 165\& puts ("stdin ready");
164\& // for one\-shot events, one must manually stop the watcher 166\& // for one\-shot events, one must manually stop the watcher
165\& // with its corresponding stop function. 167\& // with its corresponding stop function.
166\& ev_io_stop (EV_A_ w); 168\& ev_io_stop (EV_A_ w);
… …
169\& ev_unloop (EV_A_ EVUNLOOP_ALL); 171\& ev_unloop (EV_A_ EVUNLOOP_ALL);
170\& } 172\& }
171\& 173\&
172\& // another callback, this time for a time\-out 174\& // another callback, this time for a time\-out
173\& static void 175\& static void
174\& timeout_cb (EV_P_ struct ev_timer *w, int revents) 176\& timeout_cb (EV_P_ ev_timer *w, int revents)
175\& { 177\& {
176\& puts ("timeout"); 178\& puts ("timeout");
177\& // this causes the innermost ev_loop to stop iterating 179\& // this causes the innermost ev_loop to stop iterating
178\& ev_unloop (EV_A_ EVUNLOOP_ONE); 180\& ev_unloop (EV_A_ EVUNLOOP_ONE);
179\& } 181\& }
180\& 182\&
181\& int 183\& int
182\& main (void) 184\& main (void)
183\& { 185\& {
184\& // use the default event loop unless you have special needs 186\& // use the default event loop unless you have special needs
185\& struct ev_loop *loop = ev_default_loop (0); 187\& ev_loop *loop = ev_default_loop (0);
186\& 188\&
187\& // initialise an io watcher, then start it 189\& // initialise an io watcher, then start it
188\& // this one will watch for stdin to become readable 190\& // this one will watch for stdin to become readable
189\& ev_io_init (&stdin_watcher, stdin_cb, /*STDIN_FILENO*/ 0, EV_READ); 191\& ev_io_init (&stdin_watcher, stdin_cb, /*STDIN_FILENO*/ 0, EV_READ);
190\& ev_io_start (loop, &stdin_watcher); 192\& ev_io_start (loop, &stdin_watcher);
… …
240Libev is very configurable. In this manual the default (and most common) 242Libev is very configurable. In this manual the default (and most common)
241configuration will be described, which supports multiple event loops. For 243configuration will be described, which supports multiple event loops. For
242more info about various configuration options please have a look at 244more info about various configuration options please have a look at
243\&\fB\s-1EMBED\s0\fR section in this manual. If libev was configured without support 245\&\fB\s-1EMBED\s0\fR section in this manual. If libev was configured without support
244for multiple event loops, then all functions taking an initial argument of 246for multiple event loops, then all functions taking an initial argument of
245name \f(CW\*(C`loop\*(C'\fR (which is always of type \f(CW\*(C`struct ev_loop *\*(C'\fR) will not have 247name \f(CW\*(C`loop\*(C'\fR (which is always of type \f(CW\*(C`ev_loop *\*(C'\fR) will not have
246this argument. 248this argument.
247.Sh "\s-1TIME\s0 \s-1REPRESENTATION\s0" 249.Sh "\s-1TIME\s0 \s-1REPRESENTATION\s0"
248.IX Subsection "TIME REPRESENTATION" 250.IX Subsection "TIME REPRESENTATION"
249Libev represents time as a single floating point number, representing the 251Libev represents time as a single floating point number, representing the
250(fractional) number of seconds since the (\s-1POSIX\s0) epoch (somewhere near 252(fractional) number of seconds since the (\s-1POSIX\s0) epoch (somewhere near
… …
406\& ... 408\& ...
407\& ev_set_syserr_cb (fatal_error); 409\& ev_set_syserr_cb (fatal_error);
408.Ve 410.Ve
409.SH "FUNCTIONS CONTROLLING THE EVENT LOOP" 411.SH "FUNCTIONS CONTROLLING THE EVENT LOOP"
410.IX Header "FUNCTIONS CONTROLLING THE EVENT LOOP" 412.IX Header "FUNCTIONS CONTROLLING THE EVENT LOOP"
411An event loop is described by a \f(CW\*(C`struct ev_loop *\*(C'\fR. The library knows two 413An event loop is described by a \f(CW\*(C`struct ev_loop *\*(C'\fR (the \f(CW\*(C`struct\*(C'\fR
412types of such loops, the \fIdefault\fR loop, which supports signals and child 414is \fInot\fR optional in this case, as there is also an \f(CW\*(C`ev_loop\*(C'\fR
413events, and dynamically created loops which do not. 415\&\fIfunction\fR).
416.PP
417The library knows two types of such loops, the \fIdefault\fR loop, which
418supports signals and child events, and dynamically created loops which do
419not.
414.IP "struct ev_loop *ev_default_loop (unsigned int flags)" 4 420.IP "struct ev_loop *ev_default_loop (unsigned int flags)" 4
415.IX Item "struct ev_loop *ev_default_loop (unsigned int flags)" 421.IX Item "struct ev_loop *ev_default_loop (unsigned int flags)"
416This will initialise the default event loop if it hasn't been initialised 422This will initialise the default event loop if it hasn't been initialised
417yet and return it. If the default loop could not be initialised, returns 423yet and return it. If the default loop could not be initialised, returns
418false. If it already was initialised it simply returns it (and ignores the 424false. If it already was initialised it simply returns it (and ignores the
… …
421If you don't know what event loop to use, use the one returned from this 427If you don't know what event loop to use, use the one returned from this
422function. 428function.
423.Sp 429.Sp
424Note that this function is \fInot\fR thread-safe, so if you want to use it 430Note that this function is \fInot\fR thread-safe, so if you want to use it
425from multiple threads, you have to lock (note also that this is unlikely, 431from multiple threads, you have to lock (note also that this is unlikely,
426as loops cannot bes hared easily between threads anyway). 432as loops cannot be shared easily between threads anyway).
427.Sp 433.Sp
428The default loop is the only loop that can handle \f(CW\*(C`ev_signal\*(C'\fR and 434The default loop is the only loop that can handle \f(CW\*(C`ev_signal\*(C'\fR and
429\&\f(CW\*(C`ev_child\*(C'\fR watchers, and to do this, it always registers a handler 435\&\f(CW\*(C`ev_child\*(C'\fR watchers, and to do this, it always registers a handler
430for \f(CW\*(C`SIGCHLD\*(C'\fR. If this is a problem for your application you can either 436for \f(CW\*(C`SIGCHLD\*(C'\fR. If this is a problem for your application you can either
431create a dynamic loop with \f(CW\*(C`ev_loop_new\*(C'\fR that doesn't do that, or you 437create a dynamic loop with \f(CW\*(C`ev_loop_new\*(C'\fR that doesn't do that, or you
… …
506.el .IP "\f(CWEVBACKEND_EPOLL\fR (value 4, Linux)" 4 512.el .IP "\f(CWEVBACKEND_EPOLL\fR (value 4, Linux)" 4
507.IX Item "EVBACKEND_EPOLL (value 4, Linux)" 513.IX Item "EVBACKEND_EPOLL (value 4, Linux)"
508For few fds, this backend is a bit little slower than poll and select, 514For few fds, this backend is a bit little slower than poll and select,
509but it scales phenomenally better. While poll and select usually scale 515but it scales phenomenally better. While poll and select usually scale
510like O(total_fds) where n is the total number of fds (or the highest fd), 516like O(total_fds) where n is the total number of fds (or the highest fd),
511epoll scales either O(1) or O(active_fds). The epoll design has a number 517epoll scales either O(1) or O(active_fds).
512of shortcomings, such as silently dropping events in some hard-to-detect 518.Sp
513cases and requiring a system call per fd change, no fork support and bad 519The epoll mechanism deserves honorable mention as the most misdesigned
514support for dup. 520of the more advanced event mechanisms: mere annoyances include silently
521dropping file descriptors, requiring a system call per change per file
522descriptor (and unnecessary guessing of parameters), problems with dup and
523so on. The biggest issue is fork races, however \- if a program forks then
524\&\fIboth\fR parent and child process have to recreate the epoll set, which can
525take considerable time (one syscall per file descriptor) and is of course
526hard to detect.
527.Sp
528Epoll is also notoriously buggy \- embedding epoll fds \fIshould\fR work, but
529of course \fIdoesn't\fR, and epoll just loves to report events for totally
530\&\fIdifferent\fR file descriptors (even already closed ones, so one cannot
531even remove them from the set) than registered in the set (especially
532on \s-1SMP\s0 systems). Libev tries to counter these spurious notifications by
533employing an additional generation counter and comparing that against the
534events to filter out spurious ones, recreating the set when required.
515.Sp 535.Sp
516While stopping, setting and starting an I/O watcher in the same iteration 536While stopping, setting and starting an I/O watcher in the same iteration
517will result in some caching, there is still a system call per such incident 537will result in some caching, there is still a system call per such
518(because the fd could point to a different file description now), so its 538incident (because the same \fIfile descriptor\fR could point to a different
519best to avoid that. Also, \f(CW\*(C`dup ()\*(C'\fR'ed file descriptors might not work 539\&\fIfile description\fR now), so its best to avoid that. Also, \f(CW\*(C`dup ()\*(C'\fR'ed
520very well if you register events for both fds. 540file descriptors might not work very well if you register events for both
521.Sp 541file descriptors.
522Please note that epoll sometimes generates spurious notifications, so you
523need to use non-blocking I/O or other means to avoid blocking when no data
524(or space) is available.
525.Sp 542.Sp
526Best performance from this backend is achieved by not unregistering all 543Best performance from this backend is achieved by not unregistering all
527watchers for a file descriptor until it has been closed, if possible, 544watchers for a file descriptor until it has been closed, if possible,
528i.e. keep at least one watcher active per fd at all times. Stopping and 545i.e. keep at least one watcher active per fd at all times. Stopping and
529starting a watcher (without re-setting it) also usually doesn't cause 546starting a watcher (without re-setting it) also usually doesn't cause
530extra overhead. 547extra overhead. A fork can both result in spurious notifications as well
548as in libev having to destroy and recreate the epoll object, which can
549take considerable time and thus should be avoided.
550.Sp
551All this means that, in practice, \f(CW\*(C`EVBACKEND_SELECT\*(C'\fR can be as fast or
552faster than epoll for maybe up to a hundred file descriptors, depending on
553the usage. So sad.
531.Sp 554.Sp
532While nominally embeddable in other event loops, this feature is broken in 555While nominally embeddable in other event loops, this feature is broken in
533all kernel versions tested so far. 556all kernel versions tested so far.
534.Sp 557.Sp
535This backend maps \f(CW\*(C`EV_READ\*(C'\fR and \f(CW\*(C`EV_WRITE\*(C'\fR in the same way as 558This backend maps \f(CW\*(C`EV_READ\*(C'\fR and \f(CW\*(C`EV_WRITE\*(C'\fR in the same way as
536\&\f(CW\*(C`EVBACKEND_POLL\*(C'\fR. 559\&\f(CW\*(C`EVBACKEND_POLL\*(C'\fR.
537.ie n .IP """EVBACKEND_KQUEUE"" (value 8, most \s-1BSD\s0 clones)" 4 560.ie n .IP """EVBACKEND_KQUEUE"" (value 8, most \s-1BSD\s0 clones)" 4
538.el .IP "\f(CWEVBACKEND_KQUEUE\fR (value 8, most \s-1BSD\s0 clones)" 4 561.el .IP "\f(CWEVBACKEND_KQUEUE\fR (value 8, most \s-1BSD\s0 clones)" 4
539.IX Item "EVBACKEND_KQUEUE (value 8, most BSD clones)" 562.IX Item "EVBACKEND_KQUEUE (value 8, most BSD clones)"
540Kqueue deserves special mention, as at the time of this writing, it was 563Kqueue deserves special mention, as at the time of this writing, it
541broken on all BSDs except NetBSD (usually it doesn't work reliably with 564was broken on all BSDs except NetBSD (usually it doesn't work reliably
542anything but sockets and pipes, except on Darwin, where of course it's 565with anything but sockets and pipes, except on Darwin, where of course
543completely useless). For this reason it's not being \*(L"auto-detected\*(R" unless 566it's completely useless). Unlike epoll, however, whose brokenness
544you explicitly specify it in the flags (i.e. using \f(CW\*(C`EVBACKEND_KQUEUE\*(C'\fR) or 567is by design, these kqueue bugs can (and eventually will) be fixed
545libev was compiled on a known-to-be-good (\-enough) system like NetBSD. 568without \s-1API\s0 changes to existing programs. For this reason it's not being
569\&\*(L"auto-detected\*(R" unless you explicitly specify it in the flags (i.e. using
570\&\f(CW\*(C`EVBACKEND_KQUEUE\*(C'\fR) or libev was compiled on a known-to-be-good (\-enough)
571system like NetBSD.
546.Sp 572.Sp
547You still can embed kqueue into a normal poll or select backend and use it 573You still can embed kqueue into a normal poll or select backend and use it
548only for sockets (after having made sure that sockets work with kqueue on 574only for sockets (after having made sure that sockets work with kqueue on
549the target platform). See \f(CW\*(C`ev_embed\*(C'\fR watchers for more info. 575the target platform). See \f(CW\*(C`ev_embed\*(C'\fR watchers for more info.
550.Sp 576.Sp
551It scales in the same way as the epoll backend, but the interface to the 577It scales in the same way as the epoll backend, but the interface to the
552kernel is more efficient (which says nothing about its actual speed, of 578kernel is more efficient (which says nothing about its actual speed, of
553course). While stopping, setting and starting an I/O watcher does never 579course). While stopping, setting and starting an I/O watcher does never
554cause an extra system call as with \f(CW\*(C`EVBACKEND_EPOLL\*(C'\fR, it still adds up to 580cause an extra system call as with \f(CW\*(C`EVBACKEND_EPOLL\*(C'\fR, it still adds up to
555two event changes per incident. Support for \f(CW\*(C`fork ()\*(C'\fR is very bad and it 581two event changes per incident. Support for \f(CW\*(C`fork ()\*(C'\fR is very bad (but
556drops fds silently in similarly hard-to-detect cases. 582sane, unlike epoll) and it drops fds silently in similarly hard-to-detect
583cases
557.Sp 584.Sp
558This backend usually performs well under most conditions. 585This backend usually performs well under most conditions.
559.Sp 586.Sp
560While nominally embeddable in other event loops, this doesn't work 587While nominally embeddable in other event loops, this doesn't work
561everywhere, so you might need to test for this. And since it is broken 588everywhere, so you might need to test for this. And since it is broken
… …
590might perform better. 617might perform better.
591.Sp 618.Sp
592On the positive side, with the exception of the spurious readiness 619On the positive side, with the exception of the spurious readiness
593notifications, this backend actually performed fully to specification 620notifications, this backend actually performed fully to specification
594in all tests and is fully embeddable, which is a rare feat among the 621in all tests and is fully embeddable, which is a rare feat among the
595OS-specific backends. 622OS-specific backends (I vastly prefer correctness over speed hacks).
596.Sp 623.Sp
597This backend maps \f(CW\*(C`EV_READ\*(C'\fR and \f(CW\*(C`EV_WRITE\*(C'\fR in the same way as 624This backend maps \f(CW\*(C`EV_READ\*(C'\fR and \f(CW\*(C`EV_WRITE\*(C'\fR in the same way as
598\&\f(CW\*(C`EVBACKEND_POLL\*(C'\fR. 625\&\f(CW\*(C`EVBACKEND_POLL\*(C'\fR.
599.ie n .IP """EVBACKEND_ALL""" 4 626.ie n .IP """EVBACKEND_ALL""" 4
600.el .IP "\f(CWEVBACKEND_ALL\fR" 4 627.el .IP "\f(CWEVBACKEND_ALL\fR" 4
… …
660responsibility to either stop all watchers cleanly yourself \fIbefore\fR 687responsibility to either stop all watchers cleanly yourself \fIbefore\fR
661calling this function, or cope with the fact afterwards (which is usually 688calling this function, or cope with the fact afterwards (which is usually
662the easiest thing, you can just ignore the watchers and/or \f(CW\*(C`free ()\*(C'\fR them 689the easiest thing, you can just ignore the watchers and/or \f(CW\*(C`free ()\*(C'\fR them
663for example). 690for example).
664.Sp 691.Sp
665Note that certain global state, such as signal state, will not be freed by 692Note that certain global state, such as signal state (and installed signal
666this function, and related watchers (such as signal and child watchers) 693handlers), will not be freed by this function, and related watchers (such
667would need to be stopped manually. 694as signal and child watchers) would need to be stopped manually.
668.Sp 695.Sp
669In general it is not advisable to call this function except in the 696In general it is not advisable to call this function except in the
670rare occasion where you really need to free e.g. the signal handling 697rare occasion where you really need to free e.g. the signal handling
671pipe fds. If you need dynamically allocated loops it is better to use 698pipe fds. If you need dynamically allocated loops it is better to use
672\&\f(CW\*(C`ev_loop_new\*(C'\fR and \f(CW\*(C`ev_loop_destroy\*(C'\fR). 699\&\f(CW\*(C`ev_loop_new\*(C'\fR and \f(CW\*(C`ev_loop_destroy\*(C'\fR).
… …
757the loop. 784the loop.
758.Sp 785.Sp
759A flags value of \f(CW\*(C`EVLOOP_ONESHOT\*(C'\fR will look for new events (waiting if 786A flags value of \f(CW\*(C`EVLOOP_ONESHOT\*(C'\fR will look for new events (waiting if
760necessary) and will handle those and any already outstanding ones. It 787necessary) and will handle those and any already outstanding ones. It
761will block your process until at least one new event arrives (which could 788will block your process until at least one new event arrives (which could
762be an event internal to libev itself, so there is no guarentee that a 789be an event internal to libev itself, so there is no guarantee that a
763user-registered callback will be called), and will return after one 790user-registered callback will be called), and will return after one
764iteration of the loop. 791iteration of the loop.
765.Sp 792.Sp
766This is useful if you are waiting for some external event in conjunction 793This is useful if you are waiting for some external event in conjunction
767with something not expressible using other libev watchers (i.e. "roll your 794with something not expressible using other libev watchers (i.e. "roll your
… …
841.Sp 868.Sp
842Example: Create a signal watcher, but keep it from keeping \f(CW\*(C`ev_loop\*(C'\fR 869Example: Create a signal watcher, but keep it from keeping \f(CW\*(C`ev_loop\*(C'\fR
843running when nothing else is active. 870running when nothing else is active.
844.Sp 871.Sp
845.Vb 4 872.Vb 4
846\& struct ev_signal exitsig; 873\& ev_signal exitsig;
847\& ev_signal_init (&exitsig, sig_cb, SIGINT); 874\& ev_signal_init (&exitsig, sig_cb, SIGINT);
848\& ev_signal_start (loop, &exitsig); 875\& ev_signal_start (loop, &exitsig);
849\& evf_unref (loop); 876\& evf_unref (loop);
850.Ve 877.Ve
851.Sp 878.Sp
… …
902reduce iterations/wake\-ups is to use \f(CW\*(C`ev_periodic\*(C'\fR watchers and make sure 929reduce iterations/wake\-ups is to use \f(CW\*(C`ev_periodic\*(C'\fR watchers and make sure
903they fire on, say, one-second boundaries only. 930they fire on, say, one-second boundaries only.
904.IP "ev_loop_verify (loop)" 4 931.IP "ev_loop_verify (loop)" 4
905.IX Item "ev_loop_verify (loop)" 932.IX Item "ev_loop_verify (loop)"
906This function only does something when \f(CW\*(C`EV_VERIFY\*(C'\fR support has been 933This function only does something when \f(CW\*(C`EV_VERIFY\*(C'\fR support has been
907compiled in. which is the default for non-minimal builds. It tries to go 934compiled in, which is the default for non-minimal builds. It tries to go
908through all internal structures and checks them for validity. If anything 935through all internal structures and checks them for validity. If anything
909is found to be inconsistent, it will print an error message to standard 936is found to be inconsistent, it will print an error message to standard
910error and call \f(CW\*(C`abort ()\*(C'\fR. 937error and call \f(CW\*(C`abort ()\*(C'\fR.
911.Sp 938.Sp
912This can be used to catch bugs inside libev itself: under normal 939This can be used to catch bugs inside libev itself: under normal
913circumstances, this function will never abort as of course libev keeps its 940circumstances, this function will never abort as of course libev keeps its
914data structures consistent. 941data structures consistent.
915.SH "ANATOMY OF A WATCHER" 942.SH "ANATOMY OF A WATCHER"
916.IX Header "ANATOMY OF A WATCHER" 943.IX Header "ANATOMY OF A WATCHER"
944In the following description, uppercase \f(CW\*(C`TYPE\*(C'\fR in names stands for the
945watcher type, e.g. \f(CW\*(C`ev_TYPE_start\*(C'\fR can mean \f(CW\*(C`ev_timer_start\*(C'\fR for timer
946watchers and \f(CW\*(C`ev_io_start\*(C'\fR for I/O watchers.
947.PP
917A watcher is a structure that you create and register to record your 948A watcher is a structure that you create and register to record your
918interest in some event. For instance, if you want to wait for \s-1STDIN\s0 to 949interest in some event. For instance, if you want to wait for \s-1STDIN\s0 to
919become readable, you would create an \f(CW\*(C`ev_io\*(C'\fR watcher for that: 950become readable, you would create an \f(CW\*(C`ev_io\*(C'\fR watcher for that:
920.PP 951.PP
921.Vb 5 952.Vb 5
922\& static void my_cb (struct ev_loop *loop, struct ev_io *w, int revents) 953\& static void my_cb (struct ev_loop *loop, ev_io *w, int revents)
923\& { 954\& {
924\& ev_io_stop (w); 955\& ev_io_stop (w);
925\& ev_unloop (loop, EVUNLOOP_ALL); 956\& ev_unloop (loop, EVUNLOOP_ALL);
926\& } 957\& }
927\& 958\&
928\& struct ev_loop *loop = ev_default_loop (0); 959\& struct ev_loop *loop = ev_default_loop (0);
960\&
929\& struct ev_io stdin_watcher; 961\& ev_io stdin_watcher;
962\&
930\& ev_init (&stdin_watcher, my_cb); 963\& ev_init (&stdin_watcher, my_cb);
931\& ev_io_set (&stdin_watcher, STDIN_FILENO, EV_READ); 964\& ev_io_set (&stdin_watcher, STDIN_FILENO, EV_READ);
932\& ev_io_start (loop, &stdin_watcher); 965\& ev_io_start (loop, &stdin_watcher);
966\&
933\& ev_loop (loop, 0); 967\& ev_loop (loop, 0);
934.Ve 968.Ve
935.PP 969.PP
936As you can see, you are responsible for allocating the memory for your 970As you can see, you are responsible for allocating the memory for your
937watcher structures (and it is usually a bad idea to do this on the stack, 971watcher structures (and it is \fIusually\fR a bad idea to do this on the
938although this can sometimes be quite valid). 972stack).
973.PP
974Each watcher has an associated watcher structure (called \f(CW\*(C`struct ev_TYPE\*(C'\fR
975or simply \f(CW\*(C`ev_TYPE\*(C'\fR, as typedefs are provided for all watcher structs).
939.PP 976.PP
940Each watcher structure must be initialised by a call to \f(CW\*(C`ev_init 977Each watcher structure must be initialised by a call to \f(CW\*(C`ev_init
941(watcher *, callback)\*(C'\fR, which expects a callback to be provided. This 978(watcher *, callback)\*(C'\fR, which expects a callback to be provided. This
942callback gets invoked each time the event occurs (or, in the case of I/O 979callback gets invoked each time the event occurs (or, in the case of I/O
943watchers, each time the event loop detects that the file descriptor given 980watchers, each time the event loop detects that the file descriptor given
944is readable and/or writable). 981is readable and/or writable).
945.PP 982.PP
946Each watcher type has its own \f(CW\*(C`ev_<type>_set (watcher *, ...)\*(C'\fR macro 983Each watcher type further has its own \f(CW\*(C`ev_TYPE_set (watcher *, ...)\*(C'\fR
947with arguments specific to this watcher type. There is also a macro 984macro to configure it, with arguments specific to the watcher type. There
948to combine initialisation and setting in one call: \f(CW\*(C`ev_<type>_init 985is also a macro to combine initialisation and setting in one call: \f(CW\*(C`ev_TYPE_init (watcher *, callback, ...)\*(C'\fR.
949(watcher *, callback, ...)\*(C'\fR.
950.PP 986.PP
951To make the watcher actually watch out for events, you have to start it 987To make the watcher actually watch out for events, you have to start it
952with a watcher-specific start function (\f(CW\*(C`ev_<type>_start (loop, watcher 988with a watcher-specific start function (\f(CW\*(C`ev_TYPE_start (loop, watcher
953*)\*(C'\fR), and you can stop watching for events at any time by calling the 989*)\*(C'\fR), and you can stop watching for events at any time by calling the
954corresponding stop function (\f(CW\*(C`ev_<type>_stop (loop, watcher *)\*(C'\fR. 990corresponding stop function (\f(CW\*(C`ev_TYPE_stop (loop, watcher *)\*(C'\fR.
955.PP 991.PP
956As long as your watcher is active (has been started but not stopped) you 992As long as your watcher is active (has been started but not stopped) you
957must not touch the values stored in it. Most specifically you must never 993must not touch the values stored in it. Most specifically you must never
958reinitialise it or call its \f(CW\*(C`set\*(C'\fR macro. 994reinitialise it or call its \f(CW\*(C`ev_TYPE_set\*(C'\fR macro.
959.PP 995.PP
960Each and every callback receives the event loop pointer as first, the 996Each and every callback receives the event loop pointer as first, the
961registered watcher structure as second, and a bitset of received events as 997registered watcher structure as second, and a bitset of received events as
962third argument. 998third argument.
963.PP 999.PP
… …
1030.el .IP "\f(CWEV_ERROR\fR" 4 1066.el .IP "\f(CWEV_ERROR\fR" 4
1031.IX Item "EV_ERROR" 1067.IX Item "EV_ERROR"
1032An unspecified error has occurred, the watcher has been stopped. This might 1068An unspecified error has occurred, the watcher has been stopped. This might
1033happen because the watcher could not be properly started because libev 1069happen because the watcher could not be properly started because libev
1034ran out of memory, a file descriptor was found to be closed or any other 1070ran out of memory, a file descriptor was found to be closed or any other
1071problem. Libev considers these application bugs.
1072.Sp
1035problem. You best act on it by reporting the problem and somehow coping 1073You best act on it by reporting the problem and somehow coping with the
1036with the watcher being stopped. 1074watcher being stopped. Note that well-written programs should not receive
1075an error ever, so when your watcher receives it, this usually indicates a
1076bug in your program.
1037.Sp 1077.Sp
1038Libev will usually signal a few \*(L"dummy\*(R" events together with an error, for 1078Libev will usually signal a few \*(L"dummy\*(R" events together with an error, for
1039example it might indicate that a fd is readable or writable, and if your 1079example it might indicate that a fd is readable or writable, and if your
1040callbacks is well-written it can just attempt the operation and cope with 1080callbacks is well-written it can just attempt the operation and cope with
1041the error from \fIread()\fR or \fIwrite()\fR. This will not work in multi-threaded 1081the error from \fIread()\fR or \fIwrite()\fR. This will not work in multi-threaded
1042programs, though, as the fd could already be closed and reused for another 1082programs, though, as the fd could already be closed and reused for another
1043thing, so beware. 1083thing, so beware.
1044.Sh "\s-1GENERIC\s0 \s-1WATCHER\s0 \s-1FUNCTIONS\s0" 1084.Sh "\s-1GENERIC\s0 \s-1WATCHER\s0 \s-1FUNCTIONS\s0"
1045.IX Subsection "GENERIC WATCHER FUNCTIONS" 1085.IX Subsection "GENERIC WATCHER FUNCTIONS"
1046In the following description, \f(CW\*(C`TYPE\*(C'\fR stands for the watcher type,
1047e.g. \f(CW\*(C`timer\*(C'\fR for \f(CW\*(C`ev_timer\*(C'\fR watchers and \f(CW\*(C`io\*(C'\fR for \f(CW\*(C`ev_io\*(C'\fR watchers.
1048.ie n .IP """ev_init"" (ev_TYPE *watcher, callback)" 4 1086.ie n .IP """ev_init"" (ev_TYPE *watcher, callback)" 4
1049.el .IP "\f(CWev_init\fR (ev_TYPE *watcher, callback)" 4 1087.el .IP "\f(CWev_init\fR (ev_TYPE *watcher, callback)" 4
1050.IX Item "ev_init (ev_TYPE *watcher, callback)" 1088.IX Item "ev_init (ev_TYPE *watcher, callback)"
1051This macro initialises the generic portion of a watcher. The contents 1089This macro initialises the generic portion of a watcher. The contents
1052of the watcher object can be arbitrary (so \f(CW\*(C`malloc\*(C'\fR will do). Only 1090of the watcher object can be arbitrary (so \f(CW\*(C`malloc\*(C'\fR will do). Only
… …
1056which rolls both calls into one. 1094which rolls both calls into one.
1057.Sp 1095.Sp
1058You can reinitialise a watcher at any time as long as it has been stopped 1096You can reinitialise a watcher at any time as long as it has been stopped
1059(or never started) and there are no pending events outstanding. 1097(or never started) and there are no pending events outstanding.
1060.Sp 1098.Sp
1061The callback is always of type \f(CW\*(C`void (*)(ev_loop *loop, ev_TYPE *watcher, 1099The callback is always of type \f(CW\*(C`void (*)(struct ev_loop *loop, ev_TYPE *watcher,
1062int revents)\*(C'\fR. 1100int revents)\*(C'\fR.
1063.Sp 1101.Sp
1064Example: Initialise an \f(CW\*(C`ev_io\*(C'\fR watcher in two steps. 1102Example: Initialise an \f(CW\*(C`ev_io\*(C'\fR watcher in two steps.
1065.Sp 1103.Sp
1066.Vb 3 1104.Vb 3
… …
1162The default priority used by watchers when no priority has been set is 1200The default priority used by watchers when no priority has been set is
1163always \f(CW0\fR, which is supposed to not be too high and not be too low :). 1201always \f(CW0\fR, which is supposed to not be too high and not be too low :).
1164.Sp 1202.Sp
1165Setting a priority outside the range of \f(CW\*(C`EV_MINPRI\*(C'\fR to \f(CW\*(C`EV_MAXPRI\*(C'\fR is 1203Setting a priority outside the range of \f(CW\*(C`EV_MINPRI\*(C'\fR to \f(CW\*(C`EV_MAXPRI\*(C'\fR is
1166fine, as long as you do not mind that the priority value you query might 1204fine, as long as you do not mind that the priority value you query might
1167or might not have been adjusted to be within valid range. 1205or might not have been clamped to the valid range.
1168.IP "ev_invoke (loop, ev_TYPE *watcher, int revents)" 4 1206.IP "ev_invoke (loop, ev_TYPE *watcher, int revents)" 4
1169.IX Item "ev_invoke (loop, ev_TYPE *watcher, int revents)" 1207.IX Item "ev_invoke (loop, ev_TYPE *watcher, int revents)"
1170Invoke the \f(CW\*(C`watcher\*(C'\fR with the given \f(CW\*(C`loop\*(C'\fR and \f(CW\*(C`revents\*(C'\fR. Neither 1208Invoke the \f(CW\*(C`watcher\*(C'\fR with the given \f(CW\*(C`loop\*(C'\fR and \f(CW\*(C`revents\*(C'\fR. Neither
1171\&\f(CW\*(C`loop\*(C'\fR nor \f(CW\*(C`revents\*(C'\fR need to be valid as long as the watcher callback 1209\&\f(CW\*(C`loop\*(C'\fR nor \f(CW\*(C`revents\*(C'\fR need to be valid as long as the watcher callback
1172can deal with that fact, as both are simply passed through to the 1210can deal with that fact, as both are simply passed through to the
… …
1189data: 1227data:
1190.PP 1228.PP
1191.Vb 7 1229.Vb 7
1192\& struct my_io 1230\& struct my_io
1193\& { 1231\& {
1194\& struct ev_io io; 1232\& ev_io io;
1195\& int otherfd; 1233\& int otherfd;
1196\& void *somedata; 1234\& void *somedata;
1197\& struct whatever *mostinteresting; 1235\& struct whatever *mostinteresting;
1198\& }; 1236\& };
1199\& 1237\&
… …
1204.PP 1242.PP
1205And since your callback will be called with a pointer to the watcher, you 1243And since your callback will be called with a pointer to the watcher, you
1206can cast it back to your own type: 1244can cast it back to your own type:
1207.PP 1245.PP
1208.Vb 5 1246.Vb 5
1209\& static void my_cb (struct ev_loop *loop, struct ev_io *w_, int revents) 1247\& static void my_cb (struct ev_loop *loop, ev_io *w_, int revents)
1210\& { 1248\& {
1211\& struct my_io *w = (struct my_io *)w_; 1249\& struct my_io *w = (struct my_io *)w_;
1212\& ... 1250\& ...
1213\& } 1251\& }
1214.Ve 1252.Ve
… …
1236.PP 1274.PP
1237.Vb 1 1275.Vb 1
1238\& #include <stddef.h> 1276\& #include <stddef.h>
1239\& 1277\&
1240\& static void 1278\& static void
1241\& t1_cb (EV_P_ struct ev_timer *w, int revents) 1279\& t1_cb (EV_P_ ev_timer *w, int revents)
1242\& { 1280\& {
1243\& struct my_biggy big = (struct my_biggy * 1281\& struct my_biggy big = (struct my_biggy *
1244\& (((char *)w) \- offsetof (struct my_biggy, t1)); 1282\& (((char *)w) \- offsetof (struct my_biggy, t1));
1245\& } 1283\& }
1246\& 1284\&
1247\& static void 1285\& static void
1248\& t2_cb (EV_P_ struct ev_timer *w, int revents) 1286\& t2_cb (EV_P_ ev_timer *w, int revents)
1249\& { 1287\& {
1250\& struct my_biggy big = (struct my_biggy * 1288\& struct my_biggy big = (struct my_biggy *
1251\& (((char *)w) \- offsetof (struct my_biggy, t2)); 1289\& (((char *)w) \- offsetof (struct my_biggy, t2));
1252\& } 1290\& }
1253.Ve 1291.Ve
… …
1387readable, but only once. Since it is likely line-buffered, you could 1425readable, but only once. Since it is likely line-buffered, you could
1388attempt to read a whole line in the callback. 1426attempt to read a whole line in the callback.
1389.PP 1427.PP
1390.Vb 6 1428.Vb 6
1391\& static void 1429\& static void
1392\& stdin_readable_cb (struct ev_loop *loop, struct ev_io *w, int revents) 1430\& stdin_readable_cb (struct ev_loop *loop, ev_io *w, int revents)
1393\& { 1431\& {
1394\& ev_io_stop (loop, w); 1432\& ev_io_stop (loop, w);
1395\& .. read from stdin here (or from w\->fd) and handle any I/O errors 1433\& .. read from stdin here (or from w\->fd) and handle any I/O errors
1396\& } 1434\& }
1397\& 1435\&
1398\& ... 1436\& ...
1399\& struct ev_loop *loop = ev_default_init (0); 1437\& struct ev_loop *loop = ev_default_init (0);
1400\& struct ev_io stdin_readable; 1438\& ev_io stdin_readable;
1401\& ev_io_init (&stdin_readable, stdin_readable_cb, STDIN_FILENO, EV_READ); 1439\& ev_io_init (&stdin_readable, stdin_readable_cb, STDIN_FILENO, EV_READ);
1402\& ev_io_start (loop, &stdin_readable); 1440\& ev_io_start (loop, &stdin_readable);
1403\& ev_loop (loop, 0); 1441\& ev_loop (loop, 0);
1404.Ve 1442.Ve
1405.ie n .Sh """ev_timer"" \- relative and optionally repeating timeouts" 1443.ie n .Sh """ev_timer"" \- relative and optionally repeating timeouts"
… …
1415monotonic clock option helps a lot here). 1453monotonic clock option helps a lot here).
1416.PP 1454.PP
1417The callback is guaranteed to be invoked only \fIafter\fR its timeout has 1455The callback is guaranteed to be invoked only \fIafter\fR its timeout has
1418passed, but if multiple timers become ready during the same loop iteration 1456passed, but if multiple timers become ready during the same loop iteration
1419then order of execution is undefined. 1457then order of execution is undefined.
1458.PP
1459\fIBe smart about timeouts\fR
1460.IX Subsection "Be smart about timeouts"
1461.PP
1462Many real-world problems involve some kind of timeout, usually for error
1463recovery. A typical example is an \s-1HTTP\s0 request \- if the other side hangs,
1464you want to raise some error after a while.
1465.PP
1466What follows are some ways to handle this problem, from obvious and
1467inefficient to smart and efficient.
1468.PP
1469In the following, a 60 second activity timeout is assumed \- a timeout that
1470gets reset to 60 seconds each time there is activity (e.g. each time some
1471data or other life sign was received).
1472.IP "1. Use a timer and stop, reinitialise and start it on activity." 4
1473.IX Item "1. Use a timer and stop, reinitialise and start it on activity."
1474This is the most obvious, but not the most simple way: In the beginning,
1475start the watcher:
1476.Sp
1477.Vb 2
1478\& ev_timer_init (timer, callback, 60., 0.);
1479\& ev_timer_start (loop, timer);
1480.Ve
1481.Sp
1482Then, each time there is some activity, \f(CW\*(C`ev_timer_stop\*(C'\fR it, initialise it
1483and start it again:
1484.Sp
1485.Vb 3
1486\& ev_timer_stop (loop, timer);
1487\& ev_timer_set (timer, 60., 0.);
1488\& ev_timer_start (loop, timer);
1489.Ve
1490.Sp
1491This is relatively simple to implement, but means that each time there is
1492some activity, libev will first have to remove the timer from its internal
1493data structure and then add it again. Libev tries to be fast, but it's
1494still not a constant-time operation.
1495.ie n .IP "2. Use a timer and re-start it with ""ev_timer_again"" inactivity." 4
1496.el .IP "2. Use a timer and re-start it with \f(CWev_timer_again\fR inactivity." 4
1497.IX Item "2. Use a timer and re-start it with ev_timer_again inactivity."
1498This is the easiest way, and involves using \f(CW\*(C`ev_timer_again\*(C'\fR instead of
1499\&\f(CW\*(C`ev_timer_start\*(C'\fR.
1500.Sp
1501To implement this, configure an \f(CW\*(C`ev_timer\*(C'\fR with a \f(CW\*(C`repeat\*(C'\fR value
1502of \f(CW60\fR and then call \f(CW\*(C`ev_timer_again\*(C'\fR at start and each time you
1503successfully read or write some data. If you go into an idle state where
1504you do not expect data to travel on the socket, you can \f(CW\*(C`ev_timer_stop\*(C'\fR
1505the timer, and \f(CW\*(C`ev_timer_again\*(C'\fR will automatically restart it if need be.
1506.Sp
1507That means you can ignore both the \f(CW\*(C`ev_timer_start\*(C'\fR function and the
1508\&\f(CW\*(C`after\*(C'\fR argument to \f(CW\*(C`ev_timer_set\*(C'\fR, and only ever use the \f(CW\*(C`repeat\*(C'\fR
1509member and \f(CW\*(C`ev_timer_again\*(C'\fR.
1510.Sp
1511At start:
1512.Sp
1513.Vb 3
1514\& ev_timer_init (timer, callback);
1515\& timer\->repeat = 60.;
1516\& ev_timer_again (loop, timer);
1517.Ve
1518.Sp
1519Each time there is some activity:
1520.Sp
1521.Vb 1
1522\& ev_timer_again (loop, timer);
1523.Ve
1524.Sp
1525It is even possible to change the time-out on the fly, regardless of
1526whether the watcher is active or not:
1527.Sp
1528.Vb 2
1529\& timer\->repeat = 30.;
1530\& ev_timer_again (loop, timer);
1531.Ve
1532.Sp
1533This is slightly more efficient then stopping/starting the timer each time
1534you want to modify its timeout value, as libev does not have to completely
1535remove and re-insert the timer from/into its internal data structure.
1536.Sp
1537It is, however, even simpler than the \*(L"obvious\*(R" way to do it.
1538.IP "3. Let the timer time out, but then re-arm it as required." 4
1539.IX Item "3. Let the timer time out, but then re-arm it as required."
1540This method is more tricky, but usually most efficient: Most timeouts are
1541relatively long compared to the intervals between other activity \- in
1542our example, within 60 seconds, there are usually many I/O events with
1543associated activity resets.
1544.Sp
1545In this case, it would be more efficient to leave the \f(CW\*(C`ev_timer\*(C'\fR alone,
1546but remember the time of last activity, and check for a real timeout only
1547within the callback:
1548.Sp
1549.Vb 1
1550\& ev_tstamp last_activity; // time of last activity
1551\&
1552\& static void
1553\& callback (EV_P_ ev_timer *w, int revents)
1554\& {
1555\& ev_tstamp now = ev_now (EV_A);
1556\& ev_tstamp timeout = last_activity + 60.;
1557\&
1558\& // if last_activity + 60. is older than now, we did time out
1559\& if (timeout < now)
1560\& {
1561\& // timeout occured, take action
1562\& }
1563\& else
1564\& {
1565\& // callback was invoked, but there was some activity, re\-arm
1566\& // the watcher to fire in last_activity + 60, which is
1567\& // guaranteed to be in the future, so "again" is positive:
1568\& w\->repeat = timeout \- now;
1569\& ev_timer_again (EV_A_ w);
1570\& }
1571\& }
1572.Ve
1573.Sp
1574To summarise the callback: first calculate the real timeout (defined
1575as \*(L"60 seconds after the last activity\*(R"), then check if that time has
1576been reached, which means something \fIdid\fR, in fact, time out. Otherwise
1577the callback was invoked too early (\f(CW\*(C`timeout\*(C'\fR is in the future), so
1578re-schedule the timer to fire at that future time, to see if maybe we have
1579a timeout then.
1580.Sp
1581Note how \f(CW\*(C`ev_timer_again\*(C'\fR is used, taking advantage of the
1582\&\f(CW\*(C`ev_timer_again\*(C'\fR optimisation when the timer is already running.
1583.Sp
1584This scheme causes more callback invocations (about one every 60 seconds
1585minus half the average time between activity), but virtually no calls to
1586libev to change the timeout.
1587.Sp
1588To start the timer, simply initialise the watcher and set \f(CW\*(C`last_activity\*(C'\fR
1589to the current time (meaning we just have some activity :), then call the
1590callback, which will \*(L"do the right thing\*(R" and start the timer:
1591.Sp
1592.Vb 3
1593\& ev_timer_init (timer, callback);
1594\& last_activity = ev_now (loop);
1595\& callback (loop, timer, EV_TIMEOUT);
1596.Ve
1597.Sp
1598And when there is some activity, simply store the current time in
1599\&\f(CW\*(C`last_activity\*(C'\fR, no libev calls at all:
1600.Sp
1601.Vb 1
1602\& last_actiivty = ev_now (loop);
1603.Ve
1604.Sp
1605This technique is slightly more complex, but in most cases where the
1606time-out is unlikely to be triggered, much more efficient.
1607.Sp
1608Changing the timeout is trivial as well (if it isn't hard-coded in the
1609callback :) \- just change the timeout and invoke the callback, which will
1610fix things for you.
1611.IP "4. Wee, just use a double-linked list for your timeouts." 4
1612.IX Item "4. Wee, just use a double-linked list for your timeouts."
1613If there is not one request, but many thousands (millions...), all
1614employing some kind of timeout with the same timeout value, then one can
1615do even better:
1616.Sp
1617When starting the timeout, calculate the timeout value and put the timeout
1618at the \fIend\fR of the list.
1619.Sp
1620Then use an \f(CW\*(C`ev_timer\*(C'\fR to fire when the timeout at the \fIbeginning\fR of
1621the list is expected to fire (for example, using the technique #3).
1622.Sp
1623When there is some activity, remove the timer from the list, recalculate
1624the timeout, append it to the end of the list again, and make sure to
1625update the \f(CW\*(C`ev_timer\*(C'\fR if it was taken from the beginning of the list.
1626.Sp
1627This way, one can manage an unlimited number of timeouts in O(1) time for
1628starting, stopping and updating the timers, at the expense of a major
1629complication, and having to use a constant timeout. The constant timeout
1630ensures that the list stays sorted.
1631.PP
1632So which method the best?
1633.PP
1634Method #2 is a simple no-brain-required solution that is adequate in most
1635situations. Method #3 requires a bit more thinking, but handles many cases
1636better, and isn't very complicated either. In most case, choosing either
1637one is fine, with #3 being better in typical situations.
1638.PP
1639Method #1 is almost always a bad idea, and buys you nothing. Method #4 is
1640rather complicated, but extremely efficient, something that really pays
1641off after the first million or so of active timers, i.e. it's usually
1642overkill :)
1420.PP 1643.PP
1421\fIThe special problem of time updates\fR 1644\fIThe special problem of time updates\fR
1422.IX Subsection "The special problem of time updates" 1645.IX Subsection "The special problem of time updates"
1423.PP 1646.PP
1424Establishing the current time is a costly operation (it usually takes at 1647Establishing the current time is a costly operation (it usually takes at
… …
1470If the timer is started but non-repeating, stop it (as if it timed out). 1693If the timer is started but non-repeating, stop it (as if it timed out).
1471.Sp 1694.Sp
1472If the timer is repeating, either start it if necessary (with the 1695If the timer is repeating, either start it if necessary (with the
1473\&\f(CW\*(C`repeat\*(C'\fR value), or reset the running timer to the \f(CW\*(C`repeat\*(C'\fR value. 1696\&\f(CW\*(C`repeat\*(C'\fR value), or reset the running timer to the \f(CW\*(C`repeat\*(C'\fR value.
1474.Sp 1697.Sp
1475This sounds a bit complicated, but here is a useful and typical 1698This sounds a bit complicated, see \*(L"Be smart about timeouts\*(R", above, for a
1476example: Imagine you have a \s-1TCP\s0 connection and you want a so-called idle 1699usage example.
1477timeout, that is, you want to be called when there have been, say, 60
1478seconds of inactivity on the socket. The easiest way to do this is to
1479configure an \f(CW\*(C`ev_timer\*(C'\fR with a \f(CW\*(C`repeat\*(C'\fR value of \f(CW60\fR and then call
1480\&\f(CW\*(C`ev_timer_again\*(C'\fR each time you successfully read or write some data. If
1481you go into an idle state where you do not expect data to travel on the
1482socket, you can \f(CW\*(C`ev_timer_stop\*(C'\fR the timer, and \f(CW\*(C`ev_timer_again\*(C'\fR will
1483automatically restart it if need be.
1484.Sp
1485That means you can ignore the \f(CW\*(C`after\*(C'\fR value and \f(CW\*(C`ev_timer_start\*(C'\fR
1486altogether and only ever use the \f(CW\*(C`repeat\*(C'\fR value and \f(CW\*(C`ev_timer_again\*(C'\fR:
1487.Sp
1488.Vb 8
1489\& ev_timer_init (timer, callback, 0., 5.);
1490\& ev_timer_again (loop, timer);
1491\& ...
1492\& timer\->again = 17.;
1493\& ev_timer_again (loop, timer);
1494\& ...
1495\& timer\->again = 10.;
1496\& ev_timer_again (loop, timer);
1497.Ve
1498.Sp
1499This is more slightly efficient then stopping/starting the timer each time
1500you want to modify its timeout value.
1501.Sp
1502Note, however, that it is often even more efficient to remember the
1503time of the last activity and let the timer time-out naturally. In the
1504callback, you then check whether the time-out is real, or, if there was
1505some activity, you reschedule the watcher to time-out in \*(L"last_activity +
1506timeout \- ev_now ()\*(R" seconds.
1507.IP "ev_tstamp repeat [read\-write]" 4 1700.IP "ev_tstamp repeat [read\-write]" 4
1508.IX Item "ev_tstamp repeat [read-write]" 1701.IX Item "ev_tstamp repeat [read-write]"
1509The current \f(CW\*(C`repeat\*(C'\fR value. Will be used each time the watcher times out 1702The current \f(CW\*(C`repeat\*(C'\fR value. Will be used each time the watcher times out
1510or \f(CW\*(C`ev_timer_again\*(C'\fR is called, and determines the next timeout (if any), 1703or \f(CW\*(C`ev_timer_again\*(C'\fR is called, and determines the next timeout (if any),
1511which is also when any modifications are taken into account. 1704which is also when any modifications are taken into account.
… …
1515.PP 1708.PP
1516Example: Create a timer that fires after 60 seconds. 1709Example: Create a timer that fires after 60 seconds.
1517.PP 1710.PP
1518.Vb 5 1711.Vb 5
1519\& static void 1712\& static void
1520\& one_minute_cb (struct ev_loop *loop, struct ev_timer *w, int revents) 1713\& one_minute_cb (struct ev_loop *loop, ev_timer *w, int revents)
1521\& { 1714\& {
1522\& .. one minute over, w is actually stopped right here 1715\& .. one minute over, w is actually stopped right here
1523\& } 1716\& }
1524\& 1717\&
1525\& struct ev_timer mytimer; 1718\& ev_timer mytimer;
1526\& ev_timer_init (&mytimer, one_minute_cb, 60., 0.); 1719\& ev_timer_init (&mytimer, one_minute_cb, 60., 0.);
1527\& ev_timer_start (loop, &mytimer); 1720\& ev_timer_start (loop, &mytimer);
1528.Ve 1721.Ve
1529.PP 1722.PP
1530Example: Create a timeout timer that times out after 10 seconds of 1723Example: Create a timeout timer that times out after 10 seconds of
1531inactivity. 1724inactivity.
1532.PP 1725.PP
1533.Vb 5 1726.Vb 5
1534\& static void 1727\& static void
1535\& timeout_cb (struct ev_loop *loop, struct ev_timer *w, int revents) 1728\& timeout_cb (struct ev_loop *loop, ev_timer *w, int revents)
1536\& { 1729\& {
1537\& .. ten seconds without any activity 1730\& .. ten seconds without any activity
1538\& } 1731\& }
1539\& 1732\&
1540\& struct ev_timer mytimer; 1733\& ev_timer mytimer;
1541\& ev_timer_init (&mytimer, timeout_cb, 0., 10.); /* note, only repeat used */ 1734\& ev_timer_init (&mytimer, timeout_cb, 0., 10.); /* note, only repeat used */
1542\& ev_timer_again (&mytimer); /* start timer */ 1735\& ev_timer_again (&mytimer); /* start timer */
1543\& ev_loop (loop, 0); 1736\& ev_loop (loop, 0);
1544\& 1737\&
1545\& // and in some piece of code that gets executed on any "activity": 1738\& // and in some piece of code that gets executed on any "activity":
… …
1632.Sp 1825.Sp
1633If you need to stop it, return \f(CW\*(C`now + 1e30\*(C'\fR (or so, fudge fudge) and stop 1826If you need to stop it, return \f(CW\*(C`now + 1e30\*(C'\fR (or so, fudge fudge) and stop
1634it afterwards (e.g. by starting an \f(CW\*(C`ev_prepare\*(C'\fR watcher, which is the 1827it afterwards (e.g. by starting an \f(CW\*(C`ev_prepare\*(C'\fR watcher, which is the
1635only event loop modification you are allowed to do). 1828only event loop modification you are allowed to do).
1636.Sp 1829.Sp
1637The callback prototype is \f(CW\*(C`ev_tstamp (*reschedule_cb)(struct ev_periodic 1830The callback prototype is \f(CW\*(C`ev_tstamp (*reschedule_cb)(ev_periodic
1638*w, ev_tstamp now)\*(C'\fR, e.g.: 1831*w, ev_tstamp now)\*(C'\fR, e.g.:
1639.Sp 1832.Sp
1640.Vb 4 1833.Vb 5
1834\& static ev_tstamp
1641\& static ev_tstamp my_rescheduler (struct ev_periodic *w, ev_tstamp now) 1835\& my_rescheduler (ev_periodic *w, ev_tstamp now)
1642\& { 1836\& {
1643\& return now + 60.; 1837\& return now + 60.;
1644\& } 1838\& }
1645.Ve 1839.Ve
1646.Sp 1840.Sp
… …
1680.IP "ev_tstamp interval [read\-write]" 4 1874.IP "ev_tstamp interval [read\-write]" 4
1681.IX Item "ev_tstamp interval [read-write]" 1875.IX Item "ev_tstamp interval [read-write]"
1682The current interval value. Can be modified any time, but changes only 1876The current interval value. Can be modified any time, but changes only
1683take effect when the periodic timer fires or \f(CW\*(C`ev_periodic_again\*(C'\fR is being 1877take effect when the periodic timer fires or \f(CW\*(C`ev_periodic_again\*(C'\fR is being
1684called. 1878called.
1685.IP "ev_tstamp (*reschedule_cb)(struct ev_periodic *w, ev_tstamp now) [read\-write]" 4 1879.IP "ev_tstamp (*reschedule_cb)(ev_periodic *w, ev_tstamp now) [read\-write]" 4
1686.IX Item "ev_tstamp (*reschedule_cb)(struct ev_periodic *w, ev_tstamp now) [read-write]" 1880.IX Item "ev_tstamp (*reschedule_cb)(ev_periodic *w, ev_tstamp now) [read-write]"
1687The current reschedule callback, or \f(CW0\fR, if this functionality is 1881The current reschedule callback, or \f(CW0\fR, if this functionality is
1688switched off. Can be changed any time, but changes only take effect when 1882switched off. Can be changed any time, but changes only take effect when
1689the periodic timer fires or \f(CW\*(C`ev_periodic_again\*(C'\fR is being called. 1883the periodic timer fires or \f(CW\*(C`ev_periodic_again\*(C'\fR is being called.
1690.PP 1884.PP
1691\fIExamples\fR 1885\fIExamples\fR
… …
1695system time is divisible by 3600. The callback invocation times have 1889system time is divisible by 3600. The callback invocation times have
1696potentially a lot of jitter, but good long-term stability. 1890potentially a lot of jitter, but good long-term stability.
1697.PP 1891.PP
1698.Vb 5 1892.Vb 5
1699\& static void 1893\& static void
1700\& clock_cb (struct ev_loop *loop, struct ev_io *w, int revents) 1894\& clock_cb (struct ev_loop *loop, ev_io *w, int revents)
1701\& { 1895\& {
1702\& ... its now a full hour (UTC, or TAI or whatever your clock follows) 1896\& ... its now a full hour (UTC, or TAI or whatever your clock follows)
1703\& } 1897\& }
1704\& 1898\&
1705\& struct ev_periodic hourly_tick; 1899\& ev_periodic hourly_tick;
1706\& ev_periodic_init (&hourly_tick, clock_cb, 0., 3600., 0); 1900\& ev_periodic_init (&hourly_tick, clock_cb, 0., 3600., 0);
1707\& ev_periodic_start (loop, &hourly_tick); 1901\& ev_periodic_start (loop, &hourly_tick);
1708.Ve 1902.Ve
1709.PP 1903.PP
1710Example: The same as above, but use a reschedule callback to do it: 1904Example: The same as above, but use a reschedule callback to do it:
1711.PP 1905.PP
1712.Vb 1 1906.Vb 1
1713\& #include <math.h> 1907\& #include <math.h>
1714\& 1908\&
1715\& static ev_tstamp 1909\& static ev_tstamp
1716\& my_scheduler_cb (struct ev_periodic *w, ev_tstamp now) 1910\& my_scheduler_cb (ev_periodic *w, ev_tstamp now)
1717\& { 1911\& {
1718\& return now + (3600. \- fmod (now, 3600.)); 1912\& return now + (3600. \- fmod (now, 3600.));
1719\& } 1913\& }
1720\& 1914\&
1721\& ev_periodic_init (&hourly_tick, clock_cb, 0., 0., my_scheduler_cb); 1915\& ev_periodic_init (&hourly_tick, clock_cb, 0., 0., my_scheduler_cb);
1722.Ve 1916.Ve
1723.PP 1917.PP
1724Example: Call a callback every hour, starting now: 1918Example: Call a callback every hour, starting now:
1725.PP 1919.PP
1726.Vb 4 1920.Vb 4
1727\& struct ev_periodic hourly_tick; 1921\& ev_periodic hourly_tick;
1728\& ev_periodic_init (&hourly_tick, clock_cb, 1922\& ev_periodic_init (&hourly_tick, clock_cb,
1729\& fmod (ev_now (loop), 3600.), 3600., 0); 1923\& fmod (ev_now (loop), 3600.), 3600., 0);
1730\& ev_periodic_start (loop, &hourly_tick); 1924\& ev_periodic_start (loop, &hourly_tick);
1731.Ve 1925.Ve
1732.ie n .Sh """ev_signal"" \- signal me when a signal gets signalled!" 1926.ie n .Sh """ev_signal"" \- signal me when a signal gets signalled!"
… …
1773.PP 1967.PP
1774Example: Try to exit cleanly on \s-1SIGINT\s0. 1968Example: Try to exit cleanly on \s-1SIGINT\s0.
1775.PP 1969.PP
1776.Vb 5 1970.Vb 5
1777\& static void 1971\& static void
1778\& sigint_cb (struct ev_loop *loop, struct ev_signal *w, int revents) 1972\& sigint_cb (struct ev_loop *loop, ev_signal *w, int revents)
1779\& { 1973\& {
1780\& ev_unloop (loop, EVUNLOOP_ALL); 1974\& ev_unloop (loop, EVUNLOOP_ALL);
1781\& } 1975\& }
1782\& 1976\&
1783\& struct ev_signal signal_watcher; 1977\& ev_signal signal_watcher;
1784\& ev_signal_init (&signal_watcher, sigint_cb, SIGINT); 1978\& ev_signal_init (&signal_watcher, sigint_cb, SIGINT);
1785\& ev_signal_start (loop, &signal_watcher); 1979\& ev_signal_start (loop, &signal_watcher);
1786.Ve 1980.Ve
1787.ie n .Sh """ev_child"" \- watch out for process status changes" 1981.ie n .Sh """ev_child"" \- watch out for process status changes"
1788.el .Sh "\f(CWev_child\fP \- watch out for process status changes" 1982.el .Sh "\f(CWev_child\fP \- watch out for process status changes"
… …
1863.PP 2057.PP
1864.Vb 1 2058.Vb 1
1865\& ev_child cw; 2059\& ev_child cw;
1866\& 2060\&
1867\& static void 2061\& static void
1868\& child_cb (EV_P_ struct ev_child *w, int revents) 2062\& child_cb (EV_P_ ev_child *w, int revents)
1869\& { 2063\& {
1870\& ev_child_stop (EV_A_ w); 2064\& ev_child_stop (EV_A_ w);
1871\& printf ("process %d exited with status %x\en", w\->rpid, w\->rstatus); 2065\& printf ("process %d exited with status %x\en", w\->rpid, w\->rstatus);
1872\& } 2066\& }
1873\& 2067\&
… …
1888.Ve 2082.Ve
1889.ie n .Sh """ev_stat"" \- did the file attributes just change?" 2083.ie n .Sh """ev_stat"" \- did the file attributes just change?"
1890.el .Sh "\f(CWev_stat\fP \- did the file attributes just change?" 2084.el .Sh "\f(CWev_stat\fP \- did the file attributes just change?"
1891.IX Subsection "ev_stat - did the file attributes just change?" 2085.IX Subsection "ev_stat - did the file attributes just change?"
1892This watches a file system path for attribute changes. That is, it calls 2086This watches a file system path for attribute changes. That is, it calls
1893\&\f(CW\*(C`stat\*(C'\fR regularly (or when the \s-1OS\s0 says it changed) and sees if it changed 2087\&\f(CW\*(C`stat\*(C'\fR on that path in regular intervals (or when the \s-1OS\s0 says it changed)
1894compared to the last time, invoking the callback if it did. 2088and sees if it changed compared to the last time, invoking the callback if
2089it did.
1895.PP 2090.PP
1896The path does not need to exist: changing from \*(L"path exists\*(R" to \*(L"path does 2091The path does not need to exist: changing from \*(L"path exists\*(R" to \*(L"path does
1897not exist\*(R" is a status change like any other. The condition \*(L"path does 2092not exist\*(R" is a status change like any other. The condition \*(L"path does not
1898not exist\*(R" is signified by the \f(CW\*(C`st_nlink\*(C'\fR field being zero (which is 2093exist\*(R" (or more correctly \*(L"path cannot be stat'ed\*(R") is signified by the
1899otherwise always forced to be at least one) and all the other fields of 2094\&\f(CW\*(C`st_nlink\*(C'\fR field being zero (which is otherwise always forced to be at
1900the stat buffer having unspecified contents. 2095least one) and all the other fields of the stat buffer having unspecified
2096contents.
1901.PP 2097.PP
1902The path \fIshould\fR be absolute and \fImust not\fR end in a slash. If it is 2098The path \fImust not\fR end in a slash or contain special components such as
2099\&\f(CW\*(C`.\*(C'\fR or \f(CW\*(C`..\*(C'\fR. The path \fIshould\fR be absolute: If it is relative and
1903relative and your working directory changes, the behaviour is undefined. 2100your working directory changes, then the behaviour is undefined.
1904.PP 2101.PP
1905Since there is no standard kernel interface to do this, the portable 2102Since there is no portable change notification interface available, the
1906implementation simply calls \f(CW\*(C`stat (2)\*(C'\fR regularly on the path to see if 2103portable implementation simply calls \f(CWstat(2)\fR regularly on the path
1907it changed somehow. You can specify a recommended polling interval for 2104to see if it changed somehow. You can specify a recommended polling
1908this case. If you specify a polling interval of \f(CW0\fR (highly recommended!) 2105interval for this case. If you specify a polling interval of \f(CW0\fR (highly
1909then a \fIsuitable, unspecified default\fR value will be used (which 2106recommended!) then a \fIsuitable, unspecified default\fR value will be used
1910you can expect to be around five seconds, although this might change 2107(which you can expect to be around five seconds, although this might
1911dynamically). Libev will also impose a minimum interval which is currently 2108change dynamically). Libev will also impose a minimum interval which is
1912around \f(CW0.1\fR, but thats usually overkill. 2109currently around \f(CW0.1\fR, but that's usually overkill.
1913.PP 2110.PP
1914This watcher type is not meant for massive numbers of stat watchers, 2111This watcher type is not meant for massive numbers of stat watchers,
1915as even with OS-supported change notifications, this can be 2112as even with OS-supported change notifications, this can be
1916resource-intensive. 2113resource-intensive.
1917.PP 2114.PP
1918At the time of this writing, the only OS-specific interface implemented 2115At the time of this writing, the only OS-specific interface implemented
1919is the Linux inotify interface (implementing kqueue support is left as 2116is the Linux inotify interface (implementing kqueue support is left as an
1920an exercise for the reader. Note, however, that the author sees no way 2117exercise for the reader. Note, however, that the author sees no way of
1921of implementing \f(CW\*(C`ev_stat\*(C'\fR semantics with kqueue). 2118implementing \f(CW\*(C`ev_stat\*(C'\fR semantics with kqueue, except as a hint).
1922.PP 2119.PP
1923\fI\s-1ABI\s0 Issues (Largefile Support)\fR 2120\fI\s-1ABI\s0 Issues (Largefile Support)\fR
1924.IX Subsection "ABI Issues (Largefile Support)" 2121.IX Subsection "ABI Issues (Largefile Support)"
1925.PP 2122.PP
1926Libev by default (unless the user overrides this) uses the default 2123Libev by default (unless the user overrides this) uses the default
… …
1928support disabled by default, you get the 32 bit version of the stat 2125support disabled by default, you get the 32 bit version of the stat
1929structure. When using the library from programs that change the \s-1ABI\s0 to 2126structure. When using the library from programs that change the \s-1ABI\s0 to
1930use 64 bit file offsets the programs will fail. In that case you have to 2127use 64 bit file offsets the programs will fail. In that case you have to
1931compile libev with the same flags to get binary compatibility. This is 2128compile libev with the same flags to get binary compatibility. This is
1932obviously the case with any flags that change the \s-1ABI\s0, but the problem is 2129obviously the case with any flags that change the \s-1ABI\s0, but the problem is
1933most noticeably disabled with ev_stat and large file support. 2130most noticeably displayed with ev_stat and large file support.
1934.PP 2131.PP
1935The solution for this is to lobby your distribution maker to make large 2132The solution for this is to lobby your distribution maker to make large
1936file interfaces available by default (as e.g. FreeBSD does) and not 2133file interfaces available by default (as e.g. FreeBSD does) and not
1937optional. Libev cannot simply switch on large file support because it has 2134optional. Libev cannot simply switch on large file support because it has
1938to exchange stat structures with application programs compiled using the 2135to exchange stat structures with application programs compiled using the
1939default compilation environment. 2136default compilation environment.
1940.PP 2137.PP
1941\fIInotify and Kqueue\fR 2138\fIInotify and Kqueue\fR
1942.IX Subsection "Inotify and Kqueue" 2139.IX Subsection "Inotify and Kqueue"
1943.PP 2140.PP
1944When \f(CW\*(C`inotify (7)\*(C'\fR support has been compiled into libev (generally 2141When \f(CW\*(C`inotify (7)\*(C'\fR support has been compiled into libev and present at
1945only available with Linux 2.6.25 or above due to bugs in earlier 2142runtime, it will be used to speed up change detection where possible. The
1946implementations) and present at runtime, it will be used to speed up 2143inotify descriptor will be created lazily when the first \f(CW\*(C`ev_stat\*(C'\fR
1947change detection where possible. The inotify descriptor will be created 2144watcher is being started.
1948lazily when the first \f(CW\*(C`ev_stat\*(C'\fR watcher is being started.
1949.PP 2145.PP
1950Inotify presence does not change the semantics of \f(CW\*(C`ev_stat\*(C'\fR watchers 2146Inotify presence does not change the semantics of \f(CW\*(C`ev_stat\*(C'\fR watchers
1951except that changes might be detected earlier, and in some cases, to avoid 2147except that changes might be detected earlier, and in some cases, to avoid
1952making regular \f(CW\*(C`stat\*(C'\fR calls. Even in the presence of inotify support 2148making regular \f(CW\*(C`stat\*(C'\fR calls. Even in the presence of inotify support
1953there are many cases where libev has to resort to regular \f(CW\*(C`stat\*(C'\fR polling, 2149there are many cases where libev has to resort to regular \f(CW\*(C`stat\*(C'\fR polling,
1954but as long as the path exists, libev usually gets away without polling. 2150but as long as kernel 2.6.25 or newer is used (2.6.24 and older have too
2151many bugs), the path exists (i.e. stat succeeds), and the path resides on
2152a local filesystem (libev currently assumes only ext2/3, jfs, reiserfs and
2153xfs are fully working) libev usually gets away without polling.
1955.PP 2154.PP
1956There is no support for kqueue, as apparently it cannot be used to 2155There is no support for kqueue, as apparently it cannot be used to
1957implement this functionality, due to the requirement of having a file 2156implement this functionality, due to the requirement of having a file
1958descriptor open on the object at all times, and detecting renames, unlinks 2157descriptor open on the object at all times, and detecting renames, unlinks
1959etc. is difficult. 2158etc. is difficult.
1960.PP 2159.PP
2160\fI\f(CI\*(C`stat ()\*(C'\fI is a synchronous operation\fR
2161.IX Subsection "stat () is a synchronous operation"
2162.PP
2163Libev doesn't normally do any kind of I/O itself, and so is not blocking
2164the process. The exception are \f(CW\*(C`ev_stat\*(C'\fR watchers \- those call \f(CW\*(C`stat
2165()\*(C'\fR, which is a synchronous operation.
2166.PP
2167For local paths, this usually doesn't matter: unless the system is very
2168busy or the intervals between stat's are large, a stat call will be fast,
2169as the path data is suually in memory already (except when starting the
2170watcher).
2171.PP
2172For networked file systems, calling \f(CW\*(C`stat ()\*(C'\fR can block an indefinite
2173time due to network issues, and even under good conditions, a stat call
2174often takes multiple milliseconds.
2175.PP
2176Therefore, it is best to avoid using \f(CW\*(C`ev_stat\*(C'\fR watchers on networked
2177paths, although this is fully supported by libev.
2178.PP
1961\fIThe special problem of stat time resolution\fR 2179\fIThe special problem of stat time resolution\fR
1962.IX Subsection "The special problem of stat time resolution" 2180.IX Subsection "The special problem of stat time resolution"
1963.PP 2181.PP
1964The \f(CW\*(C`stat ()\*(C'\fR system call only supports full-second resolution portably, and 2182The \f(CW\*(C`stat ()\*(C'\fR system call only supports full-second resolution portably,
1965even on systems where the resolution is higher, most file systems still 2183and even on systems where the resolution is higher, most file systems
1966only support whole seconds. 2184still only support whole seconds.
1967.PP 2185.PP
1968That means that, if the time is the only thing that changes, you can 2186That means that, if the time is the only thing that changes, you can
1969easily miss updates: on the first update, \f(CW\*(C`ev_stat\*(C'\fR detects a change and 2187easily miss updates: on the first update, \f(CW\*(C`ev_stat\*(C'\fR detects a change and
1970calls your callback, which does something. When there is another update 2188calls your callback, which does something. When there is another update
1971within the same second, \f(CW\*(C`ev_stat\*(C'\fR will be unable to detect unless the 2189within the same second, \f(CW\*(C`ev_stat\*(C'\fR will be unable to detect unless the
… …
2123Example: Dynamically allocate an \f(CW\*(C`ev_idle\*(C'\fR watcher, start it, and in the 2341Example: Dynamically allocate an \f(CW\*(C`ev_idle\*(C'\fR watcher, start it, and in the
2124callback, free it. Also, use no error checking, as usual. 2342callback, free it. Also, use no error checking, as usual.
2125.PP 2343.PP
2126.Vb 7 2344.Vb 7
2127\& static void 2345\& static void
2128\& idle_cb (struct ev_loop *loop, struct ev_idle *w, int revents) 2346\& idle_cb (struct ev_loop *loop, ev_idle *w, int revents)
2129\& { 2347\& {
2130\& free (w); 2348\& free (w);
2131\& // now do something you wanted to do when the program has 2349\& // now do something you wanted to do when the program has
2132\& // no longer anything immediate to do. 2350\& // no longer anything immediate to do.
2133\& } 2351\& }
2134\& 2352\&
2135\& struct ev_idle *idle_watcher = malloc (sizeof (struct ev_idle)); 2353\& ev_idle *idle_watcher = malloc (sizeof (ev_idle));
2136\& ev_idle_init (idle_watcher, idle_cb); 2354\& ev_idle_init (idle_watcher, idle_cb);
2137\& ev_idle_start (loop, idle_cb); 2355\& ev_idle_start (loop, idle_cb);
2138.Ve 2356.Ve
2139.ie n .Sh """ev_prepare""\fP and \f(CW""ev_check"" \- customise your event loop!" 2357.ie n .Sh """ev_prepare""\fP and \f(CW""ev_check"" \- customise your event loop!"
2140.el .Sh "\f(CWev_prepare\fP and \f(CWev_check\fP \- customise your event loop!" 2358.el .Sh "\f(CWev_prepare\fP and \f(CWev_check\fP \- customise your event loop!"
… …
2221.Vb 2 2439.Vb 2
2222\& static ev_io iow [nfd]; 2440\& static ev_io iow [nfd];
2223\& static ev_timer tw; 2441\& static ev_timer tw;
2224\& 2442\&
2225\& static void 2443\& static void
2226\& io_cb (ev_loop *loop, ev_io *w, int revents) 2444\& io_cb (struct ev_loop *loop, ev_io *w, int revents)
2227\& { 2445\& {
2228\& } 2446\& }
2229\& 2447\&
2230\& // create io watchers for each fd and a timer before blocking 2448\& // create io watchers for each fd and a timer before blocking
2231\& static void 2449\& static void
2232\& adns_prepare_cb (ev_loop *loop, ev_prepare *w, int revents) 2450\& adns_prepare_cb (struct ev_loop *loop, ev_prepare *w, int revents)
2233\& { 2451\& {
2234\& int timeout = 3600000; 2452\& int timeout = 3600000;
2235\& struct pollfd fds [nfd]; 2453\& struct pollfd fds [nfd];
2236\& // actual code will need to loop here and realloc etc. 2454\& // actual code will need to loop here and realloc etc.
2237\& adns_beforepoll (ads, fds, &nfd, &timeout, timeval_from (ev_time ())); 2455\& adns_beforepoll (ads, fds, &nfd, &timeout, timeval_from (ev_time ()));
… …
2252\& } 2470\& }
2253\& } 2471\& }
2254\& 2472\&
2255\& // stop all watchers after blocking 2473\& // stop all watchers after blocking
2256\& static void 2474\& static void
2257\& adns_check_cb (ev_loop *loop, ev_check *w, int revents) 2475\& adns_check_cb (struct ev_loop *loop, ev_check *w, int revents)
2258\& { 2476\& {
2259\& ev_timer_stop (loop, &tw); 2477\& ev_timer_stop (loop, &tw);
2260\& 2478\&
2261\& for (int i = 0; i < nfd; ++i) 2479\& for (int i = 0; i < nfd; ++i)
2262\& { 2480\& {
… …
2433used). 2651used).
2434.PP 2652.PP
2435.Vb 3 2653.Vb 3
2436\& struct ev_loop *loop_hi = ev_default_init (0); 2654\& struct ev_loop *loop_hi = ev_default_init (0);
2437\& struct ev_loop *loop_lo = 0; 2655\& struct ev_loop *loop_lo = 0;
2438\& struct ev_embed embed; 2656\& ev_embed embed;
2439\& 2657\&
2440\& // see if there is a chance of getting one that works 2658\& // see if there is a chance of getting one that works
2441\& // (remember that a flags value of 0 means autodetection) 2659\& // (remember that a flags value of 0 means autodetection)
2442\& loop_lo = ev_embeddable_backends () & ev_recommended_backends () 2660\& loop_lo = ev_embeddable_backends () & ev_recommended_backends ()
2443\& ? ev_loop_new (ev_embeddable_backends () & ev_recommended_backends ()) 2661\& ? ev_loop_new (ev_embeddable_backends () & ev_recommended_backends ())
… …
2459\&\f(CW\*(C`loop_socket\*(C'\fR. (One might optionally use \f(CW\*(C`EVFLAG_NOENV\*(C'\fR, too). 2677\&\f(CW\*(C`loop_socket\*(C'\fR. (One might optionally use \f(CW\*(C`EVFLAG_NOENV\*(C'\fR, too).
2460.PP 2678.PP
2461.Vb 3 2679.Vb 3
2462\& struct ev_loop *loop = ev_default_init (0); 2680\& struct ev_loop *loop = ev_default_init (0);
2463\& struct ev_loop *loop_socket = 0; 2681\& struct ev_loop *loop_socket = 0;
2464\& struct ev_embed embed; 2682\& ev_embed embed;
2465\& 2683\&
2466\& if (ev_supported_backends () & ~ev_recommended_backends () & EVBACKEND_KQUEUE) 2684\& if (ev_supported_backends () & ~ev_recommended_backends () & EVBACKEND_KQUEUE)
2467\& if ((loop_socket = ev_loop_new (EVBACKEND_KQUEUE)) 2685\& if ((loop_socket = ev_loop_new (EVBACKEND_KQUEUE))
2468\& { 2686\& {
2469\& ev_embed_init (&embed, 0, loop_socket); 2687\& ev_embed_init (&embed, 0, loop_socket);
… …
2601\fIWatcher-Specific Functions and Data Members\fR 2819\fIWatcher-Specific Functions and Data Members\fR
2602.IX Subsection "Watcher-Specific Functions and Data Members" 2820.IX Subsection "Watcher-Specific Functions and Data Members"
2603.IP "ev_async_init (ev_async *, callback)" 4 2821.IP "ev_async_init (ev_async *, callback)" 4
2604.IX Item "ev_async_init (ev_async *, callback)" 2822.IX Item "ev_async_init (ev_async *, callback)"
2605Initialises and configures the async watcher \- it has no parameters of any 2823Initialises and configures the async watcher \- it has no parameters of any
2606kind. There is a \f(CW\*(C`ev_asynd_set\*(C'\fR macro, but using it is utterly pointless, 2824kind. There is a \f(CW\*(C`ev_async_set\*(C'\fR macro, but using it is utterly pointless,
2607trust me. 2825trust me.
2608.IP "ev_async_send (loop, ev_async *)" 4 2826.IP "ev_async_send (loop, ev_async *)" 4
2609.IX Item "ev_async_send (loop, ev_async *)" 2827.IX Item "ev_async_send (loop, ev_async *)"
2610Sends/signals/activates the given \f(CW\*(C`ev_async\*(C'\fR watcher, that is, feeds 2828Sends/signals/activates the given \f(CW\*(C`ev_async\*(C'\fR watcher, that is, feeds
2611an \f(CW\*(C`EV_ASYNC\*(C'\fR event on the watcher into the event loop. Unlike 2829an \f(CW\*(C`EV_ASYNC\*(C'\fR event on the watcher into the event loop. Unlike
… …
2666\& /* doh, nothing entered */; 2884\& /* doh, nothing entered */;
2667\& } 2885\& }
2668\& 2886\&
2669\& ev_once (STDIN_FILENO, EV_READ, 10., stdin_ready, 0); 2887\& ev_once (STDIN_FILENO, EV_READ, 10., stdin_ready, 0);
2670.Ve 2888.Ve
2671.IP "ev_feed_event (ev_loop *, watcher *, int revents)" 4 2889.IP "ev_feed_event (struct ev_loop *, watcher *, int revents)" 4
2672.IX Item "ev_feed_event (ev_loop *, watcher *, int revents)" 2890.IX Item "ev_feed_event (struct ev_loop *, watcher *, int revents)"
2673Feeds the given event set into the event loop, as if the specified event 2891Feeds the given event set into the event loop, as if the specified event
2674had happened for the specified watcher (which must be a pointer to an 2892had happened for the specified watcher (which must be a pointer to an
2675initialised but not necessarily started event watcher). 2893initialised but not necessarily started event watcher).
2676.IP "ev_feed_fd_event (ev_loop *, int fd, int revents)" 4 2894.IP "ev_feed_fd_event (struct ev_loop *, int fd, int revents)" 4
2677.IX Item "ev_feed_fd_event (ev_loop *, int fd, int revents)" 2895.IX Item "ev_feed_fd_event (struct ev_loop *, int fd, int revents)"
2678Feed an event on the given fd, as if a file descriptor backend detected 2896Feed an event on the given fd, as if a file descriptor backend detected
2679the given events it. 2897the given events it.
2680.IP "ev_feed_signal_event (ev_loop *loop, int signum)" 4 2898.IP "ev_feed_signal_event (struct ev_loop *loop, int signum)" 4
2681.IX Item "ev_feed_signal_event (ev_loop *loop, int signum)" 2899.IX Item "ev_feed_signal_event (struct ev_loop *loop, int signum)"
2682Feed an event as if the given signal occurred (\f(CW\*(C`loop\*(C'\fR must be the default 2900Feed an event as if the given signal occurred (\f(CW\*(C`loop\*(C'\fR must be the default
2683loop!). 2901loop!).
2684.SH "LIBEVENT EMULATION" 2902.SH "LIBEVENT EMULATION"
2685.IX Header "LIBEVENT EMULATION" 2903.IX Header "LIBEVENT EMULATION"
2686Libev offers a compatibility emulation layer for libevent. It cannot 2904Libev offers a compatibility emulation layer for libevent. It cannot
… …
2901<http://rev.rubyforge.org/>. 3119<http://rev.rubyforge.org/>.
2902.IP "D" 4 3120.IP "D" 4
2903.IX Item "D" 3121.IX Item "D"
2904Leandro Lucarella has written a D language binding (\fIev.d\fR) for libev, to 3122Leandro Lucarella has written a D language binding (\fIev.d\fR) for libev, to
2905be found at <http://proj.llucax.com.ar/wiki/evd>. 3123be found at <http://proj.llucax.com.ar/wiki/evd>.
3124.IP "Ocaml" 4
3125.IX Item "Ocaml"
3126Erkki Seppala has written Ocaml bindings for libev, to be found at
3127<http://modeemi.cs.tut.fi/~flux/software/ocaml\-ev/>.
2906.SH "MACRO MAGIC" 3128.SH "MACRO MAGIC"
2907.IX Header "MACRO MAGIC" 3129.IX Header "MACRO MAGIC"
2908Libev can be compiled with a variety of options, the most fundamental 3130Libev can be compiled with a variety of options, the most fundamental
2909of which is \f(CW\*(C`EV_MULTIPLICITY\*(C'\fR. This option determines whether (most) 3131of which is \f(CW\*(C`EV_MULTIPLICITY\*(C'\fR. This option determines whether (most)
2910functions and callbacks have an initial \f(CW\*(C`struct ev_loop *\*(C'\fR argument. 3132functions and callbacks have an initial \f(CW\*(C`struct ev_loop *\*(C'\fR argument.
… …
3012\& #define EV_STANDALONE 1 3234\& #define EV_STANDALONE 1
3013\& #include "ev.h" 3235\& #include "ev.h"
3014.Ve 3236.Ve
3015.PP 3237.PP
3016Both header files and implementation files can be compiled with a \*(C+ 3238Both header files and implementation files can be compiled with a \*(C+
3017compiler (at least, thats a stated goal, and breakage will be treated 3239compiler (at least, that's a stated goal, and breakage will be treated
3018as a bug). 3240as a bug).
3019.PP 3241.PP
3020You need the following files in your source tree, or in a directory 3242You need the following files in your source tree, or in a directory
3021in your include path (e.g. in libev/ when using \-Ilibev): 3243in your include path (e.g. in libev/ when using \-Ilibev):
3022.PP 3244.PP
… …
3476loop, as long as you don't confuse yourself). The only exception is that 3698loop, as long as you don't confuse yourself). The only exception is that
3477you must not do this from \f(CW\*(C`ev_periodic\*(C'\fR reschedule callbacks. 3699you must not do this from \f(CW\*(C`ev_periodic\*(C'\fR reschedule callbacks.
3478.PP 3700.PP
3479Care has been taken to ensure that libev does not keep local state inside 3701Care has been taken to ensure that libev does not keep local state inside
3480\&\f(CW\*(C`ev_loop\*(C'\fR, and other calls do not usually allow for coroutine switches as 3702\&\f(CW\*(C`ev_loop\*(C'\fR, and other calls do not usually allow for coroutine switches as
3481they do not clal any callbacks. 3703they do not call any callbacks.
3482.Sh "\s-1COMPILER\s0 \s-1WARNINGS\s0" 3704.Sh "\s-1COMPILER\s0 \s-1WARNINGS\s0"
3483.IX Subsection "COMPILER WARNINGS" 3705.IX Subsection "COMPILER WARNINGS"
3484Depending on your compiler and compiler settings, you might get no or a 3706Depending on your compiler and compiler settings, you might get no or a
3485lot of warnings when compiling libev code. Some people are apparently 3707lot of warnings when compiling libev code. Some people are apparently
3486scared by this. 3708scared by this.
… …
3519\& ==2274== possibly lost: 0 bytes in 0 blocks. 3741\& ==2274== possibly lost: 0 bytes in 0 blocks.
3520\& ==2274== still reachable: 256 bytes in 1 blocks. 3742\& ==2274== still reachable: 256 bytes in 1 blocks.
3521.Ve 3743.Ve
3522.PP 3744.PP
3523Then there is no memory leak, just as memory accounted to global variables 3745Then there is no memory leak, just as memory accounted to global variables
3524is not a memleak \- the memory is still being refernced, and didn't leak. 3746is not a memleak \- the memory is still being referenced, and didn't leak.
3525.PP 3747.PP
3526Similarly, under some circumstances, valgrind might report kernel bugs 3748Similarly, under some circumstances, valgrind might report kernel bugs
3527as if it were a bug in libev (e.g. in realloc or in the poll backend, 3749as if it were a bug in libev (e.g. in realloc or in the poll backend,
3528although an acceptable workaround has been found here), or it might be 3750although an acceptable workaround has been found here), or it might be
3529confused. 3751confused.
… …
3749Sending involves a system call \fIiff\fR there were no other \f(CW\*(C`ev_async_send\*(C'\fR 3971Sending involves a system call \fIiff\fR there were no other \f(CW\*(C`ev_async_send\*(C'\fR
3750calls in the current loop iteration. Checking for async and signal events 3972calls in the current loop iteration. Checking for async and signal events
3751involves iterating over all running async watchers or all signal numbers. 3973involves iterating over all running async watchers or all signal numbers.
3752.SH "AUTHOR" 3974.SH "AUTHOR"
3753.IX Header "AUTHOR" 3975.IX Header "AUTHOR"
3754Marc Lehmann <libev@schmorp.de>. 3976Marc Lehmann <libev@schmorp.de>, with repeated corrections by Mikael Magnusson.

Diff Legend

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