Skip to content

v1.0.0 — Stable API

Latest
Latest

Choose a tag to compare

View all tags
@jamesgober jamesgober released this 11 Jul 20:24
v1.0.0
35bedd6

query-lang v1.0.0 — API Freeze

The surface is now stable. v1.0.0 freezes the public API introduced in 0.2.0 under Semantic Versioning. There are no code changes from 0.2.0 — this release marks the contract as fixed and completes the roadmap.

What is query-lang?

An incremental computation engine — the model behind Rust's own salsa and rust-analyzer, distilled to a small, dependency-free core. You describe a set of queries once; the engine stores the base facts (inputs), caches the computed results (derived queries), records what each result was read from, and recomputes only what a change actually affects. The whole public surface is one trait and four types — System, Database, Revision, Stats, and QueryError. It is #![forbid(unsafe_code)], no_std-compatible, wires no first-party dependency, and never panics on a query cycle.

The stability promise

As of 1.0.0 the public API is frozen. Within the 1.x series:

  • System (its associated types and compute), Database (new / set / get / revision / stats / system), Revision, Stats, and QueryError will not change in a breaking way. A breaking change means a new major version.
  • The resolution semantics are part of the contract, not an implementation detail: a set with an unchanged value does not advance the revision or invalidate dependents; a derived query recomputes only on a real miss or a changed dependency; and early cutoff holds — when a recomputed value equals its predecessor, dependents are validated rather than recomputed. Code may rely on these, and on Stats reflecting them.
  • QueryError is #[non_exhaustive], so a newly distinguished failure is an additive minor change. Match it with a wildcard arm.
  • The serde representations are fixed within 1.x: a Revision serializes as its underlying integer, and Stats as an object with computed / validated / hits fields.
  • MSRV (Rust 1.85) is a compatibility surface: raising it is a documented minor change, never a patch.

Not promised: the concrete Revision numbering (only its order and monotonicity are contractual), the internal cache representation, and the exact Debug output of a Database.

Full details in docs/API.md.

Since 0.2.0

Nothing functional. 0.2.0 delivered the engine; 1.0.0 promises not to break it. If you are already on query-lang = "0.2", moving to "1" is a no-op recompile.

Performance

Unchanged from 0.2.0. Latest local Criterion means, Windows x86_64 and Linux (WSL2 Ubuntu), Rust stable, release build:

Benchmark What it measures Time
chain/cache_hit Re-resolving an already-current query (a hit). 19–38 ns
chain/cold_build/256 First resolution of a 256-deep query chain. ~55 µs
chain/edit_rebuild/256 Editing the leaf input, rebuilding a 256-deep chain. ~46 µs
wide/edit_one_of/256 Editing one input of a 256-wide sum (one branch recomputes, 255 validate). ~42 µs

The engine's own per-query overhead is a BTreeMap lookup and a revision compare — the figures are dominated by that bookkeeping, since the benchmarked queries do trivial work. Numbers vary by CPU; run cargo bench --bench bench on your target for a baseline.

Verification

Run on Windows x86_64 with testing on Linux (WSL2 Ubuntu), Rust stable and the 1.85 MSRV; the same commands run in the CI matrix across Linux, macOS, and Windows:

cargo fmt --all -- --check
cargo clippy --all-targets -- -D warnings
cargo clippy --all-targets --all-features -- -D warnings
cargo clippy --no-default-features --all-targets -- -D warnings
cargo test
cargo test --all-features
cargo build --no-default-features
cargo build --examples
cargo +1.85 build --all-features
RUSTDOCFLAGS="-D warnings" cargo doc --no-deps --all-features
cargo deny check
cargo audit

All green. Counts at this tag:

  • Default features: 28 unit + 6 integration + 4 property + 31 doctests. The doctests include every rust example in README.md and docs/API.md, wired into cargo test so the published examples cannot drift from the API.
  • --all-features: adds 3 serde serialization tests exercising the Revision and Stats derivations.

Installation

[dependencies]
query-lang = "1"

# With serde:
query-lang = { version = "1", features = ["serde"] }

# no_std:
query-lang = { version = "1", default-features = false }

MSRV: Rust 1.85.

Documentation

Full diff: v0.2.0...v1.0.0.
Changelog: CHANGELOG.md.

Assets 2
Loading