Loading...
Searching...
No Matches
utils.h File Reference

Utility functions for convenient scratchpad retrieval with exception handling. More...

`#include "gridfire/engine/scratchpads/blob.h"`
`#include "gridfire/exceptions/error_scratchpad.h"`
Include dependency graph for utils.h:
This graph shows which files directly or indirectly include this file:

## Namespaces

namespace | gridfire
namespace | gridfire::engine
namespace | gridfire::engine::scratch
| Scratchpad memory management for computational engines.

## Functions

template<IsScratchPad CTX>
CTX * | gridfire::engine::scratch::get_state (StateBlob &ctx)
| Retrieve a scratchpad from a StateBlob, throwing on error.
template<IsScratchPad CTX>
const CTX * | gridfire::engine::scratch::get_state (const StateBlob &ctx)
| Retrieve a const scratchpad from a const StateBlob, throwing on error.
template<IsScratchPad CTX, bool MUST_BE_INITIALIZED>
CTX * | gridfire::engine::scratch::get_state (StateBlob &ctx)
| Retrieve a scratchpad with optional initialization check, throwing on error.
template<IsScratchPad CTX, bool MUST_BE_INITIALIZED>
const CTX * | gridfire::engine::scratch::get_state (const StateBlob &ctx)
| Retrieve a const scratchpad with optional initialization check, throwing on error.

## Detailed Description

Utility functions for convenient scratchpad retrieval with exception handling.

This header provides helper functions that wrap StateBlob's get() methods, converting error codes into exceptions for simpler error handling. These utilities eliminate the need to manually check std::expected results and switch on error codes at every call site.

Purpose
  The utility functions provide:
  - Exception-based error handling instead of std::expected
  - Consistent error messages across the codebase
  - Both mutable and const-correct overloads
  - Optional initialization checking via template parameter

Examples
  #include "gridfire/engine/scratchpads/utils.h"
  #include "gridfire/engine/scratchpads/engine_graph_scratchpad.h"
  using namespace gridfire::engine::scratch;
  void compute(StateBlob& blob) {
  // Simple retrieval - throws if not found
  GraphEngineScratchPad* scratch = get_state<GraphEngineScratchPad>(blob);
  scratch->initialize(engine);
  // Retrieval with initialization check - throws if not initialized
  auto* initialized_scratch = get_state<GraphEngineScratchPad, true>(blob);
  // Safe to use - guaranteed to be initialized
  }
  void read_only_access(const StateBlob& blob) {
  // Const overload for read-only access
  const GraphEngineScratchPad* scratch = get_state<GraphEngineScratchPad>(blob);
  bool ready = scratch->is_initialized();
  }
  gridfire::engine::scratch::StateBlob
  Container for managing a collection of typed scratchpad instances.
  Definition blob.h:114
  utils.h
  Utility functions for convenient scratchpad retrieval with exception handling.
  engine_graph_scratchpad.h
  Scratchpad implementation for the GraphEngine using CppAD automatic differentiation.
  gridfire::engine::scratch
  Scratchpad memory management for computational engines.
  Definition blob.h:69
  gridfire::engine::scratch::get_state
  CTX * get_state(StateBlob &ctx)
  Retrieve a scratchpad from a StateBlob, throwing on error.
  Definition utils.h:84
  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

Thread Safety
  These functions inherit the thread safety characteristics of StateBlob. They are not thread-safe - each thread should operate on its own StateBlob instance.

See also
  StateBlob
  IsScratchPad
  exceptions::ScratchPadError