\documentclass[]{article}
\usepackage{amsmath,graphicx,supertabular,hyperref,tabularx,ifthen}
\title{TIP \#427: Introspection of Asynchronous Socket Connection}
\date{March 16, 2014}
\author{Reinhard Max, Harald Oehlmann, Reinhard Max}
\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 \#427}&\textbf{Introspection of Asynchronous Socket Connection}\\\hline
Author&

Reinhard Max \tipmail{max}{suse.com}
\par
Harald Oehlmann \tipmail{oehhar}{users.sourceforge.net}
\par
Reinhard Max \tipmail{max}{tclers.tk}
\\
Created&Sunday, \(\text{16}^{\text{th}}\) March 2014\\
Type&Project\\
Tcl Version&\(8.6.4\)\\
State&Final\\
Vote&Done\\
Version&\tipversion$Revision: 1.13 $\\
Keywords&async socket connect, introspection, IPV6\\
Post History&\\
\hline\end{tabularx}\end{center}
\thispagestyle{empty}\pagestyle{empty}
\begin{tipabstract}

This TIP describes a method to introspect the asynchronous connection process by an extension of the \textbf{fconfigure} interface in addition to \textbf{fconfigure -error}. This will enable better control over the asynchronous connection process, even in cases where the event loop is not in use.
\end{tipabstract}
\tableofcontents\setcounter{page}{0}\clearpage\pagestyle{plain}

\section{Rationale}

The \textbf{socket} core command supports two ways to establish a client socket, \textit{synchronous} and \textit{asynchronous}. In synchronous mode (which is the default) the command does not return until the connection attempt has completed (established or failed).

In asynchronous mode (\textbf{-async option}) the command returns after DNS lookup and the connection is established in the background. This is useful in situations where it is undesirable that a process or thread blocks for completing a synchronous connection attempt. Classically, an asyncronously connecting socket would indicate that it had connected (or failed to connect) by becoming writeable, which \textbf{fileevent writable} can be used to detect.

A DNS name may have multiple IP addresses associated, e.g. for IPv4/IPv6 dual stack hosts or for fail safety or load balancing reasons as it is the case for google.com as of this writing.

In Tcl 8.5 the socket command only tried to connect to a single IPv4 address that was randomly picked from the list returned by DNS. In Tcl 8.6, the socket command tries to connect to all the IP addresses of a DNS name in turn until one succeeds or all have failed.

This caused the following changes to the \textbf{socket -async} command from Tcl 8.5 to 8.6:
\begin{itemize}
\item{}
The socket introspection options to \textbf{fconfigure} (i.e., \textbf{-error}, \textbf{-sockname} and \textbf{-peername}) can change between successive invocations while the connection is in progress as they reflect the state of the internal loop over the IP addresses.
\item{}
The event loop must run in order to allow looping over the various possible IP addresses of a host.
\end{itemize}

The usage of \textbf{socket -async} is seen as helpful even without the event loop. An example is an application, which checks a list of hosts for a connection. The application may start many background socket connects, do something else, and then collect the results. Without the event loop (i.e., a \textbf{fileevent writable}), there is no non-blocking way to discover if the asynchronous connect has completed.

In addition, the following future points may be considered:
\begin{itemize}
\item{}
The connection process may internally get delegated to its own thread; this would allow the connection process to be asynchronous without requiring the event loop.
\item{}
A future Windows implementation may use the Vista+ API \textit{WSAConnectByList} (once we do not support Windows XP any more). Using this, no own looping over the addresses is necessary. It allows the connection process to be a single OS call, but does not allow inspection of the different connection steps.
\end{itemize}

\section{Proposed Change}

\subsection{Current Introspection Change}

The introspection functions should act as follows during an asynchronous connection process:
\begin{itemize}
\item{}
\textbf{fconfigure -error} will return the empty string (no error)
\item{}
\textbf{fconfigure -sockname} will return the empty string
\item{}
\textbf{fconfigure -peername} will return the empty string
\end{itemize}

\subsection{Introspection Command to Inspect a Running Asynchronous Connect}

An additional introspection function should inform if the asynchronous connect is running or if it has terminated:

\begin{quote}
\textbf{fconfigure} \textit{channel} \textbf{-connecting}
\end{quote}

This option returns \textbf{1} as long as a socket is still in the process of connecting asynchronously and 0 when the asynchronous connection has completed (succeeded or failed) or the socket was opened synchronously.

\subsection{Non-Event Loop Operation}

If the event loop runs, the state machine of a (possibly multiple-address try) async connection proceeds within an internal callback.

In addition to that (for the case the event loop does currently not run), it proceeds whenever a channel operation is attempted on the socket\_
\begin{itemize}
\item{}
nonblocking I/O and [fconfigure] will advance it by one step (i.e. do whatever is doable without waiting).
\item{}
blocking I/O will advance it to completion, in essence meaning ``switch back to synchronous connect, and in case of success, do the blocking I/O I asked for''.
\end{itemize}

\section{Use Case of the Connecting Option}

My own use case for the proposed option \textbf{-connecting} is as follows. A TCL script is started within Rivet to do two tasks:
\begin{itemize}
\item{}
Verify many URLs for existance (e.g. open a socket and do a head request).
\item{}
Do some data base work.
\end{itemize}

I don't use the event loop to get a linear program with controlled order.

So the program flow is as follows:
\begin{itemize}
\item{}
Open async sockets for all links to verify:

\textit{foreach host \$hosts; set h(\$host) [socket -async \$host 23]}
\item{}
Do some data base work which takes time.
\item{}
Check all open sockets and eventually advance the state machine by calling \textbf{-connecting}:

\textit{foreach host \$hosts; if \{[fconfigure \$h(\$host) -connecting]\} \{Connected \$host\}}
\item{}
Do some more data base work which takes time.
\item{}
Check \textbf{-connecting} and react until there are no open sockets any more.
\end{itemize}

I have cut the data base processing into two parts; I assume there are normally two IP's to try, one IPV6 and one IPV4.

\section{Alternatives}

Two alternatives for the behavior of \textbf{fconfigure -sockname} and \textbf{fconfigure -peername} are:
\begin{itemize}
\item{}
If there is only one destination IP address, return this before the connection is really established. This may also happen if the socket has processed its \textit{bind()} system call in such a way that it knows it will not attempt another, and is currently processing its \textit{connect()} to the remote host.
\item{}
If an asynchronous connect is running, raise an error.
\end{itemize}

These are open to discussion.

\section{Implementation}

The fossil branch \textit{tip-427} contains an implementation of these extensions.

\section{Copyright}

This document has been placed in the public domain.

\section{Colophon}

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