\documentclass[]{article}
\usepackage{amsmath,graphicx,supertabular,hyperref,tabularx,ifthen}
\title{TIP \#372: Multi-argument Yield for Coroutines}
\date{August 11, 2010}
\author{Colin McCormack}
\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 \#372}&\textbf{Multi-argument Yield for Coroutines}\\\hline
Author&

Colin McCormack \tipmail{colin}{chinix.com}
\\
Created&Wednesday, \(\text{11}^{\text{th}}\) August 2010\\
Type&Project\\
Tcl Version&\(8.6\)\\
State&Draft\\
Vote&Done\\
Version&\tipversion$Revision: 1.3 $\\
Keywords&coroutine, yield\\
Obsoleted By&396\\
Post History&\\
Discussions To&http://wiki.tcl.tk/26006\\
\hline\end{tabularx}\end{center}
\thispagestyle{empty}\pagestyle{empty}
\begin{tipabstract}

This TIP proposes a command that allows a coroutine to accept multiple arguments being passed in on return from yield.
\end{tipabstract}
\tableofcontents\setcounter{page}{0}\clearpage\pagestyle{plain}

\section{Rationale}

The coroutine mechanism of \cite{tip328} has given Tcl 8.6 a new primitive which permits light-weight mulitasking. The mechanism as specified by \cite{tip328} lacks the ability to emulate general-purpose procedural invocation through the arbitrary limitation of coroutine calls to a single argument (except on the initial call).

The ability of coroutines to emulate general-purpose procedural invocation is of great utility, the lack of which leads to stilted verbiage, and diverges unnecessarily from Tcl's other functionals.

The \textbf{yieldm} command, as currently implemented by \textbf{::tcl::unsupported::yieldm}, extends coroutines to permit general emulation, and it is the proposal of this TIP that yieldm be moved to the global namespace, or such other namespaces as may be used for coroutine functionality in the future.

\section{Syntax and Semantics of yieldm}

\begin{quote}
\textbf{yieldm} ?\textit{value}?
\end{quote}

This is just like \textbf{yield}, except that it causes the coroutine command to accept arbitrarily many arguments and will return the list of those arguments (i.e., an empty list if there are no arguments, a single-element list if there is one, a pair for two, etc.)

\section{Detailed Rationale}

\subsection{Utility}

Restatement-in-summary of the arguments in \url{http://wiki.tcl.tk/26006:}
\begin{enumerate}
\item{}
Coroutines should be able to simulate any command, not just any single-arg'd command. [Argument: generality]
\setcounter{enumi}{1}
\item{}
To implement single-arg's coroutines in multi-arg'd coroutines is trivial --- nothing needs to be done. The converse (implementing multi-arg'd coroutines under coroutine is inefficient and difficult. [Argument: increased expressive power]
\setcounter{enumi}{2}
\item{}
There is no sound reason that the invocation of a coroutine should not resemble that of any other command. [Argument: principle of minimal surprise]
\setcounter{enumi}{3}
\item{}
It is impossible to construct forms like \textbf{interp alias} to address a coroutine in the common case that the caller is expecting to pass more than one argument.
\end{enumerate}

\subsection{Consistency}

Restatement-in-summary of the arguments in \url{http://wiki.tcl.tk/26056:}

The following commands create new commands: \textbf{proc}, \textbf{coroutine}, \textbf{namespace ensemble}, \textbf{class create}, \textit{\$cls} \textbf{create}, \textbf{interp alias}, \textbf{interp create}, \textbf{::thread::create}, \textbf{apply}.

In each case except \textbf{coroutine}, the created command permits multiple arguments (arguably this being a key feature of Tcl in practice). There is no sound reason for this disparity, and for consistency the disparity should be removed, which the proposed \textbf{yieldm} does.

\section{Implementation}

Simply rename the \textbf{::tcl::unsupported::yieldm} into the global namespace, and extend the coroutine documentation to refer to the new command.

\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 \#328]{tip328}
Miguel Sofer,
Neil Madden,
\emph{Coroutines},
on-line at \url{http://purl.org/tcl/tip/328.html}
\end{thebibliography}
\end{document}
