instrumented_pool.hpp

Go to the documentation of this file.

// SPDX-License-Identifier: MIT
// Copyright (c) 2026 Daniel Polo
 
#ifndef IT_D4NP_MEMORYPOOL_INSTRUMENTED_POOL_HPP_
#define IT_D4NP_MEMORYPOOL_INSTRUMENTED_POOL_HPP_
 
#include <it/d4np/memorypool/memory_pool.hpp>
 
#include <atomic>
#include <cstddef>
#include <cstdint>
#include <new>
#include <optional>
#include <ostream>
#include <utility>
#include <vector>
 
namespace it::d4np::memorypool {
 
struct PoolStats {
    std::size_t allocations_;          
    std::size_t deallocations_;        
    std::size_t allocation_failures_;  
    std::size_t live_;                 
    std::size_t peak_live_;            
};
 
enum class PoolEvent : std::uint8_t {
    exhausted,  
    grew,       
    destroyed   
};
 
struct PoolObserver {
    PoolObserver() = default;
    PoolObserver(const PoolObserver&) = default;
    PoolObserver(PoolObserver&&) = default;
    PoolObserver& operator=(const PoolObserver&) = default;
    PoolObserver& operator=(PoolObserver&&) = default;
    virtual ~PoolObserver() = default;
 
    virtual void on_pool_event(PoolEvent event, const PoolStats& stats) noexcept = 0;
};
 
class InstrumentedPool {
public:
    explicit InstrumentedPool(Pool&& pool) noexcept : pool_(std::move(pool)) {}
 
    [[nodiscard]] static std::optional<InstrumentedPool> make(std::size_t block_size, std::size_t block_count) {
        std::optional<Pool> pool = Pool::make(block_size, block_count);
        if (!pool.has_value()) {
            return std::nullopt;
        }
        return {InstrumentedPool{std::move(*pool)}};
    }
 
    // NOLINTNEXTLINE(bugprone-easily-swappable-parameters)
    [[nodiscard]] static std::optional<InstrumentedPool> make_dynamic(std::size_t block_size, std::size_t block_count,
                                                                      std::size_t growth_factor) {
        std::optional<Pool> pool = Pool::make_dynamic(block_size, block_count, growth_factor);
        if (!pool.has_value()) {
            return std::nullopt;
        }
        return {InstrumentedPool{std::move(*pool)}};
    }
 
    InstrumentedPool(const InstrumentedPool&) = delete;
    InstrumentedPool& operator=(const InstrumentedPool&) = delete;
 
    InstrumentedPool(InstrumentedPool&& other) noexcept
        : pool_(std::move(other.pool_)), allocations_(other.allocations_.load(std::memory_order_relaxed)),
          deallocations_(other.deallocations_.load(std::memory_order_relaxed)),
          allocation_failures_(other.allocation_failures_.load(std::memory_order_relaxed)),
          live_(other.live_.load(std::memory_order_relaxed)),
          peak_live_(other.peak_live_.load(std::memory_order_relaxed)), observers_(std::move(other.observers_)),
          last_growths_(other.last_growths_.load(std::memory_order_relaxed)) {}
 
    InstrumentedPool& operator=(InstrumentedPool&& other) noexcept {
        if (this != &other) {
            notify(PoolEvent::destroyed);
            pool_ = std::move(other.pool_);
            allocations_.store(other.allocations_.load(std::memory_order_relaxed), std::memory_order_relaxed);
            deallocations_.store(other.deallocations_.load(std::memory_order_relaxed), std::memory_order_relaxed);
            allocation_failures_.store(other.allocation_failures_.load(std::memory_order_relaxed),
                                       std::memory_order_relaxed);
            live_.store(other.live_.load(std::memory_order_relaxed), std::memory_order_relaxed);
            peak_live_.store(other.peak_live_.load(std::memory_order_relaxed), std::memory_order_relaxed);
            observers_ = std::move(other.observers_);
            last_growths_.store(other.last_growths_.load(std::memory_order_relaxed), std::memory_order_relaxed);
        }
        return *this;
    }
 
    ~InstrumentedPool() {
        notify(PoolEvent::destroyed);
    }
 
    void add_observer(PoolObserver& observer) {
        observers_.push_back(&observer);
    }
 
    [[nodiscard]] void* allocate() {
        void* block = nullptr;
        try {
            block = pool_.allocate();
        } catch (const std::bad_alloc&) {
            allocation_failures_.fetch_add(1U, std::memory_order_relaxed);
            notify(PoolEvent::exhausted);
            throw;
        }
        record_allocation();
        notify_if_grew();
        return block;
    }
 
