async/await, async*, sync* and yield

docs/language/dartLangSpec.tex

 \documentclass{article}
 \usepackage{epsfig}
 \usepackage{dart}
 \usepackage{bnf}
 \usepackage{hyperref}
 \newcommand{\code}[1]{{\sf #1}}
 \title{Dart Programming Language  Specification \\
 {\large Version 1.6}}
 %\author{The Dart Team}
 \begin{document}
@@ skipping 234 matching lines @@
 }
 
 \rationale{Privacy is, at this point, a static notion tied to a particular piece of code (a library). It is designed to support software engineering concerns rather than security concerns. Untrusted code should always run in an another isolate.  It is possible that libraries will become first class objects and privacy will be a dynamic notion tied to a library instance.
 
 Privacy is indicated by the name of a declaration - hence privacy and naming are not orthogonal. This has the advantage that both humans and machines can recognize access to private declarations at the point of use without knowledge of the context from which the declaration is derived.}
 
 \subsection{Concurrency}
 
 Dart code is always single threaded. There is no shared-state concurrency in Dart. Concurrency is supported via actor-like entities called {\em isolates}.
 
-An isolate is a unit of concurrency. It has its own memory and its own thread of control. Isolates communicate by message passing (\ref{sendingMessages}). No state is ever shared between isolates. Isolates are created by spawning (\ref{spawningAnIsolate}).
+An isolate is a unit of concurrency. It has its own memory and its own thread of control. Isolates communicate by message passing (\ref{sendingMessages}). No state is ever shared between isolates. Isolates are created by spawning (\ref{spawningAnIsolate}). 
 
 
 \section{Errors and Warnings}
 \label{errorsAndWarnings}
 
 This specification distinguishes between several kinds of errors.
 
 {\em Compile-time errors} are errors that preclude execution. A compile-time error must be reported by a Dart compiler before the erroneous code is executed. 
 
 \rationale{A Dart implementation has considerable freedom as to when compilation takes place. Modern programming language implementations often interleave compilation and execution, so that compilation of a method may be delayed, e.g.,  until it is first invoked. Consequently, compile-time errors in a method $m$ may be reported as late as the time of $m$'s first invocation.
@@ skipping 208 matching lines @@
 \begin{grammar}
 {\bf functionSignature:}
     metadata returnType? identifier formalParameterList
     .
     
 {\bf returnType:}
       \VOID{};
       type
     .
 
-{\bf functionBody:}`={\escapegrammar \gt}' expression `{\escapegrammar ;}';
-     block
+{\bf functionBody:} \ASYNC{}?  `={\escapegrammar \gt}' expression `{\escapegrammar ;}';
+     (\ASYNC{} $|$ \ASYNC* $|$ \SYNC*)? block
     .
 
 {\bf block:}
       `\{' statements `\}'
     .
 
 \end{grammar}
 
 Functions include  function declarations (\ref{functionDeclarations}), methods (\ref{instanceMethods},  \ref{staticMethods}), getters  (\ref{getters}), setters  (\ref{setters}), constructors  (\ref{constructors}) and function literals  (\ref{functionExpressions}).  
 
 All functions have a signature and a body. The signature describes the formal parameters of the function, and possibly its name and return type.  A function body is either:
 \begin{itemize}
-\item A block statement  (\ref{blocks}) containing the statements  (\ref{statements}) executed by the function. In this case, if the last statement of a function is not a return statement, the statement \code{\RETURN{};} is implicitly appended to the function body.
+\item A block statement  (\ref{blocks}) containing the statements  (\ref{statements}) executed by the function, optionally marked with one of the modifiers: \ASYNC, \ASYNC* or \SYNC*. In this case, if the last statement of a function is not a return statement (\ref{return}), the statement \code{\RETURN{};} is implicitly appended to the function body.
 
 \rationale{
-Because Dart is optionally typed, we cannot guarantee that a function that does not return a value will not be used in the context of an expression. Therefore, every function must return a value. A \RETURN{} without an expression returns \NULL{}. See further discussion in section \ref{return}.
+Because Dart is optionally typed, we cannot guarantee that a function that does not return a value will not be used in the context of an expression. Therefore, every function must return a value. A \RETURN{} without an expression returns \NULL{}. For generator functions, the situation is more subtle. See further discussion in section \ref{return}.
 }
 
 OR
-\item of the form   \code{=$>$ $e$} which is equivalent to a body of the form \code{\{\RETURN{} $e$;\}}.
+\item of the form   \code{=$>$ $e$} which is equivalent to a body of the form \code{\{\RETURN{} $e$;\}} or the form \code{\ASYNC{} =$>$ $e$} which is equivalent to a body of the form \code{\ASYNC{} \{\RETURN{} $e$;\}}. \rationale{The other modifiers do not apply here, because they apply only to generators, discussed below, and generators do not allow the form \code{\RETURN{} $e$}; values are added to the generated stream or iterable using \YIELD{} instead.}

[Lasse Reichstein Nielsen, 2014/08/28 14:35:49]

at "the other modifiers", maybe add "(\ASYNC* and \SYNC*)" as elaboration. This
is just a rationale, so it may be ok to let some things be implicit.

[gbracha, 2014/08/28 21:52:08]

I think it's fine as a rationale.

+
 \end{itemize}
 
+A function is {\em asynchronous} if its body is marked with the \ASYNC{} or \ASYNC* modifier. Otherwise the function is {\em synchronous}. A function is a {\em generator} if its body is marked with the \SYNC* or \ASYNC* modifier.  
 
+\commentary{
+Whether a function is synchronous or asynchronous is orthogonal to whether it is a generator or not. Generator functions are a sugar for functions that produce collections in a systematic way, by lazily applying a function that {\em generates} individual elements of a collection. Dart provides such a sugar in both the synchronous case, where one returns an iterable, and in the asynchronous case, where one returns a stream. Dart also allows both synchronous and asynchronous functions that produce a single value. 
+}
 
-% A function has a formal parameter scope and a  body scope. The enclosing scope of a function's body scope is its formal parameter scope. The enclosing scope of the  formal parameter scope of a function is the enclosing scope of the function.
+It is a compile-time error if an \ASYNC, \ASYNC* or \SYNC* modifier is attached to the body of a setter or constructor.
 
-% The body of a function $f$ is processed within the body scope of $f$.
-%\rationale{This may seem obvious, but needs to be stated.}
-% \commentary{It follows from the above rules that the formal parameters of a function may be referenced within its body.  }
+\rationale{
+An asynchronous setter would be of little use, since setters can only be used in the context of an assignment (\ref{assignment}), and an assignment expression always evaluates to the value of the assignment's right hand side. If the setter actually did its work asynchronously, one might imagine that one would return a future that resolved to the assignment's right hand side after the setter did its work. However, this would require dynamic tests at every assignment, and so would be prohibitively expensive. 
+
+An asynchronous constructor would, by definition, never return an instance of the class it purports to construct, but instead return a future. Calling such a beast via \NEW{} would be very confusing. If you need to produce an object asynchronously, use a method.
+
+One could allow modifiers for factories. A factory for \code{Future} could be modified by \ASYNC{}, a factory for \code{Stream} could be modified by \ASYNC* and a factory for \code{Iterable} could be modified by \SYNC*. No other scenario makes sense because the object returned by the factory would be of the wrong type. This situation is very unusual so it is not worth making an exception to the general rule for constructors in order to allow it.
+}
+
 
 \subsection{Function Declarations}
 \label{functionDeclarations}
 
 A {\em function declaration} is a function that is neither a member of a class nor a function literal. Function declarations include {\em library functions}, which are function declarations 
 %(including getters and setters) 
 at the top level of a library, and {\em local functions}, which are function declarations declared inside other functions. Library functions are often referred to simply as top-level functions.
 
 A function declaration consists of an identifier indicating the function's name, possibly prefaced by a return type. The function name is followed by a signature and body. For getters, the signature  is empty. The body is empty for functions that are external.
 
@@ skipping 20 matching lines @@
 It is a compile-time error to preface a function declaration with the built-in identifier \STATIC{}.
 
 When we say that a function $f_1$ {\em forwards} to another function $f_2$, we mean that  invoking $f_1$ causes $f_2$ to  be executed with the same arguments and/or receiver as $f_1$, and returns the result of executing $f_2$ to the caller of $f_1$, unless $f_2$ throws an exception, in which case $f_1$ throws the same exception. Furthermore, we only use the term for synthetic functions introduced by the specification.
 
 
 \subsection{Formal Parameters}
 \label{formalParameters}
 
 Every function includes a {\em formal parameter list}, which consists of a list of required positional parameters (\ref{requiredFormals}), followed by any optional parameters (\ref{optionalFormals}). The optional parameters may be specified either as a set of named parameters or as a list of positional parameters, but not both.
 
-The formal parameter list of a function introduces a new scope known as the function`s {\em formal parameter scope}. The formal parameter scope of a function $f$  is enclosed in the scope where $f$ is declared.   Every formal parameter introduces a local variable into the formal parameter scope. However, the scope of a function's signature is the function's enclosing scope, not the formal parameter scope.
+The formal parameter list of a function introduces a new scope known as the function's {\em formal parameter scope}. The formal parameter scope of a function $f$  is enclosed in the scope where $f$ is declared.   Every formal parameter introduces a local variable into the formal parameter scope. However, the scope of a function's signature is the function's enclosing scope, not the formal parameter scope.
 
-The body of a function introduces a new scope known as the function`s {\em  body scope}. The body scope of a function $f$  is enclosed  in the scope introduced by the formal parameter scope of $f$.
+The body of a function introduces a new scope known as the function's {\em  body scope}. The body scope of a function $f$  is enclosed  in the scope introduced by the formal parameter scope of $f$.
 
 
 %The formal parameter scope of a function maps the name of each formal parameter $p$ to the value $p$ is bound to. 
 
 % The formal parameters of a function are processed in the enclosing scope of the function. 
 % \commentary{this means that the parameters themselves may not be referenced within the formal parameter list.}
 
 It is a compile-time error if a formal parameter is declared as a constant variable (\ref{variables}).
 
 \begin{grammar}
@@ skipping 355 matching lines @@
 \end{grammar}
 
 If no return type is specified, the return type of the setter is  \DYNAMIC{}.
 
 A setter definition that is prefixed with the \STATIC{} modifier defines a static setter. Otherwise, it defines an instance setter. The name of a setter is  obtained by appending the  string `='  to the identifier given in its signature. The effect of a static setter declaration in class $C$ is to add an instance setter with the same name and signature to the \code{Type} object for class $C$ that forwards (\ref{functionDeclarations})  to the static setter.
 
 \commentary{Hence, a setter name can never conflict with, override or be overridden by a getter or method.}
 
 The instance setters of a class $C$ are those instance setters declared by $C$ either implicitly or explicitly, and the instance setters inherited by $C$ from its superclass. The static setters of a class $C$ are those static setters declared by $C$.
 
-It is a compile-time error if a setter's formal parameter list does not consist of exactly one required formal parameter $p$.  \rationale{We could enforce this via the grammar, but we`d have to specify the evaluation rules in that case.}
+It is a compile-time error if a setter's formal parameter list does not consist of exactly one required formal parameter $p$.  \rationale{We could enforce this via the grammar, but we'd have to specify the evaluation rules in that case.}
 
 %It is a compile-time error if a class has both a setter and a method with the same name. This restriction holds regardless of whether the setter is defined explicitly or implicitly, or whether the setter or the method are inherited or not.
 
 It is a static warning if a setter declares a return type other than \VOID{}.
 It is a static warning if a setter $m_1$ overrides  (\ref{inheritanceAndOverriding}) a setter $m_2$ and the type of $m_1$ is not a subtype of the type of $m_2$. It is a static warning if a class has a setter named $v=$ with argument type $T$ and a getter named $v$ with return type $S$, and $T$ may not be assigned to $S$. 
 
 It is a static warning if a class  declares a static setter named $v=$ and also has a non-static member named $v$. It is a static warning if a class $C$ declares an instance setter named $v=$ and an accessible static member named $v=$ or $v$ is declared in a superclass of $C$.
 
 These warnings must be issued regardless of whether the getters or setters are declared explicitly or implicitly.
 
