\documentclass[]{article}
\usepackage{amsmath,graphicx,supertabular,hyperref,tabularx,ifthen}
\title{TIP \#10: Tcl I/O Enhancement: Thread-Aware Channels}
\date{November 08, 2000}
\author{Andreas Kupries}
\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 \#10}&\textbf{Tcl I/O Enhancement: Thread-Aware Channels}\\\hline
Author&

Andreas Kupries \tipmail{a.kupries}{westend.com}
\\
Created&Wednesday, \(\text{8}^{\text{th}}\) November 2000\\
Type&Project\\
Tcl Version&\(8.4\)\\
State&Final\\
Vote&Done\\
Version&\tipversion$Revision: 1.6 $\\
Post History&\\
\hline\end{tabularx}\end{center}
\thispagestyle{empty}\pagestyle{empty}
\begin{tipabstract}

This TIP describes how to change the generic I/O layer in the Tcl core to make channels aware of the thread they are managed by.
\end{tipabstract}
\tableofcontents\setcounter{page}{0}\clearpage\pagestyle{plain}

\section{Rationale}

To explain the motives behind this TIP first a short look at the history of channels and threading.

In ancient times the Tcl core was not thread safe and did not employ threads. All channels belonged to a single interpreter. Later on interpreter hierarchies were introduced and the ability to move or share a channel between the interpreters in a hierarchy. When the Tcl core was made thread safe a short time after the ability to move channels between threads was added (Helper APIs in the core, main functionality in the Thread extension). The goal behind these modifications was to enable the creation of stream-like communication paths between threads to complement the message based facilities (thread send). The modifications were only a partial success because an in-depth analysis of the relevant data structures showed that the sharing of a channel between threads is not possible with the current design, only moving. This was implemented to allow at least the dispatcher- / worker-thread pattern for structuring a threaded application.

In further pursuit of the original goal the currently chosen approach is to define a channeltype where two channels are connected internally through in-memory fifo buffers where access to these shared structures is protected by mutexes.

During the implementation of fileevents for this channeltype it was discovered that an efficient implementation of this part is \textit{not} possible because of the inability to post file events to the eventqueue of the thread the other channel of the pair resides in. An API to post such events is available (\textit{Tcl\_ThreadQueueEvent}), but not the information which thread actually manages the other channel. Because of this the current implementation of the channeltype uses polling based upon timer events posted by each side/thread to itself to manage file events in a rather inefficient way.

\section{Reference implementation}

This TIP now proposes to change the internals of the generic I/O layers in the core so that
\begin{enumerate}
\item{}
Channels know the thread they are managed by, and
\item{}
are able to deliver this information to an extension querying the core.
\end{enumerate}

This then allows the two sides of the channeltype mentioned above to post events to each other, facilitating an efficient implementation of fileevents.

The changes necessary to accomplish this are:
\begin{enumerate}
\item{}
Extend the structure \textit{ChannelState} in tclIO.h with a new field of type \textit{Tcl\_ThreadId} to hold the id of the thread currently managing all channels with this state. Note: This structure is shared by all channels in a stack of transformations.
\item{}
Modify the procedure \textit{Tcl\_CreateChannel} to store the Id of the current thread in the \textit{ChannelState} of the new channel. This information can be obtained with \textit{Tcl\_GetCurrentThread}. It is \textit{not} necessary to modify \textit{Tcl\_StackChannel} as the thread information is already part of the state when it is called, and won't be changed by the call.
\item{}
If some sort of NIL/NULL value meaning ``No thread'' is available for \textit{Tcl\_ThreadId}, then we should modify \textit{Tcl\_CutChannel} to insert this value into the state of the channel it is called with, as this channel will not be managed by any thread afterward (the procedure removes the channel from the list of all channels managed by the current thread).
\item{}
Modify \textit{Tcl\_SpliceChannel} in the same manner as \textit{Tcl\_CreateChannel} as the channel will be managed by the current thread afterward (The procedure adds the channel to the list of all channels managed by the current thread).
\item{}
Declare a new API function to retrieve the Id of the managing thread from a channel. Add this declaration to generic/tcl.decls and implement the function in the file generic/tclIO.c. I propose \textit{Tcl\_GetChannelThread} as the name of this new API function.
\end{enumerate}

A patch implementing all of the changes described above and additionally extending the documentation and the test-suite is available here: \url{http://www.cs.man.ac.uk/fellowsd-bin/TIP/10.patch}

\section{Copyright}

This document has been placed in the public domain.

\section{Colophon}

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