Revise with feedback from John and Andy

Author: jckarter

docs/SIL.rst

@@ -631,98 +631,80 @@ autorelease in the callee.
   type behaves like a non-generic type, as if the substitutions were
   actually applied to the underlying function type.
 
+Async Functions
+```````````````
+
+SIL function types may be ``@async``. ``@async`` functions run inside async
+tasks, and can have explicit *suspend points* where they suspend execution.
+``@async`` functions can only be called from other ``@async`` functions, but
+otherwise can be invoked with the normal ``apply`` and ``try_apply``
+instructions (or ``begin_apply`` if they are coroutines).
+
+``@async`` functions may express primitive suspend points by using the
+``begin_async_continuation[_addr]`` and ``await_async_continuation``
+instructions. ``begin_async_continuation[_addr]`` creates a *continuation*
+value that can be used to resume the coroutine when it suspends, feeding a
+value back into the currently-running function or causing it to fail with an
+error when it resumes. The resulting continuation value can then be passed
+into a completion handler, registered with an event loop, or scheduled by
+some other mechanism. The ``await_async_continuation`` instruction suspends
+execution of the coroutine until the continuation is invoked to resume it.
+All continuation values must be used to resume the async coroutine exactly
+once. It is undefined behavior to attempt to resume the same continuation
+more than once. Failing to resume a continuation will leave the coroutine
+stuck in the suspended state, leaking any memory or other resources it owns.
+
 Coroutine Types
 ```````````````
 
 A coroutine is a function which can suspend itself and return control to
 its caller without terminating the function.  That is, it does not need to
-obey a strict stack discipline. Different kinds of coroutines in SIL have
-different representations, reflecting the different capabilities and
-structural constraints of different language-level features:
-
-Yielding Coroutines
-...................
-
-Some kinds of coroutine have control flow that is tightly integrated with
-their callers, and pass information back and forth between caller and callee
-in a structured way. *Generalized accessors* and generators in Swift fit this
-description: a ``read`` or ``modify`` accessor coroutine projects a single
-value, yields ownership of that one value temporarily to the caller, and then
-takes ownership back when resumed, allowing the coroutine to clean up resources
-or otherwise react to mutations done by the caller. *Generators* similarly
-yield a stream of values one at a time to their caller, temporarily yielding
-ownership of each value in turn to the caller. The tight coupling of the
-caller's control flow with these coroutines allows the caller to *borrow*
-values produced by the coroutine, where a normal function return would need to
-transfer ownership of its return value, since a normal function's context
-ceases to exist and be able to maintain ownership of the value after it
-returns.
-
-To support these concepts, SIL supports two kinds of *yielding coroutine*:
+obey a strict stack discipline. SIL coroutines have control flow that is
+tightly integrated with their callers, and they pass information back and forth
+between caller and callee in a structured way through yield points.
+*Generalized accessors* and *generators* in Swift fit this description: a
+``read`` or ``modify`` accessor coroutine projects a single value, yields
+ownership of that one value temporarily to the caller, and then takes ownership
+back when resumed, allowing the coroutine to clean up resources or otherwise
+react to mutations done by the caller. *Generators* similarly yield a stream of
+values one at a time to their caller, temporarily yielding ownership of each
+value in turn to the caller. The tight coupling of the caller's control flow
+with these coroutines allows the caller to *borrow* values produced by the
+coroutine, where a normal function return would need to transfer ownership of
+its return value, since a normal function's context ceases to exist and be able
+to maintain ownership of the value after it returns.
+
+To support these concepts, SIL supports two kinds of coroutine:
 ``@yield_many`` and ``@yield_once``. Either of these attributes may be
-written before a function type to indicate that it is a yielding coroutine type.
+written before a function type to indicate that it is a coroutine type.
+``@yield_many`` and ``@yield_once`` coroutines are allowed to also be
+``@async``. (Note that ``@async`` functions are not themselves modeled
+explicitly as coroutines in SIL, although the implementation may use a coroutine
+lowering strategy.)
 
-A yielding coroutine type may declare any number of *yielded values*, which is to
+A coroutine type may declare any number of *yielded values*, which is to
 say, values which are provided to the caller at a yield point.  Yielded
 values are written in the result list of a function type, prefixed by
 the ``@yields`` attribute.  A yielded value may have a convention attribute,
 taken from the set of parameter attributes and interpreted as if the yield
 site were calling back to the calling function.
 
-Currently, a yielding coroutine may not have normal results.
+Currently, a coroutine may not have normal results.
 
-Yielding coroutine functions may be used in many of the same ways as normal
+Coroutine functions may be used in many of the same ways as normal
 function values.  However, they cannot be called with the standard
 ``apply`` or ``try_apply`` instructions.  A non-throwing yield-once
 coroutine can be called with the ``begin_apply`` instruction.  There
 is no support yet for calling a throwing yield-once coroutine or for
 calling a yield-many coroutine of any kind.
 
-Yielding coroutines may contain the special ``yield`` and ``unwind``
+Coroutines may contain the special ``yield`` and ``unwind``
 instructions.
 
 A ``@yield_many`` coroutine may yield as many times as it desires.
 A ``@yield_once`` coroutine may yield exactly once before returning,
 although it may also ``throw`` before reaching that point.
 
