\documentclass[]{article}
\usepackage{amsmath,graphicx,supertabular,hyperref,tabularx,ifthen}
\title{TIP \#400: Setting the Compression Dictionary and Other 'zlib' Updates}
\date{March 30, 2012}
\author{Donal K. Fellows}
\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 \#400}&\textbf{Setting the Compression Dictionary and Other 'zlib' Updates}\\\hline
Author&

Donal K. Fellows \tipmail{dkf}{users.sf.net}
\\
Created&Friday, \(\text{30}^{\text{th}}\) March 2012\\
Type&Project\\
Tcl Version&\(8.6\)\\
State&Final\\
Vote&Done\\
Version&\tipversion$Revision: 1.7 $\\
Keywords&Tcl, zlib\\
Post History&\\
\hline\end{tabularx}\end{center}
\thispagestyle{empty}\pagestyle{empty}
\begin{tipabstract}

Sometimes it is necessary to set the compression dictionary so that a sequence of bytes may be compressed more efficiently (and decompressed as well). This TIP exposes that functionality. It also reduces the number of inconsistencies in the \textbf{zlib} command.
\end{tipabstract}
\tableofcontents\setcounter{page}{0}\clearpage\pagestyle{plain}

\section{Rationale}

The SPDY protocol extensions to HTTP require the seeding of the zlib compression dictionary (which greatly improves the performance of compression on small amounts of data, such as HTTP headers). In order to allow a pure Tcl implementation of the SPDY protocol, it is therefore necessary to provide a mechanism whereby the compression dictionary (a byte-array, normally up to 262 bytes long according to the zlib documentation).

There is to be no mechanism for retrieving the compression dictionary generated by the compression engine; there is no API for doing that.

A side issue discovered during working on this TIP was that there was considerable variation in what could be achieved by various parts of the API. In partcular, it was identified that the API was inconsistent, providing access to some features in ``simplified'' parts of the API that could not be controlled from the ``advanced'' parts (e.g., there was no way to set the GZIP header descriptor with \textbf{zlib stream gzip}).

\section{Proposed Changes: Tcl}

\subsection{Changes to the Channel Transforms}

The \textbf{zlib push} command will gain two extra options, \textbf{-dictionary} and \textbf{-limit}:

\begin{quote}
\textbf{-dictionary} \textit{bytes}
\end{quote}

This option will provide a compression dictionary to be used (\textit{bytes} is a byte-array used to initialize the compression engine) which will be supplied to the zlib compression engine at the correct moment during compression or provided on request of the compression engine on decompression. The \textit{bytes} argument must be non-empty if given (we will not enforce a limit on the length of the dictionary, but using an excessively long one may cause the zlib engine to issue errors). This will be illegal to use with \textbf{gzip} and \textbf{gunzip} streams, and its use with raw (\textbf{deflate}) streams will be not recommended due to the difficulty of detecting whether a compression dictionary was applied; the zlib-format header adds very little overhead. This value can also be set with \textbf{chan configure}, though doing so after data has started to be pushed through the compression engine (except if an error requesting a compression dictionary was received) is not recommended.

\begin{quote}
\textbf{-limit} \textit{size}
\end{quote}

This option (valid on the three decompressing transforms only, and where \textit{size} must be a positive integer of no more than 0x10000) allows for control over the size of chunks read from the underlying channel for feeding into the decompression engine. Its default is 1, which makes for the correct behavior under the widest range of conditions, but at a significant cost in terms of computational complexity: when the underlying data source is known to never block for long and to have complete data, a larger value can be used which will greatly improve performance. This value can be set at runtime using \textbf{chan configure}.

\subsection{Changes to the Streams}

The \textbf{zlib stream} command will also gain some complexity. In particular, the \textbf{compress}, \textbf{decompress}, \textbf{deflate} and \textbf{inflate} subcommands will gain the ability to take an extra \textbf{-dictionary} \textit{bytes} pair of options (same interpretation as above), as will the \textbf{add} and \textbf{put} subcommands of the stream instance command.

In addition (as a correction to the functionality originally proposed in \cite{tip234}) the \textbf{zlib stream gzip} subcommand will also gain the ability to take:

\begin{quote}
\textbf{-header} \textit{dict}
\end{quote}

(where \textit{dict} is a Tcl dictionary such as is passed to the \textbf{-header} option to \textbf{zlib gzip} and not a compression dictionary), and the stream instance subcommand will gain a \textbf{header} subcommand to retrieve the gzip header (it will be an error to use it on a stream not produced by \textbf{zlib stream gunzip}). In order to facilitate the above change, the compression level used in that case will be altered to be specified via an option:

\begin{quote}
\textbf{-level} \textit{compressionLevel}
\end{quote}

\section{Proposed Change: C}

At the C level, one additional function will be provided:

\begin{quote}
void \textbf{Tcl\_ZlibStreamSetCompressionDictionary}(Tcl\_ZlibStream \textit{zshandle}, Tcl\_Obj *\textit{compressionDictionaryObj})
\end{quote}

This sets the compression dictionary for a particular stream to the given (byte-array) Tcl\_Obj, which will be duplicated. It is the caller's responsibility to dispose of the object passed in if they allocated it; they may do so immediately after calling this function.

\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 \#234]{tip234}
Pascal Scheffers,
\emph{Add Support For Zlib Compression},
on-line at \url{http://purl.org/tcl/tip/234.html}
\end{thebibliography}
\end{document}
