resource_pool.hpp

/*
    arrp
    Auto returning resource pool for modern C++
 
    BSD 3-Clause License
 
    Copyright (c) 2026 Abdulkareem Siddiq
    All rights reserved.
 
    Redistribution and use in source and binary forms, with or without
    modification, are permitted provided that the following conditions are met:
 
    1. Redistributions of source code must retain the above copyright notice,
   this list of conditions and the following disclaimer.
 
    2. Redistributions in binary form must reproduce the above copyright notice,
       this list of conditions and the following disclaimer in the documentation
       and/or other materials provided with the distribution.
 
    3. Neither the name of the copyright holder nor the names of its
       contributors may be used to endorse or promote products derived from
       this software without specific prior written permission.
 
    THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
    IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
   ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
   LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
   CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
   SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
   INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
   CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
   ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
   POSSIBILITY OF SUCH DAMAGE.
 */
 
#pragma once
#ifndef RESOURCE_POOL_HPP
#define RESOURCE_POOL_HPP
 
#include <atomic>
#include <concepts>
#include <cstdint>
#include <deque>
#include <format>
#include <mutex>
#include <stdexcept>
#include <type_traits>
 
#include "private/common.hpp"
#include "private/scoped_resource.hpp"
#include "siddiqsoft/RunOnEnd.hpp"
 
namespace siddiqsoft::arrp
{
    template <typename T, typename SRT = scoped_resource<T>, uint8_t InitCapacity = resource_pool_limits::DefaultCapacity>
        requires((InitCapacity <= resource_pool_limits::MaxCapacity)) && NonNumericMoveConstructible<T> &&
                std::derived_from<SRT, scoped_resource<T>>
    class resource_pool
    {
    private:
        uint8_t m_capacity {InitCapacity};

        std::atomic_uint16_t m_resources_checkedout {0};

        std::atomic_uint16_t m_invalidated_resources {0};

        std::atomic_uint64_t m_counter_checkout {0};

        std::atomic_uint64_t m_counter_ondemand_adds {0};

        std::atomic_uint64_t m_counter_checkin {0};

        std::atomic_uint64_t m_counter_auto_returned {0};

        std::deque<T> m_pool {};
 
#if defined(arrp_USE_RECURSIVE_MUTEX) || defined(ARRP_USE_RECURSIVE_MUTEX)
        mutable std::recursive_mutex m_pool_lock {};
        // It might be more expensive but the client might find this useful!
        #warning "You're using std::recursive_mutex which is more expensive"
#else
        mutable std::mutex m_pool_lock {};
#endif

        std::function<SRT(resource_pool&)> m_callback_to_add_new_raw_resource_to_pool {};
 
    public:
        enum class auto_add_policy
        {
            NoGrow,
            AutoGrow
        };

        static inline std::function<SRT(resource_pool&)> CallbackDoNotAutoAddResource = [](resource_pool&) -> SRT {
            throw std::runtime_error("No items in the pool; add something first.");
        };

        resource_pool(std::function<SRT(resource_pool&)>&& new_resource_callback)
        {
            if (new_resource_callback) {
                m_callback_to_add_new_raw_resource_to_pool = std::move(new_resource_callback);
            }
            else {
                // This is just in case someone sends an empty callback!
                m_callback_to_add_new_raw_resource_to_pool = CallbackDoNotAutoAddResource;
            }
        }

        resource_pool(auto_add_policy add_policy = auto_add_policy::NoGrow)
        {
            if (add_policy == auto_add_policy::NoGrow) {
                m_callback_to_add_new_raw_resource_to_pool = CallbackDoNotAutoAddResource;
            }
            else if (add_policy == auto_add_policy::AutoGrow) {
                // This method is declared here as lambda to capture the this pointer
                // whereas if we attempted to declared it earlier as a static inline then the
                // this pointer would not be captured.
                m_callback_to_add_new_raw_resource_to_pool = [this](resource_pool& pool) -> SRT {
                    // Create a SRT element and wire up the auto-return callback to return
                    // the resource back to this object.
                    return SRT {T {}, [this](T&& src) {
                                    this->m_counter_auto_returned++;
                                    this->checkin(std::forward<T&&>(src));
                                }};
                    // Allow the compiler to use NRVO (move elision; do not use std::move here!)
                    // return temp;
                };
            }
        }
 
        // Not copy-able, not movable
        resource_pool(resource_pool&) = delete;

        resource_pool(resource_pool&& src) = delete;

        resource_pool& operator=(resource_pool&) = delete;

        resource_pool& operator=(resource_pool&& src) = delete;

        ~resource_pool() { clear(); }

        void clear() noexcept
        {
            std::scoped_lock l(m_pool_lock);
            m_pool.clear();
        }

