\documentclass[]{article}
\usepackage{amsmath,graphicx,supertabular,hyperref,tabularx,ifthen}
\title{TIP \#428: Produce Error Dictionary from 'fconfigure -error'}
\date{March 16, 2014}
\author{Harald Oehlmann, Harald Oehlmann}
\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 \#428}&\textbf{Produce Error Dictionary from 'fconfigure -error'}\\\hline
Author&

Harald Oehlmann \tipmail{oehhar}{users.sourceforge.net}
\par
Harald Oehlmann \tipmail{harald.oehlmann}{users.sourceforge.net}
\\
Created&Sunday, \(\text{16}^{\text{th}}\) March 2014\\
Type&Project\\
Tcl Version&\(8.7\)\\
State&Draft\\
Vote&Pending\\
Version&\tipversion$Revision: 1.26 $\\
Keywords&socket, non-blocking, error reporting, option dictionary\\
Post History&\\
\hline\end{tabularx}\end{center}
\thispagestyle{empty}\pagestyle{empty}
\begin{tipabstract}

This TIP proposes a new method which allows to return the error message and the error code of a background socket error (as reported by \textbf{fconfigure -error}), similar to the option dictionaries produced by catch and try and consumed by return.
\end{tipabstract}
\tableofcontents\setcounter{page}{0}\clearpage\pagestyle{plain}

\section{Rationale}

The error message of a background channel error may be retrieved and cleared by \textbf{fconfigure} \textit{channel} \textbf{-error}, but there is no access to the error code.

In addition, the error may not be handled in the TCL-like way using \textbf{catch} or \textbf{try} (or just let fail the program).

Specially the new \textbf{try} syntax (see example in the man page) is well suited to handle socket errors. Example:
\begingroup\small\begin{verbatim}
try {set h [socket $host $port]}\
trap {POSIX ECONNREFUSED} {} {
    # handle not open port
}
\end{verbatim}
\endgroup

Drivers mostly use POSIX errors to report issues where the error code is more portable than the error message (AFAIK).

To handle an error by \textbf{try}, the error must be thrown.

We are limited to an option to the command \textbf{fconfigure}, as this is implemented within the driver interface.

Throwing the error would change the semantics of \textbf{fconfigure} and thus should not happen (consensus on the core list). Instead, the new \textbf{fconfigure} operation should return the error message and the error code.

To finally throw the error, an utility function (\textbf{chan throwerror \$h}) may be defined in TCL. This is not part of this TIP.

\section{Proposed Change}

The option \textbf{fconfigure channel -error} should be extended to take an optional argument as follows:

\begin{quote}
\textbf{fconfigure} \textit{channel} \textbf{-error} \textit{?errorDictVar?}
\end{quote}

If the optional argument \textit{errorDictVar} is given, the following dict is written in the named variable of the caller environment:
\begin{itemize}
\item{}
 if there is no error, it should be set to \textbf{-code 0}
\item{}
 if there is an error, it should be set to \textbf{-code 1 -errorcode } \textit{errorCode}
\end{itemize}

This is executed in addition to the standard action of \textbf{fconfigure} \textit{channel} \textbf{-error}.

\section{Example}

Usage example with failing async connect:
\begingroup\small\begin{verbatim}
% set h [connect -async localhost 30001]
d00000af
% fileevent $h writable {set x 1}
% vwait x
% fconfigure $h -error errorDict
connection refused
% set errorDict
-code 1 -errorcode {POSIX ECONNREFUSED {connection refused}}
% close $h
\end{verbatim}
\endgroup

The following example demonstrates the implementation of \textbf{chan throwerror} eg to throw the error from the provided dict.
\begingroup\small\begin{verbatim}
proc throwerror {h} {
    set errorMessage [fconfigure $h -errorDict]
    return -options $errorDict $errorMessage
}
\end{verbatim}
\endgroup

\section{Alternatives}
\begin{itemize}
\item{}
 Revision 1.11 of this TIP proposed to really throw the error.
\item{}
 Revision 1.21 of this TIP proposed a new option to return an error dict directly.
\end{itemize}

\section{Implementation}

The tip is implemented in fossil branch \textbf{tip-428}.

\section{Remarks}

The idea of this semantics and a feasability study is from Reinhard Max.

\section{Copyright}

This document has been placed in the public domain.

\section{Colophon}

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