Eduasync part 13: first look at coroutines with async

(This part covers project 18 in the source code.)

As I mentioned in earlier parts, the "awaiting" part of async methods is in no way limited to tasks. So long as we have a suitable GetAwaiter() method which returns a value of a type which in turn has suitable methods on it, the compiler doesn’t really care what’s going on. It’s time to exploit that to implement some form of coroutines in C#.

Introduction to coroutines

The fundamental idea of coroutines is to have multiple methods executing cooperatively, each of them maintaining their position within the coroutine when they yield to another. You can almost think of them as executing in multiple threads, with only one thread actually running at a time, and signalling between the different threads to control flow. However, we don’t really need multiple threads once we’ve got continuations – we can have a single thread with a complex flow of continuations, and still only a very short "real" stack. (The control flow is stored in normal collections instead of being implicit on the thread’s stack.)

Coroutines were already feasible in C# through the use of iterator blocks, but the async feature of C# allows a slightly more natural way of expressing them, in my view. (The linked Wikipedia page gives a sketch of how coroutines can be built on top of generators, which in the general concept that iterator blocks implement in C#.)

I have implemented various flavours of coroutines in Eduasync. It’s possible that some (all?) of them shouldn’t strictly be called coroutines, but they’re close enough to the real thing in feeling. This is far from an exhaustive set of approaches. Once you’ve got the basic idea of what I’m doing, you may well want to experiment with your own implementations.

I’m not going to claim that the use of coroutines in any of my examples really makes any sense in terms of making real tasks easier. This is purely for the sake of interest and twisting the async feature for fun.

Round-robin independent coroutines

Our first implementation of coroutines is relatively simple. A coordinator effectively "schedules" the coroutines it’s set up with in a round-robin fashion: when one of the coroutines yields control to the coordinator, the coordinator remembers where the coroutine had got to, and then starts the next one. When each coroutine has executed its first piece of code and yielded control, the coordinator will go back to the first coroutine to continue execution, and so on until all coroutines have completed.

The coroutines don’t know about each other, and no data is being passed between them.

Hopefully it’s reasonably obvious that the coordinator contains all the smarts here – the coroutines themselves can be relatively dumb. Let’s look at what the client code looks like (along with the results) before we get to the coordinator code.

Client code

The sample code contains three coroutines, all of which take a Coordinator parameter and have a void return type. These are passed to a new coordinator using a collection initializer and method group conversions; the coordinator is then started. Here’s the entry point code for this:

