PR for blog post on async-iterators #1

jcouv · 2019-01-02T21:24:00Z

No description provided.

stephentoub · 2019-01-07T01:43:52Z

async-iterator.md

+## Consumption with `await foreach`
+
+The `await foreach` statement offers the most straightforward way of enumerating an async-enumerable's items.
+It is very similar to `foreach` for enumerables. The main difference is that `await foreach` awaits each item (and also disposal).


awaits each item => awaits the retrieval of each item?

stephentoub · 2019-01-07T01:46:06Z

async-iterator.md

+As the code continues to execute in the background:
+- if it reaches a `yield return`, the background execution completes and the task we've previously handed to the caller is fulfilled with `true`,
+- if it reaches the end of the method, that task is fulfilled with `false`,
+- if it reaches an `await`, execution continues in the background.


This last bullet isn't really necessary. From the caller's perspective, this isn't visible, separate from the lifecycle of the ValueTask<bool> that's returned to them.

stephentoub · 2019-01-07T01:47:28Z

async-iterator.md

+
+That task is complete (rather than pending). When the caller tries to access its result the task will throw the exception it holds.
+
+When background execution is moving the method forward and an exception is thrown without handling, the exception is similarly caught and passed onto the caller via the task.


In any case, exceptions that go unhandled in the method are caught and stored onto the task returned from MoveNextAsync.

stephentoub · 2019-01-07T01:48:08Z

async-iterator.md

+When background execution is moving the method forward and an exception is thrown without handling, the exception is similarly caught and passed onto the caller via the task.
+
+
+### Parallels with iterator and async control flow (optional)


Nit: maybe avoid the word "parallel", as it has a meaning very related to concurrency, which is applicable to this discussion, and it might confuse readers.

Suggestion: "Relationship between iterator and async control flow"

Or "Comparison"

stephentoub · 2019-01-07T01:48:52Z

async-iterator.md

+
+The execution of iterator methods shifts the control between the caller and the method:
+- the caller repeatedly calls `MoveNext()` (which executes the method),
+- the method yields control back to the caller (when reaching a `yield return`).


"when reaching a yield return"... or the end of the method, or a yield break, or an unhandled exception

I found this a more comfortable explanation of what is happening than the earlier discussion of "continues in background"

stephentoub · 2019-01-07T01:49:57Z

async-iterator.md

+
+The execution of async methods starts by the caller giving control to the method and background execution.
+From there on, the control shifts between the method and background execution:
+- the background execution resumes the method after a long-running task completes,


"long-running task"... "LongRunning" is a specific concept in the Task APIs, so I'd avoid using that term here. Background execution resumes the method after an awaited task completes asynchronously.

stephentoub · 2019-01-07T01:51:17Z

async-iterator.md

+From there on, the control shifts between the method and background execution:
+- the background execution resumes the method after a long-running task completes,
+- the method yields control back to the background execution (when reaching an `await`).
+Only when the method completes with a `return` is the control fully returned to the caller.


What does this mean? Control is returned for yield returns, etc... do you just mean there's still additional work to be done if the caller calls back into the iterator? While they should do so, they're fully in control of whether they do so.

also, this does'nt seem true given exceptions. and, while pedantic, i'd like these docs to be accurate and to cover cancellation/exceptions as well as i view both are so core to the async/task world. Thanks!

Also, await only yields control to the caller when the task is still pending. It does not yield control if the awaited task completes synchronously.

stephentoub · 2019-01-07T01:57:30Z

async-iterator.md

+
+#### Locals
+
+Although I won't go into much details on this, it is worth mentioning that all the local variables in the method are converted to fields on a compiler-generated type, so they maintain their values across suspensions/resumptions.


"all the local variables in the method are converted to fields"... all? Do we not optimize this to avoid lifting locals that don't need to be?

Indeed, only locals that are used across suspensions get hoisted to a field. Thanks

stephentoub · 2019-01-07T02:08:49Z

