\documentclass[]{article}
\usepackage{amsmath,graphicx,supertabular,hyperref,tabularx,ifthen}
\title{TIP \#469: A Callback for Channel-Exception Conditions}
\date{April 16, 2017}
\author{Andreas Leitgeb}
\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 \#469}&\textbf{A Callback for Channel-Exception Conditions}\\\hline
Author&

Andreas Leitgeb \tipmail{avl}{logic.at}
\\
Created&Sunday, \(\text{16}^{\text{th}}\) April 2017\\
Type&Project\\
Tcl Version&\(8.7\)\\
State&Draft\\
Vote&Pending\\
Version&\tipversion$Revision: 1.3 $\\
Keywords&Tcl, event handling\\
Post History&\\
\hline\end{tabularx}\end{center}
\thispagestyle{empty}\pagestyle{empty}
\begin{tipabstract}

This TIP proposes to extend the \textbf{fileevent} Tcl command to also accept the keyword \textbf{exception} for its second argument. This will allow to register a callback for the specific event that the OS reports an exception on the channel, while ignoring read- or writability.
\end{tipabstract}
\tableofcontents\setcounter{page}{0}\clearpage\pagestyle{plain}

\section{Rationale}

Tcl already allows registering for exceptions in its C-API function Tcl\_CreateChannelHandler(). This TIP merely enables the command \textbf{fileevent} to pass TCL\_EXCEPTION for the mask in the call to Tcl\_CreateChannelHandler().

On Linux, there exist special ``files'' that are always readable or writable without blocking, but certain (hardware-related) events are reported as exceptions on the channel. The example at hand is the ``sysfs''-API for GPIO (general purpose input output) where level-changes on GPIO pins are reported as exceptions on the channel. For details see [\url{https://www.kernel.org/doc/Documentation/gpio/sysfs.txt}] and the paragraphs about ``value''.

Listening for readable plus exceptions (as Tcl automatically does when asking for readable event) doesn't help here, because then the event would continuously fire, as reading the current level on a pin never blocks.

The only way to react to level-changes (short of busy-looping) is to have the internal select/poll call specify exclusively the exception notification for that channel.

\section{Specification}

This document proposes to add the keyword \textbf{exception} to the \textbf{fileevent} command, where so far only \textbf{readable} and \textbf{writable} are allowed.

If \textbf{exception} is given as event specifier, then a handler script is registered, cleared or queried just like with \textbf{readable} or \textbf{writable}.

Since \textbf{readable} or \textbf{writable} already check for exception as well, registering an exception event for a channel that already has readable and/or writable handlers registered makes little sense, but allowing it does not raise any issues that having both readable and writable handlers wouldn't already have, so being fussy about it would confuse more than it could help to avoid confusion.

\section{Alternatives}

The \textit{piio} extension provides event registration on its own, but its support for certain IO-chipsets lags behind the sysfs-API.

With \textbf{exception} becoming its own event type, then \textbf{readable} and \textbf{writable} would no longer need to also fire on exceptions, but compatibility forbids this particular follow-up change.

\section{Compatibility}

No incompatibilities are introduced.

\section{Reference Implementation}

A really bare-bones reference implementation is available as a patch [\url{http://paste.tclers.tk/4231}]. Also, a branch named tip-469 in fossil has been created: [\url{https://core.tcl.tk/tcl/timeline?r=tip-469}].

A thus-patched tclsh can successfully wait for input-level changes on TIP-author's ``nano-pi'' raspberryPI-like platform with a chipset not yet supported by piio.

Documentation and test updates yet to be done.

\section{Copyright}

This document has been placed in the public domain.

\section{Colophon}

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