\documentclass[]{article}
\usepackage{amsmath,graphicx,supertabular,hyperref,tabularx,ifthen}
\title{TIP \#175: Add an -async Option to [open]}
\date{March 15, 2004}
\author{Neil Madden}
\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 \#175}&\textbf{Add an -async Option to [open]}\\\hline
Author&

Neil Madden \tipmail{nem}{cs.nott.ac.uk}
\\
Created&Monday, \(\text{15}^{\text{th}}\) March 2004\\
Type&Project\\
Tcl Version&\(9.0\)\\
State&Withdrawn\\
Vote&Pending\\
Version&\tipversion$Revision: 1.9 $\\
Post History&\\
\hline\end{tabularx}\end{center}
\thispagestyle{empty}\pagestyle{empty}
\begin{tipabstract}

This TIP propose to add an \textit{-async} option to the [open] command, with identical semantics to the \textit{-async} option to the [socket] command.
\end{tipabstract}
\tableofcontents\setcounter{page}{0}\clearpage\pagestyle{plain}

\section{Rationale}

With the introduction of Virtual File Systems (VFS, see \cite{tip17}), it is now possible to use [open] to access resources which are not available in the local file system. However, initial access to these resources may take some time (for instance, in an HTTP VFS, this requires an HTTP GET request to a remote server). Currently, while this request is being processed, the Tcl application will block waiting for a response. It may take several seconds before the open call returns, and control is passed back to the application. Delays of this length can cause problems, especially in applications with a Tk graphical user interface, which will not repond to events until the call has completed. Tcl provides mechanisms to avoid this initial blocking for the socket command, and in the HTTP package. However, this functionality is missing from the open command. For VFS to become useful for writing network code, this functionality needs to be added.

\section{Proposed Change}

This TIP proposes adding an \textit{-async} option to the open command. The new syntax for the open command would be:
\begingroup\small\begin{verbatim}
 open ?-async? ?--? name ?access? ?permissions?
\end{verbatim}
\endgroup

The ``-{}-'' marker is also proposed to signify ``end of options''. This is needed as \textit{name} can be anything, including the string ``-async'', and so some mechanism is needed to distinguish between the \textit{-async} option, and the name. This is in line with other commands which take multiple options.

When the \textit{-async} option is present, the open command will return immediately, without waiting for the underlying channel to be created and connected. If the channel is configured for blocking mode, a \textit{gets} or \textit{flush} that is done on the channel before the connection is made will wait until the connection is completed, or fails. If the channel is configured for nonblocking mode, then a \textit{gets} or \textit{flush} on the channel before the connection has been made will return immediately and \textit{fblocked} on the channel will return 1. This is exactly the same behaviour of the current implementation of the \textit{-async} option to the \textit{socket} command.

In addition, each VFS should support the \textit{-error} option to \textit{fconfigure} to allow scripts to determine the cause of an error when asynchronous opening fails. Furthermore, there needs to be a mechanism for notifying a script when an asynchronous open fails. This could be achieved by firing any fileevents (readable or writeable) which are registered on the resulting channel. This is the behaviour of [socket -async].

In order for this TIP to be implemented, there would have to be changes to the VFS layer in Tcl. There are at three ways to accomplish this:
\begin{enumerate}
\item{}
Extend Tcl\_FSOpenFileChannelProc to accept an \textit{async} argument, of type \textit{int}.
\setcounter{enumi}{1}
\item{}
Extend the Tcl\_Filesystem structure to add a new callback, alongside T\_FSOFCP. For instance, Tcl\_FSOpenFileChannelAsyncProc.
\setcounter{enumi}{2}
\item{}
(Ab)use the \textit{mode} parameter, and add a mask such as TCL\_ASYNC.
\end{enumerate}

Of these, option 3 is the easiest in terms of maintaining compatibility, but is not the nicest implementation.

\section{Reference Implementation}

A reference implementation does \textit{not} yet exist. The TIP author would be willing to implement any changes needed, but currently is not familiar with the internal workings of the VFS system.

\section{Questions}

Should the \textit{-async} option be supported when a command pipeline is being created?

Should a more general option passing mechanism be implemented? It is possible that some VFS implementations may require more information than is currently available in order to correctly create a channel (the \textit{-myaddr} and \textit{-myport} options to socket spring to mind). Would it be more sensible to consider a proposal for a more general option passing mechanism, to avoid further updates to the API in the future? This TIP does \textit{not} propose such a mechanism.

\section{Copyright}

This document has been placed in the public domain.

\section{Colophon}

\textit{TIP AutoGenerator --- written by Donal K. Fellows}
\begin{thebibliography}{TIP \#1}
\addcontentsline{toc}{section}{References}
\bibitem[TIP \#17]{tip17}
Vince Darley,
\emph{Redo Tcl's filesystem},
on-line at \url{http://purl.org/tcl/tip/17.html}
\end{thebibliography}
\end{document}
