serif::utils::dependencies::ComputationCache< GraphT, ContextT, ErrorT, ObserversT > Class Template Reference

Execute a computational graph on demand, publishing immutable results only after the entire request succeeds. More...

#include <computation_cache.hpp>

Collaboration diagram for serif::utils::dependencies::ComputationCache< GraphT, ContextT, ErrorT, ObserversT >:

Public Types
using	Traits = detail::ComputationCacheTraits<GraphT, ContextT, ErrorT>
using	Bindings = typename Traits::Bindings
using	Sources = typename Traits::Sources
using	Report = PreparationReport<typename GraphT::Results, Sources>
using	Failure = PreparationFailure<ErrorT>

Public Member Functions
	ComputationCache (GraphT graph, ObserversT observers=ObserversT{})
	Own the graph, observer callbacks, and accepted cache; each preparation borrows its context.
	ComputationCache (const ComputationCache &)=delete
ComputationCache &	operator= (const ComputationCache &)=delete
	ComputationCache (ComputationCache &&other)
	Transfer accepted results while leaving the original object unprepared.
ComputationCache &	operator= (ComputationCache &&)=delete
template<IsKeyList RequestedT = GraphT::Results> requires detail::key_list_subset_v<std::remove_cvref_t<RequestedT>, typename GraphT::Results>
std::expected< Report, Failure >	try_prepare (const ContextT &context, RequestedT={}, const PreparationMode mode=PreparationMode::reuse_unchanged)
	Prepare the requested results and their prerequisites, publishing only a complete successful candidate.
template<typename KeyT> requires detail::contains_key_v<KeyT, typename GraphT::Results>
bool	contains () const
	Test whether a result belongs to the latest successful request, including its prerequisites.
template<typename KeyT> requires detail::contains_key_v<KeyT, typename GraphT::Results>
const auto &	get () const
	Read a frozen result. References remain valid until the next preparation or invalidation.
template<typename KeyT> requires detail::contains_key_v<KeyT, typename GraphT::Results>
auto	share () const
	Retain an immutable accepted result independently of subsequent cache preparations.
const Report &	report () const noexcept
	Report reuse and rebuilding from the latest successful preparation.
bool	ready () const noexcept
	A failed preparation makes all result access unavailable until a subsequent success.
std::size_t	preparation_count () const noexcept
	Count successful preparations, including requests whose results were all reused.
void	clear_preparation () noexcept
	Make results unavailable before validating a new candidate's inputs.
void	invalidate () noexcept
	Discard accepted snapshots and results, requiring fresh preparation on the next request.

Private Types
using	Storage = detail::ComputationCacheStorage<GraphT, Bindings, typename Traits::Resources, std::make_index_sequence<GraphT::size>>
using	ResultMask = typename GraphT::Dependencies::Mask
using	SourceMask = std::array<bool, source_count>

Private Member Functions
template<typename KeyT>
void	inspect_source (const ContextT &context, Storage &candidate, Report &report, SourceMask &inspected, const PreparationMode mode) const
	Inspect each required source once; other context objects need no snapshot policy.
template<typename KeyT>
const auto &	input_value (const ContextT &context, const Storage &candidate) const
	Sources and computed prerequisites expose the same read-only values to edge observers.
template<typename ComputationT, typename KeyT>
const auto &	input (const ContextT &context, const Storage &candidate) const
	Only computed prerequisites have immutable owning handles; ordinary inputs remain references.
template<std::size_t Index, typename... Keys>
auto	evaluate_node (const ContextT &context, const Storage &candidate, KeyList< Keys... >)
	Execute one node after its inputs are ready and reuse has been ruled out.
template<std::size_t Index, typename... Keys>
std::expected< void, Failure >	prepare_one (const ContextT &context, Storage &candidate, Report &report, SourceMask &inspected, const PreparationMode mode, KeyList< Keys... >)
	Reuse a result only when every input version matches its accepted version.
template<std::size_t Position>
std::expected< void, Failure >	prepare_in_order (const ContextT &context, Storage &candidate, Report &report, SourceMask &inspected, const ResultMask &required, PreparationMode mode)
	Follow the compile-time order while skipping branches outside the requested closure.

Static Private Member Functions
template<typename KeyT>
static consteval std::size_t	version_index ()
	Share one version namespace between source snapshots and computed results.

Private Attributes
GraphT	m_graph
ObserversT	m_observers
Storage	m_storage
Report	m_report
bool	m_ready {false}
std::size_t	m_preparation_count {0}

Static Private Attributes
static constexpr std::size_t	source_count = detail::KeyListSize<Sources>::value

Detailed Description

