Add support for Async Streams #606

RexJaeschke · 2022-08-08T11:48:25Z

There is some overlap between this PR and PR #672 in 13.14, "The using statement" that will require reconciliation when the second of these two PRs is merged. (PR 606 was spec'd first.)

KalleOlaviNiemitalo · 2022-08-08T14:49:15Z

standard/classes.md

+>
+> *end example*
+
+Consumption of an asynchronous stream requires an `await foreach` to enumerate the elements of the stream. Adding the `await` keyword requires the method that enumerates the asynchronous stream to be declared with the `async` modifier and to return a type allowed for an async method.


"requires" seems too strong; it is certainly possible to enumerate the items of an asynchronous stream by calling IAsyncEnumerator<T>.MoveNextAsync explicitly, without await foreach. I thought perhaps "consumption" is a term that means only foreach loops, but I didn't find the term used with such a meaning anywhere else in this repo.

This feels like an odd paragraph in general. In particular, the "Adding the await keyword" part feels ambiguous - adding it to what? I think we can make that a lot clearer, probably taking language from earlier in 15.15. (The program text for a method can include await without it being asynchronous, due to local functions of course, so some care is required.)

More later, but I think a good way to address this is to look at the statements section, and add a new subclause for "The await foreach" statement, rather than modifying the foreach statement section.

KalleOlaviNiemitalo · 2022-08-08T14:57:22Z

standard/standard-library.md

+IAsyncEnumerator<T> GetAsyncEnumerator(System.Threading.CancellationToken cancellationToken = default);
+```
+
+> However, as we have not mentioned type `System.Threading.CancellationToken` in any other threading contexts in the spec, it has been omitted from the requirements, as if there was no argument expected.


In my opinion, System.Threading.CancellationToken and System.Runtime.CompilerServices.EnumeratorCancellationAttribute should be added to the standard.

If the C# standard defines IAsyncEnumerable<T> with IAsyncEnumerator<T> GetAsyncEnumerator();, and a user-defined class implements IAsyncEnumerable<T> by explicit interface implementation:

using System; using System.Collections.Generic; class Class1 : IAsyncEnumerable<int> { IAsyncEnumerator<int> IAsyncEnumerable<int>.GetAsyncEnumerator() { throw new NotImplementedException(); } }

then Class1 will not be portable between the standard and the .NET implementation, as the method signature will not match.

I agree that we should add this to the standard and make everything match up. We could probably do it in a second PR, if that's easier.

Let’s do it in this PR

standard/standard-library.md

KalleOlaviNiemitalo · 2022-08-08T15:04:45Z

standard/statements.md

@@ -1488,6 +1519,8 @@ While a mutual-exclusion lock is held, code executing in the same execution thre

 ## 12.14 The using statement

+(Almost all of the text in this subclause was written prior to the addition of async streams; the text applies to async streams as well, unless stated otherwise, usually in parenthetic text. Asynchronous stream creation and usage is discussed in §asynchronous-streams.)
+
 The `using` statement obtains one or more resources, executes a statement, and then disposes of the resource.

 ```ANTLR


The using_statement grammar needs to allow await using.

That is in #672

KalleOlaviNiemitalo · 2022-08-08T15:46:43Z

standard/statements.md


 Local variables declared in a *resource_acquisition* are read-only, and shall include an initializer. A compile-time error occurs if the embedded statement attempts to modify these local variables (via assignment or the `++` and `--` operators), take the address of them, or pass them as `ref` or `out` parameters.

