From 67ca3c87a6e78f769cbe7272f089379ab5acce05 Mon Sep 17 00:00:00 2001
From: Henning Andersen <henning.andersen@elastic.co>
Date: Mon, 26 Aug 2024 11:37:35 +0200
Subject: [PATCH] comment clarity.

---
 .../blobcache/shared/SharedBlobCacheService.java       | 10 ++++++----
 1 file changed, 6 insertions(+), 4 deletions(-)

diff --git a/x-pack/plugin/blob-cache/src/main/java/org/elasticsearch/blobcache/shared/SharedBlobCacheService.java b/x-pack/plugin/blob-cache/src/main/java/org/elasticsearch/blobcache/shared/SharedBlobCacheService.java
index 1599520d78fed..db5d17d20f914 100644
--- a/x-pack/plugin/blob-cache/src/main/java/org/elasticsearch/blobcache/shared/SharedBlobCacheService.java
+++ b/x-pack/plugin/blob-cache/src/main/java/org/elasticsearch/blobcache/shared/SharedBlobCacheService.java
@@ -806,10 +806,12 @@ private static VarHandle findIOVarHandle() {
         final RegionKey<KeyType> regionKey;
         final SparseFileTracker tracker;
         // io can be null when not init'ed or after evict/take
-        // io does not need volatile access on the read path, since it goes from null to a final value only and "cache.get" never returns
-        // a `CacheFileRegion` without checking the value is non-null (with a volatile read, ensuring the value is visible in that thread).
-        // we assume any IndexInput passing among threads (slicing etc) is done with proper happens-before semantics (otherwise they'd
-        // themselves break).
+        // io does not need volatile access on the read path, since it goes from null to a single value (and then possbily back to null).
+        // "cache.get" never returns a `CacheFileRegion` without checking the value is non-null (with a volatile read, ensuring the value is
+        // visible in that thread).
+        // We assume any IndexInput passing among threads is done with proper happens-before semantics (otherwise they'd themselves break).
+        // In general, assertions should use `nonVolatileIO` (when they can) to access this over `volatileIO` to avoid memory visibility
+        // side effects
         private SharedBytes.IO io = null;
 
         CacheFileRegion(SharedBlobCacheService<KeyType> blobCacheService, RegionKey<KeyType> regionKey, int regionSize) {