\documentclass[]{article}
\usepackage{amsmath,graphicx,supertabular,hyperref,tabularx,ifthen}
\title{TIP \#68: Dynamic Trace Result Handling}
\date{October 16, 2001}
\author{Donal K. Fellows}
\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 \#68}&\textbf{Dynamic Trace Result Handling}\\\hline
Author&

Donal K. Fellows \tipmail{fellowsd}{cs.man.ac.uk}
\\
Created&Tuesday, \(\text{16}^{\text{th}}\) October 2001\\
Type&Project\\
Tcl Version&\(8.4\)\\
State&Final\\
Vote&Done\\
Version&\tipversion$Revision: 1.5 $\\
Post History&\\
\hline\end{tabularx}\end{center}
\thispagestyle{empty}\pagestyle{empty}
\begin{tipabstract}

This TIP proposes an extension to the \textit{Tcl\_TraceVar} API to cope with dynamically allocated results.
\end{tipabstract}
\tableofcontents\setcounter{page}{0}\clearpage\pagestyle{plain}

\section{Rationale}

The current API for handling errors during variable accesses is based on static strings, which is perfectly adequate for the errors that Tcl generates of its own accord, but which is substantially at odds with the setting of traces on variables which may produce errors. The problem is that as those errors come from a Tcl script, they are allocated dynamically and fail to satisfy the static allocation rule mentioned previously. Normally this does not cause a problem, but under some circumstances (as set out in Bug \#219393 \url{http://sf.net/tracker/?func=detail&aid=219393&group_id=10894&atid=110894}) it is possible for this to cause a memory fault or even memory corruption. This is because it can sometimes happen that the pointer to the supposedly static string winds up dangling as the string it was pointing to gets deleted out from underneath it (the storage area used to static-ify the string is part of the trace structure, but the trace is permitted to delete that structure...) Obviously this is not desirable!

There are several possible fixes, but the two main ones are to:
\begin{enumerate}
\item{}
use the \textit{Tcl\_Preserve} mechanism to postpone deletion of the allocated memory block until it has been copied into something more permanent.
\setcounter{enumi}{1}
\item{}
add special handling so as to mark the error result coming back from the trace mechanism as something other than a static string. The main alternatives here are:
\begin{itemize}
\item{}
A dynamically-allocated C string, to be disposed of with \textit{ckfree}.
\item{}
A dynamically-allocated \textit{Tcl\_Obj} reference, to be disposed of with a single call to \textit{Tcl\_DecrRefCount}.
\end{itemize}
\end{enumerate}

Although option 1 is the easiest to implement, it has the disadvantage of putting a new \textit{non-obvious} requirement on all variable traces, and that is that their results are all \textit{Tcl\_Preserve}d before the end of the trace. This is feasible for the Tcl core, but unreasonable to ask of extension writers.

Instead I prefer option 2, and it is possible to introduce this change in such a way that existing software does not see an API change (i.e. there are no serious backward-compatibility issues) and both styles of result listed above are supported. The advantage of supporting both of these is that dynamically allocated strings are a very easy interface for extension writers to use though not particularly efficient, and objects are a very efficient interface well-suited to the core itself but are not as easy to use. (It is far easier to adapt existing code to use dynamic strings as no understanding of lifespan management is required.)

\section{Changes}

To achieve this, the following new flags will be defined:
\begingroup\small\begin{verbatim}
#define TCL_TRACE_RESULT_DYNAMIC  0x2000
#define TCL_TRACE_RESULT_OBJECT   0x4000
\end{verbatim}
\endgroup

These flags, when passed to the \textit{flags} argument of \textit{Tcl\_TraceVar} (and related functions) alter the interpretation of the value returned by the call to the \textit{proc} parameter from the default behaviour (a static string) to be either a string to be deallocated by Tcl as and when it sees fit using \textit{ckfree} (when \textit{TCL\_TRACE\_RESULT\_DYNAMIC} is specified) or to be a \textit{Tcl\_Obj} (which must be cast to a \textit{char *} for type compatibility) to be disposed of when the error message is no longer required (when \textit{TCL\_TRACE\_RESULT\_OBJECT} is specified.) It is an error to specify both flags on the same call.

The core will then be modified to use this mechanism for variable traces as set up by the \textit{trace} command.

\section{Copyright}

This TIP is placed in the public domain.

\section{Reference}

For reference, the pre-TIP definition of the \textit{Tcl\_TraceVar} function is as follows:
\begingroup\small\begin{verbatim}
     int
     Tcl_TraceVar(Tcl_Interp *interp, char *varName, int flags,
                  Tcl_VarTraceProc *proc, ClientData clientData)
\end{verbatim}
\endgroup

(There is a corresponding function that takes the variable name as a pair of strings.) All parameters have the usual obvious interpretations, with the \textit{flags} being an OR-ed combination of the following flags:
\begin{description}
\item[TCL\_TRACE\_READS]
Invoke the callback when the variable is read.
\item[TCL\_TRACE\_WRITES]
Invoke the callback when the variable is written.
\item[TCL\_TRACE\_UNSETS]
Invoke the callback when the variable is unset.
\item[TCL\_TRACE\_ARRAY]
Invoke the callback when the variable is accessed as an array.
\item[TCL\_GLOBAL\_ONLY]
Force the lookup of the variable in the global scope, and not the current one.
\end{description}

\section{Colophon}

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