siddiqsoft::arrp::resource_guard Class Reference¶

Namespace {root_namespace}

#include <siddiqsoft/private/resource_guard.hpp>

RAII wrapper for managing resource lifecycle in a resource pool.

Class Hierarchy & Inheritance

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

Figure: GraphViz UML Collaboration diagram

Member Functions Summary¶

Constructors & Destructors¶

`void`	resource_guard ((const resource_guard &)=delete) Copy constructor is deleted.
`void`	resource_guard (const pool_error &err) Constructs an invalid guard carrying a borrow error.
`void`	resource_guard (resource_guard &&src) Move constructor.
`void`	~resource_guard (() noexcept) Destructor - invokes callback to handle resource return or abandonment.

Core Accessors & Modifiers¶

`resource_guard &`	operator= ((const resource_guard &)=delete) Copy assignment operator is deleted.
`resource_guard &`	operator= (resource_guard &&src) Move assignment operator.
`T &`	operator* () Dereference operator to access the wrapped resource.
`T *`	operator-> () Pointer-like access to the wrapped resource.
`const T *`	operator-> (() const) Provides const pointer-like access to the wrapped resource.
`void`	operator T& (() &) Explicit conversion to resource reference.
`void`	operator const T & (() const &) Provides a const reference to the wrapped resource.
`void`	operator bool (() const noexcept) Tests whether the guard holds a resource eligible for return.
`void`	operator InnerType (() const) Converts through a conversion supplied by the stored resource type.
`resource_guard &`	operator= (T &&src) Assignment operator for resource value.
`void`	invalidate () Marks the resource as invalid (abandoned).
`bool`	is_valid (() const) Checks if the resource is valid.
`auto &`	set_error (pool_error err) Sets the error reported by error().
`pool_error`	error (() const) Gets the error associated with this guard.
`bool`	has_value (() const) Tests whether the guard holds a valid resource.
`nlohmann::json`	to_json (() const) Serializes the resource_guard to JSON.

Member Function Documentation¶

◆

resource_guard()¶

void resource_guard::resource_guard(const resource_guard &)=delete;

Copy constructor is deleted. resource_guard is move-only to prevent resource ownership ambiguity and ensure proper RAII semantics. Only one resource_guard can own a resource.

◆

operator=()¶

resource_guard & resource_guard::operator=(const resource_guard &)=delete;

Copy assignment operator is deleted. Copy assignment is not allowed to maintain move-only semantics and prevent resource ownership ambiguity.

◆

resource_guard()¶

void resource_guard::resource_guard(const pool_error &err);

Constructs an invalid guard carrying a borrow error.

Parameters

const pool_error & err Error reported by `error()`

◆

resource_guard()¶

void resource_guard::resource_guard(resource_guard &&src);

Move constructor. Transfers ownership from another resource_guard to this one. The source is invalidated to prevent double-return.

Parameters

resource_guard && src The source `resource_guard` to move from

Note

The source's callback is cleared to prevent double-return The source is marked as invalid This constructor is using new syntax for noexcept specification based on the move-constructibility of T and the callback function.

◆

operator=()¶

resource_guard & resource_guard::operator=(resource_guard &&src);

Move assignment operator. Transfers ownership from another resource_guard to this one. Before taking ownership, the currently-held resource (if valid) is returned to the pool via the putback callback. The source is then invalidated to prevent double-return.

Parameters

resource_guard && src The source `resource_guard` to move from

Returns

Reference to this resource_guard

Note

Self-assignment is checked via pointer comparison The currently-held resource is returned to the pool before overwrite The source's callback is cleared to prevent double-return The source is marked as invalid after the move NOT noexcept: T's move-assignment may throw; declaring noexcept here would call std::terminate if T::operator=(T&&) throws after the putback callback has already fired (state would be inconsistent).

◆

~resource_guard()¶

void resource_guard::~resource_guard() noexcept;

Destructor - invokes callback to handle resource return or abandonment. Invokes the putback callback if one exists, passing the resource and its validity status. The callback is responsible for deciding whether to return the resource to the pool (if valid) or discard it (if invalid). Exceptions from the callback are caught and logged to stderr.

Note

Noexcept: Exceptions are caught and logged, not propagated The callback is always invoked if set, regardless of validity The callback receives the validity flag to make the appropriate decision The callback is cleared after invocation The resource is marked as invalid after callback invocation

