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

Comparing libev/ev.pod (file contents):
Revision 1.397 by root, Mon Feb 13 01:52:14 2012 UTC vs.
Revision 1.400 by root, Mon Apr 2 23:46:11 2012 UTC

… …
567 567
568It scales in the same way as the epoll backend, but the interface to the 568It scales in the same way as the epoll backend, but the interface to the
569kernel is more efficient (which says nothing about its actual speed, of 569kernel is more efficient (which says nothing about its actual speed, of
570course). While stopping, setting and starting an I/O watcher does never 570course). While stopping, setting and starting an I/O watcher does never
571cause an extra system call as with C<EVBACKEND_EPOLL>, it still adds up to 571cause an extra system call as with C<EVBACKEND_EPOLL>, it still adds up to
572two event changes per incident. Support for C<fork ()> is very bad (but 572two event changes per incident. Support for C<fork ()> is very bad (you
573sane, unlike epoll) and it drops fds silently in similarly hard-to-detect 573might have to leak fd's on fork, but it's more sane than epoll) and it
574cases 574drops fds silently in similarly hard-to-detect cases
575 575
576This backend usually performs well under most conditions. 576This backend usually performs well under most conditions.
577 577
578While nominally embeddable in other event loops, this doesn't work 578While nominally embeddable in other event loops, this doesn't work
579everywhere, so you might need to test for this. And since it is broken 579everywhere, so you might need to test for this. And since it is broken
… …
792without a previous call to C<ev_suspend>. 792without a previous call to C<ev_suspend>.
793 793
794Calling C<ev_suspend>/C<ev_resume> has the side effect of updating the 794Calling C<ev_suspend>/C<ev_resume> has the side effect of updating the
795event loop time (see C<ev_now_update>). 795event loop time (see C<ev_now_update>).
796 796
797=item ev_run (loop, int flags) 797=item bool ev_run (loop, int flags)
798 798
799Finally, this is it, the event handler. This function usually is called 799Finally, this is it, the event handler. This function usually is called
800after you have initialised all your watchers and you want to start 800after you have initialised all your watchers and you want to start
801handling events. It will ask the operating system for any new events, call 801handling events. It will ask the operating system for any new events, call
802the watcher callbacks, an then repeat the whole process indefinitely: This 802the watcher callbacks, and then repeat the whole process indefinitely: This
803is why event loops are called I<loops>. 803is why event loops are called I<loops>.
804 804
805If the flags argument is specified as C<0>, it will keep handling events 805If the flags argument is specified as C<0>, it will keep handling events
806until either no event watchers are active anymore or C<ev_break> was 806until either no event watchers are active anymore or C<ev_break> was
807called. 807called.
808
809The return value is false if there are no more active watchers (which
810usually means "all jobs done" or "deadlock"), and true in all other cases
811(which usually means " you should call C<ev_run> again").
808 812
809Please note that an explicit C<ev_break> is usually better than 813Please note that an explicit C<ev_break> is usually better than
810relying on all watchers to be stopped when deciding when a program has 814relying on all watchers to be stopped when deciding when a program has
811finished (especially in interactive programs), but having a program 815finished (especially in interactive programs), but having a program
812that automatically loops as long as it has to and no longer by virtue 816that automatically loops as long as it has to and no longer by virtue
813of relying on its watchers stopping correctly, that is truly a thing of 817of relying on its watchers stopping correctly, that is truly a thing of
814beauty. 818beauty.
815 819
816This function is also I<mostly> exception-safe - you can break out of 820This function is I<mostly> exception-safe - you can break out of a
817a C<ev_run> call by calling C<longjmp> in a callback, throwing a C++ 821C<ev_run> call by calling C<longjmp> in a callback, throwing a C++
818exception and so on. This does not decrement the C<ev_depth> value, nor 822exception and so on. This does not decrement the C<ev_depth> value, nor
819will it clear any outstanding C<EVBREAK_ONE> breaks. 823will it clear any outstanding C<EVBREAK_ONE> breaks.
820 824
821A flags value of C<EVRUN_NOWAIT> will look for new events, will handle 825A flags value of C<EVRUN_NOWAIT> will look for new events, will handle
822those events and any already outstanding ones, but will not wait and 826those events and any already outstanding ones, but will not wait and
… …
4616 #define EV_USE_POLL 1 4620 #define EV_USE_POLL 1
4617 #define EV_CHILD_ENABLE 1 4621 #define EV_CHILD_ENABLE 1
4618 #define EV_ASYNC_ENABLE 1 4622 #define EV_ASYNC_ENABLE 1
4619 4623
4620The actual value is a bitset, it can be a combination of the following 4624The actual value is a bitset, it can be a combination of the following
4621values: 4625values (by default, all of these are enabled):
4622 4626
4623=over 4 4627=over 4
4624 4628
4625=item C<1> - faster/larger code 4629=item C<1> - faster/larger code
4626 4630
… …
4630code size by roughly 30% on amd64). 4634code size by roughly 30% on amd64).
4631 4635
4632When optimising for size, use of compiler flags such as C<-Os> with 4636When optimising for size, use of compiler flags such as C<-Os> with
4633gcc is recommended, as well as C<-DNDEBUG>, as libev contains a number of 4637gcc is recommended, as well as C<-DNDEBUG>, as libev contains a number of
4634assertions. 4638assertions.
4639
4640The default is off when C<__OPTIMIZE_SIZE__> is defined by your compiler
4641(e.g. gcc with C<-Os>).
4635 4642
4636=item C<2> - faster/larger data structures 4643=item C<2> - faster/larger data structures
4637 4644
4638Replaces the small 2-heap for timer management by a faster 4-heap, larger 4645Replaces the small 2-heap for timer management by a faster 4-heap, larger
4639hash table sizes and so on. This will usually further increase code size 4646hash table sizes and so on. This will usually further increase code size
4640and can additionally have an effect on the size of data structures at 4647and can additionally have an effect on the size of data structures at
4641runtime. 4648runtime.
4649
4650The default is off when C<__OPTIMIZE_SIZE__> is defined by your compiler
4651(e.g. gcc with C<-Os>).
4642 4652
4643=item C<4> - full API configuration 4653=item C<4> - full API configuration
4644 4654
4645This enables priorities (sets C<EV_MAXPRI>=2 and C<EV_MINPRI>=-2), and 4655This enables priorities (sets C<EV_MAXPRI>=2 and C<EV_MINPRI>=-2), and
4646enables multiplicity (C<EV_MULTIPLICITY>=1). 4656enables multiplicity (C<EV_MULTIPLICITY>=1).

Diff Legend

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