Clearer documentation for errdefer in blocks

[alinebee]

The current documentation example for errdefer only shows it being used at function scope, where its behaviour is pretty intuitive. But the behaviour in if/while/for etc blocks - i.e. that the errdefer goes out of scope at the end of the block - is subtle and could use more documentation.

In particular, blocks silently break the pattern described in the documentation where "The deallocation code is always directly following the allocation code." A couple of footguns:

const std = @import("std");

const Error = error {
    FlagrantViolation,
};

// Example 1
fn errdeferAtFunctionScope(allocator: *std.mem.Allocator) !void {
    const ptr = try allocator.alloc(u8, 1);
    
    // Does not leak: the errdefer is at the same scope as the return.
    errdefer allocator.free(ptr);
    
    return Error.FlagrantViolation;
}

// Example 2
fn errdeferInBlock(allocator: *std.mem.Allocator) !void {
    {
        const ptr = try allocator.alloc(u8, 1);

        // Leaks: by the time the error is returned, errdefer has gone out of scope.
        errdefer allocator.free(ptr);
    }
    
    return Error.FlagrantViolation;
}

// Example 3
fn errdeferInLoop(allocator: *std.mem.Allocator) !void {
    var count: usize = 0;
    
    while (true) {
        const ptr = try allocator.alloc(u8, 1);

        // Leaks on the second iteration of the loop: 
        // the errdefer from the first iteration will have gone out of scope.
        errdefer allocator.free(ptr);
        
        count += 1;
        if (count == 2) {
            return Error.FlagrantViolation;
        }
    }
}

test "errdefer at function scope" {
    // Passes
    std.testing.expectError(Error.FlagrantViolation, errdeferAtFunctionScope(std.testing.allocator));
}

test "errdefer in block" {
    // Fails with a leak
    std.testing.expectError(Error.FlagrantViolation, errdeferInBlock(std.testing.allocator));
}

test "errdefer in loop" {
    // Fails with a leak
    std.testing.expectError(Error.FlagrantViolation, errdeferInLoop(std.testing.allocator));
}

The specific case that bit me was Example 3: repeatedly allocating in a failable loop, and assuming that I could keep an errdefer next to the alloc call and undo all previous allocations that way. It makes sense in retrospect that it doesn't work that way, but some scope examples in the docs could help users arrive at that mental model.

(Ideally, useless errdefer blocks like 2 could be a compiler error; 3 might be harder for the compiler to spot.)

[DontBreakAlex]

Hi, just commenting to say that as a new Zig user, I just shot my foot with example 3.

[mslapek]

Ideally, useless errdefer blocks like 2 could be a compiler error;

That's an excellent idea! 👏 I initially thought that errdefer works with nullable (non-error) result, because this func compiled:

fn foo_nullable() ?i64 {
    errdefer {
        _ = stdout.writeAll("foo_nullable\n") catch undefined;
    }
    return null;
}

[Vexu]

This was addressed by #10607.

Ideally, useless errdefer blocks like 2 could be a compiler error;

That's an excellent idea! clap I initially thought that errdefer works with nullable (non-error) result, because this func compiled:

That is #2654