From 61a5b49c2219391e164595719ddecd42a95777b1 Mon Sep 17 00:00:00 2001
From: Nitload <YoumuLiu_NSI@whv0t.onmicrosoft.com>
Date: Mon, 13 Apr 2026 00:12:29 +0800
Subject: [PATCH] solution to unsafe operation in l4

---
 .../HighPerformance/Memory/L4.Predictor.cs    | 26 +++++++++++++++++++
 .../HighPerformance/Memory/L4.Prefetch.cs     |  5 ++++
 2 files changed, 31 insertions(+)

diff --git a/StgSharp.Common/HighPerformance/Memory/L4.Predictor.cs b/StgSharp.Common/HighPerformance/Memory/L4.Predictor.cs
index b4faa043..8d7ed1be 100644
--- a/StgSharp.Common/HighPerformance/Memory/L4.Predictor.cs
+++ b/StgSharp.Common/HighPerformance/Memory/L4.Predictor.cs
@@ -45,6 +45,32 @@ namespace StgSharp.HighPerformance.Memory
     public interface IL4Predict
     {
 
+        /*
+         * Planned optimization contract types:
+         * 1. internal interface IL4PredictOptimizationContract
+         *    - Trusted extension point queried once during predictor registration.
+         *    - Produces normalized compatibility tokens for a given map policy.
+         * 2. readonly struct L4PredictCompatibilityToken
+         *    - Hot-path comparable descriptor cached by L4.
+         *    - Should at least carry ResidentFamily, FlushFamily and AccessMode.
+         * 3. enum L4PredictAccessMode
+         *    - Distinguishes read-only sources from write-back or write-through targets.
+         *
+         * L4 should only use these cached tokens in the prefetch path. Predictors without the
+         * internal contract stay on the conservative path: write back the old owner, then
+         * rematerialize the cache line for the new predictor.
+         */
+
+        /// <summary>
+        ///   Determines whether a cache line materialized by <paramref name="predict" /> under
+        ///   <paramref name="policy" /> can be adopted by the current predictor without an
+        ///   intermediate rematerialization.
+        /// </summary>
+        /// <remarks>
+        ///   This is intentionally stronger than comparing raw policy bits for equality. A true
+        ///   result means the resident bytes can continue to be interpreted safely after ownership
+        ///   is transferred to the current predictor.
+        /// </remarks>
         bool IsSamePolicy(
              uint policy,
              IL4Predict predict
diff --git a/StgSharp.Common/HighPerformance/Memory/L4.Prefetch.cs b/StgSharp.Common/HighPerformance/Memory/L4.Prefetch.cs
index b9dfe4bc..9017ee1b 100644
--- a/StgSharp.Common/HighPerformance/Memory/L4.Prefetch.cs
+++ b/StgSharp.Common/HighPerformance/Memory/L4.Prefetch.cs
@@ -88,11 +88,16 @@ namespace StgSharp.HighPerformance.Memory
 
                         int predictId = head->_predictor;
                         IL4Predict belong = predictorSpan[predictId];
+                        // This branch performs resident-line adoption rather than a simple policy
+                        // equality check. Returning true means the current predictor can keep using
+                        // the existing cache bytes without a write-back plus re-prefetch cycle.
                         if (predict.IsSamePolicy(head->_profile, belong))
                         {
                             head->_predictor =predictIndex;
                         } else
                         {
+                            // Compatibility failed, so the old owner must first flush its view of
+                            // the line before the new predictor rematerializes the cache bytes.
                             belong.WriteBack(head->_origin, head->_profile, new ReadOnlySpan<byte>((byte*)head->_address, Unsafe.SizeOf<CacheLineData>()));
                             head->_profile = pHandle.MapPolicy;
                             predict.Prefetch(head->_origin, head->_profile, new Span<byte>((byte*)head->_address, Unsafe.SizeOf<CacheLineData>()));