\documentclass[]{article}
\usepackage{amsmath,graphicx,supertabular,hyperref,tabularx,ifthen}
\title{TIP \#307: Make TclTransferResult() Public}
\date{September 28, 2007}
\author{Erik Leunissen}
\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 \#307}&\textbf{Make TclTransferResult() Public}\\\hline
Author&

Erik Leunissen \tipmail{e.leunissen}{hccnet.nl}
\\
Created&Friday, \(\text{28}^{\text{th}}\) September 2007\\
Type&Project\\
Tcl Version&\(8.6\)\\
State&Final\\
Vote&Done\\
Version&\tipversion$Revision: 1.7 $\\
Keywords&Tcl, result, transfer, interpreter, API rename\\
Post History&\\
\hline\end{tabularx}\end{center}
\thispagestyle{empty}\pagestyle{empty}
\begin{tipabstract}

This TIP proposes to make the existing function \textbf{TclTransferResult}() part of the public interface.
\end{tipabstract}
\tableofcontents\setcounter{page}{0}\clearpage\pagestyle{plain}

\section{Rationale}

The function \textbf{TclTransferResult}() is used by Tcl internally to transfer an interpreter result and/or error information between different Tcl interpreters. Besides its use in the Tcl sources, applications (based on the Tcl library) which use multiple interpreters may have a need for this functionality as well. However, programmers are likely to overlook the existing TclTransferResult() as long as the function continues to lead its more or less hidden existence. (The TIP author discovered its existence only after bugs in his own code led him to inspect how Tcl internally handles result and error info between interpreters.) Making the function public is very much a matter of courtesy/generosity to programmers that use the Tcl library. It also seems to make the API's for result and error handling more complete.

This TIP does not propose to change either the arguments or semantics of the function.

\section{Implementation}

There is not much to implement: TclTransferResult() already exists in \textit{tclResult.c}. What remains to be done:
\begin{itemize}
\item{}
renaming to Tcl\_TranferResult(): i.e. insert a single underscore character in its name. The function is not declared static already.
\item{}
slot it into the Tcl stubs table.
\item{}
write documentation
\end{itemize}

A draft version of the documentation has already been supplied as a separate file \textit{Tcl\_TransferResult.doc} (see [\url{http://sf.net/support/tracker.php?aid=1723738}]). It has been written as an addition to an existing man page. The question remains which is the most appropriate manual page to add it to.

Considerations for placement of the documentation:
\begin{itemize}
\item{}
man page for Tcl\_CreateInterp: this is the only manual page that is solely intended for multiple interpreters which are truly arbitrary interpreters, i.e. without any imposed relationship between them. However, it doesn't concern interp results.
\item{}
man page for Tcl\_CreateSlave: this manual page says for itself that it concerns multiple interpreters, which is only half the truth: it concerns mostly interpreters that have an explicit master-slave relationship, the only exception being Tcl\_CreateAlias(Obj).
\item{}
man page for Tcl\_SaveResult: handles interp results, but is not at all intended for multiple interpreter situations.
\end{itemize}

\section{Copyright}

This document has been placed in the public domain.

\section{Colophon}

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