\documentclass[]{article}
\usepackage{amsmath,graphicx,supertabular,hyperref,tabularx,ifthen}
\title{TIP \#416: New Options for 'load': -global and -lazy}
\date{October 31, 2012}
\author{Christian Delbaere, Jan Nijtmans, Jan Nijtmans}
\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 \#416}&\textbf{New Options for 'load': -global and -lazy}\\\hline
Author&

Christian Delbaere \tipmail{cdelbaere}{rogers.com}
\par
Jan Nijtmans \tipmail{nijtmans}{users.sf.net}
\par
Jan Nijtmans \tipmail{jan.nijtmans}{gmail.com}
\\
Created&Wednesday, \(\text{31}^{\text{st}}\) October 2012\\
Type&Project\\
Tcl Version&\(8.6\)\\
State&Final\\
Vote&Done\\
Version&\tipversion$Revision: 1.5 $\\
Post History&\\
\hline\end{tabularx}\end{center}
\thispagestyle{empty}\pagestyle{empty}
\begin{tipabstract}

This TIP proposes enhancing the Tcl \textbf{load} command with the additional options \textbf{-global} and \textbf{-lazy}. It is implemented on top of \cite{tip357}, by defining a meaning to the \textbf{flags} parameter already defined there.
\end{tipabstract}
\tableofcontents\setcounter{page}{0}\clearpage\pagestyle{plain}

\section{Rationale}

Platforms that use the \textit{dlopen()} function to Tcl \textbf{load} shared modules at runtime provide options to control how the library is loaded:
\begin{itemize}
\item{}
global vs. local symbol scoping
\item{}
lazy vs. now symbol resolution
\end{itemize}

Currently, Tcl's \textbf{load} command has hard coded defaults for these options and they cannot be overridden within a Tcl script. This imposes constraints on the internal implementation of the modules intended to be loaded into the interpreter. This is especially problematic for modules that provide Tcl scripting bindings for existing C++ APIs. Often, the C++ APIs make assumptions about the availability and scoping of their symbols.

Tcl binding packages for C++ APIs are often created by a different development group than the one that created the original C++ API. Because the two groups are independent, the C++ API maintainers will not always be open or able to change their code to fit the requirements to be loaded into a scripting language.

A common problem occurs when the same static variable is present in two different Tcl modules. For some applications, the variable is meant to be shared across modules (global scoping), while in other applications, the variable must have its own value within each module (local scoping). If the wrong scoping is chosen, the underlying code will not work correctly; rather it will yield strange bugs and / or crashes.

Also in the domain of Tcl bindings for C++ APIs: it's convenient for the binding package maintainers to have binary compatibility between one version of the Tcl API and several versions of the C++ API. The \textbf{-lazy} flag for Tcl's load command will provides the feature necessary for this flexibility, since it can be used to defer missing symbol errors. So, users can often continue to run their scripts as long as they restrict themselves to calling only commands where the symbols are available.

Of course, some applications work best when \textbf{load} is called with \textbf{-global} and some work best without it. The same can be said for \textbf{-lazy}. By providing these options, Tcl will allow programmers to choose the best fit for their application.

\section{Specification}

In \cite{tip357}, the \textit{Tcl\_LoadFile} is given as:

\begin{quote}
EXTERN int \textbf{Tcl\_LoadFile}( Tcl\_Interp *\textit{interp}, Tcl\_Obj *\textit{pathPtr}, const char *\textit{symbols}[], int \textit{flags}, void *\textit{procPtrs}, Tcl\_LoadHandle *\textit{handlePtr});
\end{quote}

The meaning of the \textit{flags} parameter is not defined in TIP \#357, except that the current value should be 0. This TIP defines the meaning of the first two bits of this parameter:
\begingroup\small\begin{verbatim}
#define TCL_LOAD_GLOBAL 1
#define TCL_LOAD_LAZY 2
\end{verbatim}
\endgroup

Any combination (logical or) of those two bits can be given to the \textit{flags} parameter. The remaining bits are meant for future extension and are currently ignored, but should be set to 0.

The \textbf{load} command will get two new options:

Current specification:

\begin{quote}
\textbf{load} \textit{fileName} ?\textit{packageName} ?\textit{interp}??
\end{quote}

Recommended specification:

\begin{quote}
\textbf{load} ?\textbf{-global}? ?\textbf{-lazy}? ?\textbf{-{}-}? \textit{fileName} ?\textit{packageName} ?\textit{interp}??
\end{quote}

\section{Discussion}

Not all platforms may support library loading to a degree required for this TIP functionality. In that case, the additional options just act as if they were not there. The reference implementation works on most modern UNIX systems and MacOSX, which use \textit{dlopen()} or \textit{NSLinkModule()}. Windows does not allow lazy symbol resolution or global scoping, so the options have no effect on Windows.

The \textbf{load} command will determine the use of the new form by checking if more than one argument is given and the first argument starts with a \textbf{-}. This should not affect any existing extensions, as dynamic library filenames beginning with \textbf{-} are rare.

Note that use of the \textbf{-global} or \textbf{-lazy} option may lead to crashes in your application later (in case of symbol conflicts resp. missing symbols), which cannot be detected during the \textbf{load}. So, only use this when you know what you are doing, you will not get a nice error message when something is wrong with the loaded library.

\section{Examples}

Load a module with the defaults (local scoping, ``now'' resolution)
\begingroup\small\begin{verbatim}
 load module.so
\end{verbatim}
\endgroup

Load the module with global scoping and ``now'' resolution
\begingroup\small\begin{verbatim}
 load -global module.so
\end{verbatim}
\endgroup

Load the module with global scoping and lazy resolution
\begingroup\small\begin{verbatim}
 load -global -lazy module.so
\end{verbatim}
\endgroup

\section{Reference Implementation}

A reference implementation is available in the \textbf{frq-3579001} branch; see \url{https://core.tcl.tk/tcl/timeline?r=frq-3579001}

\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 \#357]{tip357}
Kevin Kenny,
\emph{Export TclLoadFile},
on-line at \url{http://purl.org/tcl/tip/357.html}
\end{thebibliography}
\end{document}
