Skip to content

siddiqsoft::arrp::resource_pool Class Reference

Namespace {root_namespace}
#include <siddiqsoft/private/resource_pool.hpp>

Thread-safe auto-returning resource pool.

Class Hierarchy & Inheritance

The following UML class diagram highlights siddiqsoft::arrp::resource_pool and its direct relationships.

siddiqsoft::arrp::resource_pool< T > Node1 siddiqsoft::arrp::resource _pool< T >   + resource_pool() + resource_pool() + operator=() + operator=() + resource_pool() + resource_pool() + ~resource_pool() + set_factory_callback() + clear() + size() + try_borrow() + try_borrow_create() + seed() + seed() + to_json() # make_resource_guard() # create_from_callback() # borrow_impl() # return_to_pool() Figure: GraphViz UML Collaboration diagram

Member Functions Summary

Constructors & Destructors

void resource_pool ((resource_pool &)=delete)
Copy constructor is deleted.
void resource_pool ((resource_pool &&src)=delete)
Move constructor is deleted.
void resource_pool (
uint8_t init_capacity=resource_pool_limits::DefaultCapacity,
std::function< void(T &)> &&on_shutdown_callback={}
)
Constructs a resource pool with an optional cleanup callback.
void resource_pool (
std::function< void(T &)> &&on_shutdown_callback
)
Constructs a resource pool with only cleanup callback.
void ~resource_pool ()
Destructor - cleans up all resources in the pool.

Core Accessors & Modifiers

resource_pool & operator= ((resource_pool &)=delete)
Copy assignment operator is deleted.
resource_pool & operator= ((resource_pool &&src)=delete)
Move assignment operator is deleted.
void set_factory_callback (F &&f)
Sets the factory used by try_borrow_create() when no resource is available.
pool_error clear ()
Clears all resources from the pool.
auto size (() const)
Gets the current size of the pool.
resource_guard< T > try_borrow (
std::chrono::nanoseconds timeout={}
)
Borrows an available resource without creating one.
resource_guard< T > try_borrow_create (
std::chrono::nanoseconds timeout={}
)
Borrows an available resource or creates one through the factory.
pool_error seed (Args &&... args)
Adds a resource to the pool by constructing it in-place.
pool_error seed (T &&item)
Adds a resource to the pool by moving it.
nlohmann::json to_json (() const)
Serializes pool statistics to JSON.

Member Function Documentation

◆

resource_pool()

void resource_pool::resource_pool(resource_pool &)=delete;

Copy constructor is deleted. resource_pool is not copyable to prevent resource duplication

◆

resource_pool()

void resource_pool::resource_pool(resource_pool &&src)=delete;

Move constructor is deleted. resource_pool is not movable to maintain resource ownership

◆

operator=()

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

Copy assignment operator is deleted. resource_pool is not copyable to prevent resource duplication

◆

operator=()

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

Move assignment operator is deleted. resource_pool is not movable to maintain resource ownership

◆

resource_pool()

void resource_pool::resource_pool(
    uint8_t init_capacity=resource_pool_limits::DefaultCapacity,
    std::function< void(
    T &
)> &&on_shutdown_callback={}
);

Constructs a resource pool with an optional cleanup callback.

Parameters
uint8_t init_capacity Initial capacity of the pool
std::function< void(T &)> && on_shutdown_callback Optional cleanup callback invoked on destruction

Note

Register a factory separately with set_factory_callback(). Capacity is clamped to [MinimumCapacity, MaxCapacity] but does not enforce a maximum number of seeded or factory-created resources.

◆

resource_pool()

void resource_pool::resource_pool(std::function< void(T &)> &&on_shutdown_callback);

Constructs a resource pool with only cleanup callback.

Parameters
std::function< void(T &)> && on_shutdown_callback Cleanup callback invoked on destruction

Note

Uses the default capacity. The cleanup callback is invoked for resources available during clear() or destruction.

◆

~resource_pool()

void resource_pool::~resource_pool();

Destructor - cleans up all resources in the pool. Sets the shutdown flag and delegates to clear() to clean up resources. The cleanup callback (if provided) is invoked for each resource during cleanup.

Note

Exceptions derived from std::exception in the cleanup callback are caught and written to stderr.

Warning

Guards borrowed from this pool must be destroyed before the pool.

◆

set_factory_callback()

void resource_pool::set_factory_callback(F &&f);

Sets the factory used by try_borrow_create() when no resource is available.

Template Parameters
F Callable type invokable with no arguments returning `resource_guard` or T

Note

Safe to call concurrently with borrow_impl(): assignment is synchronized under m_pool_lock, matching the read sites in borrow_impl(). A borrow in flight may still use the factory that was registered just before or after this call (no ordering is guaranteed relative to a specific concurrent borrow), but the read/write of the underlying std::function is race-free.

Warning

The callback must not call methods on this pool.

◆

clear()

pool_error resource_pool::clear();

Clears all resources from the pool.

