\documentclass[]{article}
\usepackage{amsmath,graphicx,supertabular,hyperref,tabularx,ifthen}
\title{TIP \#124: High-Resolution Absolute Time Values From [clock]}
\date{December 20, 2002}
\author{Mark Harrison, Kevin Kenny}
\urlstyle{sf}
\setlength{\parskip}{1ex}
\setlength{\parindent}{0pt}
\def\tipversion$#1${\texttt{\$#1\$}}
\def\tiplangle#1{\ensuremath{<}}
\def\tiprangle#1{\ensuremath{>}}
\def\tipbar#1{\ensuremath{|}}
\def\tipmail#1#2{\(\langle\){\small\expandafter\url{#1@#2}}\(\rangle\)}
\ifx\pdfoutput\undefined
\newcommand{\tipimage}[2]{\typeout{Make sure you download #1.eps}\ifthenelse{\lengthtest{0.8\textwidth>#2}\and\lengthtest{0pt<#2}}{\includegraphics{#1.eps}}{\includegraphics[width=0.8\textwidth]{#1.eps}}}
\newcommand{\tipxref}[1]{}
\newcommand{\tipxrefend}{}
\else
\newcommand{\tipimage}[2]{\typeout{Make sure you create #1.pdf}\ifthenelse{\lengthtest{0.8\textwidth>#2}\and\lengthtest{0pt<#2}}{\includegraphics{#1.pdf}}{\includegraphics[width=0.8\textwidth]{#1.pdf}}}
\pdfcatalog{/PageMode /UseOutlines}
\newcommand{\tipxref}[1]{\pdfannotlink attr {/C [0.5 0.5 1.0] /Border [0 0 1]} goto name {#1}}
\newcommand{\tipxrefend}{\pdfendlink}
\fi
\newenvironment{tipabstract}{\begin{abstract}}{\end{abstract}}
\begin{document}\maketitle
\begin{center}\begin{tabularx}{\linewidth}{|r@{: }X|}\hline
\textbf{TIP \#124}&\textbf{High-Resolution Absolute Time Values From [clock]}\\\hline
Author&

Mark Harrison \tipmail{mh}{pixar.com}
\par
Kevin Kenny \tipmail{kennykb}{users.sourceforge.net}
\\
Created&Friday, \(\text{20}^{\text{th}}\) December 2002\\
Type&Project\\
Tcl Version&\(8.5\)\\
State&Final\\
Vote&Done\\
Version&\tipversion$Revision: 1.13 $\\
Post History&\\
\hline\end{tabularx}\end{center}
\thispagestyle{empty}\pagestyle{empty}
\begin{tipabstract}

This TIP proposes altering the \textbf{clock clicks} command to add a \textbf{-microseconds} option, and to tie it to an absolute reference.
\end{tipabstract}
\tableofcontents\setcounter{page}{0}\clearpage\pagestyle{plain}

\section{Rationale}

The \textbf{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.

\section{Proposed change}

This TIP proposes two changes to \textbf{clock clicks} to make it more useful in situations where absolute times are needed:
\begin{enumerate}
\item{}
Change \textbf{clock clicks -milliseconds} to return a wide integer, representing the number of milliseconds since the Posix epoch.
\item{}
Add a \textbf{clock clicks -microseconds} that likewise returns a wide integer, representing the number of microseconds since the Posix epoch.
\end{enumerate}

\section{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 \textbf{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 \textbf{clock clicks -milliseconds} on Windows in support of \cite{tip7}, and no Windows users reported trouble as a result.

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

\section{Reference Implementation}

The original reference implementation at

\url{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.

\section{Copyright}

This document has been placed in the public domain.

\section{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 \textit{gettimeofday()} call (and Tcl's mirroring of it in the \textit{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.''

\section{Colophon}

\textit{TIP AutoGenerator --- written by Donal K. Fellows}
\begin{thebibliography}{TIP \#1}
\addcontentsline{toc}{section}{References}
\bibitem[TIP \#7]{tip7}
Kevin Kenny,
\emph{Increased resolution for TclpGetTime on Windows},
on-line at \url{http://purl.org/tcl/tip/7.html}
\end{thebibliography}
\end{document}
