Per-tier free-list pool with runtime statistics and oversized passthrough. More...

#include <memory_pool.h>

Collaboration diagram for vlink::MemoryPool:

Classes
struct	Config
	Constructor configuration grouping the tier list and the preallocation toggle. More...

struct	OversizedStats
	Statistics for allocations that bypass the tier free lists. More...

struct	Tier
	Descriptor for one size class. More...

struct	TierStats
	Per-tier runtime statistics snapshot. More...

Public Member Functions
	MemoryPool ()
	Constructs an empty pool in bypass mode. More...

	MemoryPool (int level, bool prealloc=false)
	Constructs a tiered pool using the built-in pyramid for `level`. More...

	MemoryPool (const Config &config)
	Constructs a tiered pool with an explicit configuration. More...

	~MemoryPool ()
	Releases every owned chunk unconditionally. More...

void *	allocate (size_t bytes, size_t alignment=kBlockAlignment) noexcept
	Allocates `bytes` of memory from the appropriate tier. More...

void	deallocate (void *p, size_t bytes, size_t alignment=kBlockAlignment) noexcept
	Returns a block previously allocated through `allocate` to the pool. More...

size_t	get_tier_count () const noexcept
	Returns the number of live managed tiers. More...

std::vector< TierStats >	get_stats () const noexcept
	Returns a snapshot of per-tier statistics. More...

OversizedStats	get_oversized_stats () const noexcept
	Returns a snapshot of the oversized-passthrough statistics. More...

void	reset_stats () noexcept
	Resets per-call statistics counters to zero. More...

void	clear () noexcept
	Releases only fully-free chunks; preserves chunks still backing live allocations. More...

void	trim () noexcept
	Alias of `clear` with a name suited to periodic-trim phrasing. More...

Static Public Member Functions
static Config	get_default_config ()
	Returns the default tier pyramid using `VLINK_MEMORY_LEVEL` / `VLINK_MEMORY_PREALLOC`. More...

static MemoryPool &	global_instance (bool use_env_level=true)
	Returns the process-wide shared `MemoryPool` instance. More...

Static Public Attributes
static constexpr size_t	kBlockAlignment = alignof(std::max_align_t)
	Default block alignment for every pooled allocation. More...

Detailed Description

Per-tier free-list pool with runtime statistics and oversized passthrough.

Thread-safe. Each tier owns its own spin lock so allocate, deallocate and clear on different size classes never contend. Bypass mode – selected by an empty tier list – routes every request through the global allocator without any pooling.

Constructor & Destructor Documentation

◆ MemoryPool() [1/3]

vlink::MemoryPool::MemoryPool ( )

Constructs an empty pool in bypass mode.

Equivalent to MemoryPool(Config{}): every request hits ::operator new / delete.

◆ MemoryPool() [2/3]

vlink::MemoryPool::MemoryPool	(	int	level,
		bool	prealloc = `false`
	)

explicit

Constructs a tiered pool using the built-in pyramid for level.

Out-of-range values are clamped to [0, 9] and a warning is logged. Level 0 yields bypass mode; the prealloc flag is ignored in that case. Level 9 fully saturates to roughly 656 MiB of resident memory.

Parameters

level	Built-in level in [0, `9`].
prealloc	When `true`, fills every tier to its quota on construction (best effort). Default: `false`.

◆ MemoryPool() [3/3]

vlink::MemoryPool::MemoryPool ( const Config & config )

explicit

Constructs a tiered pool with an explicit configuration.

Empty config.tiers selects bypass mode. Sentinel entries with blocks_per_chunk == 0 declare a size ceiling but are stripped at construction; an all-sentinel list is therefore equivalent to bypass mode. Malformed input (non-monotonic ordering, duplicate max_size, zero max_size or max_size below the minimum block size) logs an error and silently falls back to the level-3 default pyramid. std::bad_alloc may propagate from internal vector growth.

Parameters

config Tier descriptors and preallocation flag.

◆ ~MemoryPool()

vlink::MemoryPool::~MemoryPool ( )

Releases every owned chunk unconditionally.

Warning: The caller must guarantee no outstanding pooled block is in use and no other thread is calling allocate, deallocate, clear or trim on this instance. Use clear for a non-destructive trim.

Member Function Documentation

◆ allocate()

void* vlink::MemoryPool::allocate	(	size_t	bytes,
		size_t	alignment = `kBlockAlignment`
	)

noexcept

Allocates bytes of memory from the appropriate tier.

Routes to the first tier whose max_size is >= bytes. Requests larger than the biggest tier or with alignment > kBlockAlignment bypass the pool. bytes == 0 routes to the smallest tier and still returns a unique non-null pointer that must be passed back to deallocate with the same 0 size. Never throws.