-Async Coroutines
-................
-
-``async`` coroutines are quite different from yielding coroutines.
-Async coroutines are almost like threads in that they
-have largely independent execution contexts, and do not generally directly
-transfer values between each other without going through synchronization
-abstractions. Unlike ``@yield_once`` or ``@yield_many`` coroutine functions, an
-individual async function does not represent an entire coroutine unto itself,
-but is an individual unit of code that may run inside an async coroutine.
-Unlike preemptive threads, async functions have explicit *suspend points* where
-they allow their coroutine's execution to be suspended so that a different
-coroutine may run.
-
-In SIL, a function type has the ``@async`` attribute to
-indicate it may contain suspend points. Being ``@async`` is orthogonal to being
-a yielding coroutine--the ``@async`` attribute can be applied
-both to functions and to both kinds of yielding coroutine. ``@async`` functions
-can only be called from other ``@async`` functions, but otherwise can be
-invoked with the normal ``apply`` and ``try_apply`` instructions (or
-``begin_apply`` if they are yielding coroutines). An ``@async`` function may
-only use the special ``yield`` and ``unwind`` instructions if it is 
-a yielding coroutine in addition to being async.
-
-``@async`` functions may
-express primitive suspend points by using the ``begin_async_continuation[_addr]`` and
-``await_async_continuation`` instructions. ``begin_async_continuation[_addr]``
-creates a *continuation* value that can be used to resume the coroutine when it
-suspends, feeding a value back into the currently-running function or causing
-it to fail with an error when it resumes. The resulting continuation value can
-then be passed into a completion handler, registered with an event loop, or
-scheduled by some other mechanism. The ``await_continuation`` instruction
-suspends execution of the coroutine until the continuation is invoked to resume
-it.  All continuation values must be used to resume the async coroutine exactly
-once. It is undefined behavior to attempt to resume the same continuation more
-than once. Failing to resume a continuation will leave the coroutine stuck in
-the suspended state, leaking any memory or other resources it owns.
-
 Properties of Types
 ```````````````````
 
@@ -5992,7 +5974,7 @@ yield
   sil-yield-values ::= '(' (sil-operand (',' sil-operand)*)? ')'
 
 Temporarily suspends the current function and provides the given
-values to the calling function. The current function must be a yielding coroutine,
+values to the calling function. The current function must be a coroutine,
 and the yield values must match the yield types of the coroutine.
 If the calling function resumes the coroutine normally, control passes to
 the ``resume`` destination. If the calling function aborts the coroutine,
@@ -6020,7 +6002,7 @@ unwind
 
 Exits the current function and returns control to the calling function,
 completing an unwind from a ``yield``. The current function must be a
-yielding coroutine.
+coroutine.
 
 ``unwind`` is only permitted in blocks reachable from the ``unwind`` edges
 of ``yield`` instructions.
@@ -6367,7 +6349,7 @@ await_async_continuation
   bb1(%1 : $T):
   bb2(%2 : $Error):
 
-Suspends execution of an ``@async`` function until the continuation operation
+Suspends execution of an ``@async`` function until the continuation
 is resumed. The continuation must be the result of a
 ``begin_async_continuation`` or ``begin_async_continuation_addr``
 instruction within the same function; see the documentation for
@@ -6378,27 +6360,28 @@ instruction must always have a ``resume`` successor, but must have an
 ``error`` successor if and only if the operand is an
 ``UnsafeThrowingContinuation<T>``.
 
-If the operand is the result of a
-``begin_async_continuation`` instruction, then the ``resume`` successor block
-must take an argument whose type is the maximally-abstracted lowered type
-of ``T``, matching the type argument of the ``Unsafe[Throwing]Continuation<T>``
-operand. The value of the ``resume`` argument is owned by the current
-function. If the operand is the result of a ``begin_async_continuation_addr``
-instruction, then the ``resume`` successor block must *not* take an argument;
-the resume value will be written to the memory referenced by the operand to the
-``begin_async_continuation_addr`` instruction, after which point the value in
-that memory becomes owned by the current function. With either variant,
-if the ``await_async_continuation`` instruction has an ``error`` successor block,
-the ``error`` block must take a single ``Error`` argument, and that argument
-is owned by the enclosing function. The memory referenced by a
-``begin_async_continuation_addr`` instruction remains uninitialized when
-``await_async_continuation`` resumes on the ``error`` successor.
-
-It is possible for a continuation to be resumed before ``await_async_continuation``.
-In this case, the resume operation returns immediately, and
-``await_async_continuation`` immediately transfers control to its ``resume``
-or ``error`` successor block, with the resume or error value that the
-continuation was resumed with.
+If the operand is the result of a ``begin_async_continuation`` instruction,
+then the ``resume`` successor block must take an argument whose type is the
+maximally-abstracted lowered type of ``T``, matching the type argument of the
+``Unsafe[Throwing]Continuation<T>`` operand. The value of the ``resume``
+argument is owned by the current function. If the operand is the result of a
+``begin_async_continuation_addr`` instruction, then the ``resume`` successor
+block must *not* take an argument; the resume value will be written to the
+memory referenced by the operand to the ``begin_async_continuation_addr``
+instruction, after which point the value in that memory becomes owned by the
+current function. With either variant, if the ``await_async_continuation``
+instruction has an ``error`` successor block, the ``error`` block must take a
+single ``Error`` argument, and that argument is owned by the enclosing
+function. The memory referenced by a ``begin_async_continuation_addr``
+instruction remains uninitialized when ``await_async_continuation`` resumes on
+the ``error`` successor.
+
+It is possible for a continuation to be resumed before
+``await_async_continuation``.  In this case, the resume operation returns
+immediately to its caller. When the ``await_async_continuation`` instruction
+later executes, it then immediately transfers control to
+its ``resume`` or ``error`` successor block, using the resume or error value
+that the continuation was already resumed with.
 
 Differentiable Programming
 ~~~~~~~~~~~~~~~~~~~~~~~~~~