\documentclass[]{article}
\usepackage{amsmath,graphicx,supertabular,hyperref,tabularx,ifthen}
\title{TIP \#348: Substituted 'errorstack' / 'traceback'}
\date{February 26, 2009}
\author{Alexandre Ferrieux}
\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 \#348}&\textbf{Substituted 'errorstack' / 'traceback'}\\\hline
Author&

Alexandre Ferrieux \tipmail{alexandre.ferrieux}{gmail.com}
\\
Created&Thursday, \(\text{26}^{\text{th}}\) February 2009\\
Type&Project\\
Tcl Version&\(8.6\)\\
State&Final\\
Vote&Done\\
Version&\tipversion$Revision: 1.17 $\\
Keywords&Tcl, debugging\\
Post History&\\
\hline\end{tabularx}\end{center}
\thispagestyle{empty}\pagestyle{empty}
\begin{tipabstract}

This TIP proposes to add an \textbf{errorstack} options dict entry and associated \textbf{info} subcommand, giving a ``substituted'' traceback similar to Python's or gdb's ones.
\end{tipabstract}
\tableofcontents\setcounter{page}{0}\clearpage\pagestyle{plain}

\section{Background}

The \textbf{::errorInfo} variable is a valuable tool for debugging; however, it yields mostly static information regarding each level of procedure call, as it only gives the static text (extracted from the source) at the call site. This leads to frustrating situations, like when an error occurs at a deep level of a recursive function, \textbf{::errorInfo} repeatedly reporting ``f \$x [foo [bar]]'' or similar un-substituted commands. In other languages, the traceback is more useful in that it contains the actual values passed as arguments.

\section{Proposed Change}

This TIP proposes to create an \textbf{-errorstack} options dictionary entry, and an associated \textbf{info errorstack} ?\textit{interp}? command returning a list containing the [\textbf{info level} 0] lists of command-and-args at each stack frame level at the time of error unwinding.

\section{Rationale}

In a natural implementation, its construction is analogous to that of \textbf{::errorInfo}, which is built incrementally, one level at a time while popping back from the error site. The only differences are that:
\begin{enumerate}
\item{}
dynamic arglists (from [\textbf{info level} 0]) are stored,
\setcounter{enumi}{1}
\item{}
the result is a true list built by (the equivalent of) \textbf{lappend}, and
\setcounter{enumi}{2}
\item{}
the granularity is coarser than with \textbf{::errorInfo} since there is just one element per stack frame level (and not for intervening \textbf{while} or \textbf{foreach} constructs) and no adornment like ``... while executing ...''
\end{enumerate}

Measurements show that the performance hit of maintaining the error stack is small, being under 5\% for realistic error stack sizes, and hits only the error cases. To achieve this speed, the list-growing is done carefully, reusing earlier optimizations made on list operations for the in-place case, so that in routine use the allocated Tcl\_Obj, internal representation, and element array storage backing the list never change. This way, even code heavily relying on \textbf{catch} across dozens of stack frame levels won't noticeably suffer from the error stack machinery.

\section{Definition}

The error stack is an even-sized list alternating tokens and parameters. Tokens are currently either \textbf{CALL} or \textbf{UP}, but other values may be introduced in the future; \textbf{CALL} indicates a procedure call, and its parameter is the corresponding [\textbf{info level} 0]; \textbf{UP}' indicates a shift in variable frames generated by \textbf{uplevel} or similar, and applies to the previous \textbf{CALL} item:

\begin{quote}
CALL \{foo a\} UP 1 CALL \{bar b\} CALL \{baz c\} UP 2 CALL \{gnu d\} CALL \{gnats e\}
\end{quote}

The above value indicates that [foo a] was called by [bar b] through [uplevel 1]. Similarly, [baz c] was itself lifted to toplevel by an [uplevel 2] in [gnu d].

\section{Reference Implementation}

The reference implementation can be found on SourceForge[\url{https://sourceforge.net/support/tracker.php?aid=2868499}].

An earlier, extremely slow, pure-Tcl proof of concept based on write traces on \textbf{::errorInfo} can be found on the Wiki[\url{http://wiki.tcl.tk/traceback}].

\section{Copyright}

This document has been placed in the public domain.

\section{Colophon}

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