\documentclass[]{article}
\usepackage{amsmath,graphicx,supertabular,hyperref,tabularx,ifthen}
\title{TIP \#373: Improved Yielding Support for Coroutines}
\date{August 12, 2010}
\author{Miguel Sofer}
\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 \#373}&\textbf{Improved Yielding Support for Coroutines}\\\hline
Author&

Miguel Sofer \tipmail{msofer}{users.sourceforge.net}
\\
Created&Thursday, \(\text{12}^{\text{th}}\) August 2010\\
Type&Project\\
Tcl Version&\(8.6\)\\
State&Withdrawn\\
Vote&Pending\\
Version&\tipversion$Revision: 1.7 $\\
Keywords&coroutine, yield\\
Obsoletes&372\\
Obsoleted By&375\\
Post History&\\
\hline\end{tabularx}\end{center}
\thispagestyle{empty}\pagestyle{empty}
\begin{tipabstract}

This TIP proposes two new commands that improve control over the yielding behaviour of coroutines.
\end{tipabstract}
\tableofcontents\setcounter{page}{0}\clearpage\pagestyle{plain}

\section{Rationale}

The new command \textbf{yieldto} allows a coroutine to suspend its execution and tailcall into an arbitrary command. It provides support for symmetric coroutines, simply specifying that the new command be another coroutine's resume command.

The new command \textbf{yieldset} specifies the number of arguments that the coroutine's resume command will accept. Note that \textbf{yieldset} obsoletes \cite{tip372}, in the sense that it provides a different way of satisfying the same needs. 

\subsection{Detailed Rationale for "yieldto"}

The current \textbf{yield} and proposed \textbf{yieldm} suspend a coroutine and return the control to the coroutine's caller: they implement asymmetric coroutines. 

It is well known that symmetric and asymmetric coroutines have equal power, in that each can be implemented on top of the other. In Tcl8.6 as of today, symmetric coroutines can be implemented by coding a scheduler, which may but doesn't have to use the event loop. The new command \textbf{yieldto} implements symmetric coroutines directly. 

The ability of \textbf{yieldto} to yield to an arbitrary command also provides new possibilities. For instance, it allows to return a non-ok code to the caller without terminating the coroutine:
\begingroup\small\begin{verbatim}
 yieldto return -level 0 -code 1 ERROR
\end{verbatim}
\endgroup

\section{Proposal for "yieldto"}

The new command

\begin{quote}
\textbf{yieldto} \textit{cmd} ?\textit{arg1 ...}?
\end{quote}

causes:
\begin{enumerate}
\item{}
the currently executing coroutine to suspend its execution (yield),
\setcounter{enumi}{1}
\item{}
the command built from the arguments to \textbf{yieldto}, as resolved in the coroutine's context, is run in the coroutine's caller scope,
\setcounter{enumi}{2}
\item{}
from the point of view of the coroutine's caller, the return value and options of the new command is what the coroutine returned on yielding.
\end{enumerate}

In other words, \textbf{yieldto} implements ``suspend yourself and \textbf{tailcall} the new command''; \textbf{yieldto} is to \textbf{yield} as \textbf{tailcall} is to \textbf{return}.

\subsection{Implementation of "yieldto"}

Simply rename the \textbf{::tcl::unsupported::yieldTo} into the global namespace while getting rid of the camelCase, and extend the \textbf{coroutine} documentation and test-suite to refer to the new command.

\section{Rationale and Proposal for "yieldset"}

\cite{tip372} justifies and requests a different interface to a coroutine's resume command, allowing for an arbitrary number of arguments that shall be returned to the coroutine's body in a list.

In order to limit the number of additional commands (\textbf{yieldm} and also \textbf{yieldmto}), and increase the flexibility, it is proposed to add a command:

\begin{quote}
\textbf{yieldset} ?\textit{arglist}?
\end{quote}

that sets the acceptable arguments for the resume command. 

If \textbf{yieldset} is called with no arguments it returns the current list of arguments.

If \textbf{yieldset} is called with a list argument, it specifies the arguments to the resume command in the manner of \textbf{proc}. The argument names shall only be used for the error message if the resume command is called with an invalid number of arguments.

In this manner, current \textbf{yield} behaves as if 
\begingroup\small\begin{verbatim}
 yieldset {{arg {}}}
\end{verbatim}
\endgroup

had been called. This shall remain the default behaviour.

If \textbf{yieldset} is called outside of a coroutine context, it sets the default behaviour for newly created coroutines. If it is called within a coroutine context it sets the behaviour for the current coroutine only. 

In order to obtain \cite{tip372}'s \textbf{yieldm} behaviour for \textbf{yield}, it would be necessary to call:
\begingroup\small\begin{verbatim}
 yieldset args
\end{verbatim}
\endgroup

either before creating the coroutine or else within the coroutine body. 

The default arglist shall be \textbf{\{\{arg \{\}\}\}}, so that the current \textbf{yield} is the default behaviour. The arglist value can be changed with \textbf{yieldset} at any time, and remains valid until changed again.

\section{Caveat}

Some new proposals for better coroutine interfaces are being discussed, based on ensembles and providing additional functionality.

I do not foresee the discussion to settle in the immediate future. The current TIP is not meant to preempt any such design, it just attempts to provide a limited improvement that is easy to implement immediately.

\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 \#372]{tip372}
Colin McCormack,
\emph{Multi-argument Yield for Coroutines},
on-line at \url{http://purl.org/tcl/tip/372.html}
\end{thebibliography}
\end{document}
