Code at the speed of thought – Zed is a high-performance, multiplayer code editor from the creators of Atom and Tree-sitter.
gpui: Report foreground executor work in bench reports (#63035)
Anthony Eid7316cf77459a
diff --git a/crates/gpui/src/app/bench_context.rs b/crates/gpui/src/app/bench_context.rsindex 7a74bcee1f5..7fc5831f72d 100644--- a/crates/gpui/src/app/bench_context.rs+++ b/crates/gpui/src/app/bench_context.rs@@ -15,7 +15,10 @@ use crate::{PlatformTextSystem, Render, Reservation, Task, TestPlatform, ThreadedDispatcher, VisualContext,Window, WindowBounds, WindowHandle, WindowOptions,app::GpuiBorrow,- profiler::{self, FrameEvent, FrameTimingCollector},+ profiler::{+ self, FrameEvent, FrameTimingCollector,+ journal::{ForegroundEvent, ForegroundJournalCollector, ForegroundJournalEntry},+ },};/// Returns a benchmark platform backed by this thread's shared dispatcher.@@ -63,6 +66,32 @@ const DEFAULT_FPS: u64 = 120;const NANOS_PER_SECOND: u128 = 1_000_000_000;+/// Aggregate statistics for total foreground executor work observed during a+/// measured interval, returned by [`BenchReport::foreground_work`].+#[derive(Clone, Copy, Debug)]+pub struct ForegroundWorkSummary {+ /// Number of foreground work items recorded: task polls, action+ /// handlers, input dispatches, and folded sub-floor poll flushes.+ pub count: u64,+ /// Sum of every recorded item's duration.+ pub total: Duration,+ /// The longest single recorded item.+ pub max: Duration,+ /// 50th percentile duration.+ pub p50: Duration,+ /// 90th percentile duration.+ pub p90: Duration,+ /// 95th percentile duration.+ pub p95: Duration,+ /// 99th percentile duration.+ pub p99: Duration,+ /// How many whole frame budgets (at the report's configured FPS) were+ /// exceeded in total, summed across every recorded item.+ pub frame_budget_overruns_total: u64,+ /// How many whole frame budgets the longest recorded item exceeded.+ pub frame_budget_overruns_max: u64,+}+/// A small report produced by GPUI benchmarks.#[derive(Clone)]pub struct BenchReport {@@ -128,6 +157,24 @@ impl BenchReport {}}+ /// Records total foreground executor work observed during a measured+ /// interval: task polls, action handlers, and input dispatches, whether+ /// or not they produced a window draw. Draws and presents are excluded+ /// here since [`Self::record_frame_timings`] already accounts for them.+ fn record_foreground_events<'i>(&self, events: impl IntoIterator<Item = &'i ForegroundEvent>) {+ let mut snapshot = self.frame_snapshot.borrow_mut();+ for event in events {+ let duration = match event {+ ForegroundEvent::Draw(_) | ForegroundEvent::Present(_) => continue,+ // A flush's span (used by `ForegroundEvent::duration`) is not+ // the time spent polling; its summary total is.+ ForegroundEvent::SmallPolls(flush) => flush.summary.total,+ _ => event.duration(),+ };+ snapshot.foreground_work.record(duration);+ }+ }+fn total_budget_overruns(&self, histogram: &Histogram<u64>) -> u64 {histogram.iter_recorded()@@ -152,6 +199,36 @@ impl BenchReport {over_budget_nanos.div_ceil(self.frame_budget_nanos) as u64}+ /// Returns aggregate statistics for total foreground executor work+ /// observed during the measured interval: every task poll, action+ /// handler, and input dispatch on the foreground thread, whether or not+ /// it produced a window draw. This is captured through GPUI's foreground+ /// journal, so it requires no window and surfaces a slow or stalled task+ /// even when nothing was drawn while it ran.+ ///+ /// Returns `None` when no foreground work was recorded, e.g. a+ /// [`BenchAppContext::bench_iter`] measurement that does no async work.+ pub fn foreground_work(&self) -> Option<ForegroundWorkSummary> {+ let frame_snapshot = self.frame_snapshot.borrow();+ let foreground_work = &frame_snapshot.foreground_work;+ if foreground_work.histogram.is_empty() {+ return None;+ }++ let max = Duration::from_nanos(foreground_work.histogram.max());+ Some(ForegroundWorkSummary {+ count: foreground_work.histogram.len(),+ total: Duration::from_nanos(foreground_work.total_nanos),+ max,+ p50: Duration::from_nanos(foreground_work.histogram.value_at_quantile(0.50)),+ p90: Duration::from_nanos(foreground_work.histogram.value_at_quantile(0.90)),+ p95: Duration::from_nanos(foreground_work.histogram.value_at_quantile(0.95)),+ p99: Duration::from_nanos(foreground_work.histogram.value_at_quantile(0.99)),+ frame_budget_overruns_total: self.total_budget_overruns(&foreground_work.histogram),+ frame_budget_overruns_max: self.budget_overruns(max),+ })+ }+/// Prints this report to stderr.pub fn print(&self, benchmark_name: Option<&'static str>) {let frame_snapshot = self.frame_snapshot.borrow();@@ -172,6 +249,7 @@ impl BenchReport {frame_snapshot.invalidations_per_frame.max());}+ self.print_foreground_work(&frame_snapshot.foreground_work);}fn print_histogram(&self, name: &str, histogram: &Histogram<u64>) {@@ -179,8 +257,26 @@ impl BenchReport {return;}- let max_foreground_time = Duration::from_nanos(histogram.max());eprintln!(" {name}:");+ self.print_histogram_body(histogram);+ }++ fn print_foreground_work(&self, foreground_work: &DurationHistogram) {+ if foreground_work.histogram.is_empty() {+ return;+ }++ eprintln!(" foreground executor work (task polls, actions, input dispatch):");+ eprintln!(" note: excludes window draw/present, reported separately above");+ eprintln!(+ " total: {}",+ format_duration(Duration::from_nanos(foreground_work.total_nanos))+ );+ self.print_histogram_body(&foreground_work.histogram);+ }++ fn print_histogram_body(&self, histogram: &Histogram<u64>) {+ let max_foreground_time = Duration::from_nanos(histogram.max());eprintln!(" samples: {}", histogram.len());eprintln!(" mean: {}",@@ -219,6 +315,7 @@ struct WindowFrameSnapshot {draw: Histogram<u64>,present_interval: Histogram<u64>,invalidations_per_frame: Histogram<u64>,+ foreground_work: DurationHistogram,}impl WindowFrameSnapshot {@@ -228,11 +325,39 @@ impl WindowFrameSnapshot {draw: Histogram::new(3).expect("3 significant digits is valid"),present_interval: Histogram::new(3).expect("3 significant digits is valid"),invalidations_per_frame: Histogram::new(3).expect("3 significant digits is valid"),+ foreground_work: DurationHistogram::new(),}}fn is_empty(&self) -> bool {- self.dirty_to_draw.is_empty() && self.draw.is_empty() && self.present_interval.is_empty()+ self.dirty_to_draw.is_empty()+ && self.draw.is_empty()+ && self.present_interval.is_empty()+ && self.foreground_work.histogram.is_empty()+ }+}++/// A duration histogram paired with an exact running total, since the+/// histogram's bucketed values (3 significant digits) approximate a sum less+/// precisely than tracking it directly.+struct DurationHistogram {+ histogram: Histogram<u64>,+ total_nanos: u64,+}++impl DurationHistogram {+ fn new() -> Self {+ Self {+ histogram: Histogram::new(3).expect("3 significant digits is valid"),+ total_nanos: 0,+ }+ }++ fn record(&mut self, duration: Duration) {+ let nanos = duration.as_nanos() as u64;+ // Infallible: the histogram auto-resizes.+ self.histogram.record(nanos).ok();+ self.total_nanos += nanos;}}@@ -240,27 +365,56 @@ fn format_duration(duration: Duration) -> String {format!("{:.3}ms", duration.as_secs_f64() * 1000.)}-/// Enables profiler tracing for a measurement and collects its frame events.+/// Enables profiler tracing for a measurement and collects its frame events+/// and foreground journal entries.////// The previous tracing state is restored on drop, so a panicking measurement/// doesn't leave tracing enabled for unrelated code such as a later benchmark/// in the same process.+///+/// The foreground journal collector is created at the same point, so+/// foreground work recorded before the scope starts (e.g. per-iteration+/// setup) is excluded from what [`Self::finish`] returns: a collector only+/// observes entries recorded after its creation.struct TraceScope {collector: FrameTimingCollector,+ journal_collector: ForegroundJournalCollector,_trace_guard: profiler::TraceGuard,}impl TraceScope {- fn start() -> Self {+ fn start(journal_collector: ForegroundJournalCollector) -> Self {let trace_guard = profiler::trace_scope();Self {collector: FrameTimingCollector::new(),+ journal_collector,_trace_guard: trace_guard,}}- fn finish(mut self) -> Vec<FrameEvent> {- self.collector.collect_unseen()+ fn finish(mut self) -> TracedEvents {+ TracedEvents {+ frame_events: self.collector.collect_unseen(),+ journal_entries: self.journal_collector.collect_unseen().entries,+ }+ }+}++/// Events observed during one [`TraceScope`].+struct TracedEvents {+ frame_events: Vec<FrameEvent>,+ journal_entries: Vec<ForegroundJournalEntry>,+}++impl TracedEvents {+ /// Foreground journal entries that describe completed work (task polls,+ /// action handlers, input dispatches, draws, presents, and folded+ /// sub-floor polls), excluding interval boundaries and metadata.+ fn foreground_events(&self) -> impl Iterator<Item = &ForegroundEvent> {+ self.journal_entries.iter().filter_map(|entry| match entry {+ ForegroundJournalEntry::Event(event) => Some(event),+ _ => None,+ })}}@@ -281,8 +435,10 @@ impl<Output> Drop for MeasuredTaskOutput<Output> {.trace_scope.take().expect("measured task output should retain its trace scope");+ let events = trace_scope.finish();+ self.report.record_frame_timings(events.frame_events.iter());self.report- .record_frame_timings(trace_scope.finish().iter());+ .record_foreground_events(events.foreground_events());}}@@ -458,6 +614,12 @@ impl<'a, 'measurement> BenchAppContext<'a, 'measurement> {.run_until(ready)}+ /// Creates a collector observing foreground journal entries recorded+ /// from this point on, for use by a new [`TraceScope`].+ fn foreground_journal_collector(&self) -> ForegroundJournalCollector {+ self.read(|app| app.foreground_journal().collector())+ }+/// Measures a generic benchmark workload using Criterion's iteration loop.////// The closure is invoked once per Criterion iteration with this@@ -467,10 +629,13 @@ impl<'a, 'measurement> BenchAppContext<'a, 'measurement> {/// benchmark's frame report through the GPUI frame profiler.pub fn bench_iter(&mut self, mut benchmark: impl FnMut(&mut Self)) {let bencher = self.take_bencher("bench_iter");- let collector = TraceScope::start();+ let collector = TraceScope::start(self.foreground_journal_collector());let mut benchmark = || benchmark(self);bencher.iter(&mut benchmark);- self.report.record_frame_timings(collector.finish().iter());+ let events = collector.finish();+ self.report.record_frame_timings(events.frame_events.iter());+ self.report+ .record_foreground_events(events.foreground_events());self.replace_bencher(bencher);}@@ -532,7 +697,9 @@ impl<'a, 'measurement> BenchAppContext<'a, 'measurement> {setup_context.settle();MeasuredTaskInput {input: setup(&mut setup_context),- trace_scope: Some(TraceScope::start()),+ trace_scope: Some(TraceScope::start(+ setup_context.foreground_journal_collector(),+ )),}},|measured_input| {@@ -574,7 +741,7 @@ impl<'a, 'measurement> BenchAppContext<'a, 'measurement> {.expect("cannot benchmark renderer for entity without a current window");let dispatcher = self.background_executor.dispatcher().clone();- let collector = TraceScope::start();+ let collector = TraceScope::start(self.foreground_journal_collector());let mut benchmark = || {// Work already queued at frame start delays the frame in@@ -599,10 +766,16 @@ impl<'a, 'measurement> BenchAppContext<'a, 'measurement> {let events = collector.finish();self.report- .record_frame_timings(events.iter().filter(|event| match event {+ .record_frame_timings(events.frame_events.iter().filter(|event| match event {FrameEvent::Draw(timing) => timing.window_id == window_id,FrameEvent::Present(timing) => timing.window_id == window_id,}));+ // Foreground work isn't attributed to a window, so unlike frame+ // timings above it isn't filtered by `window_id`. A benchmark app+ // hosts one window at a time, so this cannot pick up unrelated+ // windows' work.+ self.report+ .record_foreground_events(events.foreground_events());self.replace_bencher(bencher);}@@ -951,6 +1124,130 @@ mod tests {use std::{rc::Rc, sync::Arc};use super::*;+ use crate::profiler::journal::install_test_foreground_journal;++ #[test]+ fn foreground_work_reports_long_task_without_window_draw() {+ let (journal, _journal_guard) = install_test_foreground_journal(1024, 64);+ let dispatcher = Arc::new(ThreadedDispatcher::new());+ let foreground_executor = ForegroundExecutor::new(dispatcher);++ let trace_scope = TraceScope::start(journal.collector());++ // A single foreground task poll that never touches a window, akin+ // to the stall a debounced background computation can cause.+ let task = foreground_executor.spawn(async move {+ std::thread::sleep(Duration::from_millis(60));+ });+ run_task_to_completion(&foreground_executor, task);++ let events = trace_scope.finish();+ assert!(+ events.frame_events.is_empty(),+ "no window was involved, so no frame events should be recorded"+ );++ let report = BenchReport::default();+ report.record_foreground_events(events.foreground_events());++ let summary = report+ .foreground_work()+ .expect("a long task poll should be reported even without a window draw");+ // The spawned task's own poll is one sample; the tiny wrapper poll+ // that observes its completion in `run_task_to_completion` folds+ // into a second, near-zero sample rather than being dropped.+ assert!(summary.count >= 1, "expected at least one recorded item");+ assert!(+ summary.max >= Duration::from_millis(55),+ "expected the long poll's duration to be recorded, got {:?}",+ summary.max+ );+ // `total` is an exact sum, while `max` may be rounded up to its+ // histogram bucket's boundary, so compare each against the expected+ // floor directly instead of against each other.+ assert!(+ summary.total >= Duration::from_millis(55),+ "expected the long poll's duration to be included in the total, got {:?}",+ summary.total+ );+ }++ #[test]+ fn foreground_work_excludes_setup_before_trace_scope_starts() {+ let (journal, _journal_guard) = install_test_foreground_journal(1024, 64);+ let dispatcher = Arc::new(ThreadedDispatcher::new());+ let foreground_executor = ForegroundExecutor::new(dispatcher);++ // Fixture/setup work that must not be attributed to the measurement:+ // a long poll recorded before the trace scope (and its journal+ // collector) is created.+ let setup_task = foreground_executor.spawn(async move {+ std::thread::sleep(Duration::from_millis(80));+ });+ run_task_to_completion(&foreground_executor, setup_task);++ let trace_scope = TraceScope::start(journal.collector());++ let measured_task = foreground_executor.spawn(async move {+ std::thread::sleep(Duration::from_millis(10));+ });+ run_task_to_completion(&foreground_executor, measured_task);++ let events = trace_scope.finish();+ let report = BenchReport::default();+ report.record_foreground_events(events.foreground_events());++ let summary = report+ .foreground_work()+ .expect("the measured task's poll should be reported");+ assert!(+ summary.max < Duration::from_millis(40),+ "setup work's 80ms poll must not leak into the measured summary, got {:?}",+ summary.max+ );+ assert!(+ summary.total < Duration::from_millis(40),+ "setup work's 80ms poll must not leak into the measured total, got {:?}",+ summary.total+ );+ }++ #[test]+ fn bench_task_reports_long_task_without_window() {+ let platform = bench_platform(None, Arc::new(crate::NoopTextSystem::new()));+ let report = BenchReport::default();+ let name = "bench_task_reports_long_task_without_window";++ let mut criterion = criterion::Criterion::default()+ .without_plots()+ .sample_size(10)+ .warm_up_time(Duration::from_millis(1))+ .measurement_time(Duration::from_millis(1));++ criterion.bench_function(name, |bencher| {+ let mut cx = BenchAppContext::new_with_platform_and_report(+ platform.clone(),+ Some(name),+ bencher,+ report.clone(),+ );+ cx.bench_task(|cx| {+ cx.foreground_executor().spawn(async move {+ std::thread::sleep(Duration::from_millis(20));+ })+ });+ cx.teardown();+ });++ let summary = report+ .foreground_work()+ .expect("bench_task should report foreground work with no window involved");+ assert!(+ summary.max >= Duration::from_millis(15),+ "expected a ~20ms task poll to be recorded, got {:?}",+ summary.max+ );+ }#[test]fn task_completion_supports_non_send_foreground_output() {diff --git a/crates/gpui/src/profiler/journal.rs b/crates/gpui/src/profiler/journal.rsindex ffd694b9148..761181a0ad2 100644--- a/crates/gpui/src/profiler/journal.rs+++ b/crates/gpui/src/profiler/journal.rs@@ -553,8 +553,11 @@ pub(crate) fn install_foreground_journal() -> ForegroundJournal {})}+/// Restores the previous foreground journal on drop, so a test's writer+/// (turn depth, pending frames, retained-since-boundary state) never leaks+/// into a later test that happens to reuse the same test-harness thread.#[cfg(test)]-pub(super) struct TestForegroundJournalGuard {+pub(crate) struct TestForegroundJournalGuard {previous: Option<ForegroundJournalWriter>,_not_send: std::marker::PhantomData<std::rc::Rc<()>>,}@@ -568,8 +571,12 @@ impl Drop for TestForegroundJournalGuard {}}+/// Installs a fresh journal for the duration of a test, isolated from+/// whatever a previous test left on this thread. Used by tests outside this+/// module (e.g. `bench_context`) that need to observe journal entries+/// without interference from the shared per-thread journal.#[cfg(test)]-pub(super) fn install_test_foreground_journal(+pub(crate) fn install_test_foreground_journal(capacity: usize,pending_capacity: usize,) -> (ForegroundJournal, TestForegroundJournalGuard) {