template<typename GraphT, typename ContextT, typename ErrorT = std::string, typename ObserversT = Observers<>>
requires CanPrepare<GraphT, ContextT, ErrorT> && ObserversFor<ObserversT, GraphT, ContextT>
class serif::utils::dependencies::ComputationCache< GraphT, ContextT, ErrorT, ObserversT >

Execute a computational graph on demand, publishing immutable results only after the entire request succeeds.

Member Typedef Documentation

Bindings

template<typename GraphT, typename ContextT, typename ErrorT = std::string, typename ObserversT = Observers<>>

using serif::utils::dependencies::ComputationCache< GraphT, ContextT, ErrorT, ObserversT >::Bindings = typename Traits::Bindings

Failure

template<typename GraphT, typename ContextT, typename ErrorT = std::string, typename ObserversT = Observers<>>

using serif::utils::dependencies::ComputationCache< GraphT, ContextT, ErrorT, ObserversT >::Failure = PreparationFailure<ErrorT>

Report

template<typename GraphT, typename ContextT, typename ErrorT = std::string, typename ObserversT = Observers<>>

using serif::utils::dependencies::ComputationCache< GraphT, ContextT, ErrorT, ObserversT >::Report = PreparationReport<typename GraphT::Results, Sources>

ResultMask

template<typename GraphT, typename ContextT, typename ErrorT = std::string, typename ObserversT = Observers<>>

using serif::utils::dependencies::ComputationCache< GraphT, ContextT, ErrorT, ObserversT >::ResultMask = typename GraphT::Dependencies::Mask

private

SourceMask

template<typename GraphT, typename ContextT, typename ErrorT = std::string, typename ObserversT = Observers<>>

using serif::utils::dependencies::ComputationCache< GraphT, ContextT, ErrorT, ObserversT >::SourceMask = std::array<bool, source_count>

private

Sources

template<typename GraphT, typename ContextT, typename ErrorT = std::string, typename ObserversT = Observers<>>

using serif::utils::dependencies::ComputationCache< GraphT, ContextT, ErrorT, ObserversT >::Sources = typename Traits::Sources

Storage

template<typename GraphT, typename ContextT, typename ErrorT = std::string, typename ObserversT = Observers<>>

using serif::utils::dependencies::ComputationCache< GraphT, ContextT, ErrorT, ObserversT >::Storage = detail::ComputationCacheStorage<GraphT, Bindings, typename Traits::Resources, std::make_index_sequence<GraphT::size>>

private

Traits

template<typename GraphT, typename ContextT, typename ErrorT = std::string, typename ObserversT = Observers<>>

using serif::utils::dependencies::ComputationCache< GraphT, ContextT, ErrorT, ObserversT >::Traits = detail::ComputationCacheTraits<GraphT, ContextT, ErrorT>

Constructor & Destructor Documentation

ComputationCache() [1/3]

template<typename GraphT, typename ContextT, typename ErrorT = std::string, typename ObserversT = Observers<>>

serif::utils::dependencies::ComputationCache< GraphT, ContextT, ErrorT, ObserversT >::ComputationCache ( GraphT graph, ObserversT observers = ObserversT{} )

inlineexplicit

Own the graph, observer callbacks, and accepted cache; each preparation borrows its context.

ComputationCache() [2/3]

template<typename GraphT, typename ContextT, typename ErrorT = std::string, typename ObserversT = Observers<>>

serif::utils::dependencies::ComputationCache< GraphT, ContextT, ErrorT, ObserversT >::ComputationCache ( const ComputationCache< GraphT, ContextT, ErrorT, ObserversT > & )

delete

ComputationCache() [3/3]

template<typename GraphT, typename ContextT, typename ErrorT = std::string, typename ObserversT = Observers<>>

serif::utils::dependencies::ComputationCache< GraphT, ContextT, ErrorT, ObserversT >::ComputationCache ( ComputationCache< GraphT, ContextT, ErrorT, ObserversT > && other )

inline

Transfer accepted results while leaving the original object unprepared.

Member Function Documentation

clear_preparation()

template<typename GraphT, typename ContextT, typename ErrorT = std::string, typename ObserversT = Observers<>>

void serif::utils::dependencies::ComputationCache< GraphT, ContextT, ErrorT, ObserversT >::clear_preparation ( )

inlinenoexcept

Make results unavailable before validating a new candidate's inputs.

Note

Accepted snapshots remain reusable after rejection; only a successful preparation restores public access. Owning handles obtained earlier remain valid.

contains()

template<typename GraphT, typename ContextT, typename ErrorT = std::string, typename ObserversT = Observers<>>

