Skip to content

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.rs
index 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.rs
index 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.rs
index 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 potentially
diff --git a/src/commands/picker/preview_orchestrator.rs b/src/commands/picker/preview_orchestrator.rs
index 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.rs
index 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"
+ );
+ }
}