Skip to content

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

Pure logic for the vox build broker: cargo resolution, fair queueing, metrics.

See docs/superpowers/specs/2026-06-18-unified-build-broker-design.md.

ModuleDescription
env_filter—
global—
metrics—
queue—
resolve—
KindSymbolSignatureSourceDescription
fnenv_filter::passthrough_envpub fn passthrough_env(crates/vox-build-queue/src/env_filter.rs#L65The caller’s env minus the volatile denylist, sorted for determinism.
fnenv_filter::env_hashpub fn env_hash(env: &BTreeMap<String, String>) -> u64crates/vox-build-queue/src/env_filter.rs#L85-L89Stable 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.
fnenv_filter::argv_hashpub fn argv_hash(argv: &[String]) -> u64crates/vox-build-queue/src/env_filter.rs#L92-L94Stable hash of argv.
fnglobal::global_rootpub fn global_root() -> PathBufcrates/vox-build-queue/src/global.rs#L20-L29Root dir for global broker state. Outside any repo → survives git clean/checkout. Overridable with VOX_BROKER_HOME (used by tests).
fnglobal::max_concurrentpub fn max_concurrent() -> usizecrates/vox-build-queue/src/global.rs#L33-L39Max concurrent cargo builds machine-wide. VOX_BROKER_MAX_CONCURRENT overrides; otherwise the machine’s available parallelism (floored at 1).
fnglobal::max_concurrent_frompub fn max_concurrent_from(raw: Option<&str>, parallelism: usize) -> usizecrates/vox-build-queue/src/global.rs#L44-L52Pure 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).
fnglobal::reserved_slotspub fn reserved_slots() -> usizecrates/vox-build-queue/src/global.rs#L58-L61Slots 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.
fnglobal::reserved_slots_frompub fn reserved_slots_from(raw: Option<&str>) -> usizecrates/vox-build-queue/src/global.rs#L65-L67Pure core of [reserved_slots], split out for the same reason as [max_concurrent_from].
fnglobal::effective_max_concurrentpub fn effective_max_concurrent() -> usizecrates/vox-build-queue/src/global.rs#L72-L79The 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).
fnglobal::effective_max_concurrent_frompub fn effective_max_concurrent_from(crates/vox-build-queue/src/global.rs#L85Pure 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.
fnglobal::should_admitpub fn should_admit(load_1m: Option<f64>, parallelism: usize, held: usize, cap: usize) -> boolcrates/vox-build-queue/src/global.rs#L98-L109Whether 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.
structglobal::Slotpub struct Slotcrates/vox-build-queue/src/global.rs#L112-L114A held global slot; dropping it (closing the file handle) frees the slot.
fnglobal::try_acquire_slotpub fn try_acquire_slot(root: &Path, n: usize) -> Result<Option<(Slot, usize)>>crates/vox-build-queue/src/global.rs#L119-L136Try 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.
fnglobal::acquire_slotpub fn acquire_slot(root: &Path, n: usize) -> Result<(Slot, u64, usize)>crates/vox-build-queue/src/global.rs#L140-L149Acquire 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.
fnglobal::probe_busy_slotspub fn probe_busy_slots(root: &Path, n: usize) -> Result<usize>crates/vox-build-queue/src/global.rs#L161-L184Count 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.
fnglobal::load_average_1mpub fn load_average_1m() -> Option<f64>crates/vox-build-queue/src/global.rs#L188-L2001-minute load average, or None where the OS does not report one.
fnglobal::acquire_slot_adaptivepub fn acquire_slot_adaptive(root: &Path, cap: usize) -> Result<(Slot, u64, usize)>crates/vox-build-queue/src/global.rs#L203-L219Like [acquire_slot], but a free slot is taken only when [should_admit] agrees.
structglobal::Inflightpub struct Inflightcrates/vox-build-queue/src/global.rs#L223-L226Marker 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.
fnglobal::register_inflightpub fn register_inflight(root: &Path, key: &str) -> Result<(Inflight, bool)>crates/vox-build-queue/src/global.rs#L242-L302Register 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).
structmetrics::MetricRecordpub struct MetricRecordcrates/vox-build-queue/src/metrics.rs#L12-L21—
fnmetrics::now_mspub fn now_ms() -> u128crates/vox-build-queue/src/metrics.rs#L24-L29Wall-clock milliseconds since the Unix epoch (0 if the clock is before it).
fnmetrics::appendpub fn append(path: &Path, rec: &MetricRecord) -> anyhow::Result<()>crates/vox-build-queue/src/metrics.rs#L32-L42Append one JSON line to the metrics file (created with parents if absent).
structmetrics::Summarypub struct Summarycrates/vox-build-queue/src/metrics.rs#L45-L50—
fnmetrics::daemon_recommendedpub fn daemon_recommended(&self) -> boolcrates/vox-build-queue/src/metrics.rs#L56-L58Go/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.
fnmetrics::renderpub fn render(&self) -> Stringcrates/vox-build-queue/src/metrics.rs#L61-L75One-line human summary for vox build-broker stats.
fnmetrics::summarizepub fn summarize(path: &Path) -> anyhow::Result<Summary>crates/vox-build-queue/src/metrics.rs#L80-L83Read a metrics.jsonl file and summarize. Malformed lines are skipped so a partially-written tail never breaks stats.
fnmetrics::summarize_strpub fn summarize_str(text: &str) -> anyhow::Result<Summary>crates/vox-build-queue/src/metrics.rs#L86-L110Summarize already-loaded JSONL content (used when aggregating across dirs).
fnqueue::hash_pathpub fn hash_path(p: &Path) -> Stringcrates/vox-build-queue/src/queue.rs#L28-L32Stable 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).
structqueue::FairQueuepub struct FairQueuecrates/vox-build-queue/src/queue.rs#L35-L37A fair FIFO queue scoped to one worktree.
structqueue::Ticketpub struct Ticketcrates/vox-build-queue/src/queue.rs#L40-L44Held while a build runs; dropping releases the run lock and ticket marker.
fnqueue::newpub fn new(queue_root: &Path, worktree_hash: &str) -> Result<Self>crates/vox-build-queue/src/queue.rs#L47-L51—
fnqueue::take_ticketpub fn take_ticket(&self, key: &str) -> Result<u64>crates/vox-build-queue/src/queue.rs#L57-L84Claim 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.
fnqueue::positionpub fn position(&self, seq: u64) -> usizecrates/vox-build-queue/src/queue.rs#L119-L121How many live tickets are ahead of seq (lower-numbered).
fnqueue::coalesce_opportunitypub fn coalesce_opportunity(&self, seq: u64, key: &str) -> boolcrates/vox-build-queue/src/queue.rs#L125-L129Whether another live invocation shares this command identity (key), i.e. a true coalescing opportunity (not merely queue contention).
fnqueue::acquirepub fn acquire(&self, seq: u64) -> Result<Ticket>crates/vox-build-queue/src/queue.rs#L133-L146Block until this caller holds the exclusive run lock, then return a Ticket whose drop releases the lock and removes the ticket marker.
fnresolve::is_build_subcommandpub fn is_build_subcommand(sub: &str) -> boolcrates/vox-build-queue/src/resolve.rs#L10-L12Subcommands whose runs take the cargo target lock and are worth queueing.
fnresolve::worktree_root_ofpub fn worktree_root_of(start: &Path) -> Option<PathBuf>crates/vox-build-queue/src/resolve.rs#L24-L29Walk 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.
fnresolve::cargo_home_proxypub fn cargo_home_proxy() -> Option<PathBuf>crates/vox-build-queue/src/resolve.rs#L34-L42The 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().
fnresolve::resolve_real_cargopub fn resolve_real_cargo(path_var: &str, own_exe: &Path) -> Option<PathBuf>crates/vox-build-queue/src/resolve.rs#L52-L74Resolve 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).
fnresolve::build_args_for_runpub fn build_args_for_run(args: &[String]) -> Option<Vec<String>>crates/vox-build-queue/src/resolve.rs#L76-L83—