TIP #233 Version 1.2: Virtualization of Tcl's Sense of Time

This is not necessarily the current version of this TIP.

Abstract

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.

Background and Motivation

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 directyl 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.

Specification

At the Tcl level nothing changes. All changes are at the C level, extending and changing existing APIs.

One new function, Tcl_SetTimeProc, is added to the public API of the core. Its signature is:

 void Tcl_SetTimeProc(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 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 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_WaitForEvent and NotifierThreadProc are changed to check for the presence of a handler as well, and will invoke it with the current wait/block time if it is present. The handler is not invoked if it is either not present, or if no timeout was specified, or if the timeout is zero. Both use the handler Tcl_ScaleTimeProc.

Limitations

While the proposed changes are able to change Tcl's view of the current time, and of time intervals, no effort was made to reduce the execution speed of the interpreter itself, i,.e. of the bytecode engine.

This means that from the point of view of the virtual time the execution of bytecode has become faster. This can change the relative timing of events. For example the window for a race condition is in virtual time effectively reduced in size by the scaling factor between virtual and real time, becoming less likely.

Reference Implementation

A reference implementation is provided at SourceForge [1].

Comments

[ Add comments on the document here ]

Copyright

This document has been placed in the public domain.

This is not necessarily the current version of this TIP.