\documentclass[]{article}
\usepackage{amsmath,graphicx,supertabular,hyperref,tabularx,ifthen}
\title{TIP \#455: Extensions to [vwait]: Variable Sets and Scripted Access to Tcl\_DoOneEvent}
\date{October 07, 2016}
\author{Christian Werner}
\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 \#455}&\textbf{Extensions to [vwait]: Variable Sets and Scripted Access to Tcl\_DoOneEvent}\\\hline
Author&

Christian Werner \tipmail{chw}{ch-werner.de}
\\
Created&Friday, \(\text{7}^{\text{th}}\) October 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 generalizes the \textbf{vwait} command to allow waiting on zero, one, or more variable changes, on zero or more file events, to time-limit the wait, and to control on which kinds of events is to be waited by partially exposing the underlying API, namely \textit{Tcl\_DoOneEvent()}.
\end{tipabstract}
\tableofcontents\setcounter{page}{0}\clearpage\pagestyle{plain}

\section{Rationale}

One remarkable property of Tcl is the ability to add traces, i.e., the execution of callback functions, on certain operations affecting variables. The \textbf{vwait} command combines the variable trace facility with the (a) event loop, i.e., the (a) program main loop waiting and processing various types of events generated by I/O channels, time, and internal activities of the running Tcl program.

The current implementation of \textbf{vwait} allows to open an unconstrained event loop which is terminated by writing or unsetting exactly one global variable given as argument to \textbf{vwait}.

This proposal extends \textbf{vwait} to terminate its event loop on occurence of
\begin{enumerate}
\item{}
zero or more variable modifications
\setcounter{enumi}{1}
\item{}
readability/writability of zero or more file channels (usually sockets)
\setcounter{enumi}{2}
\item{}
an optional timeout specified as milliseconds as in the \textbf{after} command.
\end{enumerate}

Additional flags to \textbf{vwait} control which types of events are to be dealt with in its event loop, i.e. the underlying \textit{Tcl\_DoOneEvent()} API.

When more than one kind of active input (both, variables and file channels) is involved in an instance of \textbf{vwait}, another flag controls if any one of the inputs or all inputs must have been activated in order to terminate the event loop. This allows for scenarios, where \textbf{vwait} can be used as a kind of ``barrier'' getting broken if all required conditions are fulfilled, i.e., axe, saw, spade, fire accelerant, water, in order to demolish, burn down, extinct the glow, and finally bury the trellis-work fence.

However, in contrast to the illustrious demolition job, the order of occurence of events breaking that ``barrier'' is indeterminate.

If the \textbf{vwait} is constrained by a timeout, and the time limit is reached, its event loop terminates early and \textbf{vwait} indicates that timeout by a negative integer result. Otherwise, the return value is the remaining number of milliseconds (positive integer which can be zero) of the timeout constraint. This property combined with \cite{tip302} allows to implement (soft real-time) control loops.

\section{Proposal}

The \textbf{vwait} command shall have the following signature:

\begin{quote}
\textbf{vwait} \textit{variable-name} --- well known and implemented behaviour
\end{quote}

\begin{quote}
\textbf{vwait} \textit{options} ?\textit{variable-names}? --- all available enhanced features; more than one variable name may be given, in which case the wait will terminate when any of the variables are written to (unless the \textbf{-all} option below is given)
\end{quote}

where \textit{options} are:
\begin{description}
\item[-{}-]
 indicates end of options
\item[-all]
 all (except timeout) conditions must be met
\item[-nofileevents]
 don't consider file events
\item[-noidleevents]
 don't consider idle events
\item[-notimerevents]
 don't consider timer events
\item[-nowindowevents]
 don't consider window system events
\item[-readable \tiplangle{}chan\tiprangle{}]
 \textit{\tiplangle{}chan\tiprangle{}} becomes readable
\item[-timeout \tiplangle{}ms\tiprangle{}]
timeout in milliseconds; return the estimated number of milliseconds remaining in the wait.
\item[-writable \tiplangle{}chan\tiprangle{}]
 \textit{\tiplangle{}chan\tiprangle{}} becomes writable
\end{description}

The return value of \textbf{vwait} shall be the empty string except when the \textbf{-timeout} option is in effect (see above).

Where the combination of options doesn't make sense, or even conflicts, an appropriate error message shall be thrown, e.g., \textbf{-timeout} and \textbf{-notimerevents} can't be specified at the same time.

If all event types except idle events are excluded, the event loop (\textit{Tcl\_DoOneEvent}) shall be constrained by \textbf{TCL\_DONT\_WAIT}.

Interesting analogies to the \textbf{update} command can be infered: \textbf{vwait -{}-} is equivalent to \textbf{update}, \textbf{vwait -nofileevents -notimerevents -nowindoevents} is equivalent to \textbf{update idletasks}.

\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}
\begin{thebibliography}{TIP \#1}
\addcontentsline{toc}{section}{References}
\bibitem[TIP \#302]{tip302}
Alexandre Ferrieux,
Kevin Kenny,
\emph{Fix "after"'s Sensitivity To Adjustments Of System Clock},
on-line at \url{http://purl.org/tcl/tip/302.html}
\end{thebibliography}
\end{document}
