ref structs, ref fields and scoped

A reader that walks through a 12-byte packet must keep the bytes it has not read yet, and to copy nothing it keeps them as a ReadOnlySpan<byte>. A class cannot hold that field: the compiler refuses it with CS8345. Declared as a ref struct instead, the reader below read four values, and a million such readers allocated 0 bytes.

Three features make such types possible: ref structs can hold spans because they never leave the stack, ref fields hold a reference to a variable, and the scoped modifier tells the compiler how far a reference may travel. You will write a ref struct, let callers pass stack memory, fix escape errors and use ref structs in generic code.

A ref struct can hold a span because it never leaves the stack

reader.cs declares PacketReader as a ref structref struct: A struct declared with ref struct, such as Span<T>. Its instances live only on the stack: it cannot be boxed, be a field of a class, be captured by a lambda or be kept across an await. with a span field, reads a type, a sensor number, a temperature and a battery level from 12 bytes, then builds a million readers over the same array:

// A ref struct that reads big-endian numbers from a 12-byte packet without copying it.
using System.Buffers.Binary;

byte[] packet = [0x00, 0x2A, 0x00, 0x00, 0x30, 0x39, 0x41, 0xD8, 0x00, 0x00, 0x01, 0xF4];
var reader = new PacketReader(packet);
Console.WriteLine($"type {reader.ReadUInt16()}, sensor {reader.ReadUInt32()}, temperature {reader.ReadSingle()}, battery {reader.ReadUInt16()} mV");
Console.WriteLine($"{reader.Remaining} bytes left, and reading on: {reader.TryReadUInt16(out _)}");

long before = GC.GetAllocatedBytesForCurrentThread();
long sum = 0;
for (int i = 0; i < 1_000_000; i++)
{
    var r = new PacketReader(packet);
    sum += r.ReadUInt16() + r.ReadUInt32();
}
Console.WriteLine($"1,000,000 readers: {GC.GetAllocatedBytesForCurrentThread() - before} bytes allocated (sum {sum})");

ref struct PacketReader(ReadOnlySpan<byte> packet)
{
    private ReadOnlySpan<byte> _rest = packet; // a span as a field: allowed in a ref struct only

    public readonly int Remaining => _rest.Length;

    public ushort ReadUInt16() => TryReadUInt16(out ushort value) ? value : throw new InvalidOperationException("not enough bytes");

    public bool TryReadUInt16(out ushort value)
    {
        value = 0;
        if (_rest.Length < 2) return false;
        value = BinaryPrimitives.ReadUInt16BigEndian(_rest);
        _rest = _rest[2..];
        return true;
    }

    public uint ReadUInt32()
    {
        uint value = BinaryPrimitives.ReadUInt32BigEndian(_rest); // throws if fewer than 4 bytes are left
        _rest = _rest[4..];
        return value;
    }

    public float ReadSingle()
    {
        float value = BinaryPrimitives.ReadSingleBigEndian(_rest);
        _rest = _rest[4..];
        return value;
    }
}

type 42, sensor 12345, temperature 27, battery 500 mV
0 bytes left, and reading on: False
1,000,000 readers: 0 bytes allocated (sum 12387000000)

BinaryPrimitives read each value with its most significant byte first, the order network protocols use, and each read moved the span past what it had read. The million readers allocated nothing: every one was a struct on the stack, viewing the same array. Step through the reads:

Ref structs pay for this with rules that keep them on the stack, which the compiler enforces:

