\documentclass[]{article}
\usepackage{amsmath,graphicx,supertabular,hyperref,tabularx,ifthen}
\title{TIP \#381: Call Chain Introspection and Control}
\date{October 20, 2010}
\author{Donal K. Fellows}
\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 \#381}&\textbf{Call Chain Introspection and Control}\\\hline
Author&

Donal K. Fellows \tipmail{dkf}{users.sf.net}
\\
Created&Wednesday, \(\text{20}^{\text{th}}\) October 2010\\
Type&Project\\
Tcl Version&\(8.6\)\\
State&Final\\
Vote&Done\\
Version&\tipversion$Revision: 1.9 $\\
Keywords&TclOO, iTcl\\
Post History&\\
\hline\end{tabularx}\end{center}
\thispagestyle{empty}\pagestyle{empty}
\begin{tipabstract}

This TIP proposes mechanisms for inspecting the TclOO call chain for a particular method, both externally via \textbf{info} and from within a call to that method. It also proposes a mechanism that will allow the traversal of the call chain in a more controlled way than at present with the \textbf{next} command.
\end{tipabstract}
\tableofcontents\setcounter{page}{0}\clearpage\pagestyle{plain}

\section{Rationale}

Experience with TclOO in deployment has shown that the call chain mechanism used for identifying method implementations to bind to a particular method call is not just a powerful system, but also fairly difficult to understand. In particular, there is currently no way to discover what implementations of a method will be actually called, which makes debugging more difficult than it ought to be.

In addition, it has been found that it is quite difficult to manage multiple inheritance with TclOO. In particular, when a ``diamond'' inheritance graph is constructed where the different arms of the graph require different arguments, it is exceptionally difficult to ensure that the correct arguments get delivered to the right constructors, this being a requirement for some of the ways in which people use [incr Tcl] and build megawidgets. Arguably, in these cases it would be perhaps better for code to use delegation as a class composition mechanism, but it is not the place of TclOO to impose such a policy. As such, there needs to be a mechanism to allow more precise runtime control over the traversal of call chain (control over the construction of the chain would not be so useful; there simply is no right order that can ensure that immiscible constructor arguments get passed correctly).

\section{Proposed Changes}

There will be the the following subcommands of \textbf{info} added:

\begin{quote}
\textbf{info object call} \textit{objectName methodName}
\end{quote}

This will return a list describing the methods used to implement a call to the given \textit{methodName} on the given \textit{objectName}. It will be an error to call it on anything that is not an object, but in the case that \textit{methodName} does not describe a (visible) method, the returned list will describe how things are handled by \textbf{unknown} processing.

Each element of the list will be a tuple. The first element of the tuple will be one of \textbf{filter}, \textbf{method} and \textbf{unknown} to indicate whether it is a filter, a normal method call, or a special method call used to handle unknown methods (i.e., with the method name as an additional argument); the remainder of the tuple's interpretation will depend on which it is. The second element will be the name of the method implementation (always \textbf{unknown} in the case of unknown handling, except where that is intercepted by a filter). The third element will be the literal \textbf{object} or the fully-qualified name of the class of that provided the implementation of the method or filter (NB: not necessarily the class that enabled the filtering through that name). The fourth element will be the type of the method implementation (i.e., as described by \textbf{info object methodtype} or \textbf{info class methodtype}, depending on where the method is declared).

\begin{quote}
\textbf{info class call} \textit{className methodName}
\end{quote}

This will be similar to \textbf{info object call}, but will instead describe what would happen with a stereotypical instance of \textit{className}.

In addition, there will be an extra subcommand of \textbf{self}:

\begin{quote}
\textbf{self call}
\end{quote}

This will return a list of two items, the first being the list that would have been returned by \textbf{info object call} for this method call, and the second being an index into the list of the current method (i.e., \textbf{0} for the first implementation on the list).

Finally, there will be another command made available inside method bodies to provide the advanced chain calling described above:

\begin{quote}
\textbf{nextto} \textit{className} ?\textit{arg ...}?
\end{quote}

This command will behave just like \textbf{next} except that it will scan \textit{forward} in the current method chain until the implementation of the method provided by \textit{className} is located, and chain to that (while passing in the \textit{arg}uments given, of course). It will be an error to attempt to call a class's implementation of a method that is not on the chain, or that is preceding the currently executing method implementation, and it will not be possible to jump to filters applied to the method.

\section{Reference Implementation}

See \url{https://core.tcl.tk/tcloo/timeline?r=development-next2} for the proposed implementation (notably commit-f5a2cfd0d4).

\section{Copyright}

This document has been placed in the public domain.

\section{Colophon}

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