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 |
| interference · recovery · spectrum | The three profilers beside contention: dose-response interference (bench.interference), step-release recovery/hysteresis transients (bench.recovery) and contention frequency response (bench.spectrum) | — |
| plant · gov · actuate · replay | The four profilers fitted into one queryable machine-plant model (plant.identify · plant.predict · plant.marginal · plant.verify), consumed as a control surface by the contention governor (gov.*) with a real actuator leg and counterfactual scheduling replay (gov.replay) | — |
netinfo · conn · net_flows (feature flows) · lsof | Subprocess-free network configuration (net.info · net.interfaces), per-connection TCP rates (net.conn_rate), the iftop-parity live flow monitor (net.flows), and per-process open files and sockets (lsof.snapshot · proc.files) | — |
| macos_power · macos_smc · snapshots | macOS-only sensor and storage surfaces with no root and no subprocess: package/CPU/GPU/ANE power over the private IOReport framework (sys.power), AppleSMC fan RPM (sys.fans), and APFS local Time Machine snapshots (snapshots.list · snapshots.exclude · snapshots.purge) | — |
| rev · cli | Reversibility classes for every command the GUI Automation Bus can run, and the headless argv-in / JSON-on-stdout command-line surface | — |
| 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
79 dotted commands across the two dispatchers — Engine::invoke (stateful) and the free harvest fn (stateless) — enumerated in commands::COMMANDS and held in lockstep with both by the commands_cover_invoke_and_harvest_arms drift guard (the table below is illustrative, not exhaustive) 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 flows feature adds the live per-connection flow monitor (imported iftoprs + libpcap), and tauri 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.