        [[nodiscard]] size_t size() const noexcept
        {
            std::scoped_lock l(m_pool_lock);
            return m_pool.size();
        }

        [[nodiscard]] auto checkout() -> SRT
        {
            // Create a guard to decrement m_resources_checkedout if the factory callback throws
            // This ensures we don't leak the checkout count if the factory fails
            auto checkout_guard = [this]() {
                if (m_resources_checkedout > 0) {
                    m_resources_checkedout--;
                }
            };
 
            try {
                // @note We use a unique_lock vs a scoped_lock to allow ourselves
                // to create the resource outside the lock!
                std::unique_lock l(m_pool_lock);
 
                if (!m_pool.empty()) {
                    // The pool is non-empty; return from the pool
                    // Return first element from the pool and pop it on scope end
                    RunOnEnd pop_guard([&]() { m_pool.pop_front(); });
 
                    m_resources_checkedout++;
                    ++m_counter_checkout;
 
                    // Make a wrapper..
                    // Create a SRT element and wire up the auto-return callback to return
                    // the resource back to this object.
                    return SRT {std::move(m_pool.front()), [this](T&& src) {
                                    this->m_counter_auto_returned++;
                                    this->checkin(std::forward<T&&>(src));
                                }};
                    // Allow the compiler to use NRVO (move elision; do not use std::move here!)
                    // return temp;
 
                    // The pop_front() happens within this scope and within the lock!
                }
                else if ((m_capacity > m_pool.size() + m_resources_checkedout) && m_callback_to_add_new_raw_resource_to_pool) {
                    // We have no more items in the pool (we're starting up or everything is
                    // checked out) but we have not reached the limit. The limit is number
                    // of m_resources_checkedout + pool.size() < m_capacity We are
                    // under-capacity.. so we can return to the caller a new item..
                    m_resources_checkedout++;
                    // We should unlock the resource and ..
                    l.unlock();
 
                    ++m_counter_checkout;
                    // Update the attempted delegated calls to add new raw resource to pool.
                    ++m_counter_ondemand_adds;
 
                    // ..delegate the new resource acquisition
                    // outside the lock.
                    return m_callback_to_add_new_raw_resource_to_pool(*this);
                }
                else if (m_capacity > m_pool.size() + m_resources_checkedout) {
                    // We're under-capacity.. but no dynamic resource provider
                    std::cerr << std::format("We're under-capacity.. but no dynamic resource provider\n");
                }
            } // scope end
            catch (std::exception& ex) {
                checkout_guard();
                std::cerr << std::format("Error in checkout: {}\n", ex.what());
                throw;
            }
            catch (...) {
                checkout_guard();
                std::cerr << std::format("UNKNOWN Error in checkout\n");
                throw;
            }
 
            auto msg = std::format(
                    "Pool Size:{}  checkedout:{}  capacity:{}", m_pool.size(), m_resources_checkedout.load(), m_capacity);
            throw std::runtime_error(msg);
        }

        void checkin(T&& raw_resource)
        {
            ++m_counter_checkin;
            {
                std::scoped_lock l(m_pool_lock);
 
                m_pool.push_back(std::move(raw_resource));
                if (m_resources_checkedout > 0) m_resources_checkedout--;
            } // lock scope end
        }
 
#if defined(NLOHMANN_JSON_VERSION_MAJOR)
        nlohmann::json to_json() const
        {
            auto myPoolSize = this->size();
 
            return {{"_typver", "siddiqsoft.arrp.resource_pool/0.0.0"},
                    {"capacity", m_capacity},
                    {"size", myPoolSize},
                    {"load", myPoolSize + m_resources_checkedout.load()},
                    {"invalidated", m_invalidated_resources.load()},
                    {"checkedout", m_resources_checkedout.load()},
                    {"counters",
                     {{"autoreturns", m_counter_auto_returned.load()},
                      {"newitems", m_counter_ondemand_adds.load()},
                      {"return", m_counter_checkin.load()},
                      {"borrow", m_counter_checkout.load()}}}};
        }
#endif
    };
 
#if defined(NLOHMANN_JSON_VERSION_MAJOR)
    template <typename T, typename SRT = scoped_resource<T>, uint8_t InitCapacity = arrp::resource_pool_limits::DefaultCapacity>
        requires((InitCapacity <= arrp::resource_pool_limits::MaxCapacity)) && NonNumericMoveConstructible<T> &&
                std::derived_from<SRT, scoped_resource<T>>
    static void to_json(nlohmann::json& dest, const siddiqsoft::arrp::resource_pool<T, SRT, InitCapacity>& src)
    {
        dest = src.to_json();
    }
#endif
 
 
} // namespace siddiqsoft::arrp
#endif