RPNX::QueryGraph
Typed, memoized, concurrent query evaluation for C++23
Loading...
Searching...
No Matches
rpnx::querygraph::debug_abi::graph Class Reference

Owns handler registrations, memoized nodes, and query execution. More...

#include <querygraph.hpp>

Classes

struct  options
 Configure cumulative node self-time diagnostics. More...
 

Public Member Functions

 graph (scheduler &execution_scheduler)
 Construct an empty graph using a scheduler that outlives it.
 
 graph (scheduler &execution_scheduler, options configuration)
 Construct a graph with timing options and built-in subquery errors.
 
 ~graph ()
 Drain this graph's scheduled work before releasing cached nodes. All external calls on this graph must have returned before destruction.
 
template<query_spec_c QuerySpec>
auto make_request (typename QuerySpec::input_type input) -> typename QuerySpec::output_type
 Execute or reuse a top-level query and return its value.
 
template<query_spec_c QuerySpec>
auto async_make_request (typename QuerySpec::input_type input) -> std::future< typename QuerySpec::output_type >
 Submit a query and return a future without waiting for evaluation.
 
template<subquery_spec_c SubquerySpec>
auto make_subquery_request (typename SubquerySpec::parent_query::input_type parent_input, typename SubquerySpec::input_type input) -> typename SubquerySpec::output_type
 Execute or reuse a subquery request from an external thread.
 
template<query_spec_c QuerySpec>
auto dump_query_to_file (std::filesystem::path output_path, typename QuerySpec::input_type input) -> std::filesystem::path
 Evaluate a root query and write its reachable graph to disk.
 
template<typename Error>
void register_canonical_error ()
 Register an exception type for canonical capture and dumping.
 
template<typename T>
void register_inputoutput_text_descriptor ()
 Register the diagnostic text conversion for a value type.
 
template<typename T>
void register_binary_descriptors ()
 Register serialization operations and a type signature.
 
template<query_handler_spec_c QuerySpec>
void register_handler_map (std::map< query_handler_input_t< QuerySpec >, query_handler_output_t< QuerySpec > > handler_map)
 Register a finite map as a query handler.
 
template<query_handler_spec_c HandlerSpec>
requires std::same_as< query_handler_input_t< HandlerSpec >, std::monostate >
void register_handler_singleton (query_handler_output_t< HandlerSpec > value)
 Register a constant result for a handler with monostate input.
 
template<query_spec_c QuerySpec>
requires std::same_as< typename QuerySpec::input_type, std::monostate >
void register_handler_singleton (typename QuerySpec::output_type value)
 Register a constant result directly from a query spec.
 
template<query_handler_spec_c HandlerSpec, typename Handler>
void register_handler_function (Handler h)
 Register the coroutine function implementing a query.
 
void bind_handlers ()
 Resolve every registered handler's declared dependencies.
 
template<typename Visitor>
void for_each_marshaled_type_descriptor (Visitor visitor)
 Visit the serialization and text descriptors of registered types.
 
graph_data dump ()
 Snapshot every currently memoized query node.
 
std::vector< std::byte > marshall ()
 Serialize a snapshot of every memoized node.
 
bool node_debug_io_capture_enabled () const noexcept
 Return whether human-readable node input/output capture is enabled.
 

Detailed Description

Owns handler registrations, memoized nodes, and query execution.

Configure a graph by registering handlers and canonical errors, then call bind_handlers() before evaluating requests. Nodes and their terminal values remain cached for the lifetime of the graph. Each graph uses an externally owned scheduler, which can execute multiple graphs concurrently. The scheduler must outlive every graph that uses it. Handlers must use coroutine requests for dependencies; synchronous external requests from scheduler workers are unsupported.

Multiple external threads may execute requests concurrently after configuration is complete. Registration and binding must not race with execution. Query input and output references exposed internally remain valid only while the graph and corresponding cached node remain alive.

Definition at line 1049 of file querygraph.hpp.

Constructor & Destructor Documentation

◆ graph()

rpnx::querygraph::debug_abi::graph::graph ( scheduler & execution_scheduler,
options configuration )

Construct a graph with timing options and built-in subquery errors.

Parameters
execution_schedulerShared worker pool; must outlive this graph.
configurationTiming configuration copied into the graph.
Exceptions
std::invalid_argumentIf a timing threshold is negative. Zero timing thresholds report any positive self-time.

Member Function Documentation

◆ async_make_request()

template<query_spec_c QuerySpec>
auto rpnx::querygraph::debug_abi::graph::async_make_request ( typename QuerySpec::input_type input) -> std::future< typename QuerySpec::output_type >
inline

Submit a query and return a future without waiting for evaluation.

Evaluation uses the graph's shared scheduler. Repeated inputs share their memoized node, and each future receives its own output copy. Cached results produce ready futures. Handler errors, dependency cycles, and output-copy errors are rethrown by future::get(). Destroying a future does not cancel or wait for its query. Graph destruction drains pending work; completed futures can outlive it.