    [[nodiscard]] void* try_allocate() noexcept {
        void* const block = pool_.try_allocate();
        if (block == nullptr) {
            allocation_failures_.fetch_add(1U, std::memory_order_relaxed);
            notify(PoolEvent::exhausted);
            return nullptr;
        }
        record_allocation();
        notify_if_grew();
        return block;
    }
 
    void deallocate(void* block) noexcept {
        if (block != nullptr) {
            deallocations_.fetch_add(1U, std::memory_order_relaxed);
            // Clamp at zero: a foreign or already-freed pointer is a no-op in the
            // core (ADR-0012), so an unconditional fetch_sub would underflow `live_`
            // to SIZE_MAX on such a call (BUG-0002). Decrement only while positive.
            std::size_t live = live_.load(std::memory_order_relaxed);
            while (live > 0U && !live_.compare_exchange_weak(live, live - 1U, std::memory_order_relaxed)) {
                // `live` is reloaded by compare_exchange_weak on failure; retry.
            }
        }
        pool_.deallocate(block);
    }
 
    [[nodiscard]] PoolStats stats() const noexcept {
        return PoolStats{allocations_.load(std::memory_order_relaxed), deallocations_.load(std::memory_order_relaxed),
                         allocation_failures_.load(std::memory_order_relaxed), live_.load(std::memory_order_relaxed),
                         peak_live_.load(std::memory_order_relaxed)};
    }
 
    void write_summary(std::ostream& os) const {
        const PoolStats snapshot = stats();
        os << "InstrumentedPool: allocations=" << snapshot.allocations_ << " deallocations=" << snapshot.deallocations_
           << " failures=" << snapshot.allocation_failures_ << " live=" << snapshot.live_
           << " peak_live=" << snapshot.peak_live_ << "\n";
    }
 
    [[nodiscard]] memory_pool_t* native_handle() noexcept {
        return pool_.native_handle();
    }
 
    [[nodiscard]] std::size_t block_size() const noexcept {
        return pool_.block_size();
    }
 
    [[nodiscard]] std::size_t metadata_bytes() const noexcept {
        return pool_.metadata_bytes();
    }
 
private:
    void record_allocation() noexcept {
        allocations_.fetch_add(1U, std::memory_order_relaxed);
        const std::size_t live = live_.fetch_add(1U, std::memory_order_relaxed) + 1U;
        // Relaxed compare-exchange max — lift peak_live_ to `live` if it is behind.
        std::size_t peak = peak_live_.load(std::memory_order_relaxed);
        while (peak < live && !peak_live_.compare_exchange_weak(peak, live, std::memory_order_relaxed)) {
            // peak is reloaded by compare_exchange_weak on failure; retry.
        }
    }
 
    void notify(PoolEvent event) noexcept {
        const PoolStats snapshot = stats();
        for (PoolObserver* const observer : observers_) {
            observer->on_pool_event(event, snapshot);
        }
    }
 
    void notify_if_grew() noexcept {
        const std::size_t growths = ::memory_pool_growths(pool_.native_handle());
        // Advance the high-water growth count atomically; the thread that wins the
        // compare-exchange notifies `grew` exactly once per observed growth, so
        // concurrent callers neither race on the counter nor double-notify (BUG-0001).
        std::size_t last = last_growths_.load(std::memory_order_relaxed);
        while (growths > last) {
            if (last_growths_.compare_exchange_weak(last, growths, std::memory_order_relaxed)) {
                notify(PoolEvent::grew);
                break;
            }
            // `last` is reloaded by compare_exchange_weak on failure; re-check.
        }
    }
 
    Pool pool_;
    std::atomic<std::size_t> allocations_{0U};
    std::atomic<std::size_t> deallocations_{0U};
    std::atomic<std::size_t> allocation_failures_{0U};
    std::atomic<std::size_t> live_{0U};
    std::atomic<std::size_t> peak_live_{0U};
    std::vector<PoolObserver*> observers_;
    // Atomic: read+advanced on the hot allocation path (`notify_if_grew`), which the
    // class contract allows to run concurrently over a thread-safe pool (BUG-0001).
    std::atomic<std::size_t> last_growths_{0U};
};
 
}  // namespace it::d4np::memorypool
 
#endif  // IT_D4NP_MEMORYPOOL_INSTRUMENTED_POOL_HPP_