pub struct Engine { /* private fields */ }Implementations§
Source§impl Engine
impl Engine
pub fn new(data_dir: &Path) -> Result<Self>
Sourcepub fn execute_powql(&mut self, input: &str) -> Result<QueryResult, String>
pub fn execute_powql(&mut self, input: &str) -> Result<QueryResult, String>
Parse + plan + execute a PowQL query.
Mission D6 — tracing collapse: the previous implementation ran 4
Instant::now() + 3 elapsed().as_micros() calls + formatted an
info! span on every query, even when tracing was disabled. On a
sub-microsecond point_lookup_indexed call that overhead was
100-200ns — 20%+ of the whole query. We now measure time only when
INFO is actually enabled via tracing::enabled!, and we moved the
noisy debug!(?plan) line behind the same gate so the Debug
formatter can’t run unconditionally either.
Mission D9 — plan cache: on the hot path we canonicalise the query text (lex + FNV-1a hash with literal values stripped), check the cache, and on a hit substitute the new literals into a clone of the cached plan. This skips re-lexing, re-parsing, and re-planning — around 3μs per call on bench workloads. On a miss we plan as before and insert the plan under its canonical hash.
Sourcepub fn plan_cache_stats(&self) -> (u64, u64, usize)
pub fn plan_cache_stats(&self) -> (u64, u64, usize)
Plan cache stats — useful for benches and debugging.
Sourcepub fn execute_powql_readonly(&self, input: &str) -> Result<QueryResult, String>
pub fn execute_powql_readonly(&self, input: &str) -> Result<QueryResult, String>
Mission infra-1: read-only entry point.
Parses + plans + executes a PowQL query using only a shared borrow
on the engine. Rejects any statement that would mutate state
(Insert/Update/Delete/CreateTable/AlterTable/DropTable/CreateView/
RefreshView/DropView) by returning READONLY_NEEDS_WRITE so the
caller can escalate to the write lock.
Also returns READONLY_NEEDS_WRITE if a materialized view in the
query is dirty — refreshing one requires &mut self, so the caller
must retake the write lock for the first refresh.
This method is the concurrent-read fast path behind
Arc<RwLock<Engine>>: multiple threads can call it simultaneously
under a shared .read() lock and each will scan independently.
Sourcepub fn prepare(&mut self, query: &str) -> Result<PreparedQuery, String>
pub fn prepare(&mut self, query: &str) -> Result<PreparedQuery, String>
Parse and plan a query once, returning a PreparedQuery handle
the caller can execute repeatedly with fresh literal values.
Mission C Phase 5: the plan cache already short-circuits repeat
queries that share a shape, but every call still pays for
canonicalize (lex + FNV hash) and a hashmap lookup. For a tight
insert loop that’s ~500-800ns of pure overhead per call on top of
the caller’s format!() cost. Prepared statements skip the lex,
skip the hash, skip the format, and skip the cache lookup — the
caller holds the plan template directly and hands us the new
literals as a slice.
The plan template holds whatever literal values the original query
string contained; those are overwritten on every execute_prepared
call, same way the plan cache does on a cache hit.
The returned param_count matches the total number of
Expr::Literal slots reachable from the plan, in the deterministic
walk order used by canonicalize and the cache. Callers must pass
exactly that many literals to execute_prepared, in the same order
they appear in the source text.
Sourcepub fn execute_prepared(
&mut self,
prep: &PreparedQuery,
literals: &[Literal],
) -> Result<QueryResult, String>
pub fn execute_prepared( &mut self, prep: &PreparedQuery, literals: &[Literal], ) -> Result<QueryResult, String>
Execute a PreparedQuery with the given literal values.
The literals are substituted into a clone of the template plan in
the same deterministic walk order that crate::canonicalize
produces (filter predicate first, then projection, then assignment
RHS, and so on). Substitution errors here mean the caller passed
the wrong number of literals for this query shape.
Sourcepub fn execute_prepared_take(
&mut self,
prep: &PreparedQuery,
literals: &mut [Literal],
) -> Result<QueryResult, String>
pub fn execute_prepared_take( &mut self, prep: &PreparedQuery, literals: &mut [Literal], ) -> Result<QueryResult, String>
Mission C Phase 13: moving variant of Engine::execute_prepared
for the insert fast path. Takes literals by mutable reference
so that each Literal::String can be consumed via mem::take
instead of cloned into a Value::Str. On insert_batch_1k that
removes three per-row heap allocations (name, status, email),
bringing the workload over the line vs SQLite’s amortized
prepare+execute loop.
The caller’s Literal::String entries are replaced with empty
strings on successful inserts — the literals slice is not
left in a valid-for-reuse state except for Int/Float/Bool
values. Non-insert templates fall through to the standard
substitute-and-execute path.