@@ skipping 115 matching lines @@
 \begin{grammar}
 {\bf constructorSignature:}
       identifier (`{\escapegrammar .}' identifier)? formalParameterList
     .
  \end{grammar}
 
 A {\em constructor parameter list} is a parenthesized, comma-separated list of formal constructor parameters. A {\em formal constructor parameter} is either a formal parameter (\ref{formalParameters}) or an initializing formal. An {\em initializing formal} has the form \code{\THIS{}.id}, where \code{id} is the name of an instance variable of the immediately enclosing class.  It is a compile-time error if \code{id} is not an instance variable of the immediately enclosing class. It is a compile-time error if an initializing formal is used by a function other than a non-redirecting generative constructor. 
 
 If an explicit type is attached to the initializing formal, that is its static type. Otherwise, the type of an initializing formal named \code{id} is $T_{id}$, where $T_{id}$ is the type of the field named \code{id} in the immediately enclosing class. It is a static warning if the static type of \code{id} is not assignable to $T_{id}$.
 
-Using an initializing formal \code{\THIS{}.id} in a formal parameter list does not introduce a formal parameter name into the scope of the constructor. However, the initializing formal does effect the type of the constructor function exactly as if a formal parameter  named \code{id}  of the same type were introduced in the same position. 
+Using an initializing formal \code{\THIS{}.id} in a formal parameter list does not introduce a formal parameter name into the scope of the constructor. However, the initializing formal does effect the type of the constructor function exactly as if a formal parameter  named \code{id}  of the same type were introduced in the same position.
 
 Initializing formals are executed during the execution of generative constructors detailed below. Executing an initializing formal  \code{\THIS{}.id} causes the field \code{id} of the immediately surrounding class to be assigned the value of the corresponding actual parameter, unless $id$ is a final variable that has already been initialized, in which case a runtime error occurs.
 
 
 \commentary{
 The above rule allows initializing formals to be used as optional parameters:
 }
 
 \begin{dartCode}
 class A \{
@@ skipping 484 matching lines @@
 Whether an override is legal or not is described elsewhere in this specification (see \ref{instanceMethods}, \ref{getters} and \ref{setters}). 
 
 \commentary{For example getters may not legally override methods and vice versa. Setters never override methods or getters, and vice versa, because their names always differ.
 }  
 
 \rationale{
 It is nevertheless convenient to define the override relation between members in this way, so that we can concisely describe the illegal cases.
 }
 
 \commentary{
-Note that instance variables do not participate in the override relation, but the getters and setters they induce do. Also, getters don`t override setters and vice versa.  Finally, static members never override anything.
+Note that instance variables do not participate in the override relation, but the getters and setters they induce do. Also, getters don't override setters and vice versa.  Finally, static members never override anything.
 }
 
 It is a static warning if a non-abstract class inherits an abstract method.
 
 \commentary {
 For convenience, here is a summary of the relevant rules. Remember that this is not normative. The controlling language is in the relevant sections of the specification.
 
 \begin{enumerate}
 
 \item There is only one namespace for getters, setters, methods and constructors (\ref{scoping}). A field $f$ introduces a getter $f$ and a non-final field $f$ also introduces a setter $f=$ (\ref{instanceVariables}, \ref{staticVariables}). When we speak of members here, we mean accessible fields, getters, setters and methods (\ref{classes}).
@@ skipping 28 matching lines @@
   \end{itemize}  (\ref{interfaceInheritanceAndOverriding})
 \item  Rule \ref{typeSigAssignable} applies to interfaces as well as classes  (\ref{interfaceInheritanceAndOverriding}).
 \item  It is a static warning if a concrete class does not have an implementation for a  method in any of its superinterfaces  unless it declares  its own \cd{noSuchMethod} method (\ref{superinterfaces}). 
 \item The identifier of a named constructor cannot be the same as the name of a member declared (as opposed to inherited) in the same class (\ref{constructors}).
 \end{enumerate}
 }
 
 
 %Can we have abstract getters and setters?
 
-\subsection{Superinterfaces}
+\subsection{ Superinterfaces}
 \label{superinterfaces}
 % what about rules about classes that fail to implement their interfaces?
 
 A class has a set of direct superinterfaces. This set includes the interface of its superclass and the interfaces specified in the the \IMPLEMENTS{}  clause of the class.
 % and any superinterfaces specified by interface injection (\ref{interfaceInjection}).  \Q{The latter needs to be worded carefully - when do interface injection clauses execute and in what scope?}
 
 \begin{grammar}
 {\bf interfaces:}
       \IMPLEMENTS{} typeList
     .
@@ skipping 265 matching lines @@
   \STATIC{} \CONST{} E id$_{n-1}$ = const E(n - 1);
   \STATIC{} \CONST{} List$<$E$>$ values = const $<$E$>$[id$_0 \ldots $ id$_{n-1}$];
   String toString() =$>$ \{ 0: `E.id$_0$', $\ldots$, n-1: `E.id$_{n-1}$'\}[index]
 \}
 \end{dartCode}
 
 \commentary {
 It is also a compile-time error to subclass, mix-in or implement an enum or to explicitly instantiate an enum.  These restrictions are given in normative form in sections \ref{superclasses}, \ref{superinterfaces}, \ref{mixinApplication} and \ref{instanceCreation} as appropriate.
 }
 
-
-
 \section{Generics}
 \label{generics}
 
 A class declaration (\ref{classes}) or type alias (\ref{typedef}) 
 $G$ may be {\em generic}, that is, $G$ may have formal type parameters declared. A generic declaration induces a family of declarations, one for each set of actual type parameters provided in the program. 
 
 \begin{grammar}
 {\bf typeParameter:}
      metadata identifier (\EXTENDS{} type)?
     .
@@ skipping 776 matching lines @@
 {\bf throwExpression:}
      \THROW{} expression 
     .
     
    {\bf throwExpressionWithoutCascade:}
      \THROW{} expressionWithoutCascade 
     .
  
  \end{grammar}
  
- The {\em current exception} is the last unhandled exception thrown. 
+ The {\em current exception} is the last unhandled exception thrown at a given moment during runtime. 

[Lasse Reichstein Nielsen, 2014/08/28 14:35:49]

It's unclear what "unhandled" means, or when an exception ceases to be
unhandled.

[gbracha, 2014/08/28 21:52:08]

Rephrased.

[gbracha, 2014/08/28 21:52:08]

How about: 

The last exception that has been raised and not subsequently caught.

 
  Evaluation of a throw expression of the form  \code{\THROW{} $e$;} proceeds as follows:
  
-The expression $e$ is evaluated yielding a value $v$. If $v$ evaluates to \NULL{}, then a \code{NullThrownError} is thrown. Otherwise, control is transferred to the nearest dynamically enclosing exception handler (\ref{try}), with the current exception set to $v$.
+The expression $e$ is evaluated yielding a value $v$. 
 
 \commentary{
 There is no requirement that the expression $e$ evaluate to a special kind of exception or error object.
 }
 
+If $e$ evaluates to \NULL{} (\ref{null}), then a \code{NullThrownError} is thrown. Otherwise the current exception is set to $v$ and the current return value (\ref{return}) becomes undefined.

[Lasse Reichstein Nielsen, 2014/08/28 14:35:49]

No mention of "current stack trace".

+
+\rationale{The current exception and the current return value must never be simultaneously defined, as they represent mutually exclusive options for exiting the current function. 
+}
+
+Let $f$ be the immediately enclosing function. 
+
+If $f$ is marked \ASYNC{} or \ASYNC* (\ref{functions}) and there is a dynamically enclosing exception handler $h$  (\ref{try}) introduced by the current activation, control is transferred to $h$, otherwise $f$  terminates.

[Lasse Reichstein Nielsen, 2014/08/28 14:35:49]

Will there always be a dynamically enclosing exception handler introduced by the
current activation? 
It is written like a condition that can be unsatisfied, but that would mean that
the throw would not end up in a future or stream?

[gbracha, 2014/08/28 21:52:08]

If there isn't one defined via a try statement, then there isn't one as far as
the language spec is concerned. The implementation may have introduced one under
the covers, but that is irrelevant.

+
+\rationale{
+The rules for where a thrown exception will be handled must necessarily differ between the synchronous and asynchronous cases. Asynchronous functions cannot transfer control to an exception handler defined outside themselves.  Asynchronous generators post exceptions to their stream. Other asynchronous functions report exceptions via their future.
+}
+
+Otherwise, control is transferred to the nearest dynamically enclosing exception handler.

[Lasse Reichstein Nielsen, 2014/08/28 14:35:49]

There is no "if" for this "otherwise". The sentence above the rationale had both
"if" and "otherwise" by itself.

Should this just be the "otherwise" of the paragraph above? It avoids having to
say what happens when $f$ terminates.

[gbracha, 2014/08/28 21:52:08]

Yes, it is the otherwise of (if f is marked async or async*). Reshuffled to make
things clearer.

+
+\commentary{
+If $f$ is marked \SYNC* then the dynamically enclosing exception handler encloses the call to \code{moveNext()} that initiated the evaluation of the throw expression.
+}
+
 If the object being thrown is an instance of class \code{Error} or a subclass thereof, its \code{stackTrace} getter will return the stack trace current at the point where the the object was first thrown.
 
 The static type of a throw expression is $\bot$.
 
 
 \subsection{ Function Expressions}
 \label{functionExpressions}
 
 A {\em function literal} is an object that encapsulates an executable unit of code. 
 
 \begin{grammar}
 {\bf functionExpression:}
