A colleague wrote an iterator method and an async method that validate their arguments, but ArgumentNullException is only thrown when the result is enumerated or awaited, far from the bad call. Why does this happen, and how do local functions fix it? Also explain static local functions and when to prefer a local function over a lambda or private method.

1. Iterator state machine

// public IEnumerable<string> ReadLines(string path) => new <ReadLines>d__0(-2) { <>3__path = path };
private sealed class <ReadLines>d__0 : IEnumerable<string>, IEnumerator<string>
{
    private int <>1__state;
    private string <>2__current;
    public string <>3__path;
    bool IEnumerator.MoveNext()
    {
        switch (<>1__state)
        {
            case 0:
                <>1__state = -1;
                ArgumentException.ThrowIfNullOrEmpty(path);   // guard lives here
                ...
        }
    }
}

The method returns the object immediately; the guard runs when MoveNext first executes.

2. Async state machine

public Task<Order> GetAsync(Guid id, CancellationToken ct)
{
    var sm = new <GetAsync>d__0 { <>t__builder = AsyncTaskMethodBuilder<Order>.Create(), id = id, ct = ct, <>1__state = -1 };
    sm.<>t__builder.Start(ref sm);          // runs MoveNext synchronously until the first incomplete await
    return sm.<>t__builder.Task;
}

MoveNext wraps the body in try/catch; any exception calls builder.SetException(ex), faulting the task. So even synchronous exceptions become task faults.

3. Local functions and capture

A non-static local function that captures locals and is only called directly uses a struct closure passed by ref (no heap allocation). But iterator or async local functions must hoist captured variables into their state machine (heap) — another reason to pass values as parameters and make them static.

4. Stack traces

Modern .NET stack traces show local functions as ReadLines(String path)+Iterate(String path) (demangled from <ReadLines>g__Iterate|0_0) and async frames cleanly, so splitting doesn't hurt diagnostics.

5. Choosing exception timing for async APIs

• Usage errors (null arguments, invalid enum values): throw synchronously — they're bugs, and early failure is clearer.
• Operational errors (not found, I/O failures, cancellation): put them in the task — callers handle them at await.
• Microsoft's guidelines for TAP methods recommend synchronous throwing only for usage errors.

6. ValueTask and eager paths

For hot async methods, the split pattern also enables synchronous fast paths: the non-async outer method can return ValueTask.FromResult(cached) without allocating a state machine, delegating to the async local function only when I/O is needed.

Try it yourself

1. Write an iterator with a guard in the body, call it with bad input and enumerate later; then split it.
2. Write an async method with a guard and call it without awaiting.
3. Mark the local function static and fix compile errors by passing parameters.
4. Inspect the generated state machines in SharpLab.

namespace Advanced.LocalFunctions;

public sealed record Row(int LineNumber, string[] Fields);

public static class CsvReader
{
    // BUG: validation deferred until enumeration
    public static IEnumerable<Row> ReadRowsDeferred(TextReader reader)
    {
        ArgumentNullException.ThrowIfNull(reader);
        var line = 0;
        while (reader.ReadLine() is { } text) yield return new Row(++line, text.Split(','));
    }

    // FIX: eager validation, lazy iteration
    public static IEnumerable<Row> ReadRows(TextReader reader)
    {
        ArgumentNullException.ThrowIfNull(reader);
        return Iterator(reader);

        static IEnumerable<Row> Iterator(TextReader r)   // static: no accidental captures
        {
            var line = 0;
            while (r.ReadLine() is { } text) yield return new Row(++line, text.Split(','));
        }
    }

    // Same idea for async
    public static Task<int> CountRowsAsync(TextReader reader, CancellationToken ct)
    {
        ArgumentNullException.ThrowIfNull(reader);
        return Core();

        async Task<int> Core()                            // captures reader and ct without allocation
        {
            var count = 0;
            while (await reader.ReadLineAsync(ct) is not null) count++;
            return count;
        }
    }

    // Recursion and generics are natural in local functions
    public static int Depth<T>(IReadOnlyDictionary<T, T> parentOf, T node) where T : notnull
    {
        return Walk(node);

        int Walk(T current) => parentOf.TryGetValue(current, out var parent) ? 1 + Walk(parent) : 0;
    }
}

public static class Program
{
    public static async Task Main()
    {
        var deferred = CsvReader.ReadRowsDeferred(null!);    // no exception yet
        try { deferred.First(); } catch (ArgumentNullException) { Console.WriteLine("Thrown late, at enumeration"); }

        try { CsvReader.ReadRows(null!); } catch (ArgumentNullException) { Console.WriteLine("Thrown at the call"); }

        using var reader = new StringReader("a,b\nc,d\n");
        Console.WriteLine(await CsvReader.CountRowsAsync(reader, CancellationToken.None)); // 2

        var parents = new Dictionary<string, string> { ["leaf"] = "branch", ["branch"] = "root" };
        Console.WriteLine(CsvReader.Depth(parents, "leaf"));  // 2
    }
}