\documentclass[]{article}
\usepackage{amsmath,graphicx,supertabular,hyperref,tabularx,ifthen}
\title{TIP \#239: Enhance the 'load' Command}
\date{January 26, 2005}
\author{Jeff Hobbs}
\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 \#239}&\textbf{Enhance the 'load' Command}\\\hline
Author&

Jeff Hobbs \tipmail{jeffh}{activestate.com}
\\
Created&Wednesday, \(\text{26}^{\text{th}}\) January 2005\\
Type&Project\\
Tcl Version&\(8.7\)\\
State&Draft\\
Vote&Pending\\
Version&\tipversion$Revision: 1.12 $\\
Post History&\\
\hline\end{tabularx}\end{center}
\thispagestyle{empty}\pagestyle{empty}
\begin{tipabstract}

This TIP proposes enhancing the Tcl \textbf{load} command with the ability to load arbitrary libraries and functions.
\end{tipabstract}
\tableofcontents\setcounter{page}{0}\clearpage\pagestyle{plain}

\section{Rationale}

The current Tcl \textbf{load} command limits itself operating within the context of loading Tcl extension libraries and nothing else, even though all the code is there for general library loading. With the introduction of the VFS and more extensions having prerequisite library dependencies, the ability to load arbitrary libraries would ease development of StarKits with these extensions. It will also provide a general mechanism to assist other developers get around the difficult process of cross-platform library loading.

\section{Specification}

Current specification:

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

Recommended specification:

\begin{quote}
\textbf{load} ?\textbf{-function} \textit{funcName}? ?\textbf{-interp} \textit{interp}? ?\textbf{-package} \textit{packageName}? ?\textbf{-keeplibrary}? ?\textbf{-{}-}? \textit{fileName\tipbar{}\tipbar{}libref}
\end{quote}

\begin{quote}
returns library pointer reference value
\end{quote}

The \textbf{-interp} option takes the place of the optional final \textit{interp} argument.

The \textbf{-package} option replaces the optional \textit{packageName} argument. The user specifies just the partial function name without the ``\_Init'' or ``\_SafeInit'', as before. The function is called with the Tcl interpreter to initialize as the sole argument. If this option is not specified, the name is inferred from the filename. If \textbf{-function} is specified, the Init call is not made.

The \textbf{-function} option takes a C function name to find the symbol of (via dlsym(), GetProcAddress(), or related function). If \textbf{-function} is specified, \textbf{-call} and \textbf{-interp} are ignored and the return value is the pointer location to the function, or 0 if it is not found. When this is used, the library is not closed upon success, it remains open until a call to \textbf{unload} is made.

The \textbf{-keeplibrary} option set a flag to indicate the library should not be unloaded by Tcl. This is needed in cases where the library may register functions (eg, via C's \textbf{atexit}) that are needed beyond the lifetime of Tcl finalization. This should only be used when necessary.

An error is thrown if the library cannot be loaded, otherwise a library pointer reference value is returned (unless \textbf{-function} is used).

\textbf{load} could take a library pointer reference as an argument for repeated \textbf{-function} requests.

I will also recommend obsoleting the existing \textbf{unload} call to use this new functional spec style. Current spec, to be unsupported (it's new in 8.5):

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

New specification:

\begin{quote}
\textbf{unload} ?\textbf{-interp} \textit{interp}? ?\textbf{-package} \textit{packageName}? ?\textbf{-keeplibrary}? ?\textbf{-{}-}? \textit{fileName\tipbar{}\tipbar{}libref}
\end{quote}

I removed the \textit{-nocomplain} option. The user should simply \textbf{catch} the command if they wish to suppress the types of errors that unload would throw.

I think that C functions should be made available as well for cross-platform access to the load functionality, but that is not specified in this TIP. This would need to account for users that may configure Tcl with -{}-disable-load (does anybody need that anymore?).

\section{Discussion}

Not all platforms may support library loading to a degree required for this TIP functionality. In that case, an error message will be thrown.

The use of \textbf{-{}-} as a option end switch was debated as unnecessary since there is only one fixed argument. JH likes the use of it for the completeness it gives the use of switches.

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.

Here is a reference to Perl's dynamic library loading functionality:

\url{http://aspn.activestate.com/ASPN/Perl/Products/ActivePerl/5.8/lib/DynaLoader.html}

\section{Examples}

For a package in a starkit, tls example with shared OpenSSL library shipped in package:
\begingroup\small\begin{verbatim}
 # $dir set by package mechanism
 if {[package provide starkit] ne ""} {
     load -call {} $dir/libopenssl.so
 }
 load $dir/libtls1.5.so
\end{verbatim}
\endgroup

This would handle the extracting of dependent libraries in starkits automatically (and their subsequent disposal).

Another example would be Oratcl 4.3's use of dynamic Oracle library callouts, which it has to do by hand due to the lack of this functionality in the core.

\section{Reference Implementation}

[To be uploaded to SourceForge and URL added to this TIP.]

\section{Copyright}

This document has been placed in the public domain.

\section{Colophon}

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