\documentclass[]{article}
\usepackage{amsmath,graphicx,supertabular,hyperref,tabularx,ifthen}
\title{TIP \#32: Add Tcl\_Obj-enabled counterpart to Tcl\_CreateTrace}
\date{March 23, 2001}
\author{David Cuthbert, 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 \#32}&\textbf{Add Tcl\_Obj-enabled counterpart to Tcl\_CreateTrace}\\\hline
Author&

David Cuthbert \tipmail{dacut}{kanga.org}
\par
Kevin Kenny \tipmail{kennykb}{acm.org}
\\
Created&Friday, \(\text{23}^{\text{rd}}\) March 2001\\
Type&Project\\
Tcl Version&\(8.4\alpha4\)\\
State&Final\\
Vote&Done\\
Version&\tipversion$Revision: 1.11 $\\
Keywords&trace, Tcl\_Obj\\
Post History&\\
Discussions To&news:comp.lang.tcl\\
\hline\end{tabularx}\end{center}
\thispagestyle{empty}\pagestyle{empty}
\begin{tipabstract}

This document proposes to add Tcl\_Obj support for trace procedures written in C.
\end{tipabstract}
\tableofcontents\setcounter{page}{0}\clearpage\pagestyle{plain}

\section{Rationale}

The \textit{Tcl\_Obj} system was introduced in version 8.0, making computations (potentially) much more efficient by eliminating many type conversions to and from strings. However, the trace API continues to require character strings in both command and variable traces.

In addition, the \textit{Tcl\_CreateTrace} function interacts rather badly with the bytecode compiler, since it forbids inlining of functions. Since many trace applications ignore the built-in functions that would have been inlined, this restriction is not needed by many applications. This TIP proposes to make it optional in the revised API.

The trace mechanism in the Tcl library has been underused for some time, partly because it is awkward. While the profiler, tracer and debugger from TclX and the debugger from Expect have seen some limited success, they are certainly not familiar to the majority of Tcl users.

The second author of this TIP has experimented with using the trace mechanism to build a profiler for Tcl that does not depend on source code instrumentation. His experience was that:
\begin{itemize}
\item{}
It is very difficult to write useful trace procedures without resorting to \textit{tclInt.h} -{}- in particular, the fact that only the command name and not the \textit{Tcl\_Command} token is passed meant that \textit{Tcl\_FindCommand} is needed to do virtually anything useful.
\item{}
The profiler often perturbs the run-time behavior of the program, often violently. The reason is twofold. First, the string representation of all of a traced command's arguments must be constructed, even though the trace procedure has no need for them. Second, the presence of the trace procedure defeats the bytecode compiler. Since the user of a profiler is unlikely to care about each individual built-in command (the common usage is to profile the time spent in procedures), turning off inline compilation of commands is neither needed nor wanted.
\item{}
The profiler traces returns from commands by subsituting the command procedure with one that is internal to the profiler itself, and restoring the command procedure upon exit. Doing so requires many needless lookups of the command name, because only the name is presented to the trace procedure, and the name is the only way to access \textit{Tcl\_GetCommandInfo} and \textit{Tcl\_SetCommandInfo}. This overhead can be avoided only by including \textit{tclInt.h} and casting the \textit{Tcl\_Command} object to a \textit{Command} object -{}- in other words, by accessing the interpreter's internal data structures from the extension.
\end{itemize}

This TIP is an effort to rationalize the trace interface to avoid these difficulties.

\section{Specification}

The following functions shall be added to the Tcl core:
\begin{enumerate}
\item{}
Tcl\_CreateObjTrace
\begingroup\small\begin{verbatim}
 Tcl_Trace Tcl_CreateObjTrace ( Tcl_Interp*          interp,
                                int                  level, 
                                int                  flags,
                                Tcl_CmdObjTraceProc* objProc,
                                ClientData           clientData );
\end{verbatim}
\endgroup

The \textit{Tcl\_CreateObjTrace} function adds a trace to the Tcl evaluator. The \textit{interp} argument is the Tcl interpreter for which tracing is being requested. The \textit{level} argument is the maximum depth of recursive calls; when the execution depth of the interpreter exceeds this number, the trace callback does not execute. The \textit{objProc} argument is the callback procedure to execute each time a Tcl command is evaluated; it is expected to have arguments and result type that match \textit{Tcl\_CmdObjTraceProc} below. The \textit{clientData} argument is client data to pass to the \textit{objProc} callback. Finally, the \textit{flags} argument gives flags that control the tracing. Initially, the only flag supported will be \textit{TCL\_ALLOW\_INLINE\_COMPILE}. If this flag is set, the bytecode compiler is permitted to compile in-line code for the Tcl built-in commands; any command that has been compiled in-line will not be traced.

The \textit{Tcl\_CreateObjTrace} function returns a \textit{trace token} -{}- an object of opaque type that may be passed to \textit{Tcl\_DeleteTrace} to delete the trace.

The \textit{Tcl\_CmdObjTraceProc} will have the following type signature.
\begingroup\small\begin{verbatim}
    typedef int Tcl_CmdObjTraceProc( ClientData     clientData,
                                     Tcl_Interp*    interp,
                                     int            level,
                                     CONST char*    command,
                                     Tcl_Command    commandInfo,
                                     int            objc,
                                     Tcl_Obj *CONST objv[] );
\end{verbatim}
\endgroup

The \textit{clientData} parameter is the client data that was passed to \textit{Tcl\_CreateObjTrace}. The \textit{interp} parameter designates a Tcl interpreter. The \textit{level} parameter specifies the execution level. The \textit{command} parameter gives the raw UTF-8 text of the command being evaluated, before any substitutions have been performed. The \textit{commandInfo} parameter is an opaque \textit{Tcl\_Command} object that gives information about the command. The \textit{objc} and \textit{objv} parameters are the command name and parameter vector after substitution.

The trace procedure is expected to return a standard Tcl status return. If it returns \textit{TCL\_OK}, the command is evaluated normally. If it returns \textit{TCL\_ERROR}, evaluation of the command does not take place. The interpreter result is expected to contain an error message. If it returns any other status, such as \textit{TCL\_BREAK}, \textit{TCL\_CONTINUE} or \textit{TCL\_RETURN}, it is treated as if the command had done so.
\item{}
Tcl\_GetCommandInfoFromToken and Tcl\_SetCommandInfoFromToken
\begingroup\small\begin{verbatim}
 int
 Tcl_GetCommandInfoFromToken( Tcl_Command  token,
                          Tcl_CmdInfo* infoPtr );
\end{verbatim}
\endgroup
\begingroup\small\begin{verbatim}
 int
 Tcl_SetCommandInfoFromToken( Tcl_Command        token,
                          CONST Tcl_CmdInfo* infoPtr );
\end{verbatim}
\endgroup

The \textit{Tcl\_GetCommandInfoFromToken} and \textit{Tcl\_SetCommandInfoFromToken} functions are precisely parallel to today's \textit{Tcl\_GetCommandInfo} and \textit{Tcl\_SetCommandInfo} procedures, except that they accept an opaque \textit{Tcl\_Command} object instead of a command name. They are provided so that trace procedures (and other extensions that have such an object) can adjust command information without having to go through two extra lookups in the command hash by applying \textit{Tcl\_GetCommandInfo} to the result of \textit{Tcl\_GetCommandName.}
\end{enumerate}

\section{Change History}

10 February 2002 --- Moved to Final Status with slight revisions in the names and arguments of Tcl\_GetCommandInfoFromToken and Tcl\_SetCommandInfoFromToken.

3 November 2001 --- Reworked the entire TIP. Changed the object trace handling to work with \textit{Tcl\_Command} objects instead of command names. Removed the object-based variable trace procedures. Since Tcl variable names really are character strings and not Tcl objects, object-based variable trace procedures would be \textit{slower} than the string-based ones.

30 March 2001 --- Changed return value of objProc to a Tcl\_Obj * instead of int (and using the interpreter result to indicate an error). This is more consistent with the current behavior (but without the bug). -dac

\section{Copyright}

Copyright (c) 2000 by David Cuthbert. Distribution in whole or part, with or without annotations, is unlimited.

Copyright (c) 2001 by Kevin B. Kenny. Distribution in whole or part, with or without annotations, is unlimited.

\section{Colophon}

\textit{TIP AutoGenerator --- written by Donal K. Fellows}
\end{document}