◆

operator*()¶

T & resource_guard::operator*();

Dereference operator to access the wrapped resource.

Returns

Reference to the wrapped resource

Warning

Does not check validity; do not use after invalidation or move-out.

◆

operator->()¶

T * resource_guard::operator->();

Pointer-like access to the wrapped resource.

Example:

// Source: tests/doxygen_examples.cpp:L58-L65
    siddiqsoft::arrp::resource_pool<std::string> pool;
    pool.seed("Hello");

    auto guard = pool.try_borrow();
    if (guard.is_valid()) {
        // Access the underlying resource
        guard.get() += " World";
    }

Returns

Pointer to the wrapped resource, or nullptr if invalid

Note

Returns nullptr if resource is invalid

◆

operator->()¶

const T * resource_guard::operator->() const;

Provides const pointer-like access to the wrapped resource.

Returns

The resource address, or nullptr if the guard is invalid.

◆

operator T&()¶

void resource_guard::operator T&() &;

Explicit conversion to resource reference.

Returns

Reference to the wrapped resource

Warning

Does not check validity; do not use after invalidation or move-out.

◆

operator const T &()¶

void resource_guard::operator const T &() const &;

Provides a const reference to the wrapped resource.

Warning

Does not check validity; do not use after invalidation or move-out.

◆

operator bool()¶

void resource_guard::operator bool() const noexcept;

Tests whether the guard holds a resource eligible for return.

Returns

true when the guard is valid

◆

operator InnerType()¶

void resource_guard::operator InnerType() const;

Converts through a conversion supplied by the stored resource type.

Template Parameters

InnerType Requested conversion target.

Returns

The result of converting the stored resource to InnerType.

◆

operator=()¶

resource_guard & resource_guard::operator=(T &&src);

Assignment operator for resource value. Replaces the held resource value in place. The old resource is returned to the pool, and the guard retains ownership of the new resource, which will be returned to the pool when destroyed.

Parameters

T && src The new resource value (moved)

Returns

Reference to this resource_guard

Note

Returns existing resource to pool before taking ownership of new resource.

◆

invalidate()¶

void resource_guard::invalidate();

Marks the resource as invalid (abandoned).

Example:

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

    {
        auto guard = pool.try_borrow();
        if (guard.get() == 42) {
            // Resource is corrupted or no longer needed.
            // Invalidate the guard so the resource is destroyed instead of returning to the pool.
            guard.invalidate();
        }
    }

Sets the validity flag to false. When the resource is destroyed, the callback will be invoked with isvalid=false, allowing the pool to discard the resource rather than returning it for reuse. This is appropriate when the resource has been moved out, corrupted, or otherwise rendered unusable.

Note

Virtual for interface consistency, but resource_guard is final, so there is currently no derived class to override this. The callback is still invoked; only the validity flag changes Typically called when the resource is corrupted, moved out, or consumed

◆

is_valid()¶

bool resource_guard::is_valid() const;

Checks if the resource is valid.

Returns

true if the resource is valid and will be returned to pool, false otherwise

Note

Virtual for interface consistency, but resource_guard is final, so there is currently no derived class to override this. Const: Does not modify the resource

◆

set_error()¶

auto & resource_guard::set_error(pool_error err);

Sets the error reported by error().

Parameters

pool_error err Error code to store.

Returns

This guard.

◆

error()¶

pool_error resource_guard::error() const;

Gets the error associated with this guard.

Returns

The stored error code; valid guards normally report pool_error::Ok.

◆

has_value()¶

bool resource_guard::has_value() const;

Tests whether the guard holds a valid resource.

Returns

true when is_valid() would return true.

◆

to_json()¶

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

Serializes the resource_guard to JSON. Returns a JSON object containing the resource state and validity. Only available if nlohmann/json.hpp is included before this header.

Returns

JSON object with: _typver: Type and version string ("siddiqsoft.arrp.resource_guard/1.0.0") valid: Whether the resource is valid (boolean) value: The resource value (if serializable, otherwise "-noserializer-")

Note

Available only when nlohmann/json.hpp was included before this header. If T is not serializable, value is set to "-noserializer-"

Source Code Reference¶

Header: include/siddiqsoft/private/resource_guard.hpp