template<typename KeyT>
requires detail::contains_key_v<KeyT, typename GraphT::Results>

bool serif::utils::dependencies::ComputationCache< GraphT, ContextT, ErrorT, ObserversT >::contains ( ) const

inlinenodiscard

Test whether a result belongs to the latest successful request, including its prerequisites.

evaluate_node()

template<typename GraphT, typename ContextT, typename ErrorT = std::string, typename ObserversT = Observers<>>

template<std::size_t Index, typename... Keys>

auto serif::utils::dependencies::ComputationCache< GraphT, ContextT, ErrorT, ObserversT >::evaluate_node ( const ContextT & context, const Storage & candidate, KeyList< Keys... >  )

inlinenodiscardprivate

Execute one node after its inputs are ready and reuse has been ruled out.

Note

This returns a candidate; it does not publish results or change the accepted cache.

get()

template<typename GraphT, typename ContextT, typename ErrorT = std::string, typename ObserversT = Observers<>>

template<typename KeyT>
requires detail::contains_key_v<KeyT, typename GraphT::Results>

const auto & serif::utils::dependencies::ComputationCache< GraphT, ContextT, ErrorT, ObserversT >::get ( ) const

inlinenodiscard

Read a frozen result. References remain valid until the next preparation or invalidation.

input()

template<typename GraphT, typename ContextT, typename ErrorT = std::string, typename ObserversT = Observers<>>

template<typename ComputationT, typename KeyT>

const auto & serif::utils::dependencies::ComputationCache< GraphT, ContextT, ErrorT, ObserversT >::input ( const ContextT & context, const Storage & candidate ) const

inlinenodiscardprivate

Only computed prerequisites have immutable owning handles; ordinary inputs remain references.

input_value()

template<typename GraphT, typename ContextT, typename ErrorT = std::string, typename ObserversT = Observers<>>

template<typename KeyT>

const auto & serif::utils::dependencies::ComputationCache< GraphT, ContextT, ErrorT, ObserversT >::input_value ( const ContextT & context, const Storage & candidate ) const

inlinenodiscardprivate

Sources and computed prerequisites expose the same read-only values to edge observers.

inspect_source()

template<typename GraphT, typename ContextT, typename ErrorT = std::string, typename ObserversT = Observers<>>

template<typename KeyT>

void serif::utils::dependencies::ComputationCache< GraphT, ContextT, ErrorT, ObserversT >::inspect_source ( const ContextT & context, Storage & candidate, Report & report, SourceMask & inspected, const PreparationMode mode ) const

inlineprivate

Inspect each required source once; other context objects need no snapshot policy.

invalidate()

template<typename GraphT, typename ContextT, typename ErrorT = std::string, typename ObserversT = Observers<>>

void serif::utils::dependencies::ComputationCache< GraphT, ContextT, ErrorT, ObserversT >::invalidate ( )

inlinenoexcept

Discard accepted snapshots and results, requiring fresh preparation on the next request.

operator=() [1/2]

template<typename GraphT, typename ContextT, typename ErrorT = std::string, typename ObserversT = Observers<>>

ComputationCache & serif::utils::dependencies::ComputationCache< GraphT, ContextT, ErrorT, ObserversT >::operator= ( ComputationCache< GraphT, ContextT, ErrorT, ObserversT > && )

delete

operator=() [2/2]

template<typename GraphT, typename ContextT, typename ErrorT = std::string, typename ObserversT = Observers<>>

ComputationCache & serif::utils::dependencies::ComputationCache< GraphT, ContextT, ErrorT, ObserversT >::operator= ( const ComputationCache< GraphT, ContextT, ErrorT, ObserversT > & )

delete

preparation_count()

template<typename GraphT, typename ContextT, typename ErrorT = std::string, typename ObserversT = Observers<>>

std::size_t serif::utils::dependencies::ComputationCache< GraphT, ContextT, ErrorT, ObserversT >::preparation_count ( ) const

inlinenodiscardnoexcept

Count successful preparations, including requests whose results were all reused.

prepare_in_order()

template<typename GraphT, typename ContextT, typename ErrorT = std::string, typename ObserversT = Observers<>>

template<std::size_t Position>

std::expected< void, Failure > serif::utils::dependencies::ComputationCache< GraphT, ContextT, ErrorT, ObserversT >::prepare_in_order ( const ContextT & context, Storage & candidate, Report & report, SourceMask & inspected, const ResultMask & required, PreparationMode mode )

inlinenodiscardprivate

Follow the compile-time order while skipping branches outside the requested closure.

prepare_one()

template<typename GraphT, typename ContextT, typename ErrorT = std::string, typename ObserversT = Observers<>>

