From c15a6e92d1a8d6b7c3ed79077981ed9ba1dd0a30 Mon Sep 17 00:00:00 2001
From: uhm0311 <uhm0311@jam2in.com>
Date: Fri, 22 Dec 2023 15:42:02 +0900
Subject: [PATCH] INTERNAL: Add comments to new SMGetResult merge method.

---
 .../internal/result/SMGetResultImpl.java      | 55 +++++++++++++++++--
 1 file changed, 51 insertions(+), 4 deletions(-)

diff --git a/src/main/java/net/spy/memcached/internal/result/SMGetResultImpl.java b/src/main/java/net/spy/memcached/internal/result/SMGetResultImpl.java
index e6d0124a4..1783e6a18 100644
--- a/src/main/java/net/spy/memcached/internal/result/SMGetResultImpl.java
+++ b/src/main/java/net/spy/memcached/internal/result/SMGetResultImpl.java
@@ -40,25 +40,52 @@ public void mergeSMGetElements(final List<SMGetElement<T>> eachResult,
       }
     } else {
       // do sort merge
-      boolean duplicated;
+      boolean duplicated; // !(Is current eachResult could be inserted?)
       int comp, pos = 0;
       for (SMGetElement<T> result : eachResult) {
         duplicated = false;
         for (; pos < mergedResult.size(); pos++) {
-          // compare b+tree key
+          // Compare bkey to search proper position of current eachResult in mergedResult.
+
           comp = result.compareBkeyTo(mergedResult.get(pos));
           if ((reverse) ? (0 < comp) : (0 > comp)) {
+            // If reverse, mergedResult is sorted as desc. (4 -> 3 -> 2 -> 1)
+            // Otherwise, mergedResult is sorted as asc. (1 -> 2 -> 3 -> 4)
+
+            // If reverse and bkey of current eachResult is greater than
+            // bkey of mergedResult.get(position),
+            // current eachResult should be inserted to position of mergedResult.
+
+            // If not reverse and bkey of current eachResult is less than
+            // bkey of mergedResult.get(position),
+            // current eachResult should be inserted to position of mergedResult.
+
             break;
           }
-          if (comp == 0) { // compare key string
+          if (comp == 0) {
+            // Duplicated bkey. Compare the "cache key".
             int keyComp = result.compareKeyTo(mergedResult.get(pos));
             if ((reverse) ? (0 < keyComp) : (0 > keyComp)) {
               if (unique) {
-                mergedResult.remove(pos); // remove dup bkey
+                // If reverse, remove less cache key.
+                // Therefore, greater cache key is remained in mergedResult.
+                // Less cache key is key of mergedResult.get(position),
+                // and greater cache key is key of current eachResult.
+                // EX: key0 vs key1, remove key0. key1 is remained.
+
+                // Otherwise, remove greater cache key.
+                // Therefore, less cache key is remain in mergedResult.
+                // Greater cache key is cache key of mergedResult.get(position).
+                // and less cache key is key of current eachResult.
+                // EX: key0 vs. key1, remove key1. key0 is remained.
+
+                mergedResult.remove(pos);
               }
               break;
             } else {
               if (unique) {
+                // In this case, current eachResult is prevented to be inserted.
+
                 duplicated = true;
                 break;
               }
@@ -78,6 +105,8 @@ public void mergeSMGetElements(final List<SMGetElement<T>> eachResult,
           // So, stop the current sort-merge.
           break;
         }
+
+        // Insert current eachResult to proper position of mergedResult.
         mergedResult.add(pos, result);
         if (mergedResult.size() > count) {
           // Remove elements that exceed the requested count.
@@ -94,9 +123,27 @@ public void mergeSMGetElements(final List<SMGetElement<T>> eachResult,
         // do sort merge trimmed list
         int pos = 0;
         for (SMGetTrimKey result : eachTrimmedResult) {
+          // Search proper position of current eachTrimmedResult in mergedTrimmedKeys.
+
           for (; pos < mergedTrimmedKeys.size(); pos++) {
             if ((reverse) ? (0 < result.compareTo(mergedTrimmedKeys.get(pos)))
                           : (0 > result.compareTo(mergedTrimmedKeys.get(pos)))) {
+
+              // If reverse, mergedTrimmedKeys is sorted as desc. (4 -> 3 -> 2 -> 1)
+              // Otherwise, mergedTrimmedKeys is sorted as asc. (1 -> 2 -> 3 -> 4)
+
+              // SMGetTrimKey.compareTo() compares bkey first, and cache key second.
+              // If bkey is same, then compares cache key.
+
+              // If reverse, mergedTrimmedKeys is sorted as desc for bkey,
+              // and in same bkey, it is sorted as desc for cache key.
+              // Otherwise, mergedTrimmedKeys is sorted as asc for bkey,
+              // and in same bkey, it is sorted as asc for cache key.
+
+              // Same bkey and cache key?
+              // For current server, there is NO duplicated bkey in one btree.
+              // Server rejects duplicated bkey insertion in one btree.
+
               break;
             }
           }