vox-build-queue API Reference (generated)
Crate: vox-build-queue · Version: 0.6.0 · Target: Library (lib.rs)
Fair FIFO build queue, cargo resolution, and build metrics for the vox build broker
Crate Overview
Section titled “Crate Overview”Pure logic for the vox build broker: cargo resolution, fair queueing, metrics.
See docs/superpowers/specs/2026-06-18-unified-build-broker-design.md.
Public API Surface
Section titled “Public API Surface”Modules
Section titled “Modules”| Module | Description |
|---|---|
env_filter | — |
global | — |
metrics | — |
queue | — |
resolve | — |
Deep Public Symbols (Source-Anchored)
Section titled “Deep Public Symbols (Source-Anchored)”| Kind | Symbol | Signature | Source | Description |
|---|---|---|---|---|
fn | env_filter::passthrough_env | pub fn passthrough_env( | crates/vox-build-queue/src/env_filter.rs#L65 | The caller’s env minus the volatile denylist, sorted for determinism. |
fn | env_filter::env_hash | pub fn env_hash(env: &BTreeMap<String, String>) -> u64 | crates/vox-build-queue/src/env_filter.rs#L85-L89 | Stable hash of build-fingerprint vars ONLY (the coalescing identity). Accepts the full passthrough env but hashes only FINGERPRINT_ALLOW keys, so volatile per-agent vars never perturb the coalescing key. See the FINGERPRINT_ALLOW doc for why an allowlist (not the denylist) defines build identity. |
fn | env_filter::argv_hash | pub fn argv_hash(argv: &[String]) -> u64 | crates/vox-build-queue/src/env_filter.rs#L92-L94 | Stable hash of argv. |
fn | global::global_root | pub fn global_root() -> PathBuf | crates/vox-build-queue/src/global.rs#L20-L29 | Root dir for global broker state. Outside any repo → survives git clean/checkout. Overridable with VOX_BROKER_HOME (used by tests). |
fn | global::max_concurrent | pub fn max_concurrent() -> usize | crates/vox-build-queue/src/global.rs#L33-L39 | Max concurrent cargo builds machine-wide. VOX_BROKER_MAX_CONCURRENT overrides; otherwise the machine’s available parallelism (floored at 1). |
fn | global::max_concurrent_from | pub fn max_concurrent_from(raw: Option<&str>, parallelism: usize) -> usize | crates/vox-build-queue/src/global.rs#L44-L52 | Pure core of [max_concurrent], split out so it’s testable without mutating the process environment (which would require unsafe under edition 2024). When unset, falls back to parallelism.max(1). |
fn | global::reserved_slots | pub fn reserved_slots() -> usize | crates/vox-build-queue/src/global.rs#L58-L61 | Slots reserved for a build domain the filesystem semaphore cannot see (a containerised CI runner sharing this host’s CPU but not its mount namespace). VOX_BROKER_RESERVED_SLOTS overrides; unset, unparseable, or negative is treated as 0 reserved slots. |
fn | global::reserved_slots_from | pub fn reserved_slots_from(raw: Option<&str>) -> usize | crates/vox-build-queue/src/global.rs#L65-L67 | Pure core of [reserved_slots], split out for the same reason as [max_concurrent_from]. |
fn | global::effective_max_concurrent | pub fn effective_max_concurrent() -> usize | crates/vox-build-queue/src/global.rs#L72-L79 | The effective machine-wide concurrency cap: [max_concurrent] reduced by [reserved_slots], floored at 1 (never 0 — acquire_slot loops until a slot frees, and a cap of 0 slots never frees one). |
fn | global::effective_max_concurrent_from | pub fn effective_max_concurrent_from( | crates/vox-build-queue/src/global.rs#L85 | Pure core of [effective_max_concurrent]. The reservation is applied after VOX_BROKER_MAX_CONCURRENT — an explicit override is still subject to it, because the reserved slots are physically in use by a kernel this semaphore can’t see regardless of what the override says. |
fn | global::should_admit | pub fn should_admit(load_1m: Option<f64>, parallelism: usize, held: usize, cap: usize) -> bool | crates/vox-build-queue/src/global.rs#L98-L109 | Whether a build may start now. The first build always runs. Another runs only while the 1-minute load average is below the machine’s parallelism (idle cores exist), and never past cap slots. Without a load reading (non-unix), builds run one at a time. |
struct | global::Slot | pub struct Slot | crates/vox-build-queue/src/global.rs#L112-L114 | A held global slot; dropping it (closing the file handle) frees the slot. |
fn | global::try_acquire_slot | pub fn try_acquire_slot(root: &Path, n: usize) -> Result<Option<(Slot, usize)>> | crates/vox-build-queue/src/global.rs#L119-L136 | Try to grab one free slot without blocking. Returns (slot, busy_count) where busy_count is how many of the N slots were already taken, or None if all N are busy. |
fn | global::acquire_slot | pub fn acquire_slot(root: &Path, n: usize) -> Result<(Slot, u64, usize)> | crates/vox-build-queue/src/global.rs#L140-L149 | Acquire one of N slots, polling until one frees. Returns the held slot, the time spent waiting (ms), and how many slots were busy when we got in. |
fn | global::probe_busy_slots | pub fn probe_busy_slots(root: &Path, n: usize) -> Result<usize> | crates/vox-build-queue/src/global.rs#L161-L184 | Count how many of the N slots are currently held, WITHOUT disturbing them: each slot is probed with a non-blocking lock attempt and immediately released if acquired (never held past the probe). Unlike [try_acquire_slot] this never returns a slot to the caller, so calling it (e.g. from a read-only status viewer) can’t itself perturb the count it’s trying to measure. This is inherently a sample, not a snapshot: another process may take or release a slot between this probing two different slot files, so the count can be stale the instant it’s returned. |
fn | global::load_average_1m | pub fn load_average_1m() -> Option<f64> | crates/vox-build-queue/src/global.rs#L188-L200 | 1-minute load average, or None where the OS does not report one. |
fn | global::acquire_slot_adaptive | pub fn acquire_slot_adaptive(root: &Path, cap: usize) -> Result<(Slot, u64, usize)> | crates/vox-build-queue/src/global.rs#L203-L219 | Like [acquire_slot], but a free slot is taken only when [should_admit] agrees. |
struct | global::Inflight | pub struct Inflight | crates/vox-build-queue/src/global.rs#L223-L226 | Marker for an in-flight build identity; holds an exclusive lock on its entry for the build’s lifetime. Dropping it unlocks and removes the marker. |
fn | global::register_inflight | pub fn register_inflight(root: &Path, key: &str) -> Result<(Inflight, bool)> | crates/vox-build-queue/src/global.rs#L242-L302 | Register this build’s identity (key) and report whether another in-flight build already shares it (a true coalescing opportunity, cross-worktree). Holds an exclusive lock on its entry for the build’s lifetime, and removes any stale entry whose lock can be acquired (its owner is gone). |
struct | metrics::MetricRecord | pub struct MetricRecord | crates/vox-build-queue/src/metrics.rs#L12-L21 | — |
fn | metrics::now_ms | pub fn now_ms() -> u128 | crates/vox-build-queue/src/metrics.rs#L24-L29 | Wall-clock milliseconds since the Unix epoch (0 if the clock is before it). |
fn | metrics::append | pub fn append(path: &Path, rec: &MetricRecord) -> anyhow::Result<()> | crates/vox-build-queue/src/metrics.rs#L32-L42 | Append one JSON line to the metrics file (created with parents if absent). |
struct | metrics::Summary | pub struct Summary | crates/vox-build-queue/src/metrics.rs#L45-L50 | — |
fn | metrics::daemon_recommended | pub fn daemon_recommended(&self) -> bool | crates/vox-build-queue/src/metrics.rs#L56-L58 | Go/no-go for the deferred coalescing daemon (Layer 1b): worth building only if a material share of invocations had a coalescing opportunity AND queue waits actually occurred. |
fn | metrics::render | pub fn render(&self) -> String | crates/vox-build-queue/src/metrics.rs#L61-L75 | One-line human summary for vox build-broker stats. |
fn | metrics::summarize | pub fn summarize(path: &Path) -> anyhow::Result<Summary> | crates/vox-build-queue/src/metrics.rs#L80-L83 | Read a metrics.jsonl file and summarize. Malformed lines are skipped so a partially-written tail never breaks stats. |
fn | metrics::summarize_str | pub fn summarize_str(text: &str) -> anyhow::Result<Summary> | crates/vox-build-queue/src/metrics.rs#L86-L110 | Summarize already-loaded JSONL content (used when aggregating across dirs). |
fn | queue::hash_path | pub fn hash_path(p: &Path) -> String | crates/vox-build-queue/src/queue.rs#L28-L32 | Stable 16-hex-digit hash of a path, used as the per-worktree queue subdir. Shared by the shim and build_service so both address the same queue (DRY). |
struct | queue::FairQueue | pub struct FairQueue | crates/vox-build-queue/src/queue.rs#L35-L37 | A fair FIFO queue scoped to one worktree. |
struct | queue::Ticket | pub struct Ticket | crates/vox-build-queue/src/queue.rs#L40-L44 | Held while a build runs; dropping releases the run lock and ticket marker. |
fn | queue::new | pub fn new(queue_root: &Path, worktree_hash: &str) -> Result<Self> | crates/vox-build-queue/src/queue.rs#L47-L51 | — |
fn | queue::take_ticket | pub fn take_ticket(&self, key: &str) -> Result<u64> | crates/vox-build-queue/src/queue.rs#L57-L84 | Claim the next monotonic ticket number (arrival order) and record an outstanding marker (t<seq> containing <ts_ms>\n<key>) so position can count waiters ahead and coalesce_opportunity can match command identity. key is the combined argv+env fingerprint of this invocation. |
fn | queue::position | pub fn position(&self, seq: u64) -> usize | crates/vox-build-queue/src/queue.rs#L119-L121 | How many live tickets are ahead of seq (lower-numbered). |
fn | queue::coalesce_opportunity | pub fn coalesce_opportunity(&self, seq: u64, key: &str) -> bool | crates/vox-build-queue/src/queue.rs#L125-L129 | Whether another live invocation shares this command identity (key), i.e. a true coalescing opportunity (not merely queue contention). |
fn | queue::acquire | pub fn acquire(&self, seq: u64) -> Result<Ticket> | crates/vox-build-queue/src/queue.rs#L133-L146 | Block until this caller holds the exclusive run lock, then return a Ticket whose drop releases the lock and removes the ticket marker. |
fn | resolve::is_build_subcommand | pub fn is_build_subcommand(sub: &str) -> bool | crates/vox-build-queue/src/resolve.rs#L10-L12 | Subcommands whose runs take the cargo target lock and are worth queueing. |
fn | resolve::worktree_root_of | pub fn worktree_root_of(start: &Path) -> Option<PathBuf> | crates/vox-build-queue/src/resolve.rs#L24-L29 | Walk up from start to the first directory that is a vox worktree root, identified by having BOTH .cargo/config.toml and Cargo.toml. Requiring Cargo.toml is essential: the global ~/.cargo/config.toml exists for every user, so matching on .cargo/config.toml alone would treat the entire home directory as a worktree. A real cargo workspace root always has a Cargo.toml next to its .cargo/config.toml. Returns None if no such ancestor exists, in which case the caller bypasses the queue and runs cargo directly. |
fn | resolve::cargo_home_proxy | pub fn cargo_home_proxy() -> Option<PathBuf> | crates/vox-build-queue/src/resolve.rs#L34-L42 | The rustup cargo proxy under $CARGO_HOME/~/.cargo/bin, if present. This is never a shim copy and honours rust-toolchain.toml / +toolchain, so the shim prefers it over a PATH scan. Mirrors the repo’s own cargo_bin(). |
fn | resolve::resolve_real_cargo | pub fn resolve_real_cargo(path_var: &str, own_exe: &Path) -> Option<PathBuf> | crates/vox-build-queue/src/resolve.rs#L52-L74 | Resolve the real cargo by scanning path_var for the first cargo that is neither the shim itself nor a sibling copy living in the shim’s own directory (e.g. target/debug/cargo.exe, target/debug/deps/cargo.exe produced during cargo test). Skipping same-directory siblings is essential: matching only the exact own_exe path let a sibling shim copy be picked as “real cargo”, causing infinite recursion (a fork bomb). Returns None if our own identity cannot be established (we must not guess). |
fn | resolve::build_args_for_run | pub fn build_args_for_run(args: &[String]) -> Option<Vec<String>> | crates/vox-build-queue/src/resolve.rs#L76-L83 | — |