gridfire::engine::scratch::StateBlob Class Reference

Container for managing a collection of typed scratchpad instances. More...

#include <blob.h>

Collaboration diagram for gridfire::engine::scratch::StateBlob:

Public Types
enum class	Error : uint8_t {   SCRATCHPAD_NOT_FOUND , SCRATCHPAD_BAD_CAST , SCRATCHPAD_NOT_INITIALIZED , SCRATCHPAD_TYPE_COLLISION ,   SCRATCHPAD_OUT_OF_BOUNDS , SCRATCHPAD_UNKNOWN_ERROR }
	Error codes for scratchpad operations. More...
enum class	ScratchPadStatus : uint8_t { NOT_ENROLLED , ENROLLED_NOT_INITIALIZED , ENROLLED_INITIALIZED }
	Status codes for scratchpad slots. More...

Public Member Functions
	StateBlob ()=default
	Default constructor.
	~StateBlob ()=default
	Default destructor.
template<IsScratchPad CTX>
void	enroll ()
	Enroll a new scratchpad type into the blob.
template<IsScratchPad CTX>
std::expected< CTX *, Error >	get () const
	Retrieve a scratchpad by type.
template<IsScratchPad CTX, bool MUST_BE_INITIALIZED>
std::expected< CTX *, Error >	get () const
	Retrieve a scratchpad by type with optional initialization check.
std::expected< AbstractScratchPad *, Error >	get (const ScratchPadType type) const
	Retrieve a scratchpad by runtime ScratchPadType value.
std::unique_ptr< StateBlob >	clone_structure () const
	Create a deep copy of this blob with all enrolled scratchpads.
std::unordered_set< ScratchPadType >	get_registered_scratchpads () const
	Get the set of all registered scratchpad types.
template<IsScratchPad CTX>
bool	initialized () const
	Check if a specific scratchpad type is initialized.
template<IsScratchPad CTX>
ScratchPadStatus	get_status () const
	Get the status of a specific scratchpad type.
std::unordered_map< ScratchPadType, ScratchPadStatus >	get_status_map () const
	Get a map of all scratchpad types to their current status.

Static Public Member Functions
static std::string	error_to_string (const Error error)
	Convert an Error enum value to a human-readable string.

Private Attributes
std::array< std::unique_ptr< AbstractScratchPad >, MAX_SCRATCHPADS >	scratchpads {}
	Array of scratchpad instances indexed by ScratchPadType.
std::array< bool, MAX_SCRATCHPADS >	scratchpad_enrolled_flags {false}
	Flags indicating which scratchpad slots have been enrolled.

Static Private Attributes
static constexpr size_t	MAX_SCRATCHPADS = static_cast<size_t>(ScratchPadType::_COUNT)
	Maximum number of scratchpad slots, derived from ScratchPadType::_COUNT.

Detailed Description

Container for managing a collection of typed scratchpad instances.

StateBlob provides a centralized registry for scratchpads used by engines. It uses a fixed-size array indexed by ScratchPadType for O(1) access, with compile-time type safety enforced through the IsScratchPad concept.

The blob supports:

• Enrolling new scratchpad types (one instance per type)
• Type-safe retrieval with optional initialization validation
• Runtime retrieval by ScratchPadType enum value
• Deep cloning for parallel execution contexts
• Status queries for monitoring scratchpad states

Thread Safety

This class is not thread-safe. Each thread should have its own StateBlob instance. Use clone_structure() to create independent copies for parallel workers. Concurrent access to the same StateBlob instance requires external synchronization.

Member Enumeration Documentation

Error

enum class gridfire::engine::scratch::StateBlob::Error : uint8_t

strong

Error codes for scratchpad operations.

Enumerator
SCRATCHPAD_NOT_FOUND	Requested scratchpad type is not enrolled.
SCRATCHPAD_BAD_CAST	Dynamic cast to requested type failed.
SCRATCHPAD_NOT_INITIALIZED	Scratchpad exists but is not initialized.
SCRATCHPAD_TYPE_COLLISION	Attempted to enroll duplicate type.
SCRATCHPAD_OUT_OF_BOUNDS	ScratchPadType index exceeds array bounds.
SCRATCHPAD_UNKNOWN_ERROR	Unspecified error condition.

ScratchPadStatus

