[AD] rest and yield_timeslice

[Elias Pschernig <elias@xxxxxxxxxx>]

[Resent, sorry if it appears double now]
There was already a discussion about this - but somehow it was only
about yield_timeslice and my "al_sleep", and rest was mostly left out of
it. After some discussion in #allegro today I got convinced that a
better idea would have been to just use rest() as function to give up
time.

The yield_timeslice behavior was changed mainly since the old behavior
didn't seem quite useful (to me), and it was such a nice way to make
existing programs drop CPU. And the main reason against using my
proposed al_sleep was the cludge of making a parameter of 0 sleep long
enough to drop CPU usage (30ms for OSX and BeOS, 10ms for QNX). So that
function really would have behaved odd - and it was not clear why we
should have it when we have both rest and yield_timeslice already. Since
Angelo is the guru for all the above 3 OSes, and also agreed in IRC that
it's better to use rest, my new proposal for Allegro 4.2.0 (and 4.1.15)
is:

[1] restore old yield_timeslice behavior, about its name, see [4]
[2] properly implement rest
[3] define some way to drop CPU, and replace yield_timeslice by rest in
readkey and the GUI
[4] possibly deprecate yield_timeslice

Details:

[1] yield_timslice gets reverted on windows and unix (and possibly
discouraged from use in the docs), it will again use Sleep(0) in windows
and sched_yield (or select if the former is not available) in linux.
(Don't know about other OSes - since OSX,BeOS,QNX always used the new
yield_timeslice_behavior) Also see [4]

[2] rest() apparently already uses Sleep() in Windows, so there rest(1)
already does the same as the current yield_timeslice (something which
always escaped me, I must admit). Same in BeOS. But most notably the
unix timer driver has no rest implementation, and this is the driver
also used by OSX and QNX. (And this missing implementation caused me to
somehow regard rest as a bad function and try to add the new al_sleep
the last time.)

[3] The way to give up time (and drop CPU) is using rest(). The problem
of Allegro apps being idle while awaiting input must be solved by short
waits (in order to drop CPU) between checking for input. Maybe we can
define a platform specific constant how long to wait to drop CPU (only
relevant for OSX, BeOS, QNX so far, which don't use timeslice based
sleeps) - or just state in the docs that rest(1) might not be enough to
actually drop CPU on those platforms, despite the fact than on some
other platforms (Windows and unix), it will wait a complete timeslice.

The other changes will be replacing yield_timeslice with rest(1) in
readkey() and the GUI code, so that at least the GUI uses no unnecessary
CPU by default. Again, not sure how to handle OSX and BeOS and QNX,
maybe use rest(TIMESLICE_MS) instead, and #define it depending on the
platform to 1 for windows/unix, and 30, 30, 10 for the others.

[4] Since rest(0) has undefined behavior so far, it would make sense to
apply the same semantics as windows Sleep - and just have it call
timer_driver->yield_timeslice, and yield_timeslice could finally be
deprecated. (Only the API name - the bahavior is still there in rest
(0).)

Comments are welcome.

-- 
Elias Pschernig