Emily Boudreaux
6b57738330
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)
252 lines
14 KiB
Groff
252 lines
14 KiB
Groff
.TH "serif::utils::dependencies::Prepared< PlanT, ContextT, ErrorT >" 3 "Version v0.0.1a" "SERiF" \" -*- nroff -*-
|
|
.ad l
|
|
.nh
|
|
.SH NAME
|
|
serif::utils::dependencies::Prepared< PlanT, ContextT, ErrorT >
|
|
.SH SYNOPSIS
|
|
.br
|
|
.PP
|
|
.PP
|
|
\fR#include <prepared\&.hpp>\fP
|
|
.SS "Public Types"
|
|
|
|
.in +1c
|
|
.ti -1c
|
|
.RI "using \fBTraits\fP = \fBdetail::PreparedTraits\fP<PlanT, 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 PlanT::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 "\fBPrepared\fP (PlanT plan)"
|
|
.br
|
|
.RI "Own a plan and its accepted cache; contexts are supplied separately to each preparation\&. "
|
|
.ti -1c
|
|
.RI "\fBPrepared\fP (const \fBPrepared\fP &)=delete"
|
|
.br
|
|
.ti -1c
|
|
.RI "\fBPrepared\fP & \fBoperator=\fP (const \fBPrepared\fP &)=delete"
|
|
.br
|
|
.ti -1c
|
|
.RI "\fBPrepared\fP (\fBPrepared\fP &&other)"
|
|
.br
|
|
.RI "Transfer accepted results while leaving the original object unprepared\&. "
|
|
.ti -1c
|
|
.RI "\fBPrepared\fP & \fBoperator=\fP (\fBPrepared\fP &&)=delete"
|
|
.br
|
|
.ti -1c
|
|
.RI "template<IsDeclaration RequestedT = typename PlanT::Results>
|
|
.br
|
|
requires \fBdetail::declaration_subset_v\fP<std::remove_cvref_t<RequestedT>, typename PlanT::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 PlanT::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 PlanT::Results>const auto & \fBget\fP () const"
|
|
.br
|
|
.RI "Read a frozen result\&. References remain valid until the next preparation or invalidation\&. "
|
|
.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 "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::PreparedStorage\fP<PlanT, \fBBindings\fP, typename Traits::Resources, std::make_index_sequence<PlanT::size>>"
|
|
.br
|
|
.ti -1c
|
|
.RI "using \fBResultMask\fP = typename PlanT::Graph::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, \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\fP (const ContextT &context, const \fBStorage\fP &candidate) const"
|
|
.br
|
|
.RI "Computations read either a supplied source or a prerequisite already prepared in this candidate\&. "
|
|
.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, \fBPreparationMode\fP mode, \fBDeclaration\fP< Keys\&.\&.\&. >) const"
|
|
.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) const"
|
|
.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 "PlanT \fBm_plan\fP"
|
|
.br
|
|
.ti -1c
|
|
.RI "\fBStorage\fP \fBm_storage\fP"
|
|
.br
|
|
.ti -1c
|
|
.RI "\fBReport\fP \fBm_report\fP"
|
|
.br
|
|
.ti -1c
|
|
.RI "\fBResultMask\fP \fBm_active\fP {}"
|
|
.br
|
|
.ti -1c
|
|
.RI "bool \fBm_ready\fP {false}"
|
|
.br
|
|
.in -1c
|
|
.SS "Static Private Attributes"
|
|
|
|
.in +1c
|
|
.ti -1c
|
|
.RI "static constexpr std::size_t \fBsource_count\fP = \fBdetail::DeclarationSize\fP<\fBSources\fP>::value"
|
|
.br
|
|
.in -1c
|
|
.SH "Member Typedef Documentation"
|
|
.PP
|
|
.SS "template<typename PlanT, typename ContextT, typename ErrorT = std::string> using \fBserif::utils::dependencies::Prepared\fP< PlanT, ContextT, ErrorT >::Bindings = typename Traits::Bindings"
|
|
|
|
.SS "template<typename PlanT, typename ContextT, typename ErrorT = std::string> using \fBserif::utils::dependencies::Prepared\fP< PlanT, ContextT, ErrorT >::Failure = \fBPreparationFailure\fP<ErrorT>"
|
|
|
|
.SS "template<typename PlanT, typename ContextT, typename ErrorT = std::string> using \fBserif::utils::dependencies::Prepared\fP< PlanT, ContextT, ErrorT >::Report = \fBPreparationReport\fP<typename PlanT::Results, \fBSources\fP>"
|
|
|
|
.SS "template<typename PlanT, typename ContextT, typename ErrorT = std::string> using \fBserif::utils::dependencies::Prepared\fP< PlanT, ContextT, ErrorT >::ResultMask = typename PlanT::Graph::Mask\fR [private]\fP"
|
|
|
|
.SS "template<typename PlanT, typename ContextT, typename ErrorT = std::string> using \fBserif::utils::dependencies::Prepared\fP< PlanT, ContextT, ErrorT >::SourceMask = std::array<bool, \fBsource_count\fP>\fR [private]\fP"
|
|
|
|
.SS "template<typename PlanT, typename ContextT, typename ErrorT = std::string> using \fBserif::utils::dependencies::Prepared\fP< PlanT, ContextT, ErrorT >::Sources = typename Traits::Sources"
|
|
|
|
.SS "template<typename PlanT, typename ContextT, typename ErrorT = std::string> using \fBserif::utils::dependencies::Prepared\fP< PlanT, ContextT, ErrorT >::Storage = \fBdetail::PreparedStorage\fP<PlanT, \fBBindings\fP, typename Traits::Resources, std::make_index_sequence<PlanT::size>>\fR [private]\fP"
|
|
|
|
.SS "template<typename PlanT, typename ContextT, typename ErrorT = std::string> using \fBserif::utils::dependencies::Prepared\fP< PlanT, ContextT, ErrorT >::Traits = \fBdetail::PreparedTraits\fP<PlanT, ContextT, ErrorT>"
|
|
|
|
.SH "Constructor & Destructor Documentation"
|
|
.PP
|
|
.SS "template<typename PlanT, typename ContextT, typename ErrorT = std::string> \fBserif::utils::dependencies::Prepared\fP< PlanT, ContextT, ErrorT >::Prepared (PlanT plan)\fR [inline]\fP, \fR [explicit]\fP"
|
|
|
|
.PP
|
|
Own a plan and its accepted cache; contexts are supplied separately to each preparation\&.
|
|
.SS "template<typename PlanT, typename ContextT, typename ErrorT = std::string> \fBserif::utils::dependencies::Prepared\fP< PlanT, ContextT, ErrorT >::Prepared (const \fBPrepared\fP< PlanT, ContextT, ErrorT > & )\fR [delete]\fP"
|
|
|
|
.SS "template<typename PlanT, typename ContextT, typename ErrorT = std::string> \fBserif::utils::dependencies::Prepared\fP< PlanT, ContextT, ErrorT >::Prepared (\fBPrepared\fP< PlanT, ContextT, ErrorT > && other)\fR [inline]\fP"
|
|
|
|
.PP
|
|
Transfer accepted results while leaving the original object unprepared\&.
|
|
.SH "Member Function Documentation"
|
|
.PP
|
|
.SS "template<typename PlanT, typename ContextT, typename ErrorT = std::string> template<typename KeyT>
|
|
.br
|
|
requires \fBdetail::contains_key_v\fP<KeyT, typename PlanT::Results>bool \fBserif::utils::dependencies::Prepared\fP< PlanT, ContextT, ErrorT >::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 PlanT, typename ContextT, typename ErrorT = std::string> template<typename KeyT>
|
|
.br
|
|
requires \fBdetail::contains_key_v\fP<KeyT, typename PlanT::Results>const auto & \fBserif::utils::dependencies::Prepared\fP< PlanT, ContextT, ErrorT >::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 PlanT, typename ContextT, typename ErrorT = std::string> template<typename KeyT> const auto & \fBserif::utils::dependencies::Prepared\fP< PlanT, ContextT, ErrorT >::input (const ContextT & context, const \fBStorage\fP & candidate) const\fR [inline]\fP, \fR [nodiscard]\fP, \fR [private]\fP"
|
|
|
|
.PP
|
|
Computations read either a supplied source or a prerequisite already prepared in this candidate\&.
|
|
.SS "template<typename PlanT, typename ContextT, typename ErrorT = std::string> template<typename KeyT> void \fBserif::utils::dependencies::Prepared\fP< PlanT, ContextT, ErrorT >::inspect_source (const ContextT & context, \fBStorage\fP & candidate, \fBReport\fP & report, \fBSourceMask\fP & inspected, \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 PlanT, typename ContextT, typename ErrorT = std::string> void \fBserif::utils::dependencies::Prepared\fP< PlanT, ContextT, ErrorT >::invalidate ()\fR [inline]\fP, \fR [noexcept]\fP"
|
|
|
|
.PP
|
|
Discard accepted snapshots and results, requiring fresh preparation on the next request\&.
|
|
.SS "template<typename PlanT, typename ContextT, typename ErrorT = std::string> \fBPrepared\fP & \fBserif::utils::dependencies::Prepared\fP< PlanT, ContextT, ErrorT >::operator= (const \fBPrepared\fP< PlanT, ContextT, ErrorT > & )\fR [delete]\fP"
|
|
|
|
.SS "template<typename PlanT, typename ContextT, typename ErrorT = std::string> \fBPrepared\fP & \fBserif::utils::dependencies::Prepared\fP< PlanT, ContextT, ErrorT >::operator= (\fBPrepared\fP< PlanT, ContextT, ErrorT > && )\fR [delete]\fP"
|
|
|
|
.SS "template<typename PlanT, typename ContextT, typename ErrorT = std::string> template<std::size_t Position> std::expected< void, \fBFailure\fP > \fBserif::utils::dependencies::Prepared\fP< PlanT, ContextT, ErrorT >::prepare_in_order (const ContextT & context, \fBStorage\fP & candidate, \fBReport\fP & report, \fBSourceMask\fP & inspected, const \fBResultMask\fP & required, \fBPreparationMode\fP mode) const\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 PlanT, typename ContextT, typename ErrorT = std::string> template<std::size_t Index, typename\&.\&.\&. Keys> std::expected< void, \fBFailure\fP > \fBserif::utils::dependencies::Prepared\fP< PlanT, ContextT, ErrorT >::prepare_one (const ContextT & context, \fBStorage\fP & candidate, \fBReport\fP & report, \fBSourceMask\fP & inspected, \fBPreparationMode\fP mode, \fBDeclaration\fP< Keys\&.\&.\&. > ) const\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 PlanT, typename ContextT, typename ErrorT = std::string> bool \fBserif::utils::dependencies::Prepared\fP< PlanT, ContextT, ErrorT >::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 PlanT, typename ContextT, typename ErrorT = std::string> const \fBReport\fP & \fBserif::utils::dependencies::Prepared\fP< PlanT, ContextT, ErrorT >::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 PlanT, typename ContextT, typename ErrorT = std::string> template<IsDeclaration RequestedT = typename PlanT::Results>
|
|
.br
|
|
requires \fBdetail::declaration_subset_v\fP<std::remove_cvref_t<RequestedT>, typename PlanT::Results>std::expected< \fBReport\fP, \fBFailure\fP > \fBserif::utils::dependencies::Prepared\fP< PlanT, ContextT, ErrorT >::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 PlanT, typename ContextT, typename ErrorT = std::string> template<typename KeyT> static consteval std::size_t \fBserif::utils::dependencies::Prepared\fP< PlanT, ContextT, ErrorT >::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 PlanT, typename ContextT, typename ErrorT = std::string> \fBResultMask\fP \fBserif::utils::dependencies::Prepared\fP< PlanT, ContextT, ErrorT >::m_active {}\fR [private]\fP"
|
|
|
|
.SS "template<typename PlanT, typename ContextT, typename ErrorT = std::string> PlanT \fBserif::utils::dependencies::Prepared\fP< PlanT, ContextT, ErrorT >::m_plan\fR [private]\fP"
|
|
|
|
.SS "template<typename PlanT, typename ContextT, typename ErrorT = std::string> bool \fBserif::utils::dependencies::Prepared\fP< PlanT, ContextT, ErrorT >::m_ready {false}\fR [private]\fP"
|
|
|
|
.SS "template<typename PlanT, typename ContextT, typename ErrorT = std::string> \fBReport\fP \fBserif::utils::dependencies::Prepared\fP< PlanT, ContextT, ErrorT >::m_report\fR [private]\fP"
|
|
|
|
.SS "template<typename PlanT, typename ContextT, typename ErrorT = std::string> \fBStorage\fP \fBserif::utils::dependencies::Prepared\fP< PlanT, ContextT, ErrorT >::m_storage\fR [private]\fP"
|
|
|
|
.SS "template<typename PlanT, typename ContextT, typename ErrorT = std::string> std::size_t \fBserif::utils::dependencies::Prepared\fP< PlanT, ContextT, ErrorT >::source_count = \fBdetail::DeclarationSize\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\&.
|