Flow-Sensitive Consumption Tracking for ref struct

[xtofs]

Proposal: Flow-Sensitive Consumption Tracking for ref struct

Abstract

This proposal introduces a [MustConsume] attribute and a companion
[Consumes] attribute that together enable the compiler to perform
flow-sensitive tracking of whether a ref struct value has been
consumed. A value of a type marked [MustConsume] must be passed to
exactly one method parameter marked [Consumes] before it goes out of
scope. Violations are reported as diagnostics — warnings by default,
errors on opt-in — with no change to code generation or the runtime.

The mechanism is purely a compiler flow analysis extension, in the
same spirit as nullable reference types (string?) and definite
assignment. It requires no new IL, no runtime support, and no changes to
the GC. It applies exclusively to ref struct types, where the GC is
already uninvolved.

---

Motivation

1. Resource safety

C# already has IDisposable and the using statement to encourage
correct resource cleanup. However, both are opt-in at the call site:
nothing prevents a caller from simply not participating. The type author
has no way to declare "every caller must close this" and have the
compiler enforce it universally.

This means nothing in the language today prevents:

var handle = OpenFile("data.txt");
ReadLine(handle);
Close(handle);
ReadLine(handle);   // use after close — silent bug
Close(handle);      // double close — silent bug

For ref struct resources specifically — file handles, native memory
handles, cryptographic contexts — the GC is not involved at all, which
means there is no safety net whatsoever. A ref struct that wraps a
native resource can be silently abandoned or double-closed with no
diagnostic.

This proposal lets the type author declare the invariant once, at the
declaration site, and have the compiler enforce it at every call site
automatically.

2. Typestate / protocol enforcement

The typestate pattern uses phantom type parameters to encode the current
state of an object, making invalid method calls a compile-time error.
For example, a query builder that requires Select before Where.

However, typestate in C# today has a critical gap: the old state
reference remains live after a transition, so stale use is not prevented:

var b = QueryBuilder<Empty>.Create();
var b2 = b.Select("id");   // b2 : QueryBuilder<Selected>
b.Where("x > 1");          // ✅ compiles — b was not consumed

Consumption tracking closes this gap. After Select consumes b, any
further use of b is a diagnostic.

These two cases — resource safety and protocol enforcement — are
instances of the same underlying need: a value that must be handed off
exactly once.

---

Proposal

Attributes

namespace System.Diagnostics.CodeAnalysis;

/// <summary>
/// Applied to a ref struct type: every local of this type must be
/// passed to a [Consumes] parameter before it goes out of scope.
/// </summary>
[AttributeUsage(AttributeTargets.Struct)]
public sealed class MustConsumeAttribute : Attribute { }

/// <summary>
/// Applied to a ref struct parameter: passing a value to this parameter
/// transfers ownership and counts as consuming it for the purposes of
/// [MustConsume] tracking.
/// </summary>
[AttributeUsage(AttributeTargets.Parameter)]
public sealed class ConsumesAttribute : Attribute { }

Borrowing vs consuming

A method that accepts a [MustConsume] ref struct without marking the
parameter [Consumes] is a borrow: the caller retains ownership and
the value remains live after the call. Only a [Consumes] parameter
transfers ownership.

This distinction is intentional and important: a method like ReadLine
can be called many times on the same handle — each call borrows it. Only
Close takes ownership. The presence or absence of [Consumes] on the
parameter is how the method author declares which contract applies.

A future [Borrows] attribute could make borrows explicit rather than
implicit, but that is left to a later discussion.

Compiler flow analysis

The compiler extends its existing flow state for local variables with a
third state alongside assigned and unassigned:

State	Meaning
Unassigned	Variable declared but not yet assigned
Assigned	Variable holds a live, unconsumed value
Consumed	Variable was passed to a [Consumes] parameter

Transitions:

• Assigned → Consumed: when the variable is passed to a [Consumes]
  parameter.
• Consumed → (any use): diagnostic —
  "Variable 'x' has already been consumed."