-    formalParameterList functionExpressionBody
-    .
-
-
-{\bf functionExpressionBody:}
-      `={\escapegrammar \gt}' expression;
-      block
+    formalParameterList functionBody
     .
  \end{grammar}   
  
 The class of a function literal implements the built-in class \code{Function}.   
 %Invoking the getter \code{runtimeType} on a function literal returns the \code{Type} object that is the value of the expression \code{Function}.
 % not necessarily
 
 
 %Q{Can anyone implement it? Then we should define things via call}
 
 The static type of a function literal of the form 
 
-$(T_1$ $a_1, \ldots, T_n$ $a_n, [T_{n+1}$ $x_{n+1} = d_1, \ldots,  T_{n+k}$ $x_{n+k} = d_k]) => e$ 
+$(T_1$ $a_1, \ldots, T_n$ $a_n, [T_{n+1}$ $x_{n+1} = d_1, \ldots,  T_{n+k}$ $x_{n+k} = d_k]) => e$ or the form  $(T_1$ $a_1, \ldots, T_n$ $a_n, [T_{n+1}$ $x_{n+1} = d_1, \ldots,  T_{n+k}$ $x_{n+k} = d_k])$ \ASYNC{} $=> e$
 
 is $(T_1 \ldots, T_n, [T_{n+1}$ $x_{n+1}, \ldots, T_{n+k}$ $x_{n+k}]) \rightarrow T_0$, where $T_0$ is the static type of $e$. In any case where $T_i, 1 \le i \le n+k$, is not specified, it is considered to have been specified as  \DYNAMIC{}.

[Lasse Reichstein Nielsen, 2014/08/28 14:35:49]

Should be Future<T_0> for the async function literal. Dittos below.

[gbracha, 2014/08/28 21:52:08]

Good catch. Fixed.

 
 The static type of a function literal of the form 
 
-$(T_1$ $a_1, \ldots, T_n$ $a_n, \{T_{n+1}$ $x_{n+1} : d_1, \ldots,  T_{n+k}$ $x_{n+k} : d_k\}) => e$ 
+$(T_1$ $a_1, \ldots, T_n$ $a_n, \{T_{n+1}$ $x_{n+1} : d_1, \ldots,  T_{n+k}$ $x_{n+k} : d_k\}) => e$ or the form $(T_1$ $a_1, \ldots, T_n$ $a_n, \{T_{n+1}$ $x_{n+1} : d_1, \ldots,  T_{n+k}$ $x_{n+k} : d_k\})$ \ASYNC{}  $=> e$
 
 is $(T_1 \ldots, T_n, \{T_{n+1}$ $x_{n+1}, \ldots, T_{n+k}$ $x_{n+k}\}) \rightarrow T_0$, where $T_0$ is the static type of $e$. In any case where $T_i, 1 \le i \le n+k$, is not specified, it is considered to have been specified as  \DYNAMIC{}.
 
 The static type of a function literal of the form  
 
 $(T_1$ $a_1, \ldots, T_n$ $a_n, [T_{n+1}$ $x_{n+1} = d_1, \ldots,  T_{n+k}$ $x_{n+k}= d_k])\{s\}$ 
-
+or the form $(T_1$ $a_1, \ldots, T_n$ $a_n, [T_{n+1}$ $x_{n+1} = d_1, \ldots,  T_{n+k}$ $x_{n+k}= d_k])$ $modifier$ $\{s\}$ (where $modifier$ is one of \ASYNC{}, \ASYNC* or \SYNC*)
 is $(T_1 \ldots, T_n, [T_{n+1}$ $x_{n+1}, \ldots, T_{n+k}$ $x_{n+k}]) \rightarrow  \DYNAMIC{}$. In any case where $T_i, 1 \le i \le n+k$, is not specified, it is considered to have been specified as  \DYNAMIC{}.
 
 The static type of a function literal of the form  
 
 $(T_1$ $a_1, \ldots, T_n$ $a_n, \{T_{n+1}$ $x_{n+1} : d_1, \ldots,  T_{n+k}$ $x_{n+k} : d_k\})\{s\}$ 
-
+$(T_1$ $a_1, \ldots, T_n$ $a_n, \{T_{n+1}$ $x_{n+1} : d_1, \ldots,  T_{n+k}$ $x_{n+k} : d_k\})$ $modifier$ $\{s\}$
+ $modifier$ $\{s\}$ (where $modifier$ is one of \ASYNC{}, \ASYNC* or \SYNC*)
 is $(T_1 \ldots, T_n, \{T_{n+1}$ $x_{n+1}, \ldots, T_{n+k}$ $x_{n+k}\}) \rightarrow  \DYNAMIC{}$. In any case where $T_i, 1 \le i \le n+k$, is not specified, it is considered to have been specified as  \DYNAMIC{}.
 
 %** Now that declared return types are precluded, do we need some better return type rule for (x){s} and friends?
 
 
 
 \subsection{ This}
 \label{this}
 
 The reserved word \THIS{} denotes the target of the current instance member invocation.
@@ skipping 258 matching lines @@
 
 \commentary{
 As discussed in section \ref{errorsAndWarnings}, the handling of a suspended isolate is the responsibility of the embedder.
 }
 
 
 
 \subsection{ Function Invocation}
 \label{functionInvocation}
  
-Function invocation occurs in the following cases: when a function expression  (\ref{functionExpressions}) is invoked (\ref{functionExpressionInvocation}), when a method (\ref{methodInvocation}), getter (\ref{topLevelGetterInvocation}, \ref{propertyExtraction}) or setter (\ref{assignment}) is invoked or when a constructor is invoked (either via instance creation (\ref{instanceCreation}), constructor redirection (\ref{redirectingConstructors}) or super initialization). The various kinds of function invocation differ as to how the function to be invoked, $f$,  is determined, as well as whether \THIS{} is bound. Once $f$ has been determined, the formal parameters of $f$ are bound to corresponding actual arguments. The body of $f$ is then executed with the aforementioned bindings. Execution of the body terminates when the first of the following occurs:
+Function invocation occurs in the following cases: when a function expression  (\ref{functionExpressions}) is invoked (\ref{functionExpressionInvocation}), when a method (\ref{methodInvocation}), getter (\ref{topLevelGetterInvocation}, \ref{propertyExtraction}) or setter (\ref{assignment}) is invoked or when a constructor is invoked (either via instance creation (\ref{instanceCreation}), constructor redirection (\ref{redirectingConstructors}) or super initialization). The various kinds of function invocation differ as to how the function to be invoked, $f$,  is determined, as well as whether \THIS{} (\ref{this}) is bound. Once $f$ has been determined, the formal parameters of $f$ are bound to corresponding actual arguments. When the body of $f$ is executed it will be executed with the aforementioned bindings. 
+
+If $f$ is marked \ASYNC{} (\ref{functions}), then a fresh instance (\ref{generativeConstructors}) $o$ implementing the built-in class \code{Future} is associated with the invocation and immediately returned to the caller. The body of $f$ is scheduled for execution at some future time. The future $o$ will complete when $f$ terminates. The value used to complete $o$ is the current return value (\ref{return}), if it is defined, and the current exception (\ref{throw}) otherwise. 

[Lasse Reichstein Nielsen, 2014/08/28 14:35:49]

And current stack trace.

[gbracha, 2014/08/28 21:52:08]

Not sure what you mean here?

[Lasse Reichstein Nielsen, 2014/09/02 13:00:08]

The returned future should be completed with both the current exception and the
current stack trace, just as if you catch the throw with "catch(e,s)". The
current stack trace is not part of the thrown value.
The current stack trace isn't mentioned here, or at the throw.

+
+If $f$ is marked \ASYNC* (\ref{functions}), then a fresh instance $s$ implementing the built-in class \code{Stream} is associated with the invocation and immediately returned. When $s$ is listened to, execution of the body of $f$ will begin.  When $f$ terminates:
+\begin{itemize}
+\item If the current return value is defined then, if $s$ has been canceled then its cancellation future is completed with \NULL{} (\ref{null}). 
+\item If the current exception $x$ is defined:
+  \begin{itemize}
+  \item $x$ is added to $s$. 
+  \item If $s$ has been canceled then its cancellation future is completed with $x$.

[Lasse Reichstein Nielsen, 2014/08/28 14:35:49]

add "as an error" - this could be read as the expression ending up as a value of
the future, not an error.

+  \end{itemize}
+\item $s$ is closed.
+\end{itemize}
+
+\rationale{
+When an asynchronous generator's stream has been canceled, cleanup will occur in the \FINALLY{} clauses (\ref{try}) inside the generator. We choose to direct any exceptions that occur at this time to the cancellation future rather than have them be lost. 
+}
+
+If $f$ is asynchronous then when $f$ terminates any open stream subscriptions associated with any asynchronous for loops  (\ref{asynchronousFor-in}) or yield-each statements  (\ref{yieldEach}) executing within $f$ are canceled.

[Lasse Reichstein Nielsen, 2014/08/28 14:35:49]

Should there be a comma before "any". Slightly hard to read.

[gbracha, 2014/08/28 21:52:08]

Gave you two commas. Extra breathing roon :-)

+
+\rationale{Such streams may be left open by for loops that were escaped when an exception was thrown within them for example.
+}
+
+If $f$ is marked \SYNC* (\ref{functions}), then a fresh instance $i$ implementing the built-in class \code{Iterable} is associated with the invocation and immediately returned. When iteration over the iterable is started, by getting an iterator $j$ from the iterable and calling \code{moveNext()} on it, execution of the body of $f$ will begin. When $f$ terminates, $j$ is positioned after its last element, so that its current value is \NULL{} and the current call to \code{moveNext()} on $j$ returns false, as will all further calls.
+
+If $f$ is synchronous and is not a generator (\ref{functions}) then execution of the body of $f$ begins immediately.  When $f$ terminates the current return value is returned to the caller.
+
+
+Execution of $f$ terminates when the first of the following occurs:
 \begin{itemize}
 \item An exception is thrown and not caught within the current function activation. 
-\item A return statement (\ref{return}) immediately nested in the body of $f$ is executed.
+\item A return statement (\ref{return}) immediately nested in the body of $f$ is executed and not intercepted in a \FINALLY{} (\ref{try}) clause.
 \item The last statement of the body completes execution.
 \end{itemize}
 
 
 
 
 \subsubsection{ Actual Argument List Evaluation}
 \label{actualArguments}
 
-Function invocation involves evaluation of the list of actual arguments to the function and binding of the results to the function`s formal parameters.
+Function invocation involves evaluation of the list of actual arguments to the function and binding of the results to the function's formal parameters.
 
 \begin{grammar}
 {\bf arguments:}
       `(' argumentList? `)'
     .
 
 {\bf argumentList:}namedArgument (`,' namedArgument)*;
   %    expressionList ',' spreadArgument;
       expressionList (`,' namedArgument)*
 %      spreadArgument
@@ skipping 96 matching lines @@
 
 \commentary{
 The implication of this definition, and the other definitions involving the method \code{call()}, is that user defined types can be used as function values provided they define a \CALL{} method. The method \CALL{} is special in this regard. The signature of the \CALL{} method determines the signature used when using the object via the built-in invocation syntax.
 }
 
 It is a static warning if the static type $F$ of $e_f$ may not be assigned to a function type.  If $F$ is not a function type, the static type of $i$ is \DYNAMIC{}. Otherwise 
 the static type of $i$ is the declared return type of  $F$.  
 %\item Let $T_i$ be the static type of $a_i, i \in 1 .. n+k$. It is a static warning if $F$ is not a supertype of  $(T_1, \ldots, T_n, [T_{n+1}$ $x_{n+1}, \ldots, T_{n+k}$ $x_{n+k}]) \to \bot$.
 %\end{itemize}
 
-\subsection{Lookup}
+\subsection{ Lookup}
 
 \subsubsection{Method Lookup}
 \label{methodLookup}
 
 The result of a lookup of a method $m$ in object $o$ with respect to library $L$ is the result of  a lookup of method $m$ in class $C$ with respect to library $L$, where $C$ is the class of $o$.
 
 The result of  a lookup of method $m$ in class $C$ with respect to library $L$ is:
 If $C$ declares a concrete instance method named $m$ that is accessible to $L$,  then that method is the result of the lookup. Otherwise, if $C$ has a superclass $S$, then the result of the lookup is the result of looking up $m$  in $S$ with respect to $L$. Otherwise, we say that the method lookup has failed.
 
 \rationale {
 The motivation for skipping abstract members during lookup is largely to allow smoother mixin composition. 
 }
 
 
 \subsubsection{ Getter and Setter Lookup}
 \label{getterAndSetterLookup}
 
 The result of a lookup of a getter (respectively setter) $m$ in object $o$  with respect  to  library $L$ is the result of looking up getter (respectively setter) $m$ in class $C$ with respect to $L$, where $C$ is the class of $o$.
 
 The result of a lookup of a getter (respectively setter) $m$ in class $C$  with respect to library $L$ is:
 If $C$ declares a concrete instance getter (respectively setter) named $m$  that is accessible to $L$,  then that getter (respectively setter) is the result of the lookup. Otherwise, if $C$ has a superclass $S$, then the result of the lookup is the result of looking up getter (respectively setter) $m$ in $S$ with respect to $L$. Otherwise, we say that the lookup has failed.
 
 \rationale {
 The motivation for skipping abstract members during lookup is largely to allow smoother mixin composition. 
 }
 
 
-\subsection{Top level Getter Invocation}
+\subsection{ Top level Getter Invocation}
 \label{topLevelGetterInvocation}
 
 Evaluation of a top-level getter invocation $i$ of the form $m$, where $m$ is an identifier, proceeds as follows:
 
 The getter function $m$ is invoked. The value of $i$ is the result returned by the call to the getter function.
 \commentary{
 Note that the invocation is always defined. Per the rules for identifier references, an identifier will not be treated as a top-level getter invocation unless the getter $i$ is defined. 
 }
 
 The static type of $i$ is the declared return type of $m$.
@@ skipping 429 matching lines @@
 A {\em conditional expression} evaluates one of two expressions based on a boolean condition.
 
 \begin{grammar}
   {\bf conditionalExpression:}
      logicalOrExpression (`?' expressionWithoutCascade `{\escapegrammar :}' expressionWithoutCascade)?
     . % the first  branches could  top level expressions, it seems, but certainly NOT the second
 \end{grammar}
 
 Evaluation of a conditional expression $c$ of the form $e_1 ? e_2 : e_3$ proceeds as follows:
 
-First, $e_1$ is evaluated to an object $o_1$.  Then, $o_1$ is  subjected to boolean conversion (\ref{booleanConversion}) producing an object $r$.  If $r$ is true, then the value of $c$ is the result of evaluating the expression $e_2$. Otherwise the value of $c$ is the result of evaluating the expression $e_3$. 
+First, $e_1$ is evaluated to an object $o_1$.  Then, $o_1$ is  subjected to boolean conversion (\ref{booleanConversion}) producing an object $r$.  If $r$ is \TRUE, then the value of $c$ is the result of evaluating the expression $e_2$. Otherwise the value of $c$ is the result of evaluating the expression $e_3$. 
 
 If all of the following hold:
 \begin{itemize}
 \item $e_1$ shows that a variable $v$ has type $T$.
 \item $v$ is not potentially mutated in $e_2$ or within a closure.
 \item If the variable $v$ is accessed by a closure in $e_2$ then the variable $v$ is not potentially mutated anywhere in the scope of $v$.
 \end{itemize}
 
 then the type of $v$ is known to be $T$ in $e_2$.
 
@@ skipping 13 matching lines @@
 
 
 {\bf logicalAndExpression:}
       equalityExpression (`\&\&' equalityExpression)*
 %      bitwiseOrExpression (`\&\&' bitwiseOrExpression)*
     .
  \end{grammar}
  
 A {\em logical boolean expression} is either an equality expression (\ref{equality}), or an invocation of a logical boolean operator on an expression $e_1$ with argument $e_2$.
  
-Evaluation of a logical boolean expression $b$ of the form $e_1 || e_2$ causes the evaluation of $e_1$ which is then  subjected to boolean conversion, yielding an object $o_1$; if $o_1$ is true, the result of evaluating $b$ is true, otherwise $e_2$ is evaluated to an object $o_2$, which is then subjected to boolean conversion (\ref{booleanConversion}) producing an object $r$, which is the value of $b$. 
+Evaluation of a logical boolean expression $b$ of the form $e_1 || e_2$ causes the evaluation of $e_1$ which is then  subjected to boolean conversion, yielding an object $o_1$; if $o_1$ is \TRUE, the result of evaluating $b$ is \TRUE, otherwise $e_2$ is evaluated to an object $o_2$, which is then subjected to boolean conversion (\ref{booleanConversion}) producing an object $r$, which is the value of $b$. 
 
-Evaluation of a logical boolean expression $b$ of the form $e_1 \&\& e_2$ causes the evaluation of $e_1$ which is then subjected to boolean conversion, yielding an object $o_1$; if $o_1$ is not  true, the result of evaluating $b$ is false, otherwise $e_2$ is evaluated to an object $o_2$, which is then subjected to boolean conversion producing an object $r$, which is the value of $b$. 
+Evaluation of a logical boolean expression $b$ of the form $e_1 \&\& e_2$ causes the evaluation of $e_1$ which is then subjected to boolean conversion, yielding an object $o_1$; if $o_1$ is not  \TRUE, the result of evaluating $b$ is \FALSE, otherwise $e_2$ is evaluated to an object $o_2$, which is then subjected to boolean conversion producing an object $r$, which is the value of $b$. 
 
 A logical boolean expression $b$ of the form $e_1 \&\& e_2$ shows that a variable $v$ has type 
 $T$ if all of the following conditions hold:
 \begin{itemize}
 \item Either $e_1$ shows that $v$ has type $T$ or $e_2$ shows that $v$ has type $T$.
 \item $v$ is a local variable or formal parameter.
 \item The variable $v$ is not mutated in $e_2$ or within a closure.
 \end{itemize}
 
 Furthermore, if all of the following hold:
@@ skipping 188 matching lines @@
  
 The static type of an multiplicative expression is usually determined by the signature given in the declaration of the operator used. However, invocations of the operators \cd{*}, \cd{\%}  and \cd{\~{}/} of class \cd{int} are treated specially by the typechecker. The static type of an expression $e_1 * e_2$ where $e_1$ has static type \cd{int} is \cd{int} if the static type of $e_2$ is \cd{int}, and \cd{double} if the static type of $e_2$ is \cd{double}. The static type of an expression $e_1 \% e_2$ where $e_1$ has static type \cd{int} is \cd{int} if the static type of $e_2$ is \cd{int}, and \cd{double} if the static type of $e_2$ is \cd{double}.  The static type of an expression \cd{$e_1$ \~{}/ $e_2$} where $e_1$ has static type \cd{int} is \cd{int} if the static type of $e_2$ is \cd{int}.
  
 \subsection{ Unary Expressions}
 \label{unaryExpressions}
 
 Unary expressions invoke unary operators on objects.
 
 \begin{grammar}
 {\bf unaryExpression:}prefixOperator unaryExpression;
+      awaitExpression;
       postfixExpression;
       (minusOperator $|$ tildeOperator) \SUPER{};
       incrementOperator assignableExpression
     .
  
  {\bf prefixOperator:}minusOperator;
       negationOperator;
       tildeOperator
     .
        
        
   {\bf minusOperator:}`-';  .
 
 
     {\bf negationOperator:}`!' ;
       .
       
     {\bf tildeOperator:}  `\~{}'
     .
     
     
 \end{grammar}
 
-A {\em unary expression} is either a postfix expression  (\ref{postfixExpressions}), an invocation of a prefix operator on an expression or an invocation of a unary operator on either \SUPER{} or an expression $e$.
+A {\em unary expression} is either a postfix expression  (\ref{postfixExpressions}), an await expression (\ref{awaitExpressions}) or an invocation of a prefix operator on an expression or an invocation of a unary operator on either \SUPER{} or an expression $e$.
 
-The expression $!e$ is equivalent to the expression $e? \FALSE{} :\TRUE{}$. 
+The expression $!e$ is equivalent to the expression $e?$ $ \FALSE{} :\TRUE{}$. 
 
 Evaluation of an expression of the form \code{++$e$} is equivalent to \code{$e$ += 1}.  Evaluation of an expression of the form \code{-{}-$e$} is equivalent to \code{$e$ -= 1}. 
 
 %The expression $-e$ is equivalent to the method invocation \code{$e$.-()}.  The expression \code{-\SUPER{}} is equivalent  to the method invocation \code{\SUPER{}.-()}.
 
-An expression of the form \code{$op$ $e$} is equivalent to the method invocation \code{$e.op()$}. An expression of the form \code{$op$ \SUPER{}} is equivalent to the method invocation \code{\SUPER{}.$op()$}.
+An expression of the form \code{$op$ $e$} is equivalent to the method invocation \code{$e.op()$}. An expression of the form \code{$op$ \SUPER{}} is equivalent to the method invocation  (\ref{superInvocation}) \code{\SUPER{}.$op()$}.
+
+\subsection{ Await Expressions}
+\label{awaitExpressions}
+
+An {\em await expression} allows code to yield control until an asynchronous operation (\ref{functions}) completes. 
+
+ \begin{grammar}
+{\bf awaitExpression:}
+      \AWAIT{} unaryExpression
+ \end{grammar}
+
+Evaluation of an await expression $a$ of the form \AWAIT{} $e$ proceeds as follows:
+First, the expression $e$ is evaluated. Next:
+
+If $e$ evaluates to an instance of \code{Future}, $f$, then execution of the function $m$ immediately enclosing $a$ is suspended until after $f$ completes. The stream associated with the innermost enclosing asynchronous for loop (\ref{asynchronousFor-in}), if any, is paused. At some time after $f$ is completed, control returns to the current invocation. The stream associated with the innermost enclosing asynchronous for loop  (\ref{asynchronousFor-in}), if any, is resumed. If $f$ has completed with an exception $x$, $a$ raises $x$. If $f$ completes with a value $v$, $a$ evaluates to $v$.
+
+Otherwise, the value of $a$ is the value of $e$. If evaluation of $e$ raises an exception $x$, $a$ raises $x$.
+
+It is a compile-time error if  the function  immediately enclosing  $a$  is not declared asynchronous.
+
+\rationale{
+An await expression has no meaning in a synchronous function. If such a function were to suspend waiting for a future, it would no longer be synchronous.
+}
+
+\commentary{
+It is not a static warning if the type of $e$ is not a subtype of \code{Future}. Tools may choose to give a hint in such cases.
+}
+
+Let $flatten(T) = flatten(S)$ if $T = Future<S>$, and $T$ otherwise. The static type of $a$ is $flatten(T)$ where $T$ is the static type of $e$.
+
+\rationale{
+We collapse multiple layers of futures into one. If $e$ evaluates to a future $f$, the future will not invoke its \code{then()} callback until f completes to a non-future value, and so the result of an await is never a future, and the result of an async function will never have type \code{Future$<X>$} where $X$ itself is an invocation of \code{Future}. 
+}
+
 
 
      
 \subsection{ Postfix Expressions}
 \label{postfixExpressions}
 
 Postfix expressions invoke the postfix operators on objects.
 
  \begin{grammar}
 {\bf postfixExpression:}assignableExpression postfixOperator;
@@ skipping 155 matching lines @@
       identifier (`{\escapegrammar .}' identifier)?  
       . 
 \end{grammar}
 
 A built-in identifier is one of the identifiers produced by the production {\em BUILT\_IN\_IDENTIFIER}. It is a compile-time error if a built-in identifier is used as the declared name of a prefix, class, type parameter or type alias. It is a compile-time error to use a built-in identifier other than \DYNAMIC{} as a type annotation.
 
 \rationale{
 Built-in identifiers are identifiers that are used as keywords in Dart, but are not reserved words in Javascript. To minimize incompatibilities when porting Javascript code to Dart, we do not make these into reserved words. A built-in identifier may not be used to name a class or type. In other words, they are treated as reserved words when used as types.  This eliminates many confusing situations without causing compatibility problems. After all, a Javascript program has no type declarations or annotations so no clash can occur.  Furthermore, types should begin with an uppercase letter (see the appendix) and so no clash should occur in any Dart user program anyway.
 }
 
+It is a compile-time error if any of the identifiers \ASYNC, \AWAIT{} or \YIELD{} is used as an identifier in a function body marked with either \ASYNC{}, \ASYNC* or \SYNC*.
+
+\rationale{
+For compatibility reasons, new constructs cannot  rely upon new reserved words or even built-in identifiers. However, the constructs above are only usable in contexts that require special markers introduced concurrently with these constructs, so no old code could use them. Hence the restriction, which treats these names as reserved words in a limited context.
+}
+
 Evaluation of an identifier expression $e$ of the form $id$ proceeds as follows:
 
 
 Let $d$ be the innermost declaration in the enclosing lexical scope whose name is $id$ or $id=$.  If no such declaration exists in the lexical scope, let $d$ be the declaration of the inherited member named $id$ if it exists. 
 %If no such member exists, let $d$ be the declaration of the static member name $id$ declared in a superclass of the current class, if it exists.
 
 \begin{itemize}
 \item if $d$ is a prefix $p$, a compile-time error occurs unless the token immediately following $d$ is \code{'.'}.
 \item If $d$ is a class or type alias $T$, the value of $e$ is an instance of  class \code{Type} (or a subclass thereof) reifying $T$.
 \item If $d$ is a type parameter $T$, then the value of $e$ is the value of the actual type argument corresponding to $T$ that was  passed to the generative constructor that created the current binding of \THIS{}. If, however, $e$ occurs inside a static member, a compile-time error occurs.
@@ skipping 47 matching lines @@
  .
  
  
 {\bf isOperator:}
 \IS{} `!'?
     .
  \end{grammar}
  
  Evaluation of the is-expression \code{$e$ \IS{} $T$} proceeds as follows:
 
-The expression $e$ is evaluated to a value $v$. Then, if $T$ is a malformed or deferred type (\ref{staticTypes}), a dynamic error occurs. Otherwise, if the interface of the class of $v$ is a subtype of $T$, the is-expression evaluates to true. Otherwise it evaluates to false.
+The expression $e$ is evaluated to a value $v$. Then, if $T$ is a malformed or deferred type (\ref{staticTypes}), a dynamic error occurs. Otherwise, if the interface of the class of $v$ is a subtype of $T$, the is-expression evaluates to \TRUE. Otherwise it evaluates to \FALSE.
 
 \commentary{It follows that \code{$e$ \IS{} Object} is always true. This makes sense in a language where everything is an object. 
 
 Also note that \code{\NULL{} \IS{} $T$} is false unless $T = \code{Object}$, $T = \code{\DYNAMIC{}}$ or $T = \code{Null}$.  The former two are useless, as is anything of the form \code{$e$ \IS{} Object} or \code{$e$ \IS{} \DYNAMIC{}}.  Users should test for a null value directly rather than via type tests.
 }
 
 The is-expression \code{$e$ \IS{}! $T$} is equivalent to \code{!($e$ \IS{} $T$)}.
 
 % Add flow dependent types
 
@@ skipping 55 matching lines @@
       forStatement;
       whileStatement;
       doStatement;
       switchStatement;
       ifStatement;
       rethrowStatement;
       tryStatement;
       breakStatement;
       continueStatement;
       returnStatement;
+      yieldStatement;
+      yieldEachStatement;
       expressionStatement;
       assertStatement;
       localFunctionDeclaration
     .
  \end{grammar}
  
  \subsection{Blocks}
  \label{blocks}
  
  A {\em block statement} supports sequencing of code.
@@ skipping 170 matching lines @@
      
 
     
 \subsection{For}
 \label{for}
 
 The {\em for statement} supports iteration.
 
 \begin{grammar}
 {\bf forStatement:}
-     \FOR{} `(' forLoopParts `)' statement
+     \AWAIT? \FOR{} `(' forLoopParts `)' statement
     .
 
 {\bf forLoopParts:}forInitializerStatement expression? `{\escapegrammar ;}' expressionList?;
       declaredIdentifier \IN{} expression;
       identifier \IN{} expression
     .
 
 {\bf forInitializerStatement:}localVariableDeclaration `{\escapegrammar ;}';
       expression? `{\escapegrammar ;}'
     .
  \end{grammar}
  
- The for statement has two forms - the traditional for loop and the for-in statement.
+ The for statement has three forms - the traditional for loop and two forms of the for-in statement - synchronous and asynchronous.
 
 \subsubsection{For Loop}
 \label{forLoop}
 
 
 Execution of a for statement of the form   \code{ \FOR{} (\VAR{} $v = e_0$ ; $c$; $e$) $s$} proceeds as follows:
 
 If $c$ is empty then let $c^\prime$ be \TRUE{} otherwise let  $c^\prime$ be $c$.
 
 First the variable declaration statement \VAR{} $v = e_0$ is executed. Then:
@@ skipping 46 matching lines @@
    $finalConstVarOrType?$ id = n0.current;
    $s$ 
 \}
 \end{dartCode}
 where \code{n0} is an identifier that does not occur anywhere in the program.
 
 \commentary{
 Note that in fact, using a  \CONST{} variable would give rise to a compile time error since \cd{n0.current} is not a constant expression.  
 }
  
+\subsubsection{Asynchronous For-in}
+\label{asynchronousFor-in}
+
+A for-in statement may be asynchronous. The asynchronous form is designed to iterate over streams. An asynchronous for loop is distinguished by the keyword \AWAIT{} immediately preceding the keyword \FOR.
+
+Execution of a for-in statement of the form  \code{\AWAIT{} \FOR{} (finalConstVarOrType? id \IN{} $e$) $s$} proceeds as follows:
+
+The expression $e$ is evaluated to an object $o$. It is a dynamic error if $o$ is not an instance of a class that implements \code{Stream}. Otherwise, the expression \code{\AWAIT{} $v_f$}  (\ref{awaitExpressions}) is evaluated, where $v_f$ is a fresh variable whose value is a fresh instance (\ref{generativeConstructors}) $f$ implementing the built-in class \code{Future}.
+
+The stream $o$ is listened to,  and on each data event in $o$ the statement $s$ is executed with \code{id} bound to the value of the current element of the stream. If $s$ raises an exception, or if $o$ raises an exception, then $f$ is completed with that exception. Otherwise, when all events in the stream $o$ have been processed, $f$ is completed with \NULL{}  (\ref{null}).
+
+Let $u$ be the stream associated with the immediately enclosing asynchronous for loop or generator function (\ref{functions}), if any. If another event $e_u$ of $u$ occurs before execution of $s$ is complete, handling of $e_u$ must wait until $s$ is complete.
+
+\rationale{
+The future $f$ and the corresponding \AWAIT{} expression ensure that execution suspends as an asynchronous for loop begins and resumes after the \FOR{} statement when it ends. They also ensure that the stream of any enclosing asynchronous \FOR{} loop is paused for the duration of this loop.
+}
+
+It is a compile-time error if an asynchronous for-in statement appears inside a synchronous function (\ref{functions}). It is a compile-time error if a traditional for loop  (\ref{forLoop}) is prefixed by the \AWAIT{}  keyword.
+
+\rationale{An asynchronous loop would make no sense within a synchronous function, for the same reasons that an await expression makes no sense in a synchronous function.}
+
+ 
 \subsection{While}
 \label{while}
 
 The while statement supports conditional iteration, where the condition is evaluated prior to the loop.
 
 \begin{grammar}
 {\bf whileStatement:}
       \WHILE{} `(' expression `)' statement  % could do top level here, and in for
 .
  \end{grammar}
@@ skipping 152 matching lines @@
 If execution reaches the point after $s_h$  then  a runtime error occurs, unless $h = n$.
 
 
 \commentary{
 In other words, there is no implicit fall-through between cases. The last case in a switch (default or otherwise) can `fall-through' to the end of the statement.
 }
 
 It is a static warning if the type of $e$ may not be assigned to the type of $e_k$. It is a static warning if the last statement of the statement sequence $s_k$ is not a \BREAK{}, \CONTINUE{}, \RETURN{} or \THROW{} statement.
 
 \rationale{
-The behavior of switch cases intentionally differs from the C tradition.  Implicit fall through is a known cause of programming errors and therefore disallowed.  Why not simply break the flow implicitly at the end of every case, rather than requiring explicit code to do so?  This would indeed be cleaner.  It would also be cleaner to insist that each case have a single (possibly compound) statement.  We have chosen not to do so in order to facilitate porting of switch statements from other languages.  Implicitly breaking the control flow at the end of a case would silently alter the meaning of ported code that relied on fall-through, potentially forcing the programmer to deal with subtle bugs. Our design ensures that the difference is immediately brought to the coder`s attention.  The programmer will be notified at compile-time if they forget to end a case with a statement that terminates the straight-line control flow. We could make this warning a compile-time error, but refrain from doing so because do not wish to force the programmer to deal with this issue immediately while porting code.  If developers ignore the warning and run their code, a run time error will prevent the program from misbehaving in hard-to-debug ways (at least with respect to this issue).
+The behavior of switch cases intentionally differs from the C tradition.  Implicit fall through is a known cause of programming errors and therefore disallowed.  Why not simply break the flow implicitly at the end of every case, rather than requiring explicit code to do so?  This would indeed be cleaner.  It would also be cleaner to insist that each case have a single (possibly compound) statement.  We have chosen not to do so in order to facilitate porting of switch statements from other languages.  Implicitly breaking the control flow at the end of a case would silently alter the meaning of ported code that relied on fall-through, potentially forcing the programmer to deal with subtle bugs. Our design ensures that the difference is immediately brought to the coder's attention.  The programmer will be notified at compile-time if they forget to end a case with a statement that terminates the straight-line control flow. We could make this warning a compile-time error, but refrain from doing so because do not wish to force the programmer to deal with this issue immediately while porting code.  If developers ignore the warning and run their code, a run time error will prevent the program from misbehaving in hard-to-debug ways (at least with respect to this issue).
 
 The sophistication of the analysis of fall-through is another issue. For now, we have opted for a very straightforward syntactic requirement. There are obviously situations where code does not fall through, and yet does not conform to these simple rules, e.g.:
 }
 
 \begin{dartCode}
 \SWITCH{} (x) \{
   \CASE{} 1: \TRY{} \{ $\ldots$ \RETURN{};\} \FINALLY{} \{ $\ldots$ \RETURN{};\}
 \}
 \end{dartCode}
 
@@ skipping 14 matching lines @@
 
  
 \subsection{ Rethrow}
 \label{rethrow}
 
 
 The {\em rethrow statement}  is used to re-raise an exception.
 
  \begin{grammar}
 {\bf rethrowStatement:}
-     \RETHROW{}
+     \RETHROW{}  `{\escapegrammar ;}'
     .
  \end{grammar}
  
 Execution of a \code{\RETHROW{}} statement proceeds as follows:
-Control is transferred to the nearest innermost enclosing exception handler (\ref{try}).
 
-\commentary{No change is made to the current exception.}
+Let $f$ be the immediately enclosing function, and let \code{\ON{} $T$ \CATCH{} ($p_1$, $p_2$)}  be the immediately enclosing catch clause (\ref{try}).
 
-It is a compile-time error if a  \code{\RETHROW{}} statement is not enclosed within an on-catch clause. 
+\rationale{
+A \RETHROW{} statement always appears inside a \CATCH{} clause, and any \CATCH{} clause is semantically equivalent to some \CATCH{} clause of the form \code{\ON{} $T$ \CATCH{} (p1, p2)}.  So we can assume that the \RETHROW{} is enclosed in a \CATCH{} clause of that form.
+}
 
-%The static type of a rethrow expression is $\bot$.
+The current exception (\ref{throw}) is set to $p_1$, the current return value (\ref{return}) becomes undefined, and the active stack trace (\ref{try}) is set to $p_2$.
+
+If $f$ is marked \ASYNC{} or \ASYNC* (\ref{functions}) and there is a dynamically enclosing exception handler (\ref{try}) $h$ introduced by the current activation, control is transferred to $h$, otherwise $f$  terminates.
+
+\rationale{
+In the case of an asynchronous function, the dynamically enclosing exception handler is only relevant within the function. If an exception is not caught within the function, the exception value is channelled through a future or stream rather than propagating via exception handlers.
+}
+
+Otherwise, control is transferred to the  innermost enclosing exception handler.
+
+\commentary{The change in control may result in multiple functions terminating if these functions do not catch the exception via a \CATCH{} or \FINALLY{} clause, both of which introduce a dynamically enclosing exception handler.}
+
+It is a compile-time error if a  \code{\RETHROW{}} statement is not enclosed within an \ON-\CATCH{} clause. 
 
 
 
 \subsection{ Try}
 \label{try}
 
 The try statement supports the definition of exception handling code in a structured way.
 
 \begin{grammar}
 {\bf tryStatement:}
@@ skipping 30 matching lines @@
 \commentary {
 It is of course a static warning if $T$ is a deferred or malformed type.
 }
 
 An \ON{}-\CATCH{} clause of the form   \code{\ON{} $T$ \CATCH{} ($p_1, p_2$) $s$} introduces a new scope $CS$ in which local variables specified by $p_1$ and $p_2$ are defined. The statement $s$ is enclosed within $CS$.
 
 
 An \ON{}-\CATCH{} clause of the form  \code{\ON{} $T$ \CATCH{} ($p_1$) $s$} is equivalent to an \ON{}-\CATCH{} clause  \code{\ON{} $T$ \CATCH{} ($p_1, p_2$) $s$} where $p_2$ is an identifier that does not occur anywhere else in the program. 
 
 
-An \ON{}-\CATCH{} clause of the form  \code{\CATCH{} ($p$) $s$} is equivalent to an \ON{}-\CATCH{} clause  \code{\ON{} \DYNAMIC{} \CATCH{} ($p$) $s$}. An \ON{}-\CATCH{} clause of the form  \code{\CATCH{} ($p_1, p_2$) $s$} is equivalent to an \ON{}-\CATCH{} clause  \code{\ON{} \DYNAMIC{} \CATCH{} ($p_1, p_2$) $s$}
+An \ON{}-\CATCH{} clause of the form  \code{\CATCH{} ($p$) $s$} is equivalent to an \ON{}-\CATCH{} clause  \code{\ON{} \DYNAMIC{} \CATCH{} ($p$) $s$}. An \ON{}-\CATCH{} clause of the form  \code{\CATCH{} ($p_1, p_2$) $s$} is equivalent to an \ON{}-\CATCH{} clause  \code{\ON{} \DYNAMIC{} \CATCH{} ($p_1, p_2$) $s$}.
 
 
 %If an explicit type is associated with of $p_2$, it is a static warning if that type is not \code{Object} or \DYNAMIC{}.
 
-The {\em active stack trace} is an object whose \code{toString()} method produces a string that is a record of exactly those function activations within the current isolate that had not completed execution at the point where the current exception was thrown.
+The {\em active stack trace} is an object whose \code{toString()} method produces a string that is a record of exactly those function activations within the current isolate that had not completed execution at the point where the current exception (\ref{throw}) was thrown.
 %\begin{enumerate}
 %\item Started execution after the currently executing function.
 %\item Had not completed execution at the point where the exception caught by the currently executing  \ON{}-\CATCH{} clause was initially thrown. 
 %\commentary{The active stack trace contains the frames between the exception handling code and the original point when an exception is thrown, not where it was rethrown.}
 %\end{enumerate}
 
  \commentary{
 This implies that no synthetic function activations may be added to the trace, nor may any source level activations be omitted. 
 This means, for example, that any inlining of functions done as an optimization must not be visible in the trace. Similarly, any synthetic routines used by the implementation must not appear in the trace.
 
 Nothing is said about how any native function calls may be represented in the trace.
  }
  
 \commentary{
 Note that we say nothing about the identity of the stack trace, or what notion of equality is defined for stack traces.
 }
  
 % Sadly, the info below cannot be computed efficiently. It would need to be computed at the throw point, since at latte points it might be destroyed. Native code in calling frames executes relative to the stack pointer, which therefore needs to be reset as each frame is unwound.  This means that the
 % OS kernel can dispose of this stack memory - it is not reliably preserved. And such code must execute if only to test if the exception should be caught or sent onward.
 
 % For each such function activation, the active stack trace includes the name of the function, the bindings of all its formal parameters, local variables and \THIS{}, and the position at which the function was executing.
  
  % Is this controversial? We were thinking of viewing the trace as a List<Invocation>,
  % but that won't capture the receiver or the locals. More generally, we need a standard interface that describes these traces, so one can type the stack trace variable in the catch.
  
  \commentary{The term position should not be interpreted as a line number, but rather as a precise position - the exact character index of the  expression that raised  the exception. }
  
  % A position can be represented via a Token. If we make that part of the core reflection facility, we can state this here.
- 
- \rationale{The definition below is an attempt to characterize exception handling without resorting to a normal/abrupt completion formulation. It has the advantage that one need not specify abrupt completion behavior for every compound statement.  On the other hand, it is new and different and needs more thought.
-}
-
-% so, we need to fix things so that returns in the try still go through the finally clause and so that
-% uncaught or rethrown exceptions propagate  from the finally clause unless it returns.
-
-% plan: return transfers control to the enclosing finally clause if it exists and erases
-% any current stack trace & exception.
-% But how to ensure return leaves the finally if it does not throw? special text? say return
-% does the finally and then xfers control ?
 
 A try statement \TRY{} $s_1$ $on-catch_1 \ldots  on-catch_n$ \FINALLY{} $s_f$  defines an exception handler $h$ that executes as follows:
 
 The \ON{}-\CATCH{} clauses are examined in order, starting with $catch_1$, until either an \ON{}-\CATCH{} clause that matches the current exception (\ref{throw}) is found, or the list of \ON{}-\CATCH{} clauses has been exhausted. If an \ON{}-\CATCH{} clause $on-catch_k$ is found, then $p_{k1}$ is bound to the current exception,  $p_{k2}$, if declared,  is bound to the active stack trace, and then $catch_k$ is executed. If no \ON{}-\CATCH{} clause is found, the \FINALLY{} clause is executed. Then, execution resumes at the end of the try statement.
 
 
-A finally clause \FINALLY{} $s$ defines an exception handler $h$ that executes by executing the finally clause. 
-% If the current exception is defined 
+A finally clause \FINALLY{} $s$ defines an exception handler $h$ that executes as follows:
 
-Then, execution resumes at the end of the try statement.
+Let $r$ be the current return value (\ref{return}). Then the current return value becomes undefined. Any open streams associated with any asynchronous for loops (\ref{asynchronousFor-in}) and yield-each (\ref{yieldEach}) statements executing within the dynamic scope of $h$ are canceled. 
+
+\rationale{
+Streams left open by for loops that were escaped for whatever reason would be canceled at function termination, but it is best to cancel them as soon as possible.
+}
+
+Then the \FINALLY{} clause is executed. Let $m$ be the immediately enclosing function. If $r$ is defined then the current return value is set to $r$ and then:
+\begin{itemize}
+\item
+ if there is a dynamically enclosing error handler $g$ defined by a \FINALLY{} clause in $m$, control is transferred to $g$.
+ \item
+Otherwise $m$ terminates. 
+\end{itemize}
+
+Otherwise, execution resumes at the end of the try statement.
 
 Execution of an \ON{}-\CATCH{} clause \code{\ON{} $T$ \CATCH{} ($p_1$, $p_2$)} $s$ of a try statement $t$ proceeds as follows: The statement $s$ is executed in the dynamic scope of the exception handler defined by the finally clause of $t$. Then, the current exception and active stack trace both become undefined.
 
 Execution of a \FINALLY{} clause \FINALLY{} $s$ of a try statement proceeds as follows: 
 
-The statement $s$ is executed. Then, if the current exception is defined, control is transferred to the nearest dynamically enclosing exception handler.
+Let $x$ be the current exception and let $t$ be the active stack trace. Then the current exception and the active stack trace both become undefined. The statement $s$ is executed. Then, if $x$ is defined,  it is rethrown as if by a rethrow statement (\ref{rethrow}) enclosed in a \CATCH{} clause of the form \code{\CATCH{} ($v_x$, $v_t$)} where $v_x$ and $v_t$ are fresh variables bound to $x$ and $t$ respectively.
+
 
 Execution of a try statement of the form \code{\TRY{} $s_1$ $on-catch_1 \ldots on-catch_n$ \FINALLY{} $s_f$;}  proceeds as follows:
 
 The statement $s_1$ is executed in the dynamic scope of the exception handler defined by the try statement. Then, the \FINALLY{} clause is executed.
 
 \commentary{
 Whether any of the \ON{}-\CATCH{} clauses is executed depends on whether a matching exception has been raised by $s_1$ (see the specification of the throw statement). 
 
 If $s_1$ has raised an exception, it will transfer control to the try statement's handler, which will examine the catch clauses in order for a match as specified above. If no matches are found, the handler will execute the \FINALLY{} clause. 
 
 If a matching \ON{}-\CATCH{} was found, it will execute first, and then the \FINALLY{} clause will be executed. 
 
 If an exception is thrown during execution of an \ON{}-\CATCH{} clause, this will transfer control to the handler for the \FINALLY{} clause, causing the \FINALLY{} clause to execute in this case as well. 
 
 If no exception was raised, the \FINALLY{} clause is also executed. Execution of the \FINALLY{} clause could also raise an exception, which will cause transfer of control to the next enclosing handler. 
 }
 
-A try statement of the form \code{\TRY{} $s_1$ $on-catch_1 \ldots on-catch_n$;} is equivalent to the statement \code{\TRY{} $s_1$ $on-catch_1 \ldots on-catch_n$ \FINALLY{} $\{\}$;}.
+A try statement of the form \code{\TRY{} $s_1$ $on-catch_1 \ldots on-catch_n$;} is equivalent to the statement \code{\TRY{} $s_1$ $on-catch_1 \ldots on-catch_n$ \FINALLY{} $\{\}$}.
  
 
 \subsection{ Return}
 \label{return}
 
-The {\em return statement} returns a result to the caller of a function.
+The {\em return statement} returns a result to the caller of a synchronous function,  completes the future associated with an asynchronous function or closes the stream associated with an asynchronous generator (\ref{functions}).
+
 
  \begin{grammar}
 {\bf returnStatement:}
-    \RETURN{} expression? '{\escapegrammar ;}' % could do top level here
+    \RETURN{} expression? `{\escapegrammar ;}' % could do top level here
     .
  \end{grammar}
+ 
+ \commentary{
+ Due to \FINALLY{} clauses, the precise behavior of \RETURN{} is a little more involved. Whether the value a return statement is supposed to return is actually returned depends on the behavior of any \FINALLY{} clauses in effect when executing the return. A \FINALLY{} clause may choose to return another value, or throw an exception, or even redirect control flow leading to other returns or throws. All a return statement really does is set a value that is intended to be returned when the function terminates. 
+ }
+
+The {\em current return value} is a unique value specific to a given function activation. It is undefined unless explicitly set in this specification.
     
-Executing a return statement 
+Executing a return statement \code{\RETURN{} $e$;} proceeds as follows:
 
-\code{\RETURN{} $e$;}
+First the expression $e$ is evaluated, producing an object $o$. Next:
+\begin{itemize}
+\item  
+The current return value is set to $o$ and the current exception (\ref{throw}) and active stack trace (\ref{try}) become undefined.
+\item
+Let $c$ be the \FINALLY{} clause of the innermost enclosing try-finally statement (\ref{try}), if any. If $c$ is defined, let $h$ be the handler induced by $c$. If $h$ is defined, control is transferred to $h$. 
+\item
+Otherwise execution of the current method terminates.
+\end{itemize}
 
-first causes evaluation of the expression $e$, producing an object $o$. Next, control is transferred to the caller of the current function activation, and the object $o$ is provided to the caller as the result of the function call.
+\commentary{
+In the simplest case, the immediately enclosing function is an ordinary, synchronous non-generator, and upon function termination, the current return value is given to the caller.  The other possibility is that the function is marked \ASYNC{}, in which case the current return value is used to complete the future associated with the function. Both these scenarios are specified in section \ref{functionInvocation}.
+The enclosing function cannot be marked as generator (i.e, \ASYNC* or \SYNC*), since generators are not allowed to contain a statement of the form \code{\RETURN{} $e$;} as discussed below.
+}
 
-It is a static type warning if the type of $e$ may not be assigned to the declared return type of the immediately enclosing function. 
-%It is a static warning if the immediately enclosing function of a return statement of the form \code{\RETURN{} $e$;} is \VOID{}.
+Let $T$ be the static type of $e$ and let $f$ be the immediately enclosing function.  
 
-In checked mode, it is a dynamic type error if $o$ is not \NULL{} and the runtime type of $o$ is not a subtype of the actual return type (\ref{actualTypeOfADeclaration}) of the immediately enclosing function.
+It is a static type warning if the body of $f$ is marked \ASYNC{} and the type \code{Future$<$flatten(T)$>$} (\ref{awaitExpressions}) may not be assigned to the declared return type of $f$.   Otherwise, it is a static type warning if $T$ may not be assigned to the declared return type of $f$. 
+
+Let $S$ be the runtime type of $o$. In checked mode:
+\begin{itemize}
+\item  If the body of $f$ is marked \ASYNC{} (\ref{functions}) it is a dynamic type error if $o$ is not \NULL{} (\ref{null}) and \code{Future$<$S$>$} is not a subtype of the actual return type  (\ref{actualTypeOfADeclaration}) of $f$.
+\item Otherwise, it is a dynamic type error if $o$ is not \NULL{} and the runtime type of $o$ is not a subtype of the actual return type of $f$.
+\end{itemize}
 
 It is a compile-time error if a return statement of the form \code{\RETURN{} $e$;} appears in a generative constructor (\ref{generativeConstructors}).
 
 \rationale{
 It is quite easy to forget to add the factory prefix for a constructor, accidentally converting a factory into a generative constructor. The static checker may detect a type mismatch in some, but not all, of these cases. The rule above helps catch such errors, which can otherwise be very hard to recognize. There is no real downside to it, as returning a value from a generative constructor is meaningless.
 }
 
+It is a compile-time error if a return statement of the form \code{\RETURN{} $e$;} appears in a generator function.
+
+\rationale{
+In the case of a generator function, the value returned by the function is the iterable or stream associated with it, and individual elements are added to that iterable using yield statements, and so returning a value makes no sense. 
+}
+
 Let $f$ be the function immediately enclosing a return statement of the form \RETURN{}; It is a static warning if both of the following conditions hold:
 \begin{itemize}
-\item  $f$ is not a generative constructor.
-\item The return type of $f$ may not be assigned to \VOID{}. 
+\item  $f$ is neither a generator nor a generative constructor.
+\item The return type of $f$ may not be assigned to \VOID{} (\ref{typeVoid}). 
 \end{itemize}
 
 \commentary{
-Hence, a static warning will not be issued if $f$ has no declared return type, since the return type would be  \DYNAMIC{} and  \DYNAMIC{} may be assigned to \VOID{}. However, any function that declares a return type must return an expression explicitly.
+Hence, a static warning will not be issued if $f$ has no declared return type, since the return type would be  \DYNAMIC{} and  \DYNAMIC{} may be assigned to \VOID{}. However, any non-generator function that declares a return type must return an expression explicitly.
 }
 
 \rationale{This helps catch situations where users forget to return a value in a return statement.}
 
-A return statement of the form \code{\RETURN{};}  is executed by executing the statement  \code{\RETURN{} \NULL{};} if it occurs inside a method, getter, setter or factory; otherwise, the return statement necessarily occurs inside a generative constructor, in which case it is executed by executing  \code{\RETURN{} \THIS{};}.
+A return statement with no expression, \code{\RETURN;} is executed as follows:
+
+If the immediately enclosing function $f$ is a generator, then:
+\begin{itemize}
+\item
+The current return value is set to \NULL{}.
+\item 
+Let $c$ be the \FINALLY{} clause of the innermost enclosing try-finally statement, if any. If $c$ is defined,  let $h$ be the handler induced by $c$. If $h$ is defined, control is transferred to $h$.
+\item
+Otherwise, execution of the current method terminates. 
+\end{itemize}
+
+Otherwise the return statement is executed by executing the statement  \code{\RETURN{} \NULL{};} if it occurs inside a method, getter, setter or factory; otherwise, the return statement necessarily occurs inside a generative constructor, in which case it is executed by executing  \code{\RETURN{} \THIS{};}.
 
 \commentary{Despite the fact that \code{\RETURN{};} is executed as if by a \code{\RETURN{} $e$;}, it is important to understand that it is not a static warning to include a statement of the form \code{\RETURN{};} 
 %in a \VOID{} function; neither is it illegal 
 in a generative constructor. The rules relate only to the specific syntactic form \code{\RETURN{} $e$;}.
 }
 
 
 \rationale{
 The motivation for formulating \code{\RETURN{};} in this way stems from the basic requirement that all function invocations indeed return a value. Function invocations are expressions, and we cannot rely on a mandatory typechecker to always prohibit use of \VOID{} functions in expressions. Hence, a return statement must always return a value, even if no expression is specified.
 
 The question then becomes, what value should a return statement return when no return expression is given. In a generative constructor, it is obviously the object being constructed (\THIS{}). A void function is not expected to participate in an expression, which is why it is marked \VOID{} in the first place. Hence, this situation is a mistake which should be detected as soon as possible. The static rules help here, but if the code is executed, using \NULL{} leads to fast failure, which is desirable in this case. The same rationale applies for function bodies that do not contain a return statement at all.
 }
 
 It is a static warning if a function contains both one or more explicit return statements of the form \code{\RETURN;} and one or more return statements of the form \code{\RETURN{} $e$;}.
 
 
+
+
 \subsection{ Labels}
 \label{labels}
 
 A {\em label} is an identifier followed by a colon. A {\em labeled statement} is a statement prefixed by a label $L$.  A {\em labeled case clause} is a case clause within a switch statement (\ref{switch}) prefixed by a label $L$.
 
 \rationale{The sole role of labels is to provide targets for the break (\ref{break}) and continue (\ref{continue}) statements.}
 
 %\Q{Are labels in a separate namespace? Bug 49774299} 
 
  \begin{grammar}
 {\bf label:}
-      identifier '{\escapegrammar :}'
+      identifier `{\escapegrammar :}'
     .
  \end{grammar}
  
  The semantics of a labeled statement $L: s$ are identical to those of the statement $s$. The namespace of labels is distinct from the one used for types, functions and variables.
 
 The scope of a label that labels a statement $s$ is $s$. The scope of a label that labels a case clause of a switch statement $s$ is $s$.
 
 \rationale{Labels should be avoided by programmers at all costs. The motivation for including labels in the language is primarily making Dart a better target for code generation.
 }
 
  
 \subsection{ Break}
 \label{break}
 
 The {\em break statement} consists of the reserved word \BREAK{} and an optional label (\ref{labels}). 
 
 \begin{grammar}
 {\bf breakStatement:}
-     \BREAK{} identifier? '{\escapegrammar ;}'
+     \BREAK{} identifier? `{\escapegrammar ;}'
     .
  \end{grammar}
  
 Let $s_b$ be a \BREAK{} statement. If $s_b$ is of the form  \code{\BREAK{} $L$;}, then let $s_E$ be the the innermost labeled statement with label $L$ enclosing $s_b$. If $s_b$ is of the form \code{\BREAK{};},  then let $s_E$ be the the innermost  \DO{} (\ref{do}), \FOR{} (\ref{for}), \SWITCH{} (\ref{switch}) or \WHILE{} (\ref{while}) statement enclosing  $s_b$. It is a compile-time error if no such statement $s_E$ exists within the innermost function in which  $s_b$ occurs.  Furthermore, let $s_1, \ldots, s_n$ be those \TRY{} statements that are both enclosed in $s_E$ and that enclose  $s_b$, and that have a \FINALLY{} clause. Lastly, let $f_j$ be the \FINALLY{} clause of $s_j, 1 \le j \le n$.   Executing  $s_b$ first executes $f_1, \ldots,  f_n$ in innermost-clause-first  order and then terminates $s_E$. 
 
+If $s_E$ is an asynchronous for loop (\ref{asynchronousFor-in}), its associated stream subscription is canceled. Furthermore, let $a_k$ be the set of asynchronous for loops  and yield-each statements (\ref{yieldEach}) enclosing $s_b$ that are enclosed in $s_E , 1 \le k \le m$.   The stream subscriptions associated with $a_j$ are canceled, $1 \le j \le m$. 
+
+
 
 \subsection{ Continue}
 \label{continue}
 
 The {\em continue statement} consists of the reserved word \CONTINUE{} and an optional label (\ref{labels}). 
 
 \begin{grammar}
 {\bf continueStatement:}
-    \CONTINUE{} identifier? '{\escapegrammar ;}'
+    \CONTINUE{} identifier? `{\escapegrammar ;}'
         .
  \end{grammar}      
  
  Let $s_c$ be a \CONTINUE{} statement. If $s_c$ is of the form  \code{\CONTINUE{} $L$;}, then let $s_E$ be the the innermost labeled \DO{} (\ref{do}), \FOR{} (\ref{for}) or \WHILE{} (\ref{while}) statement or case clause with label $L$ enclosing $s_c$. If $s_c$ is of the form \code{\CONTINUE{};}  then let $s_E$ be the the innermost  \DO{} (\ref{do}), \FOR{} (\ref{for}) or \WHILE{} (\ref{while}) statement enclosing  $s_c$. It is a compile-time error if no such statement or case clause $s_E$ exists within the innermost function in which  $s_c$ occurs.  Furthermore, let $s_1, \ldots, s_n$ be those \TRY{} statements that are both enclosed in $s_E$ and that enclose  $s_c$, and that have a \FINALLY{} clause. Lastly, let $f_j$ be the \FINALLY{} clause of $s_j, 1 \le j \le n$.   Executing  $s_c$ first executes $f_1, \ldots,  f_n$ in innermost-clause-first  order. Then, if $s_E$ is a case clause, control is transferred to the case clause. Otherwise, $s_E$ is necessarily a loop and execution resumes after the last statement in the loop body.
  
  \commentary{
  In a while loop, that would be the boolean expression before the body. In a do loop, it would be the boolean expression after the body. In a for loop, it would be the increment clause.  In other words, execution continues to the next iteration of the loop.
  }
  
+ If $s_E$ is an asynchronous for loop (\ref{asynchronousFor-in}), let $a_k$ be the set of asynchronous for loops and yield-each statements (\ref{yieldEach}) enclosing $s_c$ that are enclosed in $s_E , 1 \le k \le m$.   The stream subscriptions associated with $a_j$ are canceled, $1 \le j \le m$. 
+ 
+ \subsection{ Yield and Yield-Each}
+ \label{yieldAndYieldEach}
+ 
+ \subsubsection{ Yield}
+ \label{yield}
+ 
+ The {\em yield statement} adds an element to the result of a generator function (\ref{functions}).
+
+ \begin{grammar}
+{\bf yieldStatement:}
+   \YIELD{} expression `{\escapegrammar ;}'
+      .
+\end{grammar}
+
+Execution of a statement $s$ of the form \code{\YIELD{} $e$;}  proceeds as follows:
+
+First, the expression $e$ is evaluated to an object $o$. If the enclosing function $m$ is marked \ASYNC* (\ref{functions}) and the stream $u$ associated with $m$ has been paused,  then execution of $m$ is suspended until $u$ is resumed or canceled.
+
+Next, $o$ is added to the iterable or stream associated with the immediately enclosing function. 
+
+If the enclosing function $m$ is marked \ASYNC* and the stream $u$ associated with $m$ has been canceled, then let $c$ be the \FINALLY{} clause (\ref{try}) of the innermost enclosing try-finally statement, if any. If $c$ is defined, let $h$ be the handler induced by $c$. If $h$ is defined, control is transferred to $h$. If $h$ is undefined, the immediately enclosing function terminates.
+
+\rationale{
+The stream associated with an asynchronous generator could be canceled by any code with a reference to that stream at any point where the generator was passivated.  Such a cancellation constitutes an irretrievable error for the generator. At this point, the only plausible action for the generator is to clean up after itself via its \FINALLY{} clauses.
+}
+
+If the enclosing function $m$ is marked \SYNC* (\ref{functions}) then:
+\begin{itemize}
+\item
+Execution of the function $m$ immediately enclosing $s$ is suspended until the method \code{moveNext()} is invoked upon the iterator used to initiate the current invocation of $m$. 
+\item
+The current call to \code{moveNext()} returns \TRUE.
+\end{itemize}
+
+It is a compile-time error if a yield statement appears in a function that is not a generator function.
+
+Let $T$ be the static type of $e$ and let $f$ be the immediately enclosing function.  It is a static type warning if either:
+\begin{itemize}
+\item
+ the body of $f$ is marked \ASYNC* and the type \code{Stream$<$T$>$} may not be assigned to the declared return type of $f$. 
+ \item
+ the body of $f$ is marked \SYNC* and the type \code{Iterable$<$T$>$} may not be assigned to the declared return type of $f$.
+ \end{itemize} 
+
+ 
+ \subsubsection{ Yield-Each}
+ \label{yieldEach}
+ 
+ The {\em yield-each statement} adds a series of values to the result of a generator function (\ref{functions}).
+ 
+ \begin{grammar}
+{\bf yieldEachStatement:}
+   \YIELD* expression `{\escapegrammar ;}'
+      .
+\end{grammar}
+
+Execution of a statement s of the form \code{\YIELD* $e$;}  proceeds as follows:
+
+First, the expression $e$ is evaluated to an object $o$. If the immediately enclosing function $m$ is synchronous, then it is a dynamic error if the class of $o$ does not implement \code{Iterable}.  If $m$ asynchronous, then it is a dynamic error if the class of $o$ does not implement \code{Stream}. Next, for each element $x$ of $o$:
+\begin{itemize}
+\item
+If $m$ is marked \ASYNC* (\ref{functions}) and the stream $u$ associated with $m$ has been paused,  then execution of $m$ is suspended until $u$ is resumed or canceled.
+\item
+ $x$ is added to the iterable or stream associated with $m$ in the order it appears in $o$.  
+ \item
+If $m$ is marked \ASYNC* and the stream $u$ associated with $m$ has been canceled, then let $c$ be the \FINALLY{} clause (\ref{try}) of the innermost enclosing try-finally statement, if any. If $c$ is defined,  let $h$ be the handler induced by $c$. If $h$ is defined, control is transferred to $h$. If $h$ is undefined, the immediately enclosing function terminates.
+\end{itemize}
+
+If the enclosing function is marked \SYNC* (\ref{functions}) then:
+\begin{itemize}
+\item
+Execution of the function $m$ immediately enclosing $s$ is suspended until the method \code{moveNext()} is invoked upon the iterator used to initiate the current invocation of $m$. 
+\item
+The current call to \code{moveNext()} returns \TRUE.
+\end{itemize}
+
+It is a compile-time error if a yield-each statement appears in a function that is not a generator function.
+
+Let $T$ be the static type of $e$ and let $f$ be the immediately enclosing function.  It is a static type warning if $T$ may not be assigned to the declared return type of $f$. 
+
 
 \subsection{ Assert}
 \label{assert}
 
 An {\em assert statement} is used to disrupt normal execution if a given boolean condition does not hold.
 
 \begin{grammar}
 {\bf assertStatement:}
-   assert '(' conditionalExpression ')' '{\escapegrammar ;}'
+   assert `(' conditionalExpression `)' `{\escapegrammar ;}'
       .
 \end{grammar}
       
 The assert statement has no effect in production mode. In checked mode, execution of an assert statement \code{\ASSERT{}($e$);} proceeds as follows:
 
 The conditional expression $e$ is evaluated to an object $o$. If the class of $o$ is a subtype of \code{Function} then let $r$ be the result of invoking $o$ with no arguments. Otherwise, let $r$ be $o$. 
 It is a dynamic type error if $o$ is not of type \code{bool} or of type \code{Function}, or if $r$ is not of type \code{bool}.  If $r$ is \FALSE{}, we say that the assertion failed. If $r$ is \TRUE{}, we say that the assertion succeeded. If the assertion succeeded, execution of the assert statement is complete. If the assertion failed, an \code{AssertionError} is thrown.
 
 %\Q{Might be cleaner to define it as \code{if (!$e$) \{\THROW{} \NEW{} AssertionError();\}} (in checked mode only).
 %What about an error message as part of the assert?}
@@ skipping 308 matching lines @@
 A library $L$ exports a namespace (\ref{scoping}), meaning that the declarations in the namespace are made available to other libraries if they choose to import $L$ (\ref{imports}).  The namespace that $L$ exports is known as its {\em exported namespace}.
 
 \begin{grammar}
 {\bf libraryExport:}
    metadata \EXPORT{}  uri  combinator* `{\escapegrammar ;}'
     .
  \end{grammar}
  
  An export specifies a URI $x$ where the declaration of an exported library is to be found.  It is a compile-time error if  the specified URI does not refer to a library declaration.  
 
-We say that a name {\em is exported by a library} (or equivalently, that a library {\em exports a name}) if the name is in the library's exported namespace. We say that a declaration {\em is exported by a library} (or equivalently, that a library {\em exports a declaration}) if the declaration is in the library`s exported namespace.
+We say that a name {\em is exported by a library} (or equivalently, that a library {\em exports a name}) if the name is in the library's exported namespace. We say that a declaration {\em is exported by a library} (or equivalently, that a library {\em exports a declaration}) if the declaration is in the library's exported namespace.
 
 A library always exports all names and all declarations in its public namespace. In addition, a library may choose to re-export additional libraries via {\em export directives}, often referred to simply as {\em exports}.
 
 Let $E$ be an export directive that refers to a URI via the string $s_1$. Evaluation of $E$  proceeds as follows:
 
 First,
 
  \begin{itemize}
  \item
 If  the URI that is the value of $s_1$ has not yet been accessed by an import or export directive  in the current isolate then the contents of the URI  are compiled to yield a library $B$.
@@ skipping 275 matching lines @@
 does not cause a dynamic error, as there is no need to test against \code{I$<$String$>$} in this case. 
 Similarly, in production mode
 }
 
 \begin{dartCode}
 A x = \NEW{} A$<$String$>$();
 bool b = x is I;
 \end{dartCode}
 
 \commentary{
-\code{b} is bound to true, but in checked mode the second line causes a dynamic type error.
+\code{b} is bound to \TRUE, but in checked mode the second line causes a dynamic type error.
 }
 
 
 
 \subsection{Type Declarations}
 \label{typeDeclarations}
 
 \subsubsection{Typedef}
 \label{typedef}
 
@@ skipping 491 matching lines @@
 \item The names of compile time constant variables never use lower case letters. If they consist of multiple words, those words are separated by underscores. Examples: PI,  I\_AM\_A\_CONSTANT.
 \item The names of functions (including getters, setters, methods and local or library functions) and non-constant variables begin with a lowercase letter. If the name consists of multiple words, each  word (except the first) begins with an uppercase letter.  No other uppercase letters are used. Examples: camlCase, dart4TheWorld
 \item The names of types (including classes and type aliases) begin with an upper case letter.  If the name consists of multiple words, each  word  begins with an uppercase letter.  No other uppercase letters are used. Examples: CamlCase, Dart4TheWorld.
 \item The names of type variables are short (preferably single letter). Examples: T, S, K, V , E.
 \item The names of libraries or library prefixes never use upper case letters. If they consist of multiple words, those words are separated by underscores. Example: my\_favorite\_library.
 \end{itemize}
 }
 
 
 \end{document}