Index: doc/proposals/concurrency/concurrency.tex
===================================================================
--- doc/proposals/concurrency/concurrency.tex	(revision d02aaa980186f786a251414408781713039d1a31)
+++ doc/proposals/concurrency/concurrency.tex	(revision 687165a1fc8dc7460bcbc337dc00177750401c8d)
@@ -149,5 +149,5 @@
 
 \begin{lstlisting}
-	mutex struct counter_t { /*...see section §\ref{data}§...*/ };
+	mutex struct counter_t { /*...see section Â§\ref{data}Â§...*/ };
 
 	void ?{}(counter_t & nomutex this); //constructor
@@ -567,5 +567,5 @@
 \newpage
 \subsection{External scheduling} \label{extsched}
-As one might expect, the alternative to Internal scheduling is to use External scheduling instead. This method is somewhat more robust to deadlocks since one of the threads keeps a relatively tight control on scheduling. Indeed, as the following examples will demonstrate, external scheduling allows users to wait for events from other threads without the concern of unrelated events occuring. External scheduling can generally be done either in terms of control flow (ex: \uC) or in terms of data (ex: Go). Of course, both of these paradigms have their own strenghts and weaknesses but for this project control flow semantics where chosen to stay consistent with the rest of the languages semantics. Two challenges specific to \CFA arise when trying to add external scheduling with loose object definitions and multi-monitor routines. The following example shows what a simple use \code{accept} versus \code{wait}/\code{signal} and its advantages.
+An alternative to internal scheduling is to use external scheduling instead. This method is more constrained and explicit which may help users tone down the undeterministic nature of concurrency. Indeed, as the following examples demonstrates, external scheduling allows users to wait for events from other threads without the concern of unrelated events occuring. External scheduling can generally be done either in terms of control flow (ex: \uC) or in terms of data (ex: Go). Of course, both of these paradigms have their own strenghts and weaknesses but for this project control flow semantics where chosen to stay consistent with the rest of the languages semantics. Two challenges specific to \CFA arise when trying to add external scheduling with loose object definitions and multi-monitor routines. The following example shows a simple use \code{accept} versus \code{wait}/\code{signal} and its advantages.
 
 \begin{center}
@@ -585,5 +585,5 @@
 
 	public:
-		void f();
+		void f() { /*...*/ }
 		void g() { _Accept(f); }
 	private:
@@ -593,5 +593,5 @@
 \end{center}
 
-In the case of internal scheduling, the call to \code{wait} only guarantees that \code{g} was the last routine to access the monitor. This intails that the routine \code{f} may have acquired mutual exclusion several times while routine \code{h} was waiting. On the other hand, external scheduling guarantees that while routine \code{h} was waiting, no routine other than \code{g} could acquire the monitor.
+In the case of internal scheduling, the call to \code{wait} only guarantees that \code{g} is the last routine to access the monitor. This intails that the routine \code{f} may have acquired mutual exclusion several times while routine \code{h} was waiting. On the other hand, external scheduling guarantees that while routine \code{h} was waiting, no routine other than \code{g} could acquire the monitor.
 \\
 
@@ -776,23 +776,23 @@
 % #       #     # #     # #     # ####### ####### ####### ####### ###  #####  #     #
 \section{Parallelism}
-Historically, computer performance was about processor speeds and instructions count. However, with heat dissipation being a direct consequence of speed increase, parallelism has become the new source for increased performance~\cite{Sutter05, Sutter05b}. In this decade, it is not longer reasonnable to create high-performance application without caring about parallelism. Indeed, parallelism is an important aspect of performance and more specifically throughput and hardware utilization. The lowest level approach of parallelism is to use \glspl{kthread} in combination with semantics like \code{fork}, \code{join}, etc. However, since these have significant costs and limitations \glspl{kthread} are now mostly used as an implementation tool rather than a user oriented one. There are several alternatives to solve these issues that all have strengths and weaknesses. While there are many variations of the presented paradigms, most of these variations do not actually change the guarantees or the semantics, they simply move costs in order to achieve better performance for certain workloads.
+Historically, computer performance was about processor speeds and instructions count. However, with heat dissipation being a direct consequence of speed increase, parallelism has become the new source for increased performance~\cite{Sutter05, Sutter05b}. In this decade, it is not longer reasonnable to create a high-performance application without caring about parallelism. Indeed, parallelism is an important aspect of performance and more specifically throughput and hardware utilization. The lowest-level approach of parallelism is to use \glspl{kthread} in combination with semantics like \code{fork}, \code{join}, etc. However, since these have significant costs and limitations, \glspl{kthread} are now mostly used as an implementation tool rather than a user oriented one. There are several alternatives to solve these issues that all have strengths and weaknesses. While there are many variations of the presented paradigms, most of these variations do not actually change the guarantees or the semantics, they simply move costs in order to achieve better performance for certain workloads.
 
 \subsection{User-level threads}
