[API Proposal]: Add managed API surface area for ByRefLike Generic constraints

[AaronRobinsonMSFT]

Background and motivation

The design for ByRefLike Generic constraints requires some new API surface area. Specifically the need to represent the new metadata values and a new feature flag to indicate support for the compiler.

API Proposal

Metadata enum values:

namespace System.Reflection
{
    [Flags]
    public enum GenericParameterAttributes
    {
+        [Obsolete("No longer represents all special constraints")]
         SpecialConstraintMask = 0x001C,
+        AcceptByRefLike = 0x0020,
    }
}

Feature flag.

namespace System.Runtime.CompilerServices
{
    public static partial class RuntimeFeature
    {
+        /// <summary>
+        /// Represents a runtime feature where byref-like types can be used in Generic parameters.
+        /// </summary>
+        public const string GenericsAcceptByRefLike = nameof(GenericsAcceptByRefLike);
    }
}

API Usage

Usage is similar to the official documentation for any of the existing GenericParameterAttributes enumeration values.

Alternative Designs

The following would represent a binary breaking change.

namespace System.Reflection
{
    [Flags]
    public enum GenericParameterAttributes
    {
-        SpecialConstraintMask = 0x001C,
+        SpecialConstraintMask = 0x003C,
+        AcceptByRefLike = 0x0020,
    }
}

Risks

Updating the enumeration value is troublesome since it contains a value that is a mask—an established anti-pattern. The "safest" way to handle this is the initial proposal but that does introduce confusion about new scenarios. It might be prudent to create a new API for accessing the specific constraints from the variance values.

[ghost]

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

Issue Details

---

Background and motivation

The design for ByRefLike Generic constraints requires some new API surface area. Specifically the need to represent the new metadata values and a new feature flag to indicate support for the compiler.

API Proposal

Metadata enum values:

namespace System.Reflection
{
    [Flags]
    public enum GenericParameterAttributes
    {
+        [Obsolete("No longer represents all special constraints")]
         SpecialConstraintMask = 0x001C,
+        AcceptByRefLike = 0x0020,
    }
}

Feature flag:

namespace System.Runtime.CompilerServices
{
    public static partial class RuntimeFeature
    {
+        /// <summary>
+        /// Represents a runtime feature where byref-like types can be used in Generic parameters.
+        /// </summary>
+        public const string GenericsAcceptByRefLike = nameof(GenericsAcceptByRefLike);
    }
}

API Usage

Usage is similar to the official documentation for any of the existing GenericParameterAttributes enumeration values.

Alternative Designs

The following would represent a binary breaking change.

namespace System.Reflection
{
    [Flags]
    public enum GenericParameterAttributes
    {
-        SpecialConstraintMask = 0x001C,
+        SpecialConstraintMask = 0x003C,
+        AcceptByRefLike = 0x0020,
    }
}

Risks

Updating the enumeration value is troublesome since it contains a value that is a mask—an established anti-pattern. The "safest" way to handle this is the initial proposal but that does introduce confusion about new scenarios. It might be prudent to create a new API for accessing the specific constraints from the variance values.

Author:	AaronRobinsonMSFT
Assignees:	-
Labels:	api-suggestion, area-System.Reflection.Metadata
Milestone:	7.0.0

[AaronRobinsonMSFT]

/cc @cston @RikkiGibson @jaredpar @davidwrighton @ericstj

[steveharter]

Todo for v7: review above and have a plan forward for V8.

[steveharter]

@AaronRobinsonMSFT I prefer the original proposal is fine with obsoleting SpecialConstraintMask.

Is this ready for review? Is there any newer information that would affect this proposal?

[AaronRobinsonMSFT]

@AaronRobinsonMSFT I prefer the original proposal is fine with obsoleting SpecialConstraintMask.

I prefer obsoleting as well.

Is this ready for review? Is there any newer information that would affect this proposal?

It is ready for review, but since we are deferring till .NET 8 and we still have language design discussion I'm not in any hurry to move this forward as it may change. I could see fallout from the language design influencing this in subtle ways so think we can hold off.

[steveharter]

@AaronRobinsonMSFT should this be moved to v9?

[AaronRobinsonMSFT]

Yep. Done.

[jaredpar]

@AlekseyTs

[bartonjs]

Video

• We decided not to obsolete SpecialConstraintMask, which we can revisit later.
• "AcceptByRefLike" => "AllowByRefLike"
• GenericsAllowByRefLike => ByRefLikeGenerics, to follow the pattern from ByRefFields

namespace System.Reflection
{
    [Flags]
    public enum GenericParameterAttributes
    {
         SpecialConstraintMask = 0x001C,
+        AllowByRefLike = 0x0020,
    }
}

namespace System.Runtime.CompilerServices
{
    public static partial class RuntimeFeature
    {
+        /// <summary>
+        /// Represents a runtime feature where byref-like types can be used in Generic parameters.
+        /// </summary>
+        public const string ByRefLikeGenerics = nameof(ByRefLikeGenerics);
    }
}