\documentclass[]{article}
\usepackage{amsmath,graphicx,supertabular,hyperref,tabularx,ifthen}
\title{TIP \#375: Symmetric Coroutines and Yieldto}
\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 \#375}&\textbf{Symmetric Coroutines and Yieldto}\\\hline
Author&

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

The new command \textbf{yieldto} allows a coroutine to suspend its execution and tailcall into an arbitrary command. If the new command is another coroutine's resume command we obtain symmetric coroutines.
\end{tipabstract}
\tableofcontents\setcounter{page}{0}\clearpage\pagestyle{plain}

\subsection{Rationale}

The current \textbf{yield} and proposed \textbf{yieldm} commands 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, to be 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{Copyright}

This document has been placed in the public domain.

\section{Colophon}

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