\documentclass[]{article}
\usepackage{amsmath,graphicx,supertabular,hyperref,tabularx,ifthen}
\title{TIP \#333: New Variable and Namespace Resolving Interface}
\date{October 13, 2008}
\author{Arnulf Wiedemann}
\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 \#333}&\textbf{New Variable and Namespace Resolving Interface}\\\hline
Author&

Arnulf Wiedemann \tipmail{arnulf}{wiedemann-pri.de}
\\
Created&Monday, \(\text{13}^{\text{th}}\) October 2008\\
Type&Project\\
Tcl Version&\(8.7\)\\
State&Draft\\
Vote&Pending\\
Version&\tipversion$Revision: 1.4 $\\
Keywords&Tcl, resolution\\
Post History&\\
\hline\end{tabularx}\end{center}
\thispagestyle{empty}\pagestyle{empty}
\begin{tipabstract}

This is a TIP to allow easy command and variable resolving for itcl-ng, but is not restricted to itcl-ng. It should be possible for an application to drive the rules for command and variable lookup using the interface described below. This TIP should allow to get rid of namespace and interpreter resolvers for itcl-ng.
\end{tipabstract}
\tableofcontents\setcounter{page}{0}\clearpage\pagestyle{plain}

\section{Rationale}

The current implementation for command and variable resolution using namespace and interpreter resolvers has a lot of problems for the Tcl core implementation. Second problem is the additonal performance penality for using the resolvers (much more code is needed in the application). The suggested interface allows to hide Tcl core details concerning handling of variables and commands from the outside. If the interface would be made public, it would be also possible to avoid use of tclInt.h in that area and to only use stubs interfaces, which means itcl-ng versions would be independent of Tcl versions. Other applications (e.g. snit) could also use this interface for fast lookup of variables and commands.

\section{C-API Specification}

At the moment there is only a need for a C-API for the suggested functionality

\subsection{For Commands (methods/procs)}

\begin{quote}
typedef int (*\textbf{TclCheckClassProtectionProc})(Tcl\_Interp *\textit{interp}, Tcl\_Namespace *\textit{nsPtr}, const char *\textit{varName}, ClientData \textit{clientData});
\end{quote}

\begin{quote}
typedef void (*\textbf{Tcl\_ClassCommandDeleteProc})(ClientData \textit{clientData});
\end{quote}

\begin{quote}
typedef void (*\textbf{Tcl\_ObjectCommandDeleteProc})(ClientData \textit{clientData});
\end{quote}

\begin{quote}
ClientData \textbf{Tcl\_RegisterClassMethod}(Tcl\_Interp *\textit{interp}, Tcl\_Namespace *\textit{nsPtr}, const char *\textit{cmdName}, ClientData \textit{clientData});
\end{quote}

\begin{quote}
Tcl\_Command \textbf{Tcl\_RegisterObjectMethod}(TclInterp *\textit{interp}, ClientData \textit{objectPtr}, const char *\textit{cmdName}, Tcl\_Command \textit{cmdPtr}, ClientData \textit{clientData});
\end{quote}

\begin{quote}
void \textbf{Tcl\_UnregisterClassCommand}(Tcl\_Interp *\textit{interp}, Tcl\_Namespace *\textit{nsPtr}, const char *\textit{cmdName}, Tcl\_ClassCommandDeleteProc \textit{delProc});
\end{quote}

\begin{quote}
void \textbf{Tcl\_UnregisterObjectCommand}(Tcl\_Interp *\textit{interp}, ClientData \textit{objectPtr}, const char *\textit{cmdName}, Tcl\_ObjectCommandDeleteProc \textit{delProc});
\end{quote}

\begin{quote}
int \textbf{Tcl\_SetCallFrameObject}(Tcl\_Interp *\textit{interp}, ClientData \textit{objectPtr});
\end{quote}

\begin{quote}
int \textbf{Tcl\_SetNamespaceCommandProtectionCallback}(Tcl\_Interp *\textit{interp}, Tcl\_Namespace *\textit{nsPtr}, TclCheckNamespaceProtection \textit{cnpProc});
\end{quote}

\subsection{For Variables (variables/commons)}

\begin{quote}
typedef int (*\textbf{TclCheckClassProtection})(Tcl\_Interp *\textit{interp}, Tcl\_Namespace *\textit{nsPtr}, const char *\textit{varName}, ClientData \textit{clientData});
\end{quote}

\begin{quote}
typedef void (*\textbf{Tcl\_ObjectVariableDeleteProc})(ClientData \textit{clientData});
\end{quote}

\begin{quote}
typedef void (*\textbf{Tcl\_ClassVariableDeleteProc})(ClientData \textit{clientData});
\end{quote}

\begin{quote}
ClientData \textbf{Tcl\_RegisterClassVariable}(Tcl\_Interp *\textit{interp}, Tcl\_Namespace *\textit{nsPtr}, const char *\textit{varName}, ClientData \textit{clientData});
\end{quote}

\begin{quote}
Tcl\_Var \textbf{Tcl\_RegisterObjectVariable}(TclInterp *\textit{interp}, ClientData \textit{objectPtr}, const char *\textit{varName}, ClientData \textit{clientData}, Tcl\_Var \textit{varPtr});
\end{quote}

\begin{quote}
void \textbf{Tcl\_UnregisterClassVariable}(Tcl\_Interp *\textit{interp}, Tcl\_Namespace *\textit{nsPtr}, const char *\textit{varName}, Tcl\_ClassVariableDeleteProc \textit{delProc});
\end{quote}

\begin{quote}
void \textbf{Tcl\_UnregisterObjectVariable}(Tcl\_Interp *\textit{interp}, ClientData \textit{objectPtr}, const char *\textit{varName}, Tcl\_ObjectVariableDeleteProc \textit{delProc});
\end{quote}

\begin{quote}
int \textbf{Tcl\_SetCallFrameObject}(Tcl\_Interp *\textit{interp}, ClientData \textit{objectPtr});
\end{quote}

\begin{quote}
int \textbf{Tcl\_SetNamespaceVariableProtectionCallback}(Tcl\_Interp *\textit{interp}, Tcl\_Namespace *\textit{nsPtr}, TclCheckNamespaceProtection \textit{cnpProc});
\end{quote}

\section{Detailed Description}

For details on how itcl-ng is using variables scopes and command scopes look here: \url{http://wiki.tcl.tk/21676}

I am only describing details for variables, as variables are more complex and commands are handled very similar to variables in itcl-ng concerning lookup. There is the need for collecting all variables from an itcl-ng class hierarchy for every class in the hierarchy together with the class (which is a namespace). Then for each such collection there is the need to specify which variables are used phisically based on a per object basis, because every object has an own set of variables for the class hierarchy tied to the object. There is the need to switch these variable collections during runtime for every itcl-ng method (a method is similar to a tcl proc) which is called. Every method is called in the class (namespace) where it is defined. Therefor it is necessary to have a registration mechanism for variables on a class and object base. During execution when calling a method the appropriate set of object variables for the currently active object has to be available on a per CallFrame basis (Tcl\_SetCallFrameObject).

The protection check function shall be called when a class variable is found to check the protection level by the caller according to the protection rules for the application. The clientData structure has to be filled by the application with the appropriate data when registering a variable.

The suggested rules for lookup should be: on all places where the namespace resolvers are called at the moment to additionally (instead of) do the lookup for the new interfaces and if there is nothing found continue with normal lookup.

The *Unregister* functions are for cleaning up variable information when no longer needed. The application has to do the calls and the deleteProc is used for freeing the contents of the clientData containers used when registering the variables. If no registered variable for a class or object is left, also the data structures in Tcl core used for registering and lookup should be freed.

For commands substitute variable by command in the last few sections.

The names for the interface functions are just a suggestion, maybe someone finds better names.

\section{Reference Implementation}

A reference implementaion has been done for itcl-ng using the namespace resolvers and in the resolver functions using the described interfaces. It runs aganist the test suite without problems.

\section{Details about the Reference Implementation}

I have used a straight forward approach, which was easy to implement.

All lookup info is at the moment in a structure available with Tcl\_SetAssocData/Tcl\_GetAssocData

Tcl\_RegisterClassVariable fills a Tcl\_HashTable with the namespace as the key (not necessary in Tcl core there the info should be tied to the Namespace structure). The value is a Tcl\_HashTable for the variable infos. In that hash table there are entries with varName as a key and clientData as the value.

Tcl\_RegisterObjectVariable fills a Tcl\_HashTable with the objectClientData as key and value is a Tcl\_HashTable. The key for the hash table is clientData tied to a varName from Tcl\_RegisterClassVariable and if varPtr != NULL then it is the value for the hash table otherwise a new variable is created and used for the varPtr. The variable is created at the moment in a special per object namespace but better should be stored in a per object TclVarHashTable.

Lookup in the namespace resolvers fetches the lookup data structure, looks with namespace and varName for clientData, and if found calls Tcl\_CheckClassProtection and if TCL\_OK is returned gets the itcl object and looks for the varPtr with objectClientData and clientData and if successful returns varPtr.

\section{Copyright}

This document has been placed in the public domain.

\section{Colophon}

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