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

#include <querygraph.hpp>

Public Member Functions
	graph (std::chrono::nanoseconds long_running_node_threshold=std::chrono::milliseconds(100))
	Construct an empty graph with built-in subquery errors registered.

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<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.

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 1038 of file querygraph.hpp.

Constructor & Destructor Documentation

◆ graph()

rpnx::querygraph::debug_abi::graph::graph ( std::chrono::nanoseconds long_running_node_threshold = std::chrono::milliseconds(100) )

explicit

Construct an empty graph with built-in subquery errors registered.

Parameters

long_running_node_threshold Minimum cumulative node self-time that prints a completion diagnostic. Progress diagnostics additionally require at least one second of self-time. A non-positive duration disables the diagnostics.

Referenced by register_handler_function().

Member Function Documentation

◆ 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

QuerySpec Registered root query specification.

Parameters

output_path	Destination file path.
input	Root query input.

Returns: output_path after a successful write.

Exceptions

std::runtime_error If the file cannot be opened or written.

Definition at line 1230 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

Visitor Callable accepting the descriptor triplet.

Parameters

visitor Callable invoked synchronously for each type.

Definition at line 2105 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 runs a worker group until the node completes or execution 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

QuerySpec Registered query specification to evaluate.

Parameters

input Input value used as the memoization key.

Returns: The cached or newly computed query output.

Exceptions

std::logic_error	If no matching handler is registered.
recursive_dependency_error	If execution quiesces while the requested node is unresolved.

Definition at line 1164 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

SubquerySpec Subquery specification to request.

Parameters

parent_input	Input identifying the memoized parent node.
input	Input identifying the subquery instance.

Returns: Produced subquery output.

Exceptions

subquery_does_not_exist	If the parent completes without the value.
subquery_parent_failed	If the parent fails first.

Definition at line 1196 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.

References rpnx::querygraph::result< T >::get_error_result(), rpnx::querygraph::result< T >::has_result(), rpnx::querygraph::result< T >::has_unexpected_exception(), and rpnx::querygraph::error_result::unexpected_exception().

◆ 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

T	Default-constructible value supported by `binary_traits<T>` and RPNXSerialization deserialization.

Definition at line 1895 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

Error Copy-constructible std::exception subtype supported by binary_traits<Error>.

Definition at line 1848 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

HandlerSpec	Specification declaring the implemented query, dependencies, and optionally produced subqueries.
Handler	Callable accepted as `coroutine<HandlerSpec>(query_handler_input_t<HandlerSpec>)`.

Parameters

h	Handler callable to retain for new nodes.

Exceptions

std::logic_error If the query already has a handler.

Definition at line 2023 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

QuerySpec Handler specification, despite the historical template parameter name.

Parameters

handler_map Complete input/output map captured by the handler.

Exceptions

std::logic_error When a requested input is absent.

Definition at line 1959 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

HandlerSpec Handler specification whose input is std::monostate.

Parameters

value Value returned for the singleton query node.

Definition at line 1981 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

QuerySpec Query specification whose input is std::monostate.

Parameters

value Value returned for the singleton query node.

Definition at line 2002 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

T	Query input or output type to register.

Definition at line 1871 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:

querygraph.hpp

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ graph()

Member Function Documentation

◆ bind_handlers()

◆ dump()

◆ dump_query_to_file()

◆ for_each_marshaled_type_descriptor()

◆ make_request()

◆ make_subquery_request()

◆ marshall()

◆ node_debug_io_capture_enabled()

◆ register_binary_descriptors()

◆ register_canonical_error()

◆ register_handler_function()

◆ register_handler_map()

◆ register_handler_singleton() [1/2]

◆ register_handler_singleton() [2/2]

◆ register_inputoutput_text_descriptor()