\documentclass[]{article}
\usepackage{amsmath,graphicx,supertabular,hyperref,tabularx,ifthen}
\title{TIP \#451: Modify [update] to Give Full Script Access to Tcl\_DoOneEvent}
\date{August 10, 2016}
\author{Colin McCormack}
\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 \#451}&\textbf{Modify [update] to Give Full Script Access to Tcl\_DoOneEvent}\\\hline
Author&

Colin McCormack \tipmail{mcccol}{gmail.com}
\\
Created&Wednesday, \(\text{10}^{\text{th}}\) August 2016\\
Type&Project\\
Tcl Version&\(8.7\)\\
State&Draft\\
Vote&Pending\\
Version&\tipversion$Revision: 1.2 $\\
Keywords&Tcl, event loop\\
Post History&\\
\hline\end{tabularx}\end{center}
\thispagestyle{empty}\pagestyle{empty}
\begin{tipabstract}

This TIP add flags to \textbf{update} to represent all the flag values available to the underlying API, \textit{Tcl\_DoOneEvent()}, exposing them to script access.
\end{tipabstract}
\tableofcontents\setcounter{page}{0}\clearpage\pagestyle{plain}

\section{Rationale}

The \textbf{update} command provides a way into the event loop in addition to \textbf{vwait}. Because the Tcl event system derived historically from Tk, \textbf{update} was written specifically to support Tk's window and idle events. When Tcl adopted the event system for timers and file events, the \textbf{update} command was anomalously not updated to cater for these new event types.

The reason this anomaly is worth correcting is that Tcl\_DoOneEvent is the actual entry into the event loop and there is no good or sufficient reason for \textbf{update} to limit the flags to those specific to Tk only.

While \textbf{vwait} provides a reasonable way into and out of the event loop, there's no good reason to impose that communication mechanism on the application when there are other approaches possible, arguably more useful, and amply provided for by the underlying C implementation.

\section{Proposal}

The \textbf{update} command should have the following flags added to it:
\begin{itemize}
\item{}
\textbf{idletasks} --- process any pending window events or idle events, do not wait (this is as currently supported)
\item{}
\textbf{window} --- process window events
\item{}
\textbf{file} --- process file events
\item{}
\textbf{timer} --- process timer events
\item{}
\textbf{onlyidle} --- process only idle events
\item{}
\textbf{all} --- process all events
\item{}
\textbf{wait} --- wait until at least one event has been processed
\item{}
\textbf{nowait} --- return immediately if no events are pending.
\end{itemize}

 and they should be painted Pantone 13-1520

The somewhat klunky and denormalised logical form of these flags is imposed by the requirement to minimally disrupt existing \textbf{update} functionality.

\section{Reference Implementation}

A reference implementation is available in Tcl core fossil under tag \textit{updateextended}.

\section{Use Case 1}

Application of \textbf{after idle} constructs a collection of \textit{idle tasks.} An \textit{idle task} represents something to be performed when no events are pending. This proposal exposes the idle state directly to a Tcl script and the application can do what it will in that state.

Use Case Summary: ``I would like to handle \textit{idle tasks} in some particular or specific order, at script level.''

\section{Use Case 2}

A script may have accepted network file i/o for some time, and have a number of pending background (aka idle) tasks to perform as a result of that i/o. It may wish to throttle acceptance of connections, or further read events, pending that background processing.

Use Case Summary: As a special case of ``I would like direct control over my 'idle' time.'', ``I would like to throttle network input.''

\section{Rejected Alternatives}

One could create a new command for this functionality, but the minimal impact on most Tcl users doesn't seem to me to warrant additional population of the :: command namespace.

One could move \textbf{update} out of Tcl altogether (to avoid its explicit dependency on Tk events) into Tk. This would open up the :: namespace to a more general event-handling mechanism.

\section{Copyright}

This document has been placed in the public domain. In legislations where this concept does not exist the CC0 license applies.

\section{Colophon}

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