v13-0003-Tweak-some-comments-in-0001.patch

From 7bcdf33fded7b5ea3b5f365dca22088fec4a46e9 Mon Sep 17 00:00:00 2001
From: Michael Paquier <michael@paquier.xyz>
Date: Fri, 15 Nov 2024 08:36:38 +0900
Subject: [PATCH v13 3/3] Tweak some comments in 0001

---
 src/include/utils/memutils.h | 36 ++++++++++++++++--------------------
 1 file changed, 16 insertions(+), 20 deletions(-)

diff --git a/src/include/utils/memutils.h b/src/include/utils/memutils.h
index 0808e91b77..f830093ca9 100644
--- a/src/include/utils/memutils.h
+++ b/src/include/utils/memutils.h
@@ -198,19 +198,20 @@ extern MemoryContext BumpContextCreate(MemoryContext parent,
  * The test is divided into multiple cases for safety reason and multiple phases
  * for efficiency.
  *
- * Case 1: len < 8 bytes, then byte per byte comparison.
- * Case 2: len in the 8-63 bytes range:
+ * Case 1: len < sizeof(size_t) bytes, then byte per byte comparison.
+ * Case 2: len < (sizeof(size_t) * 8 - 1) bytes:
  *       - Phase 1: Byte by byte comparison, until the pointer is aligned.
  *       - Phase 2: size_t comparisons, with aligned pointers, up to the last
  *                  location possible.
  *       - Phase 3: Byte by byte comparison, until the end location.
- * Case 3: len >= 64 bytes, same as case 2 except that an additional phase is
- *         is placed between Phase 1 and Phase 2, with 8 * sizeof(size_t)
- *         comparisons using bitwise OR, to encourage compilers to use SIMD
- *         instructions if available, up to the last aligned location possible.
+ * Case 3: len >= (sizeof(size_t) * 8) bytes, same as case 2 except that an
+ *         additional phase is placed between Phase 1 and Phase 2, with
+ *         (8 * sizeof(size_t)) comparisons using bitwise OR, to encourage
+ *         compilers to use SIMD instructions if available, up to the last
+ *         aligned location possible.
  *
  * Case 1 and Case 2 are mandatory to ensure that we won't read beyond the
- * memory area.
+ * memory area.  This is portable for 32-bit and 64-bit architectures.
  *
  * Caller must ensure that "ptr" is not NULL.
  */
@@ -222,7 +223,6 @@ pg_memory_is_all_zeros(const void *ptr, size_t len)
 	const unsigned char *aligned_end = (const unsigned char *)
 		((uintptr_t) end & (~(sizeof(size_t) - 1)));
 
-	/* len < 8 bytes case */
 	if (len < sizeof(size_t))
 	{
 		while (p < end)
@@ -233,7 +233,7 @@ pg_memory_is_all_zeros(const void *ptr, size_t len)
 		return true;
 	}
 
-	/* len in the 8-63 bytes range case */
+	/* "len" in the [sizeof(size_t), sizeof(size_t) * 8 - 1] range */
 	if (len < sizeof(size_t) * 8)
 	{
 		/* Compare bytes until the pointer "p" is aligned */
@@ -248,9 +248,8 @@ pg_memory_is_all_zeros(const void *ptr, size_t len)
 		/*
 		 * Compare remaining size_t-aligned chunks.
 		 *
-		 * There is no risk to read beyond the memory area, as aligned_end
-		 * can't be > end as we are in the len 8-63 bytes range case (so len
-		 * >= 8).
+		 * There is no risk to read beyond the memory area, as "aligned_end"
+		 * cannot be higher than "end".
 		 */
 		for (; p < aligned_end; p += sizeof(size_t))
 		{
@@ -267,9 +266,9 @@ pg_memory_is_all_zeros(const void *ptr, size_t len)
 		return true;
 	}
 
-	/* len >= 64 bytes case */
+	/* "len" in the [sizeof(size_t) * 8, inf[ range */
 
-	/* Compare bytes until the pointer "p" is aligned */
+	/* Compare bytes until the pointer "p" is aligned. */
 	while (((uintptr_t) p & (sizeof(size_t) - 1)) != 0)
 	{
 		if (p == end)
@@ -288,9 +287,6 @@ pg_memory_is_all_zeros(const void *ptr, size_t len)
 	 * all 8 elements regardless of the result of the other comparisons.  This
 	 * seems to be enough to coax a few compilers into using SIMD
 	 * instructions.
-	 *
-	 * There is no risk to read beyond the memory area as we are in the len >=
-	 * 64 bytes case.
 	 */
 	for (; p < aligned_end - (sizeof(size_t) * 7); p += sizeof(size_t) * 8)
 	{
@@ -304,8 +300,8 @@ pg_memory_is_all_zeros(const void *ptr, size_t len)
 	/*
 	 * Compare remaining size_t-aligned chunks.
 	 *
-	 * There is no risk to read beyond the memory area, as aligned_end can't
-	 * be > end as we are in the len >= 64 bytes case (so len >= 8).
+	 * There is no risk to read beyond the memory area, as "aligned_end"
+	 * cannot be higher than "end".
 	 */
 	for (; p < aligned_end; p += sizeof(size_t))
 	{
@@ -313,7 +309,7 @@ pg_memory_is_all_zeros(const void *ptr, size_t len)
 			return false;
 	}
 
-	/* Compare remaining bytes until the end */
+	/* Compare remaining bytes until the end. */
 	while (p < end)
 	{
 		if (*p++ != 0)
-- 
2.45.2