5a24289898fd
ci_lock.rs
//! One `cargo xtask ci` at a time per machine.
//!
//! Every CI run builds the workspace several times with one job per CPU. Several worktrees running
//! it at once (parallel agents) slow each other down far more than waiting in turn would, and make
//! the machine unusable meanwhile. So `ci` first takes one of `LIGHTCRAFT_CI_SLOTS` (default 1)
//! lock files in a per-user cache directory, shared by every checkout and worktree, and holds it
//! until it exits. The OS drops the lock when the process ends, crashed or not.
//!
//! - `LIGHTCRAFT_CI_SLOTS=N`: N runs at once (1–64).
//! - `LIGHTCRAFT_CI_LOCK=off`: no lock (e.g. a CI runner that only ever runs one job).
//! - `LIGHTCRAFT_CI_LOCK=<dir>`: keep the lock files there instead.
use std::fs::{File, OpenOptions, TryLockError};
use std::io::Write;
use std::path::{Path, PathBuf};
use std::time::{Duration, Instant};
const POLL: Duration = Duration::from_secs(2);
/// A held CI slot; dropping it releases the slot.
pub struct Held {
_file: File,
owner: PathBuf,
}
impl Drop for Held {
fn drop(&mut self) {
let _ = std::fs::remove_file(&self.owner);
}
}
/// Where the lock files live, or `None` when the lock is switched off.
fn lock_dir() -> Option<PathBuf> {
match std::env::var_os("LIGHTCRAFT_CI_LOCK") {
Some(v) if matches!(v.to_str(), Some("off" | "0" | "false" | "no")) => return None,
Some(v) if !v.is_empty() => return Some(PathBuf::from(v)),
_ => {}
}
let cache = std::env::var_os("XDG_CACHE_HOME")
.map(PathBuf::from)
.or_else(|| std::env::var_os("LOCALAPPDATA").map(PathBuf::from))
.or_else(|| std::env::var_os("HOME").map(|h| PathBuf::from(h).join(".cache")))
.unwrap_or_else(std::env::temp_dir);
Some(cache.join("lightcraft"))
}
fn slots() -> usize {
std::env::var("LIGHTCRAFT_CI_SLOTS").ok().and_then(|s| s.trim().parse().ok()).unwrap_or(1).clamp(1, 64)
}
fn slot_path(dir: &Path, slot: usize) -> PathBuf {
if slot == 0 { dir.join("ci.lock") } else { dir.join(format!("ci-{}.lock", slot + 1)) }
}
fn owner_path(lock: &Path) -> PathBuf {
lock.with_extension("lock.owner")
}
/// What to do when the lock itself can't be set up (read-only home, sandbox, network mount).
const LOCK_HINT: &str = "set LIGHTCRAFT_CI_LOCK=off to run without the lock, or LIGHTCRAFT_CI_LOCK=<dir> to keep it elsewhere";
/// Take the first free slot of `slots` in `dir`, or `None` when all are held.
pub fn try_acquire(dir: &Path, slots: usize, owner: &str) -> Result<Option<Held>, String> {
std::fs::create_dir_all(dir).map_err(|e| format!("ci lock: {}: {e} ({LOCK_HINT})", dir.display()))?;
for slot in 0..slots.max(1) {
let path = slot_path(dir, slot);
let file = OpenOptions::new()
.create(true)
.truncate(false)
.write(true)
.open(&path)
.map_err(|e| format!("ci lock: {}: {e} ({LOCK_HINT})", path.display()))?;
match file.try_lock() {
Ok(()) => {
// a sidecar file, not the lock file: Windows locks are mandatory, so others couldn't read it
let owner_file = owner_path(&path);
// a new file: an entry left under the name (a link planted in a shared lock folder)
// is removed, never written through
let removed = std::fs::remove_file(&owner_file);
let written = OpenOptions::new().write(true).create_new(true).open(&owner_file).and_then(|mut f| f.write_all(owner.as_bytes()));
// when the file could be neither replaced nor written it may still name an earlier
// holder: say so rather than let `holders` report it as this run's slot's owner
if let (Err(e), Err(w)) = (&removed, &written)
&& e.kind() != std::io::ErrorKind::NotFound
{
eprintln!("ci lock: could not record the owner in {} ({e}; {w}): waiting runs may show a stale owner", owner_file.display());
}
return Ok(Some(Held { _file: file, owner: owner_file }));
}
Err(TryLockError::WouldBlock) => continue,
Err(TryLockError::Error(e)) => return Err(format!("ci lock: {}: {e} ({LOCK_HINT})", path.display())),
}
}
Ok(None)
}
/// Who holds each slot, as they wrote it.
fn holders(dir: &Path, slots: usize) -> Vec<String> {
(0..slots.max(1))
.filter_map(|slot| std::fs::read_to_string(owner_path(&slot_path(dir, slot))).ok())
.map(|s| s.trim().to_owned())
.filter(|s| !s.is_empty())
.collect()
}
/// Wait for a CI slot (see the module docs). `None` when the lock is off.
pub fn acquire(root: &Path, command: &str) -> Result<Option<Held>, String> {
let Some(dir) = lock_dir() else {
return Ok(None);
};
let slots = slots();
let owner = format!("pid {} in {}: {command}", std::process::id(), root.display());
if let Some(held) = try_acquire(&dir, slots, &owner)? {
return Ok(Some(held));
}
let waiting = Instant::now();
eprintln!("=== ci: waiting for another CI run to finish ({slots} at a time; LIGHTCRAFT_CI_SLOTS changes it) ===");
for h in holders(&dir, slots) {
eprintln!(" running: {h}");
}
loop {
std::thread::sleep(POLL);
if let Some(held) = try_acquire(&dir, slots, &owner)? {
eprintln!("=== ci: waited {:.0} s for a CI slot ===", waiting.elapsed().as_secs_f64());
return Ok(Some(held));
}
}
}
#[cfg(test)]
mod tests {
use super::*;
fn scratch(name: &str) -> PathBuf {
let dir = std::env::temp_dir().join(format!("xtask-ci-lock-{name}-{}", std::process::id()));
let _ = std::fs::remove_dir_all(&dir);
dir
}
#[test]
fn one_slot_is_exclusive_until_dropped() {
let dir = scratch("one");
let first = try_acquire(&dir, 1, "first").unwrap().expect("free slot");
assert!(try_acquire(&dir, 1, "second").unwrap().is_none());
assert_eq!(holders(&dir, 1), ["first"]);
drop(first);
assert!(holders(&dir, 1).is_empty());
assert!(try_acquire(&dir, 1, "third").unwrap().is_some());
let _ = std::fs::remove_dir_all(&dir);
}
#[test]
fn more_slots_admit_more_runs() {
let dir = scratch("two");
let a = try_acquire(&dir, 2, "a").unwrap();
let b = try_acquire(&dir, 2, "b").unwrap();
assert!(a.is_some() && b.is_some());
assert!(try_acquire(&dir, 2, "c").unwrap().is_none());
assert_eq!(holders(&dir, 2), ["a", "b"]);
let _ = std::fs::remove_dir_all(&dir);
}
}
No file is open. Choose one in the tree, or press Ctrl+O (⌘O on a Mac) to find one by name.
Syntax highlighting could not load. The unmodified read-only text remains available above.