Re: [AD] proposal: al_sleep()

[Elias Pschernig <elias@xxxxxxxxxx>]

On Sun, 2004-01-18 at 15:31, Eric Botcazou wrote:
> > Oh, and I'm still hoping for someone to step in and agree with my view
> > on yield_timeslice() - so there would be no al_sleep at all :) Although
> > I can see now why yield_timeslice was added, I still can't think of any
> > Allegro program where I would want to call yield_timeslice, with the
> > current meaning of it.
> 
> Apply your initial patch to mainline.  The current yield_timeslice is pretty 
> useless for the average Allegro programmer and we strive for ease-of-use.  
> Moreover, there is a precedent with BeOS, QNX and MacOS X.
> 

Exactly what I was thinking. (And we can always later add the al_sleep
anyway, with al_sleep(0) doing what the current yield_timeslice does,
for the small amount of users who actually need it.)

> Then update allegro._tx and document the change in api_.tx.
> 
> (I'll not reconsider this position until after the next WIP is out, so go 
> ahead whatever happens, barring of course a veto by another maintainer).

Attached is the docs patch. I'll commit everything to SF as soon as
their CVS services are restored.

-- 
Elias Pschernig <elias@xxxxxxxxxx>

Index: docs/src/api._tx
===================================================================
RCS file: /cvsroot/alleg/allegro/docs/src/api._tx,v
retrieving revision 1.31
diff -u -p -r1.31 api._tx
--- docs/src/api._tx	30 Dec 2003 13:06:54 -0000	1.31
+++ docs/src/api._tx	19 Jan 2004 12:25:41 -0000
@@ -108,6 +108,10 @@ Changes between 4.0.x and 4.2.x series
 <li>
    set_volume() doesn't use the hardware mixer anymore to alter the global
    volume. Use set_hardware_volume() instead to get the old behaviour.
+<li>
+   yield_timeslice() doesn't just yield anymore, but actually takes CPU
+   time away from the program, in order to enable Allegro programs to
+   use less than 100% of the available processor time.
 </ul>
 
 @heading
Index: docs/src/allegro._tx
===================================================================
RCS file: /cvsroot/alleg/allegro/docs/src/allegro._tx,v
retrieving revision 1.209
diff -u -p -r1.209 allegro._tx
--- docs/src/allegro._tx	14 Jan 2004 09:14:12 -0000	1.209
+++ docs/src/allegro._tx	19 Jan 2004 12:26:02 -0000
@@ -304,11 +304,12 @@ information about how to install Allegro
 
 @@void @yield_timeslice();
 @xref vsync, d_yield_proc
-   To "play nice" with other processes you can call this function. On systems
-   that support it, it will give up the rest of the current scheduler
-   timeslice and offer it to some other process. Your CPU consumption rate
-   will drop *only* if there is another process ready to use the freed
-   timeslice.
+   Gives up some CPU time. This can be useful in order to "play nice"
+   with other processes, or simply to make the CPU usage drop. This will
+   look better to users, and also does things like saving battery power
+   and making fans less noisy. On systems that support it, it works by
+   giving up the rest of the current scheduler timeslice. On other systems,
+   it may sleep for a short while to achieve the same effect.
 
    Note that calling this inside your active game loop is a very bad idea,
    you never know when the OS will give you the CPU back, so you could end up
@@ -8274,6 +8275,7 @@ still drawn too large until version 4.1.
    should return D_O_K, D_REDRAW, or D_CLOSE.
 
 @@int @d_yield_proc(int msg, DIALOG *d, int c);
+@xref yield_timeslice
 @eref exgui
    An invisible helper object that yields timeslices for the scheduler (if
    the system supports it) when the GUI has nothing to do but waiting for