zthrottle-core is early-stage and in active development. The figures on this page are derived from the crate source as it stands today (Cargo.toml, src/lib.rs, src/ffi.rs): version, crate-types, the dotted commands matched in Engine::invoke, and the exported C symbols. The "planned" column lists work that is not yet implemented — it is a roadmap, not a claim of coverage.
Module map
| module | role today | planned |
|---|---|---|
| lib (Engine) | one dotted command surface via Engine::invoke; throttled progress event sink; run-history record | richer event payloads, config profiles |
| model | Axis, BenchConfig, ContentionPlan and the per-axis result types | user-tunable per-axis workload matrices |
| disk | sequential + random throughput and IOPS; direct I/O (F_NOCACHE / O_DIRECT) to measure the device, not the page cache | queue-depth sweeps, mixed read/write profiles |
| net | loopback + peer TCP/UDP throughput and RTT; real-internet download/upload via the Cloudflare speed endpoint | multi-stream saturation, jitter histograms |
| cpu | multi-threaded integer + float compute, single- vs all-core scaling | per-ISA micro-kernels, thermal-throttle detection |
| mem | bandwidth (copy / add / triad) and latency | NUMA-aware placement, working-set sweeps |
| contention | drives every axis at once and returns the degradation matrix + bottleneck-migration timeline — the world-first surface | user-defined mixes, longer soak profiles |
| drives | volume enumeration for the "Select Target Drive" disk-bench override | per-volume capability probe |
sys (feature monitor) | live monitor via sysinfo — processes/CPU/memory/disks/per-interface network, sensors, named-signal delivery, directory-usage scans | process tree, per-process I/O columns |
treedb (feature treedb) | persistent SQLite directory-tree index — instant load on launch, mtime-diff incremental refresh, targeted prune | FSEvents/inotify-driven refresh |
| stats · store | summary statistics; data-dir + run-history JSON load/save | historical trend export |
| ffi | C ABI: zth_invoke · zth_free | streaming event callback export |
tauri_plugin (feature tauri) | Tauri v2 plugin glue + the mountable served frontend | per-window capability scoping |
Command surface
23 dotted commands through Engine::invoke: version · capabilities; the benchmarks bench.disk / bench.net / bench.cpu / bench.mem / bench.all / bench.contention; drives.list / drives.set_target; run history history.list / history.get / history.clear; the monitor sys.overview / sys.processes / sys.disks / sys.net / sys.sensors and proc.kill / proc.detail; and storage storage.scan / storage.biggest / storage.delete. The storage and monitor commands are stateless data-harvest and run lock-free off the engine mutex so a minutes-long scan never blocks a benchmark or a poll.
Build surfaces
The crate declares crate-type = ["rlib", "staticlib", "cdylib"]. The rlib links natively into Rust/Tauri hosts; the staticlib/cdylib expose the C ABI for non-Rust hosts. Default features are net (internet speed test, rustls), directio (page-cache-bypassing disk I/O via libc), monitor (sysinfo live data) and treedb (bundled SQLite tree index); --no-default-features yields a pure disk/CPU/mem/contention core that compiles in headless CI. The optional tauri feature adds the Tauri v2 plugin layer. Every dependency is foundational and vendorable (serde, rusqlite/bundled, ureq/rustls, libc, sysinfo).
Verification
The crate carries in-source and integration tests that run without network access and pass identically in headless Linux CI: the engine command surface and contention profiler (matrix + timeline shape), the SQLite tree round-trip (index → instant load → mtime-diff refresh → delete-prune, with ancestor-size decrement), and real signal delivery (a self-spawned child receives SIGTERM by name and exits). Destructive paths are floored — storage.delete refuses the filesystem root and top-level system dirs, and directory scans stop at filesystem boundaries (du -x) so a network share is never walked blind.