Round metadata to MIN_META_ALIGN, not next_pow2

BackendArenaRange / SmallArenaRange accept any UNIT_SIZE-aligned
request; the pow2 rounding the backend was applying to metadata
sizes was a leftover from the buddy era and inflated every slab's
metadata block to the next power of two. With a ClientMeta
provider whose per-slab storage is non-pow2 (e.g. allocation
bitmap + small fixed header), this rounding doubled the metadata
overhead.

Publish MIN_META_ALIGN on each LocalState (= MetaRange::UNIT_SIZE).
Add BackendAllocator::meta_size_round, which pads to MIN_META_ALIGN
and steps up to MIN_CHUNK_SIZE for requests that would bypass the
small range to the parent. Replace all four next_pow2-rounded
metadata sites in backend.h with this helper.

A new test func/client_meta_nonpow2 installs a ClientMetaDataProvider
whose per-slab storage is non-pow2 and exercises alloc/dealloc
round-tripping across several sizeclasses; any disagreement between
alloc-side and dealloc-side rounding would trip the meta range's
dealloc_range assertions.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: mjp41

docs/Arena.md

@@ -0,0 +1,125 @@
+# Bitmap-Indexed Coalescing Range
+
+## The problem
+
+snmalloc's `LargeBuddyRange` only stores power-of-two blocks. A request for 5
+chunks must be served from an 8-chunk buddy block, wasting 3 chunks. We want
+to store blocks at their actual size and use snmalloc's full size class
+sequence at the range level.
+
+## The core idea: search upward, skip a mask
+
+Free blocks are binned by the set of size classes they can serve. To allocate,
+search upward through bins — any larger block can be carved down. This almost
+works perfectly, but some bins hold blocks whose alignment is too poor to
+serve certain smaller, more-aligned sizes. Those bins must be masked out
+during the search.
+
+The mechanism: `find_first_set(bitmap & ~skip_mask)`. The skip mask depends
+only on the requested size class, not on the block. It's a small constant
+that can be precomputed.
+
+## Why skips exist
+
+snmalloc's size classes follow `S = 2^e + m · 2^(e−B)`, where `B` is the
+number of intermediate bits. Each size class has a natural alignment
+`align(S) = S & ~(S−1)`.
+
+A size class with high alignment needs padding to reach an aligned address
+within a block. A block of a *larger* size class with *lower* alignment may
+not have room for that padding. Concretely: a block of size 5 at address 1
+can serve size 5 (alignment 1) but cannot serve size 4 (alignment 4) — there
+aren't enough chunks left after padding to the first 4-aligned address.
+
+Same size block, different address, different capability. This is what creates
+the need for separate bins and skip masks.
+
+## The general structure
+
+At each exponent level, the distinct "servable sets" (which size classes a
+block can serve) form a structure with some incomparable pairs. Exhaustive
+enumeration shows:
+
+| B | Mantissas/exponent | Bins/exponent | Max skip mask bits |
+|---|-------------------:|--------------:|-------------------:|
+| 1 | 2                  | 2             | 0                  |
+| 2 | 4                  | 5             | 1                  |
+| 3 | 8                  | 13            | 4                  |
+| 4 | 16                 | 34            | 11                 |
+
+Each bin corresponds to a distinct servable set. The bins are ordered so that
+upward search is almost always correct — the skip mask handles the exceptions.
+
+For any B, the structure is:
+- **Most requests need no skips.** Only size classes with alignment higher
+  than expected for their position in the sequence need to mask anything.
+- **The skip mask is a small constant** per size class, precomputable at
+  compile time.
+- **The mechanism is identical** regardless of B:
+  `find_first_set(bitmap & ~skip_mask, start_bit)`.
+
+`prototype/skip_analysis.py` verifies this exhaustively for B = 1, 2, 3.
+
+## The bitmap design
+
+Each free block gets one bin based on its size and alignment. Within each
+exponent, there are as many bins as there are distinct servable sets (5 for
+B=2, 13 for B=3). A flat bitmap tracks which bins are non-empty.
+
+To allocate size class `(e, m)`:
+
+1. Compute the **start bit** — the first bin that could serve this size class.
+2. Compute the **skip mask** — bits for bins that can't serve this request.
+3. `find_first_set(bitmap & ~skip_mask, start_bit)` → pop a block from that
+   bin.
+
+The returned block may not be exactly aligned for the requested size class.
+The caller **carves** the aligned region and returns any prefix/suffix
+remainders to the free pool.
+
+## Contrast with buddy allocators
+
+A buddy allocator guarantees alignment by construction — a 16-chunk buddy is
+always 16-aligned — but wastes space by decomposing everything into
+power-of-two pieces.
+
+This design stores blocks at their actual size (no decomposition, no waste)
+and handles alignment at allocation time by carving. The skip mask makes
+lookup O(1) despite blocks having arbitrary size and alignment.
+
+## Concrete example (B = 2)
+
+At exponent `e = 2`, the size classes are 4, 5, 6, 7. There are 5 bins,
+each labeled by the set of size classes it can serve at this exponent:
+
+    Bin 0: serves {4}
+    Bin 1: serves {5}
+    Bin 2: serves {4, 5}
+    Bin 3: serves {4, 5, 6}
+    Bin 4: serves {4, 5, 6, 7}
+
+Allocation searches upward from the smallest sufficient bin:
+
+    Request for 7: can use bin 4                       → search bits {4}
+    Request for 6: can use bins 3, 4                   → search bits {3, 4}
+    Request for 5: can use bins 1, 2, 3, 4             → search bits {1, 2, 3, 4}
+    Request for 4: can use bins 0, 2, 3, 4 — skip 1   → search bits {0, 2, 3, 4}
+
+Only the request for size 4 needs to skip a bin: bin 1 holds blocks that can
+serve 5 but not 4. The skip mask is just bit 1.
+
+## Concrete example (B = 3)
+
+At exponent `e = 4`, the size classes are 16, 18, 20, 22, 24, 26, 28, 30.
+There are 13 bins. The skip analysis shows:
+
+    Request for 16 (align 16): must skip bins for {18}, {20}, {22}, {26}
+    Request for 24 (align  8): must skip bin for {26}
+    All other requests: no skips needed
+
+The pattern: size 16 has high alignment and must skip 4 bins whose blocks
+are large enough but too poorly aligned. Size 24 is a "sub-power-of-two"
+(alignment 8) and must skip 1 bin. All odd-coefficient sizes have low
+alignment and never need to skip anything.
+
+Same mechanism, wider mask, same `find_first_set(bitmap & ~mask)` operation.

