C# Fixed Buffer Struct: Unsafe

Fixed buffers are used in unsafe code. The fixed modifier can be used to describe a buffer of constant size in an unsafe context in a struct. You can use this memory then as an array after you ensure it is in an unmovable memory location. This can be useful for interoperation—and sometimes performance.

This C# example program uses a fixed buffer. It requires an unsafe context.

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.

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

Program that uses fixed buffer and unsafe context [C#]

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

Overview. This program uses the fixed keyword in three lines, and the keyword has two different 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. The fixed statement (followed by a parenthetical assignment statement) changes the memory model of a variable so it can be manipulated with pointers, ensuring the memory is unmovable.

Ensure umoveable memory. The fixed buffer itself is persistent in memory during the program's execution and is always allocated. However, when using the fixed buffer in C# methods, you must fix the memory location so that the garbage collector cannot move it when you are using it. The int* type (pointer to integer variable) is assigned to the integer buffer field in the statements.

Program results. What this program does is simply use a fixed buffer as a field in an unsafe struct, and uses a static reference to this struct type in the Program class as a field. It then uses a fixed context to assign three values to the memory, and then uses another fixed context to read those three values back in. This code can be adapted for usage for persistent memory for unsafe operations.

Performance

Although the fixed buffer eliminates the possibility of requiring many array bounds checks, the overhead of changing the memory to an unmovable address can actually hurt performance. Theoretically, the fixed buffer will improve performance on long-running computations; if you have a method called many times, the pinning overhead may outweigh the benefits.

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

Summary

We described the usage of a fixed buffer field of primitive type elements in a struct in the C# language. You must specify the unsafe context to use a fixed buffer, and whenever you access the fixed buffer you must declare the memory as unmovable. This approach does not always improve performance and in most cases results in less readable code.