memory_pool.h

Go to the documentation of this file.

/*
 * SPDX-License-Identifier: MIT
 * Copyright (c) 2026 Daniel Polo
 */
 
#ifndef IT_D4NP_MEMORYPOOL_MEMORY_POOL_H_
#define IT_D4NP_MEMORYPOOL_MEMORY_POOL_H_
 
#include <stddef.h>
 
/*
 * Diagnostics gate (ADR-0019 §1). A single macro controls the entire
 * free-list diagnostic surface: the C accessors below and the C++
 * `free_list_iterator.hpp` iterator. The default is build-type driven so
 * the surface is available in debug builds and compiled out of release
 * builds; an explicit definition (e.g. the CMake option
 * PBR_MEMORY_POOL_ENABLE_DIAGNOSTICS, which defines it to 1 PUBLIC-ly on
 * the library target) always wins. Walking the free list is O(free_count)
 * and has no place on the allocation hot path — hence "disabled in release
 * unless explicitly enabled" (ROADMAP 3.4).
 */
/* This is a preprocessor gate (it drives `#if` below and in the C++
 * iterator header), so it must be a macro, not a constexpr constant — hence
 * the cppcoreguidelines-macro-usage suppression around the definitions. */
/* NOLINTBEGIN(cppcoreguidelines-macro-usage) */
#ifndef PBR_MEMORY_POOL_DIAGNOSTICS
#ifdef NDEBUG
#define PBR_MEMORY_POOL_DIAGNOSTICS 0
#else
#define PBR_MEMORY_POOL_DIAGNOSTICS 1
#endif
#endif
/* NOLINTEND(cppcoreguidelines-macro-usage) */
 
/*
 * Thread-safety mode (ADR-0020 §2). Selects how the implementation
 * synchronizes the free-list head: NONE (no synchronization — the
 * single-thread fast path, spec §2.4), MUTEX (a std::mutex), or LOCKFREE
 * (an ABA-tagged Treiber-stack CAS). Bound at COMPILE TIME (a policy
 * selected once, not a per-call branch) so the single-thread build pays
 * nothing. Selected library-wide at build time via the
 * PBR_MEMORY_POOL_THREAD_SAFETY macro (CMake option); the default is NONE.
 * These are preprocessor constants (they drive `#if` selection in
 * memory_pool.cpp), hence the cppcoreguidelines-macro-usage suppression.
 */
/* NOLINTBEGIN(cppcoreguidelines-macro-usage) */
#define PBR_MEMORY_POOL_THREAD_SAFETY_NONE 0
#define PBR_MEMORY_POOL_THREAD_SAFETY_MUTEX 1
#define PBR_MEMORY_POOL_THREAD_SAFETY_LOCKFREE 2
#ifndef PBR_MEMORY_POOL_THREAD_SAFETY
#define PBR_MEMORY_POOL_THREAD_SAFETY PBR_MEMORY_POOL_THREAD_SAFETY_NONE
#endif
/* NOLINTEND(cppcoreguidelines-macro-usage) */
 
/*
 * Opt-in debug-hardening gate (ADR-0043). When 1, the intrusive free list
 * gains freed-block poisoning, a per-slot guard word (overflow + double-free
 * detection), and next-pointer safe-linking; see pool_hardening.hpp. OFF by
 * default — a release build is byte-for-byte unchanged. Set library-wide at
 * build time via the PBR_MEMORY_POOL_HARDENING CMake option (defined PUBLIC,
 * because a hardened build changes the on-disk free-list layout, so the
 * library and every consumer must agree). Preprocessor gate → a macro, not a
 * constexpr constant; hence the cppcoreguidelines-macro-usage suppression.
 */
/* NOLINTBEGIN(cppcoreguidelines-macro-usage) */
#ifndef PBR_MEMORY_POOL_HARDENING
#define PBR_MEMORY_POOL_HARDENING 0
#endif
/* NOLINTEND(cppcoreguidelines-macro-usage) */
 
#ifdef __cplusplus
extern "C" {
#endif
 
/* The struct tag is snake_case to match the C convention for forward-
 * declared opaque types; the .clang-tidy StructCase rule (CamelCase) is
 * the right default for new C++ types, suppressed here for the C-interop
 * boundary per the same rationale recorded at the definition site in
 * memory_pool.cpp. */
/* NOLINTNEXTLINE(readability-identifier-naming) */
typedef struct memory_pool memory_pool_t;
 
memory_pool_t* memory_pool_create(size_t block_size, size_t block_count);
 
memory_pool_t* memory_pool_create_dynamic(size_t block_size, size_t block_count, size_t growth_factor);
 
void* memory_pool_alloc(memory_pool_t* pool);
 
void memory_pool_free(memory_pool_t* pool, void* block);
 
void memory_pool_destroy(memory_pool_t* pool);
 
size_t memory_pool_metadata_bytes(const memory_pool_t* pool);
 
size_t memory_pool_block_size(const memory_pool_t* pool);
 
size_t memory_pool_growths(const memory_pool_t* pool);
 
#if PBR_MEMORY_POOL_DIAGNOSTICS
 
const void* memory_pool_debug_free_list_head(const memory_pool_t* pool);
 
const void* memory_pool_debug_free_list_next(const memory_pool_t* pool, const void* current);
 
size_t memory_pool_debug_free_count(const memory_pool_t* pool);
 
#endif /* PBR_MEMORY_POOL_DIAGNOSTICS */
 
#ifdef __cplusplus
}
#endif
 
#endif