Example:
// Source: tests/doxygen_examples.cpp:L58-L64
    siddiqsoft::arrp::resource_pool<std::string> pool;
    pool.seed("A");
    pool.seed("B");

    // Empties the pool completely. Any resources currently borrowed by guards 
    // will be destroyed rather than returned upon guard destruction.
    pool.clear();

Removes currently available resources and invokes the cleanup callback for each. Borrowed resources can return after clear() completes.

Returns

pool_error::Ok

Note

The cleanup callback runs under the pool lock. Exceptions derived from std::exception are caught and written to stderr. Non-blocking by design: if a concurrent borrow has already claimed a resource's semaphore permit but not yet popped it from the pool (it is waiting on the same lock clear() holds), that item is left in place for the borrower rather than drained here. This avoids a deadlock; it means a racing clear() call is not guaranteed to empty every resource that was visible to size() just before it ran.

◆

size()

auto resource_pool::size() const;

Gets the current size of the pool.

Example:
// Source: tests/doxygen_examples.cpp:L71-L76
    siddiqsoft::arrp::resource_pool<int> pool(10);
    pool.seed(1);
    pool.seed(2);

    // size() returns the total number of resources (both idle in queue and currently borrowed)
    std::cout << "Total resources tracked: " << pool.size() << std::endl; // Outputs 2
Returns

Number of currently available resources

Note

Does not include checked-out resources

◆

try_borrow()

resource_guard< T > resource_pool::try_borrow(std::chrono::nanoseconds timeout={});

Borrows an available resource without creating one.

Example:
// Source: tests/doxygen_examples.cpp:L23-L33
    siddiqsoft::arrp::resource_pool<int> pool;
    pool.seed(42);

    {
        // Borrow the resource. It is removed from the pool queue.
        auto guard = pool.try_borrow();
        if (guard.is_valid()) {
            std::cout << "Borrowed: " << guard.get() << std::endl;
        }
        // When 'guard' goes out of scope, the resource is automatically returned to the pool.
    }
Parameters
std::chrono::nanoseconds timeout Maximum time to wait; zero performs a non-blocking attempt.
Returns

A valid scoped resource, or an invalid one with NoMoreResources, Timeout, ShutdownInitiated, or Unknown set as its error.

◆

try_borrow_create()

resource_guard< T > resource_pool::try_borrow_create(std::chrono::nanoseconds timeout={});

Borrows an available resource or creates one through the factory.

Example:
// Source: tests/doxygen_examples.cpp:L40-L51
    siddiqsoft::arrp::resource_pool<int> pool(5);

    // Set a factory callback to generate missing resources
    pool.set_factory_callback([](auto& p) {
        return std::make_unique<int>(99);
    });

    // The pool is currently empty, so try_borrow_create will invoke the factory
    auto guard = pool.try_borrow_create();
    if (guard.is_valid()) {
        std::cout << "Created on demand: " << guard.get() << std::endl;
    }
Parameters
std::chrono::nanoseconds timeout Maximum time to wait; zero performs a non-blocking attempt.
Returns

A valid scoped resource, or an invalid one when shutdown or an implementation or factory error prevents borrowing.

◆

seed()

pool_error resource_pool::seed(Args &&... args);

Adds a resource to the pool by constructing it in-place.

Example:
// Source: tests/doxygen_examples.cpp:L9-L16
    siddiqsoft::arrp::resource_pool<std::string> pool(10);

    // Seed by constructing in-place
    pool.seed(5, 'A'); // "AAAAA"

    // Seed by moving an existing object
    std::string existing = "Hello";
    pool.seed(std::move(existing));
Template Parameters
Args Types of arguments to forward to T's constructor
Parameters
Args &&... args Arguments to forward to T's constructor for in-place construction
Returns

pool_error::Ok, or pool_error::ShutdownInitiated during destruction

Note

Resource is constructed in-place Does not enforce the configured capacity. Do not use this to return a borrowed resource; guards return resources automatically.

◆

seed()

pool_error resource_pool::seed(T &&item);

Adds a resource to the pool by moving it.

Parameters
T && item The resource to add (moved)
Returns

pool_error::Ok, or pool_error::ShutdownInitiated during destruction

Note

Resource is moved into the pool Does not enforce the configured capacity. Do not use this to return a borrowed resource; guards return resources automatically.

◆

to_json()

nlohmann::json resource_pool::to_json() const;

Serializes pool statistics to JSON.

Example:
// Source: tests/doxygen_examples.cpp:L71-L79
    siddiqsoft::arrp::resource_pool<int> pool(10);
    pool.seed(1);
    pool.seed(2);

    auto borrowed = pool.try_borrow();

    // Export telemetry statistics to a JSON object
    nlohmann::json stats = pool.to_json();
    std::cout << stats.dump(4) << std::endl;

Returns a JSON object containing pool statistics and configuration. Only available if nlohmann/json.hpp is included before this header file.

Returns

A JSON object containing a snapshot of pool statistics

Note

Available only when nlohmann/json.hpp was included before this header.

Source Code Reference