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.91 by root, Mon Apr 2 23:46:27 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
… …
4722\& #define EV_CHILD_ENABLE 1 4726\& #define EV_CHILD_ENABLE 1
4723\& #define EV_ASYNC_ENABLE 1 4727\& #define EV_ASYNC_ENABLE 1
4724.Ve 4728.Ve
4725.Sp 4729.Sp
4726The actual value is a bitset, it can be a combination of the following 4730The actual value is a bitset, it can be a combination of the following
4727values: 4731values (by default, all of these are enabled):
4728.RS 4 4732.RS 4
4729.ie n .IP "1 \- faster/larger code" 4 4733.ie n .IP "1 \- faster/larger code" 4
4730.el .IP "\f(CW1\fR \- faster/larger code" 4 4734.el .IP "\f(CW1\fR \- faster/larger code" 4
4731.IX Item "1 - faster/larger code" 4735.IX Item "1 - faster/larger code"
4732Use larger code to speed up some operations. 4736Use larger code to speed up some operations.
… …
4735code size by roughly 30% on amd64). 4739code size by roughly 30% on amd64).
4736.Sp 4740.Sp
4737When optimising for size, use of compiler flags such as \f(CW\*(C`\-Os\*(C'\fR with 4741When optimising for size, use of compiler flags such as \f(CW\*(C`\-Os\*(C'\fR with
4738gcc is recommended, as well as \f(CW\*(C`\-DNDEBUG\*(C'\fR, as libev contains a number of 4742gcc is recommended, as well as \f(CW\*(C`\-DNDEBUG\*(C'\fR, as libev contains a number of
4739assertions. 4743assertions.
4744.Sp
4745The default is off when \f(CW\*(C`_\|_OPTIMIZE_SIZE_\|_\*(C'\fR is defined by your compiler
4746(e.g. gcc with \f(CW\*(C`\-Os\*(C'\fR).
4740.ie n .IP "2 \- faster/larger data structures" 4 4747.ie n .IP "2 \- faster/larger data structures" 4
4741.el .IP "\f(CW2\fR \- faster/larger data structures" 4 4748.el .IP "\f(CW2\fR \- faster/larger data structures" 4
4742.IX Item "2 - faster/larger data structures" 4749.IX Item "2 - faster/larger data structures"
4743Replaces the small 2\-heap for timer management by a faster 4\-heap, larger 4750Replaces the small 2\-heap for timer management by a faster 4\-heap, larger
4744hash table sizes and so on. This will usually further increase code size 4751hash table sizes and so on. This will usually further increase code size
4745and can additionally have an effect on the size of data structures at 4752and can additionally have an effect on the size of data structures at
4746runtime. 4753runtime.
4754.Sp
4755The default is off when \f(CW\*(C`_\|_OPTIMIZE_SIZE_\|_\*(C'\fR is defined by your compiler
4756(e.g. gcc with \f(CW\*(C`\-Os\*(C'\fR).
4747.ie n .IP "4 \- full \s-1API\s0 configuration" 4 4757.ie n .IP "4 \- full \s-1API\s0 configuration" 4
4748.el .IP "\f(CW4\fR \- full \s-1API\s0 configuration" 4 4758.el .IP "\f(CW4\fR \- full \s-1API\s0 configuration" 4
4749.IX Item "4 - full API configuration" 4759.IX Item "4 - full API configuration"
4750This enables priorities (sets \f(CW\*(C`EV_MAXPRI\*(C'\fR=2 and \f(CW\*(C`EV_MINPRI\*(C'\fR=\-2), and 4760This enables priorities (sets \f(CW\*(C`EV_MAXPRI\*(C'\fR=2 and \f(CW\*(C`EV_MINPRI\*(C'\fR=\-2), and
4751enables multiplicity (\f(CW\*(C`EV_MULTIPLICITY\*(C'\fR=1). 4761enables multiplicity (\f(CW\*(C`EV_MULTIPLICITY\*(C'\fR=1).

Diff Legend

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