• Assigned, goes out of scope without being consumed: diagnostic —
  "Variable 'x' of type T (marked [MustConsume]) was not consumed."

Example: resource safety

[MustConsume]
ref struct FileHandle { /* wraps a native handle */ }

FileHandle OpenFile(string path) { ... }
string     ReadLine(FileHandle handle) { ... }        // borrow — no [Consumes]
void       Close([Consumes] FileHandle handle) { ... } // transfer — consumes

// ✅ correct: borrow multiple times, then consume once
var handle = OpenFile("data.txt");
var line1 = ReadLine(handle);   // borrow, handle still live
var line2 = ReadLine(handle);   // borrow again, handle still live
Close(handle);                  // consumed here

// ❌ use after consume
var handle2 = OpenFile("data.txt");
Close(handle2);
ReadLine(handle2);   // diagnostic: 'handle2' has already been consumed

// ❌ not consumed before going out of scope
{
    var handle3 = OpenFile("data.txt");
}  // diagnostic: 'handle3' was not consumed

Example: typestate / protocol enforcement

[MustConsume]
ref struct QueryBuilder<S> { ... }

QueryBuilder<Empty>    Create() { ... }
QueryBuilder<Selected> Select([Consumes] QueryBuilder<Empty> b,
                               string field) { ... }
QueryBuilder<Filtered> Where([Consumes] QueryBuilder<Selected> b,
                              string cond) { ... }
Query                  Build([Consumes] QueryBuilder<Selected> b) { ... }

// ✅ correct
var b = Create();
var b2 = Select(b, "id");
var result = Build(b2);

// ❌ stale use — b was consumed by Select
var b3 = Create();
var b4 = Select(b3, "id");
Select(b3, "name");   // diagnostic: 'b3' has already been consumed

// ❌ wrong protocol order — caught by existing typestate (type mismatch)
var b5 = Create();
Build(b5);            // existing error: QueryBuilder<Empty> is not QueryBuilder<Selected>

The two mechanisms are complementary: the phantom type parameter
prevents wrong-order calls; consumption tracking prevents stale use of
a superseded state.

---

Relationship to existing features

Nullable reference types

The closest precedent. Nullable reference types added a flow-sensitive
"maybe null" / "not null" state to the compiler with:

• no IL or runtime changes
• warnings by default, errors on opt-in (<Nullable>enable</Nullable>)
• no effect on code that doesn't opt in

This proposal follows the same pattern exactly, adding a "consumed"
state to the flow graph for ref struct locals.

Definite assignment

The compiler already tracks "assigned" vs "unassigned" for all locals
and reports use of unassigned variables. "Consumed" is a natural third
state in the same framework, symmetric with "unassigned" at the other
end of a value's life.

ref struct and the GC

ref struct values cannot be boxed, cannot be stored in heap fields,
and cannot contain managed references. They are entirely invisible to
the GC. This is precisely why consumption tracking is both safe and
self-contained for this type category: there is no aliasing through the
heap, no finalizer safety net, and no GC involvement to reason about.
The compiler has complete visibility into the lifetime of every
ref struct local.

scoped and lifetime annotations

