Loading...
Searching...
No Matches
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:
[legend]

## 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());
  }
  gridfire::engine::scratch::StateBlob::StateBlob
  StateBlob()=default
  Default constructor.
  gridfire::engine::scratch::StateBlob::enroll
  void enroll()
  Enroll a new scratchpad type into the blob.
  Definition blob.h:196
  gridfire::engine::scratch::StateBlob::clone_structure
  std::unique_ptr< StateBlob > clone_structure() const
  Create a deep copy of this blob with all enrolled scratchpads.
  Definition blob.h:361
  gridfire::engine::scratch::StateBlob::get
  std::expected< CTX *, Error > get() const
  Retrieve a scratchpad by type.
  Definition blob.h:230
  gridfire::engine::scratch
  Scratchpad memory management for computational engines.
  Definition blob.h:69
  gridfire::engine
  Definition dynamic_engine_diagnostics.h:39
  gridfire::engine::scratch::GraphEngineScratchPad
  Scratchpad for storing CppAD automatic differentiation state for GraphEngine.
  Definition engine_graph_scratchpad.h:83

## 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>();
  gridfire::engine::scratch::AdaptiveEngineViewScratchPad
  Scratchpad for storing working memory used by AdaptiveEngineView computations.
  Definition engine_adaptive_scratchpad.h:66

## 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());
  }
  gridfire::engine::scratch::StateBlob::error_to_string
  static std::string error_to_string(const Error error)
  Convert an Error enum value to a human-readable string.
  Definition blob.h:142

## 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
  }
  }
  gridfire::engine::scratch::StateBlob::Error::SCRATCHPAD_NOT_INITIALIZED
  @ SCRATCHPAD_NOT_INITIALIZED
  Scratchpad exists but is not initialized.
  Definition blob.h:122

## 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...
  }
  }
  gridfire::engine::scratch::ScratchPadType
  ScratchPadType
  Enumeration of all registered scratchpad types.
  Definition types.h:64
  gridfire::engine::scratch::ScratchPadType::GRAPH_ENGINE_SCRATCHPAD
  @ GRAPH_ENGINE_SCRATCHPAD
  GraphEngineScratchPad for CppAD-based engines.
  Definition types.h:65
  gridfire::engine::scratch::AbstractScratchPad
  Abstract base struct for engine scratchpad memory.
  Definition scratchpad_abstract.h:82

## 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;
  }
  gridfire::engine::scratch::StateBlob::ScratchPadStatus::NOT_ENROLLED
  @ NOT_ENROLLED
  No scratchpad has been enrolled for this slot.
  Definition blob.h:163
  gridfire::engine::scratch::StateBlob::ScratchPadStatus::ENROLLED_NOT_INITIALIZED
  @ ENROLLED_NOT_INITIALIZED
  Scratchpad enrolled but not yet initialized.
  Definition blob.h:164
  gridfire::engine::scratch::StateBlob::ScratchPadStatus::ENROLLED_INITIALIZED
  @ ENROLLED_INITIALIZED
  Scratchpad enrolled and fully initialized.
  Definition blob.h:165

## 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