Skip to content

Document ECMA-335 augment III.1.7.7 recognition for UnscopedRefAttribute and RefSafetyRulesAttribute #12902

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
Copilot wants to merge 3 commits into
base: main
Choose a base branch
from
+21 −2
Draft

Document ECMA-335 augment III.1.7.7 recognition for UnscopedRefAttribute and RefSafetyRulesAttribute #12902

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
494c89e
Document ECMA-335 augment III.1.7.7 recognition for ref attributes
Copilot Jul 24, 2026
0001584
Refine dynamic IL note; UnscopedRef depends on RefSafetyRules on module
Copilot Jul 24, 2026
df930d7
Drop claim that tools must emit RefSafetyRulesAttribute
Copilot Jul 24, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 10 additions & 1 deletion xml/System.Diagnostics.CodeAnalysis/UnscopedRefAttribute.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -37,7 +37,16 @@
<see langword="out" /> parameters.</li>
</ol>
<para> This attribute is used in those instances where the <see langword="ref" /> should be allowed to escape.</para>
<para> Applying this attribute, in any form, has impact on consumers of the applicable API. It is necessary for API authors to understand the lifetime implications of applying this attribute and how it may impact their users.</para>
<para> Applying this attribute, in any form, has impact on consumers of the applicable API. It's necessary for API authors to understand the lifetime implications of applying this attribute and how it might impact their users.</para>
<format type="text/markdown"><![CDATA[

## Remarks

This attribute is specially recognized by the runtime. ECMA-335 augment III.1.7.7 defines restrictions on valid IL that reference this attribute. For example, when this attribute is applied to an instance method of a value type, the `this` argument is allowed to escape the method. When the attribute is absent, an optimizing compiler can rely on `this` not escaping to further optimize certain code patterns, such as eliminating boxing. For more information, see the [ECMA-335 CLI Specification Addendum](https://github.com/dotnet/runtime/blob/main/docs/design/specs/Ecma-335-Augments.md#iii177-opt-in-restrictions), Sec. III.1.7.7 ("Opt-in restrictions").

Because the runtime relies on this attribute, it can't be stripped from an assembly. The restrictions defined by augment III.1.7.7 apply only when the <xref:System.Runtime.CompilerServices.RefSafetyRulesAttribute> is present on the module, so this attribute has its documented effect only in a module that's also annotated with `RefSafetyRulesAttribute`.

]]></format>
</remarks>
</Docs>
<Members>
Expand Down
12 changes: 11 additions & 1 deletion xml/System.Runtime.CompilerServices/RefSafetyRulesAttribute.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,17 @@
</Attributes>
<Docs>
<summary>Indicates the language version of the ref safety rules used when the module was compiled.</summary>
<remarks>To be added.</remarks>
<remarks>
<format type="text/markdown"><![CDATA[

## Remarks

This attribute is specially recognized by the runtime. ECMA-335 augment III.1.7.7 defines restrictions on valid IL that reference this attribute. Applying this attribute to a module opts the module into further restrictions based on the version value specified in the attribute, which permits an optimizing compiler to further optimize certain code patterns. For more information, see the [ECMA-335 CLI Specification Addendum](https://github.com/dotnet/runtime/blob/main/docs/design/specs/Ecma-335-Augments.md#iii177-opt-in-restrictions), Sec. III.1.7.7 ("Opt-in restrictions").

Because the runtime relies on this attribute, it can't be stripped from an assembly.

]]></format>
</remarks>
</Docs>
<Members>
<Member MemberName=".ctor">
Expand Down
Loading