async-iterator.md

+```
+
+This relies on locals (instead of the stack) to store the two results.
+So when we rewrite async or async-iterator methods, we can assume that all awaits have been spilled.


But temp2 in this example doesn't actually need to be lifted to the state machine, right? It should be able to remain a local. In fact, it shouldn't need a local, either, should it? The awaiter will need to be stored in the state machine, but temp2 is just the result of calling GetResult on the awaiter, and that can be on the stack to be passed directly to Method1.

In M1(M2(), await expr); the result of M2() needs to be saved and restored during the await suspension. (example)

But in M1(await expr, M2()) there is no need for that. We just put the result of the await on the stack, the result of M2() on the stack, then invoke M1. (example)

async-iterator.md

CyrusNajmabadi · 2019-01-07T02:45:26Z

async-iterator.md

+This returns a `ValueTask<bool>` where the `bool` represents the presence or absence of an item.
+When you call `MoveNextAsync()`:
+- if the code reaches a `yield return` statement, you immediately get a `true`,
+- if the code reaches the end of the method, you immediately get a `false`,


what about yield break?

CyrusNajmabadi · 2019-01-07T02:46:49Z

async-iterator.md

+When you call `MoveNextAsync()`:
+- if the code reaches a `yield return` statement, you immediately get a `true`,
+- if the code reaches the end of the method, you immediately get a `false`,
+- if you reach an `await`, you get a pending task and the code continues to execute in the background.


what about exceptions? would also like to know how exceptions work before/after the first yield and first await.

@BillWagner Is this "continues to execute in the background" consistent with the way we talk about await elsewhere?

We try to avoid the term "execute in the background" for async tasks. As others have said, many readers conflate "parallel" with "async".

CyrusNajmabadi · 2019-01-07T02:49:29Z

async-iterator.md

+Only when the method completes with a `return` is the control fully returned to the caller.
+
+The execution of async-iterator methods mixes both of those patterns, with the control shifting between caller (repeatedly calls `MoveNextAsync()`), method (gives control to the caller when reaching a `yield return` and to the background execution when reaching an `await`) and background execution (resumes the method after an `await`).
+


note: if it gets very redundant to keep on having to mention yield break or exception info, it would be fine with me if there was a preliminary paragraph mentioning that these are important, but will be elided for brevity in the following paragraphs, but will then have dedicated info explaining them later.

CyrusNajmabadi · 2019-01-07T02:51:00Z

async-iterator.md

+    {
+        /* set state to N */
+        /* save awaiter temp */
+        /* kick off background execution */


i wouldn't mind explanations of these. if those explanations come later, can the comment mention that fact? For me, i like having the pseudo-code, knowing that each bit will be expanded on more fully. Thanks!

CyrusNajmabadi · 2019-01-07T02:52:03Z

async-iterator.md

+... code after `await expr` ...
+```
+
+Note this is the same pattern used to lower awaits in async methods.


i would mention this before the pseudo-code. effectively "we do the same as normal async methods, but for expository purposes, we'll show what we do for both".

CyrusNajmabadi · 2019-01-07T02:53:23Z

async-iterator.md

+        /* set state to N */
+        /* save awaiter temp */
+        /* kick off background execution */
+        return;


this confuses me a bit. if the sig of the method is that it gives back a Task, then clearly this 'return' isn't following that. So, presumably this is in some other method that relates more to the control flow logic to eventually move the original task back to the completed/faulted state.

CyrusNajmabadi · 2019-01-07T02:54:34Z

async-iterator.md

+When either the caller or background execution need to move the method forward, execution will resume from the right label because the state variable was set to `N` and the dispatching logic will jump to that label.
+
+Because there is a cost to starting background execution, suspending and resuming, the lowering pattern is optimized: if the task was already completed, we avoid that overhead and instead just move ahead with the result.
+


it might be useful to show the pseudocode for that.

