What does it mean "NoGCRegion is a read-only value"?

[deep-outcome]

Type of issue

Typo

Description

From https://learn.microsoft.com/en-us/dotnet/api/system.runtime.gclatencymode?view=net-8.0#fields

Brief look at enum itself reveals that NoGCRegion is declared same as other values,, https://source.dot.net/#System.Private.CoreLib/src/libraries/System.Private.CoreLib/src/System/Runtime/GCSettings.cs,9dba3e06a9881afd.

LatencyMode property is what validates its inputs, https://source.dot.net/#System.Private.CoreLib/src/libraries/System.Private.CoreLib/src/System/Runtime/GCSettings.cs,44.

Page URL

https://learn.microsoft.com/en-us/dotnet/api/system.runtime.gclatencymode?view=net-8.0#system-runtime-gclatencymode-nogcregion

Content source URL

https://github.com/dotnet/dotnet-api-docs/blob/main/xml/System.Runtime/GCLatencyMode.xml

Document Version Independent Id

0bc21af3-3d1b-eea7-9f2f-9a0cf3045dee

Article author

@dotnet-bot

[dotnet-issue-labeler]

I couldn't figure out the best area label to add to this issue. If you have write-permissions please help me learn by adding exactly one area label.

[dotnet-issue-labeler]

I couldn't figure out the best area label to add to this issue. If you have write-permissions please help me learn by adding exactly one area label.

[dotnet-policy-service]

Tagging subscribers to this area: @dotnet/area-system-runtime

[tannergooding]

CC. @dotnet/gc docs clarifying question for you.

[markples]

It is readonly in the sense that the value can be read from GCSettings.LatencyMode but can't be set there. In other words, var x = GCSettings.LatencyMode can result in LatencyMode.NoGCRegion, but GCSettings.LatencyMode = LatencyMode.NoGCRegion will throw an exception.

It is actually the check earlier in that method - https://github.com/dotnet/runtime/blob/161f34645c5a7e18880f601b5bee569694d67f79/src/libraries/System.Private.CoreLib/src/System/Runtime/GCSettings.cs#L37-L41 - that will throw an exception.

 public static GCLatencyMode LatencyMode
        {
            get => GetGCLatencyMode();
            set
            {
>               if ((value < GCLatencyMode.Batch) ||
>                   (value > GCLatencyMode.SustainedLowLatency))
>               {
>                   ThrowHelper.ArgumentOutOfRangeException_Enum_Value();
>               }

The screenshot above with NoGCInProgress is handling a different case. The latency mode can't be set during a NoGCRegion because a GC isn't supposed to occur.

There is a description of this on the other side as well (the LatencyMode property- https://learn.microsoft.com/en-us/dotnet/api/system.runtime.gcsettings.latencymode?view=net-8.0#system-runtime-gcsettings-latencymode):

Ordinarily, you set the value of the LatencyMode property to define the garbage collector's latency mode. However, you cannot set the no GC region latency mode by assigning the GCLatencyMode.NoGCRegion enumeration value to the LatencyMode property. Instead, you call the GC.TryStartNoGCRegion method to begin the no GC region latency mode, and you call the GC.EndNoGCRegion to end it.

[deep-outcome]

That you for corrective post. I acknowledge information. Sense is obvious to me. Because read-onlyness is conceptualy broad, but well-known, in csharp, this is confusing. Thus I expected kind of compliance with some spec area.

Because of actual meaning, I would expect something like "NoGCRegion is a non-assinable value;" or "NoGCRegion is a indicative value only;".

Confusion vector is also value because both read-only and value usually have strict meaning regarding specificion which documentation derives from.

enum options are casually referenced as fields and technically exactly these are named constants, members. See 19.4 Enum members.

While sense is obvious, degree of confusion exists. "NoGCRegion is a non-assinable option;" or "NoGCRegion is a indicative option only;" seem also fine.