[Scummvm-devel] ENGINES: Pausing the engine while debugger console visible

Max Horn max at quendi.de
Mon Nov 1 13:22:24 CET 2010


Hi there,

the following concerns all Engine maintainers whose engine implements a debugger console, via GUI::Debugger. Feedback by all engine authors solicited. Engine authors can also immediately proceed to implement this if they desire so. 

If there is no big outcry over this, and no serious objections, then I expect this to be implemented gradually over time by me and other people.


Proposed change:
===============
The engine should be paused when entering the debugger console, and unpaused afterwards. Specifically by using Engine::pauseEngine.

Rational:
--------
When debugging using gdb or similar debuggers, I expect the program to be completely halted while I inspect its state. The debuggee is for all purposes "paused". Once I enter "run" the debugger console stops accepting commands, until a breakpoint is hit or I enter the debugger by other means.
It seems logical to me that the engine / game should also be "paused" while I am in the debugger. As an example, consider the situation where a timing sensitive game sequence is active, which requires the player to make a certain action within a fixed amount of time. Now supposed this is to be debugged, and the debugger is entered, in order to inspect some state, etc.. The developer takes some minutes for this. Then, after resuming, if we do *not* pause, the game might immediately act as if the player failed to perform the required action in time. This makes debugging these sequences hard. OTOH, if the game was paused by the debugger, then the internal "clock" of the game hopefully would also be paused, and debugging the sequence becomes easy.

Using Engine::pauseEngine has some additional advantages:
* If the engine is paused this way, then showing additional dialogs (such as the GMM or the "confirm_exit" dialog) will correctly interact and correctly "nest" the pause level.
(Note: Currently, the GMM won't open while the engine is paused; so if the debugger pauses the game, then the GMM could not be used anymore while the Debugger is open. This can be both considered an advantage or a disadvantage. It would be relatively easy to change this, though; but note that using the GMM while a debugger is attached may result in incorrect or unexpected results in some engines).

* Pausing the engine will also automatically take care of adjusting the "total play time" which Engine records. I.e. if a new game is launched, and the debugger is immediately entered, and exited after 5 minutes, then if you use pauseEngine, the total play time will be 0 seconds (or at least something small), while without pausing, it will be 5+ minutes.


Caveats:
-------
Some engines may implement pausing in such a way that it would interfere with the debugger. E.g. pausing might mess up some internal state in undesirable ways. If so, these engines and the precise issues they have should be identified, so that we can deal with them resp. adjust this proposal accordingly.

Implementation:
--------------
I propose a gradual introduction of this change. For each engine using a debugger, we modify (resp. add) the Debugger::preEnter() / postEnter() implementations, adding calls to Engine::pauseEngine(true/false) into them. And possibly removing any existing functionality (e.g. for pausing music).
This way, we can perform the change step by step, for each engine independently; if regressions are detected, we can easily focus on fixing up the affected engine specifically, up to the ability to easily revert the change for that engine only.

On the long run, I think we should insert the pauseEngine calls into GUI::Debugger itself. Three approaches come to mind:
1) Insert pauseEngine(true) before preEnter is called, and pauseEngine(true) after postEnter is called.
2) Insert pauseEngine(true) after preEnter is called, and pauseEngine(true) before postEnter is called.
3) Insert pauseEngine(true) into the default preEnter() implementation, similarly for postEnter().

The advantage of 3 is that engine who really do not want pauseEngine to be used can easily prevent it. The drawback is that subclasses must "remember" to invoke the default preEnter / postEnter methods. However, that does not seem like too much of a burden.


Cheers,
Max



More information about the Scummvm-devel mailing list