From 33fd8bb705cb8c23ae991817a2d947fde1d180af Mon Sep 17 00:00:00 2001
From: Andrew Noyes <andrew@weaselab.dev>
Date: Tue, 19 Aug 2025 14:31:42 -0400
Subject: [PATCH] Update realloc_raw docstring

---
 src/arena_allocator.hpp | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/src/arena_allocator.hpp b/src/arena_allocator.hpp
index 41f462b..a51be67 100644
--- a/src/arena_allocator.hpp
+++ b/src/arena_allocator.hpp
@@ -237,6 +237,10 @@ public:
    * - The old pointer becomes invalid if a copy occurs
    * - Like malloc/realloc, the contents beyond old_size are uninitialized
    * - When copying to new location, uses the specified alignment
+   * - **Shrinking behavior**: If `new_size < old_size` and the allocation
+   *   is *not* the most recent one, this function returns the original
+   *   pointer, but **no memory is reclaimed**. The arena design does not
+   *   support freeing memory from the middle of a block.
    */
   void *realloc_raw(void *ptr, uint32_t old_size, uint32_t new_size,
                     uint32_t alignment = alignof(std::max_align_t));