prf::net::pool::Ipv4PoolManager class final
#include <net/pool/pool_manager.hpp>

Fixed-footprint IPv4 pool manager for static and dynamic pools.

The manager is initialized once by a scenario with known poolX sections. Each pool gets a fixed allocation budget derived from max_allocations; the manager then serves offer, commit, renew, and release operations without allocating heap memory per pool.

Typical usage:

prf::net::pool::Ipv4PoolManager pools;
std::array<prf::net::pool::cfg::PoolConfigSection*, 2> sections{{&pool1, &pool2}};
if (pools.init(sections)) {
    prf::net::pool::PoolAllocation alloc{};
    auto client = prf::net::pool::PoolClientIdentity{};
    prf::net::pool::make_pool_client_identity("us0", &client);
    pools.acquire_committed("pool1", client, 1u, UINT64_MAX, &alloc);
}

Base classes

class IPoolSourceSink: Sink used by runtime publishers of dynamic address ranges.

Public types

using AllocationVisitorFn = bool(*)(const PoolAllocationEntryView&entry, void*user_ctx): Callback used by allocation enumeration helpers.

Public static variables

static size_t kMaxAllocationsTotal constexpr: Global allocation entry budget shared across all pools.
static size_t kMaxPools constexpr: Maximum number of scenario-provided pools supported by this runtime.

Public functions

auto acquire_committed(std::string_view pool_section, const PoolClientIdentity& client, uint16_t ip_count, uint64_t expires_at_ms, PoolAllocation* out) -> bool: Acquires or reuses a committed allocation for one client.
auto acquire_committed_with_snapshot(std::string_view pool_section, const PoolClientIdentity& client, uint16_t ip_count, uint64_t expires_at_ms, PoolAllocation* out_allocation, PoolSnapshot* out_snapshot) -> bool: Acquires or reuses a committed allocation and returns the matching pool snapshot generation.
auto classify_ip_in_pool(std::string_view pool_section, uint32_t ip, PoolIpClass* out_class) const -> bool: Classifies one IPv4 address against current effective pool snapshot.
auto clear_source_snapshot(std::string_view source_interface) -> bool override: Invalidates all dynamic pools bound to one source interface.
auto commit_offer(std::string_view pool_section, const PoolClientIdentity& client, uint32_t ip_start, uint64_t expires_at_ms, PoolAllocation* out) -> bool: Converts an offered allocation into a committed one.
auto init(std::span<cfg::PoolConfigSection*const> sections) -> bool: Binds manager to scenario-owned pool config sections for whole runtime lifetime.
auto list_allocations(std::string_view pool_section, PoolAllocationEntryView* out, size_t max_count) const -> size_t: Enumerates current allocations for observability or tests.
auto offer_temporary(std::string_view pool_section, const PoolClientIdentity& client, uint16_t ip_count, uint64_t expires_at_ms, PoolAllocation* out) -> bool: Offers a temporary block to a client without committing it yet.
auto publish_source_snapshot(std::string_view source_interface, const PoolSourceSnapshot& snapshot) -> bool override: Updates all dynamic pools bound to one source interface.
auto release_allocation(std::string_view pool_section, const PoolClientIdentity& client) -> bool: Releases a committed or offered allocation belonging to one client.
auto renew_allocation(std::string_view pool_section, const PoolClientIdentity& client, uint64_t expires_at_ms) -> bool: Extends lifetime of an existing committed allocation.
void service_timeouts(uint64_t now_ms): Removes expired offers and leases from all configured pools.
auto snapshot_pool(std::string_view pool_section, PoolSnapshot* out) const -> bool: Returns the current effective snapshot of one pool.
auto visit_allocations(std::string_view pool_section, AllocationVisitorFn visitor, void* user_ctx) const -> size_t: Visits active allocations without requiring a temporary output buffer.

Function documentation

bool prf::net::pool::Ipv4PoolManager::acquire_committed(std::string_view pool_section, const PoolClientIdentity& client, uint16_t ip_count, uint64_t expires_at_ms, PoolAllocation* out)

Acquires or reuses a committed allocation for one client.

Returns	`true` when a committed block exists or was created.

Repeated calls with the same client_id, generation, and ip_count return the same allocation.

bool prf::net::pool::Ipv4PoolManager::acquire_committed_with_snapshot(std::string_view pool_section, const PoolClientIdentity& client, uint16_t ip_count, uint64_t expires_at_ms, PoolAllocation* out_allocation, PoolSnapshot* out_snapshot)

Acquires or reuses a committed allocation and returns the matching pool snapshot generation.

Parameters
pool_section	Section name such as `pool1`.
client	Stable pool client identity.
ip_count	Number of contiguous addresses requested.
expires_at_ms	Absolute expiration time, or `UINT64_MAX`.
out_allocation	Output allocation, optional.
out_snapshot	Output effective pool snapshot for the same generation.
Returns	`true` when allocation exists or was created successfully.