src/snmalloc/backend/backend.h

@@ -23,7 +23,27 @@ namespace snmalloc
     using Pal = PAL;
     using SlabMetadata = typename PagemapEntry::SlabMetadata;
 
-  public:
+    /**
+     * Round a metadata allocation size to a value the meta range can
+     * service.
+     *
+     * - Pads to `LocalState::MIN_META_ALIGN` so that the in-band small
+     *   meta range (`SmallArenaRange`) accepts it.
+     * - If the result reaches `MIN_CHUNK_SIZE`, the request will bypass
+     *   the small range to the parent `LargeArenaRange`, which requires
+     *   `MIN_CHUNK_SIZE` alignment; step up to satisfy that.
+     *
+     * Alloc and dealloc sites MUST share this helper so a chunk's
+     * metadata is freed at the same size it was allocated.
+     */
+    SNMALLOC_FAST_PATH static size_t meta_size_round(size_t size)
+    {
+      size_t r = bits::align_up(size, LocalState::MIN_META_ALIGN);
+      if (r >= MIN_CHUNK_SIZE)
+        r = bits::align_up(r, MIN_CHUNK_SIZE);
+      return r;
+    }
+
     /**
      * Provide a block of meta-data with size and align.
      *
@@ -47,18 +67,15 @@ namespace snmalloc
       if (local_state != nullptr)
       {
         auto& meta_range = local_state->get_meta_range();
-        using MetaRangeT = stl::remove_reference_t<decltype(meta_range)>;
-        size_t alignment =
-          bits::max(bits::next_pow2(size), MetaRangeT::UNIT_SIZE);
-        p = meta_range.alloc_size_with_align(size, alignment);
+        p = meta_range.alloc_range(meta_size_round(size));
       }
       else
       {
         static_assert(
           GlobalMetaRange::ConcurrencySafe,
           "Global meta data range needs to be concurrency safe.");
         GlobalMetaRange global_state;
-        p = global_state.alloc_range(bits::next_pow2(size));
+        p = global_state.alloc_range(meta_size_round(size));
       }
 
       if (p == nullptr)
@@ -110,7 +127,7 @@ namespace snmalloc
       // Calculate the extra bytes required to store the client meta-data.
       size_t extra_bytes = SlabMetadata::get_extra_bytes(sizeclass);
 
-      auto meta_size = bits::next_pow2(sizeof(SlabMetadata) + extra_bytes);
+      auto meta_size = meta_size_round(sizeof(SlabMetadata) + extra_bytes);
 
 #ifdef SNMALLOC_TRACING
       message<1024>(
@@ -210,7 +227,7 @@ namespace snmalloc
       // Calculate the extra bytes required to store the client meta-data.
       size_t extra_bytes = SlabMetadata::get_extra_bytes(sizeclass);
 
-      auto meta_size = bits::next_pow2(sizeof(SlabMetadata) + extra_bytes);
+      auto meta_size = meta_size_round(sizeof(SlabMetadata) + extra_bytes);
       local_state.get_meta_range().dealloc_range(
         capptr::Arena<void>::unsafe_from(&slab_metadata), meta_size);
 

src/snmalloc/backend/meta_protected_range.h

@@ -112,6 +112,12 @@ namespace snmalloc
     MetaRange meta_range;
 
   public:
+    /// Granularity of the local meta range. Backend rounds metadata
+    /// allocation sizes up to this; replaces pow2 rounding.
+    static constexpr size_t MIN_META_ALIGN = MetaRange::UNIT_SIZE;
+    static_assert(
+      bits::is_pow2(MIN_META_ALIGN), "MIN_META_ALIGN must be a power of two");
+
     using Stats = StatsCombiner<CentralObjectRange, CentralMetaRange>;
 
     ObjectRange* get_object_range()

src/snmalloc/backend/standard_range.h

@@ -62,6 +62,12 @@ namespace snmalloc
     ObjectRange object_range;
 
   public:
+    /// Granularity of the local meta range. Backend rounds metadata
+    /// allocation sizes up to this; replaces pow2 rounding.
+    static constexpr size_t MIN_META_ALIGN = ObjectRange::UNIT_SIZE;
+    static_assert(
+      bits::is_pow2(MIN_META_ALIGN), "MIN_META_ALIGN must be a power of two");
+
     // Expose a global range for the initial allocation of meta-data.
     using GlobalMetaRange = Pipe<ObjectRange, GlobalRange>;
 

src/test/func/client_meta_nonpow2/client_meta_nonpow2.cc

@@ -0,0 +1,92 @@
+/**
+ * Exercises the slab metadata allocation path with a ClientMetaDataProvider
+ * whose per-slab extra_bytes is non-power-of-two.
+ *
+ * The backend rounds slab metadata sizes to `MIN_META_ALIGN` (= the meta
+ * range's UNIT_SIZE) rather than the next power of two, so a non-pow2
+ * client meta size actually occupies a non-pow2 slab metadata block.
+ * This test gates the alloc/dealloc round-trip on that path: if
+ * `meta_size_round` is wrong, an inconsistent alloc/dealloc size would
+ * either trip an assertion in the meta range or leak.
+ */
+
+#include "test/setup.h"
+
+#include <iostream>
+#include <snmalloc/backend/globalconfig.h>
+#include <snmalloc/snmalloc_core.h>
+#include <vector>
+
+namespace snmalloc
+{
+  /**
+   * Per-slab client meta: `max_count + 7` bytes of storage. With
+   * `StorageType = uint8_t`, the resulting extra_bytes
+   * (= (required_count - 1) * 1) is non-power-of-two for typical
+   * sizeclass slab object counts.
+   */
+  struct NonPow2ClientMetaDataProvider
+  {
+    using StorageType = uint8_t;
+    using DataRef = uint8_t&;
+
+    static size_t required_count(size_t max_count)
+    {
+      return max_count + 7;
+    }
+
+    static DataRef get(StorageType* base, size_t index)
+    {
+      return base[index];
+    }
+  };
+
+  using Config = snmalloc::StandardConfigClientMeta<NonPow2ClientMetaDataProvider>;
+} // namespace snmalloc
+
+#define SNMALLOC_PROVIDE_OWN_CONFIG
+#include <snmalloc/snmalloc.h>
+
+int main()
+{
+#if defined(SNMALLOC_ENABLE_GWP_ASAN_INTEGRATION)
+  // This test does not make sense in GWP-ASan mode.
+  return 0;
+#else
+  // Spread allocations across several small sizeclasses to force a
+  // variety of slab metadata sizes; each combination of (slab object
+  // count, +7 bytes) produces a different non-pow2 extra_bytes.
+  constexpr size_t sizes[] = {16, 48, 96, 192, 512, 1024};
+  std::vector<std::pair<void*, uint8_t>> ptrs;
+
+  for (size_t round = 0; round < 5; round++)
+  {
+    for (size_t s : sizes)
+    {
+      for (size_t i = 0; i < 200; i++)
+      {
+        auto p = snmalloc::libc::malloc(s);
+        auto& meta = snmalloc::get_client_meta_data(p);
+        uint8_t tag = static_cast<uint8_t>((round * 31 + s + i) & 0xff);
+        meta = tag;
+        memset(p, tag, s);
+        ptrs.emplace_back(p, tag);
+      }
+    }
+  }
+
+  for (auto [p, tag] : ptrs)
+  {
+    auto& meta = snmalloc::get_client_meta_data(p);
+    if (meta != tag)
+    {
+      std::cout << "Meta mismatch: expected " << int(tag) << " got "
+                << int(meta) << std::endl;
+      abort();
+    }
+    snmalloc::libc::free(p);
+  }
+
+  return 0;
+#endif
+}