enum class gridfire::engine::scratch::StateBlob::ScratchPadStatus : uint8_t

strong

Status codes for scratchpad slots.

Enumerator
NOT_ENROLLED	No scratchpad has been enrolled for this slot.
ENROLLED_NOT_INITIALIZED	Scratchpad enrolled but not yet initialized.
ENROLLED_INITIALIZED	Scratchpad enrolled and fully initialized.

Constructor & Destructor Documentation

StateBlob()

gridfire::engine::scratch::StateBlob::StateBlob ( )

default

Default constructor.

~StateBlob()

gridfire::engine::scratch::StateBlob::~StateBlob ( )

default

Default destructor.

Member Function Documentation

clone_structure()

std::unique_ptr< StateBlob > gridfire::engine::scratch::StateBlob::clone_structure ( ) const

inlinenodiscard

Create a deep copy of this blob with all enrolled scratchpads.

Clones the blob structure and all enrolled scratchpads using their clone() methods. The resulting blob is independent and can be used in a separate thread.

Returns

A unique pointer to the cloned StateBlob.

Examples

StateBlob blob;
blob.enroll<GraphEngineScratchPad>();
 
// Initialize the scratchpad
auto scratch = blob.get<GraphEngineScratchPad>().value();
scratch->initialize(engine);
 
// Clone for parallel workers
std::vector<std::unique_ptr<StateBlob>> worker_blobs;
for (int i = 0; i < num_threads; ++i) {
    worker_blobs.push_back(blob.clone_structure());
}

enroll()

template<IsScratchPad CTX>

void gridfire::engine::scratch::StateBlob::enroll ( )

inline

Enroll a new scratchpad type into the blob.

Creates a new instance of the specified scratchpad type and registers it in the appropriate slot. Only one instance per type is allowed.

Template Parameters

CTX	The scratchpad type to enroll (must satisfy IsScratchPad).

Exceptions

exceptions::ScratchPadError

if a scratchpad of this type is already enrolled.

Examples

StateBlob blob;
blob.enroll<GraphEngineScratchPad>();
blob.enroll<AdaptiveEngineViewScratchPad>();
 
// This would throw - duplicate enrollment
// blob.enroll<GraphEngineScratchPad>();

error_to_string()

static std::string gridfire::engine::scratch::StateBlob::error_to_string ( const Error error )

inlinestatic

Convert an Error enum value to a human-readable string.

Parameters

error

The error code to convert.

Returns

A string representation of the error.

Examples

auto result = blob.get<MyScratchPad>();
if (!result.has_value()) {
    std::cerr << "Error: " << StateBlob::error_to_string(result.error());
}

get() [1/3]

template<IsScratchPad CTX>

std::expected< CTX *, Error > gridfire::engine::scratch::StateBlob::get ( ) const

inline

Retrieve a scratchpad by type.

Returns a pointer to the enrolled scratchpad of the specified type. In debug builds, performs a dynamic_cast for type safety; in release builds, uses static_cast for performance.

Template Parameters

CTX	The scratchpad type to retrieve (must satisfy IsScratchPad).

Returns

std::expected containing the scratchpad pointer, or an Error if not found/invalid.

Examples

auto result = blob.get<GraphEngineScratchPad>();
if (result.has_value()) {
    GraphEngineScratchPad* scratch = result.value();
    // Use scratch...
} else {
    // Handle error
    std::cerr << StateBlob::error_to_string(result.error());
}

get() [2/3]

template<IsScratchPad CTX, bool MUST_BE_INITIALIZED>

std::expected< CTX *, Error > gridfire::engine::scratch::StateBlob::get ( ) const

inline

Retrieve a scratchpad by type with optional initialization check.

Returns a pointer to the enrolled scratchpad of the specified type. When MUST_BE_INITIALIZED is true, also verifies that the scratchpad has been initialized before returning it.

Template Parameters

CTX	The scratchpad type to retrieve (must satisfy IsScratchPad).
MUST_BE_INITIALIZED	If true, returns an error for uninitialized scratchpads.

Returns

std::expected containing the scratchpad pointer, or an Error if not found/invalid/uninitialized.

Examples

// Get only if initialized
auto result = blob.get<GraphEngineScratchPad, true>();
if (!result.has_value()) {
    if (result.error() == StateBlob::Error::SCRATCHPAD_NOT_INITIALIZED) {
        // Need to initialize first
    }
}