This method closes races between allocation and snapshot fetch by doing both under one manager lock.

bool prf::net::pool::Ipv4PoolManager::classify_ip_in_pool(std::string_view pool_section, uint32_t ip, PoolIpClass* out_class) const

Classifies one IPv4 address against current effective pool snapshot.

Parameters
pool_section	Section name such as `pool1`.
ip	IPv4 address in host-order u32 representation.
out_class	Output class.
Returns	`true` when pool exists, refresh succeeded, and output was written.

This helper refreshes named pool and then applies classify_ip_against_pool(...) on the resulting effective snapshot.

bool prf::net::pool::Ipv4PoolManager::clear_source_snapshot(std::string_view source_interface) override

Invalidates all dynamic pools bound to one source interface.

Returns	`true` when at least one dynamic pool observed the clear.

bool prf::net::pool::Ipv4PoolManager::commit_offer(std::string_view pool_section, const PoolClientIdentity& client, uint32_t ip_start, uint64_t expires_at_ms, PoolAllocation* out)

Converts an offered allocation into a committed one.

Returns	`true` when the offered block matched `client` and `ip_start`.

bool prf::net::pool::Ipv4PoolManager::init(std::span<cfg::PoolConfigSection*const> sections)

Binds manager to scenario-owned pool config sections for whole runtime lifetime.

Parameters
sections	Stable typed pool section pointers, usually `pool1..poolN`.
Returns	`true` when all sections parsed successfully and fit into the global allocation budget.

Per-pool allocation budget is fixed here from max_allocations. Changing max_allocations in live config after init is unsupported and causes subsequent refresh-backed operations on that pool to fail until the manager is reinitialized. Binds the manager to scenario-owned pool sections.

All sections must stay alive for the whole manager lifetime.

size_t prf::net::pool::Ipv4PoolManager::list_allocations(std::string_view pool_section, PoolAllocationEntryView* out, size_t max_count) const

Enumerates current allocations for observability or tests.

Parameters
pool_section	Section name such as `pool1`.
out	Optional output buffer.
max_count	Capacity of `out`.
Returns	Number of active allocations currently stored for the pool.

When out is null, the method still returns the total count.

bool prf::net::pool::Ipv4PoolManager::offer_temporary(std::string_view pool_section, const PoolClientIdentity& client, uint16_t ip_count, uint64_t expires_at_ms, PoolAllocation* out)

Offers a temporary block to a client without committing it yet.

Returns	`true` when a temporary block exists or was created.

This is intended for future DHCP-style two-phase assignment.

bool prf::net::pool::Ipv4PoolManager::publish_source_snapshot(std::string_view source_interface, const PoolSourceSnapshot& snapshot) override

Updates all dynamic pools bound to one source interface.

Returns	`true` when at least one dynamic pool accepted the update.

Example:

prf::net::pool::PoolSourceSnapshot src{};
src.valid = true;
src.ip_start = 0x0A0A0001u;
src.ip_size = 8u;
src.subnet_mask = 0xFFFFFF00u;
manager.publish_source_snapshot("np2", src);

bool prf::net::pool::Ipv4PoolManager::release_allocation(std::string_view pool_section, const PoolClientIdentity& client)

Releases a committed or offered allocation belonging to one client.

Returns	`true` when the client had an allocation in the named pool.

bool prf::net::pool::Ipv4PoolManager::renew_allocation(std::string_view pool_section, const PoolClientIdentity& client, uint64_t expires_at_ms)

Extends lifetime of an existing committed allocation.

Returns	`true` when a committed allocation for `client` was found.

void prf::net::pool::Ipv4PoolManager::service_timeouts(uint64_t now_ms)

Removes expired offers and leases from all configured pools.

Parameters
now_ms	Current monotonic time in milliseconds.

bool prf::net::pool::Ipv4PoolManager::snapshot_pool(std::string_view pool_section, PoolSnapshot* out) const

Returns the current effective snapshot of one pool.

Parameters
pool_section	Section name such as `pool1`.
out	Output snapshot.
Returns	`true` when the pool exists and current config refresh succeeded.

size_t prf::net::pool::Ipv4PoolManager::visit_allocations(std::string_view pool_section, AllocationVisitorFn visitor, void* user_ctx) const

Visits active allocations without requiring a temporary output buffer.

Parameters
pool_section	Section name such as `pool1`.
visitor	Per-allocation callback.
user_ctx	Opaque pointer forwarded to `visitor`.
Returns	Number of active allocations observed before iteration stopped.

This is intended for observability code such as control endpoints that need to encode every lease into a response map while keeping stack usage predictable.

Returning false from the visitor stops enumeration early.

prf::net::pool::Ipv4PoolManager class final #include <net/pool/pool_manager.hpp>