template<std::size_t Index, typename... Keys>

std::expected< void, Failure > serif::utils::dependencies::ComputationCache< GraphT, ContextT, ErrorT, ObserversT >::prepare_one ( const ContextT & context, Storage & candidate, Report & report, SourceMask & inspected, const PreparationMode mode, KeyList< Keys... >  )

inlinenodiscardprivate

Reuse a result only when every input version matches its accepted version.

ready()

template<typename GraphT, typename ContextT, typename ErrorT = std::string, typename ObserversT = Observers<>>

bool serif::utils::dependencies::ComputationCache< GraphT, ContextT, ErrorT, ObserversT >::ready ( ) const

inlinenodiscardnoexcept

A failed preparation makes all result access unavailable until a subsequent success.

report()

template<typename GraphT, typename ContextT, typename ErrorT = std::string, typename ObserversT = Observers<>>

const Report & serif::utils::dependencies::ComputationCache< GraphT, ContextT, ErrorT, ObserversT >::report ( ) const

inlinenodiscardnoexcept

Report reuse and rebuilding from the latest successful preparation.

share()

template<typename GraphT, typename ContextT, typename ErrorT = std::string, typename ObserversT = Observers<>>

template<typename KeyT>
requires detail::contains_key_v<KeyT, typename GraphT::Results>

auto serif::utils::dependencies::ComputationCache< GraphT, ContextT, ErrorT, ObserversT >::share ( ) const

inlinenodiscard

Retain an immutable accepted result independently of subsequent cache preparations.

Note

This retains the result itself; resources borrowed by that result must still outlive their use.

try_prepare()

template<typename GraphT, typename ContextT, typename ErrorT = std::string, typename ObserversT = Observers<>>

template<IsKeyList RequestedT = GraphT::Results>
requires detail::key_list_subset_v<std::remove_cvref_t<RequestedT>, typename GraphT::Results>

std::expected< Report, Failure > serif::utils::dependencies::ComputationCache< GraphT, ContextT, ErrorT, ObserversT >::try_prepare ( const ContextT & context, RequestedT = {}, const PreparationMode mode = PreparationMode::reuse_unchanged )

inlinenodiscard

Prepare the requested results and their prerequisites, publishing only a complete successful candidate.

version_index()

template<typename GraphT, typename ContextT, typename ErrorT = std::string, typename ObserversT = Observers<>>

template<typename KeyT>

static consteval std::size_t serif::utils::dependencies::ComputationCache< GraphT, ContextT, ErrorT, ObserversT >::version_index ( )

inlinestaticnodiscardconstevalprivate

Share one version namespace between source snapshots and computed results.

Member Data Documentation

m_graph

template<typename GraphT, typename ContextT, typename ErrorT = std::string, typename ObserversT = Observers<>>

GraphT serif::utils::dependencies::ComputationCache< GraphT, ContextT, ErrorT, ObserversT >::m_graph

private

m_observers

template<typename GraphT, typename ContextT, typename ErrorT = std::string, typename ObserversT = Observers<>>

ObserversT serif::utils::dependencies::ComputationCache< GraphT, ContextT, ErrorT, ObserversT >::m_observers

private

m_preparation_count

template<typename GraphT, typename ContextT, typename ErrorT = std::string, typename ObserversT = Observers<>>

std::size_t serif::utils::dependencies::ComputationCache< GraphT, ContextT, ErrorT, ObserversT >::m_preparation_count {0}

private

m_ready

template<typename GraphT, typename ContextT, typename ErrorT = std::string, typename ObserversT = Observers<>>

bool serif::utils::dependencies::ComputationCache< GraphT, ContextT, ErrorT, ObserversT >::m_ready {false}

private

m_report

template<typename GraphT, typename ContextT, typename ErrorT = std::string, typename ObserversT = Observers<>>

Report serif::utils::dependencies::ComputationCache< GraphT, ContextT, ErrorT, ObserversT >::m_report

private

m_storage

template<typename GraphT, typename ContextT, typename ErrorT = std::string, typename ObserversT = Observers<>>

Storage serif::utils::dependencies::ComputationCache< GraphT, ContextT, ErrorT, ObserversT >::m_storage

private

source_count

template<typename GraphT, typename ContextT, typename ErrorT = std::string, typename ObserversT = Observers<>>

std::size_t serif::utils::dependencies::ComputationCache< GraphT, ContextT, ErrorT, ObserversT >::source_count = detail::KeyListSize<Sources>::value

staticconstexprprivate

---

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

• src/include/serif/utils/dependencies/computation_cache.hpp