Skip to content

armgit / zed

Public Imported from GitHub
0

Code at the speed of thought – Zed is a high-performance, multiplayer code editor from the creators of Atom and Tree-sitter.

gpui: Journal foreground work between frames and report hang incidents (#62779)

Anthony Eid1861e58f984c
diff --git a/Cargo.lock b/Cargo.lock
index fcbb281d430..59936218079 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -23357,7 +23357,6 @@ dependencies = [
"gpui",
"gpui_platform",
"gpui_tokio",
- "hdrhistogram",
"http_client",
"image",
"image_viewer",
@@ -23423,6 +23422,7 @@ dependencies = [
"smol",
"snippet_provider",
"snippets_ui",
+ "spin 0.10.0",
"svg_preview",
"sysinfo 0.37.2",
"system_specs",
diff --git a/crates/gpui/src/app.rs b/crates/gpui/src/app.rs
index 452143676a0..b99da408226 100644
--- a/crates/gpui/src/app.rs
+++ b/crates/gpui/src/app.rs
@@ -689,6 +689,8 @@ pub struct App {
platform_owned_drag: Option<PlatformOwnedDrag>,
pub(crate) background_executor: BackgroundExecutor,
pub(crate) foreground_executor: ForegroundExecutor,
+ #[cfg(feature = "profiler")]
+ foreground_journal: crate::profiler::journal::ForegroundJournal,
pub(crate) entities: EntityMap,
pub(crate) new_entity_observers: SubscriberSet<TypeId, NewEntityListener>,
pub(crate) windows: SlotMap<WindowId, Option<Box<Window>>>,
@@ -785,6 +787,8 @@ impl App {
background_executor.is_main_thread(),
"must construct App on main thread"
);
+ #[cfg(feature = "profiler")]
+ let foreground_journal = crate::profiler::journal::install_foreground_journal();
let synced_animation_epoch = background_executor.now();
let text_system = Arc::new(TextSystem::new(platform.text_system()));
@@ -809,6 +813,8 @@ impl App {
platform_owned_drag: None,
background_executor,
foreground_executor,
+ #[cfg(feature = "profiler")]
+ foreground_journal,
svg_renderer: SvgRenderer::new(asset_source.clone()),
loading_assets: Default::default(),
asset_source,
@@ -1920,6 +1926,13 @@ impl App {
&self.foreground_executor
}
+ /// Returns the foreground work journal for this app's foreground thread.
+ /// Apps constructed on the same thread share the stream.
+ #[cfg(feature = "profiler")]
+ pub fn foreground_journal(&self) -> crate::profiler::journal::ForegroundJournal {
+ self.foreground_journal.clone()
+ }
+
/// Spawns the future returned by the given function on the main thread. The closure will be invoked
/// with [AsyncApp], which allows the application state to be accessed across await points.
#[track_caller]
diff --git a/crates/gpui/src/executor.rs b/crates/gpui/src/executor.rs
index b5c1737aa19..fb8eefd63b0 100644
--- a/crates/gpui/src/executor.rs
+++ b/crates/gpui/src/executor.rs
@@ -24,6 +24,8 @@ pub struct BackgroundExecutor {
pub struct ForegroundExecutor {
inner: scheduler::LocalExecutor,
dispatcher: Arc<dyn PlatformDispatcher>,
+ #[cfg(feature = "profiler")]
+ foreground_runnables: Option<crate::profiler::journal::ForegroundRunnableCounter>,
not_send: PhantomData<Rc<()>>,
}
@@ -305,15 +307,18 @@ impl ForegroundExecutor {
return Self {
inner,
dispatcher,
+ #[cfg(feature = "profiler")]
+ foreground_runnables: Some(platform_scheduler.foreground_runnable_counter()),
not_send: PhantomData,
};
};
#[cfg(not(any(test, feature = "test-support")))]
- let inner = {
- let platform_scheduler = Arc::new(PlatformScheduler::new(dispatcher.clone()));
- platform_scheduler.foreground_executor()
- };
+ let platform_scheduler = Arc::new(PlatformScheduler::new(dispatcher.clone()));
+ #[cfg(not(any(test, feature = "test-support")))]
+ let inner = platform_scheduler.foreground_executor();
+ #[cfg(all(not(any(test, feature = "test-support")), feature = "profiler"))]
+ let foreground_runnables = Some(platform_scheduler.foreground_runnable_counter());
#[cfg(any(test, feature = "test-support"))]
let inner = {
@@ -325,9 +330,16 @@ impl ForegroundExecutor {
})
};
+ #[cfg(all(any(test, feature = "test-support"), feature = "profiler"))]
+ // The deterministic test scheduler does not invoke GPUI's task profiler
+ // hooks, so an increment here would have no matching decrement.
+ let foreground_runnables = None;
+
Self {
inner,
dispatcher,
+ #[cfg(feature = "profiler")]
+ foreground_runnables,
not_send: PhantomData,
}
}
@@ -374,8 +386,14 @@ impl ForegroundExecutor {
R: 'static,
{
let dispatcher = self.dispatcher.clone();
+ #[cfg(feature = "profiler")]
+ let foreground_runnables = self.foreground_runnables.clone();
self.inner
.spawn_with_dispatch(future.boxed_local(), move |runnable| {
+ #[cfg(feature = "profiler")]
+ if let Some(foreground_runnables) = &foreground_runnables {
+ foreground_runnables.queued();
+ }
dispatcher.dispatch_on_main_thread_when_idle(runnable, timeout);
})
}
diff --git a/crates/gpui/src/interactive.rs b/crates/gpui/src/interactive.rs
index ac5210a11d6..790593c4635 100644
--- a/crates/gpui/src/interactive.rs
+++ b/crates/gpui/src/interactive.rs
@@ -821,6 +821,25 @@ impl PlatformInput {
}
}
+ /// A short static name for this input's variant, for diagnostics and
+ /// telemetry.
+ pub fn kind_name(&self) -> &'static str {
+ match self {
+ PlatformInput::KeyDown(_) => "key_down",
+ PlatformInput::KeyUp(_) => "key_up",
+ PlatformInput::ModifiersChanged(_) => "modifiers_changed",
+ PlatformInput::MouseDown(_) => "mouse_down",
+ PlatformInput::MouseUp(_) => "mouse_up",
+ PlatformInput::MousePressure(_) => "mouse_pressure",
+ PlatformInput::MouseMove(_) => "mouse_move",
+ PlatformInput::MouseExited(_) => "mouse_exited",
+ PlatformInput::ScrollWheel(_) => "scroll_wheel",
+ PlatformInput::Pinch(_) => "pinch",
+ PlatformInput::FileDrop(_) => "file_drop",
+ PlatformInput::Touch(_) => "touch",
+ }
+ }
+
/// Returns the touch event contained in this input, if any.
pub fn touch_event(&self) -> Option<&TouchEvent> {
match self {
diff --git a/crates/gpui/src/platform_scheduler.rs b/crates/gpui/src/platform_scheduler.rs
index a50b3920a72..311f452751d 100644
--- a/crates/gpui/src/platform_scheduler.rs
+++ b/crates/gpui/src/platform_scheduler.rs
@@ -28,6 +28,8 @@ pub struct PlatformScheduler {
dispatcher: Arc<dyn PlatformDispatcher>,
clock: Arc<PlatformClock>,
next_session_id: AtomicU16,
+ #[cfg(feature = "profiler")]
+ foreground_runnables: crate::profiler::journal::ForegroundRunnableCounter,
}
impl PlatformScheduler {
@@ -36,6 +38,8 @@ impl PlatformScheduler {
dispatcher: dispatcher.clone(),
clock: Arc::new(PlatformClock { dispatcher }),
next_session_id: AtomicU16::new(0),
+ #[cfg(feature = "profiler")]
+ foreground_runnables: crate::profiler::journal::foreground_runnable_counter(),
}
}
@@ -52,6 +56,13 @@ impl PlatformScheduler {
fn next_session_id(&self) -> SessionId {
SessionId::new(self.next_session_id.fetch_add(1, Ordering::SeqCst))
}
+
+ #[cfg(feature = "profiler")]
+ pub(crate) fn foreground_runnable_counter(
+ &self,
+ ) -> crate::profiler::journal::ForegroundRunnableCounter {
+ self.foreground_runnables.clone()
+ }
}
impl Scheduler for PlatformScheduler {
@@ -105,6 +116,8 @@ impl Scheduler for PlatformScheduler {
}
fn schedule_local(&self, _session_id: SessionId, runnable: Runnable<RunnableMeta>) {
+ #[cfg(feature = "profiler")]
+ self.foreground_runnables.queued();
self.dispatcher
.dispatch_on_main_thread(runnable, Priority::default());
}
diff --git a/crates/gpui/src/profiler.rs b/crates/gpui/src/profiler.rs
index 433db4ecf55..1c4f09adc34 100644
--- a/crates/gpui/src/profiler.rs
+++ b/crates/gpui/src/profiler.rs
@@ -17,6 +17,10 @@ use std::{
};
mod actions;
+#[cfg(feature = "profiler")]
+pub mod hang;
+#[cfg(feature = "profiler")]
+pub mod journal;
pub use actions::{ActionStatistics, ActionTiming, take_action_stats};
use serde::{Deserialize, Serialize};
@@ -587,7 +591,7 @@ impl ThreadTimings {
pub fn update_running_task(&mut self, _: SpawnTime, _: &'static std::panic::Location<'_>) {}
#[cfg(feature = "profiler")]
- pub fn save_task_timing(&mut self, ended: YieldTime) {
+ pub fn save_task_timing(&mut self, ended: YieldTime) -> TaskTiming {
let ActiveTiming {
location,
start,
@@ -614,6 +618,7 @@ impl ThreadTimings {
self.timings.push_back(timing);
self.total_pushed += 1;
}
+ timing
}
#[cfg(not(feature = "profiler"))]
pub fn save_task_timing(&mut self, _: YieldTime) {}
@@ -662,6 +667,8 @@ impl Drop for ThreadTimings {
#[doc(hidden)]
pub fn update_running_task(spawned: SpawnTime, location: &'static std::panic::Location<'_>) {
+ #[cfg(feature = "profiler")]
+ journal::begin_foreground_turn();
THREAD_TIMINGS.with(|timings| {
timings.lock().update_running_task(spawned, location);
});
@@ -670,6 +677,12 @@ pub fn update_running_task(spawned: SpawnTime, location: &'static std::panic::Lo
#[doc(hidden)]
pub fn save_task_timing() {
let yielded_at = YieldTime(Instant::now());
+ #[cfg(feature = "profiler")]
+ {
+ let timing = THREAD_TIMINGS.with(|timings| timings.lock().save_task_timing(yielded_at));
+ journal::record_task_poll(timing);
+ }
+ #[cfg(not(feature = "profiler"))]
THREAD_TIMINGS.with(|timings| {
timings.lock().save_task_timing(yielded_at);
});
@@ -801,19 +814,29 @@ impl FrameTiming {
}
}
-/// A newly drawn frame reaching the screen.
+/// Work spent submitting a window frame to the platform.
#[cfg(feature = "profiler")]
#[derive(Debug, Copy, Clone)]
pub struct PresentTiming {
- /// The window whose frame was presented.
+ /// The window whose frame was submitted.
pub window_id: WindowId,
- /// When the frame was presented.
- pub presented_at: Instant,
- /// The interval since the previous newly drawn frame was presented, when
+ /// When the platform submission began.
+ pub present_start: Instant,
+ /// When the platform submission completed.
+ pub present_end: Instant,
+ /// The interval since the previous newly drawn frame was submitted, when
/// both frames belong to an active animation.
pub animation_interval: Option<Duration>,
}
+#[cfg(feature = "profiler")]
+impl PresentTiming {
+ /// Time spent submitting the frame to the platform.
+ pub fn present_duration(&self) -> Duration {
+ self.present_end.duration_since(self.present_start)
+ }
+}
+
/// A frame event observed by the profiler.
#[cfg(feature = "profiler")]
#[derive(Debug, Copy, Clone)]
@@ -852,8 +875,13 @@ pub struct InputLatencySnapshot {
#[cfg(feature = "profiler")]
enum WindowActivity {
- Input { started_at: Instant },
- Draw { started_at: Instant },
+ Input {
+ started_at: Instant,
+ kind: &'static str,
+ },
+ Draw {
+ started_at: Instant,
+ },
}
/// Collects profiling information for one window.
@@ -865,6 +893,7 @@ enum WindowActivity {
pub struct WindowProfiler {
window_id: WindowId,
active_activities: SmallVec<[WindowActivity; 4]>,
+ active_actions: SmallVec<[(&'static str, Instant); 2]>,
draw_duration_histogram: Histogram<u64>,
present_interval_histogram: Histogram<u64>,
first_input_at: Option<Instant>,
@@ -874,16 +903,17 @@ pub struct WindowProfiler {
mid_draw_events_dropped: u64,
last_present_at: Option<Instant>,
animating_at_last_present: bool,
- drew_since_last_present: bool,
+ pending_frame: Option<FrameTiming>,
}
#[cfg(feature = "profiler")]
impl WindowProfiler {
/// Creates a profiler for a window.
pub fn new(window_id: WindowId) -> anyhow::Result<Self> {
- Ok(Self {
+ let profiler = Self {
window_id,
active_activities: SmallVec::new(),
+ active_actions: SmallVec::new(),
draw_duration_histogram: Histogram::new(3).map_err(|error| {
anyhow::anyhow!("Failed to create draw duration histogram: {error}")
})?,
@@ -901,24 +931,38 @@ impl WindowProfiler {
mid_draw_events_dropped: 0,
last_present_at: None,
animating_at_last_present: false,
- drew_since_last_present: false,
- })
+ pending_frame: None,
+ };
+ journal::record_frame_pending(window_id, Instant::now());
+ Ok(profiler)
}
- /// Records the beginning of an input dispatch.
- pub fn begin_input(&mut self) {
+ /// Records the beginning of an input dispatch. `kind` names the platform
+ /// input variant being dispatched (see [`crate::PlatformInput::kind_name`]).
+ pub fn begin_input(&mut self, kind: &'static str) {
+ journal::begin_foreground_turn();
self.active_activities.push(WindowActivity::Input {
started_at: Instant::now(),
+ kind,
});
}
/// Records the end of an input dispatch.
pub fn end_input(&mut self, caused_invalidation: bool) {
- let Some(WindowActivity::Input { started_at }) = self.active_activities.pop() else {
+ let Some(WindowActivity::Input { started_at, kind }) = self.active_activities.pop() else {
debug_assert!(false, "input activity must be the current window activity");
+ journal::end_foreground_turn();
return;
};
+ journal::record_input(journal::InputTiming {
+ kind,
+ start: started_at,
+ end: Instant::now(),
+ caused_invalidation,
+ });
+ journal::end_foreground_turn();
+
if !caused_invalidation {
return;
}
@@ -937,19 +981,37 @@ impl WindowProfiler {
/// Records the beginning of an action handler.
pub fn begin_action_handler(&mut self, action: &(dyn Action + 'static), cx: &mut App) {
- actions::update_running_action(action, cx);
+ journal::begin_foreground_turn();
+ let name = actions::update_running_action(action, cx);
+ self.active_actions.push((name, Instant::now()));
}
/// Records the end of the current action handler.
pub fn end_action_handler(&mut self) {
+ // Dual-write to the legacy aggregate store; its single global running
+ // slot misbehaves when tests run actions concurrently, which is why
+ // the journal entry is tracked here on the window instead.
actions::save_action_timing();
+ let Some((name, start)) = self.active_actions.pop() else {
+ debug_assert!(false, "action handler must be begun before it ends");
+ journal::end_foreground_turn();
+ return;
+ };
+ journal::record_action(ActionTiming {
+ name,
+ start,
+ end: Instant::now(),
+ });
+ journal::end_foreground_turn();
}
/// Records the beginning of a window draw.
pub fn begin_draw(&mut self) {
- self.active_activities.push(WindowActivity::Draw {
- started_at: Instant::now(),
- });
+ journal::begin_foreground_turn();
+ let started_at = Instant::now();
+ journal::record_frame_pending(self.window_id, started_at);
+ self.active_activities
+ .push(WindowActivity::Draw { started_at });
}
/// Records the end of a window draw and returns the draw duration.
@@ -959,20 +1021,21 @@ impl WindowProfiler {
}) = self.active_activities.pop()
else {
debug_assert!(false, "draw activity must be the current window activity");
+ journal::end_foreground_turn();
return Duration::ZERO;
};
- self.drew_since_last_present = true;
let draw_end = Instant::now();
- let draw_duration = draw_end.duration_since(draw_start);
- self.record_draw_duration(draw_duration);
- record_frame_event(FrameEvent::Draw(FrameTiming {
+ let frame_timing = FrameTiming {
window_id: self.window_id,
dirty_at,
invalidations,
draw_start,
draw_end,
- }));
+ };
+ let draw_duration = frame_timing.draw_duration();
+ self.record_draw_timing(frame_timing);
+ journal::end_foreground_turn();
draw_duration
}
@@ -980,8 +1043,19 @@ impl WindowProfiler {
///
/// `next_frame_scheduled` marks the animation state for the interval ending
/// at the next newly drawn frame's presentation.
- pub fn record_present(&mut self, window_active: bool, next_frame_scheduled: bool) {
- self.record_present_at(Instant::now(), window_active, next_frame_scheduled);
+ pub fn record_present(
+ &mut self,
+ present_start: Instant,
+ present_end: Instant,
+ window_active: bool,
+ next_frame_scheduled: bool,
+ ) {
+ self.record_present_at(
+ present_start,
+ present_end,
+ window_active,
+ next_frame_scheduled,
+ );
}
/// Returns a snapshot of the current input-latency histograms.
@@ -1003,12 +1077,13 @@ impl WindowProfiler {
fn record_present_at(
&mut self,
- presented_at: Instant,
+ present_start: Instant,
+ present_end: Instant,
window_active: bool,
next_frame_scheduled: bool,
) {
if let Some(first_input_at) = self.first_input_at.take() {
- let latency_nanos = presented_at.duration_since(first_input_at).as_nanos() as u64;
+ let latency_nanos = present_end.duration_since(first_input_at).as_nanos() as u64;
self.input_latency_histogram.record(latency_nanos).ok();
}
if self.pending_input_count > 0 {
@@ -1018,38 +1093,55 @@ impl WindowProfiler {
self.pending_input_count = 0;
}
- if !std::mem::take(&mut self.drew_since_last_present) {
+ let frame = self.pending_frame.take();
+ let animation_interval =
+ if frame.is_some() && self.animating_at_last_present && window_active {
+ self.last_present_at
+ .map(|last_present_at| present_end.duration_since(last_present_at))
+ } else {
+ None
+ };
+ let present_timing = PresentTiming {
+ window_id: self.window_id,
+ present_start,
+ present_end,
+ animation_interval,
+ };
+ journal::record_present(present_timing, frame);
+
+ if frame.is_none() {
return;
}
- let animation_interval = if self.animating_at_last_present && window_active {
- self.last_present_at
- .map(|last_present_at| presented_at.duration_since(last_present_at))
- } else {
- None
- };
-
if let Some(animation_interval) = animation_interval {
self.present_interval_histogram
.record(animation_interval.as_nanos() as u64)
.ok();
}
+ record_frame_event(FrameEvent::Present(present_timing));
- record_frame_event(FrameEvent::Present(PresentTiming {
- window_id: self.window_id,
- presented_at,
- animation_interval,
- }));
-
- self.last_present_at = Some(presented_at);
+ self.last_present_at = Some(present_end);
self.animating_at_last_present = next_frame_scheduled && window_active;
}
+ fn record_draw_timing(&mut self, timing: FrameTiming) {
+ self.record_draw_duration(timing.draw_duration());
+ self.pending_frame = Some(timing);
+ record_frame_event(FrameEvent::Draw(timing));
+ journal::record_draw(timing);
+ }
+
fn record_draw_duration(&mut self, duration: Duration) {
self.draw_duration_histogram
.record(duration.as_nanos() as u64)
.ok();
- self.drew_since_last_present = true;
+ }
+}
+
+#[cfg(feature = "profiler")]
+impl Drop for WindowProfiler {
+ fn drop(&mut self) {
+ journal::record_window_closed(self.window_id);
}
}
@@ -1180,11 +1272,16 @@ mod tests {
let start = Instant::now();
let mut collector = FrameTimingCollector::new();
- window_profiler.record_draw_duration(Duration::from_millis(2));
- window_profiler.record_present_at(start, true, true);
- window_profiler.record_draw_duration(Duration::from_millis(2));
- window_profiler.record_present_at(start + FRAME, true, true);
- window_profiler.record_present_at(start + FRAME + FRAME / 2, true, true);
+ record_test_draw(&mut window_profiler, start);
+ window_profiler.record_present_at(start, start, true, true);
+ record_test_draw(&mut window_profiler, start + FRAME);
+ window_profiler.record_present_at(start + FRAME, start + FRAME, true, true);
+ window_profiler.record_present_at(
+ start + FRAME + FRAME / 2,
+ start + FRAME + FRAME / 2,
+ true,
+ true,
+ );
let present_timings = collector
.collect_unseen()
@@ -1284,7 +1381,7 @@ mod tests {
let start = Instant::now();
draw_and_present(&mut window_profiler, start, true, true);
- window_profiler.record_present_at(start + FRAME / 2, true, true);
+ window_profiler.record_present_at(start + FRAME / 2, start + FRAME / 2, true, true);
draw_and_present(&mut window_profiler, start + FRAME, true, true);
assert_eq!(window_profiler.present_interval_histogram.len(), 1);
@@ -1339,8 +1436,8 @@ mod tests {
first_input_at + Duration::from_millis(2),
);
window_profiler.end_input(true);
- window_profiler.record_draw_duration(Duration::from_millis(2));
- window_profiler.record_present_at(presented_at, true, false);
+ record_test_draw(&mut window_profiler, presented_at);
+ window_profiler.record_present_at(presented_at, presented_at, true, false);
let snapshot = window_profiler.input_latency_snapshot();
assert_eq!(snapshot.latency_histogram.len(), 1);
@@ -1420,7 +1517,10 @@ mod tests {
fn begin_input_at(window_profiler: &mut WindowProfiler, started_at: Instant) {
window_profiler
.active_activities
- .push(WindowActivity::Input { started_at });
+ .push(WindowActivity::Input {
+ started_at,
+ kind: "test",
+ });
}
#[cfg(feature = "profiler")]
@@ -1430,7 +1530,22 @@ mod tests {
window_active: bool,
next_frame_scheduled: bool,
) {
- window_profiler.record_draw_duration(Duration::from_millis(2));
- window_profiler.record_present_at(presented_at, window_active, next_frame_scheduled);
+ record_test_draw(window_profiler, presented_at);
+ window_profiler.record_present_at(
+ presented_at,
+ presented_at,
+ window_active,
+ next_frame_scheduled,
+ );
+ }
+
+ fn record_test_draw(window_profiler: &mut WindowProfiler, draw_end: Instant) {
+ window_profiler.record_draw_timing(FrameTiming {
+ window_id: window_profiler.window_id,
+ dirty_at: Some(draw_end - Duration::from_millis(4)),
+ invalidations: 1,
+ draw_start: draw_end - Duration::from_millis(2),
+ draw_end,
+ });
}
}
diff --git a/crates/gpui/src/profiler/actions.rs b/crates/gpui/src/profiler/actions.rs
index efa9b756db6..be82af22bc7 100644
--- a/crates/gpui/src/profiler/actions.rs
+++ b/crates/gpui/src/profiler/actions.rs
@@ -95,6 +95,12 @@ impl ActionStatistics {
return;
};
+ let timing = ActionTiming {
+ name: action,
+ start: started,
+ end: now,
+ };
+
let runtime = now.duration_since(started);
if runtime >= self.runtime_to_beat {
std::hint::cold_path(); // most actions are not the worst, optimize for that
@@ -105,18 +111,10 @@ impl ActionStatistics {
.iter_mut()
.min_by_key(|action| runtime >= action.runtime())
{
- *to_replace = ActionTiming {
- name: action,
- start: started,
- end: now,
- };
+ *to_replace = timing;
} else {
self.longest_runtimes
- .push(ActionTiming {
- name: action,
- start: started,
- end: now,
- })
+ .push(timing)
.expect("just checked it is not full");
};
@@ -184,11 +182,15 @@ static ACTION_STATISTICS: spin::Mutex<ActionStatistics> =
#[doc(hidden)]
#[cfg(feature = "profiler")]
-pub(crate) fn update_running_action(action: &(dyn Action + 'static), cx: &mut crate::App) {
+pub(crate) fn update_running_action(
+ action: &(dyn Action + 'static),
+ cx: &mut crate::App,
+) -> &'static str {
let now = Instant::now();
let action = action.type_id();
let action = cx.actions.try_resolve_action(&action).unwrap_or("un-named");
ACTION_STATISTICS.lock().update_running_action(action, now);
+ action
}
#[doc(hidden)]
diff --git a/crates/gpui/src/profiler/hang.rs b/crates/gpui/src/profiler/hang.rs
new file mode 100644
index 00000000000..95149312253
--- /dev/null
+++ b/crates/gpui/src/profiler/hang.rs
@@ -0,0 +1,1268 @@
+//! Post-hoc detection of foreground hangs from the journal's event stream.
+//!
+//! A hang is any single piece of foreground work — a task poll, an action
+//! handler, an input dispatch, a window draw, or platform presentation — that
+//! blocked the foreground thread for at least a threshold duration. An
+//! interval whose total foreground spend reached the frame budget also
+//! counts, even when no single event crossed the threshold: many small
+//! pieces of work can drop a frame — or starve a headless app — as
+//! thoroughly as one long stall. [`HangDetector`] drains the journal and
+//! reports each completed activity interval containing hangs as a
+//! [`HangIncident`].
+
+use std::time::Duration;
+
+use scheduler::Instant;
+use serde::Serialize;
+
+use super::SerializedLocation;
+use super::journal::{
+ ForegroundEvent, ForegroundJournal, ForegroundJournalCollector, ForegroundJournalEntry,
+ FrameSnapshot, IntervalBoundary, IntervalSealer,
+};
+
+/// Detects foreground hangs by polling the journal.
+///
+/// Detection is post-hoc: a hang is reported once an explicit presentation
+/// or foreground-idle boundary completes its interval. Work that never
+/// yields back to the foreground is not observed until it does.
+pub struct HangDetector {
+ collector: ForegroundJournalCollector,
+ sealer: IntervalSealer,
+ threshold: Duration,
+ frame_budget: Duration,
+ first_present_at: Option<Instant>,
+}
+
+/// One sealed interval that contained at least one hang.
+#[derive(Debug, Clone)]
+pub struct HangIncident {
+ /// The interval the hangs occurred in, including all non-hang foreground
+ /// work recorded alongside them.
+ pub snapshot: FrameSnapshot,
+ /// The events that blocked the foreground for at least the detector's
+ /// threshold, longest first. When the incident was triggered by the
+ /// frame budget alone, no event crossed the threshold and this instead
+ /// holds every event in the interval, longest first.
+ pub contributors: Vec<ForegroundEvent>,
+}
+
+impl HangDetector {
+ /// Creates a detector reporting single events at or above `threshold`
+ /// and intervals whose total foreground spend reached `frame_budget`.
+ /// Only events recorded from this point on are observed.
+ pub fn new(journal: ForegroundJournal, threshold: Duration, frame_budget: Duration) -> Self {
+ Self {
+ collector: journal.collector(),
+ sealer: IntervalSealer::new(Instant::now()),
+ threshold,
+ frame_budget,
+ first_present_at: None,
+ }
+ }
+
+ /// When the first newly drawn frame observed by this detector finished
+ /// platform submission. `None` until a presentation boundary is observed.
+ pub fn first_present_at(&self) -> Option<Instant> {
+ self.first_present_at
+ }
+
+ /// Drains newly recorded events and returns the incidents sealed since
+ /// the previous poll.
+ pub fn poll(&mut self) -> Vec<HangIncident> {
+ let drained = self.collector.collect_unseen();
+ if self.first_present_at.is_none() {
+ self.first_present_at = drained.entries.iter().find_map(|entry| match entry {
+ ForegroundJournalEntry::Boundary(IntervalBoundary::Presented(presented)) => {
+ Some(presented.presentation.present_end)
+ }
+ _ => None,
+ });
+ }
+ self.sealer
+ .push_entries(drained.entries)
+ .into_iter()
+ .filter_map(|snapshot| {
+ HangIncident::detect(snapshot, self.threshold, self.frame_budget)
+ })
+ .collect()
+ }
+}
+
+/// A [`HangIncident`] in a telemetry-friendly form: timestamps and durations
+/// in fractional milliseconds since app startup (microsecond precision),
+/// locations as plain data, contributor count capped by the converter.
+#[derive(Debug, Clone, Serialize)]
+pub struct SerializedHangIncident {
+ /// `"startup"` when the active window began before the first observed
+ /// newly drawn frame finished platform submission (see
+ /// [`HangDetector::first_present_at`]), otherwise `"steady"`.
+ pub phase: &'static str,
+ /// When the incident's active window started, in milliseconds since app
+ /// startup: the sealing frame's first invalidation, or the earliest
+ /// contributor's start when nothing was pending a repaint. Foreground
+ /// idle time between the previous frame and the cause is excluded.
+ pub start_ms: f64,
+ /// Length of the active window in milliseconds: from the cause to the
+ /// seal. Exceeds `stall_ms` when several stalls piled up on one frame.
+ pub active_ms: f64,
+ /// The longest single block of foreground work, in milliseconds: the
+ /// best estimate of the freeze a user perceived. Below the hang
+ /// threshold (possibly zero) when the frame budget alone triggered the
+ /// incident.
+ pub stall_ms: f64,
+ /// For presentation-sealed incidents, how long the submitted frame had
+ /// been dirty, in milliseconds.
+ pub dirty_to_present_ms: Option<f64>,
+ /// What closed the incident: `"present"` or `"idle"`. This labels the
+ /// boundary, not the hang's cause — the cause is the first contributor.
+ pub sealed_by: &'static str,
+ /// Fraction of the active window the foreground spent working,
+ /// `0.0..=1.0`. Low values with a high `dirty_to_present_ms` indicate
+ /// throttling or scheduling delay rather than application work.
+ pub busy_fraction: f64,
+ /// Total events recorded in the interval (before the contributor cap).
+ pub event_count: usize,
+ /// Count of task polls below the journal's floor.
+ pub small_poll_count: u64,
+ /// Total duration of task polls below the journal's floor, in milliseconds.
+ pub small_poll_total_ms: f64,
+ /// Events lost to caps or ring overwrites.
+ pub dropped_events: u64,
+ /// Whether one or more journal entries were unavailable in the interval.
+ /// Threshold-qualified contributors remain valid, but cumulative budget
+ /// conclusions and boundary attribution are not trusted across the gap.
+ pub journal_discontinuous: bool,
+ /// The incident's contributors (see [`HangIncident::contributors`]) in
+ /// start order. The cap keeps the longest ones; `stall_ms` is always
+ /// among them.
+ pub contributors: Vec<SerializedHangContributor>,
+ /// Contributors elided by the cap.
+ pub contributors_elided: usize,
+}
+
+/// One hang contributor in serialized form.
+///
+/// Foreground work nests: an input dispatch can synchronously draw a window,
+/// a draw can poll a task. `depth` expresses that containment — a depth-1
+/// event's time is already inside some depth-0 event's duration, so summing
+/// sibling durations across depths double-counts.
+#[derive(Debug, Clone, Serialize)]
+#[serde(tag = "kind", rename_all = "snake_case")]
+pub enum SerializedHangContributor {
+ /// A foreground task poll.
+ TaskPoll {
+ /// Where the task was spawned.
+ location: SerializedLocation,
+ /// When the poll started, in milliseconds since app startup.
+ start_ms: f64,
+ /// How long the poll blocked the foreground, in milliseconds.
+ duration_ms: f64,
+ /// How many other events in the interval contain this one.
+ depth: usize,
+ },
+ /// An action handler.
+ Action {
+ /// The action's name.
+ name: &'static str,
+ /// When the handler started, in milliseconds since app startup.
+ start_ms: f64,
+ /// How long the handler ran, in milliseconds.
+ duration_ms: f64,
+ /// How many other events in the interval contain this one.
+ depth: usize,
+ },
+ /// A platform input dispatch.
+ Input {
+ /// The platform input variant dispatched, e.g. `"key_down"`.
+ /// Named `input_kind` because `kind` is this enum's serde tag.
+ input_kind: &'static str,
+ /// When the dispatch started, in milliseconds since app startup.
+ start_ms: f64,
+ /// How long the dispatch ran, in milliseconds.
+ duration_ms: f64,
+ /// Whether handling the input invalidated a window.
+ caused_invalidation: bool,
+ /// How many other events in the interval contain this one.
+ depth: usize,
+ },
+ /// A window draw.
+ Draw {
+ /// The window that was drawn.
+ window_id: u64,
+ /// When the draw started, in milliseconds since app startup.
+ start_ms: f64,
+ /// How long the draw took, in milliseconds.
+ duration_ms: f64,
+ /// Time from the frame's first invalidation to the end of its draw,
+ /// in milliseconds.
+ dirty_to_draw_ms: Option<f64>,
+ /// Invalidations coalesced into the frame.
+ invalidations: u64,
+ /// How many other events in the interval contain this one.
+ depth: usize,
+ },
+ /// Work spent submitting a frame to the platform.
+ Present {
+ /// The window whose frame was submitted.
+ window_id: u64,
+ /// When submission began, in milliseconds since app startup.
+ start_ms: f64,
+ /// How long platform submission took, in milliseconds.
+ duration_ms: f64,
+ /// How many other events in the interval contain this one.
+ depth: usize,
+ },
+}
+
+/// Milliseconds with microsecond precision: keeps `dbg!`/JSON output short
+/// (`115.954` rather than `115.95400000000001` or `115954`).
+fn as_millis(duration: Duration) -> f64 {
+ duration.as_micros() as f64 / 1000.0
+}
+
+impl SerializedHangIncident {
+ /// Converts an incident, keeping at most `max_contributors` contributors.
+ /// `first_present_at` is the end of the first observed newly drawn frame's
+ /// platform submission (typically [`HangDetector::first_present_at`]);
+ /// incidents whose active window begins before it are tagged `"startup"`.
+ pub fn convert(
+ startup: Instant,
+ incident: &HangIncident,
+ max_contributors: usize,
+ first_present_at: Option<Instant>,
+ ) -> Self {
+ let since_startup =
+ |instant: Instant| as_millis(instant.saturating_duration_since(startup));
+ let snapshot = &incident.snapshot;
+ let (active_start, active_end) = incident.active_window();
+ let active = active_end.duration_since(active_start);
+ let busy_fraction = if active.is_zero() {
+ 1.0
+ } else {
+ snapshot
+ .occupancy_within(active_start, active_end)
+ .div_duration_f64(active)
+ .min(1.0)
+ };
+ Self {
+ phase: match first_present_at {
+ Some(first_present_at) if active_start >= first_present_at => "steady",
+ _ => "startup",
+ },
+ start_ms: since_startup(active_start),
+ active_ms: as_millis(active),
+ stall_ms: incident
+ .contributors
+ .first()
+ .map(|event| as_millis(event.duration()))
+ .unwrap_or(0.0),
+ dirty_to_present_ms: match snapshot.boundary {
+ IntervalBoundary::Presented(presented) => {
+ presented.dirty_to_present_duration().map(as_millis)
+ }
+ IntervalBoundary::Idle { .. } => None,
+ },
+ sealed_by: match snapshot.boundary {
+ IntervalBoundary::Presented(_) => "present",
+ IntervalBoundary::Idle { .. } => "idle",
+ },
+ busy_fraction: (busy_fraction * 1000.0).round() / 1000.0,
+ event_count: snapshot.events.len(),
+ small_poll_count: snapshot.small_poll_summary().count,
+ small_poll_total_ms: as_millis(snapshot.small_poll_summary().total),
+ dropped_events: snapshot.dropped_events,
+ journal_discontinuous: snapshot.journal_discontinuous,
+ contributors: {
+ let mut kept: Vec<&ForegroundEvent> = incident
+ .contributors
+ .iter()
+ .take(max_contributors)
+ .collect();
+ kept.sort_by_key(|event| event.start_time());
+ kept.into_iter()
+ .map(|event| {
+ SerializedHangContributor::convert(
+ startup,
+ event,
+ nesting_depth(event, &snapshot.events),
+ )
+ })
+ .collect()
+ },
+ contributors_elided: incident.contributors.len().saturating_sub(max_contributors),
+ }
+ }
+}
+
+/// How many events in `events` strictly contain `event`'s span. Events with
+/// identical spans don't count as containing each other, so `event`'s own
+/// presence in `events` contributes nothing.
+fn nesting_depth(event: &ForegroundEvent, events: &[ForegroundEvent]) -> usize {
+ let (start, end) = (event.start_time(), event.end_time());
+ events
+ .iter()
+ .filter(|other| {
+ let (other_start, other_end) = (other.start_time(), other.end_time());
+ other_start <= start && end <= other_end && (other_start < start || end < other_end)
+ })
+ .count()
+}
+
+impl SerializedHangContributor {
+ fn convert(startup: Instant, event: &ForegroundEvent, depth: usize) -> Self {
+ let since_startup =
+ |instant: Instant| as_millis(instant.saturating_duration_since(startup));
+ let duration_ms = as_millis(event.duration());
+ match event {
+ ForegroundEvent::TaskPoll(timing) => Self::TaskPoll {
+ location: timing.location.into(),
+ start_ms: since_startup(timing.start),
+ duration_ms,
+ depth,
+ },
+ ForegroundEvent::Action(timing) => Self::Action {
+ name: timing.name,
+ start_ms: since_startup(timing.start),
+ duration_ms,
+ depth,
+ },
+ ForegroundEvent::Input(timing) => Self::Input {
+ input_kind: timing.kind,
+ start_ms: since_startup(timing.start),
+ duration_ms,
+ caused_invalidation: timing.caused_invalidation,
+ depth,
+ },
+ ForegroundEvent::Draw(timing) => Self::Draw {
+ window_id: timing.window_id.as_u64(),
+ start_ms: since_startup(timing.draw_start),
+ duration_ms,
+ dirty_to_draw_ms: timing.dirty_to_draw_duration().map(as_millis),
+ invalidations: timing.invalidations,
+ depth,
+ },
+ ForegroundEvent::Present(timing) => Self::Present {
+ window_id: timing.window_id.as_u64(),
+ start_ms: since_startup(timing.present_start),
+ duration_ms,
+ depth,
+ },
+ ForegroundEvent::SmallPolls(flush) => {
+ // The sealer folds these out of snapshot events; a contributor
+ // can therefore never be one, but serialize defensively as an
+ // unnamed poll spanning the flush rather than panicking.
+ Self::TaskPoll {
+ location: SerializedLocation {
+ file: "<small poll summary>".into(),
+ line: 0,
+ column: 0,
+ },
+ start_ms: since_startup(flush.since),
+ duration_ms,
+ depth,
+ }
+ }
+ }
+ }
+}
+
+impl HangIncident {
+ /// The incident's reporting window: from its earliest cause — the
+ /// sealing frame's first invalidation, or the earliest contributor's
+ /// start when no repaint was pending — to the seal. This trims
+ /// foreground-idle time between the previous frame and the cause, and
+ /// may begin before the underlying snapshot when a contributor was
+ /// already running at the previous seal.
+ pub fn active_window(&self) -> (Instant, Instant) {
+ let snapshot = &self.snapshot;
+ let dirty_at = snapshot.boundary.dirty_at();
+ let earliest_contributor = self
+ .contributors
+ .iter()
+ .map(|event| event.start_time())
+ .min();
+ let start = [dirty_at, earliest_contributor]
+ .into_iter()
+ .flatten()
+ .min()
+ .unwrap_or(snapshot.interval_start);
+ (start, snapshot.interval_end())
+ }
+
+ /// Returns an incident when the snapshot contains at least one event
+ /// that blocked the foreground for `threshold` or longer, or when the
+ /// interval's total foreground spend — event time plus folded
+ /// small-poll time — reached `frame_budget` even though no single event
+ /// did. In the latter case every event in the interval becomes a
+ /// contributor, since no single stall explains the busy interval.
+ pub fn detect(
+ snapshot: FrameSnapshot,
+ threshold: Duration,
+ frame_budget: Duration,
+ ) -> Option<Self> {
+ let mut contributors: Vec<ForegroundEvent> = snapshot
+ .events
+ .iter()
+ .filter(|event| event.duration() >= threshold)
+ .copied()
+ .collect();
+ if contributors.is_empty() {
+ if snapshot.journal_discontinuous {
+ return None;
+ }
+ let spend = snapshot.occupancy_within(snapshot.interval_start, snapshot.interval_end());
+ if spend < frame_budget {
+ return None;
+ }
+ contributors = snapshot.events.clone();
+ }
+ contributors.sort_by_key(|event| std::cmp::Reverse(event.duration()));
+ Some(Self {
+ snapshot,
+ contributors,
+ })
+ }
+}
+
+#[cfg(test)]
+mod tests {
+ use std::cell::Cell;
+ use std::rc::Rc;
+ use std::thread;
+ use std::time::Duration;
+
+ use proptest::prelude::*;
+ use rand::prelude::*;
+ use scheduler::SpawnTime;
+
+ use crate::{
+ self as gpui, Context, FocusHandle, InteractiveElement, IntoElement, Modifiers,
+ MouseButton, Render, Styled, TestAppContext, VisualTestContext, Window, WindowId, div,
+ point, px,
+ };
+
+ use crate::profiler::{ActionTiming, FrameTiming, PresentTiming, TaskTiming, YieldTime};
+
+ use super::super::journal::{
+ FRAME_DEADLINE, ForegroundEvent, ForegroundJournalEntry, FrameSnapshot, FrameStateChange,
+ InputTiming, IntervalBoundary, PollSummary, PresentedFrame, SmallPollFlush,
+ install_test_foreground_journal, record_present,
+ };
+ use super::{HangDetector, HangIncident, SerializedHangContributor, SerializedHangIncident};
+
+ actions!(hang_test, [HangyAction]);
+
+ // Well above legitimate per-event work in a test app (layout of one div,
+ // empty polls), well below the injected hangs.
+ const HANG_THRESHOLD: Duration = Duration::from_millis(10);
+ // Equal to the threshold, mirroring how production wires the detector
+ // today.
+ const FRAME_BUDGET: Duration = HANG_THRESHOLD;
+
+ /// A hang that outlives the frame deadline stays in one incident with
+ /// the frame it starved: the deadline only unblocks idle boundaries, so
+ /// the eventual presentation seals the hang together with its
+ /// dirty-to-present association.
+ #[test]
+ fn a_hang_outliving_the_frame_deadline_keeps_its_frame_association() {
+ let start = scheduler::Instant::now();
+ let window_id = WindowId::from(0x51E17);
+ let hang_end = start + FRAME_DEADLINE * 5;
+ let presented_at = hang_end + Duration::from_millis(16);
+ let (journal, _journal_guard) = install_test_foreground_journal(64, 8);
+ let mut detector = HangDetector::new(journal, HANG_THRESHOLD, FRAME_BUDGET);
+
+ let snapshots = detector.sealer.push_entries([
+ ForegroundJournalEntry::FrameState(FrameStateChange::Pending {
+ window_id,
+ dirty_at: start,
+ }),
+ ForegroundJournalEntry::Event(task_poll_event(start, hang_end)),
+ ]);
+ assert!(snapshots.is_empty(), "nothing seals mid-hang");
+
+ let snapshots = detector
+ .sealer
+ .push_entries([ForegroundJournalEntry::Boundary(
+ IntervalBoundary::Presented(PresentedFrame {
+ frame: frame(window_id, presented_at),
+ presentation: PresentTiming {
+ window_id,
+ present_start: presented_at - Duration::from_millis(1),
+ present_end: presented_at,
+ animation_interval: None,
+ },
+ }),
+ )]);
+ let [snapshot] = snapshots.as_slice() else {
+ panic!("expected one presented snapshot, got {snapshots:?}");
+ };
+ let incident = HangIncident::detect(snapshot.clone(), HANG_THRESHOLD, FRAME_BUDGET)
+ .expect("the hang qualifies");
+ assert!(matches!(
+ incident.contributors[0],
+ ForegroundEvent::TaskPoll(timing) if timing.end.0 == hang_end
+ ));
+ assert!(matches!(
+ incident.snapshot.boundary,
+ IntervalBoundary::Presented(_)
+ ));
+ }
+
+ #[test]
+ fn serialized_incident_reports_presented_seal_fields() {
+ let startup = scheduler::Instant::now();
+ let at = |ms: u64| startup + Duration::from_millis(ms);
+ let window_id = WindowId::from(0xF1E1D);
+
+ let presentation = PresentTiming {
+ window_id,
+ present_start: at(380),
+ present_end: at(400),
+ animation_interval: None,
+ };
+ let frame = FrameTiming {
+ window_id,
+ dirty_at: Some(at(100)),
+ invalidations: 3,
+ draw_start: at(350),
+ draw_end: at(380),
+ };
+ let snapshot = FrameSnapshot {
+ interval_start: at(150),
+ boundary: IntervalBoundary::Presented(PresentedFrame {
+ frame,
+ presentation,
+ }),
+ events: vec![
+ task_poll_event(at(150), at(300)),
+ ForegroundEvent::Action(ActionTiming {
+ name: "test::SlowAction",
+ start: at(300),
+ end: at(340),
+ }),
+ ForegroundEvent::Input(InputTiming {
+ kind: "test",
+ start: at(340),
+ end: at(345),
+ caused_invalidation: false,
+ }),
+ ForegroundEvent::Present(presentation),
+ ],
+ small_polls: vec![SmallPollFlush {
+ summary: PollSummary {
+ count: 2,
+ total: Duration::from_millis(1),
+ },
+ since: at(105),
+ until: at(145),
+ }],
+ dropped_events: 0,
+ journal_discontinuous: false,
+ };
+
+ let incident =
+ HangIncident::detect(snapshot, HANG_THRESHOLD, FRAME_BUDGET).expect("has contributors");
+ let serialized = SerializedHangIncident::convert(startup, &incident, 1, Some(at(50)));
+
+ assert_eq!(serialized.phase, "steady");
+ // The frame's first invalidation anchors the active window, not the
+ // interval start or the first contributor.
+ assert_eq!(serialized.start_ms, 100.0);
+ assert_eq!(serialized.active_ms, 300.0);
+ assert_eq!(serialized.stall_ms, 150.0);
+ assert_eq!(serialized.dirty_to_present_ms, Some(300.0));
+ assert_eq!(serialized.sealed_by, "present");
+ // Occupancy: poll 150ms + action 40ms + input 5ms + present 20ms +
+ // folded polls 1ms = 216ms of the 300ms window.
+ assert_eq!(serialized.busy_fraction, 0.72);
+ assert_eq!(serialized.event_count, 4);
+ assert_eq!(serialized.small_poll_count, 2);
+ assert_eq!(serialized.small_poll_total_ms, 1.0);
+ assert_eq!(serialized.dropped_events, 0);
+ // Three contributors qualify (poll, action, present); the cap keeps
+ // the longest and counts the rest.
+ assert_eq!(serialized.contributors.len(), 1);
+ assert_eq!(serialized.contributors_elided, 2);
+ assert!(matches!(
+ serialized.contributors[0],
+ SerializedHangContributor::TaskPoll {
+ start_ms,
+ duration_ms,
+ ..
+ } if start_ms == 150.0 && duration_ms == 150.0
+ ));
+ }
+
+ #[test]
+ fn serialized_incident_reports_idle_seal_fields() {
+ let startup = scheduler::Instant::now();
+ let at = |ms: u64| startup + Duration::from_millis(ms);
+
+ let idle = FrameSnapshot {
+ interval_start: at(200),
+ boundary: IntervalBoundary::Idle { ended_at: at(260) },
+ events: vec![task_poll_event(at(200), at(260))],
+ small_polls: Vec::new(),
+ dropped_events: 0,
+ journal_discontinuous: false,
+ };
+ let incident =
+ HangIncident::detect(idle, HANG_THRESHOLD, FRAME_BUDGET).expect("has contributors");
+ let serialized = SerializedHangIncident::convert(startup, &incident, 8, None);
+ assert_eq!(serialized.phase, "startup");
+ assert_eq!(serialized.sealed_by, "idle");
+ assert_eq!(serialized.dirty_to_present_ms, None);
+ // With no frame, the earliest contributor anchors the active window.
+ assert_eq!(serialized.start_ms, 200.0);
+ assert_eq!(serialized.active_ms, 60.0);
+ assert_eq!(serialized.stall_ms, 60.0);
+ assert_eq!(serialized.busy_fraction, 1.0);
+ }
+
+ #[test]
+ fn phase_is_startup_until_the_first_present() {
+ let startup = scheduler::Instant::now();
+ let at = |ms: u64| startup + Duration::from_millis(ms);
+ let snapshot = FrameSnapshot {
+ interval_start: at(500),
+ boundary: IntervalBoundary::Idle { ended_at: at(600) },
+ events: vec![task_poll_event(at(500), at(600))],
+ small_polls: Vec::new(),
+ dropped_events: 0,
+ journal_discontinuous: false,
+ };
+ let incident =
+ HangIncident::detect(snapshot, HANG_THRESHOLD, FRAME_BUDGET).expect("has contributors");
+
+ let phase = |first_present_at| {
+ SerializedHangIncident::convert(startup, &incident, 8, first_present_at).phase
+ };
+ assert_eq!(phase(None), "startup", "nothing has been presented yet");
+ assert_eq!(
+ phase(Some(at(700))),
+ "startup",
+ "the incident began before the first presentation"
+ );
+ assert_eq!(
+ phase(Some(at(500))),
+ "steady",
+ "an incident beginning exactly at first presentation is steady"
+ );
+ assert_eq!(phase(Some(at(100))), "steady");
+ }
+
+ /// The detector must latch the first presentation it observes and never
+ /// move it.
+ #[test]
+ fn first_present_at_latches_on_the_first_observed_presentation() {
+ let (journal, _journal_guard) = install_test_foreground_journal(64, 8);
+ let mut detector = HangDetector::new(journal, HANG_THRESHOLD, FRAME_BUDGET);
+ let window_id = WindowId::from(0x1A7C4);
+
+ let first_present_end = scheduler::Instant::now();
+ record_present(
+ presentation(window_id, first_present_end),
+ Some(frame(window_id, first_present_end)),
+ );
+ detector.poll();
+ let latched = detector
+ .first_present_at()
+ .expect("a presentation was recorded");
+ assert_eq!(latched, first_present_end);
+
+ record_present(
+ presentation(window_id, first_present_end + Duration::from_millis(16)),
+ Some(frame(
+ window_id,
+ first_present_end + Duration::from_millis(16),
+ )),
+ );
+ detector.poll();
+ assert_eq!(detector.first_present_at(), Some(latched));
+ }
+
+ /// The only work inside the 100ms active window here is the 50ms poll,
+ /// so the busy fraction is 0.5: the folded polls' flush span lies
+ /// entirely before the window and must contribute nothing to it
+ /// (PR #62779 review finding 5).
+ #[test]
+ fn busy_fraction_excludes_small_polls_outside_the_active_window() {
+ let startup = scheduler::Instant::now();
+ let at = |ms: u64| startup + Duration::from_millis(ms);
+ let snapshot = FrameSnapshot {
+ interval_start: at(0),
+ boundary: IntervalBoundary::Idle { ended_at: at(1000) },
+ events: vec![task_poll_event(at(900), at(950))],
+ // Folded polls that ran during at(0)..at(800), long before the
+ // active window opens at the contributor's start.
+ small_polls: vec![SmallPollFlush {
+ summary: PollSummary {
+ count: 500,
+ total: Duration::from_millis(400),
+ },
+ since: at(0),
+ until: at(800),
+ }],
+ dropped_events: 0,
+ journal_discontinuous: false,
+ };
+
+ let incident =
+ HangIncident::detect(snapshot, HANG_THRESHOLD, FRAME_BUDGET).expect("has contributors");
+ let serialized = SerializedHangIncident::convert(startup, &incident, 8, None);
+
+ assert_eq!(serialized.busy_fraction, 0.5);
+ }
+
+ /// Many sub-threshold pieces of work can drop a frame as thoroughly as
+ /// one long stall: an interval whose total foreground spend reaches the
+ /// budget is an incident even when no single event crosses the hang
+ /// threshold, and every event becomes a contributor so the report shows
+ /// what filled the interval.
+ #[test]
+ fn an_interval_of_small_work_over_budget_is_an_incident() {
+ let startup = scheduler::Instant::now();
+ let at = |ms: u64| startup + Duration::from_millis(ms);
+ let window_id = WindowId::from(0xB0D6E7);
+ let snapshot = FrameSnapshot {
+ interval_start: at(0),
+ boundary: IntervalBoundary::Presented(PresentedFrame {
+ frame: FrameTiming {
+ window_id,
+ dirty_at: Some(at(0)),
+ invalidations: 1,
+ draw_start: at(140),
+ draw_end: at(145),
+ },
+ presentation: PresentTiming {
+ window_id,
+ present_start: at(145),
+ present_end: at(150),
+ animation_interval: None,
+ },
+ }),
+ events: vec![
+ task_poll_event(at(0), at(5)),
+ task_poll_event(at(5), at(13)),
+ task_poll_event(at(13), at(18)),
+ ],
+ small_polls: Vec::new(),
+ dropped_events: 0,
+ journal_discontinuous: false,
+ };
+
+ let incident = HangIncident::detect(snapshot, HANG_THRESHOLD, FRAME_BUDGET)
+ .expect("foreground spend exceeded the frame budget");
+ assert_eq!(incident.contributors.len(), 3);
+ assert_eq!(
+ incident.contributors[0].duration(),
+ Duration::from_millis(8)
+ );
+ let serialized = SerializedHangIncident::convert(startup, &incident, 8, Some(startup));
+ assert_eq!(serialized.stall_ms, 8.0);
+ assert_eq!(serialized.dirty_to_present_ms, Some(150.0));
+ assert_eq!(serialized.sealed_by, "present");
+ }
+
+ #[test]
+ fn a_journal_gap_suppresses_budget_inference_but_retains_observed_hangs() {
+ let start = scheduler::Instant::now();
+ let at = |ms: u64| start + Duration::from_millis(ms);
+ let mut sealer = super::super::journal::IntervalSealer::new(start);
+ let snapshots = sealer.push_entries([
+ ForegroundJournalEntry::Event(task_poll_event(at(0), at(5))),
+ ForegroundJournalEntry::Discontinuity { lost: 1 },
+ ForegroundJournalEntry::Event(task_poll_event(at(10), at(15))),
+ ForegroundJournalEntry::Boundary(IntervalBoundary::Idle { ended_at: at(15) }),
+ ForegroundJournalEntry::Discontinuity { lost: 1 },
+ ForegroundJournalEntry::Event(task_poll_event(at(20), at(32))),
+ ForegroundJournalEntry::Boundary(IntervalBoundary::Idle { ended_at: at(32) }),
+ ForegroundJournalEntry::Event(task_poll_event(at(40), at(52))),
+ ForegroundJournalEntry::Boundary(IntervalBoundary::Idle { ended_at: at(52) }),
+ ]);
+ let [budget_only, observed_hang, clean] = snapshots.as_slice() else {
+ panic!("expected two discontinuous snapshots followed by a clean one");
+ };
+
+ assert!(budget_only.journal_discontinuous);
+ assert_eq!(budget_only.dropped_events, 1);
+ assert!(HangIncident::detect(budget_only.clone(), HANG_THRESHOLD, FRAME_BUDGET).is_none());
+
+ let observed_hang =
+ HangIncident::detect(observed_hang.clone(), HANG_THRESHOLD, FRAME_BUDGET)
+ .expect("the directly observed threshold-qualified hang remains valid");
+ assert!(observed_hang.snapshot.journal_discontinuous);
+ assert_eq!(observed_hang.contributors.len(), 1);
+ let serialized = SerializedHangIncident::convert(start, &observed_hang, 8, None);
+ assert!(serialized.journal_discontinuous);
+
+ assert!(!clean.journal_discontinuous);
+ assert!(HangIncident::detect(clean.clone(), HANG_THRESHOLD, FRAME_BUDGET).is_some());
+ }
+
+ /// A frame that reaches the screen late with almost no foreground work
+ /// behind it — pure scheduling or presentation delay — is not a hang:
+ /// the budget measures foreground spend, not dirty-to-present time.
+ #[test]
+ fn a_slow_frame_with_little_foreground_spend_is_not_an_incident() {
+ let startup = scheduler::Instant::now();
+ let at = |ms: u64| startup + Duration::from_millis(ms);
+ let window_id = WindowId::from(0xFA57);
+ let snapshot = FrameSnapshot {
+ interval_start: at(0),
+ boundary: IntervalBoundary::Presented(PresentedFrame {
+ frame: FrameTiming {
+ window_id,
+ dirty_at: Some(at(0)),
+ invalidations: 1,
+ draw_start: at(145),
+ draw_end: at(147),
+ },
+ presentation: PresentTiming {
+ window_id,
+ present_start: at(149),
+ present_end: at(150),
+ animation_interval: None,
+ },
+ }),
+ events: vec![task_poll_event(at(0), at(5))],
+ small_polls: Vec::new(),
+ dropped_events: 0,
+ journal_discontinuous: false,
+ };
+
+ assert!(HangIncident::detect(snapshot, HANG_THRESHOLD, FRAME_BUDGET).is_none());
+ }
+
+ /// The budget applies to idle-sealed intervals too: a headless app (or
+ /// a stretch with no repaint pending) can still starve the foreground
+ /// with accumulated sub-threshold work.
+ #[test]
+ fn an_idle_sealed_interval_over_budget_is_an_incident() {
+ let startup = scheduler::Instant::now();
+ let at = |ms: u64| startup + Duration::from_millis(ms);
+ let snapshot = FrameSnapshot {
+ interval_start: at(0),
+ boundary: IntervalBoundary::Idle { ended_at: at(200) },
+ events: (0..10)
+ .map(|i| task_poll_event(at(i * 20), at(i * 20 + 5)))
+ .collect(),
+ small_polls: Vec::new(),
+ dropped_events: 0,
+ journal_discontinuous: false,
+ };
+
+ let incident = HangIncident::detect(snapshot, HANG_THRESHOLD, FRAME_BUDGET)
+ .expect("foreground spend exceeded the frame budget");
+ assert_eq!(incident.contributors.len(), 10);
+ let serialized = SerializedHangIncident::convert(startup, &incident, 8, Some(startup));
+ assert_eq!(serialized.sealed_by, "idle");
+ assert_eq!(serialized.dirty_to_present_ms, None);
+ assert_eq!(serialized.stall_ms, 5.0);
+ assert_eq!(serialized.contributors_elided, 2);
+ }
+
+ /// Contributors serialize in start order with their nesting depth: an
+ /// input dispatch that synchronously drew a window reads as the input at
+ /// depth 0 followed by the draw at depth 1, rather than two unrelated
+ /// blocks of equal wall time.
+ #[test]
+ fn serialized_contributors_are_chronological_with_nesting_depths() {
+ let startup = scheduler::Instant::now();
+ let at = |ms: u64| startup + Duration::from_millis(ms);
+ let window_id = WindowId::from(0x2E57ED);
+ let snapshot = FrameSnapshot {
+ interval_start: at(0),
+ boundary: IntervalBoundary::Idle { ended_at: at(80) },
+ events: vec![
+ task_poll_event(at(50), at(70)),
+ ForegroundEvent::Input(InputTiming {
+ kind: "mouse_move",
+ start: at(0),
+ end: at(40),
+ caused_invalidation: true,
+ }),
+ ForegroundEvent::Draw(FrameTiming {
+ window_id,
+ dirty_at: Some(at(0)),
+ invalidations: 1,
+ draw_start: at(1),
+ draw_end: at(39),
+ }),
+ ],
+ small_polls: Vec::new(),
+ dropped_events: 0,
+ journal_discontinuous: false,
+ };
+
+ let incident =
+ HangIncident::detect(snapshot, HANG_THRESHOLD, FRAME_BUDGET).expect("has contributors");
+ let serialized = SerializedHangIncident::convert(startup, &incident, 8, Some(startup));
+
+ assert_eq!(serialized.stall_ms, 40.0);
+ assert!(matches!(
+ serialized.contributors.as_slice(),
+ [
+ SerializedHangContributor::Input {
+ input_kind: "mouse_move",
+ depth: 0,
+ ..
+ },
+ SerializedHangContributor::Draw { depth: 1, .. },
+ SerializedHangContributor::TaskPoll { depth: 0, .. },
+ ]
+ ));
+ }
+
+ /// Folded small polls count toward foreground spend, so an interval can
+ /// reach the budget with no retained events at all. The incident then
+ /// has no contributors and the small-poll summary carries the story.
+ #[test]
+ fn small_poll_spend_alone_can_reach_the_budget() {
+ let startup = scheduler::Instant::now();
+ let at = |ms: u64| startup + Duration::from_millis(ms);
+ let window_id = WindowId::from(0xDE1A7);
+ let snapshot = FrameSnapshot {
+ interval_start: at(0),
+ boundary: IntervalBoundary::Presented(PresentedFrame {
+ frame: FrameTiming {
+ window_id,
+ dirty_at: Some(at(0)),
+ invalidations: 1,
+ draw_start: at(148),
+ draw_end: at(149),
+ },
+ presentation: PresentTiming {
+ window_id,
+ present_start: at(149),
+ present_end: at(150),
+ animation_interval: None,
+ },
+ }),
+ events: Vec::new(),
+ small_polls: vec![SmallPollFlush {
+ summary: PollSummary {
+ count: 40,
+ total: Duration::from_millis(12),
+ },
+ since: at(0),
+ until: at(150),
+ }],
+ dropped_events: 0,
+ journal_discontinuous: false,
+ };
+
+ let incident = HangIncident::detect(snapshot, HANG_THRESHOLD, FRAME_BUDGET)
+ .expect("small-poll spend exceeded the frame budget");
+ assert!(incident.contributors.is_empty());
+ let serialized = SerializedHangIncident::convert(startup, &incident, 8, Some(startup));
+ assert_eq!(serialized.stall_ms, 0.0);
+ assert_eq!(serialized.event_count, 0);
+ assert_eq!(serialized.small_poll_count, 40);
+ assert_eq!(serialized.dirty_to_present_ms, Some(150.0));
+ assert_eq!(serialized.busy_fraction, 0.08);
+ }
+
+ proptest! {
+ #![proptest_config(ProptestConfig {
+ failure_persistence: None,
+ ..ProptestConfig::default()
+ })]
+
+ #[test]
+ fn detection_matches_threshold_and_budget_model_at_boundaries(
+ durations_ms in prop::collection::vec(0u16..=50, 0..=16),
+ threshold_ms in 0u16..=60,
+ frame_budget_ms in 0u16..=500,
+ small_poll_total_ms in 0u16..=100,
+ ) {
+ let origin = scheduler::Instant::now();
+ let mut cursor_ms = 0u64;
+ let events = durations_ms
+ .iter()
+ .map(|duration_ms| {
+ let start = origin + Duration::from_millis(cursor_ms);
+ cursor_ms += u64::from(*duration_ms);
+ let end = origin + Duration::from_millis(cursor_ms);
+ cursor_ms += 1;
+ ForegroundEvent::Input(InputTiming {
+ kind: "test",
+ start,
+ end,
+ caused_invalidation: false,
+ })
+ })
+ .collect::<Vec<_>>();
+ let interval_end_ms = cursor_ms.max(1);
+ let snapshot = FrameSnapshot {
+ interval_start: origin,
+ boundary: IntervalBoundary::Idle {
+ ended_at: origin + Duration::from_millis(interval_end_ms),
+ },
+ events,
+ small_polls: vec![SmallPollFlush {
+ summary: PollSummary {
+ count: u64::from(small_poll_total_ms > 0),
+ total: Duration::from_millis(u64::from(small_poll_total_ms)),
+ },
+ since: origin,
+ until: origin + Duration::from_millis(interval_end_ms),
+ }],
+ dropped_events: 0,
+ journal_discontinuous: false,
+ };
+ let qualifying_durations = durations_ms
+ .iter()
+ .copied()
+ .filter(|duration| *duration >= threshold_ms)
+ .collect::<Vec<_>>();
+ let occupancy_ms = durations_ms
+ .iter()
+ .map(|duration| u64::from(*duration))
+ .sum::<u64>()
+ + u64::from(small_poll_total_ms);
+ let expected_incident =
+ !qualifying_durations.is_empty() || occupancy_ms >= u64::from(frame_budget_ms);
+
+ let incident = HangIncident::detect(
+ snapshot,
+ Duration::from_millis(u64::from(threshold_ms)),
+ Duration::from_millis(u64::from(frame_budget_ms)),
+ );
+ prop_assert_eq!(incident.is_some(), expected_incident);
+
+ if let Some(incident) = incident {
+ let mut expected_contributors = if qualifying_durations.is_empty() {
+ durations_ms
+ } else {
+ qualifying_durations
+ };
+ expected_contributors.sort_unstable_by(|first, second| second.cmp(first));
+ let observed_contributors = incident
+ .contributors
+ .iter()
+ .map(|event| event.duration().as_millis() as u16)
+ .collect::<Vec<_>>();
+ prop_assert_eq!(observed_contributors, expected_contributors);
+ }
+ }
+ }
+
+ #[derive(Clone, Default)]
+ struct HangControls {
+ render: Rc<Cell<Option<Duration>>>,
+ input: Rc<Cell<Option<Duration>>>,
+ action: Rc<Cell<Option<Duration>>>,
+ }
+
+ struct HangyView {
+ controls: HangControls,
+ focus_handle: FocusHandle,
+ }
+
+ impl Render for HangyView {
+ fn render(&mut self, _: &mut Window, cx: &mut Context<Self>) -> impl IntoElement {
+ if let Some(duration) = self.controls.render.take() {
+ thread::sleep(duration);
+ }
+ let action_controls = self.controls.clone();
+ let input_controls = self.controls.clone();
+ div()
+ .size_full()
+ .track_focus(&self.focus_handle)
+ .on_action(cx.listener(move |_, _: &HangyAction, _, _| {
+ if let Some(duration) = action_controls.action.take() {
+ thread::sleep(duration);
+ }
+ }))
+ .on_mouse_down(MouseButton::Left, move |_, _, _| {
+ if let Some(duration) = input_controls.input.take() {
+ thread::sleep(duration);
+ }
+ })
+ }
+ }
+
+ #[derive(Debug, Copy, Clone, PartialEq, Eq)]
+ enum HangKind {
+ Render,
+ Input,
+ Action,
+ Poll,
+ }
+
+ /// Renders a real element tree and injects randomly ordered, randomly
+ /// sized hangs through the production dispatch paths: view rendering
+ /// (window draw), platform input dispatch, action dispatch, and a
+ /// foreground task poll. Asserts the detector reports every one of them.
+ #[gpui::test(iterations = 5)]
+ fn detects_randomly_placed_foreground_hangs(mut rng: StdRng, cx: &mut TestAppContext) {
+ let (journal, _journal_guard) = install_test_foreground_journal(1024, 16);
+ let mut detector = HangDetector::new(journal, HANG_THRESHOLD, FRAME_BUDGET);
+
+ let controls = HangControls::default();
+ let (view, cx) = cx.add_window_view(|_, cx| HangyView {
+ controls: controls.clone(),
+ focus_handle: cx.focus_handle(),
+ });
+ view.update_in(cx, |view, window, cx| {
+ window.focus(&view.focus_handle, cx);
+ });
+ draw_window(cx);
+
+ let mut injected: Vec<(HangKind, Duration)> = Vec::new();
+ for _ in 0..rng.random_range(1..=4) {
+ let duration = HANG_THRESHOLD + Duration::from_millis(rng.random_range(5..25));
+ let kind = match rng.random_range(0..4) {
+ 0 => {
+ controls.render.set(Some(duration));
+ view.update_in(cx, |_, _, cx| cx.notify());
+ draw_window(cx);
+ HangKind::Render
+ }
+ 1 => {
+ controls.input.set(Some(duration));
+ cx.simulate_mouse_down(
+ point(px(5.), px(5.)),
+ MouseButton::Left,
+ Modifiers::none(),
+ );
+ HangKind::Input
+ }
+ 2 => {
+ controls.action.set(Some(duration));
+ cx.dispatch_action(HangyAction);
+ HangKind::Action
+ }
+ _ => {
+ simulate_blocked_foreground_poll(duration);
+ HangKind::Poll
+ }
+ };
+ injected.push((kind, duration));
+
+ // Innocent interleaved activity that must not confuse detection.
+ if rng.random_bool(0.5) {
+ draw_window(cx);
+ }
+ if rng.random_bool(0.5) {
+ cx.simulate_mouse_up(point(px(5.), px(5.)), MouseButton::Left, Modifiers::none());
+ }
+ }
+
+ // A final presentation seals whatever interval is still open.
+ draw_window(cx);
+
+ let incidents = detector.poll();
+ let contributors: Vec<ForegroundEvent> = incidents
+ .iter()
+ .flat_map(|incident| incident.contributors.iter().copied())
+ .collect();
+
+ for kind in [
+ HangKind::Render,
+ HangKind::Input,
+ HangKind::Action,
+ HangKind::Poll,
+ ] {
+ let expected: Vec<Duration> = injected
+ .iter()
+ .filter(|(injected_kind, _)| *injected_kind == kind)
+ .map(|(_, duration)| *duration)
+ .collect();
+ let observed: Vec<Duration> = contributors
+ .iter()
+ .filter(|event| matches_kind(event, kind) && event.duration() >= HANG_THRESHOLD)
+ .map(|event| event.duration())
+ .collect();
+ assert_all_matched(kind, expected, observed);
+ }
+ }
+
+ /// Every injected hang must be covered by a distinct observed contributor
+ /// at least as long as the injected sleep (sleeps never wake early).
+ fn assert_all_matched(
+ kind: HangKind,
+ mut expected: Vec<Duration>,
+ mut observed: Vec<Duration>,
+ ) {
+ assert_eq!(
+ observed.len(),
+ expected.len(),
+ "expected every observed {kind:?} hang to correspond to one injection; \
+ expected {expected:?}, observed {observed:?}"
+ );
+ expected.sort_unstable_by(|a, b| b.cmp(a));
+ observed.sort_unstable_by(|a, b| b.cmp(a));
+ let mut observed = observed.into_iter();
+ for expected_duration in expected {
+ let matched = observed.find(|observed| *observed >= expected_duration);
+ assert!(
+ matched.is_some(),
+ "injected {kind:?} hang of {expected_duration:?} was not detected"
+ );
+ }
+ }
+
+ fn matches_kind(event: &ForegroundEvent, kind: HangKind) -> bool {
+ match (event, kind) {
+ (ForegroundEvent::Draw(_), HangKind::Render) => true,
+ (ForegroundEvent::Input(_), HangKind::Input) => true,
+ (ForegroundEvent::Action(timing), HangKind::Action) => {
+ timing.name.ends_with("HangyAction")
+ }
+ (ForegroundEvent::TaskPoll(timing), HangKind::Poll) => {
+ timing.location.file() == file!()
+ }
+ _ => false,
+ }
+ }
+
+ fn draw_window(cx: &mut VisualTestContext) {
+ cx.update(|window, cx| {
+ let arena_clear = window.draw(cx);
+ window.present_if_needed();
+ arena_clear.clear(cx);
+ });
+ }
+
+ /// The deterministic test scheduler does not bracket runnables with the
+ /// profiler hooks, so drive the same public hooks the platform
+ /// dispatchers call around a poll that blocks the foreground.
+ fn simulate_blocked_foreground_poll(duration: Duration) {
+ let location = std::panic::Location::caller();
+ crate::profiler::update_running_task(SpawnTime(scheduler::Instant::now()), location);
+ thread::sleep(duration);
+ crate::profiler::save_task_timing();
+ }
+
+ fn task_poll_event(start: scheduler::Instant, end: scheduler::Instant) -> ForegroundEvent {
+ ForegroundEvent::TaskPoll(TaskTiming {
+ location: std::panic::Location::caller(),
+ spawned: SpawnTime(start),
+ start,
+ end: YieldTime(end),
+ })
+ }
+
+ fn presentation(window_id: WindowId, present_end: scheduler::Instant) -> PresentTiming {
+ PresentTiming {
+ window_id,
+ present_start: present_end - Duration::from_millis(1),
+ present_end,
+ animation_interval: None,
+ }
+ }
+
+ fn frame(window_id: WindowId, draw_end: scheduler::Instant) -> FrameTiming {
+ FrameTiming {
+ window_id,
+ dirty_at: Some(draw_end - Duration::from_millis(2)),
+ invalidations: 1,
+ draw_start: draw_end - Duration::from_millis(1),
+ draw_end,
+ }
+ }
+}
diff --git a/crates/gpui/src/profiler/journal.rs b/crates/gpui/src/profiler/journal.rs
new file mode 100644
index 00000000000..ffd694b9148
--- /dev/null
+++ b/crates/gpui/src/profiler/journal.rs
@@ -0,0 +1,2759 @@
+//! A journal of foreground work and the semantic boundaries between activity intervals.
+//!
+//! The foreground thread records task polls, action handlers, input dispatches,
+//! draws, and presentations as [`ForegroundEvent`]s in a bounded journal ring.
+//! Task polls shorter than [`TASK_POLL_FLOOR`] are folded into summaries, which
+//! bound the stream by the number of slow polls while preserving their exact
+//! count and total duration.
+//!
+//! Presentation and the foreground going idle are explicit [`IntervalBoundary`]
+//! entries in the same stream. Independent [`ForegroundJournalCollector`]s
+//! feed entries to [`IntervalSealer`], a pure state machine that groups all work
+//! preceding each boundary into a [`FrameSnapshot`]. The sealer does not infer
+//! boundaries from elapsed time or from incidental event kinds such as draws.
+
+use std::cell::{RefCell, UnsafeCell};
+use std::collections::{HashMap, VecDeque};
+use std::mem::MaybeUninit;
+use std::sync::{
+ Arc,
+ atomic::{AtomicU64, AtomicUsize, Ordering},
+};
+use std::time::Duration;
+
+use scheduler::Instant;
+
+use super::{ActionTiming, FrameTiming, PresentTiming, TaskTiming};
+use crate::WindowId;
+
+/// Task polls shorter than this are folded into a [`PollSummary`] instead of
+/// being recorded individually. This keeps the stream bounded by the number
+/// of *slow* polls while preserving their exact count and total duration.
+pub const TASK_POLL_FLOOR: Duration = Duration::from_micros(100);
+
+/// A dirty frame that has not been presented by this deadline stops blocking
+/// foreground-idle boundaries, so a window that never presents (hidden or
+/// occluded windows receive no frame callbacks) cannot suppress boundaries
+/// indefinitely. Expiry only unblocks: the open interval still seals at a
+/// real presentation or idle boundary, keeping a starving hang and the frame
+/// it starved in one interval.
+pub const FRAME_DEADLINE: Duration = Duration::from_secs(1);
+
+// Backstop against pathological event storms within a single interval. At the
+// 100us floor, a fully hung second can produce at most ~10k recordable polls,
+// so this bound is only reachable when something is already deeply wrong.
+const MAX_INTERVAL_EVENTS: usize = 16 * 1024;
+
+// Allow 4MiB for the fixed ring allocation, including each slot's atomic
+// metadata. The poll floor and frame cadence bound the event rate to roughly
+// 10k per second in the worst case, so this holds several seconds of
+// worst-case traffic between consumer drains.
+const MAX_JOURNAL_ENTRIES: usize = (4 * 1024 * 1024) / core::mem::size_of::<JournalSlot>();
+
+// Absorbs brief collisions with a collector reading the exact slot being
+// wrapped. The foreground never waits for a reader; queued entries are retried
+// in order on the next publication.
+const MAX_PENDING_JOURNAL_ENTRIES: usize = 64;
+
+/// One entry in the foreground stream.
+///
+/// Events are recorded in completion order (ordered by their end time). An
+/// event that was in progress across a frame boundary (e.g. the task poll
+/// enclosing a draw) is recorded when it *ends*, with timestamps that may
+/// precede events recorded before it.
+#[derive(Debug, Copy, Clone)]
+pub enum ForegroundEvent {
+ /// A foreground task poll at least [`TASK_POLL_FLOOR`] long.
+ TaskPoll(TaskTiming),
+ /// A completed action handler.
+ Action(ActionTiming),
+ /// A dispatched platform input event.
+ Input(InputTiming),
+ /// A completed window draw.
+ Draw(FrameTiming),
+ /// Work spent submitting a frame to the platform.
+ Present(PresentTiming),
+ /// Aggregate of task polls below [`TASK_POLL_FLOOR`], flushed before the
+ /// next individually retained event or interval boundary.
+ SmallPolls(SmallPollFlush),
+}
+
+impl ForegroundEvent {
+ /// When the work described by this event began. For draws this is the
+ /// start of the draw itself, not the frame's first invalidation.
+ pub fn start_time(&self) -> Instant {
+ match self {
+ Self::TaskPoll(timing) => timing.start,
+ Self::Action(timing) => timing.start,
+ Self::Input(timing) => timing.start,
+ Self::Draw(timing) => timing.draw_start,
+ Self::Present(timing) => timing.present_start,
+ Self::SmallPolls(flush) => flush.since,
+ }
+ }
+
+ /// When the work described by this event ended.
+ pub fn end_time(&self) -> Instant {
+ match self {
+ Self::TaskPoll(timing) => timing.end.0,
+ Self::Action(timing) => timing.end,
+ Self::Input(timing) => timing.end,
+ Self::Draw(timing) => timing.draw_end,
+ Self::Present(timing) => timing.present_end,
+ Self::SmallPolls(flush) => flush.until,
+ }
+ }
+
+ /// How long the work described by this event took. For
+ /// [`Self::SmallPolls`] this is the span the summary covers, not time
+ /// spent polling; use the summary's `total` for occupancy.
+ pub fn duration(&self) -> Duration {
+ self.end_time().duration_since(self.start_time())
+ }
+}
+
+/// Timing of one platform input dispatch on a window.
+#[derive(Debug, Copy, Clone)]
+pub struct InputTiming {
+ /// The platform input variant dispatched (see
+ /// [`crate::PlatformInput::kind_name`]).
+ pub kind: &'static str,
+ /// When the input dispatch started.
+ pub start: Instant,
+ /// When the input dispatch finished.
+ pub end: Instant,
+ /// Whether handling the input invalidated a window.
+ pub caused_invalidation: bool,
+}
+
+/// Exact count and total duration of task polls below [`TASK_POLL_FLOOR`].
+#[derive(Debug, Copy, Clone, Default, PartialEq, Eq)]
+pub struct PollSummary {
+ /// Number of polls below the floor.
+ pub count: u64,
+ /// Total duration of polls below the floor.
+ pub total: Duration,
+}
+
+impl PollSummary {
+ fn add(&mut self, other: Self) {
+ self.count += other.count;
+ self.total += other.total;
+ }
+}
+
+/// A flushed [`PollSummary`] and the tightest span containing its folded polls.
+#[derive(Debug, Copy, Clone)]
+pub struct SmallPollFlush {
+ /// The folded polls.
+ pub summary: PollSummary,
+ /// When the first folded poll began.
+ pub since: Instant,
+ /// When the last folded poll ended.
+ pub until: Instant,
+}
+
+/// A newly drawn frame and the platform submission that completed its interval.
+#[derive(Debug, Copy, Clone)]
+pub struct PresentedFrame {
+ /// The draw whose rendered scene was submitted.
+ pub frame: FrameTiming,
+ /// Work spent submitting that scene to the platform.
+ pub presentation: PresentTiming,
+}
+
+impl PresentedFrame {
+ /// Time from the frame's first invalidation through platform submission.
+ pub fn dirty_to_present_duration(&self) -> Option<Duration> {
+ self.frame
+ .dirty_at
+ .map(|dirty_at| self.presentation.present_end.duration_since(dirty_at))
+ }
+}
+
+/// The semantic event that completed a foreground activity interval.
+#[derive(Debug, Copy, Clone)]
+pub enum IntervalBoundary {
+ /// A newly drawn frame was submitted to the platform.
+ Presented(PresentedFrame),
+ /// The foreground returned to an idle platform loop with no unexpired
+ /// frame pending.
+ Idle {
+ /// When the foreground went idle.
+ ended_at: Instant,
+ },
+}
+
+impl IntervalBoundary {
+ /// When the interval ended.
+ pub fn end_time(&self) -> Instant {
+ match self {
+ Self::Presented(presented) => presented.presentation.present_end,
+ Self::Idle { ended_at } => *ended_at,
+ }
+ }
+
+ /// The first invalidation of the frame satisfied by this boundary, if any.
+ pub fn dirty_at(&self) -> Option<Instant> {
+ match self {
+ Self::Presented(presented) => presented.frame.dirty_at,
+ Self::Idle { .. } => None,
+ }
+ }
+}
+
+/// A control-plane change to one window's pending-frame state.
+#[derive(Debug, Copy, Clone)]
+pub enum FrameStateChange {
+ /// The window has a frame waiting to be presented.
+ Pending {
+ /// The window waiting for presentation.
+ window_id: WindowId,
+ /// When this frame generation first became dirty.
+ dirty_at: Instant,
+ },
+ /// The window closed, so any pending frame no longer blocks idle
+ /// boundaries.
+ Closed {
+ /// The window that closed.
+ window_id: WindowId,
+ /// When the window closed.
+ at: Instant,
+ },
+}
+
+/// One item retained in the foreground journal.
+#[derive(Debug, Copy, Clone)]
+pub enum ForegroundJournalEntry {
+ /// A completed piece of foreground work.
+ Event(ForegroundEvent),
+ /// A semantic interval boundary.
+ Boundary(IntervalBoundary),
+ /// A change to pending-frame state. This is metadata, not foreground work.
+ FrameState(FrameStateChange),
+ /// One or more logical entries were unavailable at this point in the
+ /// stream. Consumers must not infer interval boundaries across this gap.
+ Discontinuity {
+ /// Number of unavailable logical entries.
+ lost: u64,
+ },
+}
+
+/// An immutable view of one sealed foreground interval, produced by
+/// [`IntervalSealer`].
+#[derive(Debug, Clone)]
+pub struct FrameSnapshot {
+ /// When the interval started (the previous seal, or the end of the idle
+ /// stretch preceding the interval's first event).
+ pub interval_start: Instant,
+ /// The semantic event that completed the interval, including its metadata.
+ pub boundary: IntervalBoundary,
+ /// Foreground work recorded during the interval, in completion order.
+ /// [`ForegroundEvent::SmallPolls`] entries are collected into
+ /// `small_polls` instead of appearing here.
+ pub events: Vec<ForegroundEvent>,
+ /// Span-tagged aggregates of task polls below [`TASK_POLL_FLOOR`]. Spans
+ /// are retained so occupancy can apportion folded poll time to reporting
+ /// windows narrower than the interval.
+ pub small_polls: Vec<SmallPollFlush>,
+ /// Events lost to the interval's event cap, plus ring losses reported
+ /// via [`IntervalSealer::note_lost`].
+ pub dropped_events: u64,
+ /// Whether the journal had an unobserved gap during this interval.
+ pub journal_discontinuous: bool,
+}
+
+impl FrameSnapshot {
+ /// When the interval ended.
+ pub fn interval_end(&self) -> Instant {
+ self.boundary.end_time()
+ }
+
+ /// The combined count and total of all folded sub-floor polls in the
+ /// interval.
+ pub fn small_poll_summary(&self) -> PollSummary {
+ let mut summary = PollSummary::default();
+ for flush in &self.small_polls {
+ summary.add(flush.summary);
+ }
+ summary
+ }
+
+ /// Total foreground time occupied within the interval: the union of the
+ /// recorded events' spans (clamped to the interval, so nested work like an
+ /// action inside an input dispatch is not double counted) plus the folded
+ /// small polls. Folded polls cannot be unioned with nested individually
+ /// timed work, so this remains a close approximation.
+ pub fn occupancy(&self) -> Duration {
+ self.occupancy_within(self.interval_start, self.interval_end())
+ }
+
+ /// Like [`Self::occupancy`], but measured against an arbitrary window
+ /// (e.g. a reporting window anchored at a frame's first invalidation).
+ /// Event spans are clamped to the window. Folded polls carry no
+ /// individual timestamps, so each flush's total is apportioned by how
+ /// much of its span overlaps the window — assuming the folded time is
+ /// spread uniformly across the span.
+ pub fn occupancy_within(&self, window_start: Instant, window_end: Instant) -> Duration {
+ let mut spans: Vec<(Instant, Instant)> = self
+ .events
+ .iter()
+ .map(|event| {
+ let start = event.start_time().max(window_start);
+ let end = event.end_time().min(window_end).max(start);
+ (start, end)
+ })
+ .collect();
+ spans.sort_by_key(|(start, _)| *start);
+
+ let mut occupied = Duration::ZERO;
+ let mut merged_until: Option<Instant> = None;
+ for (start, end) in spans {
+ let start = match merged_until {
+ Some(merged_until) => start.max(merged_until),
+ None => start,
+ };
+ occupied += end.duration_since(start);
+ merged_until = Some(match merged_until {
+ Some(merged_until) => merged_until.max(end),
+ None => end,
+ });
+ }
+
+ let apportioned_small_polls: Duration = self
+ .small_polls
+ .iter()
+ .map(|flush| {
+ let span = flush.until.duration_since(flush.since);
+ if span.is_zero() {
+ // A point-like flush lies either inside or outside the
+ // window.
+ if flush.since >= window_start && flush.since <= window_end {
+ flush.summary.total
+ } else {
+ Duration::ZERO
+ }
+ } else {
+ let overlap_start = flush.since.max(window_start);
+ let overlap_end = flush.until.min(window_end).max(overlap_start);
+ let overlap = overlap_end.duration_since(overlap_start);
+ flush.summary.total.mul_f64(overlap.div_duration_f64(span))
+ }
+ })
+ .sum();
+ occupied + apportioned_small_polls
+ }
+
+ /// The fraction of the interval the foreground spent working, in `0.0..=1.0`.
+ pub fn busy_fraction(&self) -> f64 {
+ let interval = self.interval_end().duration_since(self.interval_start);
+ if interval.is_zero() {
+ return 1.0;
+ }
+ (self.occupancy().div_duration_f64(interval)).min(1.0)
+ }
+}
+
+#[derive(Clone)]
+pub(crate) struct ForegroundRunnableCounter(Arc<AtomicUsize>);
+
+impl ForegroundRunnableCounter {
+ fn new() -> Self {
+ Self(Arc::new(AtomicUsize::new(0)))
+ }
+
+ pub(crate) fn queued(&self) {
+ self.0.fetch_add(1, Ordering::Release);
+ }
+
+ fn finished(&self) {
+ let _ = self
+ .0
+ .fetch_update(Ordering::AcqRel, Ordering::Acquire, |count| {
+ count.checked_sub(1)
+ });
+ }
+
+ fn has_runnables(&self) -> bool {
+ self.0.load(Ordering::Acquire) > 0
+ }
+}
+
+struct ForegroundJournalWriter {
+ foreground_runnables: ForegroundRunnableCounter,
+ publisher: JournalPublisher,
+ turn_depth: usize,
+ pending_frames: HashMap<WindowId, Instant>,
+ retained_since_boundary: bool,
+ small_polls: Option<SmallPollFlush>,
+}
+
+impl ForegroundJournalWriter {
+ fn new(foreground_runnables: ForegroundRunnableCounter, publisher: JournalPublisher) -> Self {
+ Self {
+ foreground_runnables,
+ publisher,
+ turn_depth: 0,
+ pending_frames: HashMap::new(),
+ retained_since_boundary: false,
+ small_polls: None,
+ }
+ }
+
+ fn begin_turn(&mut self) {
+ self.turn_depth += 1;
+ }
+
+ // Idle boundaries require a retained event since the last boundary, not
+ // merely folded sub-floor polls. Sporadic wake-ups (timers, file
+ // watchers) leave the foreground idle after every tiny poll; a boundary
+ // for each would re-admit to the ring the very polls the fold keeps out
+ // of it, wrapping the ring within seconds. Folded-only work is discarded
+ // at true idle so unrelated wake-ups cannot accumulate toward a later
+ // frame budget. Polls remain folded while a frame or runnable is pending.
+ fn end_turn(&mut self, ended_at: Instant) {
+ let Some(turn_depth) = self.turn_depth.checked_sub(1) else {
+ debug_assert!(false, "foreground turn must be begun before it ends");
+ return;
+ };
+ self.turn_depth = turn_depth;
+ if self.turn_depth > 0
+ || self.foreground_runnables.has_runnables()
+ || self.has_unexpired_pending_frame(ended_at)
+ {
+ return;
+ }
+ if !self.retained_since_boundary {
+ self.small_polls = None;
+ return;
+ }
+
+ self.record_entry(ForegroundJournalEntry::Boundary(IntervalBoundary::Idle {
+ ended_at,
+ }));
+ }
+
+ fn has_unexpired_pending_frame(&mut self, now: Instant) -> bool {
+ if self.pending_frames.is_empty() {
+ return false;
+ }
+ self.pending_frames
+ .retain(|_, dirty_at| now.saturating_duration_since(*dirty_at) < FRAME_DEADLINE);
+ !self.pending_frames.is_empty()
+ }
+
+ fn fold_small_poll(&mut self, timing: TaskTiming) {
+ let flush = self.small_polls.get_or_insert(SmallPollFlush {
+ summary: PollSummary::default(),
+ since: timing.start,
+ until: timing.end.0,
+ });
+ flush.summary.count += 1;
+ flush.summary.total += timing.poll_duration();
+ flush.since = flush.since.min(timing.start);
+ flush.until = flush.until.max(timing.end.0);
+ }
+
+ fn take_small_polls(&mut self) -> Option<SmallPollFlush> {
+ self.small_polls.take()
+ }
+
+ fn record_event(&mut self, event: ForegroundEvent) {
+ self.retained_since_boundary = true;
+ self.record_entry(ForegroundJournalEntry::Event(event));
+ }
+
+ fn record_entry(&mut self, entry: ForegroundJournalEntry) {
+ let small_polls = self
+ .take_small_polls()
+ .map(ForegroundEvent::SmallPolls)
+ .map(ForegroundJournalEntry::Event);
+ self.publisher
+ .publish([small_polls, Some(entry)].into_iter().flatten());
+ if matches!(entry, ForegroundJournalEntry::Boundary(_)) {
+ self.retained_since_boundary = false;
+ }
+ }
+
+ fn record_frame_state(&mut self, change: FrameStateChange) {
+ self.record_entry(ForegroundJournalEntry::FrameState(change));
+ }
+
+ fn record_frame_pending(&mut self, window_id: WindowId, dirty_at: Instant) {
+ let should_record = match self.pending_frames.get(&window_id) {
+ Some(previous_dirty_at) => {
+ dirty_at.saturating_duration_since(*previous_dirty_at) >= FRAME_DEADLINE
+ }
+ None => true,
+ };
+ if !should_record {
+ return;
+ }
+
+ self.pending_frames.insert(window_id, dirty_at);
+ self.record_frame_state(FrameStateChange::Pending {
+ window_id,
+ dirty_at,
+ });
+ }
+
+ fn record_window_closed(&mut self, window_id: WindowId, at: Instant) {
+ self.pending_frames.remove(&window_id);
+ self.record_frame_state(FrameStateChange::Closed { window_id, at });
+ }
+
+ fn record_present(&mut self, timing: PresentTiming, frame: Option<FrameTiming>) {
+ match frame {
+ Some(frame) => {
+ self.pending_frames.remove(&frame.window_id);
+ self.record_entry(ForegroundJournalEntry::Boundary(
+ IntervalBoundary::Presented(PresentedFrame {
+ frame,
+ presentation: timing,
+ }),
+ ));
+ }
+ None => {
+ self.pending_frames.remove(&timing.window_id);
+ self.record_event(ForegroundEvent::Present(timing));
+ }
+ }
+ }
+}
+
+thread_local! {
+ static FOREGROUND_RUNNABLES: ForegroundRunnableCounter = ForegroundRunnableCounter::new();
+ static FOREGROUND_JOURNAL: RefCell<Option<ForegroundJournalWriter>> = const { RefCell::new(None) };
+}
+
+pub(crate) fn foreground_runnable_counter() -> ForegroundRunnableCounter {
+ FOREGROUND_RUNNABLES.with(Clone::clone)
+}
+
+/// Starts journaling on the calling thread. Called once by `App` construction
+/// on the main thread; every other thread's recording calls are no-ops.
+/// Idempotent so that multiple `App`s on one thread (tests) share one journal.
+pub(crate) fn install_foreground_journal() -> ForegroundJournal {
+ let foreground_runnables = foreground_runnable_counter();
+ FOREGROUND_JOURNAL.with(|journal| {
+ let mut journal = journal.borrow_mut();
+ if let Some(journal) = journal.as_ref() {
+ return ForegroundJournal {
+ ring: Arc::clone(&journal.publisher.ring),
+ };
+ }
+
+ let (handle, publisher) =
+ ForegroundJournal::new(MAX_JOURNAL_ENTRIES, MAX_PENDING_JOURNAL_ENTRIES);
+ *journal = Some(ForegroundJournalWriter::new(
+ foreground_runnables,
+ publisher,
+ ));
+ handle
+ })
+}
+
+#[cfg(test)]
+pub(super) struct TestForegroundJournalGuard {
+ previous: Option<ForegroundJournalWriter>,
+ _not_send: std::marker::PhantomData<std::rc::Rc<()>>,
+}
+
+#[cfg(test)]
+impl Drop for TestForegroundJournalGuard {
+ fn drop(&mut self) {
+ FOREGROUND_JOURNAL.with(|journal| {
+ *journal.borrow_mut() = self.previous.take();
+ });
+ }
+}
+
+#[cfg(test)]
+pub(super) fn install_test_foreground_journal(
+ capacity: usize,
+ pending_capacity: usize,
+) -> (ForegroundJournal, TestForegroundJournalGuard) {
+ let foreground_runnables = foreground_runnable_counter();
+ let (handle, publisher) = ForegroundJournal::new(capacity, pending_capacity);
+ let previous = FOREGROUND_JOURNAL.with(|journal| {
+ journal.borrow_mut().replace(ForegroundJournalWriter::new(
+ foreground_runnables,
+ publisher,
+ ))
+ });
+ (
+ handle,
+ TestForegroundJournalGuard {
+ previous,
+ _not_send: std::marker::PhantomData,
+ },
+ )
+}
+
+fn with_journal(f: impl FnOnce(&mut ForegroundJournalWriter)) {
+ FOREGROUND_JOURNAL.with(|journal| {
+ if let Some(journal) = journal.borrow_mut().as_mut() {
+ f(journal);
+ }
+ });
+}
+
+// TODO(gpui-profiler): the turn brackets in the dispatchers and
+// WindowProfiler are bare begin/end call pairs rather than uses of this
+// guard. A caught unwind between a pair leaves `turn_depth` (and potentially
+// the runnable counter) permanently unbalanced, which silently disables
+// idle boundaries for the rest of the process. Zed aborts on panics so
+// this is latent today, but gpui-as-a-library callers may catch unwinds;
+// route all bracketing through this guard.
+pub(crate) struct ForegroundTurnGuard;
+
+impl Drop for ForegroundTurnGuard {
+ fn drop(&mut self) {
+ end_foreground_turn();
+ }
+}
+
+pub(crate) fn foreground_turn() -> ForegroundTurnGuard {
+ begin_foreground_turn();
+ ForegroundTurnGuard
+}
+
+pub(crate) fn begin_foreground_turn() {
+ with_journal(ForegroundJournalWriter::begin_turn);
+}
+
+pub(crate) fn end_foreground_turn() {
+ with_journal(|journal| journal.end_turn(Instant::now()));
+}
+
+pub(crate) fn record_task_poll(timing: TaskTiming) {
+ FOREGROUND_RUNNABLES.with(ForegroundRunnableCounter::finished);
+ with_journal(|journal| {
+ if timing.poll_duration() >= TASK_POLL_FLOOR {
+ journal.record_event(ForegroundEvent::TaskPoll(timing));
+ } else {
+ journal.fold_small_poll(timing);
+ }
+ journal.end_turn(timing.end.0);
+ });
+}
+
+pub(crate) fn record_action(timing: ActionTiming) {
+ with_journal(|journal| journal.record_event(ForegroundEvent::Action(timing)));
+}
+
+pub(crate) fn record_input(timing: InputTiming) {
+ with_journal(|journal| journal.record_event(ForegroundEvent::Input(timing)));
+}
+
+pub(crate) fn record_draw(timing: FrameTiming) {
+ with_journal(|journal| journal.record_event(ForegroundEvent::Draw(timing)));
+}
+
+pub(crate) fn record_present(timing: PresentTiming, frame: Option<FrameTiming>) {
+ with_journal(|journal| journal.record_present(timing, frame));
+}
+
+pub(crate) fn record_frame_pending(window_id: WindowId, dirty_at: Instant) {
+ with_journal(|journal| journal.record_frame_pending(window_id, dirty_at));
+}
+
+pub(crate) fn record_window_closed(window_id: WindowId) {
+ let at = Instant::now();
+ with_journal(|journal| journal.record_window_closed(window_id, at));
+}
+
+const SLOT_WRITER: usize = 1 << (usize::BITS - 1);
+const SLOT_READER_MASK: usize = !SLOT_WRITER;
+const EMPTY_SEQUENCE: u64 = u64::MAX;
+
+struct JournalSlot {
+ users: AtomicUsize,
+ sequence: AtomicU64,
+ entry: UnsafeCell<MaybeUninit<ForegroundJournalEntry>>,
+}
+
+// `users` ensures the entry is only read while no writer owns the slot and is
+// only written while no readers own it.
+unsafe impl Sync for JournalSlot {}
+
+impl JournalSlot {
+ fn new() -> Self {
+ Self {
+ users: AtomicUsize::new(0),
+ sequence: AtomicU64::new(EMPTY_SEQUENCE),
+ entry: UnsafeCell::new(MaybeUninit::uninit()),
+ }
+ }
+
+ fn try_publish(&self, sequence: u64, entry: ForegroundJournalEntry) -> bool {
+ if self
+ .users
+ .compare_exchange(0, SLOT_WRITER, Ordering::Acquire, Ordering::Relaxed)
+ .is_err()
+ {
+ return false;
+ }
+
+ // SAFETY: setting SLOT_WRITER from zero gives this writer exclusive
+ // access to the slot until the Release store below.
+ unsafe {
+ (*self.entry.get()).write(entry);
+ }
+ self.sequence.store(sequence, Ordering::Relaxed);
+ self.users.store(0, Ordering::Release);
+ true
+ }
+
+ fn try_read(&self, expected_sequence: u64) -> Option<ForegroundJournalEntry> {
+ let _guard = JournalSlotReadGuard::try_new(self)?;
+ if self.sequence.load(Ordering::Relaxed) != expected_sequence {
+ return None;
+ }
+
+ // SAFETY: a matching sequence means the slot was initialized for this
+ // logical entry, and `guard` prevents the writer from overwriting it
+ // until after the Copy.
+ Some(unsafe { *(*self.entry.get()).assume_init_ref() })
+ }
+
+ fn try_add_reader(&self) -> bool {
+ let mut users = self.users.load(Ordering::Relaxed);
+ loop {
+ if users & SLOT_WRITER != 0 || users == SLOT_READER_MASK {
+ return false;
+ }
+ match self.users.compare_exchange_weak(
+ users,
+ users + 1,
+ Ordering::Acquire,
+ Ordering::Relaxed,
+ ) {
+ Ok(_) => return true,
+ Err(updated_users) => users = updated_users,
+ }
+ }
+ }
+
+ fn remove_reader(&self) {
+ let previous = self.users.fetch_sub(1, Ordering::Release);
+ debug_assert!(
+ previous > 0 && previous & SLOT_WRITER == 0,
+ "invalid slot reader state: {previous:#x}"
+ );
+ }
+}
+
+struct JournalSlotReadGuard<'a> {
+ slot: &'a JournalSlot,
+}
+
+impl<'a> JournalSlotReadGuard<'a> {
+ fn try_new(slot: &'a JournalSlot) -> Option<Self> {
+ if slot.try_add_reader() {
+ Some(Self { slot })
+ } else {
+ None
+ }
+ }
+}
+
+impl Drop for JournalSlotReadGuard<'_> {
+ fn drop(&mut self) {
+ self.slot.remove_reader();
+ }
+}
+
+struct JournalRing {
+ slots: Box<[JournalSlot]>,
+ finalized: AtomicU64,
+ offered: AtomicU64,
+}
+
+impl JournalRing {
+ fn new(capacity: usize) -> Self {
+ let capacity = capacity.max(1);
+ Self {
+ slots: (0..capacity).map(|_| JournalSlot::new()).collect(),
+ finalized: AtomicU64::new(0),
+ offered: AtomicU64::new(0),
+ }
+ }
+
+ fn capacity(&self) -> usize {
+ self.slots.len()
+ }
+
+ fn try_publish(&self, sequence: u64, entry: ForegroundJournalEntry) -> bool {
+ let index = (sequence % self.slots.len() as u64) as usize;
+ self.slots[index].try_publish(sequence, entry)
+ }
+
+ fn read(&self, sequence: u64) -> Option<ForegroundJournalEntry> {
+ let index = (sequence % self.slots.len() as u64) as usize;
+ self.slots[index].try_read(sequence)
+ }
+}
+
+struct PendingJournalEntry {
+ sequence: u64,
+ entry: ForegroundJournalEntry,
+}
+
+struct JournalPublisher {
+ ring: Arc<JournalRing>,
+ next_sequence: u64,
+ pending: VecDeque<PendingJournalEntry>,
+ dropped_after_pending: u64,
+ pending_capacity: usize,
+}
+
+impl JournalPublisher {
+ fn new(ring: Arc<JournalRing>, pending_capacity: usize) -> Self {
+ Self {
+ ring,
+ next_sequence: 0,
+ pending: VecDeque::with_capacity(pending_capacity),
+ dropped_after_pending: 0,
+ pending_capacity,
+ }
+ }
+
+ fn publish(&mut self, entries: impl IntoIterator<Item = ForegroundJournalEntry>) {
+ for entry in entries {
+ self.flush_pending();
+ self.publish_one(entry);
+ }
+ self.flush_pending();
+ }
+
+ fn publish_one(&mut self, entry: ForegroundJournalEntry) {
+ let sequence = self.next_sequence;
+ self.next_sequence += 1;
+ self.ring
+ .offered
+ .store(self.next_sequence, Ordering::Release);
+
+ if !self.pending.is_empty() || self.dropped_after_pending > 0 {
+ if self.dropped_after_pending == 0 && self.pending.len() < self.pending_capacity {
+ self.pending
+ .push_back(PendingJournalEntry { sequence, entry });
+ } else {
+ self.dropped_after_pending += 1;
+ }
+ return;
+ }
+
+ if self.ring.try_publish(sequence, entry) {
+ self.ring.finalized.store(sequence + 1, Ordering::Release);
+ } else if self.pending_capacity > 0 {
+ self.pending
+ .push_back(PendingJournalEntry { sequence, entry });
+ } else {
+ self.dropped_after_pending = 1;
+ }
+ }
+
+ fn flush_pending(&mut self) {
+ while let Some(pending) = self.pending.front() {
+ if !self.ring.try_publish(pending.sequence, pending.entry) {
+ return;
+ }
+ let sequence = pending.sequence;
+ self.pending.pop_front();
+ self.ring.finalized.store(sequence + 1, Ordering::Release);
+ }
+
+ if self.dropped_after_pending > 0 {
+ self.ring
+ .finalized
+ .store(self.next_sequence, Ordering::Release);
+ self.dropped_after_pending = 0;
+ }
+ }
+}
+
+/// A cloneable handle to one foreground journal stream.
+///
+/// Each collector has an independent cursor. Collectors briefly pin one slot
+/// at a time and never block recording; entries they could not observe are
+/// reported as discontinuities. Apps on the same foreground thread share the
+/// stream.
+#[derive(Clone)]
+pub struct ForegroundJournal {
+ ring: Arc<JournalRing>,
+}
+
+impl ForegroundJournal {
+ fn new(capacity: usize, pending_capacity: usize) -> (Self, JournalPublisher) {
+ let ring = Arc::new(JournalRing::new(capacity));
+ (
+ Self {
+ ring: Arc::clone(&ring),
+ },
+ JournalPublisher::new(ring, pending_capacity),
+ )
+ }
+
+ /// Creates an independent collector that observes entries offered after
+ /// this call.
+ pub fn collector(&self) -> ForegroundJournalCollector {
+ ForegroundJournalCollector {
+ cursor: self.ring.offered.load(Ordering::Acquire),
+ ring: Arc::clone(&self.ring),
+ }
+ }
+}
+
+/// Entries returned by one [`ForegroundJournalCollector::collect_unseen`] call.
+#[derive(Debug, Default)]
+pub struct DrainedEntries {
+ /// Journal entries recorded since the previous drain, in recording order,
+ /// including synthetic [`ForegroundJournalEntry::Discontinuity`] markers at
+ /// unavailable logical positions.
+ pub entries: Vec<ForegroundJournalEntry>,
+ /// Entries unavailable to this collector because they were overwritten or
+ /// could not be published after the fixed pending queue filled. This is the
+ /// aggregate of the discontinuity markers in `entries`.
+ pub lost: u64,
+}
+
+/// Reads the foreground stream, tracking a cursor so each call to
+/// [`Self::collect_unseen`] returns only entries recorded since the previous
+/// call. Independent collectors do not affect each other.
+pub struct ForegroundJournalCollector {
+ cursor: u64,
+ ring: Arc<JournalRing>,
+}
+
+impl ForegroundJournalCollector {
+ /// Returns entries recorded since the previous call (or since the
+ /// collector was created), reporting how many were unavailable before this
+ /// drain observed them.
+ pub fn collect_unseen(&mut self) -> DrainedEntries {
+ let end = self.ring.finalized.load(Ordering::Acquire);
+ if self.cursor >= end {
+ return DrainedEntries::default();
+ }
+ let retained_start = end.saturating_sub(self.ring.capacity() as u64);
+ let mut lost = retained_start.saturating_sub(self.cursor);
+ self.cursor = self.cursor.max(retained_start);
+ let mut entries = Vec::with_capacity((end - self.cursor) as usize + usize::from(lost > 0));
+ if lost > 0 {
+ entries.push(ForegroundJournalEntry::Discontinuity { lost });
+ }
+
+ while self.cursor < end {
+ if let Some(entry) = self.ring.read(self.cursor) {
+ entries.push(entry);
+ } else {
+ lost += 1;
+ match entries.last_mut() {
+ Some(ForegroundJournalEntry::Discontinuity { lost }) => *lost += 1,
+ _ => entries.push(ForegroundJournalEntry::Discontinuity { lost: 1 }),
+ }
+ }
+ self.cursor += 1;
+ }
+
+ DrainedEntries { entries, lost }
+ }
+}
+
+/// A pure state machine that groups foreground journal entries into
+/// [`FrameSnapshot`]s.
+///
+/// Feed it drained entries in recording order. Work is carried across calls
+/// until an explicit [`IntervalBoundary`] arrives. Idle time before an
+/// interval's first event is excluded without relying on an elapsed-time
+/// heuristic.
+#[derive(Debug)]
+pub struct IntervalSealer {
+ interval_start: Instant,
+ events: Vec<ForegroundEvent>,
+ small_polls: Vec<SmallPollFlush>,
+ dropped_events: u64,
+ journal_discontinuous: bool,
+}
+
+impl IntervalSealer {
+ /// Creates a sealer whose first interval starts at `start` (typically
+ /// the moment the consumer's collector was created).
+ pub fn new(start: Instant) -> Self {
+ Self {
+ interval_start: start,
+ events: Vec::new(),
+ small_polls: Vec::new(),
+ dropped_events: 0,
+ journal_discontinuous: false,
+ }
+ }
+
+ /// Accounts for a loss supplied outside a collector drain. Collector losses
+ /// are already represented by ordered discontinuity entries.
+ pub fn note_lost(&mut self, lost: u64) {
+ self.dropped_events += lost;
+ self.journal_discontinuous |= lost > 0;
+ }
+
+ /// Processes a batch of drained entries, returning the snapshots completed
+ /// by explicit boundaries. Work without a following boundary is carried
+ /// over to subsequent calls.
+ pub fn push_entries(
+ &mut self,
+ entries: impl IntoIterator<Item = ForegroundJournalEntry>,
+ ) -> Vec<FrameSnapshot> {
+ let mut snapshots = Vec::new();
+ for entry in entries {
+ match entry {
+ ForegroundJournalEntry::Event(event) => {
+ if self.is_empty() {
+ self.interval_start = self.interval_start.max(event.start_time());
+ }
+ match event {
+ ForegroundEvent::SmallPolls(flush) => self.push_small_polls(flush),
+ event => self.push_event(event),
+ }
+ }
+ ForegroundJournalEntry::Boundary(boundary) => {
+ if let IntervalBoundary::Presented(presented) = boundary {
+ if self.is_empty() {
+ self.interval_start = self
+ .interval_start
+ .max(presented.presentation.present_start);
+ }
+ self.push_event(ForegroundEvent::Present(presented.presentation));
+ }
+ if self.is_empty() {
+ self.interval_start = self.interval_start.max(boundary.end_time());
+ } else {
+ snapshots.push(self.seal(boundary));
+ }
+ }
+ // Pending-frame state gates boundaries on the writer side;
+ // the entries remain in the stream for consumers that want
+ // dirty timing, but the sealer has no use for them.
+ ForegroundJournalEntry::FrameState(_) => {}
+ ForegroundJournalEntry::Discontinuity { lost } => self.note_lost(lost),
+ }
+ }
+ snapshots
+ }
+
+ fn is_empty(&self) -> bool {
+ self.events.is_empty()
+ && self.small_polls.is_empty()
+ && self.dropped_events == 0
+ && !self.journal_discontinuous
+ }
+
+ fn push_event(&mut self, event: ForegroundEvent) {
+ if self.events.len() >= MAX_INTERVAL_EVENTS {
+ self.dropped_events += 1;
+ } else {
+ self.events.push(event);
+ }
+ }
+
+ fn push_small_polls(&mut self, flush: SmallPollFlush) {
+ if self.small_polls.len() >= MAX_INTERVAL_EVENTS
+ && let Some(last) = self.small_polls.last_mut()
+ {
+ // Degrade gracefully at the cap: widen the last flush's span
+ // instead of dropping poll time, at the cost of coarser
+ // apportioning.
+ last.summary.add(flush.summary);
+ last.since = last.since.min(flush.since);
+ last.until = last.until.max(flush.until);
+ } else {
+ self.small_polls.push(flush);
+ }
+ }
+
+ fn seal(&mut self, boundary: IntervalBoundary) -> FrameSnapshot {
+ let ended = boundary.end_time();
+ let snapshot = FrameSnapshot {
+ interval_start: self.interval_start,
+ boundary,
+ events: std::mem::take(&mut self.events),
+ small_polls: std::mem::take(&mut self.small_polls),
+ dropped_events: std::mem::take(&mut self.dropped_events),
+ journal_discontinuous: std::mem::take(&mut self.journal_discontinuous),
+ };
+ self.interval_start = ended;
+ snapshot
+ }
+}
+
+#[cfg(test)]
+mod tests {
+ use proptest::prelude::*;
+ use scheduler::SpawnTime;
+
+ use super::*;
+ use crate::{WindowId, profiler::YieldTime};
+
+ #[test]
+ fn draw_waits_for_its_presentation_boundary() {
+ let start = Instant::now();
+ let input = InputTiming {
+ kind: "test",
+ start: start + Duration::from_millis(1),
+ end: start + Duration::from_millis(2),
+ caused_invalidation: true,
+ };
+ let frame = FrameTiming {
+ window_id: WindowId::from(1),
+ dirty_at: Some(input.start),
+ invalidations: 1,
+ draw_start: start + Duration::from_millis(3),
+ draw_end: start + Duration::from_millis(4),
+ };
+ let presentation = PresentTiming {
+ window_id: frame.window_id,
+ present_start: start + Duration::from_millis(5),
+ present_end: start + Duration::from_millis(6),
+ animation_interval: None,
+ };
+ let mut sealer = IntervalSealer::new(start);
+
+ let snapshots = sealer.push_entries([
+ ForegroundJournalEntry::Event(ForegroundEvent::Input(input)),
+ ForegroundJournalEntry::Event(ForegroundEvent::Draw(frame)),
+ ]);
+ assert!(snapshots.is_empty());
+
+ let snapshots = sealer.push_entries([ForegroundJournalEntry::Boundary(
+ IntervalBoundary::Presented(PresentedFrame {
+ frame,
+ presentation,
+ }),
+ )]);
+ let [snapshot] = snapshots.as_slice() else {
+ panic!("expected one presentation-sealed snapshot, got {snapshots:?}");
+ };
+ assert_eq!(snapshot.interval_start, input.start);
+ assert_eq!(snapshot.interval_end(), presentation.present_end);
+ assert_eq!(snapshot.events.len(), 3);
+ assert!(matches!(
+ snapshot.events.last(),
+ Some(ForegroundEvent::Present(timing))
+ if timing.present_duration() == Duration::from_millis(1)
+ ));
+ assert_eq!(
+ match snapshot.boundary {
+ IntervalBoundary::Presented(presented) => {
+ presented.dirty_to_present_duration()
+ }
+ IntervalBoundary::Idle { .. } => None,
+ },
+ Some(Duration::from_millis(5))
+ );
+ }
+
+ #[test]
+ fn outermost_turn_seals_no_frame_work_when_idle() {
+ let start = Instant::now();
+ let counter = ForegroundRunnableCounter::new();
+ let (mut journal, mut collector) = test_journal(counter);
+ let events = [
+ ForegroundEvent::Input(InputTiming {
+ kind: "test",
+ start,
+ end: start + Duration::from_millis(1),
+ caused_invalidation: false,
+ }),
+ ForegroundEvent::Action(ActionTiming {
+ name: "test.action",
+ start: start + Duration::from_millis(2),
+ end: start + Duration::from_millis(3),
+ }),
+ ForegroundEvent::TaskPoll(task_timing(
+ start + Duration::from_millis(4),
+ start + Duration::from_millis(5),
+ )),
+ ];
+
+ for event in events {
+ journal.begin_turn();
+ journal.record_event(event);
+ journal.end_turn(event.end_time());
+ }
+
+ let entries = collector.collect_unseen().entries;
+ for event in events {
+ assert!(entries.iter().any(|entry| {
+ matches!(
+ entry,
+ ForegroundJournalEntry::Boundary(IntervalBoundary::Idle { ended_at })
+ if *ended_at == event.end_time()
+ )
+ }));
+ }
+ }
+
+ #[test]
+ fn nested_turns_only_seal_after_the_outermost_turn() {
+ let start = Instant::now();
+ let (mut journal, mut collector) = test_journal(ForegroundRunnableCounter::new());
+ let action = ForegroundEvent::Action(ActionTiming {
+ name: "test.action",
+ start,
+ end: start + Duration::from_millis(1),
+ });
+ let input = ForegroundEvent::Input(InputTiming {
+ kind: "test",
+ start,
+ end: start + Duration::from_millis(2),
+ caused_invalidation: false,
+ });
+
+ journal.begin_turn();
+ journal.begin_turn();
+ journal.record_event(action);
+ journal.end_turn(action.end_time());
+ assert!(!has_boundary_at(
+ &collector.collect_unseen().entries,
+ action.end_time()
+ ));
+
+ journal.record_event(input);
+ journal.end_turn(input.end_time());
+ assert!(collector.collect_unseen().entries.iter().any(|entry| {
+ matches!(
+ entry,
+ ForegroundJournalEntry::Boundary(IntervalBoundary::Idle { ended_at })
+ if *ended_at == input.end_time()
+ )
+ }));
+ }
+
+ #[test]
+ fn an_immediately_ready_runnable_prevents_an_idle_boundary_between_polls() {
+ let start = Instant::now();
+ let counter = ForegroundRunnableCounter::new();
+ let (mut journal, mut collector) = test_journal(counter.clone());
+ counter.queued();
+ counter.queued();
+
+ let first = ForegroundEvent::TaskPoll(task_timing(start, start + Duration::from_millis(1)));
+ journal.begin_turn();
+ journal.record_event(first);
+ counter.finished();
+ journal.end_turn(first.end_time());
+ assert!(!has_boundary_at(
+ &collector.collect_unseen().entries,
+ first.end_time()
+ ));
+
+ let second = ForegroundEvent::TaskPoll(task_timing(
+ start + Duration::from_millis(2),
+ start + Duration::from_millis(3),
+ ));
+ journal.begin_turn();
+ journal.record_event(second);
+ counter.finished();
+ journal.end_turn(second.end_time());
+ assert!(collector.collect_unseen().entries.iter().any(|entry| {
+ matches!(
+ entry,
+ ForegroundJournalEntry::Boundary(IntervalBoundary::Idle { ended_at })
+ if *ended_at == second.end_time()
+ )
+ }));
+ }
+
+ #[test]
+ fn a_pending_frame_prevents_idle_until_presentation() {
+ let start = Instant::now();
+ let window_id = WindowId::from(0xD17A);
+ let (mut journal, mut collector) = test_journal(ForegroundRunnableCounter::new());
+ journal.record_frame_pending(window_id, start);
+ journal.begin_turn();
+ journal.record_event(ForegroundEvent::Input(InputTiming {
+ kind: "test",
+ start,
+ end: start + Duration::from_millis(1),
+ caused_invalidation: true,
+ }));
+ let input_end = start + Duration::from_millis(1);
+ journal.end_turn(input_end);
+ assert!(!has_boundary_at(
+ &collector.collect_unseen().entries,
+ input_end
+ ));
+
+ let frame = frame_timing(window_id, start, start + Duration::from_millis(2));
+ let presentation = presentation_timing(window_id, start + Duration::from_millis(3));
+ journal.record_present(presentation, Some(frame));
+ assert!(collector.collect_unseen().entries.iter().any(|entry| {
+ matches!(
+ entry,
+ ForegroundJournalEntry::Boundary(IntervalBoundary::Presented(presented))
+ if presented.frame.window_id == window_id
+ )
+ }));
+ }
+
+ #[test]
+ fn a_present_without_a_draw_clears_the_window_pending_state() {
+ let start = Instant::now();
+ let presented_at = start + Duration::from_millis(1);
+ let window_id = WindowId::from(0xD17B);
+ let (mut journal, mut collector) = test_journal(ForegroundRunnableCounter::new());
+ journal.record_frame_pending(window_id, start);
+ journal.begin_turn();
+ journal.record_present(presentation_timing(window_id, presented_at), None);
+ journal.end_turn(presented_at);
+
+ let entries = collector.collect_unseen().entries;
+ assert!(entries.iter().any(|entry| {
+ matches!(
+ entry,
+ ForegroundJournalEntry::Event(ForegroundEvent::Present(timing))
+ if timing.window_id == window_id
+ )
+ }));
+ assert!(has_boundary_at(&entries, presented_at));
+ }
+
+ /// A frame that outlives [`FRAME_DEADLINE`] no longer seals an interval
+ /// of its own: the work that starved it and its eventual presentation
+ /// stay in one interval, preserving the dirty-to-present association.
+ #[test]
+ fn a_presentation_after_the_deadline_seals_the_whole_interval() {
+ let start = Instant::now();
+ let window_id = WindowId::from(0xDEA1);
+ let presented_at = start + FRAME_DEADLINE + Duration::from_millis(250);
+ let mut sealer = IntervalSealer::new(start);
+ let snapshots = sealer.push_entries([
+ pending_frame(window_id, start),
+ input_entry(start, start + Duration::from_millis(20)),
+ ForegroundJournalEntry::Boundary(presented_boundary(window_id, start, presented_at)),
+ ]);
+ let [snapshot] = snapshots.as_slice() else {
+ panic!("expected one presented snapshot, got {snapshots:?}");
+ };
+ assert!(matches!(
+ snapshot.boundary,
+ IntervalBoundary::Presented(presented)
+ if presented.frame.window_id == window_id
+ && presented.dirty_to_present_duration()
+ == Some(presented_at.duration_since(start))
+ ));
+ assert_eq!(snapshot.interval_end(), presented_at);
+ assert_eq!(snapshot.events.len(), 2);
+ }
+
+ /// Frame expiry unblocks idle boundaries on the writer side: retained
+ /// work after the deadline seals at its turn's end even though the window
+ /// never presented.
+ #[test]
+ fn an_expired_frame_no_longer_blocks_idle_boundaries() {
+ let start = Instant::now();
+ let window_id = WindowId::from(0xDEA2);
+ let (mut journal, mut collector) = test_journal(ForegroundRunnableCounter::new());
+ journal.record_frame_pending(window_id, start);
+
+ let blocked_end = start + Duration::from_millis(20);
+ journal.begin_turn();
+ journal.record_event(ForegroundEvent::Input(InputTiming {
+ kind: "test",
+ start,
+ end: blocked_end,
+ caused_invalidation: true,
+ }));
+ journal.end_turn(blocked_end);
+ assert!(!has_boundary_at(
+ &collector.collect_unseen().entries,
+ blocked_end
+ ));
+
+ let unblocked_end = start + FRAME_DEADLINE + Duration::from_millis(1);
+ journal.begin_turn();
+ journal.record_event(ForegroundEvent::Input(InputTiming {
+ kind: "test",
+ start: start + FRAME_DEADLINE,
+ end: unblocked_end,
+ caused_invalidation: false,
+ }));
+ journal.end_turn(unblocked_end);
+ assert!(has_boundary_at(
+ &collector.collect_unseen().entries,
+ unblocked_end
+ ));
+ }
+
+ /// Closing a window clears its pending frame, so idle boundaries resume
+ /// without waiting for the deadline.
+ #[test]
+ fn closing_a_window_unblocks_idle_boundaries() {
+ let start = Instant::now();
+ let window_id = WindowId::from(0xDEA7);
+ let (mut journal, mut collector) = test_journal(ForegroundRunnableCounter::new());
+ journal.record_frame_pending(window_id, start);
+ journal.record_window_closed(window_id, start + Duration::from_millis(1));
+
+ let event_end = start + Duration::from_millis(2);
+ journal.begin_turn();
+ journal.record_event(ForegroundEvent::Input(InputTiming {
+ kind: "test",
+ start: start + Duration::from_millis(1),
+ end: event_end,
+ caused_invalidation: false,
+ }));
+ journal.end_turn(event_end);
+ assert!(has_boundary_at(
+ &collector.collect_unseen().entries,
+ event_end
+ ));
+ }
+
+ /// One window presenting must not unblock idle boundaries while another
+ /// window's unexpired frame is still pending.
+ #[test]
+ fn presenting_one_window_does_not_clear_another_pending_window() {
+ let start = Instant::now();
+ let first_window = WindowId::from(0xDEA5);
+ let second_window = WindowId::from(0xDEA6);
+ let (mut journal, mut collector) = test_journal(ForegroundRunnableCounter::new());
+ journal.record_frame_pending(first_window, start);
+ journal.record_frame_pending(second_window, start + Duration::from_millis(100));
+ journal.record_present(
+ presentation_timing(first_window, start + Duration::from_millis(500)),
+ Some(frame_timing(
+ first_window,
+ start,
+ start + Duration::from_millis(500),
+ )),
+ );
+
+ let event_end = start + Duration::from_millis(620);
+ journal.begin_turn();
+ journal.record_event(ForegroundEvent::Input(InputTiming {
+ kind: "test",
+ start: start + Duration::from_millis(600),
+ end: event_end,
+ caused_invalidation: false,
+ }));
+ journal.end_turn(event_end);
+
+ let entries = collector.collect_unseen().entries;
+ assert!(entries.iter().any(|entry| {
+ matches!(
+ entry,
+ ForegroundJournalEntry::Boundary(IntervalBoundary::Presented(presented))
+ if presented.frame.window_id == first_window
+ )
+ }));
+ assert!(!has_boundary_at(&entries, event_end));
+ }
+
+ #[test]
+ fn small_polls_are_flushed_immediately_before_a_retained_event() {
+ let start = Instant::now();
+ let first = task_timing(
+ start + Duration::from_millis(1),
+ start + Duration::from_millis(1) + Duration::from_micros(20),
+ );
+ let second = task_timing(
+ start + Duration::from_millis(3),
+ start + Duration::from_millis(3) + Duration::from_micros(30),
+ );
+ let input = InputTiming {
+ kind: "test",
+ start: start + Duration::from_millis(5),
+ end: start + Duration::from_millis(6),
+ caused_invalidation: false,
+ };
+ let (mut journal, mut collector) = test_journal(ForegroundRunnableCounter::new());
+
+ journal.fold_small_poll(first);
+ journal.fold_small_poll(second);
+ journal.record_event(ForegroundEvent::Input(input));
+
+ let drained = collector.collect_unseen();
+ let input_index = drained
+ .entries
+ .iter()
+ .position(|entry| {
+ matches!(
+ entry,
+ ForegroundJournalEntry::Event(ForegroundEvent::Input(timing))
+ if timing.start == input.start
+ )
+ })
+ .expect("input event should be retained");
+ let Some(ForegroundJournalEntry::Event(ForegroundEvent::SmallPolls(flush))) = input_index
+ .checked_sub(1)
+ .and_then(|index| drained.entries.get(index))
+ else {
+ panic!("small-poll summary should immediately precede the input event");
+ };
+ assert_eq!(flush.summary.count, 2);
+ assert_eq!(flush.summary.total, Duration::from_micros(50));
+ assert_eq!(flush.since, first.start);
+ assert_eq!(flush.until, second.end.0);
+ }
+
+ #[test]
+ fn small_polls_are_flushed_before_frame_state_changes() {
+ let start = Instant::now();
+ let window_id = WindowId::from(0xDEA9);
+ let poll = task_timing(start, start + Duration::from_micros(50));
+ let (mut journal, mut collector) = test_journal(ForegroundRunnableCounter::new());
+ journal.fold_small_poll(poll);
+ journal.record_frame_pending(window_id, poll.end.0);
+
+ let entries = collector.collect_unseen().entries;
+ let pending_index = entries
+ .iter()
+ .position(|entry| {
+ matches!(
+ entry,
+ ForegroundJournalEntry::FrameState(FrameStateChange::Pending {
+ window_id: pending_window,
+ ..
+ }) if *pending_window == window_id
+ )
+ })
+ .expect("pending frame should be retained");
+ assert!(matches!(
+ pending_index
+ .checked_sub(1)
+ .and_then(|index| entries.get(index)),
+ Some(ForegroundJournalEntry::Event(ForegroundEvent::SmallPolls(flush)))
+ if flush.since == poll.start && flush.until == poll.end.0
+ ));
+ }
+
+ /// Sporadic wake-ups (a tiny folded poll after which the foreground goes
+ /// idle, repeatedly) must write nothing to the ring and must not accumulate
+ /// toward a later retained interval.
+ #[test]
+ fn sparse_small_polls_are_discarded_when_the_foreground_returns_to_idle() {
+ let start = Instant::now();
+ let (mut journal, mut collector) = test_journal(ForegroundRunnableCounter::new());
+ let mut tiny_wake = |ended_at: Instant| {
+ journal.begin_turn();
+ journal.fold_small_poll(task_timing(ended_at - Duration::from_micros(50), ended_at));
+ journal.end_turn(ended_at);
+ };
+
+ for second in 1..=160 {
+ tiny_wake(start + Duration::from_secs(second));
+ }
+ let quiet = collector.collect_unseen().entries;
+ assert!(quiet.is_empty());
+
+ // A later retained event seals normally without inheriting the earlier
+ // folded-only wake-ups.
+ let retained = ForegroundEvent::TaskPoll(task_timing(
+ start + Duration::from_secs(161),
+ start + Duration::from_secs(161) + Duration::from_millis(1),
+ ));
+ journal.begin_turn();
+ journal.record_event(retained);
+ journal.end_turn(retained.end_time());
+ let entries = collector.collect_unseen().entries;
+ assert!(has_boundary_at(&entries, retained.end_time()));
+ assert!(!entries.iter().any(|entry| matches!(
+ entry,
+ ForegroundJournalEntry::Event(ForegroundEvent::SmallPolls(_))
+ )));
+ }
+
+ #[test]
+ fn note_lost_is_reported_on_the_next_snapshot_only() {
+ let start = Instant::now();
+ let mut sealer = IntervalSealer::new(start);
+ sealer.note_lost(7);
+
+ let snapshots = sealer.push_entries([
+ input_entry(start, start + Duration::from_millis(1)),
+ ForegroundJournalEntry::Boundary(IntervalBoundary::Idle {
+ ended_at: start + Duration::from_millis(1),
+ }),
+ input_entry(
+ start + Duration::from_millis(2),
+ start + Duration::from_millis(3),
+ ),
+ ForegroundJournalEntry::Boundary(IntervalBoundary::Idle {
+ ended_at: start + Duration::from_millis(3),
+ }),
+ ]);
+
+ assert_eq!(snapshots.len(), 2);
+ assert_eq!(snapshots[0].dropped_events, 7);
+ assert_eq!(snapshots[1].dropped_events, 0);
+ }
+
+ /// Ring losses must be able to surface even when every retained entry was
+ /// among the losses: a loss-only interval still seals at the next
+ /// boundary rather than sliding away as empty.
+ #[test]
+ fn losses_alone_seal_a_snapshot_at_the_next_boundary() {
+ let start = Instant::now();
+ let mut sealer = IntervalSealer::new(start);
+ sealer.note_lost(3);
+
+ let snapshots =
+ sealer.push_entries([ForegroundJournalEntry::Boundary(IntervalBoundary::Idle {
+ ended_at: start + Duration::from_millis(1),
+ })]);
+
+ assert_eq!(snapshots.len(), 1);
+ assert_eq!(snapshots[0].dropped_events, 3);
+ assert!(snapshots[0].events.is_empty());
+ }
+
+ #[test]
+ fn interval_event_cap_counts_overflowing_events() {
+ let start = Instant::now();
+ let mut sealer = IntervalSealer::new(start);
+ let overflow = 5;
+ let mut entries: Vec<ForegroundJournalEntry> = (0..(MAX_INTERVAL_EVENTS + overflow) as u64)
+ .map(|i| {
+ input_entry(
+ start + Duration::from_micros(i),
+ start + Duration::from_micros(i + 1),
+ )
+ })
+ .collect();
+ entries.push(ForegroundJournalEntry::Boundary(IntervalBoundary::Idle {
+ ended_at: start + Duration::from_micros((MAX_INTERVAL_EVENTS + overflow) as u64 + 1),
+ }));
+
+ let snapshots = sealer.push_entries(entries);
+
+ assert_eq!(snapshots.len(), 1);
+ assert_eq!(snapshots[0].events.len(), MAX_INTERVAL_EVENTS);
+ assert_eq!(snapshots[0].dropped_events, overflow as u64);
+ }
+
+ #[test]
+ fn collect_unseen_returns_each_entry_once_in_order() {
+ let start = Instant::now();
+ let (journal, mut publisher) = ForegroundJournal::new(32, 4);
+ let mut collector = journal.collector();
+ let timestamps: Vec<Instant> = (0..19)
+ .map(|i| start + Duration::from_micros(i as u64 + 1))
+ .collect();
+ publisher.publish(timestamps.iter().map(|&at| input_entry(at, at)));
+
+ let ours = |entries: &[ForegroundJournalEntry]| -> Vec<Instant> {
+ entries
+ .iter()
+ .filter_map(|entry| match entry {
+ ForegroundJournalEntry::Event(ForegroundEvent::Input(timing))
+ if timestamps.contains(&timing.end) =>
+ {
+ Some(timing.end)
+ }
+ _ => None,
+ })
+ .collect()
+ };
+
+ let drained = collector.collect_unseen();
+ assert_eq!(ours(&drained.entries), timestamps);
+
+ // The cursor advanced past everything: a second drain sees none of
+ // our entries again.
+ let drained = collector.collect_unseen();
+ assert!(ours(&drained.entries).is_empty());
+ }
+
+ #[test]
+ fn concurrent_collection_preserves_the_complete_logical_sequence() {
+ const ENTRY_COUNT: u64 = 20_000;
+
+ let origin = Instant::now();
+ let (journal, mut publisher) = ForegroundJournal::new(8, 4);
+ let mut collector = journal.collector();
+ let done = Arc::new(std::sync::atomic::AtomicBool::new(false));
+ let collector_done = Arc::clone(&done);
+ let collector_task = std::thread::spawn(move || {
+ let mut observed = Vec::new();
+ loop {
+ let drained = collector.collect_unseen();
+ observed.extend(normalize_ring_drain(origin, drained.entries));
+ if collector_done.load(Ordering::Acquire) {
+ let drained = collector.collect_unseen();
+ observed.extend(normalize_ring_drain(origin, drained.entries));
+ return (collector, observed);
+ }
+ std::thread::yield_now();
+ }
+ });
+
+ for sequence in 0..ENTRY_COUNT {
+ publisher.publish([ring_entry(origin, sequence)]);
+ }
+ done.store(true, Ordering::Release);
+
+ let (mut collector, mut observed) = collector_task
+ .join()
+ .expect("collector thread should not panic");
+ publisher.flush_pending();
+ observed.extend(normalize_ring_drain(
+ origin,
+ collector.collect_unseen().entries,
+ ));
+
+ let mut expected_sequence = 0;
+ for entry in observed {
+ match entry {
+ ModelDrainEntry::Entry(sequence) => {
+ assert_eq!(sequence, expected_sequence);
+ expected_sequence += 1;
+ }
+ ModelDrainEntry::Discontinuity(lost) => expected_sequence += lost,
+ }
+ }
+ assert_eq!(expected_sequence, ENTRY_COUNT);
+ assert_eq!(
+ publisher.ring.finalized.load(Ordering::Acquire),
+ ENTRY_COUNT
+ );
+ }
+
+ #[derive(Clone, Debug)]
+ enum RingOperation {
+ Publish,
+ Collect(u8),
+ NewCollector,
+ Pin(u8),
+ Unpin(u8),
+ }
+
+ #[derive(Clone, Debug, PartialEq, Eq)]
+ enum ModelDrainEntry {
+ Entry(u64),
+ Discontinuity(u64),
+ }
+
+ struct ModelRing {
+ capacity: usize,
+ pending_capacity: usize,
+ next_sequence: u64,
+ finalized: u64,
+ offered: u64,
+ slots: Vec<Option<(u64, u64)>>,
+ pinned: Vec<bool>,
+ pending: VecDeque<(u64, u64)>,
+ dropped_after_pending: u64,
+ }
+
+ impl ModelRing {
+ fn new(capacity: usize, pending_capacity: usize) -> Self {
+ Self {
+ capacity,
+ pending_capacity,
+ next_sequence: 0,
+ finalized: 0,
+ offered: 0,
+ slots: vec![None; capacity],
+ pinned: vec![false; capacity],
+ pending: VecDeque::new(),
+ dropped_after_pending: 0,
+ }
+ }
+
+ fn publish(&mut self) {
+ self.flush_pending();
+ let sequence = self.next_sequence;
+ self.next_sequence += 1;
+ self.offered = self.next_sequence;
+
+ if !self.pending.is_empty() || self.dropped_after_pending > 0 {
+ if self.dropped_after_pending == 0 && self.pending.len() < self.pending_capacity {
+ self.pending.push_back((sequence, sequence));
+ } else {
+ self.dropped_after_pending += 1;
+ }
+ } else {
+ let index = sequence as usize % self.capacity;
+ if self.pinned[index] {
+ if self.pending_capacity > 0 {
+ self.pending.push_back((sequence, sequence));
+ } else {
+ self.dropped_after_pending = 1;
+ }
+ } else {
+ self.slots[index] = Some((sequence, sequence));
+ self.finalized = sequence + 1;
+ }
+ }
+ self.flush_pending();
+ }
+
+ fn flush_pending(&mut self) {
+ while let Some(&(sequence, value)) = self.pending.front() {
+ let index = sequence as usize % self.capacity;
+ if self.pinned[index] {
+ return;
+ }
+ self.slots[index] = Some((sequence, value));
+ self.pending.pop_front();
+ self.finalized = sequence + 1;
+ }
+
+ if self.dropped_after_pending > 0 {
+ self.finalized = self.next_sequence;
+ self.dropped_after_pending = 0;
+ }
+ }
+
+ fn collect(&self, cursor: &mut u64) -> (Vec<ModelDrainEntry>, u64) {
+ let end = self.finalized;
+ if *cursor >= end {
+ return (Vec::new(), 0);
+ }
+
+ let retained_start = end.saturating_sub(self.capacity as u64);
+ let mut lost = retained_start.saturating_sub(*cursor);
+ *cursor = (*cursor).max(retained_start);
+ let mut entries = Vec::new();
+ if lost > 0 {
+ entries.push(ModelDrainEntry::Discontinuity(lost));
+ }
+ while *cursor < end {
+ let index = *cursor as usize % self.capacity;
+ match self.slots[index] {
+ Some((sequence, value)) if sequence == *cursor => {
+ entries.push(ModelDrainEntry::Entry(value));
+ }
+ _ => {
+ lost += 1;
+ match entries.last_mut() {
+ Some(ModelDrainEntry::Discontinuity(lost)) => *lost += 1,
+ _ => entries.push(ModelDrainEntry::Discontinuity(1)),
+ }
+ }
+ }
+ *cursor += 1;
+ }
+ (entries, lost)
+ }
+ }
+
+ fn ring_entry(origin: Instant, sequence: u64) -> ForegroundJournalEntry {
+ let at = origin + Duration::from_micros(sequence);
+ input_entry(at, at)
+ }
+
+ fn normalize_ring_drain(
+ origin: Instant,
+ entries: Vec<ForegroundJournalEntry>,
+ ) -> Vec<ModelDrainEntry> {
+ entries
+ .into_iter()
+ .map(|entry| match entry {
+ ForegroundJournalEntry::Event(ForegroundEvent::Input(timing)) => {
+ ModelDrainEntry::Entry(timing.start.duration_since(origin).as_micros() as u64)
+ }
+ ForegroundJournalEntry::Discontinuity { lost } => {
+ ModelDrainEntry::Discontinuity(lost)
+ }
+ other => panic!("ring property observed an unexpected entry: {other:?}"),
+ })
+ .collect()
+ }
+
+ #[derive(Debug, Clone, PartialEq, Eq)]
+ struct NormalizedEvent {
+ kind: u8,
+ start: u64,
+ end: u64,
+ }
+
+ #[derive(Debug, Clone, PartialEq, Eq)]
+ struct NormalizedSmallPolls {
+ count: u64,
+ total_micros: u64,
+ since: u64,
+ until: u64,
+ }
+
+ #[derive(Debug, Clone, PartialEq, Eq)]
+ struct NormalizedSnapshot {
+ interval_start: u64,
+ boundary_kind: u8,
+ interval_end: u64,
+ events: Vec<NormalizedEvent>,
+ small_polls: Vec<NormalizedSmallPolls>,
+ dropped_events: u64,
+ journal_discontinuous: bool,
+ }
+
+ #[derive(Debug, Clone, PartialEq, Eq)]
+ struct NormalizedSealerTail {
+ interval_start: u64,
+ events: Vec<NormalizedEvent>,
+ small_polls: Vec<NormalizedSmallPolls>,
+ dropped_events: u64,
+ journal_discontinuous: bool,
+ }
+
+ fn completion_order_entries(
+ origin: Instant,
+ specifications: &[(u8, u8, u8)],
+ ) -> Vec<ForegroundJournalEntry> {
+ let mut completed_at_micros = 1u64;
+ specifications
+ .iter()
+ .map(|(advance, span, kind)| {
+ completed_at_micros += u64::from(*advance) + 1;
+ let started_at_micros = completed_at_micros.saturating_sub(u64::from(*span));
+ let start = origin + Duration::from_micros(started_at_micros);
+ let end = origin + Duration::from_micros(completed_at_micros);
+ match kind % 7 {
+ 0 => input_entry(start, end),
+ 1 => ForegroundJournalEntry::Event(ForegroundEvent::Action(ActionTiming {
+ name: "test.action",
+ start,
+ end,
+ })),
+ 2 => ForegroundJournalEntry::Event(ForegroundEvent::TaskPoll(task_timing(
+ start, end,
+ ))),
+ 3 => {
+ ForegroundJournalEntry::Event(ForegroundEvent::SmallPolls(SmallPollFlush {
+ summary: PollSummary {
+ count: u64::from(*span % 5) + 1,
+ total: Duration::from_micros(u64::from(*span)),
+ },
+ since: start,
+ until: end,
+ }))
+ }
+ 4 => pending_frame(WindowId::from(completed_at_micros), start),
+ 5 => ForegroundJournalEntry::Boundary(IntervalBoundary::Idle { ended_at: end }),
+ _ => ForegroundJournalEntry::Boundary(presented_boundary(
+ WindowId::from(completed_at_micros),
+ start,
+ end,
+ )),
+ }
+ })
+ .collect()
+ }
+
+ fn normalize_event(origin: Instant, event: ForegroundEvent) -> NormalizedEvent {
+ let kind = match event {
+ ForegroundEvent::TaskPoll(_) => 0,
+ ForegroundEvent::Action(_) => 1,
+ ForegroundEvent::Input(_) => 2,
+ ForegroundEvent::Draw(_) => 3,
+ ForegroundEvent::Present(_) => 4,
+ ForegroundEvent::SmallPolls(_) => 5,
+ };
+ NormalizedEvent {
+ kind,
+ start: event.start_time().duration_since(origin).as_micros() as u64,
+ end: event.end_time().duration_since(origin).as_micros() as u64,
+ }
+ }
+
+ fn normalize_small_polls(origin: Instant, flush: SmallPollFlush) -> NormalizedSmallPolls {
+ NormalizedSmallPolls {
+ count: flush.summary.count,
+ total_micros: flush.summary.total.as_micros() as u64,
+ since: flush.since.duration_since(origin).as_micros() as u64,
+ until: flush.until.duration_since(origin).as_micros() as u64,
+ }
+ }
+
+ fn normalize_snapshot(origin: Instant, snapshot: &FrameSnapshot) -> NormalizedSnapshot {
+ NormalizedSnapshot {
+ interval_start: snapshot.interval_start.duration_since(origin).as_micros() as u64,
+ boundary_kind: match snapshot.boundary {
+ IntervalBoundary::Idle { .. } => 0,
+ IntervalBoundary::Presented(_) => 1,
+ },
+ interval_end: snapshot.interval_end().duration_since(origin).as_micros() as u64,
+ events: snapshot
+ .events
+ .iter()
+ .copied()
+ .map(|event| normalize_event(origin, event))
+ .collect(),
+ small_polls: snapshot
+ .small_polls
+ .iter()
+ .copied()
+ .map(|flush| normalize_small_polls(origin, flush))
+ .collect(),
+ dropped_events: snapshot.dropped_events,
+ journal_discontinuous: snapshot.journal_discontinuous,
+ }
+ }
+
+ fn normalize_tail(origin: Instant, sealer: &IntervalSealer) -> NormalizedSealerTail {
+ NormalizedSealerTail {
+ interval_start: sealer.interval_start.duration_since(origin).as_micros() as u64,
+ events: sealer
+ .events
+ .iter()
+ .copied()
+ .map(|event| normalize_event(origin, event))
+ .collect(),
+ small_polls: sealer
+ .small_polls
+ .iter()
+ .copied()
+ .map(|flush| normalize_small_polls(origin, flush))
+ .collect(),
+ dropped_events: sealer.dropped_events,
+ journal_discontinuous: sealer.journal_discontinuous,
+ }
+ }
+
+ fn reference_seal(
+ origin: Instant,
+ entries: &[ForegroundJournalEntry],
+ ) -> (Vec<NormalizedSnapshot>, NormalizedSealerTail) {
+ let mut interval_start = 0;
+ let mut events = Vec::new();
+ let mut small_polls = Vec::new();
+ let mut snapshots = Vec::new();
+ let mut dropped_events = 0;
+ let mut journal_discontinuous = false;
+
+ for entry in entries {
+ match *entry {
+ ForegroundJournalEntry::Event(event) => {
+ let event_start = event.start_time().duration_since(origin).as_micros() as u64;
+ if events.is_empty()
+ && small_polls.is_empty()
+ && dropped_events == 0
+ && !journal_discontinuous
+ {
+ interval_start = interval_start.max(event_start);
+ }
+ match event {
+ ForegroundEvent::SmallPolls(flush) => {
+ small_polls.push(normalize_small_polls(origin, flush));
+ }
+ event => events.push(normalize_event(origin, event)),
+ }
+ }
+ ForegroundJournalEntry::Boundary(boundary) => {
+ if let IntervalBoundary::Presented(presented) = boundary {
+ let present = ForegroundEvent::Present(presented.presentation);
+ if events.is_empty()
+ && small_polls.is_empty()
+ && dropped_events == 0
+ && !journal_discontinuous
+ {
+ interval_start =
+ interval_start
+ .max(present.start_time().duration_since(origin).as_micros()
+ as u64);
+ }
+ events.push(normalize_event(origin, present));
+ }
+
+ let interval_end =
+ boundary.end_time().duration_since(origin).as_micros() as u64;
+ if events.is_empty()
+ && small_polls.is_empty()
+ && dropped_events == 0
+ && !journal_discontinuous
+ {
+ interval_start = interval_start.max(interval_end);
+ } else {
+ snapshots.push(NormalizedSnapshot {
+ interval_start,
+ boundary_kind: match boundary {
+ IntervalBoundary::Idle { .. } => 0,
+ IntervalBoundary::Presented(_) => 1,
+ },
+ interval_end,
+ events: std::mem::take(&mut events),
+ small_polls: std::mem::take(&mut small_polls),
+ dropped_events: std::mem::take(&mut dropped_events),
+ journal_discontinuous: std::mem::take(&mut journal_discontinuous),
+ });
+ interval_start = interval_end;
+ }
+ }
+ ForegroundJournalEntry::FrameState(_) => {}
+ ForegroundJournalEntry::Discontinuity { lost } => {
+ dropped_events += lost;
+ journal_discontinuous = true;
+ }
+ }
+ }
+
+ (
+ snapshots,
+ NormalizedSealerTail {
+ interval_start,
+ events,
+ small_polls,
+ dropped_events,
+ journal_discontinuous,
+ },
+ )
+ }
+
+ fn reference_occupancy_micros(
+ event_spans: &[(u8, u8)],
+ small_poll_spans: &[(u8, u8, u8)],
+ window_start: u8,
+ window_end: u8,
+ ) -> u64 {
+ let mut clamped_spans = event_spans
+ .iter()
+ .map(|&(first, second)| {
+ let start = first.min(second).max(window_start);
+ let end = first.max(second).min(window_end).max(start);
+ (start, end)
+ })
+ .collect::<Vec<_>>();
+ clamped_spans.sort_unstable();
+
+ let mut occupied = 0u64;
+ let mut merged_until = None;
+ for (start, end) in clamped_spans {
+ let start = merged_until.map_or(start, |until| start.max(until));
+ occupied += u64::from(end.saturating_sub(start));
+ merged_until = Some(merged_until.map_or(end, |until| until.max(end)));
+ }
+
+ occupied
+ + small_poll_spans
+ .iter()
+ .map(|&(first, second, factor)| {
+ let since = first.min(second);
+ let until = first.max(second);
+ if since == until {
+ if since >= window_start && since <= window_end {
+ u64::from(factor)
+ } else {
+ 0
+ }
+ } else {
+ let overlap_start = since.max(window_start);
+ let overlap_end = until.min(window_end).max(overlap_start);
+ u64::from(overlap_end - overlap_start) * u64::from(factor)
+ }
+ })
+ .sum::<u64>()
+ }
+
+ #[derive(Debug, Clone)]
+ struct WriterOperation {
+ kind: u8,
+ advance: u16,
+ argument: u8,
+ }
+
+ #[derive(Debug, Clone, PartialEq, Eq)]
+ enum WriterEntry {
+ Input(u64),
+ SmallPolls {
+ count: u64,
+ total_micros: u64,
+ since: u64,
+ until: u64,
+ },
+ Pending {
+ window: u64,
+ at: u64,
+ },
+ Closed {
+ window: u64,
+ at: u64,
+ },
+ Present {
+ window: u64,
+ at: u64,
+ },
+ Presented {
+ window: u64,
+ at: u64,
+ },
+ Idle(u64),
+ }
+
+ #[derive(Default)]
+ struct ModelSmallPolls {
+ count: u64,
+ total_micros: u64,
+ since: u64,
+ until: u64,
+ }
+
+ #[derive(Default)]
+ struct ModelWriter {
+ turn_depth: usize,
+ runnables: usize,
+ pending_frames: HashMap<u64, u64>,
+ retained_since_boundary: bool,
+ small_polls: Option<ModelSmallPolls>,
+ entries: Vec<WriterEntry>,
+ }
+
+ impl ModelWriter {
+ fn record_entry(&mut self, entry: WriterEntry) {
+ if let Some(small_polls) = self.small_polls.take() {
+ self.entries.push(WriterEntry::SmallPolls {
+ count: small_polls.count,
+ total_micros: small_polls.total_micros,
+ since: small_polls.since,
+ until: small_polls.until,
+ });
+ }
+ let boundary = matches!(entry, WriterEntry::Presented { .. } | WriterEntry::Idle(_));
+ self.entries.push(entry);
+ if boundary {
+ self.retained_since_boundary = false;
+ }
+ }
+
+ fn record_input(&mut self, at: u64) {
+ self.retained_since_boundary = true;
+ self.record_entry(WriterEntry::Input(at));
+ }
+
+ fn fold_small_poll(&mut self, since: u64, until: u64) {
+ let small_polls = self.small_polls.get_or_insert(ModelSmallPolls {
+ since,
+ until,
+ ..ModelSmallPolls::default()
+ });
+ small_polls.count += 1;
+ small_polls.total_micros += until - since;
+ small_polls.since = small_polls.since.min(since);
+ small_polls.until = small_polls.until.max(until);
+ }
+
+ fn record_pending(&mut self, window: u64, at: u64) {
+ let should_record = self
+ .pending_frames
+ .get(&window)
+ .is_none_or(|previous| at.saturating_sub(*previous) >= 1_000_000);
+ if should_record {
+ self.pending_frames.insert(window, at);
+ self.record_entry(WriterEntry::Pending { window, at });
+ }
+ }
+
+ fn record_closed(&mut self, window: u64, at: u64) {
+ self.pending_frames.remove(&window);
+ self.record_entry(WriterEntry::Closed { window, at });
+ }
+
+ fn record_present(&mut self, window: u64, at: u64, has_frame: bool) {
+ if has_frame {
+ self.pending_frames.remove(&window);
+ self.record_entry(WriterEntry::Presented { window, at });
+ } else {
+ self.pending_frames.remove(&window);
+ self.retained_since_boundary = true;
+ self.record_entry(WriterEntry::Present { window, at });
+ }
+ }
+
+ fn end_turn(&mut self, at: u64) {
+ if self.turn_depth == 0 {
+ return;
+ }
+ self.turn_depth -= 1;
+ if self.turn_depth > 0 || self.runnables > 0 {
+ return;
+ }
+ self.pending_frames
+ .retain(|_, dirty_at| at.saturating_sub(*dirty_at) < 1_000_000);
+ if !self.pending_frames.is_empty() {
+ return;
+ }
+ if !self.retained_since_boundary {
+ self.small_polls = None;
+ return;
+ }
+ self.record_entry(WriterEntry::Idle(at));
+ }
+ }
+
+ fn normalize_writer_entries(
+ origin: Instant,
+ entries: Vec<ForegroundJournalEntry>,
+ ) -> Vec<WriterEntry> {
+ let at = |instant: Instant| instant.duration_since(origin).as_micros() as u64;
+ entries
+ .into_iter()
+ .map(|entry| match entry {
+ ForegroundJournalEntry::Event(ForegroundEvent::Input(timing)) => {
+ WriterEntry::Input(at(timing.end))
+ }
+ ForegroundJournalEntry::Event(ForegroundEvent::SmallPolls(flush)) => {
+ WriterEntry::SmallPolls {
+ count: flush.summary.count,
+ total_micros: flush.summary.total.as_micros() as u64,
+ since: at(flush.since),
+ until: at(flush.until),
+ }
+ }
+ ForegroundJournalEntry::Event(ForegroundEvent::Present(timing)) => {
+ WriterEntry::Present {
+ window: timing.window_id.as_u64(),
+ at: at(timing.present_end),
+ }
+ }
+ ForegroundJournalEntry::FrameState(FrameStateChange::Pending {
+ window_id,
+ dirty_at,
+ }) => WriterEntry::Pending {
+ window: window_id.as_u64(),
+ at: at(dirty_at),
+ },
+ ForegroundJournalEntry::FrameState(FrameStateChange::Closed {
+ window_id,
+ at: closed_at,
+ }) => WriterEntry::Closed {
+ window: window_id.as_u64(),
+ at: at(closed_at),
+ },
+ ForegroundJournalEntry::Boundary(IntervalBoundary::Presented(presented)) => {
+ WriterEntry::Presented {
+ window: presented.frame.window_id.as_u64(),
+ at: at(presented.presentation.present_end),
+ }
+ }
+ ForegroundJournalEntry::Boundary(IntervalBoundary::Idle { ended_at }) => {
+ WriterEntry::Idle(at(ended_at))
+ }
+ other => panic!("writer property emitted an unexpected entry: {other:?}"),
+ })
+ .collect()
+ }
+
+ proptest! {
+ #![proptest_config(ProptestConfig {
+ failure_persistence: None,
+ ..ProptestConfig::default()
+ })]
+
+ #[test]
+ fn ring_matches_reference_model_under_wrap_collisions_and_independent_cursors(
+ capacity in 1usize..=8,
+ pending_capacity in 0usize..=4,
+ operations in prop::collection::vec(
+ prop_oneof![
+ 5 => Just(RingOperation::Publish),
+ 3 => any::<u8>().prop_map(RingOperation::Collect),
+ 1 => Just(RingOperation::NewCollector),
+ 2 => any::<u8>().prop_map(RingOperation::Pin),
+ 2 => any::<u8>().prop_map(RingOperation::Unpin),
+ ],
+ 1..=128,
+ ),
+ ) {
+ let origin = Instant::now();
+ let (journal, mut publisher) = ForegroundJournal::new(capacity, pending_capacity);
+ let mut collectors = vec![journal.collector()];
+ let mut model_collectors = vec![0];
+ let mut model = ModelRing::new(capacity, pending_capacity);
+ let mut pins: Vec<Option<JournalSlotReadGuard<'_>>> =
+ (0..capacity).map(|_| None).collect();
+
+ for operation in operations {
+ match operation {
+ RingOperation::Publish => {
+ let sequence = model.next_sequence;
+ publisher.publish([ring_entry(origin, sequence)]);
+ model.publish();
+ }
+ RingOperation::Collect(collector) => {
+ let index = usize::from(collector) % collectors.len();
+ let drained = collectors[index].collect_unseen();
+ let (expected_entries, expected_lost) =
+ model.collect(&mut model_collectors[index]);
+ let observed_entries = normalize_ring_drain(origin, drained.entries);
+ prop_assert_eq!(observed_entries, expected_entries);
+ prop_assert_eq!(drained.lost, expected_lost);
+ }
+ RingOperation::NewCollector if collectors.len() < 4 => {
+ collectors.push(journal.collector());
+ model_collectors.push(model.offered);
+ }
+ RingOperation::NewCollector => {}
+ RingOperation::Pin(slot) => {
+ let index = usize::from(slot) % capacity;
+ if pins[index].is_none() {
+ pins[index] = JournalSlotReadGuard::try_new(&journal.ring.slots[index]);
+ prop_assert!(pins[index].is_some());
+ model.pinned[index] = true;
+ }
+ }
+ RingOperation::Unpin(slot) => {
+ let index = usize::from(slot) % capacity;
+ pins[index].take();
+ model.pinned[index] = false;
+ }
+ }
+
+ prop_assert_eq!(publisher.next_sequence, model.next_sequence);
+ prop_assert_eq!(
+ publisher.ring.offered.load(Ordering::Acquire),
+ model.offered
+ );
+ prop_assert_eq!(
+ publisher.ring.finalized.load(Ordering::Acquire),
+ model.finalized
+ );
+ prop_assert_eq!(
+ publisher
+ .pending
+ .iter()
+ .map(|entry| entry.sequence)
+ .collect::<Vec<_>>(),
+ model
+ .pending
+ .iter()
+ .map(|(sequence, _)| *sequence)
+ .collect::<Vec<_>>()
+ );
+ prop_assert_eq!(
+ publisher.dropped_after_pending,
+ model.dropped_after_pending
+ );
+ }
+
+ for pin in &mut pins {
+ pin.take();
+ }
+ model.pinned.fill(false);
+ publisher.flush_pending();
+ model.flush_pending();
+
+ for (collector, model_cursor) in collectors.iter_mut().zip(&mut model_collectors) {
+ let drained = collector.collect_unseen();
+ let (expected_entries, expected_lost) = model.collect(model_cursor);
+ let observed_entries = normalize_ring_drain(origin, drained.entries);
+ prop_assert_eq!(observed_entries, expected_entries);
+ prop_assert_eq!(drained.lost, expected_lost);
+ }
+ }
+
+ #[test]
+ fn a_presentation_seals_exactly_once_regardless_of_delay(
+ present_delay_micros in 1u64..=2_000_000
+ ) {
+ let start = Instant::now();
+ let window_id = WindowId::from(0xDEA8);
+ let presented_at = start + Duration::from_micros(present_delay_micros);
+ let mut sealer = IntervalSealer::new(start);
+ let snapshots = sealer.push_entries([
+ pending_frame(window_id, start),
+ input_entry(start, start + Duration::from_micros(1)),
+ ForegroundJournalEntry::Boundary(presented_boundary(
+ window_id,
+ start,
+ presented_at,
+ )),
+ ]);
+
+ prop_assert_eq!(snapshots.len(), 1);
+ prop_assert!(matches!(
+ snapshots[0].boundary,
+ IntervalBoundary::Presented(_)
+ ));
+ prop_assert_eq!(snapshots[0].interval_end(), presented_at);
+ }
+
+ #[test]
+ fn completion_order_sealer_matches_reference_under_arbitrary_batching(
+ specifications in prop::collection::vec((0u8..16, 0u8..128, any::<u8>()), 1..=96),
+ batch_sizes in prop::collection::vec(1usize..=12, 1..=24),
+ ) {
+ let origin = Instant::now();
+ let entries = completion_order_entries(origin, &specifications);
+ let (expected_snapshots, expected_tail) = reference_seal(origin, &entries);
+
+ let mut one_batch_sealer = IntervalSealer::new(origin);
+ let one_batch_snapshots = one_batch_sealer
+ .push_entries(entries.iter().copied())
+ .iter()
+ .map(|snapshot| normalize_snapshot(origin, snapshot))
+ .collect::<Vec<_>>();
+ prop_assert_eq!(&one_batch_snapshots, &expected_snapshots);
+ prop_assert_eq!(&normalize_tail(origin, &one_batch_sealer), &expected_tail);
+
+ let mut batched_sealer = IntervalSealer::new(origin);
+ let mut batched_snapshots = Vec::new();
+ let mut offset = 0;
+ let mut batch_index = 0;
+ while offset < entries.len() {
+ let batch_size = batch_sizes[batch_index % batch_sizes.len()];
+ let batch_end = (offset + batch_size).min(entries.len());
+ batched_snapshots.extend(
+ batched_sealer
+ .push_entries(entries[offset..batch_end].iter().copied())
+ .iter()
+ .map(|snapshot| normalize_snapshot(origin, snapshot)),
+ );
+ offset = batch_end;
+ batch_index += 1;
+ }
+ prop_assert_eq!(batched_snapshots, expected_snapshots);
+ prop_assert_eq!(normalize_tail(origin, &batched_sealer), expected_tail);
+ }
+
+ #[test]
+ fn occupancy_matches_interval_union_and_fold_apportionment(
+ event_spans in prop::collection::vec((0u8..=128, 0u8..=128), 0..=16),
+ small_poll_spans in prop::collection::vec(
+ (0u8..=128, 0u8..=128, 0u8..=4),
+ 0..=12,
+ ),
+ window in (0u8..=128, 0u8..=128),
+ ) {
+ let origin = Instant::now();
+ let window_start_micros = window.0.min(window.1);
+ let window_end_micros = window.0.max(window.1);
+ let events = event_spans
+ .iter()
+ .map(|&(first, second)| {
+ let start = origin + Duration::from_micros(u64::from(first.min(second)));
+ let end = origin + Duration::from_micros(u64::from(first.max(second)));
+ ForegroundEvent::Input(InputTiming {
+ kind: "test",
+ start,
+ end,
+ caused_invalidation: false,
+ })
+ })
+ .collect();
+ let small_polls = small_poll_spans
+ .iter()
+ .map(|&(first, second, factor)| {
+ let since_micros = first.min(second);
+ let until_micros = first.max(second);
+ let span_micros = u64::from(until_micros - since_micros);
+ let total_micros = if span_micros == 0 {
+ u64::from(factor)
+ } else {
+ span_micros * u64::from(factor)
+ };
+ SmallPollFlush {
+ summary: PollSummary {
+ count: 1,
+ total: Duration::from_micros(total_micros),
+ },
+ since: origin + Duration::from_micros(u64::from(since_micros)),
+ until: origin + Duration::from_micros(u64::from(until_micros)),
+ }
+ })
+ .collect();
+ let snapshot = FrameSnapshot {
+ interval_start: origin,
+ boundary: IntervalBoundary::Idle {
+ ended_at: origin + Duration::from_micros(128),
+ },
+ events,
+ small_polls,
+ dropped_events: 0,
+ journal_discontinuous: false,
+ };
+ let expected_micros = reference_occupancy_micros(
+ &event_spans,
+ &small_poll_spans,
+ window_start_micros,
+ window_end_micros,
+ );
+ let observed = snapshot.occupancy_within(
+ origin + Duration::from_micros(u64::from(window_start_micros)),
+ origin + Duration::from_micros(u64::from(window_end_micros)),
+ );
+
+ prop_assert_eq!(observed, Duration::from_micros(expected_micros));
+
+ let full_expected =
+ reference_occupancy_micros(&event_spans, &small_poll_spans, 0, 128);
+ prop_assert_eq!(snapshot.occupancy(), Duration::from_micros(full_expected));
+ prop_assert!((0.0..=1.0).contains(&snapshot.busy_fraction()));
+ prop_assert_eq!(
+ snapshot.busy_fraction(),
+ (full_expected as f64 / 128.0).min(1.0)
+ );
+ }
+
+ #[test]
+ fn writer_matches_state_model_across_turn_frame_and_runnable_transitions(
+ operations in prop::collection::vec(
+ (any::<u8>(), any::<u16>(), any::<u8>()).prop_map(
+ |(kind, advance, argument)| WriterOperation {
+ kind,
+ advance,
+ argument,
+ },
+ ),
+ 1..=128,
+ ),
+ ) {
+ let origin = Instant::now();
+ let counter = ForegroundRunnableCounter::new();
+ let (mut writer, mut collector) = test_journal(counter.clone());
+ let mut model = ModelWriter::default();
+ let mut at_micros = 100u64;
+
+ for operation in operations {
+ if operation.advance % 16 == 0 {
+ at_micros += FRAME_DEADLINE.as_micros() as u64;
+ } else {
+ at_micros += u64::from(operation.advance) + 1;
+ }
+ let at = origin + Duration::from_micros(at_micros);
+ let window_id = WindowId::from(u64::from(operation.argument % 4));
+ let window = window_id.as_u64();
+
+ match operation.kind % 10 {
+ 0 => {
+ writer.begin_turn();
+ model.turn_depth += 1;
+ }
+ 1 if model.turn_depth > 0 => {
+ writer.end_turn(at);
+ model.end_turn(at_micros);
+ }
+ 1 => {}
+ 2 => {
+ writer.record_event(ForegroundEvent::Input(InputTiming {
+ kind: "test",
+ start: at,
+ end: at,
+ caused_invalidation: false,
+ }));
+ model.record_input(at_micros);
+ }
+ 3 => {
+ let duration_micros = u64::from(operation.argument % 100);
+ writer.fold_small_poll(task_timing(
+ at - Duration::from_micros(duration_micros),
+ at,
+ ));
+ model.fold_small_poll(
+ at_micros - duration_micros,
+ at_micros,
+ );
+ }
+ 4 => {
+ counter.queued();
+ model.runnables += 1;
+ }
+ 5 if model.runnables > 0 => {
+ counter.finished();
+ model.runnables -= 1;
+ }
+ 5 => {}
+ 6 => {
+ writer.record_frame_pending(window_id, at);
+ model.record_pending(window, at_micros);
+ }
+ 7 => {
+ writer.record_window_closed(window_id, at);
+ model.record_closed(window, at_micros);
+ }
+ 8 => {
+ writer.record_present(
+ presentation_timing(window_id, at),
+ Some(frame_timing(window_id, at, at)),
+ );
+ model.record_present(window, at_micros, true);
+ }
+ _ => {
+ writer.record_present(presentation_timing(window_id, at), None);
+ model.record_present(window, at_micros, false);
+ }
+ }
+
+ let drained = collector.collect_unseen();
+ prop_assert_eq!(drained.lost, 0);
+ prop_assert_eq!(
+ normalize_writer_entries(origin, drained.entries),
+ std::mem::take(&mut model.entries)
+ );
+ prop_assert_eq!(writer.turn_depth, model.turn_depth);
+ prop_assert_eq!(writer.retained_since_boundary, model.retained_since_boundary);
+ prop_assert_eq!(writer.pending_frames.len(), model.pending_frames.len());
+ }
+ }
+ }
+
+ fn test_journal(
+ foreground_runnables: ForegroundRunnableCounter,
+ ) -> (ForegroundJournalWriter, ForegroundJournalCollector) {
+ let (journal, publisher) = ForegroundJournal::new(256, 8);
+ let collector = journal.collector();
+ (
+ ForegroundJournalWriter::new(foreground_runnables, publisher),
+ collector,
+ )
+ }
+
+ fn has_boundary_at(entries: &[ForegroundJournalEntry], at: Instant) -> bool {
+ entries.iter().any(|entry| {
+ matches!(entry, ForegroundJournalEntry::Boundary(boundary) if boundary.end_time() == at)
+ })
+ }
+
+ fn input_entry(start: Instant, end: Instant) -> ForegroundJournalEntry {
+ ForegroundJournalEntry::Event(ForegroundEvent::Input(InputTiming {
+ kind: "test",
+ start,
+ end,
+ caused_invalidation: false,
+ }))
+ }
+
+ fn pending_frame(window_id: WindowId, dirty_at: Instant) -> ForegroundJournalEntry {
+ ForegroundJournalEntry::FrameState(FrameStateChange::Pending {
+ window_id,
+ dirty_at,
+ })
+ }
+
+ fn frame_timing(window_id: WindowId, dirty_at: Instant, draw_end: Instant) -> FrameTiming {
+ FrameTiming {
+ window_id,
+ dirty_at: Some(dirty_at),
+ invalidations: 1,
+ draw_start: draw_end,
+ draw_end,
+ }
+ }
+
+ fn presentation_timing(window_id: WindowId, present_end: Instant) -> PresentTiming {
+ PresentTiming {
+ window_id,
+ present_start: present_end,
+ present_end,
+ animation_interval: None,
+ }
+ }
+
+ fn presented_boundary(
+ window_id: WindowId,
+ dirty_at: Instant,
+ present_end: Instant,
+ ) -> IntervalBoundary {
+ IntervalBoundary::Presented(PresentedFrame {
+ frame: frame_timing(window_id, dirty_at, present_end),
+ presentation: presentation_timing(window_id, present_end),
+ })
+ }
+
+ fn task_timing(start: Instant, end: Instant) -> TaskTiming {
+ TaskTiming {
+ location: std::panic::Location::caller(),
+ spawned: SpawnTime(start),
+ start,
+ end: YieldTime(end),
+ }
+ }
+}
diff --git a/crates/gpui/src/window.rs b/crates/gpui/src/window.rs
index fb1b2edd9ff..bddeda62782 100644
--- a/crates/gpui/src/window.rs
+++ b/crates/gpui/src/window.rs
@@ -117,6 +117,8 @@ impl DispatchPhase {
}
struct WindowInvalidatorInner {
+ #[cfg(feature = "profiler")]
+ pub window_id: WindowId,
pub dirty: bool,
pub draw_phase: DrawPhase,
pub dirty_views: FxHashSet<EntityId>,
@@ -128,8 +130,9 @@ struct WindowInvalidatorInner {
/// Per-frame invalidation bookkeeping, drained at draw time and emitted to the
/// frame profiler. Tracks when the current frame first became dirty and how
-/// many invalidations were coalesced into it. Only populated when the profiler
-/// is compiled in and `profiler::trace_enabled()` is set.
+/// many invalidations were coalesced into it, whenever the profiler is
+/// compiled in. Retention of the resulting per-frame records is what
+/// `profiler::trace_enabled()` controls, not this measurement.
#[cfg(feature = "profiler")]
#[derive(Default)]
struct FrameDirtyAccumulator {
@@ -143,9 +146,11 @@ pub(crate) struct WindowInvalidator {
}
impl WindowInvalidator {
- pub fn new() -> Self {
+ pub fn new(#[allow(unused_variables)] window_id: WindowId) -> Self {
WindowInvalidator {
inner: Rc::new(RefCell::new(WindowInvalidatorInner {
+ #[cfg(feature = "profiler")]
+ window_id,
dirty: true,
draw_phase: DrawPhase::None,
dirty_views: FxHashSet::default(),
@@ -163,11 +168,17 @@ impl WindowInvalidator {
inner.dirty_views.insert(entity);
if inner.draw_phase == DrawPhase::None {
#[cfg(feature = "profiler")]
- Self::record_frame_dirty(&mut inner);
+ let dirty_at = Self::record_frame_dirty(&mut inner);
let became_dirty = !inner.dirty;
inner.dirty = true;
let waker = became_dirty.then(|| inner.platform_waker.clone()).flatten();
+ #[cfg(feature = "profiler")]
+ let window_id = inner.window_id;
drop(inner);
+ #[cfg(feature = "profiler")]
+ if became_dirty {
+ profiler::journal::record_frame_pending(window_id, dirty_at);
+ }
cx.push_effect(Effect::Notify { emitter: entity });
if let Some(waker) = waker {
waker();
@@ -188,11 +199,17 @@ impl WindowInvalidator {
inner.dirty = dirty;
if dirty {
inner.update_count += 1;
- #[cfg(feature = "profiler")]
- Self::record_frame_dirty(&mut inner);
}
+ #[cfg(feature = "profiler")]
+ let dirty_at = dirty.then(|| Self::record_frame_dirty(&mut inner));
let waker = became_dirty.then(|| inner.platform_waker.clone()).flatten();
+ #[cfg(feature = "profiler")]
+ let window_id = inner.window_id;
drop(inner);
+ #[cfg(feature = "profiler")]
+ if became_dirty && let Some(dirty_at) = dirty_at {
+ profiler::journal::record_frame_pending(window_id, dirty_at);
+ }
if let Some(waker) = waker {
waker();
}
@@ -227,11 +244,10 @@ impl WindowInvalidator {
}
#[cfg(feature = "profiler")]
- fn record_frame_dirty(inner: &mut WindowInvalidatorInner) {
- if profiler::trace_enabled() {
- inner.frame_dirty.dirty_at.get_or_insert_with(Instant::now);
- inner.frame_dirty.invalidations += 1;
- }
+ fn record_frame_dirty(inner: &mut WindowInvalidatorInner) -> Instant {
+ let dirty_at = *inner.frame_dirty.dirty_at.get_or_insert_with(Instant::now);
+ inner.frame_dirty.invalidations += 1;
+ dirty_at
}
#[cfg(feature = "profiler")]
@@ -1402,7 +1418,7 @@ impl Window {
let scale_factor = platform_window.scale_factor();
let appearance = platform_window.appearance();
let text_system = Arc::new(WindowTextSystem::new(cx.text_system().clone()));
- let invalidator = WindowInvalidator::new();
+ let invalidator = WindowInvalidator::new(handle.window_id());
let active = Rc::new(Cell::new(platform_window.is_active()));
let hovered = Rc::new(Cell::new(platform_window.is_hovered()));
let needs_present = Rc::new(Cell::new(false));
@@ -1523,6 +1539,8 @@ impl Window {
let input_rate_tracker = input_rate_tracker.clone();
let mut deferred_force_render = false;
move |request_frame_options| {
+ #[cfg(feature = "profiler")]
+ let _foreground_turn = profiler::journal::foreground_turn();
// This must be checked before anything else: if this request
// arrived re-entrantly while a draw is on this thread's stack
// (e.g. via a nested message pump in the Windows window
@@ -2834,8 +2852,8 @@ impl Window {
/// the contents of the new [`Scene`], use [`Self::present`].
#[profiling::function]
pub fn draw(&mut self, cx: &mut App) -> ArenaClearNeeded {
- // Drain every draw in profiler builds so a stale first-invalidation
- // timestamp can't leak across enable/disable of runtime tracing.
+ // Drain every draw in profiler builds so a previous frame's
+ // first-invalidation timestamp can't be attributed to this one.
#[cfg(feature = "profiler")]
let frame_dirty = self.invalidator.take_frame_dirty();
#[cfg(feature = "profiler")]
@@ -2996,9 +3014,15 @@ impl Window {
#[profiling::function]
fn present(&mut self) {
+ #[cfg(feature = "profiler")]
+ let _foreground_turn = profiler::journal::foreground_turn();
+ #[cfg(feature = "profiler")]
+ let present_start = Instant::now();
self.platform_window.draw(&self.rendered_frame.scene);
#[cfg(feature = "profiler")]
self.window_profiler.record_present(
+ present_start,
+ Instant::now(),
self.active.get(),
!self.next_frame_callbacks.borrow().is_empty(),
);
@@ -3011,7 +3035,7 @@ impl Window {
/// Benchmarks drive drawing synchronously rather than through a platform
/// frame-request loop, so they call this after each measured update to
/// submit the frame like production presentation would.
- #[cfg(feature = "bench")]
+ #[cfg(any(feature = "bench", all(test, feature = "profiler")))]
pub fn present_if_needed(&mut self) {
if self.needs_present.get() {
self.present();
@@ -4984,7 +5008,7 @@ impl Window {
#[profiling::function]
pub fn dispatch_event(&mut self, event: PlatformInput, cx: &mut App) -> DispatchEventResult {
#[cfg(feature = "profiler")]
- self.window_profiler.begin_input();
+ self.window_profiler.begin_input(event.kind_name());
let update_count_before = self.invalidator.update_count();
// Track input modality for focus-visible styling and hover suppression.
// Hover is suppressed during keyboard modality so that keyboard navigation
diff --git a/crates/zed/Cargo.toml b/crates/zed/Cargo.toml
index 6ced4002b20..1258dfc5f4a 100644
--- a/crates/zed/Cargo.toml
+++ b/crates/zed/Cargo.toml
@@ -123,8 +123,8 @@ go_to_line.workspace = true
gpui = { workspace = true, features = [ "profiler" ] }
gpui_platform = { workspace = true, features = [ "screen-capture", "font-kit", "wayland", "x11" ] }
gpui_tokio.workspace = true
-hdrhistogram.workspace = true
image = { workspace = true, optional = true }
+spin = "0.10.0"
itertools.workspace = true
rayon.workspace = true
semver.workspace = true
diff --git a/crates/zed/src/reliability/hang_detection.rs b/crates/zed/src/reliability/hang_detection.rs
index 82f8f2b85a6..bb4db321983 100644
--- a/crates/zed/src/reliability/hang_detection.rs
+++ b/crates/zed/src/reliability/hang_detection.rs
@@ -1,12 +1,15 @@
use std::sync::Arc;
use std::thread;
-use std::time::Duration;
+use std::time::{Duration, Instant};
use client::Client;
+use gpui::profiler::hang::{HangDetector, SerializedHangIncident};
use gpui::{AppContext, TasksIncluded, profiler};
use parking_lot::Mutex;
use ui::App;
+use crate::STARTUP_TIME;
+
mod logging;
mod task_traces;
mod telemetry;
@@ -23,6 +26,8 @@ gpui::actions!(
]
);
+const MAX_SERIALIZED_CONTRIBUTORS: usize = 8;
+
pub(crate) fn start(client: Arc<Client>, cx: &mut App) {
let hang_time = if cfg!(debug_assertions) {
if cfg!(windows) {
@@ -36,11 +41,22 @@ pub(crate) fn start(client: Arc<Client>, cx: &mut App) {
Duration::from_millis(100)
};
+ let frame_budget = if cfg!(debug_assertions) {
+ // Unoptimized builds routinely spend more than a release frame
+ // budget on ordinary frames; keep dev builds from reporting
+ // constantly.
+ Duration::from_millis(100)
+ } else {
+ // One 120Hz refresh: an interval that spends this much on the
+ // foreground has plausibly dropped a frame.
+ Duration::from_millis(8)
+ };
+
if cfg!(debug_assertions) {
log::warn!("debug build, only reporting hangs longer then {hang_time:?}");
}
- start_hang_detection(hang_time, client, cx);
+ start_hang_detection(hang_time, frame_budget, client, cx);
cx.on_action(move |_: &HangAction, _| {
log::warn!(
@@ -75,16 +91,44 @@ pub(crate) fn start(client: Arc<Client>, cx: &mut App) {
});
}
-fn start_hang_detection(report_longer_then: Duration, client: Arc<Client>, cx: &App) {
+fn start_hang_detection(
+ report_longer_then: Duration,
+ frame_budget: Duration,
+ client: Arc<Client>,
+ cx: &App,
+) {
let foreground_thread = thread::current().id();
let monitor_interval = Duration::from_secs(1);
- let telemetry = Arc::new(Mutex::new(telemetry::Reporter::new(foreground_thread)));
+ let telemetry = Arc::new(Mutex::new(telemetry::Reporter::new()));
+ let incident_detector = Arc::new(spin::Mutex::new(HangDetector::new(
+ cx.foreground_journal(),
+ report_longer_then,
+ frame_budget,
+ )));
+ let started = Instant::now();
+ let startup = *STARTUP_TIME.get().unwrap_or(&started);
let mut log = logging::Reporter::new(monitor_interval, report_longer_then, foreground_thread);
- let telemetry2 = Arc::clone(&telemetry);
cx.on_app_quit({
+ let telemetry = Arc::clone(&telemetry);
+ let incident_detector = Arc::clone(&incident_detector);
move |_| {
- telemetry2.lock().send();
+ let mut incident_detector = incident_detector.lock();
+ let incidents = incident_detector.poll();
+ let first_present_at = incident_detector.first_present_at();
+ drop(incident_detector);
+
+ let mut telemetry = telemetry.lock();
+ for incident in &incidents {
+ telemetry.add(SerializedHangIncident::convert(
+ startup,
+ incident,
+ MAX_SERIALIZED_CONTRIBUTORS,
+ first_present_at,
+ ));
+ }
+ telemetry.send();
+ drop(telemetry);
client.telemetry().flush_events()
}
})
@@ -100,14 +144,25 @@ fn start_hang_detection(report_longer_then: Duration, client: Arc<Client>, cx: &
thread::sleep(Duration::from_millis(200));
loop {
thread::sleep(monitor_interval);
- // TODO(yara) the telemetry should not include still running tasks while the
- // reports being logged should.
let task_stats = profiler::take_all_stats(TasksIncluded::CompletedAndRunning);
let action_stats = profiler::take_action_stats();
{
+ let mut incident_detector = incident_detector.lock();
+ let incidents = incident_detector.poll();
+ let first_present_at = incident_detector.first_present_at();
+ drop(incident_detector);
+
let mut telemetry = telemetry.lock();
- telemetry.update(&task_stats, &action_stats);
+ for incident in &incidents {
+ let serialized_incident = SerializedHangIncident::convert(
+ startup,
+ incident,
+ MAX_SERIALIZED_CONTRIBUTORS,
+ first_present_at,
+ );
+ telemetry.add(serialized_incident);
+ }
telemetry.send_periodically();
}
diff --git a/crates/zed/src/reliability/hang_detection/telemetry.rs b/crates/zed/src/reliability/hang_detection/telemetry.rs
index a2d8e4136a1..97eea191c07 100644
--- a/crates/zed/src/reliability/hang_detection/telemetry.rs
+++ b/crates/zed/src/reliability/hang_detection/telemetry.rs
@@ -1,301 +1,56 @@
-use std::thread::ThreadId;
use std::time::{Duration, Instant};
-use collections::HashMap;
-use hdrhistogram::Histogram;
-use itertools::Itertools;
+use gpui::profiler::hang::SerializedHangIncident;
-use crate::STARTUP_TIME;
+/// Cap on incidents per telemetry event. When more accrue between sends, the
+/// ones with the largest stalls are kept and `total_incidents` still counts
+/// them all.
+const MAX_REPORTED_INCIDENTS: usize = 10;
-/// Microseconds since app start
-type MicroSeconds = u64;
-
-// TODO(yara) some crazy ideas:
-// - track most recent action?
-// - Action that this task was spawned from?
-// - flag that enables tracking more for a specific task
-// - task backtrace? (who spawned who etc)
-
-#[derive(Debug, Clone, serde::Serialize)]
-struct HangReport {
- location: String,
- hang_density: f64,
- mean_hang_duration: MicroSeconds,
-
- /// since app start
- slowest_start: MicroSeconds,
- /// since app start
- slowest_end: MicroSeconds,
-
- /// 50% of bad polls where faster then this value
- /// This also approximate the median
- p50: MicroSeconds,
- /// 75% of bad polls where faster then this value
- p75: MicroSeconds,
- /// 95% of bad polls where faster then this value
- p95: MicroSeconds,
-}
-
-#[derive(Debug, Clone, serde::Serialize)]
-struct TelemetryReport {
- foreground: Vec<HangReport>,
- background: Vec<HangReport>,
- actions: Vec<HangReport>,
-}
-
-struct Item<T: Hang> {
- total_hanged: Duration,
- slowest_poll: T,
- /// saturates if more then 256 measurements end up in the same bin
- histogram: Histogram<u8>,
-}
-
-impl<T: Hang> Item<T> {
- fn hang_density(&self, period: Duration) -> f64 {
- self.total_hanged.div_duration_f64(period)
- }
- fn into_report(&self, location: &T::Descriptor, period: Duration) -> HangReport {
- let now = Instant::now();
- let startup = STARTUP_TIME.get().unwrap_or(&now);
- HangReport {
- location: T::format_location(location),
- hang_density: self.hang_density(period),
- mean_hang_duration: self.histogram.mean() as u64,
- slowest_start: self
- .slowest_poll
- .start()
- .duration_since(*startup)
- .as_micros() as u64,
- slowest_end: self.slowest_poll.end().duration_since(*startup).as_micros() as u64,
- p50: self.histogram.value_at_quantile(0.5),
- p75: self.histogram.value_at_quantile(0.75),
- p95: self.histogram.value_at_quantile(0.95),
- }
- }
-}
-
-struct Hangs<T: Hang> {
- last_reset: Instant,
- hangs: HashMap<T::Descriptor, Item<T>>,
-}
-
-trait Hang: Clone {
- type Descriptor: std::hash::Hash + PartialEq + Eq;
- fn poll_duration(&self) -> Duration;
- fn descriptor(&self) -> Self::Descriptor;
- fn format_location(location: &Self::Descriptor) -> String;
- fn start(&self) -> Instant;
- fn end(&self) -> Instant;
-}
-
-impl Hang for gpui::TaskTiming {
- type Descriptor = std::panic::Location<'static>;
-
- fn poll_duration(&self) -> Duration {
- gpui::TaskTiming::poll_duration(self)
- }
- fn descriptor(&self) -> Self::Descriptor {
- *self.location
- }
- fn format_location(location: &Self::Descriptor) -> String {
- format!(
- "{}:{}:{}",
- location.file(),
- location.line(),
- location.column()
- )
- }
- fn start(&self) -> Instant {
- self.start
- }
- fn end(&self) -> Instant {
- self.end.0
- }
-}
-
-impl Hang for gpui::ActionTiming {
- type Descriptor = &'static str;
-
- fn poll_duration(&self) -> Duration {
- self.duration()
- }
- fn descriptor(&self) -> Self::Descriptor {
- self.name
- }
- fn format_location(location: &Self::Descriptor) -> String {
- location.to_string()
- }
- fn start(&self) -> Instant {
- self.start
- }
- fn end(&self) -> Instant {
- self.end
- }
-}
-
-impl<T: Hang> Hangs<T> {
- fn new() -> Self {
- Self {
- last_reset: Instant::now(),
- hangs: HashMap::default(),
- }
- }
- fn add(&mut self, new: T, min_recorded_us: u64) {
- const MICROSECONDS_MINUTE: u64 = 60 * 1000 * 1000;
-
- if self.hangs.len() > 1000 {
- log::warn!("Too many hanging tasks to track, can not add new");
- return;
- }
-
- self.hangs
- .entry(new.descriptor())
- .and_modify(|item| {
- item.total_hanged += new.poll_duration();
- item.histogram
- .saturating_record(new.poll_duration().as_micros() as u64);
- if new.poll_duration() > item.slowest_poll.poll_duration() {
- item.slowest_poll = new.clone();
- }
- })
- .or_insert({
- Item {
- total_hanged: new.poll_duration(),
- slowest_poll: new,
- histogram: Histogram::new_with_bounds(min_recorded_us, MICROSECONDS_MINUTE, 3)
- .expect("function parameters are constants and correct"),
- }
- });
- }
-
- fn report_and_reset(&mut self) -> Vec<HangReport> {
- let period = self.last_reset.elapsed();
- self.last_reset = Instant::now();
-
- let lowest_density_to_report = self
- .hangs
- .values()
- .map(|item| item.total_hanged.div_duration_f64(period))
- .k_largest_relaxed_by(5, f64::total_cmp)
- .nth(5)
- .unwrap_or(0.0);
-
- let report = self
- .hangs
- .drain()
- .filter(|(_, item)| item.hang_density(period) >= lowest_density_to_report)
- .map(|(location, item)| item.into_report(&location, period))
- .collect();
-
- report
- }
-
- fn is_empty(&self) -> bool {
- self.hangs.is_empty()
- }
-}
+// A long interval keeps hang telemetry a small fraction of event volume even
+// for pathologically hang-prone sessions; the on-quit flush covers short ones.
+const SEND_INTERVAL: Duration = Duration::from_mins(30);
pub struct Reporter {
- record_slower_then: Duration,
- foreground_thread: ThreadId,
last_send: Instant,
-
- foreground: Hangs<gpui::TaskTiming>,
- background: Hangs<gpui::TaskTiming>,
- actions: Hangs<gpui::ActionTiming>,
+ pending: Vec<SerializedHangIncident>,
+ total_incidents: u64,
}
impl Reporter {
- pub fn new(foreground_thread: ThreadId) -> Self {
+ pub fn new() -> Self {
Self {
- record_slower_then: Duration::from_millis(1),
- foreground_thread,
last_send: Instant::now(),
- foreground: Hangs::new(),
- background: Hangs::new(),
- actions: Hangs::new(),
+ pending: Vec::new(),
+ total_incidents: 0,
}
}
- pub fn update(
- &mut self,
- task_stats: &[gpui::ThreadTaskStatistics],
- action_stats: &gpui::ActionStatistics,
- ) {
- self.process_foreground(task_stats);
- self.process_background(task_stats);
- self.process_actions(action_stats);
+ pub fn add(&mut self, incident: SerializedHangIncident) {
+ self.total_incidents += 1;
+ self.pending.push(incident);
+ if self.pending.len() > MAX_REPORTED_INCIDENTS {
+ self.pending
+ .sort_by(|a, b| b.stall_ms.total_cmp(&a.stall_ms));
+ self.pending.truncate(MAX_REPORTED_INCIDENTS);
+ }
}
pub fn send_periodically(&mut self) {
- // this should be a long period otherwise things like
- // hang density get
- if self.last_send.elapsed() > Duration::from_mins(30) {
- self.send()
+ if self.last_send.elapsed() > SEND_INTERVAL {
+ self.send();
}
}
pub fn send(&mut self) {
self.last_send = Instant::now();
- if self.nothing_to_report() {
- return;
- }
- let report = TelemetryReport {
- foreground: self.foreground.report_and_reset(),
- background: self.background.report_and_reset(),
- actions: self.actions.report_and_reset(),
- };
-
- telemetry::event!("Hang Report", report);
- }
-
- fn process_foreground(&mut self, task_stats: &[gpui::ThreadTaskStatistics]) {
- let foreground_thread = self.foreground_thread;
- let Some(foreground) = task_stats.iter().find(|t| t.thread_id == foreground_thread) else {
- // during startup foreground thread might not have statistics yet
+ if self.pending.is_empty() {
return;
- };
-
- for hang in foreground
- .stats
- .longest_poll_times
- .into_iter()
- .filter(|task| task.poll_duration() > self.record_slower_then)
- {
- self.foreground
- .add(hang, self.record_slower_then.as_micros() as u64);
- }
- }
- fn process_background(&mut self, task_stats: &[gpui::ThreadTaskStatistics]) {
- let foreground_thread = self.foreground_thread;
- let background = task_stats
- .iter()
- .filter(|t| t.thread_id != foreground_thread);
-
- for worker in background {
- for hang in worker
- .stats
- .longest_poll_times
- .into_iter()
- .filter(|task| task.poll_duration() > self.record_slower_then)
- {
- self.background
- .add(hang, self.record_slower_then.as_micros() as u64);
- }
}
- }
-
- fn process_actions(&mut self, action_stats: &gpui::ActionStatistics) {
- for hang in action_stats
- .longest_runtimes(false)
- .filter(|action| action.runtime() > self.record_slower_then)
- {
- self.actions
- .add(hang, self.record_slower_then.as_micros() as u64);
- }
- }
+ let mut incidents = std::mem::take(&mut self.pending);
+ incidents.sort_by(|a, b| b.stall_ms.total_cmp(&a.stall_ms));
+ let total_incidents = std::mem::take(&mut self.total_incidents);
- fn nothing_to_report(&self) -> bool {
- self.actions.is_empty() && self.foreground.is_empty() && self.background.is_empty()
+ telemetry::event!("Hang Incidents", incidents, total_incidents);
}
}