• no array of them, and no field of one in a class or in an ordinary struct;
• no boxing, so no conversion to object or to an interface they implement;
• no capture by a lambda or a local function;
• in an async method or an iterator, never alive across an await or a yield return (allowed at all since C# 13);
• as a type argument only where the type parameter says allows ref struct (also C# 13).

The rules grew version by version, as the C# version history records:

Ref fields and scoped say how far a reference may go

A ref fieldref field: A field declared with ref inside a ref struct, added in C# 11: it holds a reference to a variable rather than a value, so writes through it reach that variable. Span<T> is built on one. is a field that refers to a variable instead of holding a value, and only ref structs may declare one; Span<T> itself is built on a ref field. The scopedscoped: A modifier on a parameter or local of a ref struct type, or on a ref variable, which promises that the value does not leave the current method. The compiler checks the promise and lets callers pass shorter-lived memory. modifier works the other way round: it promises that a parameter or local does not leave the current method. scoped.cs uses both:

// A ref field refers to a variable of its creator, and scoped promises that a parameter does not escape.
int count = 0;
var counter = new Counter(ref count);
counter.Add();
counter.Add();
counter.Add();
Console.WriteLine($"count is {count} after three calls of counter.Add()");

var line = new LineBuilder(new char[64]); // a builder over a heap array, which may outlive this method's stack memory
Span<char> digits = stackalloc char[11];  // stack memory, gone when this method returns
41_250.TryFormat(digits, out int length);
line.Append("total: ");
line.Append(digits[..length]);            // allowed because Append's parameter is scoped
Console.WriteLine(line.ToString());

ref struct Counter
{
    private ref int _count; // a ref field (C# 11): another name for the caller's variable

    public Counter(ref int count) => _count = ref count;

    public void Add() => _count++;
}

ref struct LineBuilder(Span<char> buffer)
{
    private readonly Span<char> _buffer = buffer;
    private int _length;

    // scoped: Append promises not to keep text, so callers may pass memory that lives shorter than the builder.
    public void Append(scoped ReadOnlySpan<char> text)
    {
        text.CopyTo(_buffer[_length..]);
        _length += text.Length;
    }

    public override readonly string ToString() => _buffer[.._length].ToString();
}

count is 3 after three calls of counter.Add()
total: 41250

Counter keeps a ref field to the local count, so three calls of Add changed the local itself. LineBuilder writes into a heap array, and its caller wanted to append digits from stack memory. Without scoped on text, the compiler would have to assume that Append might keep the span inside the builder, which lives longer than the stack memory, and it would refuse the call. With scoped, Append promises not to keep it, the compiler checks that promise inside Append, and the call compiles.

The compiler reasons about how far each reference may travel, which the C# documentation calls its ref safe contextref safe context: How far a reference to a variable may travel: for a local, the block that declares it; for a ref or in parameter or a field of a class, back to the caller. A reference may be returned or stored only within it., and for a span or another ref struct value its safe context:

A reference may be returned or stored only where it cannot outlive what it refers to; every escape error is this one rule.

Escape errors reproduced, each with its fix Pro: opens with a Pro, Premium or Ultimate pass

ref returns, generics that accept ref structs, and a bit reader to build Pro: opens with a Pro, Premium or Ultimate pass

Practise

Test yourself on the rules of ref structs and on what ref fields and scoped change. The questions adapt to your answers, weakest idea first, and each one explains its right answer and every wrong one:

Interview questions

Fresher · What is a ref struct, and why can it not be boxed?

A ref struct is a struct declared with ref struct, such as Span<T>, whose instances may live only on the stack. That lets it hold references that would be unsafe on the heap: a span over stack memory, or a ref field to a local variable. Boxing would copy the value into an object on the heap, where it could outlive the memory it refers to, so the compiler forbids it, and with it every conversion to object or to an interface. For the same reason a ref struct cannot be a field of a class, an element of an array, captured by a lambda or kept across an await. Since C# 13 it can implement interfaces and be a type argument where the type parameter allows ref struct, but it is still never boxed.

Key takeaways

• Ref structs live only on the stack, so they can hold spans and ref fields, and the compiler forbids everything that could move them to the heap: boxing, class fields, arrays, lambda captures and locals alive across an await.
• A reader or builder over a span can be a ref struct and allocate nothing; a million readers in reader.cs allocated 0 bytes.
• Ref fields refer to a variable instead of holding a value, and the scoped modifier promises that a parameter does not leave the method, which lets callers pass stack memory.
• Every escape error is one rule: a reference may be returned or stored only where it cannot outlive what it refers to.