[API Proposal]: System.Diagnostics.CodeAnalysis.UnscopedRefAttribute

[cston]

Background and motivation

There are several cases where the C# compiler treats a ref as implicitly scoped, where the compiler does not allow the ref to escape the method.

1. this for struct instance methods
2. ref parameters that refer to ref struct types
3. out parameters

For specific instances where the ref should be allowed to escape, we should provide a well-known attribute that the compiler will recognize that indicates the ref is not scoped.

See low-level-struct-improvements.md.

API Proposal

namespace System.Diagnostics.CodeAnalysis
{
    [AttributeUsage(
        AttributeTargets.Struct | AttributeTargets.Method | AttributeTargets.Property | AttributeTargets.Parameter,
        AllowMultiple = false,
        Inherited = false)]
    public sealed class RefEscapesAttribute : Attribute
    {
    }
}

API Usage

When applied to struct instance methods and properties, this ref is unscoped.

struct S1
{
    private int _field;
    [RefEscapes] public ref int Property => ref _field; // ok
    [RefEscapes] public ref int GetField() => ref _field; // ok
}

When applied to a struct type, this ref is unscoped for all instance methods and properties.

[RefEscapes]
struct S2
{
    private int _field;
    public ref int Property => ref _field; // ok
    public ref int GetField() => ref _field; // ok
}

[RefEscapes]
struct S3
{
    private S2 _child;
    public ref int Value => ref _child.Property; // ok
}

When applied to a ref parameter, the ref is unscoped.

ref struct R { }

ref R ReturnRefStructRef(bool b, ref R x, [RefEscapes] ref R y)
{
    if (b)
        return ref x; // error: Cannot return parameter by reference
    else
        return ref y; // ok
}

When applied to an out parameter, the ref is unscoped.

ref int ReturnOut(bool b, out int x, [RefEscapes] out int y)
{
    x = 1;
    y = 2;
    if (b)
        return ref x; // error: Cannot return parameter by reference
    else
        return ref y; // ok
}

Alternative Designs

Without a well-known attribute recognized by the compiler, callers will need to use Unsafe.AsRef() and similar methods to return a scoped ref.

An alternative attribute name: UnscopedAttribute.

Risks

No response

Tagging subscribers to this area: @dotnet/area-system-runtime-compilerservices
See info in area-owners.md if you want to be subscribed.

Issue Details

---

Background and motivation

There are several cases where the C# compiler treats a ref as implicitly scoped, where the compiler does not allow the ref to escape the method.

1. this for struct instance methods
2. ref parameters that refer to ref struct types
3. out parameters

For specific instances where the ref should be allowed to escape, we should provide a well-known attribute that the compiler will recognize that indicates the ref is not scoped.

See low-level-struct-improvements.md.

API Proposal

namespace System.Diagnostics.CodeAnalysis
{
    [AttributeUsage(
        AttributeTargets.Struct | AttributeTargets.Method | AttributeTargets.Property | AttributeTargets.Parameter,
        AllowMultiple = false,
        Inherited = false)]
    public sealed class RefEscapesAttribute : Attribute
    {
    }
}

API Usage

When applied to struct instance methods and properties, this ref is unscoped.

struct S1
{
    private int _field;
    [RefEscapes] public ref int Property => ref _field; // ok
    [RefEscapes] public ref int GetField() => ref _field; // ok
}

When applied to a struct type, this ref is unscoped for all instance methods and properties.

[RefEscapes]
struct S2
{
    private int _field;
    public ref int Property => ref _field; // ok
    public ref int GetField() => ref _field; // ok
}

[RefEscapes]
struct S3
{
    private S2 _child;
    public ref int Value => ref _child.Property; // ok
}

When applied to a ref parameter, the ref is unscoped.

ref struct R { }

ref R ReturnRefStructRef(bool b, ref R x, [RefEscapes] ref R y)
{
    if (b)
        return ref x; // error: Cannot return parameter by reference
    else
        return ref y; // ok
}

When applied to an out parameter, the ref is unscoped.

ref int ReturnOut(bool b, out int x, [RefEscapes] out int y)
{
    x = 1;
    y = 2;
    if (b)
        return ref x; // error: Cannot return parameter by reference
    else
        return ref y; // ok
}

Alternative Designs

Without a well-known attribute recognized by the compiler, callers will need to use Unsafe.AsRef() and similar methods to return a scoped ref.

An alternative attribute name: UnscopedAttribute.

Risks

No response

Author:	cston
Assignees:	-
Labels:	api-suggestion, area-System.Runtime.CompilerServices
Milestone:	-

[cston]

cc @jaredpar, @AaronRobinsonMSFT

[AaronRobinsonMSFT]

@cston Is this expected for .NET 8 or do we need it for .NET 7?

[Sergio0694]

Why is the attribute needed here:

ref struct R { }

ref R ReturnRefStructRef(bool b, ref R x, [RefEscapes] ref R y)
{
    if (b)
        return ref x; // error: Cannot return parameter by reference
    else
        return ref y; // ok
}

Wouldn't those refs all be escaping, and in order to get only the second one to be so, the first should be marked as scoped ref instead? 🤔

[stephentoub]

@cston, is this instead of the proposed "unscoped" keyword?

[cston]

@Sergio0694, it's likely that ref parameters to ref struct types will be considered implicitly scoped ref.

[cston]

@stephentoub, yes, this attribute is instead of the proposed unscoped keyword.

[cston]

@AaronRobinsonMSFT, we should add this in .NET 7 if possible.

The attribute will be especially important after the compiler has been updated to treat ref parameters to ref struct types as scoped ref.

[Sergio0694]

"it's likely that ref parameters to ref struct types will be considered implicitly scoped ref."

Q: wouldn't that make it harder to read and understand code, if the scope of refs will now depend on how the type itself is defined rather than just what's visible at the parameter declaration? As in, I can no longer just see whether I'm taking a ref or a scoped ref, but now I have to CTRL + click on that type to double check whether it's a struct or a ref struct to understand whether that ref has been secretly downgraded to a scoped ref. Not sure I like that change, personally 🥲

"yes, this attribute is instead of the proposed unscoped keyword."

Just so I understand, this is only so that we can enable this in C# 11 already by manually using the attribute (and allow people to escape fields by ref), while language support isn't there yet, but the plan is still to eventually get unscoped in C# 12, right?