pool_hardening.hpp File Reference

Opt-in debug-hardening surface for the free list — ADR-0043. More...

#include <it/d4np/memorypool/memory_pool.h>

Go to the source code of this file.

Typedefs
using	it::d4np::memorypool::HardeningViolationHandler = void(*)(const char *kind, const void *block) noexcept
	Handler invoked when the hardening layer detects a violation.

Functions
HardeningViolationHandler	it::d4np::memorypool::set_hardening_violation_handler (HardeningViolationHandler handler) noexcept
	Install handler as the hardening violation handler and return the previous one.
HardeningViolationHandler	it::d4np::memorypool::hardening_violation_handler () noexcept

Variables
constexpr const char *	it::d4np::memorypool::HARDENING_USE_AFTER_FREE = "use-after-free"
	A write to a freed block's poisoned payload was detected on allocation.
constexpr const char *	it::d4np::memorypool::HARDENING_OVERFLOW = "buffer-overflow"
	A contiguous write past block_size corrupted the trailing guard word.
constexpr const char *	it::d4np::memorypool::HARDENING_DOUBLE_FREE = "double-free"
	The same block was freed twice (its guard still read as freed).
constexpr const char *	it::d4np::memorypool::HARDENING_FREELIST_CORRUPTION = "free-list-corruption"
	A free-list slot's guard or next-link was corrupted (integrity check).

Detailed Description

Opt-in debug-hardening surface for the free list — ADR-0043.

When the library is built with PBR_MEMORY_POOL_HARDENING (a compile-time knob, OFF by default — see the CMake option of the same name), the pool's intrusive free list gains three self-contained protections against the classic use-after-free / pointer-corruption primitives an intrusive free list exposes (ADR-0009 §1):

1. Freed-block poisoning — a freed block's payload is filled with a recognizable byte pattern; a write to freed memory is caught on the next allocation of that block (use-after-free).
2. Guard word — a trailing guard word per slot detects a contiguous write past block_size (buffer overflow) and a repeated free of the same block (double-free), deterministically.
3. Free-list safe-linking — the in-band next-pointer is stored XORed with a per-slot key (glibc's PROTECT_PTR/REVEAL_PTR), so a leaked or overwritten next-link is neither directly usable nor silently followed; corruption surfaces as an alignment fault on reveal.

Release builds are byte-for-byte and cycle-for-cycle unchanged — the entire mechanism is compiled out when the knob is off, and this header is then a no-op. A hardened build changes the on-disk free-list encoding and the physical slot stride, so it is deliberately not memory-layout-compatible with a non-hardened build: never mix the two configurations.

This header exposes only the violation policy hook. On a detected violation the library calls the installed handler; the default handler prints a diagnostic and calls std::abort() (the ADR-0012 "defined, loud failure" stance). Tests install a recording handler so a violation can be asserted without terminating the process.

Definition in file pool_hardening.hpp.

Typedef Documentation

HardeningViolationHandler

using it::d4np::memorypool::HardeningViolationHandler = typedef void (*)(const char* kind, const void* block) noexcept

Handler invoked when the hardening layer detects a violation.

Parameters

kind	A stable, static string naming the violation — one of the HARDENING_* constants below.
block	Address of the offending block (for the diagnostic).

The handler is noexcept: it is called from the pool's noexcept allocate/deallocate path. The default handler does not return (it aborts); a handler that does return lets the operation continue on a best-effort, no-further-corruption path (used by the tests).

Definition at line 59 of file pool_hardening.hpp.

Function Documentation

set_hardening_violation_handler()

HardeningViolationHandler it::d4np::memorypool::set_hardening_violation_handler ( HardeningViolationHandler  handler )

noexcept

Install handler as the hardening violation handler and return the previous one.

Passing nullptr restores the default (diagnostic + abort). Thread-safe. Present only in hardened builds.

hardening_violation_handler()

HardeningViolationHandler it::d4np::memorypool::hardening_violation_handler ( )

noexcept

Returns

The currently installed hardening violation handler.

Variable Documentation

HARDENING_USE_AFTER_FREE

constexpr const char* it::d4np::memorypool::HARDENING_USE_AFTER_FREE = "use-after-free"

inlineconstexpr

A write to a freed block's poisoned payload was detected on allocation.

Definition at line 62 of file pool_hardening.hpp.

HARDENING_OVERFLOW

constexpr const char* it::d4np::memorypool::HARDENING_OVERFLOW = "buffer-overflow"

inlineconstexpr

A contiguous write past block_size corrupted the trailing guard word.

Definition at line 64 of file pool_hardening.hpp.

HARDENING_DOUBLE_FREE

constexpr const char* it::d4np::memorypool::HARDENING_DOUBLE_FREE = "double-free"

inlineconstexpr

The same block was freed twice (its guard still read as freed).

Definition at line 66 of file pool_hardening.hpp.

HARDENING_FREELIST_CORRUPTION

constexpr const char* it::d4np::memorypool::HARDENING_FREELIST_CORRUPTION = "free-list-corruption"

inlineconstexpr

A free-list slot's guard or next-link was corrupted (integrity check).

Definition at line 68 of file pool_hardening.hpp.