Template Parameters
QuerySpecRegistered query specification to evaluate.
Parameters
inputInput value copied into the memoization cache when new.
Returns
A future for this query's value or stored exception.
Exceptions
std::logic_errorIf no matching handler is registered. Submission and allocation failures are thrown directly.

Definition at line 1274 of file querygraph.hpp.

References rpnx::querygraph::result< T >::has_result(), and rpnx::querygraph::result< T >::value().

◆ bind_handlers()

void rpnx::querygraph::debug_abi::graph::bind_handlers ( )

Resolve every registered handler's declared dependencies.

Call this once after all handlers have been registered and before the first request. A missing dependency causes an exception during binding. Repeated calls are harmless when no new handlers were registered, but registering or binding concurrently with execution is unsupported.

◆ dump()

graph_data rpnx::querygraph::debug_abi::graph::dump ( )

Snapshot every currently memoized query node.

Returns
Structured dump with no selected root node.

References dump().

Referenced by dump().

◆ dump_query_to_file()

template<query_spec_c QuerySpec>
auto rpnx::querygraph::debug_abi::graph::dump_query_to_file ( std::filesystem::path output_path,
typename QuerySpec::input_type input ) -> std::filesystem::path
inline

Evaluate a root query and write its reachable graph to disk.

The output is the RPNXSerialization encoding described by doc/dump-file-format.md. Existing files are truncated. The root query's stored error is retained in the dump rather than rethrown, except for failures that abort execution itself.

Template Parameters
QuerySpecRegistered root query specification.
Parameters
output_pathDestination file path.
inputRoot query input.
Returns
output_path after a successful write.
Exceptions
std::runtime_errorIf the file cannot be opened or written.

Definition at line 1359 of file querygraph.hpp.

References marshall().

◆ for_each_marshaled_type_descriptor()

template<typename Visitor>
void rpnx::querygraph::debug_abi::graph::for_each_marshaled_type_descriptor ( Visitor visitor)
inline

Visit the serialization and text descriptors of registered types.

The visitor is invoked as (typesig, deserialize, to_string) for every registered binary type. to_string may be empty if no text conversion was installed.

Template Parameters
VisitorCallable accepting the descriptor triplet.
Parameters
visitorCallable invoked synchronously for each type.

Definition at line 2272 of file querygraph.hpp.

◆ make_request()

template<query_spec_c QuerySpec>
auto rpnx::querygraph::debug_abi::graph::make_request ( typename QuerySpec::input_type input) -> typename QuerySpec::output_type
inline

Execute or reuse a top-level query and return its value.

If the (QuerySpec, input) node is new, this call submits it to the shared scheduler and waits until this graph becomes quiescent. If another thread already started it, this call waits for the shared node's terminal result. Stored exceptions are rethrown.

Handler and canonical-error registration and bind_handlers() must be complete before concurrent calls are made on the same graph.

Template Parameters
QuerySpecRegistered query specification to evaluate.
Parameters
inputInput value used as the memoization key.
Returns
The cached or newly computed query output.
Exceptions
std::logic_errorIf no matching handler is registered.
recursive_dependency_errorIf execution quiesces while the requested node is unresolved.

Definition at line 1251 of file querygraph.hpp.

◆ make_subquery_request()

template<subquery_spec_c SubquerySpec>
auto rpnx::querygraph::debug_abi::graph::make_subquery_request ( typename SubquerySpec::parent_query::input_type parent_input,
typename SubquerySpec::input_type input ) -> typename SubquerySpec::output_type
inline

Execute or reuse a subquery request from an external thread.

The parent query is evaluated as needed. The call then waits until the parent publishes the requested subquery or reaches a terminal state that determines the subquery error.

Template Parameters
SubquerySpecSubquery specification to request.
Parameters
parent_inputInput identifying the memoized parent node.
inputInput identifying the subquery instance.
Returns
Produced subquery output.
Exceptions
subquery_does_not_existIf the parent completes without the value.
subquery_parent_failedIf the parent fails first.

Definition at line 1325 of file querygraph.hpp.

◆ marshall()

std::vector< std::byte > rpnx::querygraph::debug_abi::graph::marshall ( )

Serialize a snapshot of every memoized node.

Returns
RPNXSerialization byte stream containing graph_data.

References marshall().

Referenced by dump_query_to_file(), and marshall().

◆ node_debug_io_capture_enabled()

bool rpnx::querygraph::debug_abi::graph::node_debug_io_capture_enabled ( ) const
noexcept

Return whether human-readable node input/output capture is enabled.

Returns
Current capture setting. The current public constructor leaves this diagnostic feature disabled.

◆ register_binary_descriptors()

