From d594ef3a3e013b84a392b6d64a54015adc8173cd Mon Sep 17 00:00:00 2001
From: David Holmes <dholmes@openjdk.org>
Date: Fri, 29 Aug 2025 16:31:13 +0000
Subject: [PATCH] 8366121: Hotspot Style Guide should document conventions for
 lock-free code

Reviewed-by: stefank, ayang, jsjolen, jwaters, kvn, kbarrett
---
 doc/hotspot-style.html | 10 ++++++++++
 doc/hotspot-style.md   | 11 +++++++++++
 2 files changed, 21 insertions(+)

diff --git a/doc/hotspot-style.html b/doc/hotspot-style.html
index dafd29d6f54..88ec07475fd 100644
--- a/doc/hotspot-style.html
+++ b/doc/hotspot-style.html
@@ -209,6 +209,16 @@ lines of code. Name what you must repeat.</p></li>
 attribute, the change should be done with a "setter" accessor matched to
 the simple "getter".</p></li>
 </ul>
+<h4 id="conventions-for-lock-free-code">Conventions for Lock-free
+Code</h4>
+<p>Sometimes variables are accessed concurrently without appropriate
+synchronization context, such as a held mutex or at a safepoint. In such
+cases the variable should be declared <code>volatile</code> and it
+should NOT be accessed as a normal C++ lvalue. Rather, access should be
+performed via functions from <code>Atomic</code>, such as
+<code>Atomic::load</code>, <code>Atomic::store</code>, etc.</p>
+<p>This special formulation makes it more clear to maintainers that the
+variable is accessed concurrently in a lock-free manner.</p>
 <h3 id="source-files">Source Files</h3>
 <ul>
 <li><p>All source files must have a globally unique basename. The build
diff --git a/doc/hotspot-style.md b/doc/hotspot-style.md
index 0a0089ee454..322bdc8458e 100644
--- a/doc/hotspot-style.md
+++ b/doc/hotspot-style.md
@@ -135,6 +135,17 @@ lines of code.  Name what you must repeat.
 change should be done with a "setter" accessor matched to the simple
 "getter".
 
+#### Conventions for Lock-free Code
+
+Sometimes variables are accessed concurrently without appropriate synchronization
+context, such as a held mutex or at a safepoint. In such cases the variable should
+be declared `volatile` and it should NOT be accessed as a normal C++ lvalue. Rather,
+access should be performed via functions from `Atomic`, such as `Atomic::load`,
+`Atomic::store`, etc.
+
+This special formulation makes it more clear to maintainers that the variable is
+accessed concurrently in a lock-free manner.
+
 ### Source Files
 
 * All source files must have a globally unique basename. The build