… | |
… | |
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-09-29" "libev-3.44" "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); |
… | |
… | |
240 | Libev is very configurable. In this manual the default (and most common) |
242 | Libev is very configurable. In this manual the default (and most common) |
241 | configuration will be described, which supports multiple event loops. For |
243 | configuration will be described, which supports multiple event loops. For |
242 | more info about various configuration options please have a look at |
244 | 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 |
245 | \&\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 |
246 | 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 |
247 | 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. |
248 | this 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" |
249 | Libev represents time as a single floating point number, representing the |
251 | Libev 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" |
411 | An event loop is described by a \f(CW\*(C`struct ev_loop *\*(C'\fR. The library knows two |
413 | 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 |
414 | 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. |
415 | \&\fIfunction\fR). |
|
|
416 | .PP |
|
|
417 | The library knows two types of such loops, the \fIdefault\fR loop, which |
|
|
418 | supports signals and child events, and dynamically created loops which do |
|
|
419 | not. |
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)" |
416 | This will initialise the default event loop if it hasn't been initialised |
422 | 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 |
423 | 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 |
424 | 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 |
427 | If you don't know what event loop to use, use the one returned from this |
422 | function. |
428 | function. |
423 | .Sp |
429 | .Sp |
424 | Note that this function is \fInot\fR thread-safe, so if you want to use it |
430 | 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, |
431 | from multiple threads, you have to lock (note also that this is unlikely, |
426 | as loops cannot bes hared easily between threads anyway). |
432 | as loops cannot be shared easily between threads anyway). |
427 | .Sp |
433 | .Sp |
428 | The default loop is the only loop that can handle \f(CW\*(C`ev_signal\*(C'\fR and |
434 | 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 |
435 | \&\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 |
436 | 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 |
437 | 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 |
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)" |
508 | For few fds, this backend is a bit little slower than poll and select, |
514 | 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 |
515 | 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), |
516 | 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 |
517 | epoll scales either O(1) or O(active_fds). |
512 | of shortcomings, such as silently dropping events in some hard-to-detect |
518 | .Sp |
513 | cases and requiring a system call per fd change, no fork support and bad |
519 | The epoll mechanism deserves honorable mention as the most misdesigned |
514 | support for dup. |
520 | of the more advanced event mechanisms: mere annoyances include silently |
|
|
521 | dropping file descriptors, requiring a system call per change per file |
|
|
522 | descriptor (and unnecessary guessing of parameters), problems with dup and |
|
|
523 | so 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 |
|
|
525 | take considerable time (one syscall per file descriptor) and is of course |
|
|
526 | hard to detect. |
|
|
527 | .Sp |
|
|
528 | Epoll is also notoriously buggy \- embedding epoll fds \fIshould\fR work, but |
|
|
529 | of 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 |
|
|
531 | even remove them from the set) than registered in the set (especially |
|
|
532 | on \s-1SMP\s0 systems). Libev tries to counter these spurious notifications by |
|
|
533 | employing an additional generation counter and comparing that against the |
|
|
534 | events to filter out spurious ones, recreating the set when required. |
515 | .Sp |
535 | .Sp |
516 | While stopping, setting and starting an I/O watcher in the same iteration |
536 | 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 |
537 | 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 |
538 | 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 |
539 | \&\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. |
540 | file descriptors might not work very well if you register events for both |
521 | .Sp |
541 | 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 |
542 | .Sp |
526 | Best performance from this backend is achieved by not unregistering all |
543 | Best performance from this backend is achieved by not unregistering all |
527 | watchers for a file descriptor until it has been closed, if possible, |
544 | 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 |
545 | 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 |
546 | starting a watcher (without re-setting it) also usually doesn't cause |
530 | extra overhead. |
547 | extra overhead. A fork can both result in spurious notifications as well |
|
|
548 | as in libev having to destroy and recreate the epoll object, which can |
|
|
549 | take considerable time and thus should be avoided. |
|
|
550 | .Sp |
|
|
551 | All this means that, in practice, \f(CW\*(C`EVBACKEND_SELECT\*(C'\fR can be as fast or |
|
|
552 | faster than epoll for maybe up to a hundred file descriptors, depending on |
|
|
553 | the usage. So sad. |
531 | .Sp |
554 | .Sp |
532 | While nominally embeddable in other event loops, this feature is broken in |
555 | While nominally embeddable in other event loops, this feature is broken in |
533 | all kernel versions tested so far. |
556 | all kernel versions tested so far. |
534 | .Sp |
557 | .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 |
558 | 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. |
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)" |
540 | Kqueue deserves special mention, as at the time of this writing, it was |
563 | 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 |
564 | 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 |
565 | 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 |
566 | 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 |
567 | 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. |
568 | without \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) |
|
|
571 | system like NetBSD. |
546 | .Sp |
572 | .Sp |
547 | You still can embed kqueue into a normal poll or select backend and use it |
573 | 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 |
574 | 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. |
575 | the target platform). See \f(CW\*(C`ev_embed\*(C'\fR watchers for more info. |
550 | .Sp |
576 | .Sp |
551 | It scales in the same way as the epoll backend, but the interface to the |
577 | 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 |
578 | 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 |
579 | 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 |
580 | 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 |
581 | 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. |
582 | sane, unlike epoll) and it drops fds silently in similarly hard-to-detect |
|
|
583 | cases |
557 | .Sp |
584 | .Sp |
558 | This backend usually performs well under most conditions. |
585 | This backend usually performs well under most conditions. |
559 | .Sp |
586 | .Sp |
560 | While nominally embeddable in other event loops, this doesn't work |
587 | 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 |
588 | everywhere, so you might need to test for this. And since it is broken |
… | |
… | |
590 | might perform better. |
617 | might perform better. |
591 | .Sp |
618 | .Sp |
592 | On the positive side, with the exception of the spurious readiness |
619 | On the positive side, with the exception of the spurious readiness |
593 | notifications, this backend actually performed fully to specification |
620 | notifications, this backend actually performed fully to specification |
594 | in all tests and is fully embeddable, which is a rare feat among the |
621 | in all tests and is fully embeddable, which is a rare feat among the |
595 | OS-specific backends. |
622 | OS-specific backends (I vastly prefer correctness over speed hacks). |
596 | .Sp |
623 | .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 |
624 | 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. |
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 |
… | |
… | |
660 | responsibility to either stop all watchers cleanly yourself \fIbefore\fR |
687 | responsibility to either stop all watchers cleanly yourself \fIbefore\fR |
661 | calling this function, or cope with the fact afterwards (which is usually |
688 | 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 |
689 | the easiest thing, you can just ignore the watchers and/or \f(CW\*(C`free ()\*(C'\fR them |
663 | for example). |
690 | for example). |
664 | .Sp |
691 | .Sp |
665 | Note that certain global state, such as signal state, will not be freed by |
692 | Note that certain global state, such as signal state (and installed signal |
666 | this function, and related watchers (such as signal and child watchers) |
693 | handlers), will not be freed by this function, and related watchers (such |
667 | would need to be stopped manually. |
694 | as signal and child watchers) would need to be stopped manually. |
668 | .Sp |
695 | .Sp |
669 | In general it is not advisable to call this function except in the |
696 | 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 |
697 | 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 |
698 | 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). |
699 | \&\f(CW\*(C`ev_loop_new\*(C'\fR and \f(CW\*(C`ev_loop_destroy\*(C'\fR). |
… | |
… | |
757 | the loop. |
784 | the loop. |
758 | .Sp |
785 | .Sp |
759 | A flags value of \f(CW\*(C`EVLOOP_ONESHOT\*(C'\fR will look for new events (waiting if |
786 | 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 |
787 | 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 |
788 | 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 |
789 | 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 |
790 | user-registered callback will be called), and will return after one |
764 | iteration of the loop. |
791 | iteration of the loop. |
765 | .Sp |
792 | .Sp |
766 | This is useful if you are waiting for some external event in conjunction |
793 | 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 |
794 | with something not expressible using other libev watchers (i.e. "roll your |
… | |
… | |
813 | has processed all outstanding events). The \f(CW\*(C`how\*(C'\fR argument must be either |
840 | has processed all outstanding events). The \f(CW\*(C`how\*(C'\fR argument must be either |
814 | \&\f(CW\*(C`EVUNLOOP_ONE\*(C'\fR, which will make the innermost \f(CW\*(C`ev_loop\*(C'\fR call return, or |
841 | \&\f(CW\*(C`EVUNLOOP_ONE\*(C'\fR, which will make the innermost \f(CW\*(C`ev_loop\*(C'\fR call return, or |
815 | \&\f(CW\*(C`EVUNLOOP_ALL\*(C'\fR, which will make all nested \f(CW\*(C`ev_loop\*(C'\fR calls return. |
842 | \&\f(CW\*(C`EVUNLOOP_ALL\*(C'\fR, which will make all nested \f(CW\*(C`ev_loop\*(C'\fR calls return. |
816 | .Sp |
843 | .Sp |
817 | This \*(L"unloop state\*(R" will be cleared when entering \f(CW\*(C`ev_loop\*(C'\fR again. |
844 | This \*(L"unloop state\*(R" will be cleared when entering \f(CW\*(C`ev_loop\*(C'\fR again. |
|
|
845 | .Sp |
|
|
846 | It is safe to call \f(CW\*(C`ev_unloop\*(C'\fR from otuside any \f(CW\*(C`ev_loop\*(C'\fR calls. |
818 | .IP "ev_ref (loop)" 4 |
847 | .IP "ev_ref (loop)" 4 |
819 | .IX Item "ev_ref (loop)" |
848 | .IX Item "ev_ref (loop)" |
820 | .PD 0 |
849 | .PD 0 |
821 | .IP "ev_unref (loop)" 4 |
850 | .IP "ev_unref (loop)" 4 |
822 | .IX Item "ev_unref (loop)" |
851 | .IX Item "ev_unref (loop)" |
… | |
… | |
839 | .Sp |
868 | .Sp |
840 | Example: Create a signal watcher, but keep it from keeping \f(CW\*(C`ev_loop\*(C'\fR |
869 | Example: Create a signal watcher, but keep it from keeping \f(CW\*(C`ev_loop\*(C'\fR |
841 | running when nothing else is active. |
870 | running when nothing else is active. |
842 | .Sp |
871 | .Sp |
843 | .Vb 4 |
872 | .Vb 4 |
844 | \& struct ev_signal exitsig; |
873 | \& ev_signal exitsig; |
845 | \& ev_signal_init (&exitsig, sig_cb, SIGINT); |
874 | \& ev_signal_init (&exitsig, sig_cb, SIGINT); |
846 | \& ev_signal_start (loop, &exitsig); |
875 | \& ev_signal_start (loop, &exitsig); |
847 | \& evf_unref (loop); |
876 | \& evf_unref (loop); |
848 | .Ve |
877 | .Ve |
849 | .Sp |
878 | .Sp |
… | |
… | |
900 | reduce iterations/wake\-ups is to use \f(CW\*(C`ev_periodic\*(C'\fR watchers and make sure |
929 | reduce iterations/wake\-ups is to use \f(CW\*(C`ev_periodic\*(C'\fR watchers and make sure |
901 | they fire on, say, one-second boundaries only. |
930 | they fire on, say, one-second boundaries only. |
902 | .IP "ev_loop_verify (loop)" 4 |
931 | .IP "ev_loop_verify (loop)" 4 |
903 | .IX Item "ev_loop_verify (loop)" |
932 | .IX Item "ev_loop_verify (loop)" |
904 | This function only does something when \f(CW\*(C`EV_VERIFY\*(C'\fR support has been |
933 | This function only does something when \f(CW\*(C`EV_VERIFY\*(C'\fR support has been |
905 | compiled in. which is the default for non-minimal builds. It tries to go |
934 | compiled in, which is the default for non-minimal builds. It tries to go |
906 | through all internal structures and checks them for validity. If anything |
935 | through all internal structures and checks them for validity. If anything |
907 | is found to be inconsistent, it will print an error message to standard |
936 | is found to be inconsistent, it will print an error message to standard |
908 | error and call \f(CW\*(C`abort ()\*(C'\fR. |
937 | error and call \f(CW\*(C`abort ()\*(C'\fR. |
909 | .Sp |
938 | .Sp |
910 | This can be used to catch bugs inside libev itself: under normal |
939 | This can be used to catch bugs inside libev itself: under normal |
911 | circumstances, this function will never abort as of course libev keeps its |
940 | circumstances, this function will never abort as of course libev keeps its |
912 | data structures consistent. |
941 | data structures consistent. |
913 | .SH "ANATOMY OF A WATCHER" |
942 | .SH "ANATOMY OF A WATCHER" |
914 | .IX Header "ANATOMY OF A WATCHER" |
943 | .IX Header "ANATOMY OF A WATCHER" |
|
|
944 | In the following description, uppercase \f(CW\*(C`TYPE\*(C'\fR in names stands for the |
|
|
945 | watcher type, e.g. \f(CW\*(C`ev_TYPE_start\*(C'\fR can mean \f(CW\*(C`ev_timer_start\*(C'\fR for timer |
|
|
946 | watchers and \f(CW\*(C`ev_io_start\*(C'\fR for I/O watchers. |
|
|
947 | .PP |
915 | A watcher is a structure that you create and register to record your |
948 | A watcher is a structure that you create and register to record your |
916 | interest in some event. For instance, if you want to wait for \s-1STDIN\s0 to |
949 | interest in some event. For instance, if you want to wait for \s-1STDIN\s0 to |
917 | become readable, you would create an \f(CW\*(C`ev_io\*(C'\fR watcher for that: |
950 | become readable, you would create an \f(CW\*(C`ev_io\*(C'\fR watcher for that: |
918 | .PP |
951 | .PP |
919 | .Vb 5 |
952 | .Vb 5 |
920 | \& 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) |
921 | \& { |
954 | \& { |
922 | \& ev_io_stop (w); |
955 | \& ev_io_stop (w); |
923 | \& ev_unloop (loop, EVUNLOOP_ALL); |
956 | \& ev_unloop (loop, EVUNLOOP_ALL); |
924 | \& } |
957 | \& } |
925 | \& |
958 | \& |
926 | \& struct ev_loop *loop = ev_default_loop (0); |
959 | \& struct ev_loop *loop = ev_default_loop (0); |
|
|
960 | \& |
927 | \& struct ev_io stdin_watcher; |
961 | \& ev_io stdin_watcher; |
|
|
962 | \& |
928 | \& ev_init (&stdin_watcher, my_cb); |
963 | \& ev_init (&stdin_watcher, my_cb); |
929 | \& ev_io_set (&stdin_watcher, STDIN_FILENO, EV_READ); |
964 | \& ev_io_set (&stdin_watcher, STDIN_FILENO, EV_READ); |
930 | \& ev_io_start (loop, &stdin_watcher); |
965 | \& ev_io_start (loop, &stdin_watcher); |
|
|
966 | \& |
931 | \& ev_loop (loop, 0); |
967 | \& ev_loop (loop, 0); |
932 | .Ve |
968 | .Ve |
933 | .PP |
969 | .PP |
934 | As you can see, you are responsible for allocating the memory for your |
970 | As you can see, you are responsible for allocating the memory for your |
935 | watcher structures (and it is usually a bad idea to do this on the stack, |
971 | watcher structures (and it is \fIusually\fR a bad idea to do this on the |
936 | although this can sometimes be quite valid). |
972 | stack). |
|
|
973 | .PP |
|
|
974 | Each watcher has an associated watcher structure (called \f(CW\*(C`struct ev_TYPE\*(C'\fR |
|
|
975 | or simply \f(CW\*(C`ev_TYPE\*(C'\fR, as typedefs are provided for all watcher structs). |
937 | .PP |
976 | .PP |
938 | Each watcher structure must be initialised by a call to \f(CW\*(C`ev_init |
977 | Each watcher structure must be initialised by a call to \f(CW\*(C`ev_init |
939 | (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 |
940 | callback gets invoked each time the event occurs (or, in the case of I/O |
979 | callback gets invoked each time the event occurs (or, in the case of I/O |
941 | watchers, each time the event loop detects that the file descriptor given |
980 | watchers, each time the event loop detects that the file descriptor given |
942 | is readable and/or writable). |
981 | is readable and/or writable). |
943 | .PP |
982 | .PP |
944 | Each watcher type has its own \f(CW\*(C`ev_<type>_set (watcher *, ...)\*(C'\fR macro |
983 | Each watcher type further has its own \f(CW\*(C`ev_TYPE_set (watcher *, ...)\*(C'\fR |
945 | with arguments specific to this watcher type. There is also a macro |
984 | macro to configure it, with arguments specific to the watcher type. There |
946 | to combine initialisation and setting in one call: \f(CW\*(C`ev_<type>_init |
985 | is also a macro to combine initialisation and setting in one call: \f(CW\*(C`ev_TYPE_init (watcher *, callback, ...)\*(C'\fR. |
947 | (watcher *, callback, ...)\*(C'\fR. |
|
|
948 | .PP |
986 | .PP |
949 | To make the watcher actually watch out for events, you have to start it |
987 | To make the watcher actually watch out for events, you have to start it |
950 | with a watcher-specific start function (\f(CW\*(C`ev_<type>_start (loop, watcher |
988 | with a watcher-specific start function (\f(CW\*(C`ev_TYPE_start (loop, watcher |
951 | *)\*(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 |
952 | corresponding stop function (\f(CW\*(C`ev_<type>_stop (loop, watcher *)\*(C'\fR. |
990 | corresponding stop function (\f(CW\*(C`ev_TYPE_stop (loop, watcher *)\*(C'\fR. |
953 | .PP |
991 | .PP |
954 | As long as your watcher is active (has been started but not stopped) you |
992 | As long as your watcher is active (has been started but not stopped) you |
955 | must not touch the values stored in it. Most specifically you must never |
993 | must not touch the values stored in it. Most specifically you must never |
956 | reinitialise it or call its \f(CW\*(C`set\*(C'\fR macro. |
994 | reinitialise it or call its \f(CW\*(C`ev_TYPE_set\*(C'\fR macro. |
957 | .PP |
995 | .PP |
958 | Each and every callback receives the event loop pointer as first, the |
996 | Each and every callback receives the event loop pointer as first, the |
959 | registered watcher structure as second, and a bitset of received events as |
997 | registered watcher structure as second, and a bitset of received events as |
960 | third argument. |
998 | third argument. |
961 | .PP |
999 | .PP |
… | |
… | |
1028 | .el .IP "\f(CWEV_ERROR\fR" 4 |
1066 | .el .IP "\f(CWEV_ERROR\fR" 4 |
1029 | .IX Item "EV_ERROR" |
1067 | .IX Item "EV_ERROR" |
1030 | An unspecified error has occurred, the watcher has been stopped. This might |
1068 | An unspecified error has occurred, the watcher has been stopped. This might |
1031 | happen because the watcher could not be properly started because libev |
1069 | happen because the watcher could not be properly started because libev |
1032 | ran out of memory, a file descriptor was found to be closed or any other |
1070 | ran out of memory, a file descriptor was found to be closed or any other |
|
|
1071 | problem. Libev considers these application bugs. |
|
|
1072 | .Sp |
1033 | problem. You best act on it by reporting the problem and somehow coping |
1073 | You best act on it by reporting the problem and somehow coping with the |
1034 | with the watcher being stopped. |
1074 | watcher being stopped. Note that well-written programs should not receive |
|
|
1075 | an error ever, so when your watcher receives it, this usually indicates a |
|
|
1076 | bug in your program. |
1035 | .Sp |
1077 | .Sp |
1036 | Libev will usually signal a few \*(L"dummy\*(R" events together with an error, for |
1078 | Libev will usually signal a few \*(L"dummy\*(R" events together with an error, for |
1037 | example it might indicate that a fd is readable or writable, and if your |
1079 | example it might indicate that a fd is readable or writable, and if your |
1038 | callbacks is well-written it can just attempt the operation and cope with |
1080 | callbacks is well-written it can just attempt the operation and cope with |
1039 | the error from \fIread()\fR or \fIwrite()\fR. This will not work in multi-threaded |
1081 | the error from \fIread()\fR or \fIwrite()\fR. This will not work in multi-threaded |
1040 | programs, though, as the fd could already be closed and reused for another |
1082 | programs, though, as the fd could already be closed and reused for another |
1041 | thing, so beware. |
1083 | thing, so beware. |
1042 | .Sh "\s-1GENERIC\s0 \s-1WATCHER\s0 \s-1FUNCTIONS\s0" |
1084 | .Sh "\s-1GENERIC\s0 \s-1WATCHER\s0 \s-1FUNCTIONS\s0" |
1043 | .IX Subsection "GENERIC WATCHER FUNCTIONS" |
1085 | .IX Subsection "GENERIC WATCHER FUNCTIONS" |
1044 | In the following description, \f(CW\*(C`TYPE\*(C'\fR stands for the watcher type, |
|
|
1045 | 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. |
|
|
1046 | .ie n .IP """ev_init"" (ev_TYPE *watcher, callback)" 4 |
1086 | .ie n .IP """ev_init"" (ev_TYPE *watcher, callback)" 4 |
1047 | .el .IP "\f(CWev_init\fR (ev_TYPE *watcher, callback)" 4 |
1087 | .el .IP "\f(CWev_init\fR (ev_TYPE *watcher, callback)" 4 |
1048 | .IX Item "ev_init (ev_TYPE *watcher, callback)" |
1088 | .IX Item "ev_init (ev_TYPE *watcher, callback)" |
1049 | This macro initialises the generic portion of a watcher. The contents |
1089 | This macro initialises the generic portion of a watcher. The contents |
1050 | of the watcher object can be arbitrary (so \f(CW\*(C`malloc\*(C'\fR will do). Only |
1090 | of the watcher object can be arbitrary (so \f(CW\*(C`malloc\*(C'\fR will do). Only |
… | |
… | |
1054 | which rolls both calls into one. |
1094 | which rolls both calls into one. |
1055 | .Sp |
1095 | .Sp |
1056 | You can reinitialise a watcher at any time as long as it has been stopped |
1096 | You can reinitialise a watcher at any time as long as it has been stopped |
1057 | (or never started) and there are no pending events outstanding. |
1097 | (or never started) and there are no pending events outstanding. |
1058 | .Sp |
1098 | .Sp |
1059 | The callback is always of type \f(CW\*(C`void (*)(ev_loop *loop, ev_TYPE *watcher, |
1099 | The callback is always of type \f(CW\*(C`void (*)(struct ev_loop *loop, ev_TYPE *watcher, |
1060 | int revents)\*(C'\fR. |
1100 | int revents)\*(C'\fR. |
1061 | .Sp |
1101 | .Sp |
1062 | Example: Initialise an \f(CW\*(C`ev_io\*(C'\fR watcher in two steps. |
1102 | Example: Initialise an \f(CW\*(C`ev_io\*(C'\fR watcher in two steps. |
1063 | .Sp |
1103 | .Sp |
1064 | .Vb 3 |
1104 | .Vb 3 |
… | |
… | |
1104 | \& ev_io_start (EV_DEFAULT_UC, &w); |
1144 | \& ev_io_start (EV_DEFAULT_UC, &w); |
1105 | .Ve |
1145 | .Ve |
1106 | .ie n .IP """ev_TYPE_stop"" (loop *, ev_TYPE *watcher)" 4 |
1146 | .ie n .IP """ev_TYPE_stop"" (loop *, ev_TYPE *watcher)" 4 |
1107 | .el .IP "\f(CWev_TYPE_stop\fR (loop *, ev_TYPE *watcher)" 4 |
1147 | .el .IP "\f(CWev_TYPE_stop\fR (loop *, ev_TYPE *watcher)" 4 |
1108 | .IX Item "ev_TYPE_stop (loop *, ev_TYPE *watcher)" |
1148 | .IX Item "ev_TYPE_stop (loop *, ev_TYPE *watcher)" |
1109 | Stops the given watcher again (if active) and clears the pending |
1149 | Stops the given watcher if active, and clears the pending status (whether |
|
|
1150 | the watcher was active or not). |
|
|
1151 | .Sp |
1110 | status. It is possible that stopped watchers are pending (for example, |
1152 | It is possible that stopped watchers are pending \- for example, |
1111 | non-repeating timers are being stopped when they become pending), but |
1153 | non-repeating timers are being stopped when they become pending \- but |
1112 | \&\f(CW\*(C`ev_TYPE_stop\*(C'\fR ensures that the watcher is neither active nor pending. If |
1154 | calling \f(CW\*(C`ev_TYPE_stop\*(C'\fR ensures that the watcher is neither active nor |
1113 | you want to free or reuse the memory used by the watcher it is therefore a |
1155 | pending. If you want to free or reuse the memory used by the watcher it is |
1114 | good idea to always call its \f(CW\*(C`ev_TYPE_stop\*(C'\fR function. |
1156 | therefore a good idea to always call its \f(CW\*(C`ev_TYPE_stop\*(C'\fR function. |
1115 | .IP "bool ev_is_active (ev_TYPE *watcher)" 4 |
1157 | .IP "bool ev_is_active (ev_TYPE *watcher)" 4 |
1116 | .IX Item "bool ev_is_active (ev_TYPE *watcher)" |
1158 | .IX Item "bool ev_is_active (ev_TYPE *watcher)" |
1117 | Returns a true value iff the watcher is active (i.e. it has been started |
1159 | Returns a true value iff the watcher is active (i.e. it has been started |
1118 | and not yet been stopped). As long as a watcher is active you must not modify |
1160 | and not yet been stopped). As long as a watcher is active you must not modify |
1119 | it. |
1161 | it. |
… | |
… | |
1158 | The default priority used by watchers when no priority has been set is |
1200 | The default priority used by watchers when no priority has been set is |
1159 | always \f(CW0\fR, which is supposed to not be too high and not be too low :). |
1201 | always \f(CW0\fR, which is supposed to not be too high and not be too low :). |
1160 | .Sp |
1202 | .Sp |
1161 | Setting a priority outside the range of \f(CW\*(C`EV_MINPRI\*(C'\fR to \f(CW\*(C`EV_MAXPRI\*(C'\fR is |
1203 | Setting a priority outside the range of \f(CW\*(C`EV_MINPRI\*(C'\fR to \f(CW\*(C`EV_MAXPRI\*(C'\fR is |
1162 | fine, as long as you do not mind that the priority value you query might |
1204 | fine, as long as you do not mind that the priority value you query might |
1163 | or might not have been adjusted to be within valid range. |
1205 | or might not have been clamped to the valid range. |
1164 | .IP "ev_invoke (loop, ev_TYPE *watcher, int revents)" 4 |
1206 | .IP "ev_invoke (loop, ev_TYPE *watcher, int revents)" 4 |
1165 | .IX Item "ev_invoke (loop, ev_TYPE *watcher, int revents)" |
1207 | .IX Item "ev_invoke (loop, ev_TYPE *watcher, int revents)" |
1166 | 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 |
1208 | 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 |
1167 | \&\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 |
1168 | can deal with that fact, as both are simply passed through to the |
1210 | can deal with that fact, as both are simply passed through to the |
… | |
… | |
1185 | data: |
1227 | data: |
1186 | .PP |
1228 | .PP |
1187 | .Vb 7 |
1229 | .Vb 7 |
1188 | \& struct my_io |
1230 | \& struct my_io |
1189 | \& { |
1231 | \& { |
1190 | \& struct ev_io io; |
1232 | \& ev_io io; |
1191 | \& int otherfd; |
1233 | \& int otherfd; |
1192 | \& void *somedata; |
1234 | \& void *somedata; |
1193 | \& struct whatever *mostinteresting; |
1235 | \& struct whatever *mostinteresting; |
1194 | \& }; |
1236 | \& }; |
1195 | \& |
1237 | \& |
… | |
… | |
1200 | .PP |
1242 | .PP |
1201 | And since your callback will be called with a pointer to the watcher, you |
1243 | And since your callback will be called with a pointer to the watcher, you |
1202 | can cast it back to your own type: |
1244 | can cast it back to your own type: |
1203 | .PP |
1245 | .PP |
1204 | .Vb 5 |
1246 | .Vb 5 |
1205 | \& 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) |
1206 | \& { |
1248 | \& { |
1207 | \& struct my_io *w = (struct my_io *)w_; |
1249 | \& struct my_io *w = (struct my_io *)w_; |
1208 | \& ... |
1250 | \& ... |
1209 | \& } |
1251 | \& } |
1210 | .Ve |
1252 | .Ve |
… | |
… | |
1232 | .PP |
1274 | .PP |
1233 | .Vb 1 |
1275 | .Vb 1 |
1234 | \& #include <stddef.h> |
1276 | \& #include <stddef.h> |
1235 | \& |
1277 | \& |
1236 | \& static void |
1278 | \& static void |
1237 | \& t1_cb (EV_P_ struct ev_timer *w, int revents) |
1279 | \& t1_cb (EV_P_ ev_timer *w, int revents) |
1238 | \& { |
1280 | \& { |
1239 | \& struct my_biggy big = (struct my_biggy * |
1281 | \& struct my_biggy big = (struct my_biggy * |
1240 | \& (((char *)w) \- offsetof (struct my_biggy, t1)); |
1282 | \& (((char *)w) \- offsetof (struct my_biggy, t1)); |
1241 | \& } |
1283 | \& } |
1242 | \& |
1284 | \& |
1243 | \& static void |
1285 | \& static void |
1244 | \& t2_cb (EV_P_ struct ev_timer *w, int revents) |
1286 | \& t2_cb (EV_P_ ev_timer *w, int revents) |
1245 | \& { |
1287 | \& { |
1246 | \& struct my_biggy big = (struct my_biggy * |
1288 | \& struct my_biggy big = (struct my_biggy * |
1247 | \& (((char *)w) \- offsetof (struct my_biggy, t2)); |
1289 | \& (((char *)w) \- offsetof (struct my_biggy, t2)); |
1248 | \& } |
1290 | \& } |
1249 | .Ve |
1291 | .Ve |
… | |
… | |
1383 | readable, but only once. Since it is likely line-buffered, you could |
1425 | readable, but only once. Since it is likely line-buffered, you could |
1384 | attempt to read a whole line in the callback. |
1426 | attempt to read a whole line in the callback. |
1385 | .PP |
1427 | .PP |
1386 | .Vb 6 |
1428 | .Vb 6 |
1387 | \& static void |
1429 | \& static void |
1388 | \& 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) |
1389 | \& { |
1431 | \& { |
1390 | \& ev_io_stop (loop, w); |
1432 | \& ev_io_stop (loop, w); |
1391 | \& .. 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 |
1392 | \& } |
1434 | \& } |
1393 | \& |
1435 | \& |
1394 | \& ... |
1436 | \& ... |
1395 | \& struct ev_loop *loop = ev_default_init (0); |
1437 | \& struct ev_loop *loop = ev_default_init (0); |
1396 | \& struct ev_io stdin_readable; |
1438 | \& ev_io stdin_readable; |
1397 | \& 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); |
1398 | \& ev_io_start (loop, &stdin_readable); |
1440 | \& ev_io_start (loop, &stdin_readable); |
1399 | \& ev_loop (loop, 0); |
1441 | \& ev_loop (loop, 0); |
1400 | .Ve |
1442 | .Ve |
1401 | .ie n .Sh """ev_timer"" \- relative and optionally repeating timeouts" |
1443 | .ie n .Sh """ev_timer"" \- relative and optionally repeating timeouts" |
… | |
… | |
1411 | monotonic clock option helps a lot here). |
1453 | monotonic clock option helps a lot here). |
1412 | .PP |
1454 | .PP |
1413 | The callback is guaranteed to be invoked only \fIafter\fR its timeout has |
1455 | The callback is guaranteed to be invoked only \fIafter\fR its timeout has |
1414 | passed, but if multiple timers become ready during the same loop iteration |
1456 | passed, but if multiple timers become ready during the same loop iteration |
1415 | then order of execution is undefined. |
1457 | then order of execution is undefined. |
|
|
1458 | .PP |
|
|
1459 | \fIBe smart about timeouts\fR |
|
|
1460 | .IX Subsection "Be smart about timeouts" |
|
|
1461 | .PP |
|
|
1462 | Many real-world problems involve some kind of timeout, usually for error |
|
|
1463 | recovery. A typical example is an \s-1HTTP\s0 request \- if the other side hangs, |
|
|
1464 | you want to raise some error after a while. |
|
|
1465 | .PP |
|
|
1466 | What follows are some ways to handle this problem, from obvious and |
|
|
1467 | inefficient to smart and efficient. |
|
|
1468 | .PP |
|
|
1469 | In the following, a 60 second activity timeout is assumed \- a timeout that |
|
|
1470 | gets reset to 60 seconds each time there is activity (e.g. each time some |
|
|
1471 | data 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." |
|
|
1474 | This is the most obvious, but not the most simple way: In the beginning, |
|
|
1475 | start 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 |
|
|
1482 | Then, each time there is some activity, \f(CW\*(C`ev_timer_stop\*(C'\fR it, initialise it |
|
|
1483 | and 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 |
|
|
1491 | This is relatively simple to implement, but means that each time there is |
|
|
1492 | some activity, libev will first have to remove the timer from its internal |
|
|
1493 | data structure and then add it again. Libev tries to be fast, but it's |
|
|
1494 | still 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." |
|
|
1498 | This 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 |
|
|
1501 | To implement this, configure an \f(CW\*(C`ev_timer\*(C'\fR with a \f(CW\*(C`repeat\*(C'\fR value |
|
|
1502 | of \f(CW60\fR and then call \f(CW\*(C`ev_timer_again\*(C'\fR at start and each time you |
|
|
1503 | successfully read or write some data. If you go into an idle state where |
|
|
1504 | you do not expect data to travel on the socket, you can \f(CW\*(C`ev_timer_stop\*(C'\fR |
|
|
1505 | the timer, and \f(CW\*(C`ev_timer_again\*(C'\fR will automatically restart it if need be. |
|
|
1506 | .Sp |
|
|
1507 | That 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 |
|
|
1509 | member and \f(CW\*(C`ev_timer_again\*(C'\fR. |
|
|
1510 | .Sp |
|
|
1511 | At 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 |
|
|
1519 | Each time there is some activity: |
|
|
1520 | .Sp |
|
|
1521 | .Vb 1 |
|
|
1522 | \& ev_timer_again (loop, timer); |
|
|
1523 | .Ve |
|
|
1524 | .Sp |
|
|
1525 | It is even possible to change the time-out on the fly, regardless of |
|
|
1526 | whether 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 |
|
|
1533 | This is slightly more efficient then stopping/starting the timer each time |
|
|
1534 | you want to modify its timeout value, as libev does not have to completely |
|
|
1535 | remove and re-insert the timer from/into its internal data structure. |
|
|
1536 | .Sp |
|
|
1537 | It 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." |
|
|
1540 | This method is more tricky, but usually most efficient: Most timeouts are |
|
|
1541 | relatively long compared to the intervals between other activity \- in |
|
|
1542 | our example, within 60 seconds, there are usually many I/O events with |
|
|
1543 | associated activity resets. |
|
|
1544 | .Sp |
|
|
1545 | In this case, it would be more efficient to leave the \f(CW\*(C`ev_timer\*(C'\fR alone, |
|
|
1546 | but remember the time of last activity, and check for a real timeout only |
|
|
1547 | within 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 |
|
|
1574 | To summarise the callback: first calculate the real timeout (defined |
|
|
1575 | as \*(L"60 seconds after the last activity\*(R"), then check if that time has |
|
|
1576 | been reached, which means something \fIdid\fR, in fact, time out. Otherwise |
|
|
1577 | the callback was invoked too early (\f(CW\*(C`timeout\*(C'\fR is in the future), so |
|
|
1578 | re-schedule the timer to fire at that future time, to see if maybe we have |
|
|
1579 | a timeout then. |
|
|
1580 | .Sp |
|
|
1581 | Note 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 |
|
|
1584 | This scheme causes more callback invocations (about one every 60 seconds |
|
|
1585 | minus half the average time between activity), but virtually no calls to |
|
|
1586 | libev to change the timeout. |
|
|
1587 | .Sp |
|
|
1588 | To start the timer, simply initialise the watcher and set \f(CW\*(C`last_activity\*(C'\fR |
|
|
1589 | to the current time (meaning we just have some activity :), then call the |
|
|
1590 | callback, 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 |
|
|
1598 | And 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 |
|
|
1605 | This technique is slightly more complex, but in most cases where the |
|
|
1606 | time-out is unlikely to be triggered, much more efficient. |
|
|
1607 | .Sp |
|
|
1608 | Changing the timeout is trivial as well (if it isn't hard-coded in the |
|
|
1609 | callback :) \- just change the timeout and invoke the callback, which will |
|
|
1610 | fix 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." |
|
|
1613 | If there is not one request, but many thousands (millions...), all |
|
|
1614 | employing some kind of timeout with the same timeout value, then one can |
|
|
1615 | do even better: |
|
|
1616 | .Sp |
|
|
1617 | When starting the timeout, calculate the timeout value and put the timeout |
|
|
1618 | at the \fIend\fR of the list. |
|
|
1619 | .Sp |
|
|
1620 | Then use an \f(CW\*(C`ev_timer\*(C'\fR to fire when the timeout at the \fIbeginning\fR of |
|
|
1621 | the list is expected to fire (for example, using the technique #3). |
|
|
1622 | .Sp |
|
|
1623 | When there is some activity, remove the timer from the list, recalculate |
|
|
1624 | the timeout, append it to the end of the list again, and make sure to |
|
|
1625 | update the \f(CW\*(C`ev_timer\*(C'\fR if it was taken from the beginning of the list. |
|
|
1626 | .Sp |
|
|
1627 | This way, one can manage an unlimited number of timeouts in O(1) time for |
|
|
1628 | starting, stopping and updating the timers, at the expense of a major |
|
|
1629 | complication, and having to use a constant timeout. The constant timeout |
|
|
1630 | ensures that the list stays sorted. |
|
|
1631 | .PP |
|
|
1632 | So which method the best? |
|
|
1633 | .PP |
|
|
1634 | Method #2 is a simple no-brain-required solution that is adequate in most |
|
|
1635 | situations. Method #3 requires a bit more thinking, but handles many cases |
|
|
1636 | better, and isn't very complicated either. In most case, choosing either |
|
|
1637 | one is fine, with #3 being better in typical situations. |
|
|
1638 | .PP |
|
|
1639 | Method #1 is almost always a bad idea, and buys you nothing. Method #4 is |
|
|
1640 | rather complicated, but extremely efficient, something that really pays |
|
|
1641 | off after the first million or so of active timers, i.e. it's usually |
|
|
1642 | overkill :) |
1416 | .PP |
1643 | .PP |
1417 | \fIThe special problem of time updates\fR |
1644 | \fIThe special problem of time updates\fR |
1418 | .IX Subsection "The special problem of time updates" |
1645 | .IX Subsection "The special problem of time updates" |
1419 | .PP |
1646 | .PP |
1420 | Establishing the current time is a costly operation (it usually takes at |
1647 | Establishing the current time is a costly operation (it usually takes at |
… | |
… | |
1466 | If the timer is started but non-repeating, stop it (as if it timed out). |
1693 | If the timer is started but non-repeating, stop it (as if it timed out). |
1467 | .Sp |
1694 | .Sp |
1468 | If the timer is repeating, either start it if necessary (with the |
1695 | If the timer is repeating, either start it if necessary (with the |
1469 | \&\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. |
1470 | .Sp |
1697 | .Sp |
1471 | This sounds a bit complicated, but here is a useful and typical |
1698 | This sounds a bit complicated, see \*(L"Be smart about timeouts\*(R", above, for a |
1472 | example: Imagine you have a \s-1TCP\s0 connection and you want a so-called idle |
1699 | usage example. |
1473 | timeout, that is, you want to be called when there have been, say, 60 |
|
|
1474 | seconds of inactivity on the socket. The easiest way to do this is to |
|
|
1475 | 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 |
|
|
1476 | \&\f(CW\*(C`ev_timer_again\*(C'\fR each time you successfully read or write some data. If |
|
|
1477 | you go into an idle state where you do not expect data to travel on the |
|
|
1478 | socket, you can \f(CW\*(C`ev_timer_stop\*(C'\fR the timer, and \f(CW\*(C`ev_timer_again\*(C'\fR will |
|
|
1479 | automatically restart it if need be. |
|
|
1480 | .Sp |
|
|
1481 | That means you can ignore the \f(CW\*(C`after\*(C'\fR value and \f(CW\*(C`ev_timer_start\*(C'\fR |
|
|
1482 | altogether and only ever use the \f(CW\*(C`repeat\*(C'\fR value and \f(CW\*(C`ev_timer_again\*(C'\fR: |
|
|
1483 | .Sp |
|
|
1484 | .Vb 8 |
|
|
1485 | \& ev_timer_init (timer, callback, 0., 5.); |
|
|
1486 | \& ev_timer_again (loop, timer); |
|
|
1487 | \& ... |
|
|
1488 | \& timer\->again = 17.; |
|
|
1489 | \& ev_timer_again (loop, timer); |
|
|
1490 | \& ... |
|
|
1491 | \& timer\->again = 10.; |
|
|
1492 | \& ev_timer_again (loop, timer); |
|
|
1493 | .Ve |
|
|
1494 | .Sp |
|
|
1495 | This is more slightly efficient then stopping/starting the timer each time |
|
|
1496 | you want to modify its timeout value. |
|
|
1497 | .Sp |
|
|
1498 | Note, however, that it is often even more efficient to remember the |
|
|
1499 | time of the last activity and let the timer time-out naturally. In the |
|
|
1500 | callback, you then check whether the time-out is real, or, if there was |
|
|
1501 | some activity, you reschedule the watcher to time-out in \*(L"last_activity + |
|
|
1502 | timeout \- ev_now ()\*(R" seconds. |
|
|
1503 | .IP "ev_tstamp repeat [read\-write]" 4 |
1700 | .IP "ev_tstamp repeat [read\-write]" 4 |
1504 | .IX Item "ev_tstamp repeat [read-write]" |
1701 | .IX Item "ev_tstamp repeat [read-write]" |
1505 | The current \f(CW\*(C`repeat\*(C'\fR value. Will be used each time the watcher times out |
1702 | The current \f(CW\*(C`repeat\*(C'\fR value. Will be used each time the watcher times out |
1506 | or \f(CW\*(C`ev_timer_again\*(C'\fR is called, and determines the next timeout (if any), |
1703 | or \f(CW\*(C`ev_timer_again\*(C'\fR is called, and determines the next timeout (if any), |
1507 | which is also when any modifications are taken into account. |
1704 | which is also when any modifications are taken into account. |
… | |
… | |
1511 | .PP |
1708 | .PP |
1512 | Example: Create a timer that fires after 60 seconds. |
1709 | Example: Create a timer that fires after 60 seconds. |
1513 | .PP |
1710 | .PP |
1514 | .Vb 5 |
1711 | .Vb 5 |
1515 | \& static void |
1712 | \& static void |
1516 | \& 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) |
1517 | \& { |
1714 | \& { |
1518 | \& .. one minute over, w is actually stopped right here |
1715 | \& .. one minute over, w is actually stopped right here |
1519 | \& } |
1716 | \& } |
1520 | \& |
1717 | \& |
1521 | \& struct ev_timer mytimer; |
1718 | \& ev_timer mytimer; |
1522 | \& ev_timer_init (&mytimer, one_minute_cb, 60., 0.); |
1719 | \& ev_timer_init (&mytimer, one_minute_cb, 60., 0.); |
1523 | \& ev_timer_start (loop, &mytimer); |
1720 | \& ev_timer_start (loop, &mytimer); |
1524 | .Ve |
1721 | .Ve |
1525 | .PP |
1722 | .PP |
1526 | Example: Create a timeout timer that times out after 10 seconds of |
1723 | Example: Create a timeout timer that times out after 10 seconds of |
1527 | inactivity. |
1724 | inactivity. |
1528 | .PP |
1725 | .PP |
1529 | .Vb 5 |
1726 | .Vb 5 |
1530 | \& static void |
1727 | \& static void |
1531 | \& timeout_cb (struct ev_loop *loop, struct ev_timer *w, int revents) |
1728 | \& timeout_cb (struct ev_loop *loop, ev_timer *w, int revents) |
1532 | \& { |
1729 | \& { |
1533 | \& .. ten seconds without any activity |
1730 | \& .. ten seconds without any activity |
1534 | \& } |
1731 | \& } |
1535 | \& |
1732 | \& |
1536 | \& struct ev_timer mytimer; |
1733 | \& ev_timer mytimer; |
1537 | \& 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 */ |
1538 | \& ev_timer_again (&mytimer); /* start timer */ |
1735 | \& ev_timer_again (&mytimer); /* start timer */ |
1539 | \& ev_loop (loop, 0); |
1736 | \& ev_loop (loop, 0); |
1540 | \& |
1737 | \& |
1541 | \& // 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": |
… | |
… | |
1628 | .Sp |
1825 | .Sp |
1629 | If you need to stop it, return \f(CW\*(C`now + 1e30\*(C'\fR (or so, fudge fudge) and stop |
1826 | If you need to stop it, return \f(CW\*(C`now + 1e30\*(C'\fR (or so, fudge fudge) and stop |
1630 | it afterwards (e.g. by starting an \f(CW\*(C`ev_prepare\*(C'\fR watcher, which is the |
1827 | it afterwards (e.g. by starting an \f(CW\*(C`ev_prepare\*(C'\fR watcher, which is the |
1631 | only event loop modification you are allowed to do). |
1828 | only event loop modification you are allowed to do). |
1632 | .Sp |
1829 | .Sp |
1633 | The callback prototype is \f(CW\*(C`ev_tstamp (*reschedule_cb)(struct ev_periodic |
1830 | The callback prototype is \f(CW\*(C`ev_tstamp (*reschedule_cb)(ev_periodic |
1634 | *w, ev_tstamp now)\*(C'\fR, e.g.: |
1831 | *w, ev_tstamp now)\*(C'\fR, e.g.: |
1635 | .Sp |
1832 | .Sp |
1636 | .Vb 4 |
1833 | .Vb 5 |
|
|
1834 | \& static ev_tstamp |
1637 | \& static ev_tstamp my_rescheduler (struct ev_periodic *w, ev_tstamp now) |
1835 | \& my_rescheduler (ev_periodic *w, ev_tstamp now) |
1638 | \& { |
1836 | \& { |
1639 | \& return now + 60.; |
1837 | \& return now + 60.; |
1640 | \& } |
1838 | \& } |
1641 | .Ve |
1839 | .Ve |
1642 | .Sp |
1840 | .Sp |
… | |
… | |
1676 | .IP "ev_tstamp interval [read\-write]" 4 |
1874 | .IP "ev_tstamp interval [read\-write]" 4 |
1677 | .IX Item "ev_tstamp interval [read-write]" |
1875 | .IX Item "ev_tstamp interval [read-write]" |
1678 | The current interval value. Can be modified any time, but changes only |
1876 | The current interval value. Can be modified any time, but changes only |
1679 | take effect when the periodic timer fires or \f(CW\*(C`ev_periodic_again\*(C'\fR is being |
1877 | take effect when the periodic timer fires or \f(CW\*(C`ev_periodic_again\*(C'\fR is being |
1680 | called. |
1878 | called. |
1681 | .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 |
1682 | .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]" |
1683 | The current reschedule callback, or \f(CW0\fR, if this functionality is |
1881 | The current reschedule callback, or \f(CW0\fR, if this functionality is |
1684 | switched off. Can be changed any time, but changes only take effect when |
1882 | switched off. Can be changed any time, but changes only take effect when |
1685 | the periodic timer fires or \f(CW\*(C`ev_periodic_again\*(C'\fR is being called. |
1883 | the periodic timer fires or \f(CW\*(C`ev_periodic_again\*(C'\fR is being called. |
1686 | .PP |
1884 | .PP |
1687 | \fIExamples\fR |
1885 | \fIExamples\fR |
… | |
… | |
1691 | system time is divisible by 3600. The callback invocation times have |
1889 | system time is divisible by 3600. The callback invocation times have |
1692 | potentially a lot of jitter, but good long-term stability. |
1890 | potentially a lot of jitter, but good long-term stability. |
1693 | .PP |
1891 | .PP |
1694 | .Vb 5 |
1892 | .Vb 5 |
1695 | \& static void |
1893 | \& static void |
1696 | \& clock_cb (struct ev_loop *loop, struct ev_io *w, int revents) |
1894 | \& clock_cb (struct ev_loop *loop, ev_io *w, int revents) |
1697 | \& { |
1895 | \& { |
1698 | \& ... 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) |
1699 | \& } |
1897 | \& } |
1700 | \& |
1898 | \& |
1701 | \& struct ev_periodic hourly_tick; |
1899 | \& ev_periodic hourly_tick; |
1702 | \& ev_periodic_init (&hourly_tick, clock_cb, 0., 3600., 0); |
1900 | \& ev_periodic_init (&hourly_tick, clock_cb, 0., 3600., 0); |
1703 | \& ev_periodic_start (loop, &hourly_tick); |
1901 | \& ev_periodic_start (loop, &hourly_tick); |
1704 | .Ve |
1902 | .Ve |
1705 | .PP |
1903 | .PP |
1706 | Example: The same as above, but use a reschedule callback to do it: |
1904 | Example: The same as above, but use a reschedule callback to do it: |
1707 | .PP |
1905 | .PP |
1708 | .Vb 1 |
1906 | .Vb 1 |
1709 | \& #include <math.h> |
1907 | \& #include <math.h> |
1710 | \& |
1908 | \& |
1711 | \& static ev_tstamp |
1909 | \& static ev_tstamp |
1712 | \& my_scheduler_cb (struct ev_periodic *w, ev_tstamp now) |
1910 | \& my_scheduler_cb (ev_periodic *w, ev_tstamp now) |
1713 | \& { |
1911 | \& { |
1714 | \& return now + (3600. \- fmod (now, 3600.)); |
1912 | \& return now + (3600. \- fmod (now, 3600.)); |
1715 | \& } |
1913 | \& } |
1716 | \& |
1914 | \& |
1717 | \& 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); |
1718 | .Ve |
1916 | .Ve |
1719 | .PP |
1917 | .PP |
1720 | Example: Call a callback every hour, starting now: |
1918 | Example: Call a callback every hour, starting now: |
1721 | .PP |
1919 | .PP |
1722 | .Vb 4 |
1920 | .Vb 4 |
1723 | \& struct ev_periodic hourly_tick; |
1921 | \& ev_periodic hourly_tick; |
1724 | \& ev_periodic_init (&hourly_tick, clock_cb, |
1922 | \& ev_periodic_init (&hourly_tick, clock_cb, |
1725 | \& fmod (ev_now (loop), 3600.), 3600., 0); |
1923 | \& fmod (ev_now (loop), 3600.), 3600., 0); |
1726 | \& ev_periodic_start (loop, &hourly_tick); |
1924 | \& ev_periodic_start (loop, &hourly_tick); |
1727 | .Ve |
1925 | .Ve |
1728 | .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!" |
… | |
… | |
1765 | The signal the watcher watches out for. |
1963 | The signal the watcher watches out for. |
1766 | .PP |
1964 | .PP |
1767 | \fIExamples\fR |
1965 | \fIExamples\fR |
1768 | .IX Subsection "Examples" |
1966 | .IX Subsection "Examples" |
1769 | .PP |
1967 | .PP |
1770 | Example: Try to exit cleanly on \s-1SIGINT\s0 and \s-1SIGTERM\s0. |
1968 | Example: Try to exit cleanly on \s-1SIGINT\s0. |
1771 | .PP |
1969 | .PP |
1772 | .Vb 5 |
1970 | .Vb 5 |
1773 | \& static void |
1971 | \& static void |
1774 | \& sigint_cb (struct ev_loop *loop, struct ev_signal *w, int revents) |
1972 | \& sigint_cb (struct ev_loop *loop, ev_signal *w, int revents) |
1775 | \& { |
1973 | \& { |
1776 | \& ev_unloop (loop, EVUNLOOP_ALL); |
1974 | \& ev_unloop (loop, EVUNLOOP_ALL); |
1777 | \& } |
1975 | \& } |
1778 | \& |
1976 | \& |
1779 | \& struct ev_signal signal_watcher; |
1977 | \& ev_signal signal_watcher; |
1780 | \& ev_signal_init (&signal_watcher, sigint_cb, SIGINT); |
1978 | \& ev_signal_init (&signal_watcher, sigint_cb, SIGINT); |
1781 | \& ev_signal_start (loop, &sigint_cb); |
1979 | \& ev_signal_start (loop, &signal_watcher); |
1782 | .Ve |
1980 | .Ve |
1783 | .ie n .Sh """ev_child"" \- watch out for process status changes" |
1981 | .ie n .Sh """ev_child"" \- watch out for process status changes" |
1784 | .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" |
1785 | .IX Subsection "ev_child - watch out for process status changes" |
1983 | .IX Subsection "ev_child - watch out for process status changes" |
1786 | Child watchers trigger when your process receives a \s-1SIGCHLD\s0 in response to |
1984 | Child watchers trigger when your process receives a \s-1SIGCHLD\s0 in response to |
… | |
… | |
1859 | .PP |
2057 | .PP |
1860 | .Vb 1 |
2058 | .Vb 1 |
1861 | \& ev_child cw; |
2059 | \& ev_child cw; |
1862 | \& |
2060 | \& |
1863 | \& static void |
2061 | \& static void |
1864 | \& child_cb (EV_P_ struct ev_child *w, int revents) |
2062 | \& child_cb (EV_P_ ev_child *w, int revents) |
1865 | \& { |
2063 | \& { |
1866 | \& ev_child_stop (EV_A_ w); |
2064 | \& ev_child_stop (EV_A_ w); |
1867 | \& 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); |
1868 | \& } |
2066 | \& } |
1869 | \& |
2067 | \& |
… | |
… | |
1884 | .Ve |
2082 | .Ve |
1885 | .ie n .Sh """ev_stat"" \- did the file attributes just change?" |
2083 | .ie n .Sh """ev_stat"" \- did the file attributes just change?" |
1886 | .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?" |
1887 | .IX Subsection "ev_stat - did the file attributes just change?" |
2085 | .IX Subsection "ev_stat - did the file attributes just change?" |
1888 | This watches a file system path for attribute changes. That is, it calls |
2086 | This watches a file system path for attribute changes. That is, it calls |
1889 | \&\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) |
1890 | compared to the last time, invoking the callback if it did. |
2088 | and sees if it changed compared to the last time, invoking the callback if |
|
|
2089 | it did. |
1891 | .PP |
2090 | .PP |
1892 | The path does not need to exist: changing from \*(L"path exists\*(R" to \*(L"path does |
2091 | The path does not need to exist: changing from \*(L"path exists\*(R" to \*(L"path does |
1893 | not exist\*(R" is a status change like any other. The condition \*(L"path does |
2092 | not exist\*(R" is a status change like any other. The condition \*(L"path does not |
1894 | not exist\*(R" is signified by the \f(CW\*(C`st_nlink\*(C'\fR field being zero (which is |
2093 | exist\*(R" (or more correctly \*(L"path cannot be stat'ed\*(R") is signified by the |
1895 | otherwise 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 |
1896 | the stat buffer having unspecified contents. |
2095 | least one) and all the other fields of the stat buffer having unspecified |
|
|
2096 | contents. |
1897 | .PP |
2097 | .PP |
1898 | The path \fIshould\fR be absolute and \fImust not\fR end in a slash. If it is |
2098 | The 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 |
1899 | relative and your working directory changes, the behaviour is undefined. |
2100 | your working directory changes, then the behaviour is undefined. |
1900 | .PP |
2101 | .PP |
1901 | Since there is no standard kernel interface to do this, the portable |
2102 | Since there is no portable change notification interface available, the |
1902 | implementation simply calls \f(CW\*(C`stat (2)\*(C'\fR regularly on the path to see if |
2103 | portable implementation simply calls \f(CWstat(2)\fR regularly on the path |
1903 | it changed somehow. You can specify a recommended polling interval for |
2104 | to see if it changed somehow. You can specify a recommended polling |
1904 | this case. If you specify a polling interval of \f(CW0\fR (highly recommended!) |
2105 | interval for this case. If you specify a polling interval of \f(CW0\fR (highly |
1905 | then a \fIsuitable, unspecified default\fR value will be used (which |
2106 | recommended!) then a \fIsuitable, unspecified default\fR value will be used |
1906 | you can expect to be around five seconds, although this might change |
2107 | (which you can expect to be around five seconds, although this might |
1907 | dynamically). Libev will also impose a minimum interval which is currently |
2108 | change dynamically). Libev will also impose a minimum interval which is |
1908 | around \f(CW0.1\fR, but thats usually overkill. |
2109 | currently around \f(CW0.1\fR, but that's usually overkill. |
1909 | .PP |
2110 | .PP |
1910 | This watcher type is not meant for massive numbers of stat watchers, |
2111 | This watcher type is not meant for massive numbers of stat watchers, |
1911 | as even with OS-supported change notifications, this can be |
2112 | as even with OS-supported change notifications, this can be |
1912 | resource-intensive. |
2113 | resource-intensive. |
1913 | .PP |
2114 | .PP |
1914 | At the time of this writing, the only OS-specific interface implemented |
2115 | At the time of this writing, the only OS-specific interface implemented |
1915 | is the Linux inotify interface (implementing kqueue support is left as |
2116 | is the Linux inotify interface (implementing kqueue support is left as an |
1916 | an exercise for the reader. Note, however, that the author sees no way |
2117 | exercise for the reader. Note, however, that the author sees no way of |
1917 | of implementing \f(CW\*(C`ev_stat\*(C'\fR semantics with kqueue). |
2118 | implementing \f(CW\*(C`ev_stat\*(C'\fR semantics with kqueue, except as a hint). |
1918 | .PP |
2119 | .PP |
1919 | \fI\s-1ABI\s0 Issues (Largefile Support)\fR |
2120 | \fI\s-1ABI\s0 Issues (Largefile Support)\fR |
1920 | .IX Subsection "ABI Issues (Largefile Support)" |
2121 | .IX Subsection "ABI Issues (Largefile Support)" |
1921 | .PP |
2122 | .PP |
1922 | Libev by default (unless the user overrides this) uses the default |
2123 | Libev by default (unless the user overrides this) uses the default |
… | |
… | |
1924 | support disabled by default, you get the 32 bit version of the stat |
2125 | support disabled by default, you get the 32 bit version of the stat |
1925 | structure. When using the library from programs that change the \s-1ABI\s0 to |
2126 | structure. When using the library from programs that change the \s-1ABI\s0 to |
1926 | use 64 bit file offsets the programs will fail. In that case you have to |
2127 | use 64 bit file offsets the programs will fail. In that case you have to |
1927 | compile libev with the same flags to get binary compatibility. This is |
2128 | compile libev with the same flags to get binary compatibility. This is |
1928 | obviously the case with any flags that change the \s-1ABI\s0, but the problem is |
2129 | obviously the case with any flags that change the \s-1ABI\s0, but the problem is |
1929 | most noticeably disabled with ev_stat and large file support. |
2130 | most noticeably displayed with ev_stat and large file support. |
1930 | .PP |
2131 | .PP |
1931 | The solution for this is to lobby your distribution maker to make large |
2132 | The solution for this is to lobby your distribution maker to make large |
1932 | file interfaces available by default (as e.g. FreeBSD does) and not |
2133 | file interfaces available by default (as e.g. FreeBSD does) and not |
1933 | optional. Libev cannot simply switch on large file support because it has |
2134 | optional. Libev cannot simply switch on large file support because it has |
1934 | to exchange stat structures with application programs compiled using the |
2135 | to exchange stat structures with application programs compiled using the |
1935 | default compilation environment. |
2136 | default compilation environment. |
1936 | .PP |
2137 | .PP |
1937 | \fIInotify and Kqueue\fR |
2138 | \fIInotify and Kqueue\fR |
1938 | .IX Subsection "Inotify and Kqueue" |
2139 | .IX Subsection "Inotify and Kqueue" |
1939 | .PP |
2140 | .PP |
1940 | When \f(CW\*(C`inotify (7)\*(C'\fR support has been compiled into libev (generally only |
2141 | When \f(CW\*(C`inotify (7)\*(C'\fR support has been compiled into libev and present at |
1941 | available with Linux) and present at runtime, it will be used to speed up |
2142 | runtime, it will be used to speed up change detection where possible. The |
1942 | change detection where possible. The inotify descriptor will be created lazily |
2143 | inotify descriptor will be created lazily when the first \f(CW\*(C`ev_stat\*(C'\fR |
1943 | when the first \f(CW\*(C`ev_stat\*(C'\fR watcher is being started. |
2144 | watcher is being started. |
1944 | .PP |
2145 | .PP |
1945 | Inotify presence does not change the semantics of \f(CW\*(C`ev_stat\*(C'\fR watchers |
2146 | Inotify presence does not change the semantics of \f(CW\*(C`ev_stat\*(C'\fR watchers |
1946 | except that changes might be detected earlier, and in some cases, to avoid |
2147 | except that changes might be detected earlier, and in some cases, to avoid |
1947 | making regular \f(CW\*(C`stat\*(C'\fR calls. Even in the presence of inotify support |
2148 | making regular \f(CW\*(C`stat\*(C'\fR calls. Even in the presence of inotify support |
1948 | there are many cases where libev has to resort to regular \f(CW\*(C`stat\*(C'\fR polling, |
2149 | there are many cases where libev has to resort to regular \f(CW\*(C`stat\*(C'\fR polling, |
1949 | but as long as the path exists, libev usually gets away without polling. |
2150 | but as long as kernel 2.6.25 or newer is used (2.6.24 and older have too |
|
|
2151 | many bugs), the path exists (i.e. stat succeeds), and the path resides on |
|
|
2152 | a local filesystem (libev currently assumes only ext2/3, jfs, reiserfs and |
|
|
2153 | xfs are fully working) libev usually gets away without polling. |
1950 | .PP |
2154 | .PP |
1951 | There is no support for kqueue, as apparently it cannot be used to |
2155 | There is no support for kqueue, as apparently it cannot be used to |
1952 | implement this functionality, due to the requirement of having a file |
2156 | implement this functionality, due to the requirement of having a file |
1953 | descriptor open on the object at all times, and detecting renames, unlinks |
2157 | descriptor open on the object at all times, and detecting renames, unlinks |
1954 | etc. is difficult. |
2158 | etc. is difficult. |
1955 | .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 |
|
|
2163 | Libev doesn't normally do any kind of I/O itself, and so is not blocking |
|
|
2164 | the 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 |
|
|
2167 | For local paths, this usually doesn't matter: unless the system is very |
|
|
2168 | busy or the intervals between stat's are large, a stat call will be fast, |
|
|
2169 | as the path data is suually in memory already (except when starting the |
|
|
2170 | watcher). |
|
|
2171 | .PP |
|
|
2172 | For networked file systems, calling \f(CW\*(C`stat ()\*(C'\fR can block an indefinite |
|
|
2173 | time due to network issues, and even under good conditions, a stat call |
|
|
2174 | often takes multiple milliseconds. |
|
|
2175 | .PP |
|
|
2176 | Therefore, it is best to avoid using \f(CW\*(C`ev_stat\*(C'\fR watchers on networked |
|
|
2177 | paths, although this is fully supported by libev. |
|
|
2178 | .PP |
1956 | \fIThe special problem of stat time resolution\fR |
2179 | \fIThe special problem of stat time resolution\fR |
1957 | .IX Subsection "The special problem of stat time resolution" |
2180 | .IX Subsection "The special problem of stat time resolution" |
1958 | .PP |
2181 | .PP |
1959 | The \f(CW\*(C`stat ()\*(C'\fR system call only supports full-second resolution portably, and |
2182 | The \f(CW\*(C`stat ()\*(C'\fR system call only supports full-second resolution portably, |
1960 | even on systems where the resolution is higher, most file systems still |
2183 | and even on systems where the resolution is higher, most file systems |
1961 | only support whole seconds. |
2184 | still only support whole seconds. |
1962 | .PP |
2185 | .PP |
1963 | That means that, if the time is the only thing that changes, you can |
2186 | That means that, if the time is the only thing that changes, you can |
1964 | easily miss updates: on the first update, \f(CW\*(C`ev_stat\*(C'\fR detects a change and |
2187 | easily miss updates: on the first update, \f(CW\*(C`ev_stat\*(C'\fR detects a change and |
1965 | calls your callback, which does something. When there is another update |
2188 | calls your callback, which does something. When there is another update |
1966 | within the same second, \f(CW\*(C`ev_stat\*(C'\fR will be unable to detect unless the |
2189 | within the same second, \f(CW\*(C`ev_stat\*(C'\fR will be unable to detect unless the |
… | |
… | |
2118 | Example: Dynamically allocate an \f(CW\*(C`ev_idle\*(C'\fR watcher, start it, and in the |
2341 | Example: Dynamically allocate an \f(CW\*(C`ev_idle\*(C'\fR watcher, start it, and in the |
2119 | callback, free it. Also, use no error checking, as usual. |
2342 | callback, free it. Also, use no error checking, as usual. |
2120 | .PP |
2343 | .PP |
2121 | .Vb 7 |
2344 | .Vb 7 |
2122 | \& static void |
2345 | \& static void |
2123 | \& idle_cb (struct ev_loop *loop, struct ev_idle *w, int revents) |
2346 | \& idle_cb (struct ev_loop *loop, ev_idle *w, int revents) |
2124 | \& { |
2347 | \& { |
2125 | \& free (w); |
2348 | \& free (w); |
2126 | \& // now do something you wanted to do when the program has |
2349 | \& // now do something you wanted to do when the program has |
2127 | \& // no longer anything immediate to do. |
2350 | \& // no longer anything immediate to do. |
2128 | \& } |
2351 | \& } |
2129 | \& |
2352 | \& |
2130 | \& struct ev_idle *idle_watcher = malloc (sizeof (struct ev_idle)); |
2353 | \& ev_idle *idle_watcher = malloc (sizeof (ev_idle)); |
2131 | \& ev_idle_init (idle_watcher, idle_cb); |
2354 | \& ev_idle_init (idle_watcher, idle_cb); |
2132 | \& ev_idle_start (loop, idle_cb); |
2355 | \& ev_idle_start (loop, idle_cb); |
2133 | .Ve |
2356 | .Ve |
2134 | .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!" |
2135 | .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!" |
… | |
… | |
2216 | .Vb 2 |
2439 | .Vb 2 |
2217 | \& static ev_io iow [nfd]; |
2440 | \& static ev_io iow [nfd]; |
2218 | \& static ev_timer tw; |
2441 | \& static ev_timer tw; |
2219 | \& |
2442 | \& |
2220 | \& static void |
2443 | \& static void |
2221 | \& io_cb (ev_loop *loop, ev_io *w, int revents) |
2444 | \& io_cb (struct ev_loop *loop, ev_io *w, int revents) |
2222 | \& { |
2445 | \& { |
2223 | \& } |
2446 | \& } |
2224 | \& |
2447 | \& |
2225 | \& // create io watchers for each fd and a timer before blocking |
2448 | \& // create io watchers for each fd and a timer before blocking |
2226 | \& static void |
2449 | \& static void |
2227 | \& adns_prepare_cb (ev_loop *loop, ev_prepare *w, int revents) |
2450 | \& adns_prepare_cb (struct ev_loop *loop, ev_prepare *w, int revents) |
2228 | \& { |
2451 | \& { |
2229 | \& int timeout = 3600000; |
2452 | \& int timeout = 3600000; |
2230 | \& struct pollfd fds [nfd]; |
2453 | \& struct pollfd fds [nfd]; |
2231 | \& // actual code will need to loop here and realloc etc. |
2454 | \& // actual code will need to loop here and realloc etc. |
2232 | \& adns_beforepoll (ads, fds, &nfd, &timeout, timeval_from (ev_time ())); |
2455 | \& adns_beforepoll (ads, fds, &nfd, &timeout, timeval_from (ev_time ())); |
… | |
… | |
2247 | \& } |
2470 | \& } |
2248 | \& } |
2471 | \& } |
2249 | \& |
2472 | \& |
2250 | \& // stop all watchers after blocking |
2473 | \& // stop all watchers after blocking |
2251 | \& static void |
2474 | \& static void |
2252 | \& adns_check_cb (ev_loop *loop, ev_check *w, int revents) |
2475 | \& adns_check_cb (struct ev_loop *loop, ev_check *w, int revents) |
2253 | \& { |
2476 | \& { |
2254 | \& ev_timer_stop (loop, &tw); |
2477 | \& ev_timer_stop (loop, &tw); |
2255 | \& |
2478 | \& |
2256 | \& for (int i = 0; i < nfd; ++i) |
2479 | \& for (int i = 0; i < nfd; ++i) |
2257 | \& { |
2480 | \& { |
… | |
… | |
2428 | used). |
2651 | used). |
2429 | .PP |
2652 | .PP |
2430 | .Vb 3 |
2653 | .Vb 3 |
2431 | \& struct ev_loop *loop_hi = ev_default_init (0); |
2654 | \& struct ev_loop *loop_hi = ev_default_init (0); |
2432 | \& struct ev_loop *loop_lo = 0; |
2655 | \& struct ev_loop *loop_lo = 0; |
2433 | \& struct ev_embed embed; |
2656 | \& ev_embed embed; |
2434 | \& |
2657 | \& |
2435 | \& // see if there is a chance of getting one that works |
2658 | \& // see if there is a chance of getting one that works |
2436 | \& // (remember that a flags value of 0 means autodetection) |
2659 | \& // (remember that a flags value of 0 means autodetection) |
2437 | \& loop_lo = ev_embeddable_backends () & ev_recommended_backends () |
2660 | \& loop_lo = ev_embeddable_backends () & ev_recommended_backends () |
2438 | \& ? ev_loop_new (ev_embeddable_backends () & ev_recommended_backends ()) |
2661 | \& ? ev_loop_new (ev_embeddable_backends () & ev_recommended_backends ()) |
… | |
… | |
2454 | \&\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). |
2455 | .PP |
2678 | .PP |
2456 | .Vb 3 |
2679 | .Vb 3 |
2457 | \& struct ev_loop *loop = ev_default_init (0); |
2680 | \& struct ev_loop *loop = ev_default_init (0); |
2458 | \& struct ev_loop *loop_socket = 0; |
2681 | \& struct ev_loop *loop_socket = 0; |
2459 | \& struct ev_embed embed; |
2682 | \& ev_embed embed; |
2460 | \& |
2683 | \& |
2461 | \& if (ev_supported_backends () & ~ev_recommended_backends () & EVBACKEND_KQUEUE) |
2684 | \& if (ev_supported_backends () & ~ev_recommended_backends () & EVBACKEND_KQUEUE) |
2462 | \& if ((loop_socket = ev_loop_new (EVBACKEND_KQUEUE)) |
2685 | \& if ((loop_socket = ev_loop_new (EVBACKEND_KQUEUE)) |
2463 | \& { |
2686 | \& { |
2464 | \& ev_embed_init (&embed, 0, loop_socket); |
2687 | \& ev_embed_init (&embed, 0, loop_socket); |
… | |
… | |
2521 | queue. But at least I can tell you how to implement locking around your |
2744 | queue. But at least I can tell you how to implement locking around your |
2522 | queue: |
2745 | queue: |
2523 | .IP "queueing from a signal handler context" 4 |
2746 | .IP "queueing from a signal handler context" 4 |
2524 | .IX Item "queueing from a signal handler context" |
2747 | .IX Item "queueing from a signal handler context" |
2525 | To implement race-free queueing, you simply add to the queue in the signal |
2748 | To implement race-free queueing, you simply add to the queue in the signal |
2526 | handler but you block the signal handler in the watcher callback. Here is an example that does that for |
2749 | handler but you block the signal handler in the watcher callback. Here is |
2527 | some fictitious \s-1SIGUSR1\s0 handler: |
2750 | an example that does that for some fictitious \s-1SIGUSR1\s0 handler: |
2528 | .Sp |
2751 | .Sp |
2529 | .Vb 1 |
2752 | .Vb 1 |
2530 | \& static ev_async mysig; |
2753 | \& static ev_async mysig; |
2531 | \& |
2754 | \& |
2532 | \& static void |
2755 | \& static void |
… | |
… | |
2596 | \fIWatcher-Specific Functions and Data Members\fR |
2819 | \fIWatcher-Specific Functions and Data Members\fR |
2597 | .IX Subsection "Watcher-Specific Functions and Data Members" |
2820 | .IX Subsection "Watcher-Specific Functions and Data Members" |
2598 | .IP "ev_async_init (ev_async *, callback)" 4 |
2821 | .IP "ev_async_init (ev_async *, callback)" 4 |
2599 | .IX Item "ev_async_init (ev_async *, callback)" |
2822 | .IX Item "ev_async_init (ev_async *, callback)" |
2600 | Initialises and configures the async watcher \- it has no parameters of any |
2823 | Initialises and configures the async watcher \- it has no parameters of any |
2601 | kind. There is a \f(CW\*(C`ev_asynd_set\*(C'\fR macro, but using it is utterly pointless, |
2824 | kind. There is a \f(CW\*(C`ev_async_set\*(C'\fR macro, but using it is utterly pointless, |
2602 | trust me. |
2825 | trust me. |
2603 | .IP "ev_async_send (loop, ev_async *)" 4 |
2826 | .IP "ev_async_send (loop, ev_async *)" 4 |
2604 | .IX Item "ev_async_send (loop, ev_async *)" |
2827 | .IX Item "ev_async_send (loop, ev_async *)" |
2605 | Sends/signals/activates the given \f(CW\*(C`ev_async\*(C'\fR watcher, that is, feeds |
2828 | Sends/signals/activates the given \f(CW\*(C`ev_async\*(C'\fR watcher, that is, feeds |
2606 | an \f(CW\*(C`EV_ASYNC\*(C'\fR event on the watcher into the event loop. Unlike |
2829 | an \f(CW\*(C`EV_ASYNC\*(C'\fR event on the watcher into the event loop. Unlike |
… | |
… | |
2628 | .IX Header "OTHER FUNCTIONS" |
2851 | .IX Header "OTHER FUNCTIONS" |
2629 | There are some other functions of possible interest. Described. Here. Now. |
2852 | There are some other functions of possible interest. Described. Here. Now. |
2630 | .IP "ev_once (loop, int fd, int events, ev_tstamp timeout, callback)" 4 |
2853 | .IP "ev_once (loop, int fd, int events, ev_tstamp timeout, callback)" 4 |
2631 | .IX Item "ev_once (loop, int fd, int events, ev_tstamp timeout, callback)" |
2854 | .IX Item "ev_once (loop, int fd, int events, ev_tstamp timeout, callback)" |
2632 | This function combines a simple timer and an I/O watcher, calls your |
2855 | This function combines a simple timer and an I/O watcher, calls your |
2633 | callback on whichever event happens first and automatically stop both |
2856 | callback on whichever event happens first and automatically stops both |
2634 | watchers. This is useful if you want to wait for a single event on an fd |
2857 | watchers. This is useful if you want to wait for a single event on an fd |
2635 | or timeout without having to allocate/configure/start/stop/free one or |
2858 | or timeout without having to allocate/configure/start/stop/free one or |
2636 | more watchers yourself. |
2859 | more watchers yourself. |
2637 | .Sp |
2860 | .Sp |
2638 | If \f(CW\*(C`fd\*(C'\fR is less than 0, then no I/O watcher will be started and events |
2861 | If \f(CW\*(C`fd\*(C'\fR is less than 0, then no I/O watcher will be started and the |
2639 | is being ignored. Otherwise, an \f(CW\*(C`ev_io\*(C'\fR watcher for the given \f(CW\*(C`fd\*(C'\fR and |
2862 | \&\f(CW\*(C`events\*(C'\fR argument is being ignored. Otherwise, an \f(CW\*(C`ev_io\*(C'\fR watcher for |
2640 | \&\f(CW\*(C`events\*(C'\fR set will be created and started. |
2863 | the given \f(CW\*(C`fd\*(C'\fR and \f(CW\*(C`events\*(C'\fR set will be created and started. |
2641 | .Sp |
2864 | .Sp |
2642 | If \f(CW\*(C`timeout\*(C'\fR is less than 0, then no timeout watcher will be |
2865 | If \f(CW\*(C`timeout\*(C'\fR is less than 0, then no timeout watcher will be |
2643 | started. Otherwise an \f(CW\*(C`ev_timer\*(C'\fR watcher with after = \f(CW\*(C`timeout\*(C'\fR (and |
2866 | started. Otherwise an \f(CW\*(C`ev_timer\*(C'\fR watcher with after = \f(CW\*(C`timeout\*(C'\fR (and |
2644 | repeat = 0) will be started. While \f(CW0\fR is a valid timeout, it is of |
2867 | repeat = 0) will be started. \f(CW0\fR is a valid timeout. |
2645 | dubious value. |
|
|
2646 | .Sp |
2868 | .Sp |
2647 | The callback has the type \f(CW\*(C`void (*cb)(int revents, void *arg)\*(C'\fR and gets |
2869 | The callback has the type \f(CW\*(C`void (*cb)(int revents, void *arg)\*(C'\fR and gets |
2648 | passed an \f(CW\*(C`revents\*(C'\fR set like normal event callbacks (a combination of |
2870 | passed an \f(CW\*(C`revents\*(C'\fR set like normal event callbacks (a combination of |
2649 | \&\f(CW\*(C`EV_ERROR\*(C'\fR, \f(CW\*(C`EV_READ\*(C'\fR, \f(CW\*(C`EV_WRITE\*(C'\fR or \f(CW\*(C`EV_TIMEOUT\*(C'\fR) and the \f(CW\*(C`arg\*(C'\fR |
2871 | \&\f(CW\*(C`EV_ERROR\*(C'\fR, \f(CW\*(C`EV_READ\*(C'\fR, \f(CW\*(C`EV_WRITE\*(C'\fR or \f(CW\*(C`EV_TIMEOUT\*(C'\fR) and the \f(CW\*(C`arg\*(C'\fR |
2650 | value passed to \f(CW\*(C`ev_once\*(C'\fR: |
2872 | value passed to \f(CW\*(C`ev_once\*(C'\fR. Note that it is possible to receive \fIboth\fR |
|
|
2873 | a timeout and an io event at the same time \- you probably should give io |
|
|
2874 | events precedence. |
|
|
2875 | .Sp |
|
|
2876 | Example: wait up to ten seconds for data to appear on \s-1STDIN_FILENO\s0. |
2651 | .Sp |
2877 | .Sp |
2652 | .Vb 7 |
2878 | .Vb 7 |
2653 | \& static void stdin_ready (int revents, void *arg) |
2879 | \& static void stdin_ready (int revents, void *arg) |
2654 | \& { |
2880 | \& { |
|
|
2881 | \& if (revents & EV_READ) |
|
|
2882 | \& /* stdin might have data for us, joy! */; |
2655 | \& if (revents & EV_TIMEOUT) |
2883 | \& else if (revents & EV_TIMEOUT) |
2656 | \& /* doh, nothing entered */; |
2884 | \& /* doh, nothing entered */; |
2657 | \& else if (revents & EV_READ) |
|
|
2658 | \& /* stdin might have data for us, joy! */; |
|
|
2659 | \& } |
2885 | \& } |
2660 | \& |
2886 | \& |
2661 | \& ev_once (STDIN_FILENO, EV_READ, 10., stdin_ready, 0); |
2887 | \& ev_once (STDIN_FILENO, EV_READ, 10., stdin_ready, 0); |
2662 | .Ve |
2888 | .Ve |
2663 | .IP "ev_feed_event (ev_loop *, watcher *, int revents)" 4 |
2889 | .IP "ev_feed_event (struct ev_loop *, watcher *, int revents)" 4 |
2664 | .IX Item "ev_feed_event (ev_loop *, watcher *, int revents)" |
2890 | .IX Item "ev_feed_event (struct ev_loop *, watcher *, int revents)" |
2665 | Feeds the given event set into the event loop, as if the specified event |
2891 | Feeds the given event set into the event loop, as if the specified event |
2666 | had happened for the specified watcher (which must be a pointer to an |
2892 | had happened for the specified watcher (which must be a pointer to an |
2667 | initialised but not necessarily started event watcher). |
2893 | initialised but not necessarily started event watcher). |
2668 | .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 |
2669 | .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)" |
2670 | Feed an event on the given fd, as if a file descriptor backend detected |
2896 | Feed an event on the given fd, as if a file descriptor backend detected |
2671 | the given events it. |
2897 | the given events it. |
2672 | .IP "ev_feed_signal_event (ev_loop *loop, int signum)" 4 |
2898 | .IP "ev_feed_signal_event (struct ev_loop *loop, int signum)" 4 |
2673 | .IX Item "ev_feed_signal_event (ev_loop *loop, int signum)" |
2899 | .IX Item "ev_feed_signal_event (struct ev_loop *loop, int signum)" |
2674 | Feed an event as if the given signal occurred (\f(CW\*(C`loop\*(C'\fR must be the default |
2900 | Feed an event as if the given signal occurred (\f(CW\*(C`loop\*(C'\fR must be the default |
2675 | loop!). |
2901 | loop!). |
2676 | .SH "LIBEVENT EMULATION" |
2902 | .SH "LIBEVENT EMULATION" |
2677 | .IX Header "LIBEVENT EMULATION" |
2903 | .IX Header "LIBEVENT EMULATION" |
2678 | Libev offers a compatibility emulation layer for libevent. It cannot |
2904 | Libev offers a compatibility emulation layer for libevent. It cannot |
… | |
… | |
2893 | <http://rev.rubyforge.org/>. |
3119 | <http://rev.rubyforge.org/>. |
2894 | .IP "D" 4 |
3120 | .IP "D" 4 |
2895 | .IX Item "D" |
3121 | .IX Item "D" |
2896 | Leandro Lucarella has written a D language binding (\fIev.d\fR) for libev, to |
3122 | Leandro Lucarella has written a D language binding (\fIev.d\fR) for libev, to |
2897 | be found at <http://proj.llucax.com.ar/wiki/evd>. |
3123 | be found at <http://proj.llucax.com.ar/wiki/evd>. |
|
|
3124 | .IP "Ocaml" 4 |
|
|
3125 | .IX Item "Ocaml" |
|
|
3126 | Erkki Seppala has written Ocaml bindings for libev, to be found at |
|
|
3127 | <http://modeemi.cs.tut.fi/~flux/software/ocaml\-ev/>. |
2898 | .SH "MACRO MAGIC" |
3128 | .SH "MACRO MAGIC" |
2899 | .IX Header "MACRO MAGIC" |
3129 | .IX Header "MACRO MAGIC" |
2900 | Libev can be compiled with a variety of options, the most fundamental |
3130 | Libev can be compiled with a variety of options, the most fundamental |
2901 | of which is \f(CW\*(C`EV_MULTIPLICITY\*(C'\fR. This option determines whether (most) |
3131 | of which is \f(CW\*(C`EV_MULTIPLICITY\*(C'\fR. This option determines whether (most) |
2902 | functions and callbacks have an initial \f(CW\*(C`struct ev_loop *\*(C'\fR argument. |
3132 | functions and callbacks have an initial \f(CW\*(C`struct ev_loop *\*(C'\fR argument. |
… | |
… | |
3004 | \& #define EV_STANDALONE 1 |
3234 | \& #define EV_STANDALONE 1 |
3005 | \& #include "ev.h" |
3235 | \& #include "ev.h" |
3006 | .Ve |
3236 | .Ve |
3007 | .PP |
3237 | .PP |
3008 | Both header files and implementation files can be compiled with a \*(C+ |
3238 | Both header files and implementation files can be compiled with a \*(C+ |
3009 | compiler (at least, thats a stated goal, and breakage will be treated |
3239 | compiler (at least, that's a stated goal, and breakage will be treated |
3010 | as a bug). |
3240 | as a bug). |
3011 | .PP |
3241 | .PP |
3012 | You need the following files in your source tree, or in a directory |
3242 | You need the following files in your source tree, or in a directory |
3013 | in your include path (e.g. in libev/ when using \-Ilibev): |
3243 | in your include path (e.g. in libev/ when using \-Ilibev): |
3014 | .PP |
3244 | .PP |
… | |
… | |
3398 | .PP |
3628 | .PP |
3399 | .Vb 2 |
3629 | .Vb 2 |
3400 | \& #include "ev_cpp.h" |
3630 | \& #include "ev_cpp.h" |
3401 | \& #include "ev.c" |
3631 | \& #include "ev.c" |
3402 | .Ve |
3632 | .Ve |
3403 | .SH "THREADS AND COROUTINES" |
3633 | .SH "INTERACTION WITH OTHER PROGRAMS OR LIBRARIES" |
|
|
3634 | .IX Header "INTERACTION WITH OTHER PROGRAMS OR LIBRARIES" |
|
|
3635 | .Sh "\s-1THREADS\s0 \s-1AND\s0 \s-1COROUTINES\s0" |
3404 | .IX Header "THREADS AND COROUTINES" |
3636 | .IX Subsection "THREADS AND COROUTINES" |
3405 | .Sh "\s-1THREADS\s0" |
3637 | \fI\s-1THREADS\s0\fR |
3406 | .IX Subsection "THREADS" |
3638 | .IX Subsection "THREADS" |
|
|
3639 | .PP |
3407 | All libev functions are reentrant and thread-safe unless explicitly |
3640 | All libev functions are reentrant and thread-safe unless explicitly |
3408 | documented otherwise, but it uses no locking itself. This means that you |
3641 | documented otherwise, but libev implements no locking itself. This means |
3409 | can use as many loops as you want in parallel, as long as there are no |
3642 | that you can use as many loops as you want in parallel, as long as there |
3410 | concurrent calls into any libev function with the same loop parameter |
3643 | are no concurrent calls into any libev function with the same loop |
3411 | (\f(CW\*(C`ev_default_*\*(C'\fR calls have an implicit default loop parameter, of |
3644 | parameter (\f(CW\*(C`ev_default_*\*(C'\fR calls have an implicit default loop parameter, |
3412 | course): libev guarantees that different event loops share no data |
3645 | of course): libev guarantees that different event loops share no data |
3413 | structures that need any locking. |
3646 | structures that need any locking. |
3414 | .PP |
3647 | .PP |
3415 | Or to put it differently: calls with different loop parameters can be done |
3648 | Or to put it differently: calls with different loop parameters can be done |
3416 | concurrently from multiple threads, calls with the same loop parameter |
3649 | concurrently from multiple threads, calls with the same loop parameter |
3417 | must be done serially (but can be done from different threads, as long as |
3650 | must be done serially (but can be done from different threads, as long as |
… | |
… | |
3452 | .Sp |
3685 | .Sp |
3453 | An example use would be to communicate signals or other events that only |
3686 | An example use would be to communicate signals or other events that only |
3454 | work in the default loop by registering the signal watcher with the |
3687 | work in the default loop by registering the signal watcher with the |
3455 | default loop and triggering an \f(CW\*(C`ev_async\*(C'\fR watcher from the default loop |
3688 | default loop and triggering an \f(CW\*(C`ev_async\*(C'\fR watcher from the default loop |
3456 | watcher callback into the event loop interested in the signal. |
3689 | watcher callback into the event loop interested in the signal. |
3457 | .Sh "\s-1COROUTINES\s0" |
3690 | .PP |
|
|
3691 | \fI\s-1COROUTINES\s0\fR |
3458 | .IX Subsection "COROUTINES" |
3692 | .IX Subsection "COROUTINES" |
|
|
3693 | .PP |
3459 | Libev is much more accommodating to coroutines (\*(L"cooperative threads\*(R"): |
3694 | Libev is very accommodating to coroutines (\*(L"cooperative threads\*(R"): |
3460 | libev fully supports nesting calls to it's functions from different |
3695 | libev fully supports nesting calls to its functions from different |
3461 | coroutines (e.g. you can call \f(CW\*(C`ev_loop\*(C'\fR on the same loop from two |
3696 | coroutines (e.g. you can call \f(CW\*(C`ev_loop\*(C'\fR on the same loop from two |
3462 | different coroutines and switch freely between both coroutines running the |
3697 | different coroutines, and switch freely between both coroutines running the |
3463 | loop, as long as you don't confuse yourself). The only exception is that |
3698 | loop, as long as you don't confuse yourself). The only exception is that |
3464 | you must not do this from \f(CW\*(C`ev_periodic\*(C'\fR reschedule callbacks. |
3699 | you must not do this from \f(CW\*(C`ev_periodic\*(C'\fR reschedule callbacks. |
3465 | .PP |
3700 | .PP |
3466 | Care has been taken to ensure that libev does not keep local state inside |
3701 | Care has been taken to ensure that libev does not keep local state inside |
3467 | \&\f(CW\*(C`ev_loop\*(C'\fR, and other calls do not usually allow coroutine switches. |
3702 | \&\f(CW\*(C`ev_loop\*(C'\fR, and other calls do not usually allow for coroutine switches as |
|
|
3703 | they do not call any callbacks. |
|
|
3704 | .Sh "\s-1COMPILER\s0 \s-1WARNINGS\s0" |
|
|
3705 | .IX Subsection "COMPILER WARNINGS" |
|
|
3706 | Depending on your compiler and compiler settings, you might get no or a |
|
|
3707 | lot of warnings when compiling libev code. Some people are apparently |
|
|
3708 | scared by this. |
|
|
3709 | .PP |
|
|
3710 | However, these are unavoidable for many reasons. For one, each compiler |
|
|
3711 | has different warnings, and each user has different tastes regarding |
|
|
3712 | warning options. \*(L"Warn-free\*(R" code therefore cannot be a goal except when |
|
|
3713 | targeting a specific compiler and compiler-version. |
|
|
3714 | .PP |
|
|
3715 | Another reason is that some compiler warnings require elaborate |
|
|
3716 | workarounds, or other changes to the code that make it less clear and less |
|
|
3717 | maintainable. |
|
|
3718 | .PP |
|
|
3719 | And of course, some compiler warnings are just plain stupid, or simply |
|
|
3720 | wrong (because they don't actually warn about the condition their message |
|
|
3721 | seems to warn about). For example, certain older gcc versions had some |
|
|
3722 | warnings that resulted an extreme number of false positives. These have |
|
|
3723 | been fixed, but some people still insist on making code warn-free with |
|
|
3724 | such buggy versions. |
|
|
3725 | .PP |
|
|
3726 | While libev is written to generate as few warnings as possible, |
|
|
3727 | \&\*(L"warn-free\*(R" code is not a goal, and it is recommended not to build libev |
|
|
3728 | with any compiler warnings enabled unless you are prepared to cope with |
|
|
3729 | them (e.g. by ignoring them). Remember that warnings are just that: |
|
|
3730 | warnings, not errors, or proof of bugs. |
|
|
3731 | .Sh "\s-1VALGRIND\s0" |
|
|
3732 | .IX Subsection "VALGRIND" |
|
|
3733 | Valgrind has a special section here because it is a popular tool that is |
|
|
3734 | highly useful. Unfortunately, valgrind reports are very hard to interpret. |
|
|
3735 | .PP |
|
|
3736 | If you think you found a bug (memory leak, uninitialised data access etc.) |
|
|
3737 | in libev, then check twice: If valgrind reports something like: |
|
|
3738 | .PP |
|
|
3739 | .Vb 3 |
|
|
3740 | \& ==2274== definitely lost: 0 bytes in 0 blocks. |
|
|
3741 | \& ==2274== possibly lost: 0 bytes in 0 blocks. |
|
|
3742 | \& ==2274== still reachable: 256 bytes in 1 blocks. |
|
|
3743 | .Ve |
|
|
3744 | .PP |
|
|
3745 | Then there is no memory leak, just as memory accounted to global variables |
|
|
3746 | is not a memleak \- the memory is still being referenced, and didn't leak. |
|
|
3747 | .PP |
|
|
3748 | Similarly, under some circumstances, valgrind might report kernel bugs |
|
|
3749 | as if it were a bug in libev (e.g. in realloc or in the poll backend, |
|
|
3750 | although an acceptable workaround has been found here), or it might be |
|
|
3751 | confused. |
|
|
3752 | .PP |
|
|
3753 | Keep in mind that valgrind is a very good tool, but only a tool. Don't |
|
|
3754 | make it into some kind of religion. |
|
|
3755 | .PP |
|
|
3756 | If you are unsure about something, feel free to contact the mailing list |
|
|
3757 | with the full valgrind report and an explanation on why you think this |
|
|
3758 | is a bug in libev (best check the archives, too :). However, don't be |
|
|
3759 | annoyed when you get a brisk \*(L"this is no bug\*(R" answer and take the chance |
|
|
3760 | of learning how to interpret valgrind properly. |
|
|
3761 | .PP |
|
|
3762 | If you need, for some reason, empty reports from valgrind for your project |
|
|
3763 | I suggest using suppression lists. |
|
|
3764 | .SH "PORTABILITY NOTES" |
|
|
3765 | .IX Header "PORTABILITY NOTES" |
|
|
3766 | .Sh "\s-1WIN32\s0 \s-1PLATFORM\s0 \s-1LIMITATIONS\s0 \s-1AND\s0 \s-1WORKAROUNDS\s0" |
|
|
3767 | .IX Subsection "WIN32 PLATFORM LIMITATIONS AND WORKAROUNDS" |
|
|
3768 | Win32 doesn't support any of the standards (e.g. \s-1POSIX\s0) that libev |
|
|
3769 | requires, and its I/O model is fundamentally incompatible with the \s-1POSIX\s0 |
|
|
3770 | model. Libev still offers limited functionality on this platform in |
|
|
3771 | the form of the \f(CW\*(C`EVBACKEND_SELECT\*(C'\fR backend, and only supports socket |
|
|
3772 | descriptors. This only applies when using Win32 natively, not when using |
|
|
3773 | e.g. cygwin. |
|
|
3774 | .PP |
|
|
3775 | Lifting these limitations would basically require the full |
|
|
3776 | re-implementation of the I/O system. If you are into these kinds of |
|
|
3777 | things, then note that glib does exactly that for you in a very portable |
|
|
3778 | way (note also that glib is the slowest event library known to man). |
|
|
3779 | .PP |
|
|
3780 | There is no supported compilation method available on windows except |
|
|
3781 | embedding it into other applications. |
|
|
3782 | .PP |
|
|
3783 | Not a libev limitation but worth mentioning: windows apparently doesn't |
|
|
3784 | accept large writes: instead of resulting in a partial write, windows will |
|
|
3785 | either accept everything or return \f(CW\*(C`ENOBUFS\*(C'\fR if the buffer is too large, |
|
|
3786 | so make sure you only write small amounts into your sockets (less than a |
|
|
3787 | megabyte seems safe, but this apparently depends on the amount of memory |
|
|
3788 | available). |
|
|
3789 | .PP |
|
|
3790 | Due to the many, low, and arbitrary limits on the win32 platform and |
|
|
3791 | the abysmal performance of winsockets, using a large number of sockets |
|
|
3792 | is not recommended (and not reasonable). If your program needs to use |
|
|
3793 | more than a hundred or so sockets, then likely it needs to use a totally |
|
|
3794 | different implementation for windows, as libev offers the \s-1POSIX\s0 readiness |
|
|
3795 | notification model, which cannot be implemented efficiently on windows |
|
|
3796 | (Microsoft monopoly games). |
|
|
3797 | .PP |
|
|
3798 | A typical way to use libev under windows is to embed it (see the embedding |
|
|
3799 | section for details) and use the following \fIevwrap.h\fR header file instead |
|
|
3800 | of \fIev.h\fR: |
|
|
3801 | .PP |
|
|
3802 | .Vb 2 |
|
|
3803 | \& #define EV_STANDALONE /* keeps ev from requiring config.h */ |
|
|
3804 | \& #define EV_SELECT_IS_WINSOCKET 1 /* configure libev for windows select */ |
|
|
3805 | \& |
|
|
3806 | \& #include "ev.h" |
|
|
3807 | .Ve |
|
|
3808 | .PP |
|
|
3809 | And compile the following \fIevwrap.c\fR file into your project (make sure |
|
|
3810 | you do \fInot\fR compile the \fIev.c\fR or any other embedded source files!): |
|
|
3811 | .PP |
|
|
3812 | .Vb 2 |
|
|
3813 | \& #include "evwrap.h" |
|
|
3814 | \& #include "ev.c" |
|
|
3815 | .Ve |
|
|
3816 | .IP "The winsocket select function" 4 |
|
|
3817 | .IX Item "The winsocket select function" |
|
|
3818 | The winsocket \f(CW\*(C`select\*(C'\fR function doesn't follow \s-1POSIX\s0 in that it |
|
|
3819 | requires socket \fIhandles\fR and not socket \fIfile descriptors\fR (it is |
|
|
3820 | also extremely buggy). This makes select very inefficient, and also |
|
|
3821 | requires a mapping from file descriptors to socket handles (the Microsoft |
|
|
3822 | C runtime provides the function \f(CW\*(C`_open_osfhandle\*(C'\fR for this). See the |
|
|
3823 | discussion of the \f(CW\*(C`EV_SELECT_USE_FD_SET\*(C'\fR, \f(CW\*(C`EV_SELECT_IS_WINSOCKET\*(C'\fR and |
|
|
3824 | \&\f(CW\*(C`EV_FD_TO_WIN32_HANDLE\*(C'\fR preprocessor symbols for more info. |
|
|
3825 | .Sp |
|
|
3826 | The configuration for a \*(L"naked\*(R" win32 using the Microsoft runtime |
|
|
3827 | libraries and raw winsocket select is: |
|
|
3828 | .Sp |
|
|
3829 | .Vb 2 |
|
|
3830 | \& #define EV_USE_SELECT 1 |
|
|
3831 | \& #define EV_SELECT_IS_WINSOCKET 1 /* forces EV_SELECT_USE_FD_SET, too */ |
|
|
3832 | .Ve |
|
|
3833 | .Sp |
|
|
3834 | Note that winsockets handling of fd sets is O(n), so you can easily get a |
|
|
3835 | complexity in the O(nA\*^X) range when using win32. |
|
|
3836 | .IP "Limited number of file descriptors" 4 |
|
|
3837 | .IX Item "Limited number of file descriptors" |
|
|
3838 | Windows has numerous arbitrary (and low) limits on things. |
|
|
3839 | .Sp |
|
|
3840 | Early versions of winsocket's select only supported waiting for a maximum |
|
|
3841 | of \f(CW64\fR handles (probably owning to the fact that all windows kernels |
|
|
3842 | can only wait for \f(CW64\fR things at the same time internally; Microsoft |
|
|
3843 | recommends spawning a chain of threads and wait for 63 handles and the |
|
|
3844 | previous thread in each. Great). |
|
|
3845 | .Sp |
|
|
3846 | Newer versions support more handles, but you need to define \f(CW\*(C`FD_SETSIZE\*(C'\fR |
|
|
3847 | to some high number (e.g. \f(CW2048\fR) before compiling the winsocket select |
|
|
3848 | call (which might be in libev or elsewhere, for example, perl does its own |
|
|
3849 | select emulation on windows). |
|
|
3850 | .Sp |
|
|
3851 | Another limit is the number of file descriptors in the Microsoft runtime |
|
|
3852 | libraries, which by default is \f(CW64\fR (there must be a hidden \fI64\fR fetish |
|
|
3853 | or something like this inside Microsoft). You can increase this by calling |
|
|
3854 | \&\f(CW\*(C`_setmaxstdio\*(C'\fR, which can increase this limit to \f(CW2048\fR (another |
|
|
3855 | arbitrary limit), but is broken in many versions of the Microsoft runtime |
|
|
3856 | libraries. |
|
|
3857 | .Sp |
|
|
3858 | This might get you to about \f(CW512\fR or \f(CW2048\fR sockets (depending on |
|
|
3859 | windows version and/or the phase of the moon). To get more, you need to |
|
|
3860 | wrap all I/O functions and provide your own fd management, but the cost of |
|
|
3861 | calling select (O(nA\*^X)) will likely make this unworkable. |
|
|
3862 | .Sh "\s-1PORTABILITY\s0 \s-1REQUIREMENTS\s0" |
|
|
3863 | .IX Subsection "PORTABILITY REQUIREMENTS" |
|
|
3864 | In addition to a working ISO-C implementation and of course the |
|
|
3865 | backend-specific APIs, libev relies on a few additional extensions: |
|
|
3866 | .ie n .IP """void (*)(ev_watcher_type *, int revents)""\fR must have compatible calling conventions regardless of \f(CW""ev_watcher_type *""." 4 |
|
|
3867 | .el .IP "\f(CWvoid (*)(ev_watcher_type *, int revents)\fR must have compatible calling conventions regardless of \f(CWev_watcher_type *\fR." 4 |
|
|
3868 | .IX Item "void (*)(ev_watcher_type *, int revents) must have compatible calling conventions regardless of ev_watcher_type *." |
|
|
3869 | Libev assumes not only that all watcher pointers have the same internal |
|
|
3870 | structure (guaranteed by \s-1POSIX\s0 but not by \s-1ISO\s0 C for example), but it also |
|
|
3871 | assumes that the same (machine) code can be used to call any watcher |
|
|
3872 | callback: The watcher callbacks have different type signatures, but libev |
|
|
3873 | calls them using an \f(CW\*(C`ev_watcher *\*(C'\fR internally. |
|
|
3874 | .ie n .IP """sig_atomic_t volatile"" must be thread-atomic as well" 4 |
|
|
3875 | .el .IP "\f(CWsig_atomic_t volatile\fR must be thread-atomic as well" 4 |
|
|
3876 | .IX Item "sig_atomic_t volatile must be thread-atomic as well" |
|
|
3877 | The type \f(CW\*(C`sig_atomic_t volatile\*(C'\fR (or whatever is defined as |
|
|
3878 | \&\f(CW\*(C`EV_ATOMIC_T\*(C'\fR) must be atomic with respect to accesses from different |
|
|
3879 | threads. This is not part of the specification for \f(CW\*(C`sig_atomic_t\*(C'\fR, but is |
|
|
3880 | believed to be sufficiently portable. |
|
|
3881 | .ie n .IP """sigprocmask"" must work in a threaded environment" 4 |
|
|
3882 | .el .IP "\f(CWsigprocmask\fR must work in a threaded environment" 4 |
|
|
3883 | .IX Item "sigprocmask must work in a threaded environment" |
|
|
3884 | Libev uses \f(CW\*(C`sigprocmask\*(C'\fR to temporarily block signals. This is not |
|
|
3885 | allowed in a threaded program (\f(CW\*(C`pthread_sigmask\*(C'\fR has to be used). Typical |
|
|
3886 | pthread implementations will either allow \f(CW\*(C`sigprocmask\*(C'\fR in the \*(L"main |
|
|
3887 | thread\*(R" or will block signals process-wide, both behaviours would |
|
|
3888 | be compatible with libev. Interaction between \f(CW\*(C`sigprocmask\*(C'\fR and |
|
|
3889 | \&\f(CW\*(C`pthread_sigmask\*(C'\fR could complicate things, however. |
|
|
3890 | .Sp |
|
|
3891 | The most portable way to handle signals is to block signals in all threads |
|
|
3892 | except the initial one, and run the default loop in the initial thread as |
|
|
3893 | well. |
|
|
3894 | .ie n .IP """long"" must be large enough for common memory allocation sizes" 4 |
|
|
3895 | .el .IP "\f(CWlong\fR must be large enough for common memory allocation sizes" 4 |
|
|
3896 | .IX Item "long must be large enough for common memory allocation sizes" |
|
|
3897 | To improve portability and simplify its \s-1API\s0, libev uses \f(CW\*(C`long\*(C'\fR internally |
|
|
3898 | instead of \f(CW\*(C`size_t\*(C'\fR when allocating its data structures. On non-POSIX |
|
|
3899 | systems (Microsoft...) this might be unexpectedly low, but is still at |
|
|
3900 | least 31 bits everywhere, which is enough for hundreds of millions of |
|
|
3901 | watchers. |
|
|
3902 | .ie n .IP """double"" must hold a time value in seconds with enough accuracy" 4 |
|
|
3903 | .el .IP "\f(CWdouble\fR must hold a time value in seconds with enough accuracy" 4 |
|
|
3904 | .IX Item "double must hold a time value in seconds with enough accuracy" |
|
|
3905 | The type \f(CW\*(C`double\*(C'\fR is used to represent timestamps. It is required to |
|
|
3906 | have at least 51 bits of mantissa (and 9 bits of exponent), which is good |
|
|
3907 | enough for at least into the year 4000. This requirement is fulfilled by |
|
|
3908 | implementations implementing \s-1IEEE\s0 754 (basically all existing ones). |
|
|
3909 | .PP |
|
|
3910 | If you know of other additional requirements drop me a note. |
3468 | .SH "COMPLEXITIES" |
3911 | .SH "ALGORITHMIC COMPLEXITIES" |
3469 | .IX Header "COMPLEXITIES" |
3912 | .IX Header "ALGORITHMIC COMPLEXITIES" |
3470 | In this section the complexities of (many of) the algorithms used inside |
3913 | In this section the complexities of (many of) the algorithms used inside |
3471 | libev will be explained. For complexity discussions about backends see the |
3914 | libev will be documented. For complexity discussions about backends see |
3472 | documentation for \f(CW\*(C`ev_default_init\*(C'\fR. |
3915 | the documentation for \f(CW\*(C`ev_default_init\*(C'\fR. |
3473 | .PP |
3916 | .PP |
3474 | All of the following are about amortised time: If an array needs to be |
3917 | All of the following are about amortised time: If an array needs to be |
3475 | extended, libev needs to realloc and move the whole array, but this |
3918 | extended, libev needs to realloc and move the whole array, but this |
3476 | happens asymptotically never with higher number of elements, so O(1) might |
3919 | happens asymptotically rarer with higher number of elements, so O(1) might |
3477 | mean it might do a lengthy realloc operation in rare cases, but on average |
3920 | mean that libev does a lengthy realloc operation in rare cases, but on |
3478 | it is much faster and asymptotically approaches constant time. |
3921 | average it is much faster and asymptotically approaches constant time. |
3479 | .IP "Starting and stopping timer/periodic watchers: O(log skipped_other_timers)" 4 |
3922 | .IP "Starting and stopping timer/periodic watchers: O(log skipped_other_timers)" 4 |
3480 | .IX Item "Starting and stopping timer/periodic watchers: O(log skipped_other_timers)" |
3923 | .IX Item "Starting and stopping timer/periodic watchers: O(log skipped_other_timers)" |
3481 | This means that, when you have a watcher that triggers in one hour and |
3924 | This means that, when you have a watcher that triggers in one hour and |
3482 | there are 100 watchers that would trigger before that then inserting will |
3925 | there are 100 watchers that would trigger before that, then inserting will |
3483 | have to skip roughly seven (\f(CW\*(C`ld 100\*(C'\fR) of these watchers. |
3926 | have to skip roughly seven (\f(CW\*(C`ld 100\*(C'\fR) of these watchers. |
3484 | .IP "Changing timer/periodic watchers (by autorepeat or calling again): O(log skipped_other_timers)" 4 |
3927 | .IP "Changing timer/periodic watchers (by autorepeat or calling again): O(log skipped_other_timers)" 4 |
3485 | .IX Item "Changing timer/periodic watchers (by autorepeat or calling again): O(log skipped_other_timers)" |
3928 | .IX Item "Changing timer/periodic watchers (by autorepeat or calling again): O(log skipped_other_timers)" |
3486 | That means that changing a timer costs less than removing/adding them |
3929 | That means that changing a timer costs less than removing/adding them, |
3487 | as only the relative motion in the event queue has to be paid for. |
3930 | as only the relative motion in the event queue has to be paid for. |
3488 | .IP "Starting io/check/prepare/idle/signal/child/fork/async watchers: O(1)" 4 |
3931 | .IP "Starting io/check/prepare/idle/signal/child/fork/async watchers: O(1)" 4 |
3489 | .IX Item "Starting io/check/prepare/idle/signal/child/fork/async watchers: O(1)" |
3932 | .IX Item "Starting io/check/prepare/idle/signal/child/fork/async watchers: O(1)" |
3490 | These just add the watcher into an array or at the head of a list. |
3933 | These just add the watcher into an array or at the head of a list. |
3491 | .IP "Stopping check/prepare/idle/fork/async watchers: O(1)" 4 |
3934 | .IP "Stopping check/prepare/idle/fork/async watchers: O(1)" 4 |
3492 | .IX Item "Stopping check/prepare/idle/fork/async watchers: O(1)" |
3935 | .IX Item "Stopping check/prepare/idle/fork/async watchers: O(1)" |
3493 | .PD 0 |
3936 | .PD 0 |
3494 | .IP "Stopping an io/signal/child watcher: O(number_of_watchers_for_this_(fd/signal/pid % \s-1EV_PID_HASHSIZE\s0))" 4 |
3937 | .IP "Stopping an io/signal/child watcher: O(number_of_watchers_for_this_(fd/signal/pid % \s-1EV_PID_HASHSIZE\s0))" 4 |
3495 | .IX Item "Stopping an io/signal/child watcher: O(number_of_watchers_for_this_(fd/signal/pid % EV_PID_HASHSIZE))" |
3938 | .IX Item "Stopping an io/signal/child watcher: O(number_of_watchers_for_this_(fd/signal/pid % EV_PID_HASHSIZE))" |
3496 | .PD |
3939 | .PD |
3497 | These watchers are stored in lists then need to be walked to find the |
3940 | These watchers are stored in lists, so they need to be walked to find the |
3498 | correct watcher to remove. The lists are usually short (you don't usually |
3941 | correct watcher to remove. The lists are usually short (you don't usually |
3499 | have many watchers waiting for the same fd or signal). |
3942 | have many watchers waiting for the same fd or signal: one is typical, two |
|
|
3943 | is rare). |
3500 | .IP "Finding the next timer in each loop iteration: O(1)" 4 |
3944 | .IP "Finding the next timer in each loop iteration: O(1)" 4 |
3501 | .IX Item "Finding the next timer in each loop iteration: O(1)" |
3945 | .IX Item "Finding the next timer in each loop iteration: O(1)" |
3502 | By virtue of using a binary or 4\-heap, the next timer is always found at a |
3946 | By virtue of using a binary or 4\-heap, the next timer is always found at a |
3503 | fixed position in the storage array. |
3947 | fixed position in the storage array. |
3504 | .IP "Each change on a file descriptor per loop iteration: O(number_of_watchers_for_this_fd)" 4 |
3948 | .IP "Each change on a file descriptor per loop iteration: O(number_of_watchers_for_this_fd)" 4 |
… | |
… | |
3525 | .IX Item "Processing signals: O(max_signal_number)" |
3969 | .IX Item "Processing signals: O(max_signal_number)" |
3526 | .PD |
3970 | .PD |
3527 | Sending involves a system call \fIiff\fR there were no other \f(CW\*(C`ev_async_send\*(C'\fR |
3971 | Sending involves a system call \fIiff\fR there were no other \f(CW\*(C`ev_async_send\*(C'\fR |
3528 | calls in the current loop iteration. Checking for async and signal events |
3972 | calls in the current loop iteration. Checking for async and signal events |
3529 | involves iterating over all running async watchers or all signal numbers. |
3973 | involves iterating over all running async watchers or all signal numbers. |
3530 | .SH "WIN32 PLATFORM LIMITATIONS AND WORKAROUNDS" |
|
|
3531 | .IX Header "WIN32 PLATFORM LIMITATIONS AND WORKAROUNDS" |
|
|
3532 | Win32 doesn't support any of the standards (e.g. \s-1POSIX\s0) that libev |
|
|
3533 | requires, and its I/O model is fundamentally incompatible with the \s-1POSIX\s0 |
|
|
3534 | model. Libev still offers limited functionality on this platform in |
|
|
3535 | the form of the \f(CW\*(C`EVBACKEND_SELECT\*(C'\fR backend, and only supports socket |
|
|
3536 | descriptors. This only applies when using Win32 natively, not when using |
|
|
3537 | e.g. cygwin. |
|
|
3538 | .PP |
|
|
3539 | Lifting these limitations would basically require the full |
|
|
3540 | re-implementation of the I/O system. If you are into these kinds of |
|
|
3541 | things, then note that glib does exactly that for you in a very portable |
|
|
3542 | way (note also that glib is the slowest event library known to man). |
|
|
3543 | .PP |
|
|
3544 | There is no supported compilation method available on windows except |
|
|
3545 | embedding it into other applications. |
|
|
3546 | .PP |
|
|
3547 | Not a libev limitation but worth mentioning: windows apparently doesn't |
|
|
3548 | accept large writes: instead of resulting in a partial write, windows will |
|
|
3549 | either accept everything or return \f(CW\*(C`ENOBUFS\*(C'\fR if the buffer is too large, |
|
|
3550 | so make sure you only write small amounts into your sockets (less than a |
|
|
3551 | megabyte seems safe, but this apparently depends on the amount of memory |
|
|
3552 | available). |
|
|
3553 | .PP |
|
|
3554 | Due to the many, low, and arbitrary limits on the win32 platform and |
|
|
3555 | the abysmal performance of winsockets, using a large number of sockets |
|
|
3556 | is not recommended (and not reasonable). If your program needs to use |
|
|
3557 | more than a hundred or so sockets, then likely it needs to use a totally |
|
|
3558 | different implementation for windows, as libev offers the \s-1POSIX\s0 readiness |
|
|
3559 | notification model, which cannot be implemented efficiently on windows |
|
|
3560 | (Microsoft monopoly games). |
|
|
3561 | .PP |
|
|
3562 | A typical way to use libev under windows is to embed it (see the embedding |
|
|
3563 | section for details) and use the following \fIevwrap.h\fR header file instead |
|
|
3564 | of \fIev.h\fR: |
|
|
3565 | .PP |
|
|
3566 | .Vb 2 |
|
|
3567 | \& #define EV_STANDALONE /* keeps ev from requiring config.h */ |
|
|
3568 | \& #define EV_SELECT_IS_WINSOCKET 1 /* configure libev for windows select */ |
|
|
3569 | \& |
|
|
3570 | \& #include "ev.h" |
|
|
3571 | .Ve |
|
|
3572 | .PP |
|
|
3573 | And compile the following \fIevwrap.c\fR file into your project (make sure |
|
|
3574 | you do \fInot\fR compile the \fIev.c\fR or any other embedded source files!): |
|
|
3575 | .PP |
|
|
3576 | .Vb 2 |
|
|
3577 | \& #include "evwrap.h" |
|
|
3578 | \& #include "ev.c" |
|
|
3579 | .Ve |
|
|
3580 | .IP "The winsocket select function" 4 |
|
|
3581 | .IX Item "The winsocket select function" |
|
|
3582 | The winsocket \f(CW\*(C`select\*(C'\fR function doesn't follow \s-1POSIX\s0 in that it |
|
|
3583 | requires socket \fIhandles\fR and not socket \fIfile descriptors\fR (it is |
|
|
3584 | also extremely buggy). This makes select very inefficient, and also |
|
|
3585 | requires a mapping from file descriptors to socket handles (the Microsoft |
|
|
3586 | C runtime provides the function \f(CW\*(C`_open_osfhandle\*(C'\fR for this). See the |
|
|
3587 | discussion of the \f(CW\*(C`EV_SELECT_USE_FD_SET\*(C'\fR, \f(CW\*(C`EV_SELECT_IS_WINSOCKET\*(C'\fR and |
|
|
3588 | \&\f(CW\*(C`EV_FD_TO_WIN32_HANDLE\*(C'\fR preprocessor symbols for more info. |
|
|
3589 | .Sp |
|
|
3590 | The configuration for a \*(L"naked\*(R" win32 using the Microsoft runtime |
|
|
3591 | libraries and raw winsocket select is: |
|
|
3592 | .Sp |
|
|
3593 | .Vb 2 |
|
|
3594 | \& #define EV_USE_SELECT 1 |
|
|
3595 | \& #define EV_SELECT_IS_WINSOCKET 1 /* forces EV_SELECT_USE_FD_SET, too */ |
|
|
3596 | .Ve |
|
|
3597 | .Sp |
|
|
3598 | Note that winsockets handling of fd sets is O(n), so you can easily get a |
|
|
3599 | complexity in the O(nA\*^X) range when using win32. |
|
|
3600 | .IP "Limited number of file descriptors" 4 |
|
|
3601 | .IX Item "Limited number of file descriptors" |
|
|
3602 | Windows has numerous arbitrary (and low) limits on things. |
|
|
3603 | .Sp |
|
|
3604 | Early versions of winsocket's select only supported waiting for a maximum |
|
|
3605 | of \f(CW64\fR handles (probably owning to the fact that all windows kernels |
|
|
3606 | can only wait for \f(CW64\fR things at the same time internally; Microsoft |
|
|
3607 | recommends spawning a chain of threads and wait for 63 handles and the |
|
|
3608 | previous thread in each. Great). |
|
|
3609 | .Sp |
|
|
3610 | Newer versions support more handles, but you need to define \f(CW\*(C`FD_SETSIZE\*(C'\fR |
|
|
3611 | to some high number (e.g. \f(CW2048\fR) before compiling the winsocket select |
|
|
3612 | call (which might be in libev or elsewhere, for example, perl does its own |
|
|
3613 | select emulation on windows). |
|
|
3614 | .Sp |
|
|
3615 | Another limit is the number of file descriptors in the Microsoft runtime |
|
|
3616 | libraries, which by default is \f(CW64\fR (there must be a hidden \fI64\fR fetish |
|
|
3617 | or something like this inside Microsoft). You can increase this by calling |
|
|
3618 | \&\f(CW\*(C`_setmaxstdio\*(C'\fR, which can increase this limit to \f(CW2048\fR (another |
|
|
3619 | arbitrary limit), but is broken in many versions of the Microsoft runtime |
|
|
3620 | libraries. |
|
|
3621 | .Sp |
|
|
3622 | This might get you to about \f(CW512\fR or \f(CW2048\fR sockets (depending on |
|
|
3623 | windows version and/or the phase of the moon). To get more, you need to |
|
|
3624 | wrap all I/O functions and provide your own fd management, but the cost of |
|
|
3625 | calling select (O(nA\*^X)) will likely make this unworkable. |
|
|
3626 | .SH "PORTABILITY REQUIREMENTS" |
|
|
3627 | .IX Header "PORTABILITY REQUIREMENTS" |
|
|
3628 | In addition to a working ISO-C implementation, libev relies on a few |
|
|
3629 | additional extensions: |
|
|
3630 | .ie n .IP """void (*)(ev_watcher_type *, int revents)""\fR must have compatible calling conventions regardless of \f(CW""ev_watcher_type *""." 4 |
|
|
3631 | .el .IP "\f(CWvoid (*)(ev_watcher_type *, int revents)\fR must have compatible calling conventions regardless of \f(CWev_watcher_type *\fR." 4 |
|
|
3632 | .IX Item "void (*)(ev_watcher_type *, int revents) must have compatible calling conventions regardless of ev_watcher_type *." |
|
|
3633 | Libev assumes not only that all watcher pointers have the same internal |
|
|
3634 | structure (guaranteed by \s-1POSIX\s0 but not by \s-1ISO\s0 C for example), but it also |
|
|
3635 | assumes that the same (machine) code can be used to call any watcher |
|
|
3636 | callback: The watcher callbacks have different type signatures, but libev |
|
|
3637 | calls them using an \f(CW\*(C`ev_watcher *\*(C'\fR internally. |
|
|
3638 | .ie n .IP """sig_atomic_t volatile"" must be thread-atomic as well" 4 |
|
|
3639 | .el .IP "\f(CWsig_atomic_t volatile\fR must be thread-atomic as well" 4 |
|
|
3640 | .IX Item "sig_atomic_t volatile must be thread-atomic as well" |
|
|
3641 | The type \f(CW\*(C`sig_atomic_t volatile\*(C'\fR (or whatever is defined as |
|
|
3642 | \&\f(CW\*(C`EV_ATOMIC_T\*(C'\fR) must be atomic with respect to accesses from different |
|
|
3643 | threads. This is not part of the specification for \f(CW\*(C`sig_atomic_t\*(C'\fR, but is |
|
|
3644 | believed to be sufficiently portable. |
|
|
3645 | .ie n .IP """sigprocmask"" must work in a threaded environment" 4 |
|
|
3646 | .el .IP "\f(CWsigprocmask\fR must work in a threaded environment" 4 |
|
|
3647 | .IX Item "sigprocmask must work in a threaded environment" |
|
|
3648 | Libev uses \f(CW\*(C`sigprocmask\*(C'\fR to temporarily block signals. This is not |
|
|
3649 | allowed in a threaded program (\f(CW\*(C`pthread_sigmask\*(C'\fR has to be used). Typical |
|
|
3650 | pthread implementations will either allow \f(CW\*(C`sigprocmask\*(C'\fR in the \*(L"main |
|
|
3651 | thread\*(R" or will block signals process-wide, both behaviours would |
|
|
3652 | be compatible with libev. Interaction between \f(CW\*(C`sigprocmask\*(C'\fR and |
|
|
3653 | \&\f(CW\*(C`pthread_sigmask\*(C'\fR could complicate things, however. |
|
|
3654 | .Sp |
|
|
3655 | The most portable way to handle signals is to block signals in all threads |
|
|
3656 | except the initial one, and run the default loop in the initial thread as |
|
|
3657 | well. |
|
|
3658 | .ie n .IP """long"" must be large enough for common memory allocation sizes" 4 |
|
|
3659 | .el .IP "\f(CWlong\fR must be large enough for common memory allocation sizes" 4 |
|
|
3660 | .IX Item "long must be large enough for common memory allocation sizes" |
|
|
3661 | To improve portability and simplify using libev, libev uses \f(CW\*(C`long\*(C'\fR |
|
|
3662 | internally instead of \f(CW\*(C`size_t\*(C'\fR when allocating its data structures. On |
|
|
3663 | non-POSIX systems (Microsoft...) this might be unexpectedly low, but |
|
|
3664 | is still at least 31 bits everywhere, which is enough for hundreds of |
|
|
3665 | millions of watchers. |
|
|
3666 | .ie n .IP """double"" must hold a time value in seconds with enough accuracy" 4 |
|
|
3667 | .el .IP "\f(CWdouble\fR must hold a time value in seconds with enough accuracy" 4 |
|
|
3668 | .IX Item "double must hold a time value in seconds with enough accuracy" |
|
|
3669 | The type \f(CW\*(C`double\*(C'\fR is used to represent timestamps. It is required to |
|
|
3670 | have at least 51 bits of mantissa (and 9 bits of exponent), which is good |
|
|
3671 | enough for at least into the year 4000. This requirement is fulfilled by |
|
|
3672 | implementations implementing \s-1IEEE\s0 754 (basically all existing ones). |
|
|
3673 | .PP |
|
|
3674 | If you know of other additional requirements drop me a note. |
|
|
3675 | .SH "COMPILER WARNINGS" |
|
|
3676 | .IX Header "COMPILER WARNINGS" |
|
|
3677 | Depending on your compiler and compiler settings, you might get no or a |
|
|
3678 | lot of warnings when compiling libev code. Some people are apparently |
|
|
3679 | scared by this. |
|
|
3680 | .PP |
|
|
3681 | However, these are unavoidable for many reasons. For one, each compiler |
|
|
3682 | has different warnings, and each user has different tastes regarding |
|
|
3683 | warning options. \*(L"Warn-free\*(R" code therefore cannot be a goal except when |
|
|
3684 | targeting a specific compiler and compiler-version. |
|
|
3685 | .PP |
|
|
3686 | Another reason is that some compiler warnings require elaborate |
|
|
3687 | workarounds, or other changes to the code that make it less clear and less |
|
|
3688 | maintainable. |
|
|
3689 | .PP |
|
|
3690 | And of course, some compiler warnings are just plain stupid, or simply |
|
|
3691 | wrong (because they don't actually warn about the condition their message |
|
|
3692 | seems to warn about). |
|
|
3693 | .PP |
|
|
3694 | While libev is written to generate as few warnings as possible, |
|
|
3695 | \&\*(L"warn-free\*(R" code is not a goal, and it is recommended not to build libev |
|
|
3696 | with any compiler warnings enabled unless you are prepared to cope with |
|
|
3697 | them (e.g. by ignoring them). Remember that warnings are just that: |
|
|
3698 | warnings, not errors, or proof of bugs. |
|
|
3699 | .SH "VALGRIND" |
|
|
3700 | .IX Header "VALGRIND" |
|
|
3701 | Valgrind has a special section here because it is a popular tool that is |
|
|
3702 | highly useful, but valgrind reports are very hard to interpret. |
|
|
3703 | .PP |
|
|
3704 | If you think you found a bug (memory leak, uninitialised data access etc.) |
|
|
3705 | in libev, then check twice: If valgrind reports something like: |
|
|
3706 | .PP |
|
|
3707 | .Vb 3 |
|
|
3708 | \& ==2274== definitely lost: 0 bytes in 0 blocks. |
|
|
3709 | \& ==2274== possibly lost: 0 bytes in 0 blocks. |
|
|
3710 | \& ==2274== still reachable: 256 bytes in 1 blocks. |
|
|
3711 | .Ve |
|
|
3712 | .PP |
|
|
3713 | Then there is no memory leak. Similarly, under some circumstances, |
|
|
3714 | valgrind might report kernel bugs as if it were a bug in libev, or it |
|
|
3715 | might be confused (it is a very good tool, but only a tool). |
|
|
3716 | .PP |
|
|
3717 | If you are unsure about something, feel free to contact the mailing list |
|
|
3718 | with the full valgrind report and an explanation on why you think this is |
|
|
3719 | a bug in libev. However, don't be annoyed when you get a brisk \*(L"this is |
|
|
3720 | no bug\*(R" answer and take the chance of learning how to interpret valgrind |
|
|
3721 | properly. |
|
|
3722 | .PP |
|
|
3723 | If you need, for some reason, empty reports from valgrind for your project |
|
|
3724 | I suggest using suppression lists. |
|
|
3725 | .SH "AUTHOR" |
3974 | .SH "AUTHOR" |
3726 | .IX Header "AUTHOR" |
3975 | .IX Header "AUTHOR" |
3727 | Marc Lehmann <libev@schmorp.de>. |
3976 | Marc Lehmann <libev@schmorp.de>, with repeated corrections by Mikael Magnusson. |