template<typename T>
void rpnx::querygraph::debug_abi::graph::register_binary_descriptors ( )
inline

Register serialization operations and a type signature.

Handler registration invokes this automatically for query inputs, outputs, and subquery value types. Direct calls are useful only for tooling that needs additional types in for_each_marshaled_type_descriptor().

Template Parameters
TDefault-constructible value supported by binary_traits<T> and RPNXSerialization deserialization.

Definition at line 2060 of file querygraph.hpp.

References rpnx::querygraph::error_result::canonical_dump(), rpnx::querygraph::result< T >::get_error_result(), rpnx::querygraph::result< T >::has_exception(), rpnx::querygraph::result< T >::has_value(), rpnx::querygraph::error_result::message(), rpnx::querygraph::result< T >::result_status(), rpnx::querygraph::binary_traits< T >::serialize_to_binary(), and rpnx::querygraph::result< T >::value().

Referenced by register_handler_function().

◆ register_canonical_error()

template<typename Error>
void rpnx::querygraph::debug_abi::graph::register_canonical_error ( )
inline

Register an exception type for canonical capture and dumping.

When a handler throws an exception whose dynamic type exactly matches Error, QueryGraph copies it into canonical storage. The stored error can be rethrown to requesters and serialized into a graph dump. Register error types before executing requests.

Template Parameters
ErrorCopy-constructible std::exception subtype supported by binary_traits<Error>.

Definition at line 2013 of file querygraph.hpp.

References rpnx::querygraph::error_result::canonical().

◆ register_handler_function()

template<query_handler_spec_c HandlerSpec, typename Handler>
void rpnx::querygraph::debug_abi::graph::register_handler_function ( Handler h)
inline

Register the coroutine function implementing a query.

Registration creates the memoization cache, runtime query descriptor, debug and binary type descriptors, and a deferred bind operation for all declared dependencies. Only one handler may be registered for a query type in a graph.

Template Parameters
HandlerSpecSpecification declaring the implemented query, dependencies, and optionally produced subqueries.
HandlerCallable accepted as coroutine<HandlerSpec>(query_handler_input_t<HandlerSpec> const&). The input refers to the memoized key and remains valid until graph destruction.
Parameters
hHandler callable to retain for new nodes.
Exceptions
std::logic_errorIf the query already has a handler.

Definition at line 2189 of file querygraph.hpp.

References graph(), register_binary_descriptors(), and register_inputoutput_text_descriptor().

Referenced by register_handler_map(), and register_handler_singleton().

◆ register_handler_map()

template<query_handler_spec_c QuerySpec>
void rpnx::querygraph::debug_abi::graph::register_handler_map ( std::map< query_handler_input_t< QuerySpec >, query_handler_output_t< QuerySpec > > handler_map)
inline

Register a finite map as a query handler.

Each map key becomes a memoized query input and its mapped value is returned by the generated coroutine handler.

Template Parameters
QuerySpecHandler specification, despite the historical template parameter name.
Parameters
handler_mapComplete input/output map captured by the handler.
Exceptions
std::logic_errorWhen a requested input is absent.

Definition at line 2124 of file querygraph.hpp.

References register_handler_function().

◆ register_handler_singleton() [1/2]

template<query_handler_spec_c HandlerSpec>
requires std::same_as< query_handler_input_t< HandlerSpec >, std::monostate >
void rpnx::querygraph::debug_abi::graph::register_handler_singleton ( query_handler_output_t< HandlerSpec > value)
inline

Register a constant result for a handler with monostate input.

Template Parameters
HandlerSpecHandler specification whose input is std::monostate.
Parameters
valueValue returned for the singleton query node.

Definition at line 2146 of file querygraph.hpp.

References register_handler_function().

Referenced by register_handler_singleton().

◆ register_handler_singleton() [2/2]

template<query_spec_c QuerySpec>
requires std::same_as< typename QuerySpec::input_type, std::monostate >
void rpnx::querygraph::debug_abi::graph::register_handler_singleton ( typename QuerySpec::output_type value)
inline

Register a constant result directly from a query spec.

This overload synthesizes a dependency-free handler specification.

Template Parameters
QuerySpecQuery specification whose input is std::monostate.
Parameters
valueValue returned for the singleton query node.

Definition at line 2167 of file querygraph.hpp.

References register_handler_singleton().

◆ register_inputoutput_text_descriptor()

template<typename T>
void rpnx::querygraph::debug_abi::graph::register_inputoutput_text_descriptor ( )
inline

Register the diagnostic text conversion for a value type.

Registration is idempotent. The converter delegates to debug_traits<T> and is used when node I/O text capture is enabled and while exposing marshaled type descriptors.

Template Parameters
TQuery input or output type to register.

Definition at line 2036 of file querygraph.hpp.

References rpnx::querygraph::debug_traits< T >::to_debug_string().

Referenced by register_handler_function().


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