tboudreaux/MeanField_SERiF
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
MeanField_SERiF/docs/man/man3/serif_utils_dependencies_ComputationCache.3

331 lines
21 KiB
Groff
Raw Permalink Normal View History

docs(docs): built docs Note for now much of the docs is LLM written. This was done to save time and focus on code development. The docs have been LOOSLEY reviewed. However, the code itself has been either fully written by hand or fully reviewed. Therefore, the docs should at the moment be seen as a loose resource rather than authoratiative (and this is on top of the general ability for docs to drift)
2026-11-09 14:09:44 -05:00
.TH "serif::utils::dependencies::ComputationCache< GraphT, ContextT, ErrorT, ObserversT >" 3 "Version v0.0.1a" "SERiF" \" -*- nroff -*-
.ad l
.nh
.SH NAME
serif::utils::dependencies::ComputationCache< GraphT, ContextT, ErrorT, ObserversT > \- Execute a computational graph on demand, publishing immutable results only after the entire request succeeds\&.
.SH SYNOPSIS
.br
.PP
.PP
\fR#include <computation_cache\&.hpp>\fP
.SS "Public Types"
.in +1c
.ti -1c
.RI "using \fBTraits\fP = \fBdetail::ComputationCacheTraits\fP<GraphT, ContextT, ErrorT>"
.br
.ti -1c
.RI "using \fBBindings\fP = typename Traits::Bindings"
.br
.ti -1c
.RI "using \fBSources\fP = typename Traits::Sources"
.br
.ti -1c
.RI "using \fBReport\fP = \fBPreparationReport\fP<typename GraphT::Results, \fBSources\fP>"
.br
.ti -1c
.RI "using \fBFailure\fP = \fBPreparationFailure\fP<ErrorT>"
.br
.in -1c
.SS "Public Member Functions"
.in +1c
.ti -1c
.RI "\fBComputationCache\fP (GraphT graph, ObserversT observers=ObserversT{})"
.br
.RI "Own the graph, observer callbacks, and accepted cache; each preparation borrows its context\&. "
.ti -1c
.RI "\fBComputationCache\fP (const \fBComputationCache\fP &)=delete"
.br
.ti -1c
.RI "\fBComputationCache\fP & \fBoperator=\fP (const \fBComputationCache\fP &)=delete"
.br
.ti -1c
.RI "\fBComputationCache\fP (\fBComputationCache\fP &&other)"
.br
.RI "Transfer accepted results while leaving the original object unprepared\&. "
.ti -1c
.RI "\fBComputationCache\fP & \fBoperator=\fP (\fBComputationCache\fP &&)=delete"
.br
.ti -1c
.RI "template<IsKeyList RequestedT = GraphT::Results>
.br
requires \fBdetail::key_list_subset_v\fP<std::remove_cvref_t<RequestedT>, typename GraphT::Results>std::expected< \fBReport\fP, \fBFailure\fP > \fBtry_prepare\fP (const ContextT &context, RequestedT={}, const \fBPreparationMode\fP mode=\fBPreparationMode::reuse_unchanged\fP)"
.br
.RI "Prepare the requested results and their prerequisites, publishing only a complete successful candidate\&. "
.ti -1c
.RI "template<typename KeyT>
.br
requires \fBdetail::contains_key_v\fP<KeyT, typename GraphT::Results>bool \fBcontains\fP () const"
.br
.RI "Test whether a result belongs to the latest successful request, including its prerequisites\&. "
.ti -1c
.RI "template<typename KeyT>
.br
requires \fBdetail::contains_key_v\fP<KeyT, typename GraphT::Results>const auto & \fBget\fP () const"
.br
.RI "Read a frozen result\&. References remain valid until the next preparation or invalidation\&. "
.ti -1c
.RI "template<typename KeyT>
.br
requires \fBdetail::contains_key_v\fP<KeyT, typename GraphT::Results>auto \fBshare\fP () const"
.br
.RI "Retain an immutable accepted result independently of subsequent cache preparations\&. "
.ti -1c
.RI "const \fBReport\fP & \fBreport\fP () const noexcept"
.br
.RI "\fBReport\fP reuse and rebuilding from the latest successful preparation\&. "
.ti -1c
.RI "bool \fBready\fP () const noexcept"
.br
.RI "A failed preparation makes all result access unavailable until a subsequent success\&. "
.ti -1c
.RI "std::size_t \fBpreparation_count\fP () const noexcept"
.br
.RI "Count successful preparations, including requests whose results were all reused\&. "
.ti -1c
.RI "void \fBclear_preparation\fP () noexcept"
.br
.RI "Make results unavailable before validating a new candidate's inputs\&. "
.ti -1c
.RI "void \fBinvalidate\fP () noexcept"
.br
.RI "Discard accepted snapshots and results, requiring fresh preparation on the next request\&. "
.in -1c
.SS "Private Types"
.in +1c
.ti -1c
.RI "using \fBStorage\fP = \fBdetail::ComputationCacheStorage\fP<GraphT, \fBBindings\fP, typename Traits::Resources, std::make_index_sequence<GraphT::size>>"
.br
.ti -1c
.RI "using \fBResultMask\fP = typename GraphT::Dependencies::Mask"
.br
.ti -1c
.RI "using \fBSourceMask\fP = std::array<bool, \fBsource_count\fP>"
.br
.in -1c
.SS "Private Member Functions"
.in +1c
.ti -1c
.RI "template<typename KeyT> void \fBinspect_source\fP (const ContextT &context, \fBStorage\fP &candidate, \fBReport\fP &\fBreport\fP, \fBSourceMask\fP &inspected, const \fBPreparationMode\fP mode) const"
.br
.RI "Inspect each required source once; other context objects need no snapshot policy\&. "
.ti -1c
.RI "template<typename KeyT> const auto & \fBinput_value\fP (const ContextT &context, const \fBStorage\fP &candidate) const"
.br
.RI "\fBSources\fP and computed prerequisites expose the same read-only values to edge observers\&. "
.ti -1c
.RI "template<typename ComputationT, typename KeyT> const auto & \fBinput\fP (const ContextT &context, const \fBStorage\fP &candidate) const"
.br
.RI "Only computed prerequisites have immutable owning handles; ordinary inputs remain references\&. "
.ti -1c
.RI "template<std::size_t Index, typename\&.\&.\&. Keys> auto \fBevaluate_node\fP (const ContextT &context, const \fBStorage\fP &candidate, \fBKeyList\fP< Keys\&.\&.\&. >)"
.br
.RI "Execute one node after its inputs are ready and reuse has been ruled out\&. "
.ti -1c
.RI "template<std::size_t Index, typename\&.\&.\&. Keys> std::expected< void, \fBFailure\fP > \fBprepare_one\fP (const ContextT &context, \fBStorage\fP &candidate, \fBReport\fP &\fBreport\fP, \fBSourceMask\fP &inspected, const \fBPreparationMode\fP mode, \fBKeyList\fP< Keys\&.\&.\&. >)"
.br
.RI "Reuse a result only when every input version matches its accepted version\&. "
.ti -1c
.RI "template<std::size_t Position> std::expected< void, \fBFailure\fP > \fBprepare_in_order\fP (const ContextT &context, \fBStorage\fP &candidate, \fBReport\fP &\fBreport\fP, \fBSourceMask\fP &inspected, const \fBResultMask\fP &required, \fBPreparationMode\fP mode)"
.br
.RI "Follow the compile-time order while skipping branches outside the requested closure\&. "
.in -1c
.SS "Static Private Member Functions"
.in +1c
.ti -1c
.RI "template<typename KeyT> static consteval std::size_t \fBversion_index\fP ()"
.br
.RI "Share one version namespace between source snapshots and computed results\&. "
.in -1c
.SS "Private Attributes"
.in +1c
.ti -1c
.RI "GraphT \fBm_graph\fP"
.br
.ti -1c
.RI "ObserversT \fBm_observers\fP"
.br
.ti -1c
.RI "\fBStorage\fP \fBm_storage\fP"
.br
.ti -1c
.RI "\fBReport\fP \fBm_report\fP"
.br
.ti -1c
.RI "bool \fBm_ready\fP {false}"
.br
.ti -1c
.RI "std::size_t \fBm_preparation_count\fP {0}"
.br
.in -1c
.SS "Static Private Attributes"
.in +1c
.ti -1c
.RI "static constexpr std::size_t \fBsource_count\fP = \fBdetail::KeyListSize\fP<\fBSources\fP>::value"
.br
.in -1c
.SH "Detailed Description"
.PP
.SS "template<typename GraphT, typename ContextT, typename ErrorT = std::string, typename ObserversT = Observers<>>
.br
requires CanPrepare<GraphT, ContextT, ErrorT> && ObserversFor<ObserversT, GraphT, ContextT>
.br
class serif::utils::dependencies::ComputationCache< GraphT, ContextT, ErrorT, ObserversT >"Execute a computational graph on demand, publishing immutable results only after the entire request succeeds\&.
.SH "Member Typedef Documentation"
.PP
.SS "template<typename GraphT, typename ContextT, typename ErrorT = std::string, typename ObserversT = Observers<>> using \fBserif::utils::dependencies::ComputationCache\fP< GraphT, ContextT, ErrorT, ObserversT >::Bindings = typename Traits::Bindings"
.SS "template<typename GraphT, typename ContextT, typename ErrorT = std::string, typename ObserversT = Observers<>> using \fBserif::utils::dependencies::ComputationCache\fP< GraphT, ContextT, ErrorT, ObserversT >::Failure = \fBPreparationFailure\fP<ErrorT>"
.SS "template<typename GraphT, typename ContextT, typename ErrorT = std::string, typename ObserversT = Observers<>> using \fBserif::utils::dependencies::ComputationCache\fP< GraphT, ContextT, ErrorT, ObserversT >::Report = \fBPreparationReport\fP<typename GraphT::Results, \fBSources\fP>"
.SS "template<typename GraphT, typename ContextT, typename ErrorT = std::string, typename ObserversT = Observers<>> using \fBserif::utils::dependencies::ComputationCache\fP< GraphT, ContextT, ErrorT, ObserversT >::ResultMask = typename GraphT::Dependencies::Mask\fR [private]\fP"
.SS "template<typename GraphT, typename ContextT, typename ErrorT = std::string, typename ObserversT = Observers<>> using \fBserif::utils::dependencies::ComputationCache\fP< GraphT, ContextT, ErrorT, ObserversT >::SourceMask = std::array<bool, \fBsource_count\fP>\fR [private]\fP"
.SS "template<typename GraphT, typename ContextT, typename ErrorT = std::string, typename ObserversT = Observers<>> using \fBserif::utils::dependencies::ComputationCache\fP< GraphT, ContextT, ErrorT, ObserversT >::Sources = typename Traits::Sources"
.SS "template<typename GraphT, typename ContextT, typename ErrorT = std::string, typename ObserversT = Observers<>> using \fBserif::utils::dependencies::ComputationCache\fP< GraphT, ContextT, ErrorT, ObserversT >::Storage = \fBdetail::ComputationCacheStorage\fP<GraphT, \fBBindings\fP, typename Traits::Resources, std::make_index_sequence<GraphT::size>>\fR [private]\fP"
.SS "template<typename GraphT, typename ContextT, typename ErrorT = std::string, typename ObserversT = Observers<>> using \fBserif::utils::dependencies::ComputationCache\fP< GraphT, ContextT, ErrorT, ObserversT >::Traits = \fBdetail::ComputationCacheTraits\fP<GraphT, ContextT, ErrorT>"
.SH "Constructor & Destructor Documentation"
.PP
.SS "template<typename GraphT, typename ContextT, typename ErrorT = std::string, typename ObserversT = Observers<>> \fBserif::utils::dependencies::ComputationCache\fP< GraphT, ContextT, ErrorT, ObserversT >::ComputationCache (GraphT graph, ObserversT observers = \fRObserversT{}\fP)\fR [inline]\fP, \fR [explicit]\fP"
.PP
Own the graph, observer callbacks, and accepted cache; each preparation borrows its context\&.
.SS "template<typename GraphT, typename ContextT, typename ErrorT = std::string, typename ObserversT = Observers<>> \fBserif::utils::dependencies::ComputationCache\fP< GraphT, ContextT, ErrorT, ObserversT >::ComputationCache (const \fBComputationCache\fP< GraphT, ContextT, ErrorT, ObserversT > & )\fR [delete]\fP"
.SS "template<typename GraphT, typename ContextT, typename ErrorT = std::string, typename ObserversT = Observers<>> \fBserif::utils::dependencies::ComputationCache\fP< GraphT, ContextT, ErrorT, ObserversT >::ComputationCache (\fBComputationCache\fP< GraphT, ContextT, ErrorT, ObserversT > && other)\fR [inline]\fP"
.PP
Transfer accepted results while leaving the original object unprepared\&.
.SH "Member Function Documentation"
.PP
.SS "template<typename GraphT, typename ContextT, typename ErrorT = std::string, typename ObserversT = Observers<>> void \fBserif::utils::dependencies::ComputationCache\fP< GraphT, ContextT, ErrorT, ObserversT >::clear_preparation ()\fR [inline]\fP, \fR [noexcept]\fP"
.PP
Make results unavailable before validating a new candidate's inputs\&.
.PP
\fBNote\fP
.RS 4
Accepted snapshots remain reusable after rejection; only a successful preparation restores public access\&. Owning handles obtained earlier remain valid\&.
.RE
.PP
.SS "template<typename GraphT, typename ContextT, typename ErrorT = std::string, typename ObserversT = Observers<>> template<typename KeyT>
.br
requires \fBdetail::contains_key_v\fP<KeyT, typename GraphT::Results>bool \fBserif::utils::dependencies::ComputationCache\fP< GraphT, ContextT, ErrorT, ObserversT >::contains () const\fR [inline]\fP, \fR [nodiscard]\fP"
.PP
Test whether a result belongs to the latest successful request, including its prerequisites\&.
.SS "template<typename GraphT, typename ContextT, typename ErrorT = std::string, typename ObserversT = Observers<>> template<std::size_t Index, typename\&.\&.\&. Keys> auto \fBserif::utils::dependencies::ComputationCache\fP< GraphT, ContextT, ErrorT, ObserversT >::evaluate_node (const ContextT & context, const \fBStorage\fP & candidate, \fBKeyList\fP< Keys\&.\&.\&. > )\fR [inline]\fP, \fR [nodiscard]\fP, \fR [private]\fP"
.PP
Execute one node after its inputs are ready and reuse has been ruled out\&.
.PP
\fBNote\fP
.RS 4
This returns a candidate; it does not publish results or change the accepted cache\&.
.RE
.PP
.SS "template<typename GraphT, typename ContextT, typename ErrorT = std::string, typename ObserversT = Observers<>> template<typename KeyT>
.br
requires \fBdetail::contains_key_v\fP<KeyT, typename GraphT::Results>const auto & \fBserif::utils::dependencies::ComputationCache\fP< GraphT, ContextT, ErrorT, ObserversT >::get () const\fR [inline]\fP, \fR [nodiscard]\fP"
.PP
Read a frozen result\&. References remain valid until the next preparation or invalidation\&.
.SS "template<typename GraphT, typename ContextT, typename ErrorT = std::string, typename ObserversT = Observers<>> template<typename ComputationT, typename KeyT> const auto & \fBserif::utils::dependencies::ComputationCache\fP< GraphT, ContextT, ErrorT, ObserversT >::input (const ContextT & context, const \fBStorage\fP & candidate) const\fR [inline]\fP, \fR [nodiscard]\fP, \fR [private]\fP"
.PP
Only computed prerequisites have immutable owning handles; ordinary inputs remain references\&.
.SS "template<typename GraphT, typename ContextT, typename ErrorT = std::string, typename ObserversT = Observers<>> template<typename KeyT> const auto & \fBserif::utils::dependencies::ComputationCache\fP< GraphT, ContextT, ErrorT, ObserversT >::input_value (const ContextT & context, const \fBStorage\fP & candidate) const\fR [inline]\fP, \fR [nodiscard]\fP, \fR [private]\fP"
.PP
\fBSources\fP and computed prerequisites expose the same read-only values to edge observers\&.
.SS "template<typename GraphT, typename ContextT, typename ErrorT = std::string, typename ObserversT = Observers<>> template<typename KeyT> void \fBserif::utils::dependencies::ComputationCache\fP< GraphT, ContextT, ErrorT, ObserversT >::inspect_source (const ContextT & context, \fBStorage\fP & candidate, \fBReport\fP & report, \fBSourceMask\fP & inspected, const \fBPreparationMode\fP mode) const\fR [inline]\fP, \fR [private]\fP"
.PP
Inspect each required source once; other context objects need no snapshot policy\&.
.SS "template<typename GraphT, typename ContextT, typename ErrorT = std::string, typename ObserversT = Observers<>> void \fBserif::utils::dependencies::ComputationCache\fP< GraphT, ContextT, ErrorT, ObserversT >::invalidate ()\fR [inline]\fP, \fR [noexcept]\fP"
.PP
Discard accepted snapshots and results, requiring fresh preparation on the next request\&.
.SS "template<typename GraphT, typename ContextT, typename ErrorT = std::string, typename ObserversT = Observers<>> \fBComputationCache\fP & \fBserif::utils::dependencies::ComputationCache\fP< GraphT, ContextT, ErrorT, ObserversT >::operator= (\fBComputationCache\fP< GraphT, ContextT, ErrorT, ObserversT > && )\fR [delete]\fP"
.SS "template<typename GraphT, typename ContextT, typename ErrorT = std::string, typename ObserversT = Observers<>> \fBComputationCache\fP & \fBserif::utils::dependencies::ComputationCache\fP< GraphT, ContextT, ErrorT, ObserversT >::operator= (const \fBComputationCache\fP< GraphT, ContextT, ErrorT, ObserversT > & )\fR [delete]\fP"
.SS "template<typename GraphT, typename ContextT, typename ErrorT = std::string, typename ObserversT = Observers<>> std::size_t \fBserif::utils::dependencies::ComputationCache\fP< GraphT, ContextT, ErrorT, ObserversT >::preparation_count () const\fR [inline]\fP, \fR [nodiscard]\fP, \fR [noexcept]\fP"
.PP
Count successful preparations, including requests whose results were all reused\&.
.SS "template<typename GraphT, typename ContextT, typename ErrorT = std::string, typename ObserversT = Observers<>> template<std::size_t Position> std::expected< void, \fBFailure\fP > \fBserif::utils::dependencies::ComputationCache\fP< GraphT, ContextT, ErrorT, ObserversT >::prepare_in_order (const ContextT & context, \fBStorage\fP & candidate, \fBReport\fP & report, \fBSourceMask\fP & inspected, const \fBResultMask\fP & required, \fBPreparationMode\fP mode)\fR [inline]\fP, \fR [nodiscard]\fP, \fR [private]\fP"
.PP
Follow the compile-time order while skipping branches outside the requested closure\&.
.SS "template<typename GraphT, typename ContextT, typename ErrorT = std::string, typename ObserversT = Observers<>> template<std::size_t Index, typename\&.\&.\&. Keys> std::expected< void, \fBFailure\fP > \fBserif::utils::dependencies::ComputationCache\fP< GraphT, ContextT, ErrorT, ObserversT >::prepare_one (const ContextT & context, \fBStorage\fP & candidate, \fBReport\fP & report, \fBSourceMask\fP & inspected, const \fBPreparationMode\fP mode, \fBKeyList\fP< Keys\&.\&.\&. > )\fR [inline]\fP, \fR [nodiscard]\fP, \fR [private]\fP"
.PP
Reuse a result only when every input version matches its accepted version\&.
.SS "template<typename GraphT, typename ContextT, typename ErrorT = std::string, typename ObserversT = Observers<>> bool \fBserif::utils::dependencies::ComputationCache\fP< GraphT, ContextT, ErrorT, ObserversT >::ready () const\fR [inline]\fP, \fR [nodiscard]\fP, \fR [noexcept]\fP"
.PP
A failed preparation makes all result access unavailable until a subsequent success\&.
.SS "template<typename GraphT, typename ContextT, typename ErrorT = std::string, typename ObserversT = Observers<>> const \fBReport\fP & \fBserif::utils::dependencies::ComputationCache\fP< GraphT, ContextT, ErrorT, ObserversT >::report () const\fR [inline]\fP, \fR [nodiscard]\fP, \fR [noexcept]\fP"
.PP
\fBReport\fP reuse and rebuilding from the latest successful preparation\&.
.SS "template<typename GraphT, typename ContextT, typename ErrorT = std::string, typename ObserversT = Observers<>> template<typename KeyT>
.br
requires \fBdetail::contains_key_v\fP<KeyT, typename GraphT::Results>auto \fBserif::utils::dependencies::ComputationCache\fP< GraphT, ContextT, ErrorT, ObserversT >::share () const\fR [inline]\fP, \fR [nodiscard]\fP"
.PP
Retain an immutable accepted result independently of subsequent cache preparations\&.
.PP
\fBNote\fP
.RS 4
This retains the result itself; resources borrowed by that result must still outlive their use\&.
.RE
.PP
.SS "template<typename GraphT, typename ContextT, typename ErrorT = std::string, typename ObserversT = Observers<>> template<IsKeyList RequestedT = GraphT::Results>
.br
requires \fBdetail::key_list_subset_v\fP<std::remove_cvref_t<RequestedT>, typename GraphT::Results>std::expected< \fBReport\fP, \fBFailure\fP > \fBserif::utils::dependencies::ComputationCache\fP< GraphT, ContextT, ErrorT, ObserversT >::try_prepare (const ContextT & context, RequestedT = \fR{}\fP, const \fBPreparationMode\fP mode = \fR\fBPreparationMode::reuse_unchanged\fP\fP)\fR [inline]\fP, \fR [nodiscard]\fP"
.PP
Prepare the requested results and their prerequisites, publishing only a complete successful candidate\&.
.SS "template<typename GraphT, typename ContextT, typename ErrorT = std::string, typename ObserversT = Observers<>> template<typename KeyT> static consteval std::size_t \fBserif::utils::dependencies::ComputationCache\fP< GraphT, ContextT, ErrorT, ObserversT >::version_index ()\fR [inline]\fP, \fR [static]\fP, \fR [nodiscard]\fP, \fR [consteval]\fP, \fR [private]\fP"
.PP
Share one version namespace between source snapshots and computed results\&.
.SH "Member Data Documentation"
.PP
.SS "template<typename GraphT, typename ContextT, typename ErrorT = std::string, typename ObserversT = Observers<>> GraphT \fBserif::utils::dependencies::ComputationCache\fP< GraphT, ContextT, ErrorT, ObserversT >::m_graph\fR [private]\fP"
.SS "template<typename GraphT, typename ContextT, typename ErrorT = std::string, typename ObserversT = Observers<>> ObserversT \fBserif::utils::dependencies::ComputationCache\fP< GraphT, ContextT, ErrorT, ObserversT >::m_observers\fR [private]\fP"
.SS "template<typename GraphT, typename ContextT, typename ErrorT = std::string, typename ObserversT = Observers<>> std::size_t \fBserif::utils::dependencies::ComputationCache\fP< GraphT, ContextT, ErrorT, ObserversT >::m_preparation_count {0}\fR [private]\fP"
.SS "template<typename GraphT, typename ContextT, typename ErrorT = std::string, typename ObserversT = Observers<>> bool \fBserif::utils::dependencies::ComputationCache\fP< GraphT, ContextT, ErrorT, ObserversT >::m_ready {false}\fR [private]\fP"
.SS "template<typename GraphT, typename ContextT, typename ErrorT = std::string, typename ObserversT = Observers<>> \fBReport\fP \fBserif::utils::dependencies::ComputationCache\fP< GraphT, ContextT, ErrorT, ObserversT >::m_report\fR [private]\fP"
.SS "template<typename GraphT, typename ContextT, typename ErrorT = std::string, typename ObserversT = Observers<>> \fBStorage\fP \fBserif::utils::dependencies::ComputationCache\fP< GraphT, ContextT, ErrorT, ObserversT >::m_storage\fR [private]\fP"
.SS "template<typename GraphT, typename ContextT, typename ErrorT = std::string, typename ObserversT = Observers<>> std::size_t \fBserif::utils::dependencies::ComputationCache\fP< GraphT, ContextT, ErrorT, ObserversT >::source_count = \fBdetail::KeyListSize\fP<\fBSources\fP>::value\fR [static]\fP, \fR [constexpr]\fP, \fR [private]\fP"
.SH "Author"
.PP
Generated automatically by Doxygen for SERiF from the source code\&.
Reference in New Issue Copy Permalink