private static void Main(string[] args)
    var coordinator = new Coordinator { 

When each coroutine is initially started, the coordinator passes a reference to itself as the argument to the coroutine. That’s how we solve the chicken-and-egg problem of the coroutine and coordinator having to know about each other. The way a coroutine yields control is simply by awaiting the coordinator. The result type of this await expression is void – it’s just a way of "pausing" the coroutine.

We’re not doing anything interesting in the actual coroutines – just tracing the execution flow. Of course we could do anything we wanted, within reason. We could even await a genuinely asynchronous task such as fetching a web page asynchronously. In that case the whole coroutine collection would be "paused" until the fetch returned.

Here’s the code for the first coroutine – the second and third ones are similar, but use different indentation for clarity. The third coroutine is also shorter, just for fun – it only awaits the coordinator once.

private static async void FirstCoroutine(Coordinator coordinator)
    Console.WriteLine("Starting FirstCoroutine");
    Console.WriteLine("Yielding from FirstCoroutine…");

    await coordinator;

    Console.WriteLine("Returned to FirstCoroutine");
    Console.WriteLine("Yielding from FirstCoroutine again…");

    await coordinator;

    Console.WriteLine("Returned to FirstCoroutine again");
    Console.WriteLine("Finished FirstCoroutine");

And here’s the output…

Starting FirstCoroutine
Yielding from FirstCoroutine…
    Starting SecondCoroutine
    Yielding from SecondCoroutine…
        Starting ThirdCoroutine
        Yielding from ThirdCoroutine…
Returned to FirstCoroutine
Yielding from FirstCoroutine again…
    Returned to SecondCoroutine
    Yielding from SecondCoroutine again…
        Returned to ThirdCoroutine
        Finished ThirdCoroutine…
Returned to FirstCoroutine again
Finished FirstCoroutine
    Returned to SecondCoroutine again
    Finished SecondCoroutine

Hopefully that’s the output you expected, given the earlier description. Again it may help if you think of the coroutines as running in separate pseudo-threads: the execution within each pseudo-thread is just linear, and the timing is controlled by our explicit "await" expressions. All of this would actually be pretty easy to implement using multiple threads which really did just block on each await expression – but the fun part is keeping it all in one real thread. Let’s have a look at the coordinator.

The Coordinator class

Some of the later coroutine examples end up being slightly brainbusting, at least for me. This one is relatively straightforward though, once you’ve got the basic idea. All we need is a queue of actions to execute. After initialization, we want our queue to contain the coroutine starting points.

When a coroutine yields control, we just need to add the remainder of it to the end of the queue, and move on to the next item. Obviously the async infrastructure will provide "the remainder of the coroutine" as a continuation via the OnContinue method.

When a coroutine just returns, we continue with the next item in the queue as before – it’s just that we won’t add a continuation to the end of the queue. Eventually (well, hopefully) we’ll end up with an empty queue, at which point we can stop.

Initialization and a choice of data structures

We’ll represent our queue using Queue<T> where the T is a delegate type. We have two choices here though, because we have two kinds of delegate – one which takes the Coordinator as a parameter (for the initial coroutine setup) and one which has no parameters (for the continuations). Fortunately we can convert between the two in either direction very simply, bearing in mind that all of this is within the context of a coordinator. For example:

// If we’re given a coroutine and want a plain Action
Action<Coordinator> coroutine = …; 
Action action = () => coroutine(this);

// If we’re given a plain Action and want an Action<Continuation>:
Action continuation = …; 
Action<Coordinator> coroutine = ignored => continuation();

I’ve arbitrarily chosen to use the first option, so there’s a Queue<Action> internally.

Now we need to get the collection initializer working. The C# compiler requires an appropriate Add method (which is easy) and also checks that the type implements IEnumerable. We don’t really need to be able to iterate over the queue of actions, so I’ve use explicit interface implementation to reduce the likelihood of GetEnumerator() being called inappropriately, and made the method throw an exception for good measure. That gives us the skeleton of the class required for setting up:

public sealed class Coordinator : IEnumerable
    private readonly Queue<Action> actions = new Queue<Action>();

    // Used by collection initializer to specify the coroutines to run
    public void Add(Action<Coordinator> coroutine)
        actions.Enqueue(() => coroutine(this));

    // Required for collection initializers, but we don’t really want
    // to expose anything.
    IEnumerator IEnumerable.GetEnumerator()
        throw new NotSupportedException("IEnumerable only supported to enable collection initializers");

(Note that I haven’t used XML documentation anywhere here – it’s great for real code, but adds clutter in blog posts.)

For production code I’d probably prevent Add from being called after the coordinator had been started, but there’s no need to do it in our well-behaved sample code. We’re only going to add extra actions to the queue via continuations, which will be added due to await expressions.

The main execution loop and async infrastructure

So far we’ve got code to register coroutines in the queue – so now we need to execute them. Bearing in mind that the actions themselves will be responsible for adding continuations, the main loop of the coordinator is embarrassingly simple:

// Execute actions in the queue until it’s empty. Actions add *more*
// actions (continuations) to the queue by awaiting this coordinator.
public void Start()
    while (actions.Count > 0)

Of course, the interesting bit is the code which supports the async methods and await expressions. We know we need to provide a GetAwaiter() method, but what should that return? Well, we’re just going to use the awaiter to add a continuation to the coordinator’s queue. It’s got no other state than that – so we might as well return the coordinator itself, and put the other infrastructure methods directly in the coordinator.

Again, this is slightly ugly, as the extra methods don’t really make sense on the coordinator – we wouldn’t want to call them directly from client code, for example. However, they’re fairly irrelevant – we could always create a nested type which just had a reference to its "parent" coordinator if we wanted to. For simplicity, I haven’t bothered with this – I’ve just implemented GetAwaiter() trivially:

// Used by await expressions to get an awaiter
public Coordinator GetAwaiter()
    return this;

So, that leaves just three members still to implement: IsCompleted, OnCompleted and GetResult. We always want the IsCompleted property to return false, as otherwise the coroutine will just continue executing immediately without returning to cede control; the await expression would be pointless. OnCompleted just needs to add the continuation to the end of the queue – we don’t need to attach it to a task, or anything like that. Finally, GetResult is a no-op – we have no results, no exceptions, and basically nothing to do. You might want to add a bit of logging here, if you were so inclined, but there’s no real need.

So, here are the final three members of Coordinator:

// Force await to yield control
public bool IsCompleted { get { return false; } }

public void OnCompleted(Action continuation)
    // Put the continuation at the end of the queue, ready to
    // execute when the other coroutines have had a go.

public void GetResult()
    // Our await expressions are void, and we never need to throw
    // an exception, so this is a no-op.

And that’s it! Fewer than 50 lines of code required, and nothing complicated at all. The interesting behaviour is all due to the way the C# compiler uses the coordinator when awaiting it.

We need AsyncVoidMethodBuilder as before, as we have some async void methods – but that doesn’t need to do anything significant. That’s basically all the code required to implement these basic round-robin coroutines.


Our first foray into the weird and wonderful world of coroutines was relatively tame. The basic idea of a coordinator keeping track of the state of all the different coroutines in one sense or another will keep coming back to us, but with different ways of controlling the execution flow.

Next time we’ll see some coroutines which can pass data to each other.

14 thoughts on “Eduasync part 13: first look at coroutines with async”

  1. Jon,

    “Coroutines were already feasible in C# through the use of iterator blocks”. Do you happen to have any examples of this? For example the output from your first example above – is it possible to “simulate” something like that in .NET4 through the use of yield?



  2. @James: I don’t have an example to hand. I suspect the coordinator would just have to iterate over a collection of iterators, basically – which would mean the coroutine wouldn’t need to know about the coordinator, of course. I may try to come up with an example another time.


  3. Jon,

    Is there a reason you wouldn’t call an async methods coroutines in all cases? The moment it has an await it qualifies as a subroutine with multiple entries and exits. I know from the outside it just looks like a method with a Task* signature, but internally it suspends itself and hands control to another routine (potentially a coroutine as well) and resumes on completion of the other routine.


  4. @Arne: Coroutines at least make *me* think of calling each other, rather than having a strict “call this, let it run to completion (possibly calling something else) and then come back to me” model, which is what we *normally* see with async.

    In terms of a strict computer science definition, you may be right though. I’m not an expert :)


  5. The use of Queue seems a little strange to me, since I think of this sort of co-routine coordinator as a round-robin scheduler, so I expected an array and a current index, but it does make the code much simpler.


  6. @James

    Rob Eisenberg gives a great example of how to do this in his MIX talk, “Build Your Own MVVM Framework.” The relevent bit starts around 48 or 49 minutes in.

    The code for the video is available as an example in Rob’s Caliburn.Micro source download.


  7. @Simon: Using an array is a bit of a pain because a) one coroutine can finish earlier than the others; b) you need to specify the coroutines as part of initialization.

    For the second part I guess I could use a params array…


  8. Well, I don’t get this. I don’t understand what you’re trying to achieve with this code? I’m not a .NET expert but I think you left *the* central point out of you’re discussion.

    The main problem with coroutines is stack handling. I do not understand how you handle that problem with you’re code or does the .NET / C# runtime does that for you automatically? How do you capture the current stack and how do you restore it before you restart a coroutine? If you do not and if the runtime does it neither, it’s just a question of time until you get a stack overflow, which simply would mean that you haven’t implemented coroutines but an overly complicated version of plain old function calls / recursion.

    Well, maybe I’m totally wrong. I surely left something important out of my calculation but I don’t know what?!


  9. @Martin: The C# compiler doesn’t capture the complete stack – just where you are within the current method. But it *does* do that part for you, so I think it still counts as a coroutine :)


  10. @skeet

    Ahhhh, Ok, so the runtime captures the current instruction counter as well as the local variables of the currently executing function? But the call stack is lost?

    So, if i have:

    function foo () = … do something … await … do something else …


    function bar () = … call foo() …

    The fact, that foo() was called from bar() and therefore should return to bar() after completion of foo() is lost forever?


  11. @Martin: It’s not really the runtime – it’s the C# compiler. It generates a nested class containing all the local variables, and maintains a state counter for “where it had got to”. See the rest of the parts in this series for details :)

    And yes, the fact that foo() was called from bar() is lost – because foo() will actually return as soon as we hit the first await. In my coroutine example, it’s the coordinator which actually calls the coroutines.

    My guess is that you’ve jumped into the end of this series – it’ll make more sense if you start from the beginning :)


  12. @skeet

    > My guess is that you’ve jumped into the end of this series – it’ll make more sense
    > if you start from the beginning :)

    Most likely you’re right … but ;-) … I just came along because I searched for information on how to implement “real” coroutines / lightweight processes on the CLR (but I currently doubt that this is possible at all since there seems to be no way to access the stack in the needed way from within a managed environment).

    I really was happy and hopeful as I saw that you tried a new way of achieving things. So my expectations went high … and unfortunately felt back down to reality after reading your answers. But I promise you, I will read at least some of your prior articles. :-)

    Anyway, thanks for spending your time,


Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s