Capacity absorption: binding mem_block::size to your allocator’s real granularity

reloco::mem_block (include/reloco/allocator.hpp) is the value every allocator_traits<Tag>::allocate/expand_in_place/reallocate returns:

struct [[nodiscard]] mem_block {
  void *ptr;
  std::size_t size; // actual capacity, guaranteed >= requested bytes
};

vector/sso_vector/basic_string/basic_sso_string all absorb size back into their own cap_ instead of keeping the originally requested size: after a grow, cap_ is exactly what the backend reported, in element units (res->size / sizeof(T), or - 1 for the null-terminated string types), never the smaller number the caller asked for. This guide explains why, when it helps, when it actively hurts, and how to bind it to a real allocator backend.

Why containers absorb the extra capacity

Every non-trivial allocator rounds requests up to some granularity it already had to pay for regardless of what the caller asked for: alignment padding, page-size rounding, or size-class/bin rounding in a slab/pool allocator. If a container ignores that and only remembers the size it asked for, every one of those already-paid-for bytes is invisible to capacity()/reserve()/growth math: the container reallocates again the moment it needs one more element, even though the previous block already had room, and repeats this on every subsequent growth step forever. Absorbing the backend’s real size turns that rounding from wasted slack into usable capacity, for free — no extra allocation, no extra bytes committed beyond what the backend already committed on its own.

The critical round-trip contract: old_size/bytes is the last returned size, not the original request

This is the one detail that matters most for a custom backend: once a container has absorbed a bigger size into cap_, every subsequent call back into the same backend for that block — expand_in_place’s old_size, reallocate’s old_size, deallocate’s bytes — is computed from that absorbed cap_, not from whatever smaller size was originally requested. For example (vector.hpp):

if (auto res = alloc_.expand_in_place(data_, cap_ * sizeof(T), required_bytes); res) {
  cap_ = *res / sizeof(T); // absorb again
  ...
}
...
alloc_.deallocate(data_, cap_ * sizeof(T)); // cap_, not the original request

A backend that reports a bigger size than requested must be able to accept that same bigger size back on every later call for that block. A naive backend that only tracks “the size the caller originally asked for” and asserts/rejects an unexpected larger old_size/bytes will break the first time a container reuses the absorbed capacity. If your backend cannot honor an arbitrary previously-returned size symmetrically across allocate/expand_in_place/reallocate/deallocate, do not report a rounded-up size in the first place — report exactly bytes (see below).

Two very different reasons to report a bigger size, and when each applies

mem_block::size being allowed to exceed the request serves two distinct audiences; conflating them is the most common mistake when binding a custom backend.

1. You are the author of your own general-purpose/arena allocator (the primary intended use)

If allocator_traits<Tag> is a thin adapter over an allocator you wrote — a bump/arena allocator, a slab allocator with fixed size classes (16/32/64/… byte bins), a pool allocator, a buddy allocator — then rounding up to the next bin/page/alignment boundary is not “extra, dangerous headroom you’re granting the caller”: it is memory your own allocator already reserved and committed for that block as an unavoidable consequence of how its internal bookkeeping works. Nothing external is watching that region for misuse (no sanitizer redzone, no guard page, no separate bookkeeping structure relies on the smaller number), so reporting the true bin/slab size back through mem_block::size costs nothing and is exactly what this feature is for: reloco’s containers get to use memory your allocator already owns instead of wasting it. stack_allocator.hpp’s bump-pointer backend (include/reloco/stack_allocator.hpp) is the simplest example of this shape in-tree, though it currently reports the exact requested size — see the worked example below for how a size-classed backend would differ.

2. You are wrapping a general-purpose system allocator (secondary, use with care)

The built-in heap_allocator_tag (include/reloco/heap_allocator.hpp, .ipp) wraps std::malloc/std::realloc/std::aligned_alloc and deliberately reports back exactly the requested bytes/new_size, even though glibc’s malloc (like most system allocators) actually rounds every request up to its own internal chunk-size granularity. That headroom is real, but it belongs to a general-purpose allocator whose internals reloco does not own or control — querying and using it is optional, and some platforms have no portable way to query it at all (see below).

If you do want that headroom, most system allocators expose a “how much did you actually give me” query:

