C# Fixed Buffer Struct: Unsafe

Fixed buffers are used in unsafe code.

The fixed modifier describes a buffer of constant size in an unsafe context in a struct. We then use this memory as an array after we ensure it is in an unmovable memory location.

Tip: Fixed buffers are useful for interoperation with other programs—and sometimes performance.

Example. First this program demonstrates how you can use a fixed buffer type field. Fixed buffers are fields described with the fixed keyword and they can only be found in structs and must be in unsafe contexts.

Struct

The size of the fixed buffer must be constant—you can use a constant expression. The program uses a static struct reference containing a fixed buffer of integers. It reads and writes values to this memory using unsafe code and pointers.

Static

C# program that uses fixed buffer and unsafe context

using System;

unsafe struct FixedBufferExample
{
    public fixed int _buffer[1024]; // This is a fixed buffer.
}

class Program
{
    static FixedBufferExample _fixedBufferExample; // Reference to struct.

    static void Main()
    {
	// Store values in the fixed buffer.
	// ... The load the values from the fixed buffer.
	Store();
	Load();
    }

    unsafe static void Store()
    {
	// Put the fixed buffer in unmovable memory.
	// ... Then assign some elements.
	fixed (int* buffer = _fixedBufferExample._buffer)
	{
	    buffer[0] = 1;
	    buffer[99] = 2;
	    buffer[1023] = 3;
	}
    }

    unsafe static void Load()
    {
	// Put in unmovable memory.
	// ... Then load some values from the memory.
	fixed (int* buffer = _fixedBufferExample._buffer)
	{
	    Console.WriteLine(buffer[0]);
	    Console.WriteLine(buffer[99]);
	    Console.WriteLine(buffer[1023]);
	}
    }
}

Output

1
2
3

This program uses the fixed keyword in three lines. The keyword has two meanings. When you use the fixed modifier as a field, you are describing a fixed buffer. A fixed buffer can only appear in an unsafe struct.

Tip: The fixed-statement changes the memory model of a variable so it can be manipulated with pointers, ensuring the memory is unmovable.

Ensure unmovable memory. The fixed buffer itself is persistent in memory. It is always allocated. But when using the fixed buffer in C# methods, you must fix the memory location so that the garbage collector cannot move it.

Note: The int* type (pointer to integer variable) is assigned to the integer buffer field in the statements.

We use a fixed buffer as a field in an unsafe struct. It also uses a static reference to this struct type as a field. It uses a fixed context to assign three values to the memory, and read in again those three values.

And: This code can be adapted for usage for persistent memory for unsafe operations.

Performance. The fixed buffer eliminates the need of many array bounds checks. But the overhead of changing the memory to an unmovable address often hurts performance. In theory, a fixed buffer could be faster on long-running computations.

Tip: As always, when improving performance, please set up benchmarks and only accept changes that result in an improvement.

Benchmark

Summary. We described the usage of a fixed buffer field of primitive type elements in a struct. You must specify the unsafe context to use a fixed buffer. Whenever you access the fixed buffer you must declare the memory as unmovable.

But: This approach does not always improve performance and in most cases results in less readable code.

Related Links