| … | |
… | |
| 792 | without a previous call to C<ev_suspend>. |
792 | without a previous call to C<ev_suspend>. |
| 793 | |
793 | |
| 794 | Calling C<ev_suspend>/C<ev_resume> has the side effect of updating the |
794 | Calling C<ev_suspend>/C<ev_resume> has the side effect of updating the |
| 795 | event loop time (see C<ev_now_update>). |
795 | event 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 | |
| 799 | Finally, this is it, the event handler. This function usually is called |
799 | Finally, this is it, the event handler. This function usually is called |
| 800 | after you have initialised all your watchers and you want to start |
800 | after you have initialised all your watchers and you want to start |
| 801 | handling events. It will ask the operating system for any new events, call |
801 | handling events. It will ask the operating system for any new events, call |
| 802 | the watcher callbacks, an then repeat the whole process indefinitely: This |
802 | the watcher callbacks, and then repeat the whole process indefinitely: This |
| 803 | is why event loops are called I<loops>. |
803 | is why event loops are called I<loops>. |
| 804 | |
804 | |
| 805 | If the flags argument is specified as C<0>, it will keep handling events |
805 | If the flags argument is specified as C<0>, it will keep handling events |
| 806 | until either no event watchers are active anymore or C<ev_break> was |
806 | until either no event watchers are active anymore or C<ev_break> was |
| 807 | called. |
807 | called. |
|
|
808 | |
|
|
809 | The return value is false if there are no more active watchers (which |
|
|
810 | usually 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 | |
| 809 | Please note that an explicit C<ev_break> is usually better than |
813 | Please note that an explicit C<ev_break> is usually better than |
| 810 | relying on all watchers to be stopped when deciding when a program has |
814 | relying on all watchers to be stopped when deciding when a program has |
| 811 | finished (especially in interactive programs), but having a program |
815 | finished (especially in interactive programs), but having a program |
| 812 | that automatically loops as long as it has to and no longer by virtue |
816 | that automatically loops as long as it has to and no longer by virtue |
| 813 | of relying on its watchers stopping correctly, that is truly a thing of |
817 | of relying on its watchers stopping correctly, that is truly a thing of |
| 814 | beauty. |
818 | beauty. |
| 815 | |
819 | |
| 816 | This function is also I<mostly> exception-safe - you can break out of |
820 | This function is I<mostly> exception-safe - you can break out of a |
| 817 | a C<ev_run> call by calling C<longjmp> in a callback, throwing a C++ |
821 | C<ev_run> call by calling C<longjmp> in a callback, throwing a C++ |
| 818 | exception and so on. This does not decrement the C<ev_depth> value, nor |
822 | exception and so on. This does not decrement the C<ev_depth> value, nor |
| 819 | will it clear any outstanding C<EVBREAK_ONE> breaks. |
823 | will it clear any outstanding C<EVBREAK_ONE> breaks. |
| 820 | |
824 | |
| 821 | A flags value of C<EVRUN_NOWAIT> will look for new events, will handle |
825 | A flags value of C<EVRUN_NOWAIT> will look for new events, will handle |
| 822 | those events and any already outstanding ones, but will not wait and |
826 | those events and any already outstanding ones, but will not wait and |
