… | |
… | |
122 | .\} |
122 | .\} |
123 | .rm #[ #] #H #V #F C |
123 | .rm #[ #] #H #V #F C |
124 | .\" ======================================================================== |
124 | .\" ======================================================================== |
125 | .\" |
125 | .\" |
126 | .IX Title "LIBEV 3" |
126 | .IX Title "LIBEV 3" |
127 | .TH LIBEV 3 "2012-03-23" "libev-4.11" "libev - high performance full featured event loop" |
127 | .TH LIBEV 3 "2012-04-03" "libev-4.11" "libev - high performance full featured event loop" |
128 | .\" For nroff, turn off justification. Always turn off hyphenation; it makes |
128 | .\" For nroff, turn off justification. Always turn off hyphenation; it makes |
129 | .\" way too many mistakes in technical documents. |
129 | .\" way too many mistakes in technical documents. |
130 | .if n .ad l |
130 | .if n .ad l |
131 | .nh |
131 | .nh |
132 | .SH "NAME" |
132 | .SH "NAME" |
… | |
… | |
685 | .Sp |
685 | .Sp |
686 | It scales in the same way as the epoll backend, but the interface to the |
686 | It scales in the same way as the epoll backend, but the interface to the |
687 | kernel is more efficient (which says nothing about its actual speed, of |
687 | kernel is more efficient (which says nothing about its actual speed, of |
688 | course). While stopping, setting and starting an I/O watcher does never |
688 | course). While stopping, setting and starting an I/O watcher does never |
689 | cause an extra system call as with \f(CW\*(C`EVBACKEND_EPOLL\*(C'\fR, it still adds up to |
689 | cause an extra system call as with \f(CW\*(C`EVBACKEND_EPOLL\*(C'\fR, it still adds up to |
690 | two event changes per incident. Support for \f(CW\*(C`fork ()\*(C'\fR is very bad (but |
690 | two event changes per incident. Support for \f(CW\*(C`fork ()\*(C'\fR is very bad (you |
691 | sane, unlike epoll) and it drops fds silently in similarly hard-to-detect |
691 | might have to leak fd's on fork, but it's more sane than epoll) and it |
692 | cases |
692 | drops fds silently in similarly hard-to-detect cases |
693 | .Sp |
693 | .Sp |
694 | This backend usually performs well under most conditions. |
694 | This backend usually performs well under most conditions. |
695 | .Sp |
695 | .Sp |
696 | While nominally embeddable in other event loops, this doesn't work |
696 | While nominally embeddable in other event loops, this doesn't work |
697 | everywhere, so you might need to test for this. And since it is broken |
697 | everywhere, so you might need to test for this. And since it is broken |
… | |
… | |
909 | given loop other than \f(CW\*(C`ev_resume\*(C'\fR, and you \fBmust not\fR call \f(CW\*(C`ev_resume\*(C'\fR |
909 | given loop other than \f(CW\*(C`ev_resume\*(C'\fR, and you \fBmust not\fR call \f(CW\*(C`ev_resume\*(C'\fR |
910 | without a previous call to \f(CW\*(C`ev_suspend\*(C'\fR. |
910 | without a previous call to \f(CW\*(C`ev_suspend\*(C'\fR. |
911 | .Sp |
911 | .Sp |
912 | Calling \f(CW\*(C`ev_suspend\*(C'\fR/\f(CW\*(C`ev_resume\*(C'\fR has the side effect of updating the |
912 | Calling \f(CW\*(C`ev_suspend\*(C'\fR/\f(CW\*(C`ev_resume\*(C'\fR has the side effect of updating the |
913 | event loop time (see \f(CW\*(C`ev_now_update\*(C'\fR). |
913 | event loop time (see \f(CW\*(C`ev_now_update\*(C'\fR). |
914 | .IP "ev_run (loop, int flags)" 4 |
914 | .IP "bool ev_run (loop, int flags)" 4 |
915 | .IX Item "ev_run (loop, int flags)" |
915 | .IX Item "bool ev_run (loop, int flags)" |
916 | Finally, this is it, the event handler. This function usually is called |
916 | Finally, this is it, the event handler. This function usually is called |
917 | after you have initialised all your watchers and you want to start |
917 | after you have initialised all your watchers and you want to start |
918 | handling events. It will ask the operating system for any new events, call |
918 | handling events. It will ask the operating system for any new events, call |
919 | the watcher callbacks, an then repeat the whole process indefinitely: This |
919 | the watcher callbacks, and then repeat the whole process indefinitely: This |
920 | is why event loops are called \fIloops\fR. |
920 | is why event loops are called \fIloops\fR. |
921 | .Sp |
921 | .Sp |
922 | If the flags argument is specified as \f(CW0\fR, it will keep handling events |
922 | If the flags argument is specified as \f(CW0\fR, it will keep handling events |
923 | until either no event watchers are active anymore or \f(CW\*(C`ev_break\*(C'\fR was |
923 | until either no event watchers are active anymore or \f(CW\*(C`ev_break\*(C'\fR was |
924 | called. |
924 | called. |
|
|
925 | .Sp |
|
|
926 | The return value is false if there are no more active watchers (which |
|
|
927 | usually means \*(L"all jobs done\*(R" or \*(L"deadlock\*(R"), and true in all other cases |
|
|
928 | (which usually means " you should call \f(CW\*(C`ev_run\*(C'\fR again"). |
925 | .Sp |
929 | .Sp |
926 | Please note that an explicit \f(CW\*(C`ev_break\*(C'\fR is usually better than |
930 | Please note that an explicit \f(CW\*(C`ev_break\*(C'\fR is usually better than |
927 | relying on all watchers to be stopped when deciding when a program has |
931 | relying on all watchers to be stopped when deciding when a program has |
928 | finished (especially in interactive programs), but having a program |
932 | finished (especially in interactive programs), but having a program |
929 | that automatically loops as long as it has to and no longer by virtue |
933 | that automatically loops as long as it has to and no longer by virtue |
930 | of relying on its watchers stopping correctly, that is truly a thing of |
934 | of relying on its watchers stopping correctly, that is truly a thing of |
931 | beauty. |
935 | beauty. |
932 | .Sp |
936 | .Sp |
933 | This function is also \fImostly\fR exception-safe \- you can break out of |
937 | This function is \fImostly\fR exception-safe \- you can break out of a |
934 | a \f(CW\*(C`ev_run\*(C'\fR call by calling \f(CW\*(C`longjmp\*(C'\fR in a callback, throwing a \*(C+ |
938 | \&\f(CW\*(C`ev_run\*(C'\fR call by calling \f(CW\*(C`longjmp\*(C'\fR in a callback, throwing a \*(C+ |
935 | exception and so on. This does not decrement the \f(CW\*(C`ev_depth\*(C'\fR value, nor |
939 | exception and so on. This does not decrement the \f(CW\*(C`ev_depth\*(C'\fR value, nor |
936 | will it clear any outstanding \f(CW\*(C`EVBREAK_ONE\*(C'\fR breaks. |
940 | will it clear any outstanding \f(CW\*(C`EVBREAK_ONE\*(C'\fR breaks. |
937 | .Sp |
941 | .Sp |
938 | A flags value of \f(CW\*(C`EVRUN_NOWAIT\*(C'\fR will look for new events, will handle |
942 | A flags value of \f(CW\*(C`EVRUN_NOWAIT\*(C'\fR will look for new events, will handle |
939 | those events and any already outstanding ones, but will not wait and |
943 | those events and any already outstanding ones, but will not wait and |