-A `using` statement is translated into three parts: acquisition, usage, and disposal. Usage of the resource is implicitly enclosed in a `try` statement that includes a `finally` clause. This `finally` clause disposes of the resource. If a `null` resource is acquired, then no call to `Dispose` is made, and no exception is thrown. If the resource is of type `dynamic` it is dynamically converted through an implicit dynamic conversion ([§10.2.10](conversions.md#10210-implicit-dynamic-conversions)) to `IDisposable` during acquisition in order to ensure that the conversion is successful before the usage and disposal.
+A `using` statement is translated into three parts: acquisition, usage, and disposal. Usage of the resource is implicitly enclosed in a `try` statement that includes a `finally` clause. This `finally` clause disposes of the resource. If a `null` resource is acquired, then no call to `Dispose` (`DisposeAsync` for async streams) is made, and no exception is thrown. If the resource is of type `dynamic` it is dynamically converted through an implicit dynamic conversion ([§10.2.10](conversions.md#10210-implicit-dynamic-conversions)) to `IDisposable` (`IAsyncDisposable` for async streams) during acquisition in order to ensure that the conversion is successful before the usage and disposal.

 A `using` statement of the form


Needs similar lowering rules for await using, particularly that the result of DisposeAsync is awaited rather than discarded.

KalleOlaviNiemitalo · 2022-11-21T08:09:15Z

A comparison that doesn't include so many unrelated changes: draft-v7...RexJaeschke:csharpstandard:async-streams

standard/classes.md

BillWagner · 2023-09-26T16:43:39Z

rebased on the latest draft v8 branch on 09/23/2023

BillWagner

This is close, but I think there are a few updates to make.

standard/classes.md

BillWagner · 2024-05-13T21:56:05Z

standard/statements.md

@@ -1109,25 +1111,25 @@ If the *foreach_statement* contains both or neither `ref` and `readonly`, the it

 The iteration variable corresponds to a local variable with a scope that extends over the embedded statement. During execution of a `foreach` statement, the iteration variable represents the collection element for which an iteration is currently being performed. If the iteration variable denotes a read-only variable, a compile-time error occurs if the embedded statement attempts to modify it (via assignment or the `++` and `--` operators) or pass it as a `ref` or `out` parameter.

-In the following, for brevity, `IEnumerable`, `IEnumerator`, `IEnumerable<T>` and `IEnumerator<T>` refer to the corresponding types in the namespaces `System.Collections` and `System.Collections.Generic`.
+In the following, for brevity, `IEnumerable` and `IEnumerator` refer to the corresponding types in the namespace `System.Collections`, and `IEnumerable<T>`,  `IEnumerator<T>`, and `IAsyncEnumerator<T>` refer to the corresponding types in the namespace `System.Collections.Generic`.


I don't think a non-generic IAsyncEnumerable and IAsyncEnumerator exist. We should re-write this so it doesn't imply that they do.

BillWagner · 2024-05-13T21:57:40Z

standard/statements.md


 The compile-time processing of a `foreach` statement first determines the ***collection type***, ***enumerator type*** and ***iteration type*** of the expression. This determination proceeds as follows:

 - If the type `X` of *expression* is an array type then there is an implicit reference conversion from X to the `IEnumerable` interface (since `System.Array` implements this interface). The collection type is the `IEnumerable` interface, the enumerator type is the `IEnumerator` interface and the iteration type is the element type of the array type `X`.
 - If the type `X` of *expression* is `dynamic` then there is an implicit conversion from *expression* to the `IEnumerable` interface ([§10.2.10](conversions.md#10210-implicit-dynamic-conversions)). The collection type is the `IEnumerable` interface and the enumerator type is the `IEnumerator` interface. If the `var` identifier is given as the *local_variable_type* then the iteration type is `dynamic`, otherwise it is `object`.
 - Otherwise, determine whether the type `X` has an appropriate `GetEnumerator` method:
-  - Perform member lookup on the type `X` with identifier `GetEnumerator` and no type arguments. If the member lookup does not produce a match, or it produces an ambiguity, or produces a match that is not a method group, check for an enumerable interface as described below. It is recommended that a warning be issued if member lookup produces anything except a method group or no match.
+  - Perform member lookup on the type `X` with identifier `GetEnumerator` (`GetAsyncEnumerator` for async streams) and no type arguments. If the member lookup does not produce a match, or it produces an ambiguity, or produces a match that is not a method group, check for an enumerable interface as described below. It is recommended that a warning be issued if member lookup produces anything except a method group or no match.


This paragraph seems to imply a non-generic GetAsyncEnumerator

I don't think so - it's just saying that the GetEnumerator() and GetAsyncEnumerator() methods aren't generic to start (which is correct for both).

BillWagner · 2024-05-13T21:58:37Z

standard/statements.md

  - Member lookup is performed on `E` with the identifier `Current` and no type arguments. If the member lookup produces no match, the result is an error, or the result is anything except a public instance property that permits reading, an error is produced and no further steps are taken.
-  - Member lookup is performed on `E` with the identifier `MoveNext` and no type arguments. If the member lookup produces no match, the result is an error, or the result is anything except a method group, an error is produced and no further steps are taken.
-  - Overload resolution is performed on the method group with an empty argument list. If overload resolution results in no applicable methods, results in an ambiguity, or results in a single best method but that method is either static or not public, or its return type is not `bool`, an error is produced and no further steps are taken.
+  - Member lookup is performed on `E` with the identifier `MoveNext` (`MoveNextAsync` for async streams) and no type arguments. If the member lookup produces no match, the result is an error, or the result is anything except a method group, an error is produced and no further steps are taken.


Again, this shouldn't apply to async streams, because of no non-generic types.

Again, I think it's about the MoveNext and MoveNextAsync methods not being generic.

Co-authored-by: Bill Wagner <[email protected]>

jskeet · 2024-05-09T09:09:33Z

standard/classes.md

@@ -5205,6 +5205,8 @@ For a discussion of the behavior when an exception is thrown from a finalizer, s

 ### 15.14.1 General

+(Almost all of the text in this subclause and its siblings was written prior to the addition of async streams; the text applies to async streams as well, unless stated otherwise, usually in parenthetic text. Asynchronous stream creation and usage is discussed in §asynchronous-streams.)


Is the intention to keep this part? It looks a little odd at the moment. I suspect it should at least be a note instead of just in parentheses.

It does feel a little odd. As an off the cuff suggestion:

swap the order of §15.14 Iterators and §15.15 Async Functions

rename "Iterators” to “Iterators and Async Streams”

rewrite this new intro paragraph to say the clause covers synchronous and async iterators, the latter usually termed async streams.

remove the parentheses and merge the content into the surrounding text

Of course this isn't the only “odd” thing we’ve done, e.g. property & indexer accessors with the “read exchanging terms” instruction.

jskeet · 2024-05-09T09:11:53Z

standard/classes.md

@@ -5213,41 +5215,41 @@ When a function member is implemented using an iterator block, it is a compile-t

 ### 15.14.2 Enumerator interfaces

-The ***enumerator interfaces*** are the non-generic interface `System.Collections.IEnumerator` and all instantiations of the generic interface `System.Collections.Generic.IEnumerator<T>`. For the sake of brevity, in this subclause and its siblings these interfaces are referenced as `IEnumerator` and `IEnumerator<T>`, respectively.
+The ***enumerator interfaces*** are the non-generic interface `System.Collections.IEnumerator` and all instantiations of the generic interface `System.Collections.Generic.IEnumerator<T>` (`System.Collections.Generic.IAsyncEnumerator<T>` for async streams). For the sake of brevity, in this subclause and its siblings these interfaces are referenced as `IEnumerator` and `IEnumerator<T>` (`IAsyncEnumerator<T>` for async streams), respectively.


I'm personally finding this style really hard to read. I'd be happy to try to get this PR into a shape we want, merge it, and then I can create a new PR to change the style - assuming others feel the same way.

jskeet · 2024-05-09T09:12:56Z

standard/classes.md


 #### 15.14.5.4 The Dispose method

-The `Dispose` method is used to clean up the iteration by bringing the enumerator object to the **after** state.
+The `Dispose` (`DisposeAync` for async streams) method is used to clean up the iteration by bringing the enumerator object to the **after** state.


Suggested change

The `Dispose` (`DisposeAync` for async streams) method is used to clean up the iteration by bringing the enumerator object to the **after** state.

The `Dispose` (`DisposeAsync` for async streams) method is used to clean up the iteration by bringing the enumerator object to the **after** state.

standard/classes.md

jskeet · 2024-05-15T09:14:03Z

standard/classes.md

+>
+> *end example*
+
+Consumption of an asynchronous stream requires an `await foreach` to enumerate the elements of the stream. Adding the `await` keyword requires the method that enumerates the asynchronous stream to be declared with the `async` modifier and to return a type allowed for an async method.


This feels like an odd paragraph in general. In particular, the "Adding the await keyword" part feels ambiguous - adding it to what? I think we can make that a lot clearer, probably taking language from earlier in 15.15. (The program text for a method can include await without it being asynchronous, due to local functions of course, so some care is required.)

jskeet · 2024-05-15T09:24:38Z

standard/statements.md


 The compile-time processing of a `foreach` statement first determines the ***collection type***, ***enumerator type*** and ***iteration type*** of the expression. This determination proceeds as follows:

 - If the type `X` of *expression* is an array type then there is an implicit reference conversion from X to the `IEnumerable` interface (since `System.Array` implements this interface). The collection type is the `IEnumerable` interface, the enumerator type is the `IEnumerator` interface and the iteration type is the element type of the array type `X`.
 - If the type `X` of *expression* is `dynamic` then there is an implicit conversion from *expression* to the `IEnumerable` interface ([§10.2.10](conversions.md#10210-implicit-dynamic-conversions)). The collection type is the `IEnumerable` interface and the enumerator type is the `IEnumerator` interface. If the `var` identifier is given as the *local_variable_type* then the iteration type is `dynamic`, otherwise it is `object`.
 - Otherwise, determine whether the type `X` has an appropriate `GetEnumerator` method:
-  - Perform member lookup on the type `X` with identifier `GetEnumerator` and no type arguments. If the member lookup does not produce a match, or it produces an ambiguity, or produces a match that is not a method group, check for an enumerable interface as described below. It is recommended that a warning be issued if member lookup produces anything except a method group or no match.
+  - Perform member lookup on the type `X` with identifier `GetEnumerator` (`GetAsyncEnumerator` for async streams) and no type arguments. If the member lookup does not produce a match, or it produces an ambiguity, or produces a match that is not a method group, check for an enumerable interface as described below. It is recommended that a warning be issued if member lookup produces anything except a method group or no match.


I don't think so - it's just saying that the GetEnumerator() and GetAsyncEnumerator() methods aren't generic to start (which is correct for both).

jskeet · 2024-05-15T09:25:00Z

standard/statements.md

  - Member lookup is performed on `E` with the identifier `Current` and no type arguments. If the member lookup produces no match, the result is an error, or the result is anything except a public instance property that permits reading, an error is produced and no further steps are taken.
-  - Member lookup is performed on `E` with the identifier `MoveNext` and no type arguments. If the member lookup produces no match, the result is an error, or the result is anything except a method group, an error is produced and no further steps are taken.
-  - Overload resolution is performed on the method group with an empty argument list. If overload resolution results in no applicable methods, results in an ambiguity, or results in a single best method but that method is either static or not public, or its return type is not `bool`, an error is produced and no further steps are taken.
+  - Member lookup is performed on `E` with the identifier `MoveNext` (`MoveNextAsync` for async streams) and no type arguments. If the member lookup produces no match, the result is an error, or the result is anything except a method group, an error is produced and no further steps are taken.


Again, I think it's about the MoveNext and MoveNextAsync methods not being generic.

jskeet · 2024-05-15T09:26:55Z

standard/statements.md

-  - Member lookup is performed on `E` with the identifier `MoveNext` and no type arguments. If the member lookup produces no match, the result is an error, or the result is anything except a method group, an error is produced and no further steps are taken.
-  - Overload resolution is performed on the method group with an empty argument list. If overload resolution results in no applicable methods, results in an ambiguity, or results in a single best method but that method is either static or not public, or its return type is not `bool`, an error is produced and no further steps are taken.
+  - Member lookup is performed on `E` with the identifier `MoveNext` (`MoveNextAsync` for async streams) and no type arguments. If the member lookup produces no match, the result is an error, or the result is anything except a method group, an error is produced and no further steps are taken.
+  - Overload resolution is performed on the method group with an empty argument list. If overload resolution results in no applicable methods, results in an ambiguity, or results in a single best method but that method is either static or not public, or its return type is not `bool`, an error is produced, and no further steps are taken.


The return type of MoveNextAsync is ValueTask<bool> rather than bool.

jskeet · 2024-05-15T09:29:42Z

standard/statements.md

@@ -1309,6 +1311,33 @@ The order in which `foreach` traverses the elements of an array, is as follows:
 >  
 > *end example*

+An async enumerator may optionally expose a `DisposeAsync` method that may be invoked with no arguments and that returns something that can be `await`ed and whose `GetResult()` returns `void`.


I suspect there's a cleaner way of expressing this via task types, e.g. "with a return type that is a non-generic task type".

jskeet · 2024-05-15T09:30:11Z

standard/statements.md

@@ -1797,6 +1826,8 @@ While a mutual-exclusion lock is held, code executing in the same execution thre

 ## 13.14 The using statement

+(Almost all of the text in this subclause was written prior to the addition of async streams; the text applies to async streams as well, unless stated otherwise, usually in parenthetic text. Asynchronous stream creation and usage is discussed in §asynchronous-streams.)


And another bit to remove

Nigel-Ecma

Like @jskeet I think this needs some reorg/rewriting to cover synchronous and asynchronous iterators more uniformly. Also need to address the omissions reported by @KalleOlaviNiemitalo .

Nigel-Ecma · 2024-05-15T18:00:13Z

standard/classes.md

@@ -5205,6 +5205,8 @@ For a discussion of the behavior when an exception is thrown from a finalizer, s

 ### 15.14.1 General

+(Almost all of the text in this subclause and its siblings was written prior to the addition of async streams; the text applies to async streams as well, unless stated otherwise, usually in parenthetic text. Asynchronous stream creation and usage is discussed in §asynchronous-streams.)


It does feel a little odd. As an off the cuff suggestion:

swap the order of §15.14 Iterators and §15.15 Async Functions

rename "Iterators” to “Iterators and Async Streams”

rewrite this new intro paragraph to say the clause covers synchronous and async iterators, the latter usually termed async streams.

remove the parentheses and merge the content into the surrounding text

Of course this isn't the only “odd” thing we’ve done, e.g. property & indexer accessors with the “read exchanging terms” instruction.

Nigel-Ecma · 2024-05-15T18:05:20Z

standard/classes.md

@@ -5213,41 +5215,41 @@ When a function member is implemented using an iterator block, it is a compile-t

 ### 15.14.2 Enumerator interfaces

-The ***enumerator interfaces*** are the non-generic interface `System.Collections.IEnumerator` and all instantiations of the generic interface `System.Collections.Generic.IEnumerator<T>`. For the sake of brevity, in this subclause and its siblings these interfaces are referenced as `IEnumerator` and `IEnumerator<T>`, respectively.
+The ***enumerator interfaces*** are the non-generic interface `System.Collections.IEnumerator` and all instantiations of the generic interface `System.Collections.Generic.IEnumerator<T>` (`System.Collections.Generic.IAsyncEnumerator<T>` for async streams). For the sake of brevity, in this subclause and its siblings these interfaces are referenced as `IEnumerator` and `IEnumerator<T>` (`IAsyncEnumerator<T>` for async streams), respectively.


As an example of what my opening off the cuff suggestion would produce this para would become:

Suggested change

The ***enumerator interfaces*** are the non-generic interface `System.Collections.IEnumerator` and all instantiations of the generic interface `System.Collections.Generic.IEnumerator<T>` (`System.Collections.Generic.IAsyncEnumerator<T>` for async streams). For the sake of brevity, in this subclause and its siblings these interfaces are referenced as `IEnumerator` and `IEnumerator<T>` (`IAsyncEnumerator<T>` for async streams), respectively.

The ***enumerator interfaces*** are the non-generic interface `System.Collections.IEnumerator` and all instantiations of the generic interfaces `System.Collections.Generic.IEnumerator<T>` and `System.Collections.Generic.IAsyncEnumerator<T>`. For the sake of brevity, in this subclause and its siblings these interfaces are referenced as `IEnumerator`, `IEnumerator<T>` and `IAsyncEnumerator<T>` respectively.

Nigel-Ecma · 2024-05-15T18:16:57Z

standard/classes.md

@@ -5213,41 +5215,41 @@ When a function member is implemented using an iterator block, it is a compile-t

 ### 15.14.2 Enumerator interfaces

-The ***enumerator interfaces*** are the non-generic interface `System.Collections.IEnumerator` and all instantiations of the generic interface `System.Collections.Generic.IEnumerator<T>`. For the sake of brevity, in this subclause and its siblings these interfaces are referenced as `IEnumerator` and `IEnumerator<T>`, respectively.
+The ***enumerator interfaces*** are the non-generic interface `System.Collections.IEnumerator` and all instantiations of the generic interface `System.Collections.Generic.IEnumerator<T>` (`System.Collections.Generic.IAsyncEnumerator<T>` for async streams). For the sake of brevity, in this subclause and its siblings these interfaces are referenced as `IEnumerator` and `IEnumerator<T>` (`IAsyncEnumerator<T>` for async streams), respectively.


I think changing the name is a non-starter (flashbacks to NNRT here ;-)) and there is some convention in using the term “stream”. If my first suggestion above is followed the stream/async iterator stuff could be covered in §asynchronous-streams which will occur before the §15.15 Iterators and Async Streams clause.

Nigel-Ecma · 2024-05-15T18:23:24Z

standard/classes.md

+
+### §asynchronous-streams Asynchronous stream creation and usage
+
+A stream can be created and consumed asynchronously.


The definition of “stream” needs to be added here, elsewhere in the Standard we have streams of Unicode characters and tokens, uses of StreamReader etc.

See previous comments for how this might be done; it may even be decided to move this section into the (now following) §15.15 Iterators and Async Streams clause.

Nigel-Ecma · 2024-05-15T18:26:41Z

standard/standard-library.md

+IAsyncEnumerator<T> GetAsyncEnumerator(System.Threading.CancellationToken cancellationToken = default);
+```
+
+> However, as we have not mentioned type `System.Threading.CancellationToken` in any other threading contexts in the spec, it has been omitted from the requirements, as if there was no argument expected.


Let’s do it in this PR

jskeet · 2024-05-15T21:30:51Z

standard/classes.md

@@ -5416,3 +5418,52 @@ When the body of the async function terminates, the return task is moved out of
 If the return type of the async function is `void`, evaluation differs from the above in the following way: Because no task is returned, the function instead communicates completion and exceptions to the current thread’s ***synchronization context***. The exact definition of synchronization context is implementation-dependent, but is a representation of “where” the current thread is running. The synchronization context is notified when evaluation of a `void`-returning async function commences, completes successfully, or causes an uncaught exception to be thrown.

 This allows the context to keep track of how many `void`-returning async functions are running under it, and to decide how to propagate exceptions coming out of them.
+
+### §asynchronous-streams Asynchronous stream creation and usage


Do we need this section at all? (Really not needed in normative text?)

(All of the bits in the bullet points can be included in the iterator section.)

jskeet · 2024-05-15T21:34:08Z

standard/classes.md

+A method that creates an asynchronous stream has the following characteristics:
+
+- It's declared with the `async` modifier.
+- It returns an `IAsyncEnumerable<T>`.


Or IAsyncEnumerator<T>.

jskeet · 2024-05-15T21:39:17Z

Summary of discussions:

Try to reword to avoid the brackets
Avoid using "stream" in normative text, but have a note
Merge the "Asynchronous stream creation and usage" into the iterator section
Reorder async and iterators so that async comes first
Defer the CancellationToken support until after we've got the structure right (but as a fast-follow - definitely in C# 8)

jskeet · 2024-11-20T11:16:15Z

It looks like there's still quite a bit to do here - but it's not clear to me that Rex is the right person to do this.

For discussion at today's call (if there's time): who should take this on? (I may have time, if we decide I'm the most appropriate person bearing in mind other PRs...)

BillWagner · 2025-01-13T16:42:32Z

standard/classes.md

@@ -5213,41 +5215,41 @@ When a function member is implemented using an iterator block, it is a compile-t

 ### 15.14.2 Enumerator interfaces

-The ***enumerator interfaces*** are the non-generic interface `System.Collections.IEnumerator` and all instantiations of the generic interface `System.Collections.Generic.IEnumerator<T>`. For the sake of brevity, in this subclause and its siblings these interfaces are referenced as `IEnumerator` and `IEnumerator<T>`, respectively.
+The ***enumerator interfaces*** are the non-generic interface `System.Collections.IEnumerator` and all instantiations of the generic interface `System.Collections.Generic.IEnumerator<T>` (`System.Collections.Generic.IAsyncEnumerator<T>` for async streams). For the sake of brevity, in this subclause and its siblings these interfaces are referenced as `IEnumerator` and `IEnumerator<T>` (`IAsyncEnumerator<T>` for async streams), respectively.


I also think we should continue to use the term "async stream". It fits well with the feature, and "stream" is the conventional term.

I also like the idea of some reordering. That may be a follow-up PR?

BillWagner · 2025-01-13T17:33:46Z

standard/classes.md

+
+- It's declared with the `async` modifier.
+- It returns an `IAsyncEnumerable<T>`.
+- It contains a `yield return` statement to return successive elements in the asynchronous stream.


We need to add that the argument to yield return must be implicitly convertible to the type argument for the return.

If we don't combine this section with the enumerator section, we should add that yield break is can be used.

BillWagner · 2025-01-13T17:47:53Z

standard/classes.md

+>
+> *end example*
+
+Consumption of an asynchronous stream requires an `await foreach` to enumerate the elements of the stream. Adding the `await` keyword requires the method that enumerates the asynchronous stream to be declared with the `async` modifier and to return a type allowed for an async method.


More later, but I think a good way to address this is to look at the statements section, and add a new subclause for "The await foreach" statement, rather than modifying the foreach statement section.

BillWagner · 2025-01-13T17:50:56Z

standard/classes.md

+>
+> *end example*
+
+A method can both consume and produce an asynchronous stream.


I don't think it's needed.

BillWagner · 2025-01-13T18:05:49Z

standard/statements.md

@@ -1094,12 +1094,14 @@ The end point of a `for` statement is reachable if at least one of the following

 ### 13.9.5 The foreach statement

+(Almost all of the text in this subclause was written prior to the addition of async streams; the text applies to async streams as well, unless stated otherwise, usually in parenthetic text. Asynchronous stream creation and usage is discussed in §asynchronous-streams.)


I'd make this two sub-clauses: One for "foreach", and one for "await foreach".

The grammar is similar, and I'll defer to Nigel on if one or two grammar productions makes more sense.

The section on "MoveNext" and "MoveNextAsync" becomes more clear as two distinct sections: One for a synchronous "move next" and one for an asynchronous value-task based "move next asynchronously"

BillWagner · 2025-01-13T18:15:51Z

standard/statements.md

@@ -1488,6 +1519,8 @@ While a mutual-exclusion lock is held, code executing in the same execution thre

 ## 12.14 The using statement

+(Almost all of the text in this subclause was written prior to the addition of async streams; the text applies to async streams as well, unless stated otherwise, usually in parenthetic text. Asynchronous stream creation and usage is discussed in §asynchronous-streams.)
+
 The `using` statement obtains one or more resources, executes a statement, and then disposes of the resource.

 ```ANTLR


That is in #672

RexJaeschke added this to the C# 8.0 milestone Aug 8, 2022

RexJaeschke marked this pull request as draft August 8, 2022 11:48

KalleOlaviNiemitalo reviewed Aug 8, 2022

View reviewed changes

BillWagner force-pushed the async-streams branch from 68c9e97 to 1f7e2b1 Compare November 21, 2022 15:46

RexJaeschke mentioned this pull request Nov 24, 2022

Add support for using declarations and async using #672

Open

BillWagner force-pushed the async-streams branch from 4f572a3 to 6bd175d Compare February 6, 2023 13:28

KalleOlaviNiemitalo reviewed Jun 29, 2023

View reviewed changes

standard/classes.md Outdated Show resolved Hide resolved

KalleOlaviNiemitalo mentioned this pull request Jun 29, 2023

Not clear when the return task of an async function is set to a cancelled state #775

Closed

KalleOlaviNiemitalo mentioned this pull request Jul 12, 2023

C# 7.x 15.15.1 standard library task types #844

Closed

RexJaeschke added the type: feature This issue describes a new feature label Jul 22, 2023

RexJaeschke added 6 commits September 26, 2023 12:23

add support for async streams

f4689c6

add support for async streams

5fa2054

add support for async streams

c889f5c

add example annotation

a1d3d6c

Create Support1AsyncStreams.cs

250f15d

Create Support2AsyncStreams.cs

5b5d590

BillWagner force-pushed the async-streams branch from 4b81f71 to 5b5d590 Compare September 26, 2023 16:39

MadsTorgersen self-assigned this Oct 4, 2023

RexJaeschke added the Review: pending Proposal is available for review label Oct 13, 2023

RexJaeschke marked this pull request as ready for review January 11, 2024 13:46

jskeet added the meeting: discuss This issue should be discussed at the next TC49-TG2 meeting label Apr 30, 2024

BillWagner self-assigned this Apr 30, 2024

BillWagner added the reQUEST label Apr 30, 2024

sequestor bot added seQUESTered and removed reQUEST labels May 1, 2024

BillWagner reviewed May 13, 2024

View reviewed changes

Update standard/classes.md

fe01c0d

Co-authored-by: Bill Wagner <[email protected]>

jskeet reviewed May 15, 2024

View reviewed changes

Nigel-Ecma requested changes May 15, 2024

View reviewed changes

jskeet reviewed May 15, 2024

View reviewed changes

BillWagner removed the seQUESTered label Aug 16, 2024

jskeet removed the meeting: discuss This issue should be discussed at the next TC49-TG2 meeting label Dec 11, 2024

BillWagner reviewed Jan 13, 2025

View reviewed changes

RexJaeschke added 2 commits February 4, 2025 12:39

Merge branch 'draft-v8' into async-streams

1354a0e

Add new types to C.5

23e4ec5

		@@ -5205,6 +5205,8 @@ For a discussion of the behavior when an exception is thrown from a finalizer, s

		### 15.14.1 General

		(Almost all of the text in this subclause and its siblings was written prior to the addition of async streams; the text applies to async streams as well, unless stated otherwise, usually in parenthetic text. Asynchronous stream creation and usage is discussed in §asynchronous-streams.)

	The `Dispose` (`DisposeAync` for async streams) method is used to clean up the iteration by bringing the enumerator object to the after state.
	The `Dispose` (`DisposeAsync` for async streams) method is used to clean up the iteration by bringing the enumerator object to the after state.

		@@ -1797,6 +1826,8 @@ While a mutual-exclusion lock is held, code executing in the same execution thre

		## 13.14 The using statement

		(Almost all of the text in this subclause was written prior to the addition of async streams; the text applies to async streams as well, unless stated otherwise, usually in parenthetic text. Asynchronous stream creation and usage is discussed in §asynchronous-streams.)


		### §asynchronous-streams Asynchronous stream creation and usage

		A stream can be created and consumed asynchronously.

		@@ -1094,12 +1094,14 @@ The end point of a `for` statement is reachable if at least one of the following

		### 13.9.5 The foreach statement

		(Almost all of the text in this subclause was written prior to the addition of async streams; the text applies to async streams as well, unless stated otherwise, usually in parenthetic text. Asynchronous stream creation and usage is discussed in §asynchronous-streams.)

Add support for Async Streams #606

Are you sure you want to change the base?

Add support for Async Streams #606

Conversation

RexJaeschke commented Aug 8, 2022 • edited by BillWagner Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

KalleOlaviNiemitalo commented Nov 21, 2022

BillWagner commented Sep 26, 2023

BillWagner left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Nigel-Ecma left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jskeet commented May 15, 2024

jskeet commented Nov 20, 2024

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

RexJaeschke commented Aug 8, 2022 •

edited by BillWagner

Loading