CyrusNajmabadi · 2019-01-07T02:56:09Z

async-iterator.md

+        return;
+
+        resumeLabelN:
+        /* reset state */


what does it mean to 'reset state', and why is it necessary? why can't the value of state just be 'N' until the next time we need to suspend, at which point we give it the new value?

This just means state = -1; . I agree it's not super useful, but it's something we do for iterator and async methods. It indicates "running" state.
I spelled out the state diagram here.

As far as I can tell this "RunningState" state value is currently only used to throw an exception when calling DisposeAsync() when the method is already running.

CyrusNajmabadi · 2019-01-07T02:56:51Z

async-iterator.md

+
+        resumeLabelN:
+        /* reset state */
+        /* restore awaiter temp */


what does thsi mean?

Whenever there is a suspension (return in lowered code) we must save all locals so they can be restored when coming back. In this case awaiterTemp.

CyrusNajmabadi · 2019-01-07T02:57:39Z

async-iterator.md

+- the `state` value,
+- persisting `awaiterTemp`,
+- the `current` value, (see section on "yield return" suspension)
+- the machinery for background execution and continuation.


if these will get sections explaining them, consider having links here to those sections. this feedback applies to this entire doc.

stopping now. it's too late for my brain to take on hte more complex stuff :)

BillWagner

I'm about half way through this, and it's really detailed.

I left a few suggestions. I'll read more later and add any more suggestions.

BillWagner · 2019-01-07T16:20:41Z

async-iterator.md

+| `IAsyncEnumerator<T>` used with `await MoveNextAsync()` and `Current` | `IEnumerator<T>` used with `MoveNext()` and `Current` |
+| `IAsyncDisposable` used with `await DisposeAsync()` | `IDisposable` used with `Dispose()` |
+
+So it is unsurprising that the lowering for `await foreach` is very similar to that of a `foreach`.


suggestion: instead of "lowering for" use "code generated from"

BillWagner · 2019-01-07T16:20:47Z

async-iterator.md

+The `await foreach` statement offers the most straightforward way of enumerating an async-enumerable's items.
+It is very similar to `foreach` for enumerables. The main difference is that `await foreach` awaits each item (and also disposal).
+
+The parallel jumps out in the interfaces involved:


Suggestion: change this sentence to "The API for async enumerables should be familiar to developers that have used enumerables".

This sentence was awkward for me on first read. I think it's because of the word "parallel" which made me wonder what parallel computing was involved.

BillWagner · 2019-01-07T16:39:15Z

async-iterator.md

+
+When the caller is moving the method forward and an exception is thrown (without being caught by user code in the async-iterator method), `MoveNextAsync()` will return a task as normal.
+
+That task is complete (rather than pending). When the caller tries to access its result the task will throw the exception it holds.


Instead of saying the task is complete, would it be more correct to say the task is faulted? /cc @stephentoub

The IsCompleted property on Task/ValueTask returns true if the task is in a final state, meaning it's either RanToCompletion/Faulted/Canceled, so technically "complete" is correct, though faulted would be, too.

BillWagner · 2019-01-07T16:40:09Z

async-iterator.md

+When background execution is moving the method forward and an exception is thrown without handling, the exception is similarly caught and passed onto the caller via the task.
+
+
+### Parallels with iterator and async control flow (optional)


Suggestion: "Relationship between iterator and async control flow"

BillWagner · 2019-01-07T16:42:38Z

async-iterator.md

+From there on, the control shifts between the method and background execution:
+- the background execution resumes the method after a long-running task completes,
+- the method yields control back to the background execution (when reaching an `await`).
+Only when the method completes with a `return` is the control fully returned to the caller.


Also, await only yields control to the caller when the task is still pending. It does not yield control if the awaited task completes synchronously.

BillWagner · 2019-01-07T16:50:17Z

async-iterator.md

