\documentclass[]{article}
\usepackage{amsmath,graphicx,supertabular,hyperref,tabularx,ifthen}
\title{TIP \#448: Update Tcl\_SetNotifier to Reinitialize Event Loop}
\date{May 24, 2016}
\author{Jeff Rogers}
\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 \#448}&\textbf{Update Tcl\_SetNotifier to Reinitialize Event Loop}\\\hline
Author&

Jeff Rogers \tipmail{dvrsn}{diphi.com}
\\
Created&Tuesday, \(\text{24}^{\text{th}}\) May 2016\\
Type&Project\\
Tcl Version&\(8.7\)\\
State&Draft\\
Vote&Pending\\
Version&\tipversion$Revision: 1.1 $\\
Keywords&Tcl, C API\\
Post History&\\
\hline\end{tabularx}\end{center}
\thispagestyle{empty}\pagestyle{empty}
\begin{tipabstract}

Tcl\_SetNotifier cannot be used in its current state to replace a notifier than has been initialized because pointers to the old initialized value are kept in the interp's private data. This TIP proposes a way to change that.
\end{tipabstract}
\tableofcontents\setcounter{page}{0}\clearpage\pagestyle{plain}

\section{Background}

The \textbf{Tcl\_SetNotifier} API was introduced to allow replacement of the built-in notifier; it works by setting hooks for various notifier functions that are called in place of the builtin functions.

It was expected that this function would only be called before the Tcl library had been initialized and any state had been set up; however this prevents it from being usable from a module loaded by a running interpreter.

This TIP proposes changing the behavior of this API to, in addition to setting the function hooks will shut down a running notifier and restart the notifier if it has been running previously. This is the minimum change necessary to allow a new notifier to be loaded from within a running interpreter.

It is probably not always possible to stop a running notifier, especially if event sources have been created. It is not necessarily easy to detect such failure; the proposed implementation doesn't even try. And there is no way to report such failure if it was detected. As such, this remains a somewhat dangerous interface to use.

With this change in place, it will be possible to load a new notifier implementation (e.g., a \textit{poll()} or \textit{libevent} based one) from a Tcl program, provided it is the very first thing done. An implementation of a poll-based notifier that requires the functionality in this TIP can be found at \url{http://fossil.etoyoc.com/sandbox/tcllib/artifact/ad30080cdee762a3}

\section{Description}

Change the implementation of \textbf{Tcl\_SetNotifier} to check if a notifier is currently running; if it is, the current notifier will be finalized before the new hooks are swapped in, and afterwards the notifier will be re-initialized. If the notifier is not already initialized, there is no change to functionality.

\section{Implementation}

A patch implementing the proposed change can be found at \url{http://fossil.etoyoc.com/sandbox/tcllib/artifact/b2b272a285811272}

\section{Copyright}

This document has been placed in the public domain.

\section{Colophon}

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