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

Comparing libev/ev.3 (file contents):
Revision 1.89 by root, Sat Mar 24 19:38:51 2012 UTC vs.
Revision 1.90 by root, Mon Apr 2 23:14:40 2012 UTC

… …
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
686It scales in the same way as the epoll backend, but the interface to the 686It scales in the same way as the epoll backend, but the interface to the
687kernel is more efficient (which says nothing about its actual speed, of 687kernel is more efficient (which says nothing about its actual speed, of
688course). While stopping, setting and starting an I/O watcher does never 688course). While stopping, setting and starting an I/O watcher does never
689cause an extra system call as with \f(CW\*(C`EVBACKEND_EPOLL\*(C'\fR, it still adds up to 689cause an extra system call as with \f(CW\*(C`EVBACKEND_EPOLL\*(C'\fR, it still adds up to
690two event changes per incident. Support for \f(CW\*(C`fork ()\*(C'\fR is very bad (but 690two event changes per incident. Support for \f(CW\*(C`fork ()\*(C'\fR is very bad (you
691sane, unlike epoll) and it drops fds silently in similarly hard-to-detect 691might have to leak fd's on fork, but it's more sane than epoll) and it
692cases 692drops fds silently in similarly hard-to-detect cases
693.Sp 693.Sp
694This backend usually performs well under most conditions. 694This backend usually performs well under most conditions.
695.Sp 695.Sp
696While nominally embeddable in other event loops, this doesn't work 696While nominally embeddable in other event loops, this doesn't work
697everywhere, so you might need to test for this. And since it is broken 697everywhere, so you might need to test for this. And since it is broken
… …
909given loop other than \f(CW\*(C`ev_resume\*(C'\fR, and you \fBmust not\fR call \f(CW\*(C`ev_resume\*(C'\fR 909given loop other than \f(CW\*(C`ev_resume\*(C'\fR, and you \fBmust not\fR call \f(CW\*(C`ev_resume\*(C'\fR
910without a previous call to \f(CW\*(C`ev_suspend\*(C'\fR. 910without a previous call to \f(CW\*(C`ev_suspend\*(C'\fR.
911.Sp 911.Sp
912Calling \f(CW\*(C`ev_suspend\*(C'\fR/\f(CW\*(C`ev_resume\*(C'\fR has the side effect of updating the 912Calling \f(CW\*(C`ev_suspend\*(C'\fR/\f(CW\*(C`ev_resume\*(C'\fR has the side effect of updating the
913event loop time (see \f(CW\*(C`ev_now_update\*(C'\fR). 913event 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)"
916Finally, this is it, the event handler. This function usually is called 916Finally, this is it, the event handler. This function usually is called
917after you have initialised all your watchers and you want to start 917after you have initialised all your watchers and you want to start
918handling events. It will ask the operating system for any new events, call 918handling events. It will ask the operating system for any new events, call
919the watcher callbacks, an then repeat the whole process indefinitely: This 919the watcher callbacks, and then repeat the whole process indefinitely: This
920is why event loops are called \fIloops\fR. 920is why event loops are called \fIloops\fR.
921.Sp 921.Sp
922If the flags argument is specified as \f(CW0\fR, it will keep handling events 922If the flags argument is specified as \f(CW0\fR, it will keep handling events
923until either no event watchers are active anymore or \f(CW\*(C`ev_break\*(C'\fR was 923until either no event watchers are active anymore or \f(CW\*(C`ev_break\*(C'\fR was
924called. 924called.
925.Sp
926The return value is false if there are no more active watchers (which
927usually 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
926Please note that an explicit \f(CW\*(C`ev_break\*(C'\fR is usually better than 930Please note that an explicit \f(CW\*(C`ev_break\*(C'\fR is usually better than
927relying on all watchers to be stopped when deciding when a program has 931relying on all watchers to be stopped when deciding when a program has
928finished (especially in interactive programs), but having a program 932finished (especially in interactive programs), but having a program
929that automatically loops as long as it has to and no longer by virtue 933that automatically loops as long as it has to and no longer by virtue
930of relying on its watchers stopping correctly, that is truly a thing of 934of relying on its watchers stopping correctly, that is truly a thing of
931beauty. 935beauty.
932.Sp 936.Sp
933This function is also \fImostly\fR exception-safe \- you can break out of 937This function is \fImostly\fR exception-safe \- you can break out of a
934a \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+
935exception and so on. This does not decrement the \f(CW\*(C`ev_depth\*(C'\fR value, nor 939exception and so on. This does not decrement the \f(CW\*(C`ev_depth\*(C'\fR value, nor
936will it clear any outstanding \f(CW\*(C`EVBREAK_ONE\*(C'\fR breaks. 940will it clear any outstanding \f(CW\*(C`EVBREAK_ONE\*(C'\fR breaks.
937.Sp 941.Sp
938A flags value of \f(CW\*(C`EVRUN_NOWAIT\*(C'\fR will look for new events, will handle 942A flags value of \f(CW\*(C`EVRUN_NOWAIT\*(C'\fR will look for new events, will handle
939those events and any already outstanding ones, but will not wait and 943those events and any already outstanding ones, but will not wait and

Diff Legend

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