|
RPNX::QueryGraph
Typed, memoized, concurrent query evaluation for C++23
|
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. | |
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.
| rpnx::querygraph::debug_abi::graph::graph | ( | scheduler & | execution_scheduler, |
| options | configuration ) |
Construct a graph with timing options and built-in subquery errors.
| execution_scheduler | Shared worker pool; must outlive this graph. |
| configuration | Timing configuration copied into the graph. |
| std::invalid_argument | If a timing threshold is negative. Zero timing thresholds report any positive self-time. |
|
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.
| QuerySpec | Registered query specification to evaluate. |
| input | Input value copied into the memoization cache when new. |
| std::logic_error | If 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().
| 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.
| graph_data rpnx::querygraph::debug_abi::graph::dump | ( | ) |
|
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.
| QuerySpec | Registered root query specification. |
| output_path | Destination file path. |
| input | Root query input. |
output_path after a successful write. | std::runtime_error | If the file cannot be opened or written. |
Definition at line 1359 of file querygraph.hpp.
References marshall().
|
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.
| Visitor | Callable accepting the descriptor triplet. |
| visitor | Callable invoked synchronously for each type. |
Definition at line 2272 of file querygraph.hpp.
|
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.
| QuerySpec | Registered query specification to evaluate. |
| input | Input value used as the memoization key. |
| std::logic_error | If no matching handler is registered. |
| recursive_dependency_error | If execution quiesces while the requested node is unresolved. |
Definition at line 1251 of file querygraph.hpp.
|
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.
| SubquerySpec | Subquery specification to request. |
| parent_input | Input identifying the memoized parent node. |
| input | Input identifying the subquery instance. |
| subquery_does_not_exist | If the parent completes without the value. |
| subquery_parent_failed | If the parent fails first. |
Definition at line 1325 of file querygraph.hpp.
| std::vector< std::byte > rpnx::querygraph::debug_abi::graph::marshall | ( | ) |
Serialize a snapshot of every memoized node.
graph_data. References marshall().
Referenced by dump_query_to_file(), and marshall().
|
noexcept |
Return whether human-readable node input/output capture is enabled.
|
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().
| T | Default-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().
|
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.
| Error | Copy-constructible std::exception subtype supported by binary_traits<Error>. |
Definition at line 2013 of file querygraph.hpp.
References rpnx::querygraph::error_result::canonical().
|
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.
| HandlerSpec | Specification declaring the implemented query, dependencies, and optionally produced subqueries. |
| Handler | Callable accepted as coroutine<HandlerSpec>(query_handler_input_t<HandlerSpec> const&). The input refers to the memoized key and remains valid until graph destruction. |
| h | Handler callable to retain for new nodes. |
| std::logic_error | If 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().
|
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.
| QuerySpec | Handler specification, despite the historical template parameter name. |
| handler_map | Complete input/output map captured by the handler. |
| std::logic_error | When a requested input is absent. |
Definition at line 2124 of file querygraph.hpp.
References register_handler_function().
|
inline |
Register a constant result for a handler with monostate input.
| HandlerSpec | Handler specification whose input is std::monostate. |
| value | Value returned for the singleton query node. |
Definition at line 2146 of file querygraph.hpp.
References register_handler_function().
Referenced by register_handler_singleton().
|
inline |
Register a constant result directly from a query spec.
This overload synthesizes a dependency-free handler specification.
| QuerySpec | Query specification whose input is std::monostate. |
| value | Value returned for the singleton query node. |
Definition at line 2167 of file querygraph.hpp.
References register_handler_singleton().
|
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.
| T | Query 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().