Edit

Share via

ref structure types (C# reference)

  • Article

You can use the ref modifier in the declaration of a structure type. Instances of a ref struct type are allocated on the stack and can't escape to the managed heap. To ensure that, the compiler limits the usage of ref struct types as follows:

  • A ref struct can't be the element type of an array.
  • A ref struct can't be a declared type of a field of a class or a non-ref struct.
  • A ref struct can't implement interfaces.
  • A ref struct can't be boxed to System.ValueType or System.Object.
  • A ref struct can't be a type argument.
  • A ref struct variable can't be captured in a lambda expression or a local function.
  • Before C# 13,ref struct variables can't be used in an async method. Beginning with C# 13, a ref struct variable can't be used in the same block as the await expression in an async method. However, you can use ref struct variables in synchronous methods, for example, in methods that return Task or Task<TResult>.
  • Before C# 13, a ref struct variable can't be used in iterators. Beginning with C# 13, ref struct types and ref locals can be used in iterators, provided they aren't in code segments with the yield return statement.

You can define a disposable ref struct. To do that, ensure that a ref struct fits the disposable pattern. That is, it has an instance Dispose method, which is accessible, parameterless and has a void return type. You can use the using statement or declaration with an instance of a disposable ref struct.

Typically, you define a ref struct type when you need a type that also includes data members of ref struct types:

public ref struct CustomRef
{
    public bool IsValid;
    public Span<int> Inputs;
    public Span<int> Outputs;
}

To declare a ref struct as readonly, combine the readonly and ref modifiers in the type declaration (the readonly modifier must come before the ref modifier):

public readonly ref struct ConversionRequest
{
    public ConversionRequest(double rate, ReadOnlySpan<double> values)
    {
        Rate = rate;
        Values = values;
    }

    public double Rate { get; }
    public ReadOnlySpan<double> Values { get; }
}

In .NET, examples of a ref struct are System.Span<T> and System.ReadOnlySpan<T>.

ref fields

Beginning with C# 11, you can declare a ref field in a ref struct, as the following example shows:

public ref struct RefFieldExample
{
    private ref int number;

    public int GetNumber()
    {
        if (System.Runtime.CompilerServices.Unsafe.IsNullRef(ref number))
        {
            throw new InvalidOperationException("The number ref field is not initialized.");
        }

        return number;
    }
}

A ref field can have the null value. Use the Unsafe.IsNullRef<T>(T) method to determine if a ref field is null.

You can apply the readonly modifier to a ref field in the following ways:

  • readonly ref: You can ref reassign such a field with the = ref operator only inside a constructor or an init accessor. You can assign a value with the = operator at any point allowed by the field access modifier.
  • ref readonly: At any point, you can't assign a value with the = operator to such a field. However, you can ref reassign a field with the = ref operator.
  • readonly ref readonly: You can only ref reassign such a field in a constructor or an init accessor. At any point, you can't assign a value to the field.

The compiler ensures that a reference stored in a ref field doesn't outlive its referent.

The ref fields feature enables a safe implementation of types like System.Span<T>:

public readonly ref struct Span<T>
{
    internal readonly ref T _reference;
    private readonly int _length;

    // Omitted for brevity...
}

The Span<T> type stores a reference through which it accesses the contiguous elements in memory. The use of a reference enables a Span<T> instance to avoid copying the storage it refers to.

C# language specification

For more information, see the following sections of the C# language specification:

For more information about ref fields, see the Low-level struct improvements proposal note.

See also