get() [3/3]

std::expected< AbstractScratchPad *, Error > gridfire::engine::scratch::StateBlob::get ( const ScratchPadType type ) const

inlinenodiscard

Retrieve a scratchpad by runtime ScratchPadType value.

Returns a pointer to the abstract base class for the scratchpad at the specified type index. Useful when the concrete type is not known at compile time.

Parameters

type	The ScratchPadType enum value identifying the scratchpad.

Returns

std::expected containing the AbstractScratchPad pointer, or an Error.

Examples

ScratchPadType type = ScratchPadType::GRAPH_ENGINE_SCRATCHPAD;
auto result = blob.get(type);
if (result.has_value()) {
    AbstractScratchPad* scratch = result.value();
    if (scratch->is_initialized()) {
        // Use scratch...
    }
}

get_registered_scratchpads()

std::unordered_set< ScratchPadType > gridfire::engine::scratch::StateBlob::get_registered_scratchpads ( ) const

inlinenodiscard

Get the set of all registered scratchpad types.

Returns

An unordered set of ScratchPadType values for all enrolled scratchpads.

Examples

auto registered = blob.get_registered_scratchpads();
for (auto type : registered) {
    std::cout << "Registered: " << static_cast<int>(type) << "\n";
}

get_status()

template<IsScratchPad CTX>

ScratchPadStatus gridfire::engine::scratch::StateBlob::get_status ( ) const

inlinenodiscard

Get the status of a specific scratchpad type.

Template Parameters

CTX	The scratchpad type to query (must satisfy IsScratchPad).

Returns

The ScratchPadStatus indicating enrollment and initialization state.

Examples

auto status = blob.get_status<GraphEngineScratchPad>();
switch (status) {
    case StateBlob::ScratchPadStatus::NOT_ENROLLED:
        blob.enroll<GraphEngineScratchPad>();
        break;
    case StateBlob::ScratchPadStatus::ENROLLED_NOT_INITIALIZED:
        // Need to initialize
        break;
    case StateBlob::ScratchPadStatus::ENROLLED_INITIALIZED:
        // Ready to use
        break;
}

get_status_map()

std::unordered_map< ScratchPadType, ScratchPadStatus > gridfire::engine::scratch::StateBlob::get_status_map ( ) const

inlinenodiscard

Get a map of all scratchpad types to their current status.

Returns

An unordered map from ScratchPadType to ScratchPadStatus for all slots.

Examples

auto status_map = blob.get_status_map();
for (const auto& [type, status] : status_map) {
    if (status == StateBlob::ScratchPadStatus::ENROLLED_NOT_INITIALIZED) {
        std::cout << "Scratchpad " << static_cast<int>(type) << " needs initialization\n";
    }
}

initialized()

template<IsScratchPad CTX>

bool gridfire::engine::scratch::StateBlob::initialized ( ) const

inlinenodiscard

Check if a specific scratchpad type is initialized.

Template Parameters

CTX	The scratchpad type to check (must satisfy IsScratchPad).

Returns

true if the scratchpad is enrolled and initialized.

Exceptions

exceptions::ScratchPadError

if the scratchpad type is not enrolled.

Examples

if (blob.initialized<GraphEngineScratchPad>()) {
    // Safe to use the scratchpad
}

Member Data Documentation

MAX_SCRATCHPADS

size_t gridfire::engine::scratch::StateBlob::MAX_SCRATCHPADS = static_cast<size_t>(ScratchPadType::_COUNT)

staticconstexprprivate

Maximum number of scratchpad slots, derived from ScratchPadType::_COUNT.

scratchpad_enrolled_flags

std::array<bool, MAX_SCRATCHPADS> gridfire::engine::scratch::StateBlob::scratchpad_enrolled_flags {false}

private

Flags indicating which scratchpad slots have been enrolled.

scratchpads

std::array<std::unique_ptr<AbstractScratchPad>, MAX_SCRATCHPADS> gridfire::engine::scratch::StateBlob::scratchpads {}

private

Array of scratchpad instances indexed by ScratchPadType.

---

The documentation for this class was generated from the following file:

• src/include/gridfire/engine/scratchpads/blob.h