\documentclass[]{article}
\usepackage{amsmath,graphicx,supertabular,hyperref,tabularx,ifthen}
\title{TIP \#445: Tcl\_ObjType Utility Routines}
\date{March 18, 2016}
\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 \#445}&\textbf{Tcl\_ObjType Utility Routines}\\\hline
Author&

Don Porter \tipmail{dgp}{users.sourceforge.net}
\\
Created&Friday, \(\text{18}^{\text{th}}\) March 2016\\
Type&Project\\
Tcl Version&\(8.7\)\\
State&Draft\\
Vote&Pending\\
Version&\tipversion$Revision: 1.7 $\\
Post History&\\
\hline\end{tabularx}\end{center}
\thispagestyle{empty}\pagestyle{empty}
\begin{tipabstract}

Proposes additional public routines useful for extensions that implement custom \textit{'Tcl\_ObjType}s.
\end{tipabstract}
\tableofcontents\setcounter{page}{0}\clearpage\pagestyle{plain}

\section{Background}

When an extension creates a custom \textbf{Tcl\_ObjType} it needs to operate on the fields of the \textbf{Tcl\_Obj} and the \textbf{Tcl\_ObjType} structs.

Almost all of these operations have been nicely encapsulated in utility routines, so for example, an extension calls \textbf{Tcl\_GetString} to make sure a value is set for \textit{objPtr-\tiprangle{}bytes}, rather than worrying about the backing details of calling the routine \textit{objPtr-\tiprangle{}typePtr-\tiprangle{}updateStringProc} (if present) for itself. Likewise \textbf{Tcl\_DuplicateObj} routes processing to type-specific routines as needed.

There are gaps in this interface. Most glaring is the lack of any way to call the \textit{freeIntRepProc} of an incumbent type other than directly through the \textit{typePtr} field. Another missing bit is an encapsulated way to set the string rep without direct manipulation of the \textit{bytes} and \textit{length} fields. Within Tcl itself, there are internal utility macros \textbf{TclFreeIntRep} and \textbf{TclInitStringRep} for these tasks, but extensions have nothing.

Besides convenience, utility routines such as these improve chances for correctness, since they bring constraints into one place instead of many places. For example, the requirement that when \textit{objPtr-\tiprangle{}typePtr} is not NULL, it must be paired with an appropriate \textit{objPtr-\tiprangle{}internalRep}. The \textbf{TclFreeIntRep} macro has a history of fixing such bugs. A corresponding routine will offer the same benefit to extensions.

\section{Proposal}

Add to Tcl's stub table of public C routines a new routine

\begin{quote}
void \textbf{Tcl\_FreeIntRep}(Tcl\_Obj* \textit{objPtr})
\end{quote}

that performs precisely the same task as the existing internal macro \textbf{TclFreeIntRep}.

Add to Tcl's stub table of public C routines a new routine 

\begin{quote}
char * \textbf{Tcl\_InitStringRep}(Tcl\_Obj* \textit{objPtr}, const char* \textit{bytes}, unsigned int \textit{numBytes})
\end{quote}

that performs the function of the existing internal macro \textbf{TclInitStringRep}, but is extended to return a pointer to the string rep, and to accept NULL as a value for \textit{bytes}. When \textit{bytes} is NULL and \textit{objPtr} has no string rep, an uninitialzed buffer of \textit{numBytes} bytes is created for filling by the caller. When \textit{bytes} is NULL and \textit{objPtr} has a string rep, the string rep will be truncated to a length of \textit{numBytes} bytes. When \textit{numBytes} is greater than zero, and the returned pointer is NULL, that indicates a failure to allocate memory for the string representation. The caller may then choose whether to raise an error or panic.

Add to Tcl's stub table of public C routines a new routine 

\begin{quote}
int \textbf{Tcl\_HasStringRep}(Tcl\_Obj* \textit{objPtr})
\end{quote}

that returns a boolean indicating whether or not a string rep is currently stored in \textit{objPtr}. This is used when the caller wants to act on \textit{objPtr} differently depending on whether or not it is a \textit{pure} value. Typically this only makes sense in an extension if it is already known that \textit{objPtr} possesses an internal type that is managed by the extension.

Define a new public type

\begin{quote}
typedef union \textbf{Tcl\_ObjIntRep} \{...\} \textbf{Tcl\_ObjIntRep}
\end{quote}

where the contents are exactly the existing contents of the union in the \textit{internalRep} field of the \textbf{Tcl\_Obj} struct. This definition permits us to pass internal representations and pointers to them as arguments and results in public routines.

Add to Tcl's stub table of public C routines a new routine 

\begin{quote}
void \textbf{Tcl\_StoreIntRep}(Tcl\_Obj* \textit{objPtr}, const Tcl\_ObjType* \textit{typePtr}, const Tcl\_ObjIntRep* \textit{irPtr})
\end{quote}

which stores in \textit{objPtr} a copy of the internal representation pointed to by \textit{irPtr} and sets its type to \textit{typePtr}. When \textit{irPtr} is NULL, this leaves \textit{objPtr} without a representation for type \textit{typePtr}.

Add to Tcl's stub table of public C routines a new routine 

\begin{quote}
Tcl\_ObjIntRep* \textbf{Tcl\_FetchIntRep}(Tcl\_Obj* \textit{objPtr}, const Tcl\_ObjType* \textit{typePtr})
\end{quote}

which returns a pointer to the internal representation stored in \textit{objPtr} that matches the requested type \textit{typePtr}.

\section{Compatibility}

These are new routines, so they have no compatibility concerns in the sense of cause trouble for existing working code.

They do help set up an improved compatibility scenario for the future however. Extensions that use these new routines to stop directly referring to the fields of the \textbf{Tcl\_Obj} and \textbf{Tcl\_ObjType} structs are prepared to support a source-compatible migration to a Tcl 9 that might then be free to make revisions to those structs.

\section{Implementation}

Taking shape on the tip-445 branch.

\section{Rejected Alternatives}

\section{Copyright}

This document has been placed in the public domain.

\section{Colophon}

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