C# Reference ยท Keywords and Statements
The scoped modifier
Reference for the C# scoped modifier: restrict how far a ref, in, out or ref struct parameter or local can escape, so stackalloc spans and refs stay safe.
scoped is a modifier for ref, in, out parameters, for parameters and locals of a ref struct type (such as Span<T>), and for ref locals. It tells the compiler: "this value may be used inside the current method only; it will never be stored or returned." That promise lets the compiler accept calls that it would otherwise reject as unsafe.
Without it, the compiler has to assume that a method which receives a Span<int> might return it or save it somewhere. If the caller built that span from stackalloc, which dies when the caller returns, passing it could create a dangling reference. With scoped, the callee guarantees it will not leak the value, so the call is safe.
static int Sum(scoped ReadOnlySpan<int> values) { /* use values locally */ }
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with Console.ReadLine()), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with Console.ReadLine()), it gets the next line from this box.
What the compiler refuses. This snippet does not compile, because a scoped parameter may not be returned:
static ref int Id(scoped ref int x) => ref x; // error CS9075: Cannot return a parameter by reference 'x' because it is scoped to the current method
And this one does not compile, because Keep may return the span that points at local:
static Span<int> Bad() { Span<int> local = stackalloc int[4]; return Keep(local); } static Span<int> Keep(Span<int> s) => s; // error CS8352: Cannot use variable 'local' in this context because it may expose // referenced variables outside of their declaration scope
Syntax
void M(scoped ref T r); void M(scoped in T r); void M(scoped Span<T> s); // ref struct parameter scoped Span<int> local = ...; // ref struct local scoped ref int r = ref x; // ref local
| Where | Meaning |
|---|---|
| Parameter | The method will not return or store the parameter (or anything derived from it) beyond the call. |
| Local | The variable may not be assigned to anything with a wider scope, nor returned. |
out parameters |
out is already implicitly scoped; ref and in are not. |
Errors: returning or storing a scoped value gives CS8352, CS8347 or CS9075. scoped on a non-ref, non-ref struct parameter is error CS9048 ("The 'scoped' modifier can be used for refs and ref struct values only").
Usage notes
- The modifier was added in C# 11 together with the improved ref-safety rules. It is rarely needed in everyday code. You meet it mostly when writing low-level APIs over
Span<T>. - A
thisparameter in astructinstance method is implicitlyscoped ref, which is why a struct method cannot return arefto the struct itself. - A parameter marked
scopedalso lets callers pass arefto a local variable without the compiler worrying that it will escape. [UnscopedRef](fromSystem.Diagnostics.CodeAnalysis) does the opposite: it lifts the implicit scoping of anoutparameter or a structthis.- Declaring a
scopedlocal with astackallocinitializer is allowed and often unnecessary, sinceSpan<int> x = stackalloc int[n]already has a safe-to-escape scope of the current method. scopedhas no run-time effect. It only changes what the compiler accepts, so it cannot make code slower.