Skip to content

Clarify volatile memory ordering, loop hoisting, and Debug vs Release behavior (Fixes #25426) - #56650

Open
Manish-1kumar wants to merge 5 commits into
dotnet:mainfrom
Manish-1kumar:users/manish/issue-25426-volatile-documentation-clarification
Open

Manish-1kumar wants to merge 5 commits into
dotnet:mainfrom
Manish-1kumar:users/manish/issue-25426-volatile-documentation-clarification

Conversation

@Manish-1kumar

@Manish-1kumar Manish-1kumar commented Nov 1, 2026 •

Copy link
Copy Markdown
Contributor

Description

Resolves #25426.

Clarifies the behavior of the worker thread code snippet in \docs/csharp/language-reference/keywords/volatile.md\ and explains why running the code without \�olatile\ may still appear to terminate predictably in standard debug test runs.

Changes Included

  • Explained what \�olatile\ prevents at the JIT level (preventing register caching across loop iterations and enforcing memory order constraints).
  • Clarified that in the absence of \�olatile, the JIT compiler may hoist the read of _shouldStop\ out of the loop or cache it in a CPU register, resulting in an infinite loop.
  • Added a note explaining why users will not observe differences when running under a debugger or in \Debug\ configuration (because JIT optimizations are disabled in \Debug\ mode) and that \Release\ configuration (\dotnet run -c Release) is required to observe JIT register caching/hoisting.
  • Noted hardware memory model differences (e.g. x86/x64 strongly ordered vs ARM64 weakly ordered).
  • Recommended \CancellationTokenSource\ and \CancellationToken\ as the idiomatic modern .NET pattern for cooperative cancellation.\
  • Validated with \markdownlint-cli2\ (0 issues).

Internal previews

File Preview link
docs/csharp/language-reference/keywords/volatile.md Learn preview

Build report

@dotnetrepoman dotnetrepoman Bot added this to the November 2026 milestone Nov 1, 2026
@dotnet-policy-service dotnet-policy-service Bot added dotnet-csharp/svc lang-reference/subsvc community-contribution Indicates PR is created by someone from the .NET community. labels Nov 1, 2026
…ile guide

Generalize JIT compiler references to runtime to encompass execution modes such as Native AOT and remove redundant CPU register phrasing per maintainer feedback.
Reflects suggestion from @jkotas on PR dotnet#56650: CancellationTokenSource
was introduced over 15 years ago and is standard practice across .NET.

Fixes: dotnet#56650 (comment)
…er caching

Per suggestion by @jkotas on PR dotnet#56650: processor registers are not
the only mechanism used to cache values; clarify that the value is
read on each loop iteration rather than reusing a previously read value.

Fixes: dotnet#56650 (comment)

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

The added note leaves the Debug-versus-Release confusion unexplained and needs an optimized-run example clarifying that Release does not guarantee an observable failure.

1 open issue
What changed in this PR

Clarifies the C# volatile example to explain why removing the modifier can produce unpredictable behavior, addressing the confusion reported in #25426.

Changes:

  • Explains per-iteration reads, memory ordering, and how loop-read hoisting can cause an infinite loop.
  • Notes that runtime conditions, hardware, and optimizations affect observed behavior.
  • Recommends CancellationTokenSource and CancellationToken for cooperative cancellation.
File Description
docs/​csharp/​language-reference/​keywords/​volatile.md Clarifies the worker-loop behavior and adds cancellation guidance.

Review effort: Balanced

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

community-contribution Indicates PR is created by someone from the .NET community. dotnet-csharp/svc lang-reference/subsvc

Projects

None yet

Development

Successfully merging this pull request may close these issues.

not good example for volatile

3 participants