A hot C# method takes a large readonly struct Matrix; what changes when its parameter is declared in versus ref readonly?
answer
- both pass a readonly reference
- the difference is at the call site
- hidden temporaries for non-variables
- warnings CS9192 and CS9193
basics
~20 sBoth pass a read-only reference instead of copying the struct. An in parameter accepts any expression and quietly copies non-variables into a temporary; a ref readonly parameter expects a variable passed with in or ref and warns otherwise.
solid answer
~50 sBoth modifiers pass `Matrix` by **readonly reference**, so the call copies a reference instead of the struct and the method cannot assign the parameter (CS8331). They differ at the call site. An `in` argument needs no modifier, and a literal, a property value, a method result or an implicitly converted value is accepted by copying it into a hidden temporary. A `ref readonly` parameter (C# 12) says the method wants an actual variable: the caller writes `in m` or `ref m`, and gets warning CS9192 without a modifier and CS9193 for a non-variable. Use `in` for a pure performance parameter, and `ref readonly` when the reference itself matters, as in `ReadOnlySpan<T>(ref readonly T reference)`, or to migrate an old `ref` parameter that never writes. With a by-value overload beside either one, a call without a modifier binds to the by-value overload.
code
csharp · 24 linesvar m = new Matrix(1);
Calc.ByIn(m); // reference to m, no modifier needed
Calc.ByIn(new Matrix(2)); // not a variable: copied into a hidden temporary
Calc.ByIn(ref m); // warning CS9191: use 'in' instead
Calc.ByRefReadonly(in m); // reference to m
Calc.ByRefReadonly(ref m); // also fine: m is a writable variable
Calc.ByRefReadonly(m); // warning CS9192
Calc.ByRefReadonly(new Matrix(3)); // warning CS9193
Console.WriteLine(Calc.ByRefReadonly(in Calc.Identity)); // a readonly field takes 'in', not 'ref'
public readonly struct Matrix(double seed)
{
public readonly double M11 = seed, M12 = seed, M13 = seed, M14 = seed,
M21 = seed, M22 = seed, M23 = seed, M24 = seed;
}
public static class Calc
{
public static readonly Matrix Identity = new(1);
public static double ByIn(in Matrix x) => x.M11;
public static double ByRefReadonly(ref readonly Matrix x) => x.M22;
}go deeper
Recall that in and ref readonly both pass a struct by read-only reference to avoid a copy, and that the method cannot assign such a parameter.
Explain the call-site rules: in takes any expression through a hidden temporary, ref readonly wants a variable passed with in or ref and warns otherwise.
Judge when the saved copy is real, keep large structs readonly to avoid defensive copies, and remember the by-value overload wins calls without a modifier.
For a shared library, decide which hot APIs take in versus ref readonly and how to migrate legacy ref parameters without breaking compiled callers.
## Why pass a struct by reference at all A `struct` argument is normally **copied**: a 64-byte matrix passed by value costs a 64-byte copy on every call, which shows up in a tight loop over thousands of transforms. A **readonly reference** avoids the copy while promising the caller that the method will not change the argument. C# has two parameter modifiers for that, `in` and `ref readonly` (C# 12), and they differ mainly in what they demand of the caller. ## What the method sees: the same for both - The parameter is a **readonly alias** for the argument. Assigning it is error CS8331, *Cannot assign to variable because it is a readonly variable*. Reading fields and calling members is fine. - The alias is **live**, not a snapshot. If the method, something it calls or another thread writes the original variable during the call, reads through the parameter see the new value; only a by-value parameter is a true snapshot. - If the struct is **not** declared `readonly`, calling a member that is not marked `readonly` makes the compiler copy the struct first to protect the original, which can cost more than the by-value copy that was avoided; the struct lessons cover these defensive copies. Declaring `readonly struct Matrix` removes the issue. - Neither modifier is allowed in `async` methods or iterators (CS1988, CS1623). ## Where they differ: the call site | Argument written as | `in Matrix x` | `ref readonly Matrix x` | |---|---|---| | `Run(m)`, a variable, no modifier | passes a reference to `m` | warning CS9192, still a reference | | `Run(in m)` | passes a reference to `m` | passes a reference to `m` | | `Run(ref m)` | warning CS9191, use `in` | passes a reference; `m` must be writable | | `Run(new Matrix(2))`, a property or a literal | hidden temporary, no diagnostic | warning CS9193, hidden temporary | | `Run(in new Matrix(2))` | error CS8156 | error CS8156 | | `Run(ref Calc.Identity)`, a `static readonly` field | error CS0199 | error CS0199; write `in` instead | Two notes on the table. `ref readonly` is never written at the call site; the caller chooses `in` or `ref`. And the CS9191 row is a C# 12 change: before it, a `ref` argument for an `in` parameter was an error, and under `LangVersion` 11 the SDK 10.0.401 compiler still reports CS9194 for it. The **hidden temporary** is the important behavioural difference. For an `in` parameter the compiler silently stores any non-variable argument in a temporary local and passes a reference to that, which is convenient for a math helper but wrong for an API that keeps or returns the reference, because the temporary is not a variable the caller can see or keep. `ref readonly` exists for those APIs: the warnings tell the caller that the method wants a real variable. ## Overloads with a by-value twin When a type declares both `Run(Matrix x)` and `Run(in Matrix x)`, a call written `Run(m)` binds to the **by-value** overload; only `Run(in m)` picks the `in` one. The same holds for a `ref readonly` overload. Adding an `in` overload next to an existing by-value method therefore speeds up nothing until callers add the modifier. ## Choosing the modifier 1. **Small structs**: pass by value. The C# documentation notes there is no benefit in passing an `int` by readonly reference, and for any small struct the copy is cheap enough that by value stays the sensible default. 2. **Large readonly structs on hot paths**: `in`. Callers need no changes, temporaries are acceptable, and the struct being `readonly` keeps defensive copies away. 3. **APIs that keep, return or compare the reference**: `ref readonly`. The runtime's own `ReadOnlySpan<T>(ref readonly T reference)` constructor and `Unsafe.IsNullRef<T>(ref readonly T source)` are declared this way, because a temporary would make no sense to them. 4. **Migrating an old `ref` parameter that never writes**: `ref readonly`. The C# design notes for the feature describe `ref` to `ref readonly` as a binary break only for virtual methods, and `in` to `ref readonly` as non-breaking apart from new warnings for current compilers. Measure before and after: the copy saved is real only when the struct is large and the call is hot.
- If the method only reads an in parameter, can the struct still be copied?Yes, in two places. The caller copies when the argument is not a variable or needs an implicit conversion, into a hidden temporary. Inside the method, calling a member that is not `readonly` on a struct that is not `readonly` makes the compiler copy it first to protect the original. A `readonly struct` and variable arguments avoid both.
- Does an in parameter guarantee that the value cannot change during the call?No. It only stops the method from writing through the parameter. The parameter is a live reference, so if the method, a method it calls or another thread writes the original variable, reads through the parameter see the new value. Only a by-value parameter gives the method a snapshot.
- Is changing a published method's parameter from in to ref readonly a breaking change?Not for callers compiled with C# 12 or later: the design notes for `ref readonly` parameters describe it as non-breaking, with new CS9192 or CS9193 warnings at calls that pass no modifier or a non-variable. The same notes flag older compilers and `LangVersion` 11, which treat the parameter like `ref` and reject those calls.
- An in parameter gives the method a private copy, so outside writes cannot affect it.
- At the call site a ref readonly argument is written as ref readonly m.
- Passing a literal or a property value to an in parameter is a compile error.
- Adding an in overload next to a by-value one speeds up existing calls automatically.
- in is always faster than passing by value, whatever the struct's size.
Assumes C# 14; ref readonly parameters arrived in C# 12, which also turned a ref argument for an in parameter from an error into warning CS9191.