Parameters

bytes	Requested size.
alignment	Required alignment (power of two). Default: `kBlockAlignment`.

Returns: Pointer to allocated memory, or nullptr on upstream OOM.

◆ clear()

void vlink::MemoryPool::clear ( )

noexcept

Releases only fully-free chunks; preserves chunks still backing live allocations.

For each tier the free list is grouped by owning chunk; chunks whose free-node count equals their block capacity are released, others stay intact. chunk_count is decremented by the number of released chunks. Safe to call concurrently with allocate and deallocate. Per-tier work is O(C log C + F log C) under the spin lock.

◆ deallocate()

void vlink::MemoryPool::deallocate	(	void *	p,
		size_t	bytes,
		size_t	alignment = `kBlockAlignment`
	)

noexcept

Returns a block previously allocated through allocate to the pool.

Parameters

p	Pointer returned by `allocate`. `nullptr` is a no-op.
bytes	Original size passed to `allocate`; MUST match.
alignment	Original alignment passed to `allocate`.

◆ get_default_config()

static Config vlink::MemoryPool::get_default_config ( )

static

Returns the default tier pyramid using VLINK_MEMORY_LEVEL / VLINK_MEMORY_PREALLOC.

Each level 0..9 maps to a hand-coded row of {max_size, blocks_per_chunk} pairs. Level 0 is bypass mode. Levels 1..9 return 19 entries covering 32 B to 16 MiB; the 1 MiB / 4 MiB / 8 MiB / 16 MiB ceilings activate at level 2 / 4 / 5 / 6 and are sentinels below those thresholds. Within each level the 32 B head tier carries twice the blocks_per_chunk of the 64 B tier to absorb high-density tiny allocations.

VLINK_MEMORY_PREALLOC controls the prealloc flag; only the literal value "1" enables preallocation.

Returns: Config ready to pass to the constructor.

◆ get_oversized_stats()

OversizedStats vlink::MemoryPool::get_oversized_stats ( ) const

noexcept

Returns a snapshot of the oversized-passthrough statistics.

Counters are loaded with relaxed ordering and are not a globally atomic snapshot.

Returns: Aggregated counters for the oversized path.

◆ get_stats()

std::vector<TierStats> vlink::MemoryPool::get_stats ( ) const

noexcept

Returns a snapshot of per-tier statistics.

Returns: Vector with one entry per live tier.

◆ get_tier_count()

size_t vlink::MemoryPool::get_tier_count ( ) const

noexcept

Returns the number of live managed tiers.

0 indicates bypass mode. Sentinel entries are stripped at construction so the count reflects only tiers backed by a live free list.

Returns: Tier count after sentinel stripping.

◆ global_instance()

static MemoryPool& vlink::MemoryPool::global_instance ( bool use_env_level = true )

static

Returns the process-wide shared MemoryPool instance.

Lazy Meyers singleton. Only the first call decides the configuration; subsequent calls return the same instance and ignore the argument.

Warning: Whichever value use_env_level takes on the first call is baked in for the rest of the program's lifetime.

Parameters

use_env_level true (default): use get_default_config and honour the environment. false: use the built-in level-3 pyramid.

Returns: Reference to the global pool.

◆ reset_stats()

void vlink::MemoryPool::reset_stats ( )

noexcept

Resets per-call statistics counters to zero.

Clears hit_count and deallocate_count on every tier and the oversized_* counters. Physical / lifetime state (chunk_count, upstream_alloc_count, upstream_alloc_bytes) is preserved.

◆ trim()

void vlink::MemoryPool::trim ( )

noexcept

Alias of clear with a name suited to periodic-trim phrasing.

Behaviour, complexity and thread-safety are identical to clear.

Member Data Documentation

◆ kBlockAlignment

constexpr size_t vlink::MemoryPool::kBlockAlignment = alignof(std::max_align_t)

staticconstexpr

Default block alignment for every pooled allocation.

Equal to alignof(std::max_align_t). Stricter alignments bypass the pool and request memory directly through ::operator new with std::align_val_t.

The documentation for this class was generated from the following file:

include/vlink/base/memory_pool.h

Classes

Public Member Functions

Static Public Member Functions

Static Public Attributes

Detailed Description

Constructor & Destructor Documentation

◆ MemoryPool() [1/3]

◆ MemoryPool() [2/3]

◆ MemoryPool() [3/3]

◆ ~MemoryPool()

Member Function Documentation

◆ allocate()

◆ clear()

◆ deallocate()

◆ get_default_config()

◆ get_oversized_stats()

◆ get_stats()

◆ get_tier_count()

◆ global_instance()

◆ reset_stats()

◆ trim()

Member Data Documentation

◆ kBlockAlignment