\documentclass[]{article}
\usepackage{amsmath,graphicx,supertabular,hyperref,tabularx,ifthen}
\title{TIP \#468: Support Passing TCP listen Backlog Size Option to TCP Socket Creation}
\date{April 03, 2017}
\author{Shannon Noe}
\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 \#468}&\textbf{Support Passing TCP listen Backlog Size Option to TCP Socket Creation}\\\hline
Author&

Shannon Noe \tipmail{shannon.noe}{flightaware.com}
\\
Created&Monday, \(\text{3}^{\text{rd}}\) April 2017\\
Type&Project\\
Tcl Version&\(8.7\)\\
State&Draft\\
Vote&Pending\\
Version&\tipversion$Revision: 1.1 $\\
Keywords&Tcl, socket, SOMAXCONN\\
Post History&\\
\hline\end{tabularx}\end{center}
\thispagestyle{empty}\pagestyle{empty}
\begin{tipabstract}

This TIP adds the ability to control the TCP backlog depth used by the \textit{listen} system call within the \textbf{socket} Command. The API function, \textbf{Tcl\_OpenTcpServerEx}, will be extended to allow the passing of the backlog value. Currently, the SOMAXCONN macro is used as the default. Backlog values are hard coded to a minimum of 100. The backlog values of 1 and 0 are useful on the Linux platform.
\end{tipabstract}
\tableofcontents\setcounter{page}{0}\clearpage\pagestyle{plain}

\section{Rationale}

Modern Linux TCP supports the kernel managing the listen queue for TCP sockets. Multiple processes open the same socket address and ports with SOREUSEADDR and SOREUSEPORT. Each process then uses a backlog value of 1 to process a single connection at a time. This is explained in detail on this website \url{http://veithen.github.io/2014/01/01/how-tcp-backlog-works-in-linux.html}

Tighter control over this would allow Tcl scripts to have tighter control over whether to support a large backlog of sockets waiting to be opened. (Exceeding the limit would cause the OS to automatically reject the socket connection, which might be preferable in some high-availability situations to being blocked for an unknown amount of time.)

\section{Specification}

A \textbf{Tcl\_OpenTcpServerEx} function will be changed to add a \textit{backlog} parameter with this signature:

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

As for the Tcl side, the \textbf{socket} command gains a new optional switch that are only valid for server sockets: ?\textbf{-backlog} \textit{int}?. Omitting the parameter will cause the default value to be used.

Tcl code includes local macroâ---™s for SOMAXCONN which override all platforms values for SOMAXCONN. This makes backwards compatibility easier. We only need to preserve the macro value in the default code path.

\section{Reference Implementation}

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

\section{Backwards Compatibility}

The \textbf{Tcl\_OpenTcpServerEx} will retain the old behavior by default as SOMAXCONN. The SOMAXCONN is defined by macros in the Tcl source. All Tcl code paths with a listen() system call pass a backlog value. No new code paths are introduced, only new values for the listen backlog parameter.

The \textbf{socket} command will be backwards compatible. The default \textbf{-backlog} parameter is set to \textit{SOMAXCONN}. Omission of the new parameter provides the current behavior.

\section{Copyright}

This document has been placed in the public domain.

\section{Colophon}

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