Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows
perf(picker): stage preview pre-compute and unify rayon pool (#2662)
Maximilian Roos3802b20a20c2
diff --git a/src/commands/list/collect/mod.rs b/src/commands/list/collect/mod.rsindex a6dac1c97..8248c8362 100644--- a/src/commands/list/collect/mod.rs+++ b/src/commands/list/collect/mod.rs@@ -372,6 +372,18 @@ pub trait PickerProgressHandler: Send + Sync {/// would corrupt the rendered frame. The picker drains stashed lines/// after `Skim::run_with` returns, when stderr is safe again.fn stash_warning(&self, line: String);++ /// Fired once before `collect` returns `Ok(Some(_))`. Lets the picker+ /// kick off the deferred tier of background work — secondary preview+ /// modes for items 1..N, and LLM summaries for items 1..N. The+ /// global rayon pool serves both pipelines; deferring this tier+ /// until drain-end keeps low-priority preview submissions out of+ /// the injector while row tasks dominate worker deques.+ ///+ /// Not fired on the `WORKTRUNK_SKELETON_ONLY` / `WORKTRUNK_FIRST_OUTPUT`+ /// benchmark early-exit, nor on the zero-worktree `Ok(None)` return+ /// (which exits before `on_skeleton`). Default: no-op.+ fn on_collect_complete(&self) {}}/// Controls how show flags (branches/remotes/full) are determined in [`collect`].@@ -1544,6 +1556,14 @@ pub fn collect(// UI (picker via `progressive_handler`)worktrunk::trace::instant("List collect complete");+ // Fire `on_collect_complete` after the row pipeline has fully torn+ // down. The picker handler uses this to spawn bulk preview pre-compute+ // for items 1..N without contending with row tasks. No-op for+ // non-picker callers (default trait impl).+ if let Some(handler) = progressive_handler.as_ref() {+ handler.on_collect_complete();+ }+Ok(Some(super::model::ListData { items }))}diff --git a/src/commands/picker/mod.rs b/src/commands/picker/mod.rsindex f02b226ef..c99fd8f59 100644--- a/src/commands/picker/mod.rs+++ b/src/commands/picker/mod.rs@@ -23,8 +23,8 @@//! 1. `current_or_recover` + config resolution.//! 2. `PreviewState::new` — auto-detects Right vs Down layout.//! 3. Allocates the `PreviewOrchestrator` and kicks off a *speculative*-//! `git diff HEAD` for the current worktree on the preview pool. That bg-//! work overlaps with everything below.+//! `git diff HEAD` for the current worktree on the global rayon pool.+//! That bg work overlaps with everything below.//! 4. Computes `num_items_estimate` — `list_worktrees` plus (conditionally)//! `local_branches` / `remote_branches`, capped at//! `MAX_VISIBLE_ITEMS`. Only used to size skim's `preview_window`.@@ -410,8 +410,9 @@ pub fn handle_picker(// (which runs `prewarm_info` again — now a cache hit).let _ = repo.current_worktree().prewarm_info();- // Preview cache + dedicated pool are created up-front so the speculative- // first-item preview can run in parallel with `collect::collect` below.+ // Preview cache is created up-front so the speculative first-item+ // preview can run in parallel with `collect::collect` below. Tasks+ // route to the global rayon pool (shared with the row pipeline).// Wrapped in `Arc` because the progressive handler (running on the// collect background thread) also calls `spawn_preview`.//@@ -653,6 +654,7 @@ pub fn handle_picker(llm_command,summary_hint,stashed_warnings: Arc::clone(&stashed_warnings),+ deferred_items: std::sync::OnceLock::new(),});// Spawn collect on a background thread. The handler holds the only@@ -689,7 +691,8 @@ pub fn handle_picker(drop(handler);// Dry-run: skim is bypassed. Wait for collect (which spawns previews- // via the handler), then for the preview pool, then dump the cache.+ // via the handler) to finish, then for the orchestrator's pending+ // tasks to drain on the global rayon pool, then dump the cache.if std::env::var_os("WORKTRUNK_PICKER_DRY_RUN").is_some() {drop(rx);let _ = bg_handle.join();diff --git a/src/commands/picker/preview_cache.rs b/src/commands/picker/preview_cache.rsindex 7e0b0c2a2..e89f72eaf 100644--- a/src/commands/picker/preview_cache.rs+++ b/src/commands/picker/preview_cache.rs@@ -56,7 +56,7 @@ const KIND: &str = "picker-preview";/// commonly: a squash merge landing `main` at the cached SHA) would/// leave the decoration text stale even though the cache key is still/// valid. The orchestrator mitigates this by enqueuing a background-/// refresh task on the picker's rayon pool whenever a Log preview hit+/// refresh task on the global rayon pool whenever a Log preview hit/// the disk cache; the refresh re-runs `compute_log_raw_and_stats`,/// overwrites this entry, and updates the in-memory `PreviewCache`./// The cached entry served on the *current* render is still potentiallydiff --git a/src/commands/picker/preview_orchestrator.rs b/src/commands/picker/preview_orchestrator.rsindex 039e59654..d097b9375 100644--- a/src/commands/picker/preview_orchestrator.rs+++ b/src/commands/picker/preview_orchestrator.rs@@ -1,10 +1,15 @@//! Background preview pre-compute orchestration.//!-//! Owns the dedicated rayon pool and preview cache for the picker, so the-//! pre-compute pipeline is testable without standing up skim. The picker-//! entry point (`run_picker`) uses this for its real spawns; the dry-run-//! path (`WORKTRUNK_PICKER_DRY_RUN`) uses it to wait for completion and dump the-//! cache to stdout.+//! Routes preview tasks to the global rayon pool (shared with the row+//! pipeline) and tracks the in-memory cache. A single pool lets workers+//! prefer whichever workload has dominant pressure: row tasks land on+//! workers' local deques and take priority during drain; preview tasks+//! sit in the global injector and pick up workers as they free.+//!+//! Provides a pending-task counter for the dry-run path+//! (`WORKTRUNK_PICKER_DRY_RUN`) and tests, both of which want to wait for+//! all spawned tasks to complete before reading the cache. The picker+//! entry point (`handle_picker`) uses this for its real spawns.use std::sync::Arc;use std::sync::atomic::{AtomicUsize, Ordering};@@ -18,6 +23,22 @@ use super::preview::PreviewMode;use super::summary;use crate::commands::list::model::ListItem;+/// The picker's initial preview tab — `WorkingTree`, shown when the+/// picker opens. Pre-computed for every row at skeleton time so j/k+/// navigation lands on warm content without paying the 4-mode bulk cost+/// per row during the row-fill window.+const INITIAL_MODE: PreviewMode = PreviewMode::WorkingTree;++/// Modes other than [`INITIAL_MODE`]. For the user's landing row (item 0)+/// these pre-compute at skeleton time alongside `INITIAL_MODE` so+/// tab-cycling is responsive immediately. For items 1..N they're+/// deferred until `spawn_deferred_precompute` fires (after row drain).+const SECONDARY_MODES: [PreviewMode; 3] = [+ PreviewMode::Log,+ PreviewMode::BranchDiff,+ PreviewMode::UpstreamDiff,+];+struct PendingGuard(Arc<AtomicUsize>);impl Drop for PendingGuard {@@ -28,7 +49,6 @@ impl Drop for PendingGuard {pub(super) struct PreviewOrchestrator {pub(super) cache: PreviewCache,- pool: Arc<rayon::ThreadPool>,pending: Arc<AtomicUsize>,/// Repository used by preview compute. Captured once at construction/// so background tasks see a stable repo binding, and so unit tests@@ -45,17 +65,8 @@ pub(super) struct PreviewOrchestrator {impl PreviewOrchestrator {pub(super) fn new(repo: Repository) -> Self {- let cache = Arc::new(DashMap::new());- let pool = Arc::new(- rayon::ThreadPoolBuilder::new()- .num_threads(crate::rayon_thread_count())- .thread_name(|i| format!("picker-preview-{i}"))- .build()- .expect("failed to build picker preview rayon pool"),- );Self {- cache,- pool,+ cache: Arc::new(DashMap::new()),pending: Arc::new(AtomicUsize::new(0)),repo,}@@ -70,10 +81,11 @@ impl PreviewOrchestrator {/// blocked on a shard write held across git/pager subprocesses.////// Log mode that hits the disk cache also enqueues a refresh task- /// (via `pool.spawn_fifo`, so it lands behind in-flight foreground- /// precompute) to recompute the embedded ref decorations before the- /// next visit. See the `LogCacheEntry` docstring for why the disk- /// cache itself is SHA-keyed but decoration text drifts.+ /// (via `rayon::spawn_fifo`, so it lands behind in-flight foreground+ /// precompute submitted with `rayon::spawn`) to recompute the+ /// embedded ref decorations before the next visit. See the+ /// `LogCacheEntry` docstring for why the disk cache itself is+ /// SHA-keyed but decoration text drifts.pub(super) fn spawn_preview(&self,item: Arc<ListItem>,@@ -83,7 +95,6 @@ impl PreviewOrchestrator {let cache = Arc::clone(&self.cache);let (w, h) = dims;let repo = self.repo.clone();- let pool = Arc::clone(&self.pool);let pending = Arc::clone(&self.pending);self.spawn_task(move || {let cache_key = (item.branch_name().to_string(), mode);@@ -99,7 +110,7 @@ impl PreviewOrchestrator {let item = Arc::clone(&item);let cache = Arc::clone(&cache);let repo = repo.clone();- pool.spawn_fifo(move || {+ rayon::spawn_fifo(move || {let _g = guard;let rendered = WorktreeSkimItem::refresh_log_preview(&repo, &item, w, h);// Skip empty results so a transient `git log` failure@@ -121,54 +132,87 @@ impl PreviewOrchestrator {});}- /// Spawn the full pre-compute fan-out for a freshly published skeleton.+ /// Spawn the skeleton-time pre-compute tier.///- /// Spawn order: the first item's modes win the first slots (the user- /// lands there and may tab-cycle), then mode-major across the rest.- /// Summaries queue last because each LLM call can take seconds.+ /// Fires at `on_skeleton`. Two layers of priority:+ /// - First item × all 4 modes + first item summary — the user lands on+ /// row 0 and frequently tab-cycles modes there.+ /// - Items 1..N × [`INITIAL_MODE`] only — pre-warms the default tab+ /// for every row so quick j/k navigation hits cached content,+ /// bounded contention with the row pipeline (~N tasks).///- /// When `llm_command` is `None` and `summary_hint` is `Some`, the hint- /// is written directly into the Summary cache for every item — gives- /// the Summary tab something useful instead of a perpetual- /// "Generating…" placeholder.- pub(super) fn spawn_all_precompute(+ /// The remaining [`SECONDARY_MODES`] for items 1..N and their summaries+ /// are deferred to [`Self::spawn_deferred_precompute`], which fires+ /// after the row pipeline tears down.+ pub(super) fn spawn_initial_precompute(&self,- list_items: &[Arc<ListItem>],+ items: &[Arc<ListItem>],preview_dims: (usize, usize),llm_command: Option<&str>,- summary_hint: Option<&str>,) {- let modes = [- PreviewMode::WorkingTree,- PreviewMode::Log,- PreviewMode::BranchDiff,- PreviewMode::UpstreamDiff,- ];-- if let Some(first) = list_items.first() {- for mode in modes {- self.spawn_preview(Arc::clone(first), mode, preview_dims);- }+ let Some(first) = items.first() else { return };++ // First item: all modes + summary.+ self.spawn_preview(Arc::clone(first), INITIAL_MODE, preview_dims);+ for mode in SECONDARY_MODES {+ self.spawn_preview(Arc::clone(first), mode, preview_dims);+ }+ if let Some(llm) = llm_command {+ self.spawn_summary(Arc::clone(first), llm.to_string(), self.repo.clone());+ }++ // Items 1..N: default tab only. Other modes wait for drain.+ for item in items.iter().skip(1) {+ self.spawn_preview(Arc::clone(item), INITIAL_MODE, preview_dims);}- for mode in modes {- for item in list_items.iter().skip(1) {+ }++ /// Spawn the deferred pre-compute tier for items 1..N.+ ///+ /// Fires from the picker handler's `on_collect_complete` hook — i.e.+ /// after `collect::collect`'s drain ends. The global rayon pool+ /// serves both the row pipeline and the preview pipeline; deferring+ /// this tier keeps these submissions out of the global injector+ /// while row tasks are still landing on workers' local deques. The+ /// default tab for these rows already fired at skeleton time via+ /// [`Self::spawn_initial_precompute`]; what's left is+ /// [`SECONDARY_MODES`] plus summaries.+ ///+ /// Spawn order: mode-major across previews, then summaries last —+ /// each LLM call can take seconds. Called from outside any rayon+ /// worker (the picker-collect bg thread), so submissions land on+ /// rayon's FIFO injector and workers pick previews before summaries.+ pub(super) fn spawn_deferred_precompute(+ &self,+ rest: &[Arc<ListItem>],+ preview_dims: (usize, usize),+ llm_command: Option<&str>,+ ) {+ for mode in SECONDARY_MODES {+ for item in rest {self.spawn_preview(Arc::clone(item), mode, preview_dims);}}-if let Some(llm) = llm_command {- if let Some(first) = list_items.first() {- self.spawn_summary(Arc::clone(first), llm.to_string(), self.repo.clone());- }- for item in list_items.iter().skip(1) {+ for item in rest {self.spawn_summary(Arc::clone(item), llm.to_string(), self.repo.clone());}- } else if let Some(hint) = summary_hint {- for item in list_items {- let branch = item.branch_name().to_string();- self.cache- .insert((branch, PreviewMode::Summary), hint.to_string());- }+ }+ }++ /// Seed the Summary cache with a static hint for every item.+ ///+ /// Used when summaries are disabled — gives the Summary tab something+ /// useful instead of a perpetual "Generating…" placeholder. Pure+ /// synchronous `DashMap::insert` calls (zero CPU, no subprocess), so+ /// this runs at skeleton time for every row regardless of position+ /// — no contention concern.+ pub(super) fn seed_summary_hints(&self, items: &[Arc<ListItem>], hint: &str) {+ for item in items {+ self.cache.insert(+ (item.branch_name().to_string(), PreviewMode::Summary),+ hint.to_string(),+ );}}@@ -182,7 +226,11 @@ impl PreviewOrchestrator {let _g = guard;task();};- self.pool.spawn(wrapped);+ // The `pending` counter is independent of which pool the task+ // lands on, so routing through `rayon::spawn` (global pool, shared+ // with the row pipeline) doesn't change `wait_for_idle` semantics+ // in tests or the dry-run path.+ rayon::spawn(wrapped);}/// Block until all spawned tasks complete.diff --git a/src/commands/picker/progressive_handler.rs b/src/commands/picker/progressive_handler.rsindex dfd3e6793..0d3eaa240 100644--- a/src/commands/picker/progressive_handler.rs+++ b/src/commands/picker/progressive_handler.rs@@ -5,8 +5,17 @@//! item's shared `rendered` mutex (in-place redraws picked up by the//! heartbeat), and `shared_items` used by `PickerCollector` for alt-r.//!-//! Preview + summary pre-compute kicks off at skeleton time so the first-//! preview the user opens is already warm.+//! Preview pre-compute is staged in two tiers:+//! - `on_skeleton` fires the first item's 4 modes + first-item summary,+//! plus the default-tab mode for items 1..N (so quick j/k navigation+//! lands on warm content). It also fills the static Summary hint for+//! every row when summaries are disabled.+//! - `on_collect_complete` fires the secondary modes (Log / BranchDiff /+//! UpstreamDiff) and summaries for items 1..N once the row pipeline+//! has torn down. Preview tasks share the global rayon pool with the+//! row pipeline; staging keeps low-priority preview submissions out+//! of the global injector while row tasks are still landing on+//! workers' local deques during drain.use std::sync::{Arc, Mutex, OnceLock};@@ -45,6 +54,10 @@ pub(super) struct PickerHandler {/// owns the terminal. The picker drains and emits these to stderr after/// `Skim::run_with` returns. Lines are kept in arrival order.pub(super) stashed_warnings: Arc<Mutex<Vec<String>>>,+ /// Items captured at `on_skeleton` and consumed at `on_collect_complete`+ /// to fan out the bulk preview pre-compute for items 1..N. Set once+ /// (`OnceLock`) because skeletons fire exactly once per collect.+ pub(super) deferred_items: OnceLock<Vec<Arc<ListItem>>>,}impl PickerProgressHandler for PickerHandler {@@ -103,12 +116,26 @@ impl PickerProgressHandler for PickerHandler {let _ = self.tx.send(Arc::clone(skim_item));}- self.orchestrator.spawn_all_precompute(+ // Tier 1: warm the user's landing row (all modes) and every+ // other row's default tab. Tier 2 (secondary modes + summaries+ // for items 1..N) fires from `on_collect_complete` after the row+ // pipeline tears down — spawning that bulk now would queue ahead+ // of row tasks in the global injector while workers are still+ // grinding through the row work.+ self.orchestrator.spawn_initial_precompute(&list_items,self.preview_dims,self.llm_command.as_deref(),- self.summary_hint.as_deref(),);+ // Static Summary hint is a synchronous in-memory insert, no+ // contention concern. Pre-fill every row at skeleton time so the+ // Summary tab is usable for any selection immediately.+ if self.llm_command.is_none()+ && let Some(hint) = self.summary_hint.as_deref()+ {+ self.orchestrator.seed_summary_hints(&list_items, hint);+ }+ let _ = self.deferred_items.set(list_items);}fn on_update(&self, idx: usize, rendered: String) {@@ -131,6 +158,20 @@ impl PickerProgressHandler for PickerHandler {fn stash_warning(&self, line: String) {self.stashed_warnings.lock().unwrap().push(line);}++ fn on_collect_complete(&self) {+ let Some(items) = self.deferred_items.get() else {+ return;+ };+ if items.len() <= 1 {+ return;+ }+ self.orchestrator.spawn_deferred_precompute(+ &items[1..],+ self.preview_dims,+ self.llm_command.as_deref(),+ );+ }}#[cfg(test)]@@ -159,6 +200,7 @@ mod tests {llm_command: None,summary_hint: Some("disabled".to_string()),stashed_warnings: Arc::new(Mutex::new(Vec::new())),+ deferred_items: OnceLock::new(),};(handler, test, rx)}@@ -248,4 +290,144 @@ mod tests {let stash = handler.stashed_warnings.lock().unwrap();assert_eq!(stash.as_slice(), &["first", "second", "third"]);}++ /// Preview pre-compute is tiered. After `on_skeleton`:+ /// - First item gets all 4 modes (the user's landing row).+ /// - Items 1..N get only `WorkingTree` (the picker's initial tab) so+ /// quick j/k navigation hits warm content.+ /// - Secondary modes for items 1..N are deferred until+ /// `on_collect_complete` fires.+ ///+ /// Summary hint is filled for every item synchronously at skeleton+ /// time so the Summary tab is usable for any selection immediately.+ #[test]+ fn precompute_staging_tiers_match_design() {+ use super::super::preview::PreviewMode;++ let (handler, _test, _rx) = make_handler();+ let items = vec![+ ListItem::new_branch("aaa".into(), "alpha".into()),+ ListItem::new_branch("bbb".into(), "beta".into()),+ ListItem::new_branch("ccc".into(), "gamma".into()),+ ];+ let rendered = vec!["s1".into(), "s2".into(), "s3".into()];++ handler.on_skeleton(items, rendered, header("hdr"));+ handler.orchestrator.wait_for_idle();++ // Static Summary hint primed for every item at skeleton time.+ for branch in ["alpha", "beta", "gamma"] {+ assert!(+ handler+ .preview_cache+ .contains_key(&(branch.into(), PreviewMode::Summary)),+ "Summary hint should be filled for {branch} at skeleton time"+ );+ }++ // First item: all 4 modes spawned at skeleton time.+ for mode in [+ PreviewMode::WorkingTree,+ PreviewMode::Log,+ PreviewMode::BranchDiff,+ PreviewMode::UpstreamDiff,+ ] {+ assert!(+ handler.preview_cache.contains_key(&("alpha".into(), mode)),+ "first item should have {mode:?} cached after on_skeleton"+ );+ }++ // Items 1..N: WorkingTree (default tab) cached at skeleton time.+ for branch in ["beta", "gamma"] {+ assert!(+ handler+ .preview_cache+ .contains_key(&(branch.into(), PreviewMode::WorkingTree)),+ "{branch}.WorkingTree should be cached after on_skeleton (initial tier)"+ );+ }++ // Items 1..N: secondary modes NOT yet spawned (deferred tier).+ for branch in ["beta", "gamma"] {+ for mode in [+ PreviewMode::Log,+ PreviewMode::BranchDiff,+ PreviewMode::UpstreamDiff,+ ] {+ assert!(+ !handler.preview_cache.contains_key(&(branch.into(), mode)),+ "{branch}.{mode:?} should NOT be cached before on_collect_complete"+ );+ }+ }++ handler.on_collect_complete();+ handler.orchestrator.wait_for_idle();++ // After on_collect_complete, every item × every preview mode is cached.+ for branch in ["alpha", "beta", "gamma"] {+ for mode in [+ PreviewMode::WorkingTree,+ PreviewMode::Log,+ PreviewMode::BranchDiff,+ PreviewMode::UpstreamDiff,+ ] {+ assert!(+ handler.preview_cache.contains_key(&(branch.into(), mode)),+ "{branch}.{mode:?} should be cached after on_collect_complete"+ );+ }+ }+ }++ /// `on_collect_complete` is safe to call when no skeleton ever fired+ /// (e.g. zero-worktree early return in `collect`) and when only one+ /// item exists (nothing to defer). The post-conditions assert that no+ /// extra spawns leak into the cache — a regression that introduces+ /// work for items 1..N from this hook would surface here.+ #[test]+ fn on_collect_complete_is_no_op_when_no_rest_items() {+ use super::super::preview::PreviewMode;++ // Case 1: never called on_skeleton — cache must remain empty.+ let (handler, _test, _rx) = make_handler();+ handler.on_collect_complete();+ handler.orchestrator.wait_for_idle();+ assert_eq!(+ handler.preview_cache.iter().count(),+ 0,+ "no work should be spawned when on_skeleton never fired"+ );++ // Case 2: single-item skeleton — first-item phase covered the 4+ // modes plus the static Summary hint (5 entries total). Nothing+ // left to defer; on_collect_complete must not add any entries.+ let (handler, _test, _rx) = make_handler();+ let items = vec![ListItem::new_branch("aaa".into(), "solo".into())];+ handler.on_skeleton(items, vec!["s1".into()], header("hdr"));+ handler.orchestrator.wait_for_idle();+ let before = handler.preview_cache.iter().count();+ for mode in [+ PreviewMode::WorkingTree,+ PreviewMode::Log,+ PreviewMode::BranchDiff,+ PreviewMode::UpstreamDiff,+ PreviewMode::Summary,+ ] {+ assert!(+ handler.preview_cache.contains_key(&("solo".into(), mode)),+ "first-item phase should have cached {mode:?}"+ );+ }+ assert_eq!(before, 5, "first-item phase populates exactly 5 entries");++ handler.on_collect_complete();+ handler.orchestrator.wait_for_idle();+ assert_eq!(+ handler.preview_cache.iter().count(),+ before,+ "on_collect_complete must not spawn additional work for a single-item skeleton"+ );+ }}