TIP #124 Version 1.3: Adding "clock microseconds" Subcommand

This is not necessarily the current version of this TIP.

Abstract

This TIP adds a "clock microseconds" command to allow the taking of sub-second timestamps.

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.

Introducing a [clock microseconds] command which returns the current time in both seconds and microseconds (to the resolution of the system clock) resolves this problem.

This should be portable across operating systems as it returns the result from TclpGetTime().

Documentation

Added to doc/clock.n: "clock microseconds -- Return a list of two system-dependent integers. The first element is the current time and date as described in clock seconds. The value of the second element is the number of elapsed microseconds since the beginning of the current second."

Example

    set now [clock microseconds]
    set s [lindex $now 0]
    set u [lindex $now 1]
    format "%s.%06d" [clock format $s  -format %T] $u

    13:14:23.146671

Reference Implementation

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

Copyright

This document has been placed in the public domain.

Comments

Kevin Kenny writes:

The two-integer result that you propose is awkward. I'd counterpropose the following:

1. Change [clock clicks -milliseconds] to return a wide integer, representing the number of milliseconds since the Posix epoch.

2. Add a [clock clicks -microseconds] that likewise returns a wide integer, representing the number of microseconds since the Posix epoch.

This proposal, to me, feels much more like Tcl, and less like exposing the awkward C gettimeofday() interface. What does the original author think?

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.

This is not necessarily the current version of this TIP.