-A direct improvement on the \gls{kthread} approach is to use \glspl{uthread}. These threads offer most of the same features that the operating system already provide but can be used on a much larger scale. This approach is the most powerfull solution as it allows all the features of multi-threading while removing several of the more expensives costs of using kernel threads. The down side is that almost none of the low-level threading problems are hidden, users still have to think about data races, deadlocks and synchronization issues. These issues can be somewhat alleviated by a concurrency toolkit with strong garantees but the parallelism toolkit offers very little to reduce complexity in itself.
-
-Examples of languages that support are Erlang~\cite{Erlang} and \uC~\cite{uC++book}.
-
-\subsection{Fibers : user-level threads without preemption}
-In the middle of the flexibility versus complexity spectrum lay \glspl{fiber} which offer \glspl{uthread} without the complexity of preemption by using cooperative scheduling. On a single core machine this means users need not worry about concurrency. On multi-core machines, while concurrency is still a concern, it is only a problem for fibers across cores but not while on the same core. This extra guarantee plus the fact that creating and destroying fibers are implicit synchronizing points means preventing mutable shared ressources still leaves many control flow options. However, multi-core processors can still execute fibers in parallel. This means users either need to worry about mutual exclusion, deadlocks and race conditions, or limit themselves to subset of concurrency primitives, raising the complexity in both cases. In this aspect, fibers can be seen as a more powerfull alternative to \glspl{job}.
+A direct improvement on the \gls{kthread} approach is to use \glspl{uthread}. These threads offer most of the same features that the operating system already provide but can be used on a much larger scale. This approach is the most powerfull solution as it allows all the features of multi-threading, while removing several of the more expensives costs of using kernel threads. The down side is that almost none of the low-level threading problems are hidden, users still have to think about data races, deadlocks and synchronization issues. These issues can be somewhat alleviated by a concurrency toolkit with strong garantees but the parallelism toolkit offers very little to reduce complexity in itself.
+
+Examples of languages that support \glspl{uthread} are Erlang~\cite{Erlang} and \uC~\cite{uC++book}.
+
+\subsubsection{Fibers : user-level threads without preemption}
+A popular varient of \glspl{uthread} is what is often reffered to as \glspl{fiber}. However, \glspl{fiber} do not present meaningful semantical differences with \glspl{uthread}. Advocates of \glspl{fiber} list their high performance and ease of implementation as majors strenghts of \glspl{fiber} but the performance difference between \glspl{uthread} and \glspl{fiber} is controversial and the ease of implementation, while true, is a weak argument in the context of language design. Therefore this proposal largely ignore fibers.
 
 An example of a language that uses fibers is Go~\cite{Go}
 
 \subsection{Jobs and thread pools}
-The approach on the opposite end of the spectrum is to base parallelism on \glspl{pool}. Indeed, \glspl{pool} offer limited flexibility but at the benefit of a simpler user interface. In \gls{pool} based systems, users express parallelism as units of work and the dependency graph (either explicit or implicit) that tie them together. This approach means users need not worry about concurrency but significantly limits the interaction that can occur between different jobs. Indeed, any \gls{job} that blocks also blocks the underlying worker, which effectively means the CPU utilization, and therefore throughput, suffers noticeably. It can be argued that a solution to this problem is to use more workers than available cores. However, unless the number of jobs and the number of workers are comparable, having a significant amount of blocked jobs will always results in idles cores.
+The approach on the opposite end of the spectrum is to base parallelism on \glspl{pool}. Indeed, \glspl{pool} offer limited flexibility but at the benefit of a simpler user interface. In \gls{pool} based systems, users express parallelism as units of work and a dependency graph (either explicit or implicit) that tie them together. This approach means users need not worry about concurrency but significantly limits the interaction that can occur among jobs. Indeed, any \gls{job} that blocks also blocks the underlying worker, which effectively means the CPU utilization, and therefore throughput, suffers noticeably. It can be argued that a solution to this problem is to use more workers than available cores. However, unless the number of jobs and the number of workers are comparable, having a significant amount of blocked jobs always results in idles cores.
 
 The gold standard of this implementation is Intel's TBB library~\cite{TBB}.
 
 \subsection{Paradigm performance}
