This is not necessarily the current version of this TIP.
|Title:||Virtualization of Tcl's Sense of Time|
|Version:||$Revision: 1.5 $|
Andreas Kupries <andreas_kupries at users dot sf dot net>|
Andreas Kupries <akupries at shaw dot ca>
|Created:||Tuesday, 30 November 2004|
This document describes a number of changes to internal and public APIs which allows external code to hook into the routines through which the Tcl core computes time-dependent information, and to override them. Through this the external code can manipulate Tcl's sense of time.
The purpose of this change is to allow code embedding the Tcl core, like simulators of all kind, to manipulate Tcl's sense of time. Currently everything in the core dependent on time, like event handling and all clock operations will always operate in real-time, as the core gets the basic information directly from the operating system. At least in simulators however it can make sense to have Tcl run in the virtual time, and not real-time. This is currently not possible, and this TIP proposes to change this, and how.
At the Tcl level nothing changes. All changes are at the C level, extending and changing existing APIs.
Two new functions, Tcl_SetTimeProc and Tcl_QueryTimeProc, are added to the public API of the core. Their signatures are:
void Tcl_SetTimeProc(Tcl_GetTimeProc *getProc, Tcl_ScaleTimeProc *scaleProc, ClientData clientData); void Tcl_QueryTimeProc(Tcl_GetTimeProc **getProc, Tcl_ScaleTimeProc **scaleProc, ClientData *clientData); typedef void (Tcl_GetTimeProc) (Tcl_Time *timebuf, ClientData clientData); typedef void (Tcl_ScaleTimeProc) (Tcl_Time *timebuf, ClientData clientData);
The first function registers two related handler functions with the core. The first handler function is a replacement for Tcl_GetTime, or rather the OS access made by Tcl_GetTime. The other handler function is used by the Tcl notifier to convert wait/block times from virtual into real time.
The second function returns the currently registered handler functions. If no external handlers were set then this will return the handlers accessing and processing the native time of the OS.
Any handler pair specified has to return data which is consistent between them. In other words, setting one handler of the pair to something assuming a 10-times slowdown, and the other handler of the pair to something assuming a two-times slowdown is wrong and not allowed.
The set handlers are allowed to run the delivered time backwards, however this should be avoided. We have to allow it as the native time can run backwards as the user can fiddle with the system time one way or other. Note that the insertion of the hooks will not change the behaviour of the Tcl core with regard to this situation, i.e. the existing behaviour is retained.
The implementations of Tcl_GetTime and TclpGetClicks are changed to check for the presence of a handler first, and will ask the operating system for the current time if and only if no handler has been registered. Both use the handler Tcl_GetTimeProc.
The implementations of Tcl_Sleep, Tcl_WaitForEvent and NotifierThreadProc are changed to ch