+The execution of async-iterator methods mixes both of those patterns, with the control shifting between caller (repeatedly calls `MoveNextAsync()`), method (gives control to the caller when reaching a `yield return` and to the background execution when reaching an `await`) and background execution (resumes the method after an `await`).
+
+
+## Lowering


Consider everything starting here as a second blog post. Everything above provides a great mental model for any developer using C# that wants to use IAsyncEnumerable (either consuming them, or creating methods that return them.) Everything that follows is a discussion of how the compiler does this magic. Mixing the two in one post runs the risk that devs wanting to learn how to use the new feature get discouraged, feeling "this is really hard" after reading.

Stoping for now. (I got to the "quick recap so far" heading.)

This may be more than 2 posts. There's a lot of advanced topics to cover in one read. I'll review more later.

Include a one sentence, or a few word clause, to define lowering

I'd rather this be named something akin to "What the compiler does to implement async iterators"

BillWagner · 2019-01-07T16:55:06Z

async-iterator.md

+
+Because the method has a type parameter, the generated type will have one as well (let's call it `T2`). As part of rewriting the body of the method, all references to `T` will be converted to references to `T2`:
+```C#
+class UnspeakableType<T2>


😆 I'd always used AnonymousMumbleMumble as my types for these compiler generated classes.

KathleenDollard

This post has two distinct sections:

Understanding async iterators so you can use them
Understanding how they are implemented

I would definitely like to see these split as they have a different audience.

I think the first will have a wide audience and it would be good to incorporate something like this in docs. For that purpose, it can use a bit of grammatical smoothing.

KathleenDollard · 2019-01-08T18:40:55Z

async-iterator.md

+When you call `MoveNextAsync()`:
+- if the code reaches a `yield return` statement, you immediately get a `true`,
+- if the code reaches the end of the method, you immediately get a `false`,
+- if you reach an `await`, you get a pending task and the code continues to execute in the background.


@BillWagner Is this "continues to execute in the background" consistent with the way we talk about await elsewhere?

KathleenDollard · 2019-01-08T18:45:06Z

async-iterator.md

+- if it reaches the end of the method, that task is fulfilled with `false`,
+- if it reaches an `await`, execution continues in the background.
+
+Note that the method is moved forward either by the caller or by background execution, but never both. Calling `MoveNextAsync()` before the task from the previous call complets yield unspecified results.


spelling: completes

KathleenDollard · 2019-01-08T18:47:07Z

async-iterator.md

+When background execution is moving the method forward and an exception is thrown without handling, the exception is similarly caught and passed onto the caller via the task.
+
+
+### Parallels with iterator and async control flow (optional)


Or "Comparison"

KathleenDollard · 2019-01-08T18:50:06Z

async-iterator.md

+
+The execution of iterator methods shifts the control between the caller and the method:
+- the caller repeatedly calls `MoveNext()` (which executes the method),
+- the method yields control back to the caller (when reaching a `yield return`).


I found this a more comfortable explanation of what is happening than the earlier discussion of "continues in background"

KathleenDollard · 2019-01-08T18:51:31Z

async-iterator.md

+- the caller repeatedly calls `MoveNext()` (which executes the method),
+- the method yields control back to the caller (when reaching a `yield return`).
+
+The execution of async methods starts by the caller giving control to the method and background execution.


Perhaps it would add clarity to say

"giving control to the iterator method.."

KathleenDollard · 2019-01-08T18:53:55Z

async-iterator.md

+The execution of async-iterator methods mixes both of those patterns, with the control shifting between caller (repeatedly calls `MoveNextAsync()`), method (gives control to the caller when reaching a `yield return` and to the background execution when reaching an `await`) and background execution (resumes the method after an `await`).
+
+
+## Lowering


Include a one sentence, or a few word clause, to define lowering

I'd rather this be named something akin to "What the compiler does to implement async iterators"

BillWagner

I finished reading. This covers a lot of information well, and in detail.

I added additional comments as I finished reading.

A few additional writing style comments:

Overall, you define terms well when they are first used. I caught a couple where you didn't. When a final draft is ready, we should look for those again.
You sometimes use marker sentences to call out what you don't explain. "There are more details here, but I won't cover them." Consider deleting those. Don't alert readers to what you're not covering. Focus on what you are covering. You may want to add a note at the summary where you say there is additional complexity that you may cover later.

BillWagner · 2019-01-10T02:20:36Z

async-iterator.md

+Then I'll explain `yield return` suspensions, disposal and yield breaks.
+
+
+### `await`


I think this section (and the examples that follow would really benefit from a simple concrete example. The labels and the code in the comments would be much more clear by showing an example where the reader can build a mental map from what a C# developer would write to what the C# compiler generates.

BillWagner · 2019-01-10T02:24:32Z

async-iterator.md

+
+Note this is the same pattern used to lower awaits in async methods.
+
+As you can see, we're introducing a suspension and resumption in the middle of the method.


Suggestion: bold suspension and resumption on first use here. You define them well, and the bold will help readers note that these are important terms you use throughout the remainder of the article.

BillWagner · 2019-01-10T02:27:15Z

async-iterator.md

+The resumption is the code starting from label `resumeLabelN:`.
+
+You might wonder how execution resumes from that label. The lowering also adds logic at the beginning of the method to jumps to `resumeLabelN:` when the **state** is `N`.
+So `{ ... method body... }` is lowered to start with a **dispatching** `switch` statement:


This is a prime example of my earlier comment regarding a concrete example. I think readers will understand this concept much better by seeing where blocks of code are rearranged to resumeLabel1, resumeLabel2 and so on

BillWagner · 2019-01-10T02:31:37Z

async-iterator.md

+```
+
+
+#### Spilling (optional)


You should start this section with a sentence that defines "spilling".

BillWagner · 2019-01-10T02:34:50Z

async-iterator.md

+}
+```
+
+This pattern can be expanded to extract `catch` handlers: each `catch` block is replaced with logic to pend the exception (save the exception into a local, remember which exception handler we were in) and the original handlers are moved out into the extracted block.


I had to look up "pend". Is that a common term? Is there a more well-known substitute?

BillWagner · 2019-01-10T02:44:41Z

async-iterator.md

+`Dispose()` should execute different `finally` block(s) depdending on the state the method was suspended at:
+- No code should execute when disposing an iterator that was not moved forward.
+- After calling `MoveNext()` once or twice (ie. after reaching `yield return 1;` or `yield return 2;`) the `finally` should be evaluated.
+- After three or four steps (ie. after reaching `yield return 3;` or the end of the method) the `finally` should not be evaluated.


suggestion: it might help readers to point out that Dispose should not execute the finally block in this case because the finally block has already been executed.

BillWagner · 2019-01-10T02:50:41Z

async-iterator.md

+A few notes before getting started:
+- Although both iterator and async-iterator methods produce disposal logic, they are implemented quite differently in the Roslyn compiler. I'll focus on disposal of async-iterator methods.
+  - One reason for this difference is that unlike disposal of iterator methods, the disposal of async-iterator methods can encounter suspensions from awaits. For instance, an `await` inside a `finally`.
+- The caller should only invoke `DisposeAsync()` when the async-iterator method is suspended on a `yield return` statement. Invoking it at other times during the method's execution produces unspecified behavior.


This confuses me. I would think that DisposeAsync would be called after AsyncMoveNext returns false. But, I would think the async-iterator method wouldn't be suspended in that case. What am I missing?

BillWagner · 2019-01-10T02:57:35Z

async-iterator.md

+
+The pseudo-code below shows what we generate. It was manually edited for readability. In particular, it more closely reflects the lowering patterns and resembles the original code structure than what you would normally see from decompilation.
+
+You can see that:


This is an excellent example, and a great summary of the main concepts.

jcouv · 2019-01-10T08:11:34Z

Thanks all. I'll go over the feedback this weekend.

update

made sync class view to get document once workspace is fully loaded

Fix tests and fix-all scenario

Forward integration from dotnet/roslyn

The computation of completion items is divided into two tasks: 1. "Core" items(i.e.non - expanded) which should be included in the list regardless of the selection of expander. Right now this includes all items except those from unimported namespaces. 2 .Expanded items which only show in the completion list when expander is selected, or by default if the corresponding features are enabled. Right now only items from unimported namespaces are associated with expander. #1 is the essence of completion so we'd always wait until its task is completed and return the results. However, because we have a really tight perf budget in completion, and computing those items in #2 could be expensive especially in a large solution (e.g.requires syntax / symbol indices and/ or runs in OOP,) we decide to kick off the computation in parallel when completion is triggered, but only include its results if it's completed by the time task #1 is completed, otherwise we don't wait on it and just return items from #1 immediately. Task #2 will still be running in the background (until session is dismissed/committed,) and we'd check back to see if it's completed whenever we have a chance to update the completion list, i.e.when user typed another character, a filter was selected, etc. If so, those items will be added as part of the refresh. The reason of adopting this approach is we want to minimize typing delays. There are two ways user might perceive a delay in typing. First, they could see a delay between typing a character and completion list being displayed if they want to examine the items available. Second, they might be typing continuously w/ o paying attention to completion list, and simply expect the completion to do the "right thing" when a commit char is typed(e.g.commit "cancellationToken" when typing 'can$TAB$'). However, the commit could be delayed if completion is still waiting on the computation of all available items, which manifests as UI delays and in worst case timeouts in commit which results in unexpected behavior(e.g.typing 'can$TAB$' results in a 250ms UI freeze and still ends up with "can" instead of "cancellationToken".) This approach would ensure the computation of #2 will not be the cause of such delays, with the obvious trade off of potentially not providing expanded items until later(or never) in a completion session even if the feature is enabled.Note that in most cases we'd expect task #2 to finish in time and complete result would be available from the start of the session.However, even in the case only partial result is returned at the start, we still believe this is acceptable given how critical perf is in typing scenario. Additionally, expanded items are usually considered complementary. The need for them only rise occasionally(it's rare when users need to add imports,) and when they are needed, our hypothesis is because of their more intrusive nature(adding an import to the document) users would more likely to contemplate such action thus typing slower before commit and / or spending more time examining the list, which give us some opportunities to still provide those items later before they are truly required. In this commit we have to handle adding those delayed expanded items into completion list in Roslyn. This is because the `CompletionContext.IsIncomplete` flag isn't fully supported in classic mode. Will need to move to that API once it's implemented properly.

Track the telemetry of rename

…tionAPI Access services on Solution rather than Workspace

jcouv added 8 commits December 30, 2018 00:35

Working on blog post

3710516

Simplify control flow section

a36a956

Rename

2a3122f

Formatting tweaks

bac2316

Explain extracted handlers. Public APIs

f5605a2

Fix table layout

23af2d5

Fix headings

9580b0d

Add end-to-end example

5f022aa

jcouv force-pushed the blog-post branch from 118ddd5 to 5f022aa Compare January 6, 2019 23:10

stephentoub reviewed Jan 7, 2019

View reviewed changes

CyrusNajmabadi reviewed Jan 7, 2019

View reviewed changes

async-iterator.md Show resolved Hide resolved

CyrusNajmabadi reviewed Jan 7, 2019

View reviewed changes

BillWagner reviewed Jan 7, 2019

View reviewed changes

KathleenDollard reviewed Jan 8, 2019

View reviewed changes

BillWagner reviewed Jan 10, 2019

View reviewed changes

genlu pushed a commit that referenced this pull request Mar 7, 2019

Merge pull request #1 from dotnet/master

76eddf2

update

jcouv pushed a commit that referenced this pull request Mar 16, 2019

Merge pull request #1 from heejaechang/partial_load_hechang

a2e0052

made sync class view to get document once workspace is fully loaded

jcouv and others added 4 commits April 28, 2019 20:50

Add notes for [EnumeratorCancellation] and combining of tokens

7d5e919

Null out __combinedTokens after disposal

0192567

Address feedback

5532aa9

Merge remote-tracking branch 'origin/blog-post' into blog-post

4c493da

jcouv pushed a commit that referenced this pull request Jan 4, 2020

Merge pull request #1 from CyrusNajmabadi/patch-37678

69e5f5e

Fix tests and fix-all scenario

jcouv pushed a commit that referenced this pull request Jul 13, 2020

Merge pull request #1 from dotnet/master

ed639d3

Forward integration from dotnet/roslyn

jcouv added 2 commits January 19, 2022 11:11

clear Current upon exit

9956d8c

Update async-iterator.md

d0a56dd

jcouv pushed a commit that referenced this pull request Apr 2, 2024

Merge pull request #1 from Cosifne/dev/shech/AddSimpleTelemetry

6425ccb

Track the telemetry of rename

jcouv pushed a commit that referenced this pull request Oct 23, 2024

Merge pull request #1 from alexgav/dev/alexgav/FixExternalRazorComple…

8cb765f

…tionAPI Access services on Solution rather than Workspace


		That task is complete (rather than pending). When the caller tries to access its result the task will throw the exception it holds.

		When background execution is moving the method forward and an exception is thrown without handling, the exception is similarly caught and passed onto the caller via the task.

		When background execution is moving the method forward and an exception is thrown without handling, the exception is similarly caught and passed onto the caller via the task.


		### Parallels with iterator and async control flow (optional)


		#### Locals

		Although I won't go into much details on this, it is worth mentioning that all the local variables in the method are converted to fields on a compiler-generated type, so they maintain their values across suspensions/resumptions.

		Only when the method completes with a `return` is the control fully returned to the caller.

		The execution of async-iterator methods mixes both of those patterns, with the control shifting between caller (repeatedly calls `MoveNextAsync()`), method (gives control to the caller when reaching a `yield return` and to the background execution when reaching an `await`) and background execution (resumes the method after an `await`).

		When either the caller or background execution need to move the method forward, execution will resume from the right label because the state variable was set to `N` and the dispatching logic will jump to that label.

		Because there is a cost to starting background execution, suspending and resuming, the lowering pattern is optimized: if the task was already completed, we avoid that overhead and instead just move ahead with the result.


		When the caller is moving the method forward and an exception is thrown (without being caught by user code in the async-iterator method), `MoveNextAsync()` will return a task as normal.

		That task is complete (rather than pending). When the caller tries to access its result the task will throw the exception it holds.

		The execution of async-iterator methods mixes both of those patterns, with the control shifting between caller (repeatedly calls `MoveNextAsync()`), method (gives control to the caller when reaching a `yield return` and to the background execution when reaching an `await`) and background execution (resumes the method after an `await`).


		## Lowering

		Then I'll explain `yield return` suspensions, disposal and yield breaks.


		### `await`


		Note this is the same pattern used to lower awaits in async methods.

		As you can see, we're introducing a suspension and resumption in the middle of the method.


		The pseudo-code below shows what we generate. It was manually edited for readability. In particular, it more closely reflects the lowering patterns and resembles the original code structure than what you would normally see from decompilation.

		You can see that:

PR for blog post on async-iterators #1

Are you sure you want to change the base?

PR for blog post on async-iterators #1

Conversation

jcouv commented Jan 2, 2019

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

stephentoub Jan 7, 2019 • edited 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

Choose a reason for hiding this comment

CyrusNajmabadi Jan 7, 2019 • edited 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

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

KathleenDollard 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

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

jcouv commented Jan 10, 2019

stephentoub Jan 7, 2019 •

edited

Loading

CyrusNajmabadi Jan 7, 2019 •

edited

Loading