\documentclass[]{article}
\usepackage{amsmath,graphicx,supertabular,hyperref,tabularx,ifthen}
\title{TIP \#226: Interface to Save and Restore Interpreter State}
\date{October 30, 2004}
\author{Don Porter}
\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 \#226}&\textbf{Interface to Save and Restore Interpreter State}\\\hline
Author&

Don Porter \tipmail{dgp}{users.sf.net}
\\
Created&Saturday, \(\text{30}^{\text{th}}\) October 2004\\
Type&Project\\
Tcl Version&\(8.5\)\\
State&Final\\
Vote&Done\\
Version&\tipversion$Revision: 1.5 $\\
Keywords&Tcl\\
Post History&\\
\hline\end{tabularx}\end{center}
\thispagestyle{empty}\pagestyle{empty}
\begin{tipabstract}

This TIP proposes new public C routines to allow the dynamic state of an interp, including the return options, and error logging in progress as well as the interp result, to be saved and later restored.
\end{tipabstract}
\tableofcontents\setcounter{page}{0}\clearpage\pagestyle{plain}

\section{Background}

The Tcl C library has long recognized the need for some routines to be able to make use of a \textit{Tcl\_Interp} without leaving any lasting footprints behind, and without interfering with whatever operations that \textit{Tcl\_Interp} might be in the midst of performing. The longstanding routines used to address this need have been \textit{Tcl\_SaveResult}, \textit{Tcl\_RestoreResult}, and \textit{Tcl\_DiscardResult}.

These existing routines also have known limitations. The documentation warns that they should not be used when an error is in progress, because they are not able to preserve the extra error information in the \textit{Tcl\_Interp}, only the result.

The existing routines are also showing their age. Because they focus on the result of the \textit{Tcl\_Interp}, and because they date from at least the Tcl 7 days, they spend an inordinate amount of effort tending to the needs of the long-deprecated \textit{interp-\tiprangle{}result} field. Also, they make use of the transparent definition of a public struct, \textit{Tcl\_SavedResult}, and expect the caller to allocate such structs itself, a practice now frowned upon, and replaced with the use of opaque structs.

The Itcl extension has long worked around the limitations of \textit{Tcl\_SaveResult}, etc. by defining its own set of routines that more completely save and restore the state of a \textit{Tcl\_Interp}. These routines are \textit{Itcl\_SaveInterpState}, \textit{Itcl\_RestoreInterpState}, and \textit{Itcl\_DiscardInterpState}. These routines are able to handle the case of an error in progress, and have an interface making use of an opaque struct, \textit{Itcl\_InterpState}. In order to create these routines, however, the Itcl extension makes direct access to some of the private fields of Tcl's \textit{Interp} struct.

In Tcl 8.5, the proposal of \cite{tip90} have already extended further the values that make up the state of a \textit{Tcl\_Interp}, including a return level, and a dictionary of return options. Also, some of the internal fields of the \textit{Interp} struct have been reworked, so that the Itcl routines no longer function without modification.

It it time for Tcl to provide public interfaces that perform the functions of the \textit{Itcl\_*InterpState} routines, and in fact, Tcl should provide exactly those routines.

\section{Proposal}

Three new routines will be added to Tcl's public stub table:

\begin{quote}
Tcl\_InterpState \textbf{Tcl\_SaveInterpState}(Tcl\_Interp *\textit{interp}, int \textit{status})
\end{quote}

\begin{quote}
int \textbf{Tcl\_RestoreInterpState}(Tcl\_Interp *\textit{interp}, Tcl\_InterpState \textit{state})
\end{quote}

\begin{quote}
void \textbf{Tcl\_DiscardInterpState}(Tcl\_InterpState \textit{state})
\end{quote}

Also an opaque struct will be declared in \textbf{tcl.h}:

\begin{quote}
typedef struct Tcl\_InterpState\_ *\textbf{Tcl\_InterpState};
\end{quote}

These routines are to have the same function as their existing Itcl counterparts.

These declarations and routines already exist in the HEAD of Tcl's development sources, but as private routines. The Tcl source code itself has already had an upgrade to replace all uses of the old \textit{Tcl\_SaveResult} calls with these new routines. This TIP merely proposes making these routines available as part of the public interface.

\section{Compatibility}

Strictly speaking, there are no compatibility issues, since these are new additions to the public interface.

Callers of the \textit{Tcl\_SaveResult} family of routines should be encouraged to update to use the new routines, as they perform the same function and more. The \textit{Tcl\_SaveResult} family of routines should be kept in the public interface at least through the Tcl 8 series of releases, though. Consideration of their removal for Tcl 9 is left for another proposal.

Itcl will have compatibility issues with Tcl 8.5 because of the changes to the internal fields of Tcl's \textit{Interp} struct. Itcl should make use of these new routines as the implementation of its corresponding routines whenever compiling against a Tcl 8.5 set of headers. When doing that, of course, version 8.5 of the Tcl stubs table will need to be required.

\section{Reference Implementation}

See Tcl Patch 1060579.

\section{Comments}

Please make any comments here.

\section{Copyright}

This document has been placed in the public domain.

\section{Colophon}

\textit{TIP AutoGenerator --- written by Donal K. Fellows}
\begin{thebibliography}{TIP \#1}
\addcontentsline{toc}{section}{References}
\bibitem[TIP \#90]{tip90}
Don Porter,
Donal K. Fellows,
\emph{Enable [return -code] in Control Structure Procs},
on-line at \url{http://purl.org/tcl/tip/90.html}
\end{thebibliography}
\end{document}
