… | |
… | |
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-10-30" "libev-3.48" "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" |
… | |
… | |
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 | \& // every watcher type has its own typedef\*(Aqd struct |
153 | \& // every watcher type has its own typedef\*(Aqd struct |
154 | \& // with the name ev_<type> |
154 | \& // with the name ev_TYPE |
155 | \& ev_io stdin_watcher; |
155 | \& ev_io stdin_watcher; |
156 | \& ev_timer timeout_watcher; |
156 | \& ev_timer timeout_watcher; |
157 | \& |
157 | \& |
158 | \& // all watcher callbacks have a similar signature |
158 | \& // all watcher callbacks have a similar signature |
159 | \& // this callback is called when data is readable on stdin |
159 | \& // this callback is called when data is readable on stdin |
160 | \& static void |
160 | \& static void |
161 | \& stdin_cb (EV_P_ struct ev_io *w, int revents) |
161 | \& stdin_cb (EV_P_ ev_io *w, int revents) |
162 | \& { |
162 | \& { |
163 | \& puts ("stdin ready"); |
163 | \& puts ("stdin ready"); |
164 | \& // for one\-shot events, one must manually stop the watcher |
164 | \& // for one\-shot events, one must manually stop the watcher |
165 | \& // with its corresponding stop function. |
165 | \& // with its corresponding stop function. |
166 | \& ev_io_stop (EV_A_ w); |
166 | \& ev_io_stop (EV_A_ w); |
… | |
… | |
169 | \& ev_unloop (EV_A_ EVUNLOOP_ALL); |
169 | \& ev_unloop (EV_A_ EVUNLOOP_ALL); |
170 | \& } |
170 | \& } |
171 | \& |
171 | \& |
172 | \& // another callback, this time for a time\-out |
172 | \& // another callback, this time for a time\-out |
173 | \& static void |
173 | \& static void |
174 | \& timeout_cb (EV_P_ struct ev_timer *w, int revents) |
174 | \& timeout_cb (EV_P_ ev_timer *w, int revents) |
175 | \& { |
175 | \& { |
176 | \& puts ("timeout"); |
176 | \& puts ("timeout"); |
177 | \& // this causes the innermost ev_loop to stop iterating |
177 | \& // this causes the innermost ev_loop to stop iterating |
178 | \& ev_unloop (EV_A_ EVUNLOOP_ONE); |
178 | \& ev_unloop (EV_A_ EVUNLOOP_ONE); |
179 | \& } |
179 | \& } |
180 | \& |
180 | \& |
181 | \& int |
181 | \& int |
182 | \& main (void) |
182 | \& main (void) |
183 | \& { |
183 | \& { |
184 | \& // use the default event loop unless you have special needs |
184 | \& // use the default event loop unless you have special needs |
185 | \& struct ev_loop *loop = ev_default_loop (0); |
185 | \& ev_loop *loop = ev_default_loop (0); |
186 | \& |
186 | \& |
187 | \& // initialise an io watcher, then start it |
187 | \& // initialise an io watcher, then start it |
188 | \& // this one will watch for stdin to become readable |
188 | \& // this one will watch for stdin to become readable |
189 | \& ev_io_init (&stdin_watcher, stdin_cb, /*STDIN_FILENO*/ 0, EV_READ); |
189 | \& ev_io_init (&stdin_watcher, stdin_cb, /*STDIN_FILENO*/ 0, EV_READ); |
190 | \& ev_io_start (loop, &stdin_watcher); |
190 | \& ev_io_start (loop, &stdin_watcher); |
… | |
… | |
240 | Libev is very configurable. In this manual the default (and most common) |
240 | Libev is very configurable. In this manual the default (and most common) |
241 | configuration will be described, which supports multiple event loops. For |
241 | configuration will be described, which supports multiple event loops. For |
242 | more info about various configuration options please have a look at |
242 | more 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 |
243 | \&\fB\s-1EMBED\s0\fR section in this manual. If libev was configured without support |
244 | for multiple event loops, then all functions taking an initial argument of |
244 | for multiple event loops, then all functions taking an initial argument of |
245 | name \f(CW\*(C`loop\*(C'\fR (which is always of type \f(CW\*(C`struct ev_loop *\*(C'\fR) will not have |
245 | name \f(CW\*(C`loop\*(C'\fR (which is always of type \f(CW\*(C`ev_loop *\*(C'\fR) will not have |
246 | this argument. |
246 | this argument. |
247 | .Sh "\s-1TIME\s0 \s-1REPRESENTATION\s0" |
247 | .Sh "\s-1TIME\s0 \s-1REPRESENTATION\s0" |
248 | .IX Subsection "TIME REPRESENTATION" |
248 | .IX Subsection "TIME REPRESENTATION" |
249 | Libev represents time as a single floating point number, representing the |
249 | Libev represents time as a single floating point number, representing the |
250 | (fractional) number of seconds since the (\s-1POSIX\s0) epoch (somewhere near |
250 | (fractional) number of seconds since the (\s-1POSIX\s0) epoch (somewhere near |
… | |
… | |
406 | \& ... |
406 | \& ... |
407 | \& ev_set_syserr_cb (fatal_error); |
407 | \& ev_set_syserr_cb (fatal_error); |
408 | .Ve |
408 | .Ve |
409 | .SH "FUNCTIONS CONTROLLING THE EVENT LOOP" |
409 | .SH "FUNCTIONS CONTROLLING THE EVENT LOOP" |
410 | .IX Header "FUNCTIONS CONTROLLING THE EVENT LOOP" |
410 | .IX Header "FUNCTIONS CONTROLLING THE EVENT LOOP" |
411 | An event loop is described by a \f(CW\*(C`struct ev_loop *\*(C'\fR. The library knows two |
411 | An event loop is described by a \f(CW\*(C`struct ev_loop *\*(C'\fR (the \f(CW\*(C`struct\*(C'\fR |
412 | types of such loops, the \fIdefault\fR loop, which supports signals and child |
412 | is \fInot\fR optional in this case, as there is also an \f(CW\*(C`ev_loop\*(C'\fR |
413 | events, and dynamically created loops which do not. |
413 | \&\fIfunction\fR). |
|
|
414 | .PP |
|
|
415 | The library knows two types of such loops, the \fIdefault\fR loop, which |
|
|
416 | supports signals and child events, and dynamically created loops which do |
|
|
417 | not. |
414 | .IP "struct ev_loop *ev_default_loop (unsigned int flags)" 4 |
418 | .IP "struct ev_loop *ev_default_loop (unsigned int flags)" 4 |
415 | .IX Item "struct ev_loop *ev_default_loop (unsigned int flags)" |
419 | .IX Item "struct ev_loop *ev_default_loop (unsigned int flags)" |
416 | This will initialise the default event loop if it hasn't been initialised |
420 | This will initialise the default event loop if it hasn't been initialised |
417 | yet and return it. If the default loop could not be initialised, returns |
421 | yet and return it. If the default loop could not be initialised, returns |
418 | false. If it already was initialised it simply returns it (and ignores the |
422 | false. If it already was initialised it simply returns it (and ignores the |
… | |
… | |
421 | If you don't know what event loop to use, use the one returned from this |
425 | If you don't know what event loop to use, use the one returned from this |
422 | function. |
426 | function. |
423 | .Sp |
427 | .Sp |
424 | Note that this function is \fInot\fR thread-safe, so if you want to use it |
428 | Note that this function is \fInot\fR thread-safe, so if you want to use it |
425 | from multiple threads, you have to lock (note also that this is unlikely, |
429 | from multiple threads, you have to lock (note also that this is unlikely, |
426 | as loops cannot bes hared easily between threads anyway). |
430 | as loops cannot be shared easily between threads anyway). |
427 | .Sp |
431 | .Sp |
428 | The default loop is the only loop that can handle \f(CW\*(C`ev_signal\*(C'\fR and |
432 | The 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 |
433 | \&\f(CW\*(C`ev_child\*(C'\fR watchers, and to do this, it always registers a handler |
430 | for \f(CW\*(C`SIGCHLD\*(C'\fR. If this is a problem for your application you can either |
434 | for \f(CW\*(C`SIGCHLD\*(C'\fR. If this is a problem for your application you can either |
431 | create a dynamic loop with \f(CW\*(C`ev_loop_new\*(C'\fR that doesn't do that, or you |
435 | create 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 |
510 | .el .IP "\f(CWEVBACKEND_EPOLL\fR (value 4, Linux)" 4 |
507 | .IX Item "EVBACKEND_EPOLL (value 4, Linux)" |
511 | .IX Item "EVBACKEND_EPOLL (value 4, Linux)" |
508 | For few fds, this backend is a bit little slower than poll and select, |
512 | For few fds, this backend is a bit little slower than poll and select, |
509 | but it scales phenomenally better. While poll and select usually scale |
513 | but it scales phenomenally better. While poll and select usually scale |
510 | like O(total_fds) where n is the total number of fds (or the highest fd), |
514 | like O(total_fds) where n is the total number of fds (or the highest fd), |
511 | epoll scales either O(1) or O(active_fds). The epoll design has a number |
515 | epoll scales either O(1) or O(active_fds). |
512 | of shortcomings, such as silently dropping events in some hard-to-detect |
516 | .Sp |
513 | cases and requiring a system call per fd change, no fork support and bad |
517 | The epoll mechanism deserves honorable mention as the most misdesigned |
514 | support for dup. |
518 | of the more advanced event mechanisms: mere annoyances include silently |
|
|
519 | dropping file descriptors, requiring a system call per change per file |
|
|
520 | descriptor (and unnecessary guessing of parameters), problems with dup and |
|
|
521 | so on. The biggest issue is fork races, however \- if a program forks then |
|
|
522 | \&\fIboth\fR parent and child process have to recreate the epoll set, which can |
|
|
523 | take considerable time (one syscall per file descriptor) and is of course |
|
|
524 | hard to detect. |
|
|
525 | .Sp |
|
|
526 | Epoll is also notoriously buggy \- embedding epoll fds \fIshould\fR work, but |
|
|
527 | of course \fIdoesn't\fR, and epoll just loves to report events for totally |
|
|
528 | \&\fIdifferent\fR file descriptors (even already closed ones, so one cannot |
|
|
529 | even remove them from the set) than registered in the set (especially |
|
|
530 | on \s-1SMP\s0 systems). Libev tries to counter these spurious notifications by |
|
|
531 | employing an additional generation counter and comparing that against the |
|
|
532 | events to filter out spurious ones, recreating the set when required. |
515 | .Sp |
533 | .Sp |
516 | While stopping, setting and starting an I/O watcher in the same iteration |
534 | While stopping, setting and starting an I/O watcher in the same iteration |
517 | will result in some caching, there is still a system call per such incident |
535 | will 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 |
536 | incident (because the same \fIfile descriptor\fR could point to a different |
519 | best to avoid that. Also, \f(CW\*(C`dup ()\*(C'\fR'ed file descriptors might not work |
537 | \&\fIfile description\fR now), so its best to avoid that. Also, \f(CW\*(C`dup ()\*(C'\fR'ed |
520 | very well if you register events for both fds. |
538 | file descriptors might not work very well if you register events for both |
521 | .Sp |
539 | file descriptors. |
522 | Please note that epoll sometimes generates spurious notifications, so you |
|
|
523 | need to use non-blocking I/O or other means to avoid blocking when no data |
|
|
524 | (or space) is available. |
|
|
525 | .Sp |
540 | .Sp |
526 | Best performance from this backend is achieved by not unregistering all |
541 | Best performance from this backend is achieved by not unregistering all |
527 | watchers for a file descriptor until it has been closed, if possible, |
542 | watchers for a file descriptor until it has been closed, if possible, |
528 | i.e. keep at least one watcher active per fd at all times. Stopping and |
543 | i.e. keep at least one watcher active per fd at all times. Stopping and |
529 | starting a watcher (without re-setting it) also usually doesn't cause |
544 | starting a watcher (without re-setting it) also usually doesn't cause |
530 | extra overhead. |
545 | extra overhead. A fork can both result in spurious notifications as well |
|
|
546 | as in libev having to destroy and recreate the epoll object, which can |
|
|
547 | take considerable time and thus should be avoided. |
531 | .Sp |
548 | .Sp |
532 | While nominally embeddable in other event loops, this feature is broken in |
549 | While nominally embeddable in other event loops, this feature is broken in |
533 | all kernel versions tested so far. |
550 | all kernel versions tested so far. |
534 | .Sp |
551 | .Sp |
535 | This backend maps \f(CW\*(C`EV_READ\*(C'\fR and \f(CW\*(C`EV_WRITE\*(C'\fR in the same way as |
552 | This 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. |
553 | \&\f(CW\*(C`EVBACKEND_POLL\*(C'\fR. |
537 | .ie n .IP """EVBACKEND_KQUEUE"" (value 8, most \s-1BSD\s0 clones)" 4 |
554 | .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 |
555 | .el .IP "\f(CWEVBACKEND_KQUEUE\fR (value 8, most \s-1BSD\s0 clones)" 4 |
539 | .IX Item "EVBACKEND_KQUEUE (value 8, most BSD clones)" |
556 | .IX Item "EVBACKEND_KQUEUE (value 8, most BSD clones)" |
540 | Kqueue deserves special mention, as at the time of this writing, it was |
557 | Kqueue deserves special mention, as at the time of this writing, it |
541 | broken on all BSDs except NetBSD (usually it doesn't work reliably with |
558 | was broken on all BSDs except NetBSD (usually it doesn't work reliably |
542 | anything but sockets and pipes, except on Darwin, where of course it's |
559 | with anything but sockets and pipes, except on Darwin, where of course |
543 | completely useless). For this reason it's not being \*(L"auto-detected\*(R" unless |
560 | it's completely useless). Unlike epoll, however, whose brokenness |
544 | you explicitly specify it in the flags (i.e. using \f(CW\*(C`EVBACKEND_KQUEUE\*(C'\fR) or |
561 | is by design, these kqueue bugs can (and eventually will) be fixed |
545 | libev was compiled on a known-to-be-good (\-enough) system like NetBSD. |
562 | without \s-1API\s0 changes to existing programs. For this reason it's not being |
|
|
563 | \&\*(L"auto-detected\*(R" unless you explicitly specify it in the flags (i.e. using |
|
|
564 | \&\f(CW\*(C`EVBACKEND_KQUEUE\*(C'\fR) or libev was compiled on a known-to-be-good (\-enough) |
|
|
565 | system like NetBSD. |
546 | .Sp |
566 | .Sp |
547 | You still can embed kqueue into a normal poll or select backend and use it |
567 | You still can embed kqueue into a normal poll or select backend and use it |
548 | only for sockets (after having made sure that sockets work with kqueue on |
568 | only for sockets (after having made sure that sockets work with kqueue on |
549 | the target platform). See \f(CW\*(C`ev_embed\*(C'\fR watchers for more info. |
569 | the target platform). See \f(CW\*(C`ev_embed\*(C'\fR watchers for more info. |
550 | .Sp |
570 | .Sp |
551 | It scales in the same way as the epoll backend, but the interface to the |
571 | It scales in the same way as the epoll backend, but the interface to the |
552 | kernel is more efficient (which says nothing about its actual speed, of |
572 | kernel is more efficient (which says nothing about its actual speed, of |
553 | course). While stopping, setting and starting an I/O watcher does never |
573 | course). While stopping, setting and starting an I/O watcher does never |
554 | cause an extra system call as with \f(CW\*(C`EVBACKEND_EPOLL\*(C'\fR, it still adds up to |
574 | cause an extra system call as with \f(CW\*(C`EVBACKEND_EPOLL\*(C'\fR, it still adds up to |
555 | two event changes per incident. Support for \f(CW\*(C`fork ()\*(C'\fR is very bad and it |
575 | two event changes per incident. Support for \f(CW\*(C`fork ()\*(C'\fR is very bad (but |
556 | drops fds silently in similarly hard-to-detect cases. |
576 | sane, unlike epoll) and it drops fds silently in similarly hard-to-detect |
|
|
577 | cases |
557 | .Sp |
578 | .Sp |
558 | This backend usually performs well under most conditions. |
579 | This backend usually performs well under most conditions. |
559 | .Sp |
580 | .Sp |
560 | While nominally embeddable in other event loops, this doesn't work |
581 | While nominally embeddable in other event loops, this doesn't work |
561 | everywhere, so you might need to test for this. And since it is broken |
582 | everywhere, so you might need to test for this. And since it is broken |
… | |
… | |
590 | might perform better. |
611 | might perform better. |
591 | .Sp |
612 | .Sp |
592 | On the positive side, with the exception of the spurious readiness |
613 | On the positive side, with the exception of the spurious readiness |
593 | notifications, this backend actually performed fully to specification |
614 | notifications, this backend actually performed fully to specification |
594 | in all tests and is fully embeddable, which is a rare feat among the |
615 | in all tests and is fully embeddable, which is a rare feat among the |
595 | OS-specific backends. |
616 | OS-specific backends (I vastly prefer correctness over speed hacks). |
596 | .Sp |
617 | .Sp |
597 | This backend maps \f(CW\*(C`EV_READ\*(C'\fR and \f(CW\*(C`EV_WRITE\*(C'\fR in the same way as |
618 | This 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. |
619 | \&\f(CW\*(C`EVBACKEND_POLL\*(C'\fR. |
599 | .ie n .IP """EVBACKEND_ALL""" 4 |
620 | .ie n .IP """EVBACKEND_ALL""" 4 |
600 | .el .IP "\f(CWEVBACKEND_ALL\fR" 4 |
621 | .el .IP "\f(CWEVBACKEND_ALL\fR" 4 |
… | |
… | |
660 | responsibility to either stop all watchers cleanly yourself \fIbefore\fR |
681 | responsibility to either stop all watchers cleanly yourself \fIbefore\fR |
661 | calling this function, or cope with the fact afterwards (which is usually |
682 | calling this function, or cope with the fact afterwards (which is usually |
662 | the easiest thing, you can just ignore the watchers and/or \f(CW\*(C`free ()\*(C'\fR them |
683 | the easiest thing, you can just ignore the watchers and/or \f(CW\*(C`free ()\*(C'\fR them |
663 | for example). |
684 | for example). |
664 | .Sp |
685 | .Sp |
665 | Note that certain global state, such as signal state, will not be freed by |
686 | Note that certain global state, such as signal state (and installed signal |
666 | this function, and related watchers (such as signal and child watchers) |
687 | handlers), will not be freed by this function, and related watchers (such |
667 | would need to be stopped manually. |
688 | as signal and child watchers) would need to be stopped manually. |
668 | .Sp |
689 | .Sp |
669 | In general it is not advisable to call this function except in the |
690 | In general it is not advisable to call this function except in the |
670 | rare occasion where you really need to free e.g. the signal handling |
691 | rare occasion where you really need to free e.g. the signal handling |
671 | pipe fds. If you need dynamically allocated loops it is better to use |
692 | pipe 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). |
693 | \&\f(CW\*(C`ev_loop_new\*(C'\fR and \f(CW\*(C`ev_loop_destroy\*(C'\fR). |
… | |
… | |
757 | the loop. |
778 | the loop. |
758 | .Sp |
779 | .Sp |
759 | A flags value of \f(CW\*(C`EVLOOP_ONESHOT\*(C'\fR will look for new events (waiting if |
780 | A flags value of \f(CW\*(C`EVLOOP_ONESHOT\*(C'\fR will look for new events (waiting if |
760 | necessary) and will handle those and any already outstanding ones. It |
781 | necessary) and will handle those and any already outstanding ones. It |
761 | will block your process until at least one new event arrives (which could |
782 | will block your process until at least one new event arrives (which could |
762 | be an event internal to libev itself, so there is no guarentee that a |
783 | be an event internal to libev itself, so there is no guarantee that a |
763 | user-registered callback will be called), and will return after one |
784 | user-registered callback will be called), and will return after one |
764 | iteration of the loop. |
785 | iteration of the loop. |
765 | .Sp |
786 | .Sp |
766 | This is useful if you are waiting for some external event in conjunction |
787 | This is useful if you are waiting for some external event in conjunction |
767 | with something not expressible using other libev watchers (i.e. "roll your |
788 | with something not expressible using other libev watchers (i.e. "roll your |
… | |
… | |
841 | .Sp |
862 | .Sp |
842 | Example: Create a signal watcher, but keep it from keeping \f(CW\*(C`ev_loop\*(C'\fR |
863 | Example: Create a signal watcher, but keep it from keeping \f(CW\*(C`ev_loop\*(C'\fR |
843 | running when nothing else is active. |
864 | running when nothing else is active. |
844 | .Sp |
865 | .Sp |
845 | .Vb 4 |
866 | .Vb 4 |
846 | \& struct ev_signal exitsig; |
867 | \& ev_signal exitsig; |
847 | \& ev_signal_init (&exitsig, sig_cb, SIGINT); |
868 | \& ev_signal_init (&exitsig, sig_cb, SIGINT); |
848 | \& ev_signal_start (loop, &exitsig); |
869 | \& ev_signal_start (loop, &exitsig); |
849 | \& evf_unref (loop); |
870 | \& evf_unref (loop); |
850 | .Ve |
871 | .Ve |
851 | .Sp |
872 | .Sp |
… | |
… | |
902 | reduce iterations/wake\-ups is to use \f(CW\*(C`ev_periodic\*(C'\fR watchers and make sure |
923 | reduce iterations/wake\-ups is to use \f(CW\*(C`ev_periodic\*(C'\fR watchers and make sure |
903 | they fire on, say, one-second boundaries only. |
924 | they fire on, say, one-second boundaries only. |
904 | .IP "ev_loop_verify (loop)" 4 |
925 | .IP "ev_loop_verify (loop)" 4 |
905 | .IX Item "ev_loop_verify (loop)" |
926 | .IX Item "ev_loop_verify (loop)" |
906 | This function only does something when \f(CW\*(C`EV_VERIFY\*(C'\fR support has been |
927 | This function only does something when \f(CW\*(C`EV_VERIFY\*(C'\fR support has been |
907 | compiled in. which is the default for non-minimal builds. It tries to go |
928 | compiled in, which is the default for non-minimal builds. It tries to go |
908 | through all internal structures and checks them for validity. If anything |
929 | through all internal structures and checks them for validity. If anything |
909 | is found to be inconsistent, it will print an error message to standard |
930 | is found to be inconsistent, it will print an error message to standard |
910 | error and call \f(CW\*(C`abort ()\*(C'\fR. |
931 | error and call \f(CW\*(C`abort ()\*(C'\fR. |
911 | .Sp |
932 | .Sp |
912 | This can be used to catch bugs inside libev itself: under normal |
933 | This can be used to catch bugs inside libev itself: under normal |
913 | circumstances, this function will never abort as of course libev keeps its |
934 | circumstances, this function will never abort as of course libev keeps its |
914 | data structures consistent. |
935 | data structures consistent. |
915 | .SH "ANATOMY OF A WATCHER" |
936 | .SH "ANATOMY OF A WATCHER" |
916 | .IX Header "ANATOMY OF A WATCHER" |
937 | .IX Header "ANATOMY OF A WATCHER" |
|
|
938 | In the following description, uppercase \f(CW\*(C`TYPE\*(C'\fR in names stands for the |
|
|
939 | watcher type, e.g. \f(CW\*(C`ev_TYPE_start\*(C'\fR can mean \f(CW\*(C`ev_timer_start\*(C'\fR for timer |
|
|
940 | watchers and \f(CW\*(C`ev_io_start\*(C'\fR for I/O watchers. |
|
|
941 | .PP |
917 | A watcher is a structure that you create and register to record your |
942 | A watcher is a structure that you create and register to record your |
918 | interest in some event. For instance, if you want to wait for \s-1STDIN\s0 to |
943 | interest in some event. For instance, if you want to wait for \s-1STDIN\s0 to |
919 | become readable, you would create an \f(CW\*(C`ev_io\*(C'\fR watcher for that: |
944 | become readable, you would create an \f(CW\*(C`ev_io\*(C'\fR watcher for that: |
920 | .PP |
945 | .PP |
921 | .Vb 5 |
946 | .Vb 5 |
922 | \& static void my_cb (struct ev_loop *loop, struct ev_io *w, int revents) |
947 | \& static void my_cb (struct ev_loop *loop, ev_io *w, int revents) |
923 | \& { |
948 | \& { |
924 | \& ev_io_stop (w); |
949 | \& ev_io_stop (w); |
925 | \& ev_unloop (loop, EVUNLOOP_ALL); |
950 | \& ev_unloop (loop, EVUNLOOP_ALL); |
926 | \& } |
951 | \& } |
927 | \& |
952 | \& |
928 | \& struct ev_loop *loop = ev_default_loop (0); |
953 | \& struct ev_loop *loop = ev_default_loop (0); |
|
|
954 | \& |
929 | \& struct ev_io stdin_watcher; |
955 | \& ev_io stdin_watcher; |
|
|
956 | \& |
930 | \& ev_init (&stdin_watcher, my_cb); |
957 | \& ev_init (&stdin_watcher, my_cb); |
931 | \& ev_io_set (&stdin_watcher, STDIN_FILENO, EV_READ); |
958 | \& ev_io_set (&stdin_watcher, STDIN_FILENO, EV_READ); |
932 | \& ev_io_start (loop, &stdin_watcher); |
959 | \& ev_io_start (loop, &stdin_watcher); |
|
|
960 | \& |
933 | \& ev_loop (loop, 0); |
961 | \& ev_loop (loop, 0); |
934 | .Ve |
962 | .Ve |
935 | .PP |
963 | .PP |
936 | As you can see, you are responsible for allocating the memory for your |
964 | As you can see, you are responsible for allocating the memory for your |
937 | watcher structures (and it is usually a bad idea to do this on the stack, |
965 | watcher structures (and it is \fIusually\fR a bad idea to do this on the |
938 | although this can sometimes be quite valid). |
966 | stack). |
|
|
967 | .PP |
|
|
968 | Each watcher has an associated watcher structure (called \f(CW\*(C`struct ev_TYPE\*(C'\fR |
|
|
969 | or simply \f(CW\*(C`ev_TYPE\*(C'\fR, as typedefs are provided for all watcher structs). |
939 | .PP |
970 | .PP |
940 | Each watcher structure must be initialised by a call to \f(CW\*(C`ev_init |
971 | Each 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 |
972 | (watcher *, callback)\*(C'\fR, which expects a callback to be provided. This |
942 | callback gets invoked each time the event occurs (or, in the case of I/O |
973 | callback gets invoked each time the event occurs (or, in the case of I/O |
943 | watchers, each time the event loop detects that the file descriptor given |
974 | watchers, each time the event loop detects that the file descriptor given |
944 | is readable and/or writable). |
975 | is readable and/or writable). |
945 | .PP |
976 | .PP |
946 | Each watcher type has its own \f(CW\*(C`ev_<type>_set (watcher *, ...)\*(C'\fR macro |
977 | Each watcher type further has its own \f(CW\*(C`ev_TYPE_set (watcher *, ...)\*(C'\fR |
947 | with arguments specific to this watcher type. There is also a macro |
978 | macro to configure it, with arguments specific to the watcher type. There |
948 | to combine initialisation and setting in one call: \f(CW\*(C`ev_<type>_init |
979 | is 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 |
980 | .PP |
951 | To make the watcher actually watch out for events, you have to start it |
981 | To make the watcher actually watch out for events, you have to start it |
952 | with a watcher-specific start function (\f(CW\*(C`ev_<type>_start (loop, watcher |
982 | with 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 |
983 | *)\*(C'\fR), and you can stop watching for events at any time by calling the |
954 | corresponding stop function (\f(CW\*(C`ev_<type>_stop (loop, watcher *)\*(C'\fR. |
984 | corresponding stop function (\f(CW\*(C`ev_TYPE_stop (loop, watcher *)\*(C'\fR. |
955 | .PP |
985 | .PP |
956 | As long as your watcher is active (has been started but not stopped) you |
986 | As long as your watcher is active (has been started but not stopped) you |
957 | must not touch the values stored in it. Most specifically you must never |
987 | must not touch the values stored in it. Most specifically you must never |
958 | reinitialise it or call its \f(CW\*(C`set\*(C'\fR macro. |
988 | reinitialise it or call its \f(CW\*(C`ev_TYPE_set\*(C'\fR macro. |
959 | .PP |
989 | .PP |
960 | Each and every callback receives the event loop pointer as first, the |
990 | Each and every callback receives the event loop pointer as first, the |
961 | registered watcher structure as second, and a bitset of received events as |
991 | registered watcher structure as second, and a bitset of received events as |
962 | third argument. |
992 | third argument. |
963 | .PP |
993 | .PP |
… | |
… | |
1030 | .el .IP "\f(CWEV_ERROR\fR" 4 |
1060 | .el .IP "\f(CWEV_ERROR\fR" 4 |
1031 | .IX Item "EV_ERROR" |
1061 | .IX Item "EV_ERROR" |
1032 | An unspecified error has occurred, the watcher has been stopped. This might |
1062 | An unspecified error has occurred, the watcher has been stopped. This might |
1033 | happen because the watcher could not be properly started because libev |
1063 | happen because the watcher could not be properly started because libev |
1034 | ran out of memory, a file descriptor was found to be closed or any other |
1064 | ran out of memory, a file descriptor was found to be closed or any other |
|
|
1065 | problem. Libev considers these application bugs. |
|
|
1066 | .Sp |
1035 | problem. You best act on it by reporting the problem and somehow coping |
1067 | You best act on it by reporting the problem and somehow coping with the |
1036 | with the watcher being stopped. |
1068 | watcher being stopped. Note that well-written programs should not receive |
|
|
1069 | an error ever, so when your watcher receives it, this usually indicates a |
|
|
1070 | bug in your program. |
1037 | .Sp |
1071 | .Sp |
1038 | Libev will usually signal a few \*(L"dummy\*(R" events together with an error, for |
1072 | Libev will usually signal a few \*(L"dummy\*(R" events together with an error, for |
1039 | example it might indicate that a fd is readable or writable, and if your |
1073 | example it might indicate that a fd is readable or writable, and if your |
1040 | callbacks is well-written it can just attempt the operation and cope with |
1074 | callbacks is well-written it can just attempt the operation and cope with |
1041 | the error from \fIread()\fR or \fIwrite()\fR. This will not work in multi-threaded |
1075 | the error from \fIread()\fR or \fIwrite()\fR. This will not work in multi-threaded |
1042 | programs, though, as the fd could already be closed and reused for another |
1076 | programs, though, as the fd could already be closed and reused for another |
1043 | thing, so beware. |
1077 | thing, so beware. |
1044 | .Sh "\s-1GENERIC\s0 \s-1WATCHER\s0 \s-1FUNCTIONS\s0" |
1078 | .Sh "\s-1GENERIC\s0 \s-1WATCHER\s0 \s-1FUNCTIONS\s0" |
1045 | .IX Subsection "GENERIC WATCHER FUNCTIONS" |
1079 | .IX Subsection "GENERIC WATCHER FUNCTIONS" |
1046 | In the following description, \f(CW\*(C`TYPE\*(C'\fR stands for the watcher type, |
|
|
1047 | e.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 |
1080 | .ie n .IP """ev_init"" (ev_TYPE *watcher, callback)" 4 |
1049 | .el .IP "\f(CWev_init\fR (ev_TYPE *watcher, callback)" 4 |
1081 | .el .IP "\f(CWev_init\fR (ev_TYPE *watcher, callback)" 4 |
1050 | .IX Item "ev_init (ev_TYPE *watcher, callback)" |
1082 | .IX Item "ev_init (ev_TYPE *watcher, callback)" |
1051 | This macro initialises the generic portion of a watcher. The contents |
1083 | This macro initialises the generic portion of a watcher. The contents |
1052 | of the watcher object can be arbitrary (so \f(CW\*(C`malloc\*(C'\fR will do). Only |
1084 | of the watcher object can be arbitrary (so \f(CW\*(C`malloc\*(C'\fR will do). Only |
… | |
… | |
1056 | which rolls both calls into one. |
1088 | which rolls both calls into one. |
1057 | .Sp |
1089 | .Sp |
1058 | You can reinitialise a watcher at any time as long as it has been stopped |
1090 | You 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. |
1091 | (or never started) and there are no pending events outstanding. |
1060 | .Sp |
1092 | .Sp |
1061 | The callback is always of type \f(CW\*(C`void (*)(ev_loop *loop, ev_TYPE *watcher, |
1093 | The callback is always of type \f(CW\*(C`void (*)(struct ev_loop *loop, ev_TYPE *watcher, |
1062 | int revents)\*(C'\fR. |
1094 | int revents)\*(C'\fR. |
1063 | .Sp |
1095 | .Sp |
1064 | Example: Initialise an \f(CW\*(C`ev_io\*(C'\fR watcher in two steps. |
1096 | Example: Initialise an \f(CW\*(C`ev_io\*(C'\fR watcher in two steps. |
1065 | .Sp |
1097 | .Sp |
1066 | .Vb 3 |
1098 | .Vb 3 |
… | |
… | |
1162 | The default priority used by watchers when no priority has been set is |
1194 | The default priority used by watchers when no priority has been set is |
1163 | always \f(CW0\fR, which is supposed to not be too high and not be too low :). |
1195 | always \f(CW0\fR, which is supposed to not be too high and not be too low :). |
1164 | .Sp |
1196 | .Sp |
1165 | Setting a priority outside the range of \f(CW\*(C`EV_MINPRI\*(C'\fR to \f(CW\*(C`EV_MAXPRI\*(C'\fR is |
1197 | Setting a priority outside the range of \f(CW\*(C`EV_MINPRI\*(C'\fR to \f(CW\*(C`EV_MAXPRI\*(C'\fR is |
1166 | fine, as long as you do not mind that the priority value you query might |
1198 | fine, as long as you do not mind that the priority value you query might |
1167 | or might not have been adjusted to be within valid range. |
1199 | or might not have been clamped to the valid range. |
1168 | .IP "ev_invoke (loop, ev_TYPE *watcher, int revents)" 4 |
1200 | .IP "ev_invoke (loop, ev_TYPE *watcher, int revents)" 4 |
1169 | .IX Item "ev_invoke (loop, ev_TYPE *watcher, int revents)" |
1201 | .IX Item "ev_invoke (loop, ev_TYPE *watcher, int revents)" |
1170 | Invoke the \f(CW\*(C`watcher\*(C'\fR with the given \f(CW\*(C`loop\*(C'\fR and \f(CW\*(C`revents\*(C'\fR. Neither |
1202 | Invoke 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 |
1203 | \&\f(CW\*(C`loop\*(C'\fR nor \f(CW\*(C`revents\*(C'\fR need to be valid as long as the watcher callback |
1172 | can deal with that fact, as both are simply passed through to the |
1204 | can deal with that fact, as both are simply passed through to the |
… | |
… | |
1189 | data: |
1221 | data: |
1190 | .PP |
1222 | .PP |
1191 | .Vb 7 |
1223 | .Vb 7 |
1192 | \& struct my_io |
1224 | \& struct my_io |
1193 | \& { |
1225 | \& { |
1194 | \& struct ev_io io; |
1226 | \& ev_io io; |
1195 | \& int otherfd; |
1227 | \& int otherfd; |
1196 | \& void *somedata; |
1228 | \& void *somedata; |
1197 | \& struct whatever *mostinteresting; |
1229 | \& struct whatever *mostinteresting; |
1198 | \& }; |
1230 | \& }; |
1199 | \& |
1231 | \& |
… | |
… | |
1204 | .PP |
1236 | .PP |
1205 | And since your callback will be called with a pointer to the watcher, you |
1237 | And since your callback will be called with a pointer to the watcher, you |
1206 | can cast it back to your own type: |
1238 | can cast it back to your own type: |
1207 | .PP |
1239 | .PP |
1208 | .Vb 5 |
1240 | .Vb 5 |
1209 | \& static void my_cb (struct ev_loop *loop, struct ev_io *w_, int revents) |
1241 | \& static void my_cb (struct ev_loop *loop, ev_io *w_, int revents) |
1210 | \& { |
1242 | \& { |
1211 | \& struct my_io *w = (struct my_io *)w_; |
1243 | \& struct my_io *w = (struct my_io *)w_; |
1212 | \& ... |
1244 | \& ... |
1213 | \& } |
1245 | \& } |
1214 | .Ve |
1246 | .Ve |
… | |
… | |
1236 | .PP |
1268 | .PP |
1237 | .Vb 1 |
1269 | .Vb 1 |
1238 | \& #include <stddef.h> |
1270 | \& #include <stddef.h> |
1239 | \& |
1271 | \& |
1240 | \& static void |
1272 | \& static void |
1241 | \& t1_cb (EV_P_ struct ev_timer *w, int revents) |
1273 | \& t1_cb (EV_P_ ev_timer *w, int revents) |
1242 | \& { |
1274 | \& { |
1243 | \& struct my_biggy big = (struct my_biggy * |
1275 | \& struct my_biggy big = (struct my_biggy * |
1244 | \& (((char *)w) \- offsetof (struct my_biggy, t1)); |
1276 | \& (((char *)w) \- offsetof (struct my_biggy, t1)); |
1245 | \& } |
1277 | \& } |
1246 | \& |
1278 | \& |
1247 | \& static void |
1279 | \& static void |
1248 | \& t2_cb (EV_P_ struct ev_timer *w, int revents) |
1280 | \& t2_cb (EV_P_ ev_timer *w, int revents) |
1249 | \& { |
1281 | \& { |
1250 | \& struct my_biggy big = (struct my_biggy * |
1282 | \& struct my_biggy big = (struct my_biggy * |
1251 | \& (((char *)w) \- offsetof (struct my_biggy, t2)); |
1283 | \& (((char *)w) \- offsetof (struct my_biggy, t2)); |
1252 | \& } |
1284 | \& } |
1253 | .Ve |
1285 | .Ve |
… | |
… | |
1387 | readable, but only once. Since it is likely line-buffered, you could |
1419 | readable, but only once. Since it is likely line-buffered, you could |
1388 | attempt to read a whole line in the callback. |
1420 | attempt to read a whole line in the callback. |
1389 | .PP |
1421 | .PP |
1390 | .Vb 6 |
1422 | .Vb 6 |
1391 | \& static void |
1423 | \& static void |
1392 | \& stdin_readable_cb (struct ev_loop *loop, struct ev_io *w, int revents) |
1424 | \& stdin_readable_cb (struct ev_loop *loop, ev_io *w, int revents) |
1393 | \& { |
1425 | \& { |
1394 | \& ev_io_stop (loop, w); |
1426 | \& ev_io_stop (loop, w); |
1395 | \& .. read from stdin here (or from w\->fd) and handle any I/O errors |
1427 | \& .. read from stdin here (or from w\->fd) and handle any I/O errors |
1396 | \& } |
1428 | \& } |
1397 | \& |
1429 | \& |
1398 | \& ... |
1430 | \& ... |
1399 | \& struct ev_loop *loop = ev_default_init (0); |
1431 | \& struct ev_loop *loop = ev_default_init (0); |
1400 | \& struct ev_io stdin_readable; |
1432 | \& ev_io stdin_readable; |
1401 | \& ev_io_init (&stdin_readable, stdin_readable_cb, STDIN_FILENO, EV_READ); |
1433 | \& ev_io_init (&stdin_readable, stdin_readable_cb, STDIN_FILENO, EV_READ); |
1402 | \& ev_io_start (loop, &stdin_readable); |
1434 | \& ev_io_start (loop, &stdin_readable); |
1403 | \& ev_loop (loop, 0); |
1435 | \& ev_loop (loop, 0); |
1404 | .Ve |
1436 | .Ve |
1405 | .ie n .Sh """ev_timer"" \- relative and optionally repeating timeouts" |
1437 | .ie n .Sh """ev_timer"" \- relative and optionally repeating timeouts" |
… | |
… | |
1415 | monotonic clock option helps a lot here). |
1447 | monotonic clock option helps a lot here). |
1416 | .PP |
1448 | .PP |
1417 | The callback is guaranteed to be invoked only \fIafter\fR its timeout has |
1449 | The callback is guaranteed to be invoked only \fIafter\fR its timeout has |
1418 | passed, but if multiple timers become ready during the same loop iteration |
1450 | passed, but if multiple timers become ready during the same loop iteration |
1419 | then order of execution is undefined. |
1451 | then order of execution is undefined. |
|
|
1452 | .PP |
|
|
1453 | \fIBe smart about timeouts\fR |
|
|
1454 | .IX Subsection "Be smart about timeouts" |
|
|
1455 | .PP |
|
|
1456 | Many real-world problems involve some kind of timeout, usually for error |
|
|
1457 | recovery. A typical example is an \s-1HTTP\s0 request \- if the other side hangs, |
|
|
1458 | you want to raise some error after a while. |
|
|
1459 | .PP |
|
|
1460 | What follows are some ways to handle this problem, from obvious and |
|
|
1461 | inefficient to smart and efficient. |
|
|
1462 | .PP |
|
|
1463 | In the following, a 60 second activity timeout is assumed \- a timeout that |
|
|
1464 | gets reset to 60 seconds each time there is activity (e.g. each time some |
|
|
1465 | data or other life sign was received). |
|
|
1466 | .IP "1. Use a timer and stop, reinitialise and start it on activity." 4 |
|
|
1467 | .IX Item "1. Use a timer and stop, reinitialise and start it on activity." |
|
|
1468 | This is the most obvious, but not the most simple way: In the beginning, |
|
|
1469 | start the watcher: |
|
|
1470 | .Sp |
|
|
1471 | .Vb 2 |
|
|
1472 | \& ev_timer_init (timer, callback, 60., 0.); |
|
|
1473 | \& ev_timer_start (loop, timer); |
|
|
1474 | .Ve |
|
|
1475 | .Sp |
|
|
1476 | Then, each time there is some activity, \f(CW\*(C`ev_timer_stop\*(C'\fR it, initialise it |
|
|
1477 | and start it again: |
|
|
1478 | .Sp |
|
|
1479 | .Vb 3 |
|
|
1480 | \& ev_timer_stop (loop, timer); |
|
|
1481 | \& ev_timer_set (timer, 60., 0.); |
|
|
1482 | \& ev_timer_start (loop, timer); |
|
|
1483 | .Ve |
|
|
1484 | .Sp |
|
|
1485 | This is relatively simple to implement, but means that each time there is |
|
|
1486 | some activity, libev will first have to remove the timer from its internal |
|
|
1487 | data structure and then add it again. Libev tries to be fast, but it's |
|
|
1488 | still not a constant-time operation. |
|
|
1489 | .ie n .IP "2. Use a timer and re-start it with ""ev_timer_again"" inactivity." 4 |
|
|
1490 | .el .IP "2. Use a timer and re-start it with \f(CWev_timer_again\fR inactivity." 4 |
|
|
1491 | .IX Item "2. Use a timer and re-start it with ev_timer_again inactivity." |
|
|
1492 | This is the easiest way, and involves using \f(CW\*(C`ev_timer_again\*(C'\fR instead of |
|
|
1493 | \&\f(CW\*(C`ev_timer_start\*(C'\fR. |
|
|
1494 | .Sp |
|
|
1495 | To implement this, configure an \f(CW\*(C`ev_timer\*(C'\fR with a \f(CW\*(C`repeat\*(C'\fR value |
|
|
1496 | of \f(CW60\fR and then call \f(CW\*(C`ev_timer_again\*(C'\fR at start and each time you |
|
|
1497 | successfully read or write some data. If you go into an idle state where |
|
|
1498 | you do not expect data to travel on the socket, you can \f(CW\*(C`ev_timer_stop\*(C'\fR |
|
|
1499 | the timer, and \f(CW\*(C`ev_timer_again\*(C'\fR will automatically restart it if need be. |
|
|
1500 | .Sp |
|
|
1501 | That means you can ignore both the \f(CW\*(C`ev_timer_start\*(C'\fR function and the |
|
|
1502 | \&\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 |
|
|
1503 | member and \f(CW\*(C`ev_timer_again\*(C'\fR. |
|
|
1504 | .Sp |
|
|
1505 | At start: |
|
|
1506 | .Sp |
|
|
1507 | .Vb 3 |
|
|
1508 | \& ev_timer_init (timer, callback); |
|
|
1509 | \& timer\->repeat = 60.; |
|
|
1510 | \& ev_timer_again (loop, timer); |
|
|
1511 | .Ve |
|
|
1512 | .Sp |
|
|
1513 | Each time there is some activity: |
|
|
1514 | .Sp |
|
|
1515 | .Vb 1 |
|
|
1516 | \& ev_timer_again (loop, timer); |
|
|
1517 | .Ve |
|
|
1518 | .Sp |
|
|
1519 | It is even possible to change the time-out on the fly, regardless of |
|
|
1520 | whether the watcher is active or not: |
|
|
1521 | .Sp |
|
|
1522 | .Vb 2 |
|
|
1523 | \& timer\->repeat = 30.; |
|
|
1524 | \& ev_timer_again (loop, timer); |
|
|
1525 | .Ve |
|
|
1526 | .Sp |
|
|
1527 | This is slightly more efficient then stopping/starting the timer each time |
|
|
1528 | you want to modify its timeout value, as libev does not have to completely |
|
|
1529 | remove and re-insert the timer from/into its internal data structure. |
|
|
1530 | .Sp |
|
|
1531 | It is, however, even simpler than the \*(L"obvious\*(R" way to do it. |
|
|
1532 | .IP "3. Let the timer time out, but then re-arm it as required." 4 |
|
|
1533 | .IX Item "3. Let the timer time out, but then re-arm it as required." |
|
|
1534 | This method is more tricky, but usually most efficient: Most timeouts are |
|
|
1535 | relatively long compared to the intervals between other activity \- in |
|
|
1536 | our example, within 60 seconds, there are usually many I/O events with |
|
|
1537 | associated activity resets. |
|
|
1538 | .Sp |
|
|
1539 | In this case, it would be more efficient to leave the \f(CW\*(C`ev_timer\*(C'\fR alone, |
|
|
1540 | but remember the time of last activity, and check for a real timeout only |
|
|
1541 | within the callback: |
|
|
1542 | .Sp |
|
|
1543 | .Vb 1 |
|
|
1544 | \& ev_tstamp last_activity; // time of last activity |
|
|
1545 | \& |
|
|
1546 | \& static void |
|
|
1547 | \& callback (EV_P_ ev_timer *w, int revents) |
|
|
1548 | \& { |
|
|
1549 | \& ev_tstamp now = ev_now (EV_A); |
|
|
1550 | \& ev_tstamp timeout = last_activity + 60.; |
|
|
1551 | \& |
|
|
1552 | \& // if last_activity + 60. is older than now, we did time out |
|
|
1553 | \& if (timeout < now) |
|
|
1554 | \& { |
|
|
1555 | \& // timeout occured, take action |
|
|
1556 | \& } |
|
|
1557 | \& else |
|
|
1558 | \& { |
|
|
1559 | \& // callback was invoked, but there was some activity, re\-arm |
|
|
1560 | \& // the watcher to fire in last_activity + 60, which is |
|
|
1561 | \& // guaranteed to be in the future, so "again" is positive: |
|
|
1562 | \& w\->again = timeout \- now; |
|
|
1563 | \& ev_timer_again (EV_A_ w); |
|
|
1564 | \& } |
|
|
1565 | \& } |
|
|
1566 | .Ve |
|
|
1567 | .Sp |
|
|
1568 | To summarise the callback: first calculate the real timeout (defined |
|
|
1569 | as \*(L"60 seconds after the last activity\*(R"), then check if that time has |
|
|
1570 | been reached, which means something \fIdid\fR, in fact, time out. Otherwise |
|
|
1571 | the callback was invoked too early (\f(CW\*(C`timeout\*(C'\fR is in the future), so |
|
|
1572 | re-schedule the timer to fire at that future time, to see if maybe we have |
|
|
1573 | a timeout then. |
|
|
1574 | .Sp |
|
|
1575 | Note how \f(CW\*(C`ev_timer_again\*(C'\fR is used, taking advantage of the |
|
|
1576 | \&\f(CW\*(C`ev_timer_again\*(C'\fR optimisation when the timer is already running. |
|
|
1577 | .Sp |
|
|
1578 | This scheme causes more callback invocations (about one every 60 seconds |
|
|
1579 | minus half the average time between activity), but virtually no calls to |
|
|
1580 | libev to change the timeout. |
|
|
1581 | .Sp |
|
|
1582 | To start the timer, simply initialise the watcher and set \f(CW\*(C`last_activity\*(C'\fR |
|
|
1583 | to the current time (meaning we just have some activity :), then call the |
|
|
1584 | callback, which will \*(L"do the right thing\*(R" and start the timer: |
|
|
1585 | .Sp |
|
|
1586 | .Vb 3 |
|
|
1587 | \& ev_timer_init (timer, callback); |
|
|
1588 | \& last_activity = ev_now (loop); |
|
|
1589 | \& callback (loop, timer, EV_TIMEOUT); |
|
|
1590 | .Ve |
|
|
1591 | .Sp |
|
|
1592 | And when there is some activity, simply store the current time in |
|
|
1593 | \&\f(CW\*(C`last_activity\*(C'\fR, no libev calls at all: |
|
|
1594 | .Sp |
|
|
1595 | .Vb 1 |
|
|
1596 | \& last_actiivty = ev_now (loop); |
|
|
1597 | .Ve |
|
|
1598 | .Sp |
|
|
1599 | This technique is slightly more complex, but in most cases where the |
|
|
1600 | time-out is unlikely to be triggered, much more efficient. |
|
|
1601 | .Sp |
|
|
1602 | Changing the timeout is trivial as well (if it isn't hard-coded in the |
|
|
1603 | callback :) \- just change the timeout and invoke the callback, which will |
|
|
1604 | fix things for you. |
|
|
1605 | .IP "4. Wee, just use a double-linked list for your timeouts." 4 |
|
|
1606 | .IX Item "4. Wee, just use a double-linked list for your timeouts." |
|
|
1607 | If there is not one request, but many thousands (millions...), all |
|
|
1608 | employing some kind of timeout with the same timeout value, then one can |
|
|
1609 | do even better: |
|
|
1610 | .Sp |
|
|
1611 | When starting the timeout, calculate the timeout value and put the timeout |
|
|
1612 | at the \fIend\fR of the list. |
|
|
1613 | .Sp |
|
|
1614 | Then use an \f(CW\*(C`ev_timer\*(C'\fR to fire when the timeout at the \fIbeginning\fR of |
|
|
1615 | the list is expected to fire (for example, using the technique #3). |
|
|
1616 | .Sp |
|
|
1617 | When there is some activity, remove the timer from the list, recalculate |
|
|
1618 | the timeout, append it to the end of the list again, and make sure to |
|
|
1619 | update the \f(CW\*(C`ev_timer\*(C'\fR if it was taken from the beginning of the list. |
|
|
1620 | .Sp |
|
|
1621 | This way, one can manage an unlimited number of timeouts in O(1) time for |
|
|
1622 | starting, stopping and updating the timers, at the expense of a major |
|
|
1623 | complication, and having to use a constant timeout. The constant timeout |
|
|
1624 | ensures that the list stays sorted. |
|
|
1625 | .PP |
|
|
1626 | So which method the best? |
|
|
1627 | .PP |
|
|
1628 | Method #2 is a simple no-brain-required solution that is adequate in most |
|
|
1629 | situations. Method #3 requires a bit more thinking, but handles many cases |
|
|
1630 | better, and isn't very complicated either. In most case, choosing either |
|
|
1631 | one is fine, with #3 being better in typical situations. |
|
|
1632 | .PP |
|
|
1633 | Method #1 is almost always a bad idea, and buys you nothing. Method #4 is |
|
|
1634 | rather complicated, but extremely efficient, something that really pays |
|
|
1635 | off after the first million or so of active timers, i.e. it's usually |
|
|
1636 | overkill :) |
1420 | .PP |
1637 | .PP |
1421 | \fIThe special problem of time updates\fR |
1638 | \fIThe special problem of time updates\fR |
1422 | .IX Subsection "The special problem of time updates" |
1639 | .IX Subsection "The special problem of time updates" |
1423 | .PP |
1640 | .PP |
1424 | Establishing the current time is a costly operation (it usually takes at |
1641 | Establishing the current time is a costly operation (it usually takes at |
… | |
… | |
1470 | If the timer is started but non-repeating, stop it (as if it timed out). |
1687 | If the timer is started but non-repeating, stop it (as if it timed out). |
1471 | .Sp |
1688 | .Sp |
1472 | If the timer is repeating, either start it if necessary (with the |
1689 | If 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. |
1690 | \&\f(CW\*(C`repeat\*(C'\fR value), or reset the running timer to the \f(CW\*(C`repeat\*(C'\fR value. |
1474 | .Sp |
1691 | .Sp |
1475 | This sounds a bit complicated, but here is a useful and typical |
1692 | This sounds a bit complicated, see \*(L"Be smart about timeouts\*(R", above, for a |
1476 | example: Imagine you have a \s-1TCP\s0 connection and you want a so-called idle |
1693 | usage example. |
1477 | timeout, that is, you want to be called when there have been, say, 60 |
|
|
1478 | seconds of inactivity on the socket. The easiest way to do this is to |
|
|
1479 | configure 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 |
|
|
1481 | you go into an idle state where you do not expect data to travel on the |
|
|
1482 | socket, you can \f(CW\*(C`ev_timer_stop\*(C'\fR the timer, and \f(CW\*(C`ev_timer_again\*(C'\fR will |
|
|
1483 | automatically restart it if need be. |
|
|
1484 | .Sp |
|
|
1485 | That means you can ignore the \f(CW\*(C`after\*(C'\fR value and \f(CW\*(C`ev_timer_start\*(C'\fR |
|
|
1486 | altogether 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 |
|
|
1499 | This is more slightly efficient then stopping/starting the timer each time |
|
|
1500 | you want to modify its timeout value. |
|
|
1501 | .Sp |
|
|
1502 | Note, however, that it is often even more efficient to remember the |
|
|
1503 | time of the last activity and let the timer time-out naturally. In the |
|
|
1504 | callback, you then check whether the time-out is real, or, if there was |
|
|
1505 | some activity, you reschedule the watcher to time-out in \*(L"last_activity + |
|
|
1506 | timeout \- ev_now ()\*(R" seconds. |
|
|
1507 | .IP "ev_tstamp repeat [read\-write]" 4 |
1694 | .IP "ev_tstamp repeat [read\-write]" 4 |
1508 | .IX Item "ev_tstamp repeat [read-write]" |
1695 | .IX Item "ev_tstamp repeat [read-write]" |
1509 | The current \f(CW\*(C`repeat\*(C'\fR value. Will be used each time the watcher times out |
1696 | The current \f(CW\*(C`repeat\*(C'\fR value. Will be used each time the watcher times out |
1510 | or \f(CW\*(C`ev_timer_again\*(C'\fR is called, and determines the next timeout (if any), |
1697 | or \f(CW\*(C`ev_timer_again\*(C'\fR is called, and determines the next timeout (if any), |
1511 | which is also when any modifications are taken into account. |
1698 | which is also when any modifications are taken into account. |
… | |
… | |
1515 | .PP |
1702 | .PP |
1516 | Example: Create a timer that fires after 60 seconds. |
1703 | Example: Create a timer that fires after 60 seconds. |
1517 | .PP |
1704 | .PP |
1518 | .Vb 5 |
1705 | .Vb 5 |
1519 | \& static void |
1706 | \& static void |
1520 | \& one_minute_cb (struct ev_loop *loop, struct ev_timer *w, int revents) |
1707 | \& one_minute_cb (struct ev_loop *loop, ev_timer *w, int revents) |
1521 | \& { |
1708 | \& { |
1522 | \& .. one minute over, w is actually stopped right here |
1709 | \& .. one minute over, w is actually stopped right here |
1523 | \& } |
1710 | \& } |
1524 | \& |
1711 | \& |
1525 | \& struct ev_timer mytimer; |
1712 | \& ev_timer mytimer; |
1526 | \& ev_timer_init (&mytimer, one_minute_cb, 60., 0.); |
1713 | \& ev_timer_init (&mytimer, one_minute_cb, 60., 0.); |
1527 | \& ev_timer_start (loop, &mytimer); |
1714 | \& ev_timer_start (loop, &mytimer); |
1528 | .Ve |
1715 | .Ve |
1529 | .PP |
1716 | .PP |
1530 | Example: Create a timeout timer that times out after 10 seconds of |
1717 | Example: Create a timeout timer that times out after 10 seconds of |
1531 | inactivity. |
1718 | inactivity. |
1532 | .PP |
1719 | .PP |
1533 | .Vb 5 |
1720 | .Vb 5 |
1534 | \& static void |
1721 | \& static void |
1535 | \& timeout_cb (struct ev_loop *loop, struct ev_timer *w, int revents) |
1722 | \& timeout_cb (struct ev_loop *loop, ev_timer *w, int revents) |
1536 | \& { |
1723 | \& { |
1537 | \& .. ten seconds without any activity |
1724 | \& .. ten seconds without any activity |
1538 | \& } |
1725 | \& } |
1539 | \& |
1726 | \& |
1540 | \& struct ev_timer mytimer; |
1727 | \& ev_timer mytimer; |
1541 | \& ev_timer_init (&mytimer, timeout_cb, 0., 10.); /* note, only repeat used */ |
1728 | \& ev_timer_init (&mytimer, timeout_cb, 0., 10.); /* note, only repeat used */ |
1542 | \& ev_timer_again (&mytimer); /* start timer */ |
1729 | \& ev_timer_again (&mytimer); /* start timer */ |
1543 | \& ev_loop (loop, 0); |
1730 | \& ev_loop (loop, 0); |
1544 | \& |
1731 | \& |
1545 | \& // and in some piece of code that gets executed on any "activity": |
1732 | \& // and in some piece of code that gets executed on any "activity": |
… | |
… | |
1632 | .Sp |
1819 | .Sp |
1633 | If you need to stop it, return \f(CW\*(C`now + 1e30\*(C'\fR (or so, fudge fudge) and stop |
1820 | If you need to stop it, return \f(CW\*(C`now + 1e30\*(C'\fR (or so, fudge fudge) and stop |
1634 | it afterwards (e.g. by starting an \f(CW\*(C`ev_prepare\*(C'\fR watcher, which is the |
1821 | it afterwards (e.g. by starting an \f(CW\*(C`ev_prepare\*(C'\fR watcher, which is the |
1635 | only event loop modification you are allowed to do). |
1822 | only event loop modification you are allowed to do). |
1636 | .Sp |
1823 | .Sp |
1637 | The callback prototype is \f(CW\*(C`ev_tstamp (*reschedule_cb)(struct ev_periodic |
1824 | The callback prototype is \f(CW\*(C`ev_tstamp (*reschedule_cb)(ev_periodic |
1638 | *w, ev_tstamp now)\*(C'\fR, e.g.: |
1825 | *w, ev_tstamp now)\*(C'\fR, e.g.: |
1639 | .Sp |
1826 | .Sp |
1640 | .Vb 4 |
1827 | .Vb 5 |
|
|
1828 | \& static ev_tstamp |
1641 | \& static ev_tstamp my_rescheduler (struct ev_periodic *w, ev_tstamp now) |
1829 | \& my_rescheduler (ev_periodic *w, ev_tstamp now) |
1642 | \& { |
1830 | \& { |
1643 | \& return now + 60.; |
1831 | \& return now + 60.; |
1644 | \& } |
1832 | \& } |
1645 | .Ve |
1833 | .Ve |
1646 | .Sp |
1834 | .Sp |
… | |
… | |
1680 | .IP "ev_tstamp interval [read\-write]" 4 |
1868 | .IP "ev_tstamp interval [read\-write]" 4 |
1681 | .IX Item "ev_tstamp interval [read-write]" |
1869 | .IX Item "ev_tstamp interval [read-write]" |
1682 | The current interval value. Can be modified any time, but changes only |
1870 | The current interval value. Can be modified any time, but changes only |
1683 | take effect when the periodic timer fires or \f(CW\*(C`ev_periodic_again\*(C'\fR is being |
1871 | take effect when the periodic timer fires or \f(CW\*(C`ev_periodic_again\*(C'\fR is being |
1684 | called. |
1872 | called. |
1685 | .IP "ev_tstamp (*reschedule_cb)(struct ev_periodic *w, ev_tstamp now) [read\-write]" 4 |
1873 | .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]" |
1874 | .IX Item "ev_tstamp (*reschedule_cb)(ev_periodic *w, ev_tstamp now) [read-write]" |
1687 | The current reschedule callback, or \f(CW0\fR, if this functionality is |
1875 | The current reschedule callback, or \f(CW0\fR, if this functionality is |
1688 | switched off. Can be changed any time, but changes only take effect when |
1876 | switched off. Can be changed any time, but changes only take effect when |
1689 | the periodic timer fires or \f(CW\*(C`ev_periodic_again\*(C'\fR is being called. |
1877 | the periodic timer fires or \f(CW\*(C`ev_periodic_again\*(C'\fR is being called. |
1690 | .PP |
1878 | .PP |
1691 | \fIExamples\fR |
1879 | \fIExamples\fR |
… | |
… | |
1695 | system time is divisible by 3600. The callback invocation times have |
1883 | system time is divisible by 3600. The callback invocation times have |
1696 | potentially a lot of jitter, but good long-term stability. |
1884 | potentially a lot of jitter, but good long-term stability. |
1697 | .PP |
1885 | .PP |
1698 | .Vb 5 |
1886 | .Vb 5 |
1699 | \& static void |
1887 | \& static void |
1700 | \& clock_cb (struct ev_loop *loop, struct ev_io *w, int revents) |
1888 | \& clock_cb (struct ev_loop *loop, ev_io *w, int revents) |
1701 | \& { |
1889 | \& { |
1702 | \& ... its now a full hour (UTC, or TAI or whatever your clock follows) |
1890 | \& ... its now a full hour (UTC, or TAI or whatever your clock follows) |
1703 | \& } |
1891 | \& } |
1704 | \& |
1892 | \& |
1705 | \& struct ev_periodic hourly_tick; |
1893 | \& ev_periodic hourly_tick; |
1706 | \& ev_periodic_init (&hourly_tick, clock_cb, 0., 3600., 0); |
1894 | \& ev_periodic_init (&hourly_tick, clock_cb, 0., 3600., 0); |
1707 | \& ev_periodic_start (loop, &hourly_tick); |
1895 | \& ev_periodic_start (loop, &hourly_tick); |
1708 | .Ve |
1896 | .Ve |
1709 | .PP |
1897 | .PP |
1710 | Example: The same as above, but use a reschedule callback to do it: |
1898 | Example: The same as above, but use a reschedule callback to do it: |
1711 | .PP |
1899 | .PP |
1712 | .Vb 1 |
1900 | .Vb 1 |
1713 | \& #include <math.h> |
1901 | \& #include <math.h> |
1714 | \& |
1902 | \& |
1715 | \& static ev_tstamp |
1903 | \& static ev_tstamp |
1716 | \& my_scheduler_cb (struct ev_periodic *w, ev_tstamp now) |
1904 | \& my_scheduler_cb (ev_periodic *w, ev_tstamp now) |
1717 | \& { |
1905 | \& { |
1718 | \& return now + (3600. \- fmod (now, 3600.)); |
1906 | \& return now + (3600. \- fmod (now, 3600.)); |
1719 | \& } |
1907 | \& } |
1720 | \& |
1908 | \& |
1721 | \& ev_periodic_init (&hourly_tick, clock_cb, 0., 0., my_scheduler_cb); |
1909 | \& ev_periodic_init (&hourly_tick, clock_cb, 0., 0., my_scheduler_cb); |
1722 | .Ve |
1910 | .Ve |
1723 | .PP |
1911 | .PP |
1724 | Example: Call a callback every hour, starting now: |
1912 | Example: Call a callback every hour, starting now: |
1725 | .PP |
1913 | .PP |
1726 | .Vb 4 |
1914 | .Vb 4 |
1727 | \& struct ev_periodic hourly_tick; |
1915 | \& ev_periodic hourly_tick; |
1728 | \& ev_periodic_init (&hourly_tick, clock_cb, |
1916 | \& ev_periodic_init (&hourly_tick, clock_cb, |
1729 | \& fmod (ev_now (loop), 3600.), 3600., 0); |
1917 | \& fmod (ev_now (loop), 3600.), 3600., 0); |
1730 | \& ev_periodic_start (loop, &hourly_tick); |
1918 | \& ev_periodic_start (loop, &hourly_tick); |
1731 | .Ve |
1919 | .Ve |
1732 | .ie n .Sh """ev_signal"" \- signal me when a signal gets signalled!" |
1920 | .ie n .Sh """ev_signal"" \- signal me when a signal gets signalled!" |
… | |
… | |
1773 | .PP |
1961 | .PP |
1774 | Example: Try to exit cleanly on \s-1SIGINT\s0. |
1962 | Example: Try to exit cleanly on \s-1SIGINT\s0. |
1775 | .PP |
1963 | .PP |
1776 | .Vb 5 |
1964 | .Vb 5 |
1777 | \& static void |
1965 | \& static void |
1778 | \& sigint_cb (struct ev_loop *loop, struct ev_signal *w, int revents) |
1966 | \& sigint_cb (struct ev_loop *loop, ev_signal *w, int revents) |
1779 | \& { |
1967 | \& { |
1780 | \& ev_unloop (loop, EVUNLOOP_ALL); |
1968 | \& ev_unloop (loop, EVUNLOOP_ALL); |
1781 | \& } |
1969 | \& } |
1782 | \& |
1970 | \& |
1783 | \& struct ev_signal signal_watcher; |
1971 | \& ev_signal signal_watcher; |
1784 | \& ev_signal_init (&signal_watcher, sigint_cb, SIGINT); |
1972 | \& ev_signal_init (&signal_watcher, sigint_cb, SIGINT); |
1785 | \& ev_signal_start (loop, &signal_watcher); |
1973 | \& ev_signal_start (loop, &signal_watcher); |
1786 | .Ve |
1974 | .Ve |
1787 | .ie n .Sh """ev_child"" \- watch out for process status changes" |
1975 | .ie n .Sh """ev_child"" \- watch out for process status changes" |
1788 | .el .Sh "\f(CWev_child\fP \- watch out for process status changes" |
1976 | .el .Sh "\f(CWev_child\fP \- watch out for process status changes" |
… | |
… | |
1863 | .PP |
2051 | .PP |
1864 | .Vb 1 |
2052 | .Vb 1 |
1865 | \& ev_child cw; |
2053 | \& ev_child cw; |
1866 | \& |
2054 | \& |
1867 | \& static void |
2055 | \& static void |
1868 | \& child_cb (EV_P_ struct ev_child *w, int revents) |
2056 | \& child_cb (EV_P_ ev_child *w, int revents) |
1869 | \& { |
2057 | \& { |
1870 | \& ev_child_stop (EV_A_ w); |
2058 | \& ev_child_stop (EV_A_ w); |
1871 | \& printf ("process %d exited with status %x\en", w\->rpid, w\->rstatus); |
2059 | \& printf ("process %d exited with status %x\en", w\->rpid, w\->rstatus); |
1872 | \& } |
2060 | \& } |
1873 | \& |
2061 | \& |
… | |
… | |
1888 | .Ve |
2076 | .Ve |
1889 | .ie n .Sh """ev_stat"" \- did the file attributes just change?" |
2077 | .ie n .Sh """ev_stat"" \- did the file attributes just change?" |
1890 | .el .Sh "\f(CWev_stat\fP \- did the file attributes just change?" |
2078 | .el .Sh "\f(CWev_stat\fP \- did the file attributes just change?" |
1891 | .IX Subsection "ev_stat - did the file attributes just change?" |
2079 | .IX Subsection "ev_stat - did the file attributes just change?" |
1892 | This watches a file system path for attribute changes. That is, it calls |
2080 | This 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 |
2081 | \&\f(CW\*(C`stat\*(C'\fR on that path in regular intervals (or when the \s-1OS\s0 says it changed) |
1894 | compared to the last time, invoking the callback if it did. |
2082 | and sees if it changed compared to the last time, invoking the callback if |
|
|
2083 | it did. |
1895 | .PP |
2084 | .PP |
1896 | The path does not need to exist: changing from \*(L"path exists\*(R" to \*(L"path does |
2085 | The path does not need to exist: changing from \*(L"path exists\*(R" to \*(L"path does |
1897 | not exist\*(R" is a status change like any other. The condition \*(L"path does |
2086 | not exist\*(R" is a status change like any other. The condition \*(L"path does |
1898 | not exist\*(R" is signified by the \f(CW\*(C`st_nlink\*(C'\fR field being zero (which is |
2087 | not exist\*(R" is signified by the \f(CW\*(C`st_nlink\*(C'\fR field being zero (which is |
1899 | otherwise always forced to be at least one) and all the other fields of |
2088 | otherwise always forced to be at least one) and all the other fields of |
1900 | the stat buffer having unspecified contents. |
2089 | the stat buffer having unspecified contents. |
1901 | .PP |
2090 | .PP |
1902 | The path \fIshould\fR be absolute and \fImust not\fR end in a slash. If it is |
2091 | The path \fImust not\fR end in a slash or contain special components such as |
|
|
2092 | \&\f(CW\*(C`.\*(C'\fR or \f(CW\*(C`..\*(C'\fR. The path \fIshould\fR be absolute: If it is relative and |
1903 | relative and your working directory changes, the behaviour is undefined. |
2093 | your working directory changes, then the behaviour is undefined. |
1904 | .PP |
2094 | .PP |
1905 | Since there is no standard kernel interface to do this, the portable |
2095 | Since there is no portable change notification interface available, the |
1906 | implementation simply calls \f(CW\*(C`stat (2)\*(C'\fR regularly on the path to see if |
2096 | portable implementation simply calls \f(CWstat(2)\fR regularly on the path |
1907 | it changed somehow. You can specify a recommended polling interval for |
2097 | to see if it changed somehow. You can specify a recommended polling |
1908 | this case. If you specify a polling interval of \f(CW0\fR (highly recommended!) |
2098 | interval for this case. If you specify a polling interval of \f(CW0\fR (highly |
1909 | then a \fIsuitable, unspecified default\fR value will be used (which |
2099 | recommended!) then a \fIsuitable, unspecified default\fR value will be used |
1910 | you can expect to be around five seconds, although this might change |
2100 | (which you can expect to be around five seconds, although this might |
1911 | dynamically). Libev will also impose a minimum interval which is currently |
2101 | change dynamically). Libev will also impose a minimum interval which is |
1912 | around \f(CW0.1\fR, but thats usually overkill. |
2102 | currently around \f(CW0.1\fR, but that's usually overkill. |
1913 | .PP |
2103 | .PP |
1914 | This watcher type is not meant for massive numbers of stat watchers, |
2104 | This watcher type is not meant for massive numbers of stat watchers, |
1915 | as even with OS-supported change notifications, this can be |
2105 | as even with OS-supported change notifications, this can be |
1916 | resource-intensive. |
2106 | resource-intensive. |
1917 | .PP |
2107 | .PP |
… | |
… | |
1928 | support disabled by default, you get the 32 bit version of the stat |
2118 | support disabled by default, you get the 32 bit version of the stat |
1929 | structure. When using the library from programs that change the \s-1ABI\s0 to |
2119 | structure. When using the library from programs that change the \s-1ABI\s0 to |
1930 | use 64 bit file offsets the programs will fail. In that case you have to |
2120 | use 64 bit file offsets the programs will fail. In that case you have to |
1931 | compile libev with the same flags to get binary compatibility. This is |
2121 | compile libev with the same flags to get binary compatibility. This is |
1932 | obviously the case with any flags that change the \s-1ABI\s0, but the problem is |
2122 | obviously the case with any flags that change the \s-1ABI\s0, but the problem is |
1933 | most noticeably disabled with ev_stat and large file support. |
2123 | most noticeably displayed with ev_stat and large file support. |
1934 | .PP |
2124 | .PP |
1935 | The solution for this is to lobby your distribution maker to make large |
2125 | The solution for this is to lobby your distribution maker to make large |
1936 | file interfaces available by default (as e.g. FreeBSD does) and not |
2126 | file interfaces available by default (as e.g. FreeBSD does) and not |
1937 | optional. Libev cannot simply switch on large file support because it has |
2127 | optional. Libev cannot simply switch on large file support because it has |
1938 | to exchange stat structures with application programs compiled using the |
2128 | to exchange stat structures with application programs compiled using the |
… | |
… | |
1959 | etc. is difficult. |
2149 | etc. is difficult. |
1960 | .PP |
2150 | .PP |
1961 | \fIThe special problem of stat time resolution\fR |
2151 | \fIThe special problem of stat time resolution\fR |
1962 | .IX Subsection "The special problem of stat time resolution" |
2152 | .IX Subsection "The special problem of stat time resolution" |
1963 | .PP |
2153 | .PP |
1964 | The \f(CW\*(C`stat ()\*(C'\fR system call only supports full-second resolution portably, and |
2154 | The \f(CW\*(C`stat ()\*(C'\fR system call only supports full-second resolution portably, |
1965 | even on systems where the resolution is higher, most file systems still |
2155 | and even on systems where the resolution is higher, most file systems |
1966 | only support whole seconds. |
2156 | still only support whole seconds. |
1967 | .PP |
2157 | .PP |
1968 | That means that, if the time is the only thing that changes, you can |
2158 | That means that, if the time is the only thing that changes, you can |
1969 | easily miss updates: on the first update, \f(CW\*(C`ev_stat\*(C'\fR detects a change and |
2159 | easily miss updates: on the first update, \f(CW\*(C`ev_stat\*(C'\fR detects a change and |
1970 | calls your callback, which does something. When there is another update |
2160 | calls your callback, which does something. When there is another update |
1971 | within the same second, \f(CW\*(C`ev_stat\*(C'\fR will be unable to detect unless the |
2161 | within the same second, \f(CW\*(C`ev_stat\*(C'\fR will be unable to detect unless the |
… | |
… | |
2123 | Example: Dynamically allocate an \f(CW\*(C`ev_idle\*(C'\fR watcher, start it, and in the |
2313 | Example: Dynamically allocate an \f(CW\*(C`ev_idle\*(C'\fR watcher, start it, and in the |
2124 | callback, free it. Also, use no error checking, as usual. |
2314 | callback, free it. Also, use no error checking, as usual. |
2125 | .PP |
2315 | .PP |
2126 | .Vb 7 |
2316 | .Vb 7 |
2127 | \& static void |
2317 | \& static void |
2128 | \& idle_cb (struct ev_loop *loop, struct ev_idle *w, int revents) |
2318 | \& idle_cb (struct ev_loop *loop, ev_idle *w, int revents) |
2129 | \& { |
2319 | \& { |
2130 | \& free (w); |
2320 | \& free (w); |
2131 | \& // now do something you wanted to do when the program has |
2321 | \& // now do something you wanted to do when the program has |
2132 | \& // no longer anything immediate to do. |
2322 | \& // no longer anything immediate to do. |
2133 | \& } |
2323 | \& } |
2134 | \& |
2324 | \& |
2135 | \& struct ev_idle *idle_watcher = malloc (sizeof (struct ev_idle)); |
2325 | \& ev_idle *idle_watcher = malloc (sizeof (ev_idle)); |
2136 | \& ev_idle_init (idle_watcher, idle_cb); |
2326 | \& ev_idle_init (idle_watcher, idle_cb); |
2137 | \& ev_idle_start (loop, idle_cb); |
2327 | \& ev_idle_start (loop, idle_cb); |
2138 | .Ve |
2328 | .Ve |
2139 | .ie n .Sh """ev_prepare""\fP and \f(CW""ev_check"" \- customise your event loop!" |
2329 | .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!" |
2330 | .el .Sh "\f(CWev_prepare\fP and \f(CWev_check\fP \- customise your event loop!" |
… | |
… | |
2221 | .Vb 2 |
2411 | .Vb 2 |
2222 | \& static ev_io iow [nfd]; |
2412 | \& static ev_io iow [nfd]; |
2223 | \& static ev_timer tw; |
2413 | \& static ev_timer tw; |
2224 | \& |
2414 | \& |
2225 | \& static void |
2415 | \& static void |
2226 | \& io_cb (ev_loop *loop, ev_io *w, int revents) |
2416 | \& io_cb (struct ev_loop *loop, ev_io *w, int revents) |
2227 | \& { |
2417 | \& { |
2228 | \& } |
2418 | \& } |
2229 | \& |
2419 | \& |
2230 | \& // create io watchers for each fd and a timer before blocking |
2420 | \& // create io watchers for each fd and a timer before blocking |
2231 | \& static void |
2421 | \& static void |
2232 | \& adns_prepare_cb (ev_loop *loop, ev_prepare *w, int revents) |
2422 | \& adns_prepare_cb (struct ev_loop *loop, ev_prepare *w, int revents) |
2233 | \& { |
2423 | \& { |
2234 | \& int timeout = 3600000; |
2424 | \& int timeout = 3600000; |
2235 | \& struct pollfd fds [nfd]; |
2425 | \& struct pollfd fds [nfd]; |
2236 | \& // actual code will need to loop here and realloc etc. |
2426 | \& // actual code will need to loop here and realloc etc. |
2237 | \& adns_beforepoll (ads, fds, &nfd, &timeout, timeval_from (ev_time ())); |
2427 | \& adns_beforepoll (ads, fds, &nfd, &timeout, timeval_from (ev_time ())); |
… | |
… | |
2252 | \& } |
2442 | \& } |
2253 | \& } |
2443 | \& } |
2254 | \& |
2444 | \& |
2255 | \& // stop all watchers after blocking |
2445 | \& // stop all watchers after blocking |
2256 | \& static void |
2446 | \& static void |
2257 | \& adns_check_cb (ev_loop *loop, ev_check *w, int revents) |
2447 | \& adns_check_cb (struct ev_loop *loop, ev_check *w, int revents) |
2258 | \& { |
2448 | \& { |
2259 | \& ev_timer_stop (loop, &tw); |
2449 | \& ev_timer_stop (loop, &tw); |
2260 | \& |
2450 | \& |
2261 | \& for (int i = 0; i < nfd; ++i) |
2451 | \& for (int i = 0; i < nfd; ++i) |
2262 | \& { |
2452 | \& { |
… | |
… | |
2433 | used). |
2623 | used). |
2434 | .PP |
2624 | .PP |
2435 | .Vb 3 |
2625 | .Vb 3 |
2436 | \& struct ev_loop *loop_hi = ev_default_init (0); |
2626 | \& struct ev_loop *loop_hi = ev_default_init (0); |
2437 | \& struct ev_loop *loop_lo = 0; |
2627 | \& struct ev_loop *loop_lo = 0; |
2438 | \& struct ev_embed embed; |
2628 | \& ev_embed embed; |
2439 | \& |
2629 | \& |
2440 | \& // see if there is a chance of getting one that works |
2630 | \& // see if there is a chance of getting one that works |
2441 | \& // (remember that a flags value of 0 means autodetection) |
2631 | \& // (remember that a flags value of 0 means autodetection) |
2442 | \& loop_lo = ev_embeddable_backends () & ev_recommended_backends () |
2632 | \& loop_lo = ev_embeddable_backends () & ev_recommended_backends () |
2443 | \& ? ev_loop_new (ev_embeddable_backends () & ev_recommended_backends ()) |
2633 | \& ? 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). |
2649 | \&\f(CW\*(C`loop_socket\*(C'\fR. (One might optionally use \f(CW\*(C`EVFLAG_NOENV\*(C'\fR, too). |
2460 | .PP |
2650 | .PP |
2461 | .Vb 3 |
2651 | .Vb 3 |
2462 | \& struct ev_loop *loop = ev_default_init (0); |
2652 | \& struct ev_loop *loop = ev_default_init (0); |
2463 | \& struct ev_loop *loop_socket = 0; |
2653 | \& struct ev_loop *loop_socket = 0; |
2464 | \& struct ev_embed embed; |
2654 | \& ev_embed embed; |
2465 | \& |
2655 | \& |
2466 | \& if (ev_supported_backends () & ~ev_recommended_backends () & EVBACKEND_KQUEUE) |
2656 | \& if (ev_supported_backends () & ~ev_recommended_backends () & EVBACKEND_KQUEUE) |
2467 | \& if ((loop_socket = ev_loop_new (EVBACKEND_KQUEUE)) |
2657 | \& if ((loop_socket = ev_loop_new (EVBACKEND_KQUEUE)) |
2468 | \& { |
2658 | \& { |
2469 | \& ev_embed_init (&embed, 0, loop_socket); |
2659 | \& ev_embed_init (&embed, 0, loop_socket); |
… | |
… | |
2601 | \fIWatcher-Specific Functions and Data Members\fR |
2791 | \fIWatcher-Specific Functions and Data Members\fR |
2602 | .IX Subsection "Watcher-Specific Functions and Data Members" |
2792 | .IX Subsection "Watcher-Specific Functions and Data Members" |
2603 | .IP "ev_async_init (ev_async *, callback)" 4 |
2793 | .IP "ev_async_init (ev_async *, callback)" 4 |
2604 | .IX Item "ev_async_init (ev_async *, callback)" |
2794 | .IX Item "ev_async_init (ev_async *, callback)" |
2605 | Initialises and configures the async watcher \- it has no parameters of any |
2795 | Initialises and configures the async watcher \- it has no parameters of any |
2606 | kind. There is a \f(CW\*(C`ev_asynd_set\*(C'\fR macro, but using it is utterly pointless, |
2796 | kind. There is a \f(CW\*(C`ev_async_set\*(C'\fR macro, but using it is utterly pointless, |
2607 | trust me. |
2797 | trust me. |
2608 | .IP "ev_async_send (loop, ev_async *)" 4 |
2798 | .IP "ev_async_send (loop, ev_async *)" 4 |
2609 | .IX Item "ev_async_send (loop, ev_async *)" |
2799 | .IX Item "ev_async_send (loop, ev_async *)" |
2610 | Sends/signals/activates the given \f(CW\*(C`ev_async\*(C'\fR watcher, that is, feeds |
2800 | Sends/signals/activates the given \f(CW\*(C`ev_async\*(C'\fR watcher, that is, feeds |
2611 | an \f(CW\*(C`EV_ASYNC\*(C'\fR event on the watcher into the event loop. Unlike |
2801 | an \f(CW\*(C`EV_ASYNC\*(C'\fR event on the watcher into the event loop. Unlike |
… | |
… | |
2666 | \& /* doh, nothing entered */; |
2856 | \& /* doh, nothing entered */; |
2667 | \& } |
2857 | \& } |
2668 | \& |
2858 | \& |
2669 | \& ev_once (STDIN_FILENO, EV_READ, 10., stdin_ready, 0); |
2859 | \& ev_once (STDIN_FILENO, EV_READ, 10., stdin_ready, 0); |
2670 | .Ve |
2860 | .Ve |
2671 | .IP "ev_feed_event (ev_loop *, watcher *, int revents)" 4 |
2861 | .IP "ev_feed_event (struct ev_loop *, watcher *, int revents)" 4 |
2672 | .IX Item "ev_feed_event (ev_loop *, watcher *, int revents)" |
2862 | .IX Item "ev_feed_event (struct ev_loop *, watcher *, int revents)" |
2673 | Feeds the given event set into the event loop, as if the specified event |
2863 | Feeds the given event set into the event loop, as if the specified event |
2674 | had happened for the specified watcher (which must be a pointer to an |
2864 | had happened for the specified watcher (which must be a pointer to an |
2675 | initialised but not necessarily started event watcher). |
2865 | initialised but not necessarily started event watcher). |
2676 | .IP "ev_feed_fd_event (ev_loop *, int fd, int revents)" 4 |
2866 | .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)" |
2867 | .IX Item "ev_feed_fd_event (struct ev_loop *, int fd, int revents)" |
2678 | Feed an event on the given fd, as if a file descriptor backend detected |
2868 | Feed an event on the given fd, as if a file descriptor backend detected |
2679 | the given events it. |
2869 | the given events it. |
2680 | .IP "ev_feed_signal_event (ev_loop *loop, int signum)" 4 |
2870 | .IP "ev_feed_signal_event (struct ev_loop *loop, int signum)" 4 |
2681 | .IX Item "ev_feed_signal_event (ev_loop *loop, int signum)" |
2871 | .IX Item "ev_feed_signal_event (struct ev_loop *loop, int signum)" |
2682 | Feed an event as if the given signal occurred (\f(CW\*(C`loop\*(C'\fR must be the default |
2872 | Feed an event as if the given signal occurred (\f(CW\*(C`loop\*(C'\fR must be the default |
2683 | loop!). |
2873 | loop!). |
2684 | .SH "LIBEVENT EMULATION" |
2874 | .SH "LIBEVENT EMULATION" |
2685 | .IX Header "LIBEVENT EMULATION" |
2875 | .IX Header "LIBEVENT EMULATION" |
2686 | Libev offers a compatibility emulation layer for libevent. It cannot |
2876 | Libev offers a compatibility emulation layer for libevent. It cannot |
… | |
… | |
2901 | <http://rev.rubyforge.org/>. |
3091 | <http://rev.rubyforge.org/>. |
2902 | .IP "D" 4 |
3092 | .IP "D" 4 |
2903 | .IX Item "D" |
3093 | .IX Item "D" |
2904 | Leandro Lucarella has written a D language binding (\fIev.d\fR) for libev, to |
3094 | Leandro Lucarella has written a D language binding (\fIev.d\fR) for libev, to |
2905 | be found at <http://proj.llucax.com.ar/wiki/evd>. |
3095 | be found at <http://proj.llucax.com.ar/wiki/evd>. |
|
|
3096 | .IP "Ocaml" 4 |
|
|
3097 | .IX Item "Ocaml" |
|
|
3098 | Erkki Seppala has written Ocaml bindings for libev, to be found at |
|
|
3099 | <http://modeemi.cs.tut.fi/~flux/software/ocaml\-ev/>. |
2906 | .SH "MACRO MAGIC" |
3100 | .SH "MACRO MAGIC" |
2907 | .IX Header "MACRO MAGIC" |
3101 | .IX Header "MACRO MAGIC" |
2908 | Libev can be compiled with a variety of options, the most fundamental |
3102 | Libev can be compiled with a variety of options, the most fundamental |
2909 | of which is \f(CW\*(C`EV_MULTIPLICITY\*(C'\fR. This option determines whether (most) |
3103 | of which is \f(CW\*(C`EV_MULTIPLICITY\*(C'\fR. This option determines whether (most) |
2910 | functions and callbacks have an initial \f(CW\*(C`struct ev_loop *\*(C'\fR argument. |
3104 | functions and callbacks have an initial \f(CW\*(C`struct ev_loop *\*(C'\fR argument. |
… | |
… | |
3012 | \& #define EV_STANDALONE 1 |
3206 | \& #define EV_STANDALONE 1 |
3013 | \& #include "ev.h" |
3207 | \& #include "ev.h" |
3014 | .Ve |
3208 | .Ve |
3015 | .PP |
3209 | .PP |
3016 | Both header files and implementation files can be compiled with a \*(C+ |
3210 | Both header files and implementation files can be compiled with a \*(C+ |
3017 | compiler (at least, thats a stated goal, and breakage will be treated |
3211 | compiler (at least, that's a stated goal, and breakage will be treated |
3018 | as a bug). |
3212 | as a bug). |
3019 | .PP |
3213 | .PP |
3020 | You need the following files in your source tree, or in a directory |
3214 | You need the following files in your source tree, or in a directory |
3021 | in your include path (e.g. in libev/ when using \-Ilibev): |
3215 | in your include path (e.g. in libev/ when using \-Ilibev): |
3022 | .PP |
3216 | .PP |
… | |
… | |
3476 | loop, as long as you don't confuse yourself). The only exception is that |
3670 | loop, as long as you don't confuse yourself). The only exception is that |
3477 | you must not do this from \f(CW\*(C`ev_periodic\*(C'\fR reschedule callbacks. |
3671 | you must not do this from \f(CW\*(C`ev_periodic\*(C'\fR reschedule callbacks. |
3478 | .PP |
3672 | .PP |
3479 | Care has been taken to ensure that libev does not keep local state inside |
3673 | Care 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 |
3674 | \&\f(CW\*(C`ev_loop\*(C'\fR, and other calls do not usually allow for coroutine switches as |
3481 | they do not clal any callbacks. |
3675 | they do not call any callbacks. |
3482 | .Sh "\s-1COMPILER\s0 \s-1WARNINGS\s0" |
3676 | .Sh "\s-1COMPILER\s0 \s-1WARNINGS\s0" |
3483 | .IX Subsection "COMPILER WARNINGS" |
3677 | .IX Subsection "COMPILER WARNINGS" |
3484 | Depending on your compiler and compiler settings, you might get no or a |
3678 | Depending on your compiler and compiler settings, you might get no or a |
3485 | lot of warnings when compiling libev code. Some people are apparently |
3679 | lot of warnings when compiling libev code. Some people are apparently |
3486 | scared by this. |
3680 | scared by this. |
… | |
… | |
3519 | \& ==2274== possibly lost: 0 bytes in 0 blocks. |
3713 | \& ==2274== possibly lost: 0 bytes in 0 blocks. |
3520 | \& ==2274== still reachable: 256 bytes in 1 blocks. |
3714 | \& ==2274== still reachable: 256 bytes in 1 blocks. |
3521 | .Ve |
3715 | .Ve |
3522 | .PP |
3716 | .PP |
3523 | Then there is no memory leak, just as memory accounted to global variables |
3717 | Then there is no memory leak, just as memory accounted to global variables |
3524 | is not a memleak \- the memory is still being refernced, and didn't leak. |
3718 | is not a memleak \- the memory is still being referenced, and didn't leak. |
3525 | .PP |
3719 | .PP |
3526 | Similarly, under some circumstances, valgrind might report kernel bugs |
3720 | Similarly, under some circumstances, valgrind might report kernel bugs |
3527 | as if it were a bug in libev (e.g. in realloc or in the poll backend, |
3721 | as if it were a bug in libev (e.g. in realloc or in the poll backend, |
3528 | although an acceptable workaround has been found here), or it might be |
3722 | although an acceptable workaround has been found here), or it might be |
3529 | confused. |
3723 | confused. |
… | |
… | |
3749 | Sending involves a system call \fIiff\fR there were no other \f(CW\*(C`ev_async_send\*(C'\fR |
3943 | Sending involves a system call \fIiff\fR there were no other \f(CW\*(C`ev_async_send\*(C'\fR |
3750 | calls in the current loop iteration. Checking for async and signal events |
3944 | calls in the current loop iteration. Checking for async and signal events |
3751 | involves iterating over all running async watchers or all signal numbers. |
3945 | involves iterating over all running async watchers or all signal numbers. |
3752 | .SH "AUTHOR" |
3946 | .SH "AUTHOR" |
3753 | .IX Header "AUTHOR" |
3947 | .IX Header "AUTHOR" |
3754 | Marc Lehmann <libev@schmorp.de>. |
3948 | Marc Lehmann <libev@schmorp.de>, with repeated corrections by Mikael Magnusson. |