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

Comparing libev/ev.pod (file contents):
Revision 1.405 by root, Thu May 3 15:07:15 2012 UTC vs.
Revision 1.406 by root, Thu May 3 16:00:47 2012 UTC

… …
2847Apart from keeping your process non-blocking (which is a useful 2847Apart from keeping your process non-blocking (which is a useful
2848effect on its own sometimes), idle watchers are a good place to do 2848effect on its own sometimes), idle watchers are a good place to do
2849"pseudo-background processing", or delay processing stuff to after the 2849"pseudo-background processing", or delay processing stuff to after the
2850event loop has handled all outstanding events. 2850event loop has handled all outstanding events.
2851 2851
2852=head3 Abusing an C<ev_idle> watcher for its side-effect
2853
2854As long as there is at least one active idle watcher, libev will never
2855sleep unnecessarily. Or in other words, it will loop as fast as possible.
2856For this to work, the idle watcher doesn't need to be invoked at all - the
2857lowest priority will do.
2858
2859This mode of operation can be useful together with an C<ev_check> watcher,
2860to do something on each event loop iteration - for example to balance load
2861between different connections.
2862
2863See L<Abusing an C<ev_check> watcher for its side-effect> for a longer
2864example.
2865
2852=head3 Watcher-Specific Functions and Data Members 2866=head3 Watcher-Specific Functions and Data Members
2853 2867
2854=over 4 2868=over 4
2855 2869
2856=item ev_idle_init (ev_idle *, callback) 2870=item ev_idle_init (ev_idle *, callback)
… …
2879 ev_idle_start (loop, idle_watcher); 2893 ev_idle_start (loop, idle_watcher);
2880 2894
2881 2895
2882=head2 C<ev_prepare> and C<ev_check> - customise your event loop! 2896=head2 C<ev_prepare> and C<ev_check> - customise your event loop!
2883 2897
2884Prepare and check watchers are usually (but not always) used in pairs: 2898Prepare and check watchers are often (but not always) used in pairs:
2885prepare watchers get invoked before the process blocks and check watchers 2899prepare watchers get invoked before the process blocks and check watchers
2886afterwards. 2900afterwards.
2887 2901
2888You I<must not> call C<ev_run> or similar functions that enter 2902You I<must not> call C<ev_run> or similar functions that enter
2889the current event loop from either C<ev_prepare> or C<ev_check> 2903the current event loop from either C<ev_prepare> or C<ev_check>
… …
2917with priority higher than or equal to the event loop and one coroutine 2931with priority higher than or equal to the event loop and one coroutine
2918of lower priority, but only once, using idle watchers to keep the event 2932of lower priority, but only once, using idle watchers to keep the event
2919loop from blocking if lower-priority coroutines are active, thus mapping 2933loop from blocking if lower-priority coroutines are active, thus mapping
2920low-priority coroutines to idle/background tasks). 2934low-priority coroutines to idle/background tasks).
2921 2935
2922It is recommended to give C<ev_check> watchers highest (C<EV_MAXPRI>) 2936When used for this purpose, it is recommended to give C<ev_check> watchers
2923priority, to ensure that they are being run before any other watchers 2937highest (C<EV_MAXPRI>) priority, to ensure that they are being run before
2924after the poll (this doesn't matter for C<ev_prepare> watchers). 2938any other watchers after the poll (this doesn't matter for C<ev_prepare>
2939watchers).
2925 2940
2926Also, C<ev_check> watchers (and C<ev_prepare> watchers, too) should not 2941Also, C<ev_check> watchers (and C<ev_prepare> watchers, too) should not
2927activate ("feed") events into libev. While libev fully supports this, they 2942activate ("feed") events into libev. While libev fully supports this, they
2928might get executed before other C<ev_check> watchers did their job. As 2943might get executed before other C<ev_check> watchers did their job. As
2929C<ev_check> watchers are often used to embed other (non-libev) event 2944C<ev_check> watchers are often used to embed other (non-libev) event
2930loops those other event loops might be in an unusable state until their 2945loops those other event loops might be in an unusable state until their
2931C<ev_check> watcher ran (always remind yourself to coexist peacefully with 2946C<ev_check> watcher ran (always remind yourself to coexist peacefully with
2932others). 2947others).
2948
2949=head3 Abusing an C<ev_check> watcher for its side-effect
2950
2951C<ev_check> (and less often also C<ev_prepare>) watchers can also be
2952useful because they are called once per event loop iteration. For
2953example, if you want to handle a large number of connections fairly, you
2954normally only do a bit of work for each active connection, and if there
2955is more work to do, you wait for the next event loop iteration, so other
2956connections have a chance of making progress.
2957
2958Using an C<ev_check> watcher is almost enough: it will be called on the
2959next event loop iteration. However, that isn't as soon as possible -
2960without external events, your C<ev_check> watcher will not be invoked.
2961
2962
2963This is where C<ev_idle> watchers come in handy - all you need is a
2964single global idle watcher that is active as long as you have one active
2965C<ev_check> watcher. The C<ev_idle> watcher makes sure the event loop
2966will not sleep, and the C<ev_check> watcher makes sure a callback gets
2967invoked. Neither watcher alone can do that.
2933 2968
2934=head3 Watcher-Specific Functions and Data Members 2969=head3 Watcher-Specific Functions and Data Members
2935 2970
2936=over 4 2971=over 4
2937 2972

Diff Legend

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