Iterator block implementation details: auto-generated state machines

Question

High level overview: what's the pattern?

This article originally came about because a reader asked about the difference between using iterator blocks for methods returning IEnumerator and those returningIEnumerable. In addition, there's the choice between the nongeneric interfaces and the generic ones. We'll start off by using the same iterator block for each of the four possibilities, and look at the differences in the generated code. Throughout this article I'll present the C# equivalent of the code that the compiler produces. Obviously the compiler doesn't actually produce C#, but I've used Reflector to decompile the code as C#.

Our first sample will just yield the numbers 0 to 9 in sequence. Initially we'll declare the method to return the nongeneric IEnumerator. Here's the complete code:

using System;
using System.Collections;

class Test
{
    static IEnumerator GetCounter()
    {
        for (int count = 0; count < 10; count++)
        {
            yield return count;
        }
    }
}

Simple, right? Well, let's see what that turns into after compilation. Hold your breath...

internal class Test
{
    // Note how this doesn't execute any of our original code
    private static IEnumerator GetCounter()
    {
        return new <GetCounter>d__0(0);
    }

    // Nested type automatically created by the compiler to implement the iterator
    [CompilerGenerated]
    private sealed class <GetCounter>d__0 : IEnumerator<object>, IEnumerator, IDisposable
    {
        // Fields: there'll always be a "state" and "current", but the "count"
        // comes from the local variable in our iterator block.
        private int <>1__state;
        private object <>2__current;
        public int <count>5__1;

        [DebuggerHidden]
        public <GetCounter>d__0(int <>1__state)
        {
            this.<>1__state = <>1__state;
        }

        // Almost all of the real work happens here
        private bool MoveNext()
        {
            switch (this.<>1__state)
            {
                case 0:
                    this.<>1__state = -1;
                    this.<count>5__1 = 0;
                    while (this.<count>5__1 < 10)
                    {
                        this.<>2__current = this.<count>5__1;
                        this.<>1__state = 1;
                        return true;
                    Label_004B:
                        this.<>1__state = -1;
                        this.<count>5__1++;
                    }
                    break;

                case 1:
                    goto Label_004B;
            }
            return false;
        }

        [DebuggerHidden]
        void IEnumerator.Reset()
        {
            throw new NotSupportedException();
        }

        void IDisposable.Dispose()
        {
        }

        object IEnumerator<object>.Current
        {
            [DebuggerHidden]
            get
            {
                return this.<>2__current;
            }
        }

        object IEnumerator.Current
        {
            [DebuggerHidden]
            get
            {
                return this.<>2__current;
            }
        }
    }
}

We'll start off with a reasonably high level look at what's going on, explaining each member. The real work is done in MoveNext() so we'll skim over that at this point, and go deeper into just that method when we're happy with the rest of the code. Looking at the code from top to bottom, here's a running commentary:

• The source shown above isn't quite valid C# - it uses names which are illegal within normal C#. The use of illegal names in generated code is quite common; it prevents any possibility of clashes with normal names, as well as stopping the manually written C# from explicitly using the generated code.
• Calling GetCounter() just calls the constructor of <GetCounter>d__0 which is the type implementing the iterator. The constructor in turn just sets the state of the iterator. None of the code in our original class has been executed yet.
• Various elements of the code are decorated with the CompilerGenerated and DebuggerHidden attributes. CompilerGenerated is almost irrelevant - the MSDN documentation for it mentions that it allows SQL Server extra access, but 99.9% of developers really don't need to know that. It's nice to see it there for the sake of clarity, however. DebuggerHidden just stops debuggers (well, those that choose to take note of the attribute) from stepping into or breaking in the code. From now on I won't bother showing these attributes.
• <GetCounter>d__0 (hereafter known as just "the iterator type") implements three interfaces: IEnumerator<object>, IEnumerator and IDisposable. In fact, the first interface implies the other two anyway, but I've left them all in the list to make things clearer. It's interesting that the generic interface is implemented even though our original GetCounter() method used the nongeneric form. This is probably just for consistency - we'll see that very little changes when we tell the compiler to use the generic version.
• It's very important that IDisposable is implemented (aside from being necessary in order to implement IEnumerator<object>). The foreach statement in C# callsDispose on any iterator which implements IDisposable; the call is in a finally block just as with the using statement. In the very rare cases where you use an iterator manually instead of with a foreach loop, you should use a using statement to make sure that Dispose is called. We'll see why later on.
• The iterator type is nested, which means it has access to all the private members of the enclosing class. That's important if your iterator block calls other private methods or accesses private variables (or other private members, of course). We'll see an example of this later on.
• The iterator type has three fields - two private and one public. The two private variables keep track of the value to return from the Current property and what state the iterator is in. We'll be looking at these in a lot more detail later. To be honest, I don't know why the variable associated with the count is public. When we look at what happens if the original iterator block method takes a parameter, we'll see public fields in use - although a different design decision could have kept everything private.
• The constructor just sets the state of the iterator. In this case, the only code calling the constructor is the GetCounter() method which always passes in 0 as the initial state, but we'll see in a minute that in other situations there's a genuine reason to pass the state in as a parameter.
• MoveNext() is basically just a big switch statement. It always is, and the value it's switching on is a state in the state machine, so it knows which bit of code to execute next. We'll spend a lot of time looking at this in a bit.
• The Reset method from IEnumerator always throws System.NotSupportedException. This isn't just an implementation decision - it's mandated by the C# specification.
• In this first simple example, the Dispose method does nothing. We'll look at this as a separate topic.
• Both the IEnumerator and IEnumerator<object> implementations of Current simply return the value of the <>2__current variable. The C# language specification explicitly leaves the behaviour of the Current property undefined in "odd" cases (such as accessing it before the first call to MoveNext() or when MoveNext() has returned false).

Generic vs nongeneric interfaces

We've seen how declaring a method to return IEnumerator results in an iterator which implements IEnumerator<object> as well. Now let's change the code just slightly, to make the method explicitly return IEnumerator<int>:

using System;
using System.Collections.Generic;

class Test
{
    static IEnumerator<int> GetCounter()
    {
        for (int count = 0; count < 10; count++)
        {
            yield return count;
        }
    }
}

I won't post the whole of the resulting code, but here are the changes. Firstly, and most obviously, the GetCounter() method has changed return type, but nothing else:

private static IEnumerator<int> GetCounter()
{
    return new <GetCounter>d__0(0);
}

Likewise the iterator now implements IEnumerator<int> instead of IEnumerator<object>. The type involved here is called the yield type of the iterator. Every yield return statement has to return something which can be implicitly converted to the yield type. As we've seen, when a nongeneric interface is used the yield type isobject. Here's the new class signature:

private sealed class <GetCounter>d__0 : IEnumerator<int>, IEnumerator, IDisposable

Similarly the Current property implementing the generic interface and the backing variable are changed to int:

private int <>2__current;
  
int IEnumerator<int>.Current
{
    get
    {
        return this.<>2__current;
    }
}

Other than those minor changes, the class looks the same as it did before.

Returning IEnumerable

There are more significant changes if we change the original code to return IEnumerable or its generic equivalent instead of IEnumerator. We'll change the code to return IEnumerable<int> and stick with the generic interfaces from now on, as we've seen they make very little difference. So, here's the source:

using System;
using System.Collections.Generic;

class Test
{
    static IEnumerable<int> GetCounter()
    {
        for (int count = 0; count < 10; count++)
        {
            yield return count;
        }
    }
}

... and the resulting code (with attributes stripped out for brevity)

• Part 2 continuous soon...