\documentclass[]{article}
\usepackage{amsmath,graphicx,supertabular,hyperref,tabularx,ifthen}
\title{TIP \#337: Make TclBackgroundException() Public}
\date{October 21, 2008}
\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 \#337}&\textbf{Make TclBackgroundException() Public}\\\hline
Author&

Don Porter \tipmail{dgp}{users.sf.net}
\\
Created&Tuesday, \(\text{21}^{\text{st}}\) October 2008\\
Type&Project\\
Tcl Version&\(8.6\)\\
State&Final\\
Vote&Done\\
Version&\tipversion$Revision: 1.6 $\\
Post History&\\
\hline\end{tabularx}\end{center}
\thispagestyle{empty}\pagestyle{empty}
\begin{tipabstract}

This TIP proposes to make the \textit{TclBackgroundException} routine available in the public interface so that extensions may notify Tcl about all return codes that occur during background operations.
\end{tipabstract}
\tableofcontents\setcounter{page}{0}\clearpage\pagestyle{plain}

\section{Background}

When background operations in Tcl result in a non-\textbf{TCL\_OK} return code, it has been recommended practice to call \textit{Tcl\_BackgroundError()} so that Tcl can arrange for background error handlers to react to the exceptional situation. The prototype of that routine is:

\begin{quote}
void \textbf{Tcl\_BackgroundError}(Tcl\_Interp *\textit{interp})
\end{quote}

In Tcl 8.5, the new \textbf{interp bgerror} command permits registration of handlers that receive the full return options dictionary as an argument \cite{tip221}. This means that such handlers can respond differently to different exceptions. At the same time a new internal routine \textbf{TclBackgroundException} with prototype:

\begin{quote}
void \textbf{TclBackgroundException}(Tcl\_Interp *\textit{interp}, int \textit{code})
\end{quote}

and the implementation of \textbf{Tcl\_BackgroundError} became:
\begingroup\small\begin{verbatim}
void Tcl_BackgroundError(Tcl_Interp *interp) {
    TclBackgroundException(interp, TCL_ERROR);
}
\end{verbatim}
\endgroup

The new \textbf{TclBackgroundException} routine is a more general routine suitable for announcing any exceptional code returned by background operations, not limited to \textbf{TCL\_ERROR} like \textbf{Tcl\_BackgroundError} has been. The new \textbf{TclBackgroundException} routine is used throughout the internal portions of Tcl so that full exception information gets reliably passed through to background exception handlers, when the background processing is governed by things which are built in to Tcl, such as \textbf{after} and \textbf{chan event}.

The oversight of \cite{tip221} was not proposing to make \textbf{TclBackgroundException} public at the same time, so that extensions which govern background operations, notably Tk, have access to the same full expressive power.

\section{Proposal}

Rename the internal routine \textbf{TclBackgroundException} to \textbf{Tcl\_BackgroundException} and place it in the public stubs table.

Apply Tk Patch 1789752 [\url{https://sourceforge.net/support/tracker.php?aid=1789752}] to make use of the new facility.

\section{Compatibility}

No compatibility concerns from a new public routine.

\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 \#221]{tip221}
Don Porter,
\emph{Allow Background Error Handlers to Accept Return Options},
on-line at \url{http://purl.org/tcl/tip/221.html}
\end{thebibliography}
\end{document}
