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

Comparing libev/ev.pod (file contents):
Revision 1.402 by root, Wed Apr 18 06:09:29 2012 UTC vs.
Revision 1.405 by root, Thu May 3 15:07:15 2012 UTC

… …
1174 1174
1175=item C<EV_PREPARE> 1175=item C<EV_PREPARE>
1176 1176
1177=item C<EV_CHECK> 1177=item C<EV_CHECK>
1178 1178
1179All C<ev_prepare> watchers are invoked just I<before> C<ev_run> starts 1179All C<ev_prepare> watchers are invoked just I<before> C<ev_run> starts to
1180to gather new events, and all C<ev_check> watchers are invoked just after 1180gather new events, and all C<ev_check> watchers are queued (not invoked)
1181C<ev_run> has gathered them, but before it invokes any callbacks for any 1181just after C<ev_run> has gathered them, but before it queues any callbacks
1182for any received events. That means C<ev_prepare> watchers are the last
1183watchers invoked before the event loop sleeps or polls for new events, and
1184C<ev_check> watchers will be invoked before any other watchers of the same
1185or lower priority within an event loop iteration.
1186
1182received events. Callbacks of both watcher types can start and stop as 1187Callbacks of both watcher types can start and stop as many watchers as
1183many watchers as they want, and all of them will be taken into account 1188they want, and all of them will be taken into account (for example, a
1184(for example, a C<ev_prepare> watcher might start an idle watcher to keep 1189C<ev_prepare> watcher might start an idle watcher to keep C<ev_run> from
1185C<ev_run> from blocking). 1190blocking).
1186 1191
1187=item C<EV_EMBED> 1192=item C<EV_EMBED>
1188 1193
1189The embedded event loop specified in the C<ev_embed> watcher needs attention. 1194The embedded event loop specified in the C<ev_embed> watcher needs attention.
1190 1195
… …
1874 callback (EV_P_ ev_timer *w, int revents) 1879 callback (EV_P_ ev_timer *w, int revents)
1875 { 1880 {
1876 // calculate when the timeout would happen 1881 // calculate when the timeout would happen
1877 ev_tstamp after = last_activity - ev_now (EV_A) + timeout; 1882 ev_tstamp after = last_activity - ev_now (EV_A) + timeout;
1878 1883
1879 // if negative, it means we the timeout already occured 1884 // if negative, it means we the timeout already occurred
1880 if (after < 0.) 1885 if (after < 0.)
1881 { 1886 {
1882 // timeout occurred, take action 1887 // timeout occurred, take action
1883 } 1888 }
1884 else 1889 else
… …
1902 1907
1903Otherwise, we now the earliest time at which the timeout would trigger, 1908Otherwise, we now the earliest time at which the timeout would trigger,
1904and simply start the timer with this timeout value. 1909and simply start the timer with this timeout value.
1905 1910
1906In other words, each time the callback is invoked it will check whether 1911In other words, each time the callback is invoked it will check whether
1907the timeout cocured. If not, it will simply reschedule itself to check 1912the timeout occurred. If not, it will simply reschedule itself to check
1908again at the earliest time it could time out. Rinse. Repeat. 1913again at the earliest time it could time out. Rinse. Repeat.
1909 1914
1910This scheme causes more callback invocations (about one every 60 seconds 1915This scheme causes more callback invocations (about one every 60 seconds
1911minus half the average time between activity), but virtually no calls to 1916minus half the average time between activity), but virtually no calls to
1912libev to change the timeout. 1917libev to change the timeout.
… …
1926 if (activity detected) 1931 if (activity detected)
1927 last_activity = ev_now (EV_A); 1932 last_activity = ev_now (EV_A);
1928 1933
1929When your timeout value changes, then the timeout can be changed by simply 1934When your timeout value changes, then the timeout can be changed by simply
1930providing a new value, stopping the timer and calling the callback, which 1935providing a new value, stopping the timer and calling the callback, which
1931will agaion do the right thing (for example, time out immediately :). 1936will again do the right thing (for example, time out immediately :).
1932 1937
1933 timeout = new_value; 1938 timeout = new_value;
1934 ev_timer_stop (EV_A_ &timer); 1939 ev_timer_stop (EV_A_ &timer);
1935 callback (EV_A_ &timer, 0); 1940 callback (EV_A_ &timer, 0);
1936 1941
… …
3313it by calling C<ev_async_send>, which is thread- and signal safe. 3318it by calling C<ev_async_send>, which is thread- and signal safe.
3314 3319
3315This functionality is very similar to C<ev_signal> watchers, as signals, 3320This functionality is very similar to C<ev_signal> watchers, as signals,
3316too, are asynchronous in nature, and signals, too, will be compressed 3321too, are asynchronous in nature, and signals, too, will be compressed
3317(i.e. the number of callback invocations may be less than the number of 3322(i.e. the number of callback invocations may be less than the number of
3318C<ev_async_sent> calls). In fact, you could use signal watchers as a kind 3323C<ev_async_send> calls). In fact, you could use signal watchers as a kind
3319of "global async watchers" by using a watcher on an otherwise unused 3324of "global async watchers" by using a watcher on an otherwise unused
3320signal, and C<ev_feed_signal> to signal this watcher from another thread, 3325signal, and C<ev_feed_signal> to signal this watcher from another thread,
3321even without knowing which loop owns the signal. 3326even without knowing which loop owns the signal.
3322 3327
3323=head3 Queueing 3328=head3 Queueing
… …
3921 3926
3922 ... 3927 ...
3923 ev_set_syserr_cb (fatal_error); 3928 ev_set_syserr_cb (fatal_error);
3924 3929
3925The only API functions that can currently throw exceptions are C<ev_run>, 3930The only API functions that can currently throw exceptions are C<ev_run>,
3926C<ev_inoke>, C<ev_invoke_pending> and C<ev_loop_destroy> (the latter 3931C<ev_invoke>, C<ev_invoke_pending> and C<ev_loop_destroy> (the latter
3927because it runs cleanup watchers). 3932because it runs cleanup watchers).
3928 3933
3929Throwing exceptions in watcher callbacks is only supported if libev itself 3934Throwing exceptions in watcher callbacks is only supported if libev itself
3930is compiled with a C++ compiler or your C and C++ environments allow 3935is compiled with a C++ compiler or your C and C++ environments allow
3931throwing exceptions through C libraries (most do). 3936throwing exceptions through C libraries (most do).

Diff Legend

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