'''Purpose: ''' [Kevin Kenny] is comtemplating starting a project to
rework the [clock] command.  The purpose of this page is to present
some of the issues with the current [[clock]] command, and collect
feedback about how best to fix it.
----
The current (Tcl 8.4a3) [[clock]] command has served us well since Tcl 7.5, but it's starting to show cracks at all levels.  It appears that nothing less than a complete rework may suffice to fix all the issues.  (In that case, the existing [[clock]] command will be preserved, but deprecated.)

'''1. The measurement of time.'''

At present, Tcl's concept of absolute time is the count of seconds from a fixed ''epoch'' or zero point.  The count is expressed as a signed 32-bit integer.  This representation has a number of drawbacks.

   * ''Range.'' The representation of time cannot represent dates before 1902 nor after 2038.  It is only a few years before banking applications, for instance, which deal with 30-year loans will run into the end of the permissible range.

   * ''Precision.'' The granularity of a second is not adequate for disambiguating timestamps in a number of applications.  Now that NTP is a near-universal part of the networking infrastructure, it is routine to keep different systems' clocks synchronized to within a few milliseconds to tens of milliseconds, and one would want to time-stamp actions

   * ''Epoch differences.'' The time returned by [[clock seconds]] is relative to the time epoch of the underlying operating system, and the choice of epoch varies.  This should be hidden from the user.

   * ''Non-uniform representation of time intervals.'' Most systems return absolute time as a count of nominal seconds of UTC from some epoch, ignoring leap seconds; two times that are a day apart will show precisely 86400 seconds (never 86399 nor 86401) between them, even if a leap second has occurred in between.  A few systems (at least certain configurations of FreeBSD) return, instead, a count of seconds of TAI, and on these systems a day will be a second long or short if a leap second occurs.

''Proposal:'' Add to [[clock]] a [[clock milliseconds]] command that returns the nominal time from the Julian epoch expressed in milliseconds as a double-precision floating-point number.

Double-precision floating point is chosen as a representation because
it is available on all the platforms, unlike 64-bit integers, which are
the most obvious alternative.  The granularity of milliseconds, rather than seconds or days, ensures that any integer number of milliseconds will be represented exactly.

The Julian epoch is chosen because many existing calendar algorithms, such as those published in the second edition of Reingold [http://emr.cs.uiuc.edu/~reingold/calendars.shtml], use Julian day number as their internal representation.  The Julian day 
can be obtained from the millisecond count simply by dividing by 86400000 and casting to an integer.

Since leap seconds cannot be predicted in advance, it is useful to assume that the day has a fixed length of 86400 seconds.  For this reason, I propose that the Tcl clock be Smoothed Universal Time (UTS) [http://www.cl.cam.ac.uk/~mgk25/uts.txt].  The code in ''TclpGetTime'' on the Unix platform  (where the kernel clock is corrected with ''adjtime'') and on the Windows platform (where the Tcl clock is derived from a separate 'performance counter' that is disciplined with a phase-locked loop to the system clock) already comes close to the desired behavior.