C# 11 introduced scoped to restrict the escape of a ref struct
value. This proposal is orthogonal: scoped restricts where a value
can go spatially (can't escape the current method); [MustConsume]
restricts how many times it can be used temporally (must be handed off
exactly once).

[DoesNotReturn], [NotNull], [MaybeNull]

The System.Diagnostics.CodeAnalysis namespace already contains
attributes that the compiler treats as semantic modifiers affecting flow
analysis. [MustConsume] and [Consumes] are a natural addition to
this family.

---

What this proposal does not address

• Classes and ordinary structs: consumption tracking applies only to
  ref struct. Extending it to heap-allocated types would require
  reasoning about aliasing through the heap, which is a substantially
  harder problem.
• Branching and conditionals: where a value is consumed on one
  branch but not another, the compiler should report a diagnostic. The
  exact rules follow the same conventions as definite assignment: a
  value is considered consumed after a branch only if it is consumed on
  all paths.
• Full linear types: this proposal gives affine semantics (at most
  once) combined with a must-consume requirement (at least once),
  yielding exactly-once for [MustConsume] values. It does not provide
  general linear types for arbitrary heap-allocated objects.
• Keyword syntax: [Consumes] could in a future version be surfaced
  as a parameter modifier keyword (e.g. consume FileHandle handle),
  as has been done for [In]/in and [Out]/out. This is left to
  an implementation discussion.

---

Open questions

1. Severity: should violations be warnings (like nullable) or errors
   (like definite assignment)? The nullable precedent suggests warnings
   with opt-in errors, which allows incremental adoption.

2. Conditional consumption: should a [Consumes] parameter on a
   method that throws still count as consumed at the call site? The
   conservative answer is yes — the value is transferred before the
   callee executes, so the caller no longer owns it regardless of
   whether the callee throws.

3. out parameters: should a method be able to return a
   [MustConsume] value via an out parameter, transferring ownership
   to the caller?

4. Interop with using: should the compiler recognize
   using var h = OpenFile(...) as an implicit consume at the end of
   the using block, satisfying the must-consume requirement
   automatically?

---

References

• Nullable reference types (C# 8)
• Low-level struct improvements (C# 11)
• Discussion #4808: Struct-based RAII
• Discussion #7620: Move semantics for IDisposable
• Wadler, P. Linear Types can Change the World (1990)
• Matsakis, N. The Rust Programming Language, ch. 4: Ownership
• Swift Evolution: consuming and borrowing parameter modifiers (SE-0377)

[CyrusNajmabadi]

This doesn't appear to be a language suggestion. Attributes, with associated analysis rules, have been supported in the Roslyn compiler for over a decade. So the above can already be implemented without any additional support needed.

[CyrusNajmabadi]

The OP is probably looking for a good place where to make this suggestion.

I'm not certain why this needs a good place. The facilities for this already exist. This is what we designed analyzers (and long before that, attributes) to be used for.

but also that means it wont play with any other source generators

Of course it will. There's nothing about this that wouldn't play well with source generators.

or be supported by libraries.

I don't see why that's the case at all. If this is popular and useful, libraries can use it. If not... c'est la vie.

but practically useless in reality.

I don't see why that's the case at all.

[franchyd]

but also that means it wont play with any other source generators

Of course it will. There's nothing about this that wouldn't play well with source generators.

This is fair, I suppose Analyzers aren't hit by the SG dependency problem.

or be supported by libraries.

I don't see why that's the case at all. If this is popular and useful, libraries can use it. If not... c'est la vie.

A chicken and egg problem. How can it become popular without library support, why would libraries support it if its not popular.

but practically useless in reality.

I don't see why that's the case at all.

I'm not sure this particular flow analysis at a language level is a good idea or not. But practically, flow analysis features would only be possible with bottom-up support for similar reasons as why nullability analysis needed to be bottom up support. Because the moment you hit an external function that doesn't support it, it stops being useful.

[CyrusNajmabadi]

How can it become popular

By being useful. If it it is useful it will be picked up.

But practically, flow analysis features would only be possible with bottom-up support for similar reasons as why nullability analysis needed to be bottom up support.

Nullability analysis needs bottom up support because it has special syntax controlling it. That's not the case here. This is literally just attributes and analyzers.

[xtofs]

Technically this might be possible to implement it as an Analyzer. (I will try it.)
But I see this proposal as an enhancement to the type system and somewhat on the level of introducing nullable reference types.
nullable reference types required a language change (the ?) in addition to attributes the compiler understands. Here there is no language change.

From the implementation perspective I currently believe this proposal would be a change in the compiler's flow analysis and a Roslyn analyzer would need to implement flow analysis from scratch.

[xtofs]

Well, i just learned that ControlFlowGraph is a public class in Roslyn https://learn.microsoft.com/en-us/dotnet/api/microsoft.codeanalysis.flowanalysis.controlflowgraph?view=roslyn-dotnet-5.0.0
So I am definitely going to build a prototype.