Author:         Mark Harrison <mh@pixar.com>
Author:         Kevin Kenny <kennykb@users.sourceforge.net>
State:          Final
Type:           Project
Vote:           Done
Created:        20-Dec-2002
Post-History:   
Tcl-Version:    8.5

Abstract

This TIP proposes altering the clock clicks command to add a -microseconds option, and to tie it to an absolute reference.

Rationale

The clock clicks command is a useful feature for analyzing and tuning performance in Tcl programs. Since the timer is relative, however, it is difficult to correlate times between two programs or with timestamps stored in a log file.

Proposed change

This TIP proposes two changes to clock clicks to make it more useful in situations where absolute times are needed:

Change clock clicks -milliseconds to return a wide integer, representing the number of milliseconds since the Posix epoch.
Add a clock clicks -microseconds that likewise returns a wide integer, representing the number of microseconds since the Posix epoch.

Compatibility with existing code

Now that Tcl supports 64-bit integers transparently, compatibility with existing code is unlikely to cause trouble. In practice, the only uses of clock clicks that the authors have seen all simply compute the difference between two successive values. Since the difference will continue to fit in 32 bits if it did so before, such code will simply continue to work.

The change from a relative standard to an absolute one is likewise transparent. One fact that supports this claim is that such a change was made in clock clicks -milliseconds on Windows in support of [7], and no Windows users reported trouble as a result.

Code that attempts to use clock clicks_ as an absolute standard by correlating its values with those returned from **clock seconds (as in http://wiki.tcl.tk/1035\) will also continue to work without without change, although the improvements to clock clicks will certainly provide a better way to do it.

Reference Implementation

The original reference implementation at

http://sf.net/tracker/?func=detail&atid=310894&aid=656997&group\_id=10894

presents an interface that has since been superseded. The reference implementation will be updated at such time as this TIP is approved.

Copyright

This document has been placed in the public domain.

Comments

Gerald Lester also points out (in the Tcl'ers Chat) that we ought to make [clock seconds] return a wide value at the same time as we implement the rest of these changes, in order to address the Y2038 problem. Alas, the problem goes deeper; the gettimeofday() call (and Tcl's mirroring of it in the Tcl_GetTime interface) is not Y2038-ready. The necessary upgrades to return a 64-bit value for [clock seconds] are outside the scope of this TIP.

Several people have informally asked whether 64 bits are enough to hold the microsecond counter. Since 2**64 microseconds is roughly half a million years, the authors are confident that the answer is, "yes."