it::d4np::memorypool::Pool Class Reference

Owning, non-copyable, move-only wrapper around a memory_pool_t*. More...

#include <memory_pool.hpp>

Public Member Functions
	Pool (std::size_t block_size, std::size_t block_count)
	Construct a pool with block_count blocks of block_size bytes each.
	~Pool () noexcept
	Destroy the pool, releasing all backing storage to the OS.
	Pool (const Pool &)=delete
Pool &	operator= (const Pool &)=delete
	Pool (Pool &&other) noexcept
	Move-construct from other, leaving other in a valid empty state.
Pool &	operator= (Pool &&other) noexcept
	Move-assign from other, releasing the current pool first.
void *	allocate ()
	Allocate one block in O(1) — throwing verb (ADR-0016 §2).
void *	try_allocate () noexcept
	Allocate one block in O(1) — non-throwing verb (ADR-0016 §2).
void	deallocate (void *block) noexcept
	Return a previously allocated block to the pool in O(1).
memory_pool_t *	native_handle () noexcept
std::size_t	metadata_bytes () const noexcept
	Report the per-pool metadata overhead in bytes (spec §3.2 / ADR-0015).
std::size_t	block_size () const noexcept
	Report the configured per-block size in bytes (ADR-0018 §3).

Static Public Member Functions
static std::optional< Pool >	make (std::size_t block_size, std::size_t block_count)
	Factory function returning an engaged std::optional<Pool> on successful construction or std::nullopt on failure (any precondition violation from ADR-0009 §2 / §3, or backing-storage allocation failure).
static std::optional< Pool >	make_dynamic (std::size_t block_size, std::size_t block_count, std::size_t growth_factor)
	Factory function for a dynamic-growth pool (spec §2.2, ADR-0022 / ADR-0024): on exhaustion it acquires a new contiguous chunk so capacity grows geometrically by growth_factor, rather than failing.

Detailed Description

Owning, non-copyable, move-only wrapper around a memory_pool_t*.

On construction the wrapper calls memory_pool_create; on destruction it calls memory_pool_destroy. Allocation is exposed through allocate and deallocate to match std::allocator-style naming, with the same semantics as the underlying C calls.

Layout is exactly sizeof(void*) — a single memory_pool_t* data member; the C handle is the Pimpl (ADR-0010). Copy operations are deleted (the pool handle has unique ownership of its backing buffer; a copy would double-free at destruction). Move operations leave the source in a valid empty state (handle_ == nullptr) so its destructor is a safe no-op.

The exception policy at the C/C++ boundary is fixed by ADR-0016: the C ABI never throws (every C failure is NULL / no-op), while the C++ surface offers both policies side by side — allocate throws std::bad_alloc on failure, try_allocate is noexcept and returns nullptr. Construction follows the same split: this ctor throws std::bad_alloc when the underlying memory_pool_create fails, while make and PoolBuilder report failure as std::nullopt.

Definition at line 51 of file memory_pool.hpp.

Constructor & Destructor Documentation

Pool()

it::d4np::memorypool::Pool::Pool	(	std::size_t	block_size,
		std::size_t	block_count
	)

Construct a pool with block_count blocks of block_size bytes each.

Parameters

block_size	Size of each block in bytes. Must satisfy ADR-0009 §2: block_size >= sizeof(void*) and block_size is a multiple of alignof(std::max_align_t).
block_count	Number of blocks the pool can vend; must be greater than zero, and block_size * block_count must not overflow size_t (ADR-0009 §3).

Exceptions

std::bad_alloc

when memory_pool_create returns NULL — on backing-storage allocation failure or on any ADR-0009 §2 / §3 precondition violation. The two causes collapse to one exception because the C boundary reports both as NULL (ADR-0016 §3).

Note

Callers wanting failure as a value instead of an exception should use make or PoolBuilder — see ADR-0011 and ADR-0016 §3.

Member Function Documentation

make()

static std::optional< Pool > it::d4np::memorypool::Pool::make ( std::size_t  block_size, std::size_t  block_count  )

static

Factory function returning an engaged std::optional<Pool> on successful construction or std::nullopt on failure (any precondition violation from ADR-0009 §2 / §3, or backing-storage allocation failure).

See ADR-0011 §1 for the design rationale and the comparison with direct ctor invocation.

Parameters

block_size	Same contract as the ctor — ADR-0009 §2.
block_count	Same contract as the ctor — ADR-0009 §3.

make_dynamic()

static std::optional< Pool > it::d4np::memorypool::Pool::make_dynamic ( std::size_t  block_size, std::size_t  block_count, std::size_t  growth_factor  )

static

Factory function for a dynamic-growth pool (spec §2.2, ADR-0022 / ADR-0024): on exhaustion it acquires a new contiguous chunk so capacity grows geometrically by growth_factor, rather than failing.

Parameters

block_size	Same contract as make — ADR-0009 §2.
block_count	Initial block count — ADR-0009 §3.
growth_factor	Geometric factor; must be at least 2.

Returns

Engaged optional on success, or std::nullopt on any precondition violation, OOM, a growth_factor < 2, or — in a library built with the lock-free policy — always, because dynamic growth is unsupported there (ADR-0024 §2).

allocate()

void * it::d4np::memorypool::Pool::allocate

(

)

Allocate one block in O(1) — throwing verb (ADR-0016 §2).

Returns

Pointer to the block; never nullptr.

Exceptions

std::bad_alloc

when the pool is exhausted, or when the wrapper is empty (moved-from) — the null handle is indistinguishable from exhaustion at the C boundary (ADR-0016 §2).

Note

The non-throwing variant is try_allocate. The verb naming follows std::allocator::allocate / the Cpp17Allocator requirements, which the Milestone 3.3 Adapter forwards to.

try_allocate()

void * it::d4np::memorypool::Pool::try_allocate ( )

noexcept

Allocate one block in O(1) — non-throwing verb (ADR-0016 §2).

Exact v0.2.0 allocate() semantics: a thin noexcept forwarder to memory_pool_alloc with failure reported in-band.

Returns

Pointer to the block, or nullptr when the pool is exhausted or the wrapper is empty (moved-from).

deallocate()

void it::d4np::memorypool::Pool::deallocate ( void *  block )

noexcept

Return a previously allocated block to the pool in O(1).

Parameters

block

Block to release, or nullptr (no-op).

native_handle()

memory_pool_t * it::d4np::memorypool::Pool::native_handle ( )

noexcept

Returns

The underlying C handle. Useful for interop with code that only knows the C API. The wrapper retains ownership.

metadata_bytes()

std::size_t it::d4np::memorypool::Pool::metadata_bytes ( ) const

noexcept

Report the per-pool metadata overhead in bytes (spec §3.2 / ADR-0015).

Forwards to memory_pool_metadata_bytes. The returned value is O(1) in both block_count and block_size — a pool with one million blocks reports the same number as a pool with one. Per-block external metadata is zero by construction (implicit free list, ADR-0009 §1).

Returns

Bytes of pool-internal metadata, or 0 on a moved-from wrapper whose handle is null.

block_size()

std::size_t it::d4np::memorypool::Pool::block_size ( ) const

noexcept

Report the configured per-block size in bytes (ADR-0018 §3).

Forwards to memory_pool_block_size. The value is fixed for the pool's lifetime and the call is O(1). The STL allocator adapter PoolAllocator<T> uses it to decide whether an object of a given size fits in a single block before routing a request to the pool.

Returns

The pool's block_size in bytes, or 0 on a moved-from wrapper whose handle is null.

---

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

• src/main/cpp/it/d4np/memorypool/memory_pool.hpp