\documentclass[]{article}
\usepackage{amsmath,graphicx,supertabular,hyperref,tabularx,ifthen}
\title{TIP \#456: Extend the C API to Support Passing Options to TCP Server Creation}
\date{November 18, 2016}
\author{LemonBoy, lime boy}
\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 \#456}&\textbf{Extend the C API to Support Passing Options to TCP Server Creation}\\\hline
Author&

LemonBoy \tipmail{that.lemon}{gmail.com}
\par
lime boy \tipmail{thatlemon}{gmail.com}
\\
Created&Friday, \(\text{18}^{\text{th}}\) November 2016\\
Type&Project\\
Tcl Version&\(8.7\)\\
State&Final\\
Vote&Done\\
Version&\tipversion$Revision: 1.6 $\\
Keywords&Tcl, socket, SO\_REUSEPORT, SO\_REUSEADDR\\
Post History&\\
\hline\end{tabularx}\end{center}
\thispagestyle{empty}\pagestyle{empty}
\begin{tipabstract}

The \textbf{Tcl\_OpenTcpServer} interface doesn't provide enough flexibility as experienced during the implementation of the scaffolding necessary to support the \textbf{SO\_REUSEPORT} flag for sockets. This TIP adds that capability through a new API function, \textbf{Tcl\_OpenTcpServerEx}, that takes extra options.
\end{tipabstract}
\tableofcontents\setcounter{page}{0}\clearpage\pagestyle{plain}

\section{Rationale}

Currently there's no way to pass extra informations to \textbf{Tcl\_OpenTcpServer} which is the function that does the heavy lifting by wrapping the socket creation and connection phase.

For example, during the implementation of a \textbf{-reuseport} option for the \textbf{socket} command, a roadblock was hit since informing \textbf{Tcl\_OpenTcpServer} about the presence of the new flag was only possible via hacks such as exploiting the upper unused bits of the port parameter or its sign bit.

A clean solution that also paves the way to the implementation of other switches (such as one for the SO\_REUSEADDR flag) is to introduce another function named \textbf{Tcl\_OpenTcpServerEx} whose signature closely matches the \textbf{Tcl\_OpenTcpServer} but allows passing a set of flags to customize its behaviour.

Following the aforementioned changes to the C API the \textbf{socket} command is enhanced with two new options allowing the user to take advantage of the newly introduced flags.

\section{Specification}

A \textbf{Tcl\_OpenTcpServerEx} function is introduced with the following signature:

\begin{quote}
Tcl\_Channel \textbf{Tcl\_OpenTcpServerEx}(Tcl\_Interp *\textit{interp}, const char * \textit{service}, const char *\textit{myHost}, unsigned int \textit{flags}, Tcl\_TcpAcceptProc *\textit{acceptProc}, ClientData \textit{acceptProcData})
\end{quote}

Most arguments are identical to \textbf{Tcl\_OpenTcpServer} with the exception of the \textit{port} parameter being replaced by the \textit{service} one taking a string instead of an integer. Two entries for the \textit{flags} bitset are defined by this TIP:
\begin{itemize}
\item{}
\textbf{TCL\_TCPSERVER\_REUSEADDR} --- indicate that the socket flag SO\_REUSEADDR (or equivalent) should be set.
\item{}
\textbf{TCL\_TCPSERVER\_REUSEPORT} --- indicate that the socket flag SO\_REUSEPORT (or equivalent) should be set.
\end{itemize}

The \textbf{Tcl\_OpenTcpServer} function is then rewritten to be an alias of \textbf{Tcl\_OpenTcpServerEx} with the \textbf{flags} parameter set by default to TCL\_TCPSERVER\_REUSEADDR so that we keep the API and behaviour compatible with the previous Tcl versions.

As for the Tcl side, the \textbf{socket} command gains two new optional switches that are only valid for server sockets: \textbf{?-reuseaddr boolean?} and \textbf{?-reuseport boolean?}, both accepting a boolean argument to either turn off or on the selected behaviour.

\section{Reference Implementation}

Please refer to the \textit{tip-456} branch of the core Tcl repository.

\section{Backwards Compatibility}

Since \textbf{Tcl\_OpenTcpServer} can be easily re-implemented in terms of \textbf{Tcl\_OpenTcpServerEx} the old behaviour is retained.

The \textbf{socket} command defaults to \textbf{-reuseaddr} set to \textit{yes} as it was already doing before, the user is now able to turn off this behaviour by using \textbf{-reuseaddr no}.

\section{Copyright}

This document has been placed in the public domain.

\section{Colophon}

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