-While the choice between the three paradigms listed above may have significant performance implication, it is difficult to pindown the performance implications of chosing a model at the language level. Indeed, in many situations one of these paradigms may show better performance but it all strongly depends on the workload. Having a large amount of mostly independent units of work to execute almost guarantess that the \gls{pool} based system has the best performance thanks to the lower memory overhead. However, interactions between jobs can easily exacerbate contention. User-level threads may allows fine grain context switching which may result in better resource utilisation but context switches will be more expansive and it is also harder for users to get perfect tunning. As with every example, fibers sit somewhat in the middle of the spectrum. Furthermore, if the units of uninterrupted work are large enough the paradigm choice will be largely amorticised by the actual work done.
+While the choice between the three paradigms listed above may have significant performance implication, it is difficult to pindown the performance implications of chosing a model at the language level. Indeed, in many situations one of these paradigms may show better performance but it all strongly depends on the workload. Having a large amount of mostly independent units of work to execute almost guarantess that the \gls{pool} based system has the best performance thanks to the lower memory overhead. However, interactions between jobs can easily exacerbate contention. User-level threads allow fine-grain context switching, which results in better resource utilisation, but context switches will be more expansive and the extra control means users need to tweak more variables to get the desired performance. Furthermore, if the units of uninterrupted work are large enough the paradigm choice is largely amorticised by the actual work done.
 
 %  #####  #######    #          ####### ######  ######