Allocator Query Header
glibc malloc_usable_size(ptr) <malloc.h>
macOS/BSD malloc malloc_size(ptr) <malloc/malloc.h>
MSVC CRT _msize(ptr) (_aligned_msize(ptr, alignment, 0) for _aligned_malloc) <malloc.h>
mimalloc mi_malloc_usable_size(ptr) / mi_usable_size(ptr) <mimalloc.h>
jemalloc je_malloc_usable_size(ptr) / sallocx(ptr, 0) <jemalloc/jemalloc.h>
tcmalloc tc_malloc_size(ptr) / MallocExtension::GetAllocatedSize <gperftools/tcmalloc.h>, <gperftools/malloc_extension.h>
musl libc none portable — do not attempt this on musl —

A worked example, binding a your_heap_allocator_tag to glibc via malloc_usable_size:

struct your_heap_allocator_tag {};

template <> struct reloco::allocator_traits<your_heap_allocator_tag> {
  using context_type = void;

  static result<mem_block> allocate(std::size_t bytes, std::size_t alignment) noexcept {
    void *ptr = alignment <= alignof(std::max_align_t)
        ? std::malloc(bytes == 0 ? 1 : bytes)
        : detail::heap_aligned_alloc(alignment, bytes == 0 ? alignment : bytes);
    if (!ptr) return unexpected(reloco::error::allocation_failed);
#if !defined(RELOCO_SANITIZE_MEMORY)
    // Report the real chunk size: containers get to use the rounding
    // glibc already committed, instead of reallocating one element later.
    return mem_block{ptr, malloc_usable_size(ptr)};
#else
    // See "Sanitizers" below: never claim more than what was requested
    // when a memory-checking tool is active.
    return mem_block{ptr, bytes};
#endif
  }

  static void deallocate(void *ptr, std::size_t /* bytes: last-reported size, see above */) noexcept {
    std::free(ptr);
  }

  // reallocate() follows the same pattern: realloc(), then wrap the
  // result's malloc_usable_size() the same way, guarded identically.
};

Note the deallocate/realloc calls above never need to pass the absorbed size back to free/realloc themselves — glibc’s own free/realloc recover the real block size from their own heap metadata, not from the caller. This is specific to malloc-family allocators; a size-classed allocator you wrote yourself typically does need the caller-supplied size (or must recompute the same bin from it), which is exactly why the round-trip contract above matters for that case.

Sanitizers (ASan/MSan/HWASan) and Valgrind: never report more than the exact request

When building under AddressSanitizer, MemorySanitizer, HWASan, or Valgrind, an allocator backend must report exactly the requested bytes/new_size, never a rounded-up or queried “usable size”. These tools instrument the system allocator itself: the bytes between your requested size and the real, larger underlying chunk are deliberately poisoned redzone, used to catch heap-buffer-overflow and use-after-free bugs. If a backend queries and reports that larger size (e.g. via malloc_usable_size under ASan — which, notably, ASan’s own interceptor already special-cases to return the requested, not real, size for exactly this reason), and a container then absorbs it into cap_ and later writes into that “capacity”, every one of those writes lands in poisoned redzone memory. The sanitizer is not wrong to flag it — that memory was never actually available; claiming otherwise defeats the overflow detection the sanitizer exists to provide, turning true diagnostic hits into what looks like container false-positives.

Guard any capacity-absorbing query in your own backend the same way the worked example above does:

#if defined(__SANITIZE_ADDRESS__) || defined(__SANITIZE_MEMORY__) || \
    (defined(__has_feature) && (__has_feature(address_sanitizer) || __has_feature(memory_sanitizer))) || \
    defined(RELOCO_SANITIZE_MEMORY) // your own build-system flag, e.g. under Valgrind
  return mem_block{ptr, bytes};
#else
  return mem_block{ptr, malloc_usable_size(ptr)};
#endif

This restriction is specific to case 2 above (wrapping a general system allocator instrumented by the sanitizer). It does not apply to case 1: your own arena/slab/pool allocator’s internal bins are not what a sanitizer’s malloc interceptor instruments or poisons, so reporting their true size remains exactly as safe under a sanitizer build as without one — sanitizers only add redzones around the system allocator calls your arena itself may or may not make internally (e.g. once per whole arena/slab, not once per allocate() call).

See also