About arrp¶

arrp (Asynchronous Resource Reusable Pool) is a lightweight, thread-safe, generic resource pool library for Modern C++20. It provides a robust, lock-aware, exception-safe mechanism to manage, limit, borrow, and loan expensive objects such as database connections, sockets, and heavy compute buffers.

Thread-Safe & Lock-Aware¶

Leverages std::mutex and std::counting_semaphore for atomic visibility and efficient concurrency without data races.

Exception-Safe Guards¶

Implements resource_guard<T>, providing RAII-based lifecycle management to ensure borrowed resources are automatically returned to the pool, even if exceptions are thrown.

Zero-Copy Moves¶

Moves expensive resources directly in and out of the pool memory structures without triggering copy semantics, drastically reducing latency.

JSON Diagnostics¶

Optional built-in integration with nlohmann::json to instantly dump detailed operational pool statistics for production telemetry.

Quick Facts¶

Language Standard	C++20 (requires Concepts and Coroutines support)
Design Pattern	Generic Resource Pool / Object Pool
Integration	Header-only (`#include <siddiqsoft/arrp.hpp>`)
Core Dependency	`nlohmann/json` (optional, for telemetry)

Usage Examples¶

Basic Resource BorrowingFactory-Backed On-Demand CreationValidation & AbandonmentTelemetry JSON Output

#include <iostream>
#include <string>
#include <siddiqsoft/arrp.hpp>

int main() {
    // 1. Create a pool with a max capacity of 10 std::strings
    siddiqsoft::arrp::resource_pool<std::string> pool(10);

    // 2. Seed the pool with an object
    pool.seed("Pre-allocated Connection String");

    // 3. Borrow the object using RAII guard
    auto guard = pool.try_borrow();
    if (guard.is_valid()) {
        std::cout << "Borrowed: " << guard.get() << "\n";
        // Object is automatically returned to the pool when 'guard' goes out of scope
    }
}

#include <iostream>
#include <siddiqsoft/arrp.hpp>

struct ExpensiveConnection {
    ExpensiveConnection() { std::cout << "Connected!\n"; }
};

int main() {
    siddiqsoft::arrp::resource_pool<ExpensiveConnection> pool(5);

    // Register a factory callback for on-demand resource creation
    pool.set_factory_callback([](auto& p) {
        return std::make_unique<ExpensiveConnection>();
    });

    // Since the pool is empty, try_borrow_create() automatically invokes the factory
    auto conn_guard = pool.try_borrow_create();
}

#include <siddiqsoft/arrp.hpp>

int main() {
    siddiqsoft::arrp::resource_pool<int> pool(5);
    pool.seed(42);

    {
        auto guard = pool.try_borrow();

        // Oh no, the resource is corrupted! Invalidate it so it is destroyed
        // and NOT returned to the pool upon guard destruction.
        guard.invalidate();
    }
}

#include <nlohmann/json.hpp>
#include <siddiqsoft/arrp.hpp>
#include <iostream>

int main() {
    siddiqsoft::arrp::resource_pool<int> pool(10);
    pool.seed(1);
    pool.seed(2);

    auto borrowed = pool.try_borrow();

    // Generates diagnostic statistics if nlohmann/json is included FIRST
    auto stats = pool.to_json();
    std::cout << stats.dump(2) << "\n";
}

Architecture & Component Relationships¶

Relationship topology connecting public API entry points and domain models:

flowchart TD
    subgraph External["External Dependencies"]
        NLOHMANN["nlohmann::json<br/>(Optional)"]
        STDLIB["C++20 Standard Library<br/>mutex, semaphore, concepts"]
    end

    subgraph PublicAPI["Public API Headers & Classes"]
        ARRP_H["<b>siddiqsoft/arrp.hpp</b><br/>Primary Entry Point"]

        C_POOL["siddiqsoft::arrp::resource_pool&lt;T&gt;<br/>- seed()<br/>- try_borrow()<br/>- try_borrow_create()<br/>- clear()"]
        C_GUARD["siddiqsoft::arrp::resource_guard&lt;T&gt;<br/>- get()<br/>- invalidate()<br/>- release()"]
    end

    subgraph PrivateData["Internal Engine (private/)"]
        P_POOL["<b>resource_pool.hpp</b>"]
        P_GUARD["<b>resource_guard.hpp</b>"]
        P_CONCEPTS["<b>concepts.hpp</b><br/>NonNumericMoveConstructible"]
    end

    ARRP_H --> P_POOL
    ARRP_H --> P_GUARD
    ARRP_H --> P_CONCEPTS

    P_POOL --> C_POOL
    P_GUARD --> C_GUARD

    C_POOL -. "creates" .-> C_GUARD
    C_GUARD -. "returns to" .-> C_POOL

    C_POOL -- "optionally depends" --> NLOHMANN
    C_POOL -- "depends" --> STDLIB

Component	File Path	Class / Responsibility
Resource Pool	`include/siddiqsoft/private/resource_pool.hpp`	The `resource_pool<T>` handles tracking, counters, locking, and the core lifecycle queue.
RAII Guard	`include/siddiqsoft/private/resource_guard.hpp`	The `resource_guard<T>` borrows the underlying `T` and guarantees return-or-destroy on scope exit.
Concepts constraints	`include/siddiqsoft/private/concepts.hpp`	Ensures type `T` is valid for pooling (`NonNumericMoveConstructible`).