@@ -805,22 +805,5 @@
 
 \section{\CFA 's Thread Building Blocks}
-As a system level language, \CFA should offer both performance and flexibilty as its primary goals, simplicity and user-friendliness being a secondary concern. Therefore, the core of parallelism in \CFA should prioritize power and efficiency. With this said, it is possible to deconstruct the three paradigms details aboved in order to get simple building blocks. Here is a table showing the core caracteristics of the mentionned paradigms :
-\begin{center}
-\begin{tabular}[t]{| r | c | c |}
-\cline{2-3}
-\multicolumn{1}{ c| }{} & Has a stack & Preemptive \\
-\hline
-\Glspl{pool} & X & X \\
-\hline
-\Glspl{fiber} & \checkmark & X \\
-\hline
-\Glspl{uthread} & \checkmark & \checkmark \\
-\hline
-\end{tabular}
-\end{center}
-
-This table is missing several variations (for example jobs on \glspl{uthread} or \glspl{fiber}), but these variation affect mostly performance and do not effect the guarantees as the presented paradigm do.
-
-As shown in section \ref{cfaparadigms} these different blocks being available in \CFA it is trivial to reproduce any of these paradigm.
+As a system-level language, \CFA should offer both performance and flexibilty as its primary goals, simplicity and user-friendliness being a secondary concern. Therefore, the core of parallelism in \CFA should prioritize power and efficiency. With this said, deconstructing popular paradigms in order to get simple building blocks yields \glspl{uthread} as the core parallelism block. \Glspl{pool} and other parallelism paradigms can then be built on top of the underlying threading model.
 
 % ####### #     # ######  #######    #    ######   #####
@@ -833,5 +816,5 @@
 
 \subsection{Thread Interface}
-The basic building blocks of \CFA are \glspl{cfathread}. By default these are implemented as \glspl{uthread} and as such offer a flexible and lightweight threading interface (lightweight comparatievely to \glspl{kthread}). A thread can be declared using a struct declaration with prefix \code{thread} as follows :
+The basic building blocks of \CFA are \glspl{cfathread}. By default these are implemented as \glspl{uthread}, and as such, offer a flexible and lightweight threading interface (lightweight compared to \glspl{kthread}). A thread can be declared using a struct declaration with prefix \code{thread} as follows :
 
 \begin{lstlisting}
@@ -839,14 +822,14 @@
 \end{lstlisting}
 
-Obviously, for this thread implementation to be usefull it must run some user code. Several other threading interfaces use some function pointer representation as the interface of threads (for example : \Csharp~\cite{Csharp} and Scala~\cite{Scala}). However, this proposal considers that statically tying a \code{main} routine to a thread superseeds this approach. Since the \code{main} routine is definitely a special routine in \CFA, the existing syntax for declaring routines with unordinary name can be extended, i.e. operator overloading. As such the \code{main} routine of a thread can be defined as :
+Obviously, for this thread implementation to be usefull it must run some user code. Several other threading interfaces use a function-pointer representation as the interface of threads (for example : \Csharp~\cite{Csharp} and Scala~\cite{Scala}). However, this proposal considers that statically tying a \code{main} routine to a thread superseeds this approach. Since the \code{main} routine is already a special routine in \CFA (where the program begins), the existing syntax for declaring routines names with special semantics can be extended, i.e. operator overloading. As such the \code{main} routine of a thread can be defined as :
 \begin{lstlisting}
 	thread struct foo {};
 
-	void ?main(thread foo* this) {
-		/*... Some useful code ...*/
-	}
-\end{lstlisting}
-
-With these semantics it is trivial to write a thread type that takes a function pointer as parameter and executes it on its stack asynchronously :
+	void ?main(foo* this) {
+		sout | "Hello World!" | endl;
+	}
+\end{lstlisting}
+
+In this example, threads of type \code{foo} will start there execution in the \code{void ?main(foo*)} routine which in this case prints \code{"Hello World!"}. While this proposoal encourages this approach which is enforces strongly type programming. Users may prefer to use the routine based thread semantics for the sake of simplicity. With these semantics it is trivial to write a thread type that takes a function pointer as parameter and executes it on its stack asynchronously :
 \begin{lstlisting}
 	typedef void (*voidFunc)(void);
@@ -857,26 +840,24 @@
 
 	//ctor
-	void ?{}(thread FuncRunner* this, voidFunc inFunc) {
+	void ?{}(FuncRunner* this, voidFunc inFunc) {
 		func = inFunc;
 	}
 
 	//main
-	void ?main(thread FuncRunner* this) {
+	void ?main(FuncRunner* this) {
 		this->func();
 	}
 \end{lstlisting}
 
-% In this example \code{func} is a function pointer stored in \acrfull{tls}, which is \CFA is both easy to use and completly typesafe.
-
-Of course for threads to be useful, it must be possible to start and stop threads and wait for them to complete execution. While using an \acrshort{api} such as \code{fork} and \code{join} is relatively common in the literature, such an interface is not needed. Indeed, the simplest approach is to use \acrshort{raii} principles and have threads \code{fork} once the constructor has completed and \code{join} before the destructor runs.
-\begin{lstlisting}
-thread struct FuncRunner; //FuncRunner declared above
-
-void world() {
+Of course for threads to be useful, it must be possible to start and stop threads and wait for them to complete execution. While using an \acrshort{api} such as \code{fork} and \code{join} is relatively common in the literature, such an interface is unnecessary. Indeed, the simplest approach is to use \acrshort{raii} principles and have threads \code{fork} once the constructor has completed and \code{join} before the destructor runs.
+\begin{lstlisting}
+thread struct World; //FuncRunner declared above
+
+void ?main(thread World* this) {
 	sout | "World!" | endl;
 }
 
 void main() {
-	FuncRunner run = {world};
+	World w;
 	//Thread run forks here
 
@@ -887,7 +868,6 @@
 }
 \end{lstlisting}
-This semantic has several advantages over explicit semantics : typesafety is guaranteed, a thread is always started and stopped exaclty once and users cannot make any progamming errors. Furthermore it naturally follows the memory allocation semantics, which means users do not need to learn multiple semantics.
-
-These semantics also naturally scale to multiple threads meaning basic synchronisation is very simple :
+This semantic has several advantages over explicit semantics : typesafety is guaranteed, a thread is always started and stopped exaclty once and users cannot make any progamming errors. However, one of the apparent drawbacks of this system is that threads now always form a lattice, that is they are always destroyed in opposite order of construction. While this seems like a significant limitation, existing \CFA semantics can solve this problem. Indeed, by using dynamic allocation to create threads will naturally let threads outlive the scope in which the thread was created much like dynamically allocating memory will let objects outlive the scope in which thy were created :
+
 \begin{lstlisting}
 	thread struct MyThread {
@@ -896,8 +876,45 @@
 
 	//ctor
-	void ?{}(thread MyThread* this) {}
+	void ?{}(MyThread* this,
+		     bool is_special = false) {
+		//...
+	}
 
 	//main
-	void ?main(thread MyThread* this) {
+	void ?main(MyThread* this) {
+		//...
+	}
+
+	void foo() {
+		MyThread* special_thread;
+		{
+			MyThread thrds = {false};
+			//Start a thread at the beginning of the scope
+
+			DoStuff();
+
+			//create a other thread that will outlive the thread in this scope
+			special_thread = new MyThread{true};
+
+			//Wait for the thread to finish
+		}
+		DoMoreStuff();
+
+		//Now wait for the special
+	}
+\end{lstlisting}
+
+Another advantage of this semantic is that it naturally scale to multiple threads meaning basic synchronisation is very simple :
+
+\begin{lstlisting}
+	thread struct MyThread {
+		//...
+	};
+
+	//ctor
+	void ?{}(MyThread* this) {}
+
+	//main
+	void ?main(MyThread* this) {
 		//...
 	}
@@ -911,18 +928,62 @@
 		//Wait for the 10 threads to finish
 	}
-
-	void bar() {
-		MyThread* thrds = new MyThread[10];
-		//Start 10 threads at the beginning of the scope
-
-		DoStuff();
-
-		//Wait for the 10 threads to finish
-		delete MyThread;
-	}
-\end{lstlisting}
-
-\newpage
-\large{\textbf{WORK IN PROGRESS}}
+\end{lstlisting}
+
+\subsection{Coroutines : A stepping stone}\label{coroutine}
+While the main focus of this proposal is concurrency and paralellism, it is important to adress coroutines which are actually a significant underlying aspect of the concurrency system. Indeed, while having nothing todo with parallelism and arguably very little to do with concurrency, coroutines need to deal with context-switchs and and other context management operations. Therefore, this proposal includes coroutines both as an intermediate step for the implementation of threads and a first class feature of \CFA.
+
+The core API of coroutines revolve around two features : independent stacks and suspedn/resume. Much like threads the syntax for declaring a coroutine is declaring a type and a main routine for it to start :
+\begin{lstlisting}
+	coroutine struct MyCoroutine {
+		//...
+	};
+
+	//ctor
+	void ?{}(MyCoroutine* this) {}
+
+	//main
+	void ?main(MyCoroutine* this) {
+		sout | "Hello World!" | endl;
+	}
+\end{lstlisting}
+
+One a coroutine is created, users can context switch to it using \code{suspend} and come back using \code{resume}. Here is an example of a solution to the fibonnaci problem using coroutines :
+\begin{lstlisting}
+	coroutine struct Fibonacci {
+		int fn; // used for communication
+	};
+
+	void ?main(Fibonacci* this) {
+		int fn1, fn2; 		// retained between resumes
+		this->fn = 0;
+		fn1 = this->fn;
+		suspend(this); 		// return to last resume
+
+		this->fn = 1;
+		fn2 = fn1;
+		fn1 = this->fn;
+		suspend(this); 		// return to last resume
+
+		for ( ;; ) {
+			this->fn = fn1 + fn2;
+			fn2 = fn1;
+			fn1 = this->fn;
+			suspend(this); 	// return to last resume
+		}
+	}
+
+	int next(Fibonacci& this) {
+		resume(&this); // transfer to last suspend
+		return this.fn;
+	}
+
+	void main() {
+		Fibonacci f1, f2;
+		for ( int i = 1; i <= 10; i += 1 ) {
+			sout | next(f1) | '§\verb+ +§' | next(f2) | endl;
+		}
+	}
+\end{lstlisting}
+
 \subsection{The \CFA Kernel : Processors, Clusters and Threads}\label{kernel}
 
