Code at the speed of thought – Zed is a high-performance, multiplayer code editor from the creators of Atom and Tree-sitter.
//! 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;
#[cfg(not(target_family = "wasm"))]
mod monitor;
#[cfg(not(target_family = "wasm"))]
pub(crate) use monitor::HangMonitor;
#[cfg(not(target_family = "wasm"))]
pub use monitor::{HangMonitorConfig, HangMonitorError, HangMonitorPoll, HangMonitorPollReason};
/// Version of the power/visibility-aware measurement rules.
pub const MEASUREMENT_VERSION: u32 = 3;
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,
/// completed frame skip, 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>,
activity: ActiveUse,
}
/// The user counts as actively using the app for this long after deliberate
/// input.
pub const ACTIVE_USE_WINDOW: Duration = Duration::from_secs(60);
/// Input that doesn't show the user is using the app: platforms deliver
/// pointer movement to background windows the pointer merely passes over.
const PASSIVE_INPUT_KINDS: [&str; 3] = ["mouse_move", "mouse_exited", "mouse_pressure"];
/// Accumulates the time the user was actively using the app: within
/// [`ACTIVE_USE_WINDOW`] of deliberate input, excluding stretches interrupted
/// by a system suspend.
#[derive(Default)]
struct ActiveUse {
/// End times of recent deliberate input, oldest first, for
/// [`Self::was_active_during`].
recent_inputs: std::collections::VecDeque<Instant>,
accounted_until: Option<Instant>,
active_until: Option<Instant>,
first_input_since_accounted: Option<Instant>,
last_input_since_accounted: Option<Instant>,
suspended: bool,
}
impl ActiveUse {
fn observe(&mut self, entry: &ForegroundJournalEntry) {
match entry {
ForegroundJournalEntry::Event(ForegroundEvent::Input(input))
if !PASSIVE_INPUT_KINDS.contains(&input.kind) =>
{
self.recent_inputs.push_back(input.end);
self.first_input_since_accounted.get_or_insert(input.start);
self.last_input_since_accounted = Some(
self.last_input_since_accounted
.map_or(input.end, |last| last.max(input.end)),
);
}
ForegroundJournalEntry::Boundary(IntervalBoundary::PowerTransition { .. }) => {
self.suspended = true;
}
_ => {}
}
}
/// Whether the user was actively using the app at some point from
/// `start` to `end`: deliberate input during that span or within
/// [`ACTIVE_USE_WINDOW`] before it.
fn was_active_during(&self, start: Instant, end: Instant) -> bool {
let since = start.checked_sub(ACTIVE_USE_WINDOW).unwrap_or(start);
self.recent_inputs
.iter()
.any(|input| *input >= since && *input <= end)
}
fn take(&mut self, now: Instant, max_elapsed: Duration) -> Duration {
// Incidents are judged soon after they end; inputs older than this
// can't be within the active window of anything still being sealed.
let retained_since = now.checked_sub(ACTIVE_USE_WINDOW * 10);
while self
.recent_inputs
.front()
.is_some_and(|input| retained_since.is_some_and(|since| *input < since))
{
self.recent_inputs.pop_front();
}
let since = self.accounted_until.replace(now);
let previous_until = self.active_until;
let first_input = self.first_input_since_accounted.take();
if let Some(last_input) = self.last_input_since_accounted.take() {
let until = last_input + ACTIVE_USE_WINDOW;
self.active_until = Some(previous_until.map_or(until, |previous| previous.max(until)));
}
let (Some(since), false) = (since, std::mem::take(&mut self.suspended)) else {
return Duration::ZERO;
};
let continued_until = previous_until.map_or(since, |until| until.min(now).max(since));
let mut active = continued_until.duration_since(since);
if let (Some(first_input), Some(active_until)) = (first_input, self.active_until) {
let start = first_input.max(continued_until);
active += active_until.min(now).saturating_duration_since(start);
}
active.min(max_elapsed)
}
}
/// 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,
/// Which detection rule qualified the interval.
pub trigger: HangTrigger,
/// The events that caused the incident, longest first: those at least as
/// long as the threshold or the frame budget for [`HangTrigger::Threshold`]
/// and [`HangTrigger::BlockingWork`], and those overlapping the late frame's
/// work for [`HangTrigger::LateFrame`].
pub contributors: Vec<ForegroundEvent>,
/// Whether the user was actively using the app during the incident (see
/// [`HangDetector::take_active_time`]), so rates per active hour can count
/// only incidents that happened during it.
pub during_active_use: bool,
}
/// The detection rule that qualified an interval as a [`HangIncident`].
///
/// Recorded explicitly so consumers can separate the two classes without
/// re-deriving them from `stall_ms`, which stops working whenever the
/// detector's thresholds change.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize)]
#[serde(rename_all = "snake_case")]
pub enum HangTrigger {
/// A single event blocked the foreground for at least the hang threshold.
Threshold,
/// The interval presented a frame whose work exceeded its budget (see
/// [`FrameTiming::is_late`](crate::profiler::FrameTiming::is_late)).
LateFrame,
/// The interval presented no frame whose work could be measured, but a
/// single event blocked the foreground for at least the frame budget,
/// long enough to delay a frame.
BlockingWork,
}
impl HangTrigger {
/// Every trigger.
pub const ALL: [Self; 3] = [Self::Threshold, Self::LateFrame, Self::BlockingWork];
/// The trigger's serialized name, e.g. `"late_frame"`.
pub fn as_str(self) -> &'static str {
match self {
Self::Threshold => "threshold",
Self::LateFrame => "late_frame",
Self::BlockingWork => "blocking_work",
}
}
}
impl HangDetector {
/// Creates a detector reporting single events at or above `threshold`,
/// late frames, and blocking work of at least `frame_budget` (see
/// [`HangIncident::detect`]).
/// 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,
activity: ActiveUse::default(),
}
}
/// The time since the previous call that the user was actively using
/// the app, as of the journal entries polled so far: within
/// [`ACTIVE_USE_WINDOW`] of deliberate input, such as key presses, clicks,
/// and scrolling, excluding polls that observed a system
/// suspend. Capped at `max_elapsed`, so time this thread spent suspended
/// isn't counted.
pub fn take_active_time(&mut self, now: Instant, max_elapsed: Duration) -> Duration {
self.activity.take(now, max_elapsed)
}
/// 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();
for entry in &drained.entries {
self.activity.observe(entry);
}
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| {
let mut incident =
HangIncident::detect(snapshot, self.threshold, self.frame_budget)?;
let (start, end) = incident.active_window();
incident.during_active_use = self.activity.was_active_during(start, end);
Some(incident)
})
.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 {
/// Identifies the rules used to exclude interrupted measurements.
pub measurement_version: u32,
/// `"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,
/// `"threshold"`, `"late_frame"`, or `"blocking_work"` (see
/// [`HangTrigger`]).
pub trigger: HangTrigger,
/// See [`HangIncident::during_active_use`].
pub during_active_use: bool,
/// 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"`, `"frame_skipped"`, `"idle"`, or
/// `"power_transition"`. 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,
/// Time spent rendering views and requesting layout, in milliseconds.
request_layout_ms: f64,
/// Time spent computing layout and prepainting, in milliseconds.
prepaint_ms: f64,
/// Time spent painting, in milliseconds.
paint_ms: f64,
/// How many other events in the interval contain this one.
depth: usize,
},
/// One phase of drawing a view whose own work took at least
/// [`crate::profiler::VIEW_TIMING_FLOOR`].
View {
/// The view's type name.
name: &'static str,
/// The draw phase: `"request_layout"`, `"prepaint"`, or `"paint"`.
phase: &'static str,
/// When the phase started, in milliseconds since app startup.
start_ms: f64,
/// How long the phase took, including nested views, in milliseconds.
duration_ms: f64,
/// How long the phase took excluding nested views, in milliseconds.
self_ms: f64,
/// 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",
},
measurement_version: MEASUREMENT_VERSION,
trigger: incident.trigger,
during_active_use: incident.during_active_use,
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::FrameSkipped(_)
| IntervalBoundary::Idle { .. }
| IntervalBoundary::PowerTransition { .. } => None,
},
sealed_by: match snapshot.boundary {
IntervalBoundary::Presented(_) => "present",
IntervalBoundary::FrameSkipped(_) => "frame_skipped",
IntervalBoundary::Idle { .. } => "idle",
IntervalBoundary::PowerTransition { .. } => "power_transition",
},
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,
request_layout_ms: as_millis(timing.phases.request_layout),
prepaint_ms: as_millis(timing.phases.prepaint),
paint_ms: as_millis(timing.phases.paint),
depth,
},
ForegroundEvent::View(timing) => Self::View {
name: timing.name,
phase: timing.phase.as_str(),
start_ms: since_startup(timing.start),
duration_ms,
self_ms: as_millis(timing.self_duration),
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 an event that blocked
/// the foreground for `threshold` or longer; otherwise when the interval
/// presented a late frame, unless the journal lost events; otherwise, when
/// no presented frame's work could be measured, when an event blocked the
/// foreground for `frame_budget` or longer. See [`HangTrigger`].
pub fn detect(
snapshot: FrameSnapshot,
threshold: Duration,
frame_budget: Duration,
) -> Option<Self> {
let events_at_least = |minimum: Duration| -> Vec<ForegroundEvent> {
snapshot
.events
.iter()
.filter(|event| event.duration() >= minimum)
.copied()
.collect()
};
let mut contributors = events_at_least(threshold);
let measured_frame = match &snapshot.boundary {
IntervalBoundary::Presented(presented) => presented
.frame
.work_start()
.map(|work_start| (presented, work_start)),
_ => None,
};
let trigger = if !contributors.is_empty() {
HangTrigger::Threshold
} else if let Some((presented, work_start)) = measured_frame {
let submitted_at = presented.presentation.present_start;
if snapshot.journal_discontinuous
|| !presented.frame.is_late(submitted_at).unwrap_or(false)
{
return None;
}
contributors = snapshot
.events
.iter()
.filter(|event| event.end_time() > work_start && event.start_time() < submitted_at)
.copied()
.collect();
HangTrigger::LateFrame
} else {
contributors = events_at_least(frame_budget);
if contributors.is_empty() {
return None;
}
HangTrigger::BlockingWork
};
contributors.sort_by_key(|event| std::cmp::Reverse(event.duration()));
Some(Self {
snapshot,
trigger,
contributors,
during_active_use: false,
})
}
}
#[cfg(test)]
mod tests {
use std::cell::Cell;
use std::rc::Rc;
use std::thread;
use std::time::Duration;
use proptest::prelude::*;
use rand::{Rng as _, rngs::StdRng};
use scheduler::SpawnTime;
use crate::{
self as gpui, AnyView, AppContext as _, Context, FocusHandle, InteractiveElement,
IntoElement, Modifiers, MouseButton, ParentElement as _, Render, Styled, TestAppContext,
VisualTestContext, Window, WindowId, actions, div, point, px,
};
use crate::profiler::{
ActionTiming, FrameTiming, PresentTiming, TaskTiming, ViewPhase, YieldTime,
};
use super::super::journal::{
FRAME_DEADLINE, ForegroundEvent, ForegroundJournalEntry, FrameSkipReason, FrameSkipped,
FrameSnapshot, FrameStateChange, InputTiming, IntervalBoundary, IntervalSealer,
PlatformSignal, PollSummary, PresentedFrame, SmallPollFlush,
install_test_foreground_journal, record_present,
};
use super::{
HangDetector, HangIncident, HangTrigger, 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;
#[test]
fn completed_skips_preserve_real_hangs_and_serialize_their_boundary() {
let startup = scheduler::Instant::now();
let at = |ms: u64| startup + Duration::from_millis(ms);
let window_id = WindowId::from(1);
for discontinuous in [false, true] {
for trigger in [HangTrigger::Threshold, HangTrigger::BlockingWork] {
let mut sealer = IntervalSealer::new(startup);
let mut entries = Vec::new();
match trigger {
HangTrigger::Threshold => entries.push(ForegroundJournalEntry::Event(
task_poll_event(at(10), at(30)),
)),
_ => entries.extend([
ForegroundJournalEntry::Event(task_poll_event(at(10), at(16))),
ForegroundJournalEntry::Event(task_poll_event(at(20), at(26))),
]),
}
if discontinuous {
entries.push(ForegroundJournalEntry::Discontinuity { lost: 1 });
}
entries.push(ForegroundJournalEntry::Boundary(
IntervalBoundary::FrameSkipped(FrameSkipped {
window_id,
at: at(60),
reason: FrameSkipReason::NoRenderNeeded,
}),
));
let snapshots = sealer.push_entries(entries);
let [snapshot] = snapshots.as_slice() else {
panic!("expected one snapshot, got {snapshots:?}");
};
let incident = HangIncident::detect(snapshot.clone(), HANG_THRESHOLD, FRAME_BUDGET);
if trigger == HangTrigger::BlockingWork {
assert!(incident.is_none(), "short work isn't blocking");
continue;
}
let incident = incident.expect("real work still qualifies across a skip");
assert_eq!(incident.trigger, trigger);
let serialized = SerializedHangIncident::convert(startup, &incident, 10, None);
assert_eq!(serialized.sealed_by, "frame_skipped");
assert_eq!(serialized.dirty_to_present_ms, None);
assert_eq!(serialized.start_ms, 10.0);
assert_eq!(serialized.active_ms, 50.0);
assert_eq!(serialized.journal_discontinuous, discontinuous);
assert_eq!(serialized.event_count, incident.contributors.len());
let json = serde_json::to_value(&serialized).expect("serialize incident");
assert_eq!(json["sealed_by"], "frame_skipped");
assert!(json["dirty_to_present_ms"].is_null());
}
}
}
#[test]
fn delayed_platform_signals_without_work_are_not_hangs() {
let start = scheduler::Instant::now();
let window_id = WindowId::from(1);
let mut sealer = IntervalSealer::new(start);
let snapshots = sealer.push_entries([
ForegroundJournalEntry::PlatformSignal(PlatformSignal {
window_id,
signal_at: Some(start),
handled_at: start + Duration::from_secs(5),
source: crate::FrameRequestSource::NativeCallback,
}),
ForegroundJournalEntry::Boundary(IntervalBoundary::FrameSkipped(FrameSkipped {
window_id,
at: start + Duration::from_secs(6),
reason: FrameSkipReason::NoRenderNeeded,
})),
]);
assert!(
snapshots.is_empty(),
"a late signal without work seals nothing, got {snapshots:?}"
);
}
/// 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 {
refresh_interval: None,
signal_at: None,
window_id,
dirty_at: Some(at(100)),
invalidations: 3,
draw_start: at(350),
draw_end: at(380),
phases: Default::default(),
};
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");
assert_eq!(serialized.trigger, HangTrigger::Threshold);
// 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 hang_monitor_polls_on_its_interval_and_on_flush() {
use super::{HangMonitor, HangMonitorPollReason};
let (journal, _guard) = install_test_foreground_journal(64, 4);
// Each monitor reports on its own channel, which disconnects once the
// monitor's thread has exited and dropped its callback.
let spawn_monitor = |journal, interval| {
let (sender, receiver) = std::sync::mpsc::channel();
let monitor = HangMonitor::spawn(
HangDetector::new(journal, HANG_THRESHOLD, FRAME_BUDGET),
interval,
move |poll| {
if !poll.incidents.is_empty() {
sender.send((poll.reason, poll.incidents.len())).ok();
}
},
)
.expect("spawn monitor thread");
(monitor, receiver)
};
let (monitor, receiver) = spawn_monitor(journal.clone(), Duration::from_millis(10));
simulate_blocked_foreground_poll(HANG_THRESHOLD * 2);
assert_eq!(
receiver.recv_timeout(Duration::from_secs(10)).ok(),
Some((HangMonitorPollReason::Interval, 1)),
);
drop(monitor);
assert_eq!(
receiver.recv_timeout(Duration::from_secs(10)),
Err(std::sync::mpsc::RecvTimeoutError::Disconnected),
);
// An interval longer than the test isolates the flush path.
let (monitor, receiver) = spawn_monitor(journal, Duration::from_secs(3600));
simulate_blocked_foreground_poll(HANG_THRESHOLD * 2);
let flushed = monitor.request_flush().expect("monitor thread is running");
futures::executor::block_on(flushed).expect("flush completes");
assert_eq!(
receiver.try_recv().ok(),
Some((HangMonitorPollReason::Flush, 1)),
);
drop(monitor);
assert_eq!(
receiver.recv_timeout(Duration::from_secs(10)),
Err(std::sync::mpsc::RecvTimeoutError::Disconnected),
);
}
#[gpui::test]
fn app_flushes_its_hang_monitor_on_shutdown(cx: &mut TestAppContext) {
use super::{HangMonitorConfig, HangMonitorPollReason};
// The monitor runs on a real OS thread, so shutdown has to park until it
// finishes the flush, and its completion wakes the scheduler from that thread.
cx.executor().allow_parking();
let (sender, receiver) = std::sync::mpsc::channel();
cx.update(|cx| {
cx.start_hang_monitor(
HangMonitorConfig {
threshold: HANG_THRESHOLD,
frame_budget: FRAME_BUDGET,
// Longer than the test, so only shutdown can poll.
interval: Duration::from_secs(3600),
},
move |poll| {
sender.send(poll.reason).ok();
},
)
.expect("start hang monitor");
});
assert!(receiver.try_recv().is_err());
cx.update(|cx| cx.shutdown());
assert_eq!(receiver.try_recv().ok(), Some(HangMonitorPollReason::Flush));
}
#[gpui::test]
fn starting_the_hang_monitor_twice_is_rejected(cx: &mut TestAppContext) {
use super::{HangMonitorConfig, HangMonitorError};
let config = HangMonitorConfig {
threshold: HANG_THRESHOLD,
frame_budget: FRAME_BUDGET,
interval: Duration::from_secs(3600),
};
cx.update(|cx| {
cx.start_hang_monitor(config, |_| {})
.expect("start hang monitor");
let second = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| {
cx.start_hang_monitor(config, |_| {})
}));
// Debug builds also assert, so misuse is caught during development.
if cfg!(debug_assertions) {
assert!(second.is_err());
} else {
assert!(matches!(second, Ok(Err(HangMonitorError::AlreadyStarted))));
}
});
}
#[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 {
refresh_interval: None,
signal_at: Some(at(0)),
window_id,
dirty_at: Some(at(0)),
invalidations: 1,
draw_start: at(140),
draw_end: at(145),
phases: Default::default(),
},
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("the frame missed the 60 Hz budget used for unknown displays");
assert_eq!(incident.trigger, HangTrigger::LateFrame);
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.trigger, HangTrigger::LateFrame);
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 {
refresh_interval: None,
signal_at: None,
window_id,
dirty_at: Some(at(0)),
invalidations: 1,
draw_start: at(145),
draw_end: at(147),
phases: Default::default(),
},
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());
}
#[test]
fn active_use_counts_time_within_a_minute_of_deliberate_input() {
let start = scheduler::Instant::now();
let at = |seconds: u64| start + Duration::from_secs(seconds);
let input_of_kind = |kind: &'static str, seconds: u64| {
ForegroundJournalEntry::Event(ForegroundEvent::Input(InputTiming {
kind,
start: at(seconds),
end: at(seconds),
caused_invalidation: true,
}))
};
let input = |seconds: u64| input_of_kind("key_down", seconds);
let max = Duration::from_secs(10);
let mut activity = super::ActiveUse::default();
assert_eq!(activity.take(at(0), max), Duration::ZERO);
// The pointer passing over a window isn't use.
activity.observe(&input_of_kind("mouse_move", 1));
activity.observe(&input_of_kind("mouse_exited", 2));
assert_eq!(activity.take(at(4), max), Duration::ZERO);
// Idle until input at 5 s.
activity.observe(&input(5));
assert_eq!(activity.take(at(8), max), Duration::from_secs(3));
// Active until 65 s, a minute after the input.
assert_eq!(activity.take(at(16), max), Duration::from_secs(8));
for second in (24..=64).step_by(8) {
activity.take(at(second), max);
}
assert_eq!(activity.take(at(70), max), Duration::from_secs(1));
assert_eq!(activity.take(at(78), max), Duration::ZERO);
// A suspend discards the poll it was observed in.
activity.observe(&input(80));
activity.observe(&ForegroundJournalEntry::Boundary(
IntervalBoundary::PowerTransition { ended_at: at(81) },
));
assert_eq!(activity.take(at(84), max), Duration::ZERO);
assert_eq!(activity.take(at(88), max), Duration::from_secs(4));
// Time the monitor itself was suspended isn't counted.
assert_eq!(activity.take(at(130), max), max);
// Incidents spanning input or within a minute after it are during
// active use; ones later than that aren't.
assert!(activity.was_active_during(at(79), at(80)));
assert!(activity.was_active_during(at(100), at(101)));
assert!(!activity.was_active_during(at(141), at(142)));
assert!(!activity.was_active_during(at(66), at(70)));
}
/// Without a measured frame, only a single event as long as the frame
/// budget is blocking work, however much short work the interval holds.
#[test]
fn only_single_events_over_the_frame_budget_are_blocking_work() {
let startup = scheduler::Instant::now();
let at = |ms: u64| startup + Duration::from_millis(ms);
let snapshot = |longest_ms: u64| 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)))
.chain([task_poll_event(at(200), at(200 + longest_ms))])
.collect(),
small_polls: Vec::new(),
dropped_events: 0,
journal_discontinuous: false,
};
let frame_budget = Duration::from_millis(7);
assert!(HangIncident::detect(snapshot(6), HANG_THRESHOLD, frame_budget).is_none());
let incident = HangIncident::detect(snapshot(7), HANG_THRESHOLD, frame_budget)
.expect("one event as long as the frame budget");
assert_eq!(incident.trigger, HangTrigger::BlockingWork);
assert_eq!(incident.contributors.len(), 1);
}
/// With a known refresh interval, a frame is a budget hang when its work,
/// from its frame signal to its submission, exceeded one refresh interval or
/// the 120 Hz floor, whichever is longer.
#[test]
fn late_frames_are_budget_hangs() {
let startup = scheduler::Instant::now();
let at = |ms: u64| startup + Duration::from_millis(ms);
let window_id = WindowId::from(0xB0D6E7);
let detect = |refresh_interval: Duration,
signal_at: Option<scheduler::Instant>,
submitted_ms: u64| {
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(1),
draw_end: at(submitted_ms - 1),
refresh_interval: Some(refresh_interval),
signal_at,
phases: Default::default(),
},
presentation: PresentTiming {
window_id,
present_start: at(submitted_ms),
// Time spent inside the submission doesn't make
// the frame late.
present_end: at(submitted_ms + 50),
animation_interval: None,
},
}),
events: vec![
task_poll_event(at(1), at(6)),
task_poll_event(at(10), at(15)),
],
small_polls: Vec::new(),
dropped_events: 0,
journal_discontinuous: false,
};
HangIncident::detect(snapshot, HANG_THRESHOLD, FRAME_BUDGET)
};
let sixty_hertz = Duration::from_secs(1) / 60;
let incident = detect(sixty_hertz, Some(at(0)), 25).expect("work exceeded one refresh");
assert_eq!(incident.trigger, HangTrigger::LateFrame);
assert_eq!(incident.contributors.len(), 2);
// Work from before the frame signal didn't delay the frame.
let incident = detect(sixty_hertz, Some(at(8)), 25).expect("17 ms of work at 60 Hz");
assert_eq!(incident.contributors.len(), 1);
assert!(detect(sixty_hertz, Some(at(0)), 16).is_none());
assert!(detect(sixty_hertz, None, 25).is_none());
let three_hundred_sixty_hertz = Duration::from_secs(1) / 360;
assert!(detect(three_hundred_sixty_hertz, Some(at(0)), 8).is_none());
assert!(detect(three_hundred_sixty_hertz, Some(at(0)), 9).is_some());
}
/// 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 {
refresh_interval: None,
signal_at: None,
window_id,
dirty_at: Some(at(0)),
invalidations: 1,
draw_start: at(1),
draw_end: at(39),
phases: Default::default(),
}),
],
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, .. },
]
));
}
proptest! {
#![proptest_config(ProptestConfig {
failure_persistence: None,
..ProptestConfig::default()
})]
#[test]
fn detection_matches_threshold_and_blocking_work_model_at_boundaries(
durations_ms in prop::collection::vec(0u16..=50, 0..=16),
threshold_ms in 0u16..=60,
frame_budget_ms in 0u16..=60,
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 interval_end = origin + Duration::from_millis(interval_end_ms);
// Without a frame signal, the frame's work can't be measured.
let window_id = WindowId::from(1);
let snapshot = FrameSnapshot {
interval_start: origin,
boundary: IntervalBoundary::Presented(PresentedFrame {
frame: FrameTiming {
window_id,
dirty_at: Some(origin),
invalidations: 1,
draw_start: interval_end,
draw_end: interval_end,
refresh_interval: None,
signal_at: None,
phases: Default::default(),
},
presentation: PresentTiming {
window_id,
present_start: interval_end,
present_end: interval_end,
animation_interval: None,
},
}),
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 blocking_durations = durations_ms
.iter()
.copied()
.filter(|duration| *duration >= frame_budget_ms)
.collect::<Vec<_>>();
let expected_incident =
!qualifying_durations.is_empty() || !blocking_durations.is_empty();
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() {
blocking_durations
} 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 injections: Vec<Injection> = Vec::new();
for _ in 0..rng.random_range(1..=4) {
let duration = HANG_THRESHOLD + Duration::from_millis(rng.random_range(5..25));
let started = scheduler::Instant::now();
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
}
};
injections.push(Injection {
kind,
duration,
window: started..scheduler::Instant::now(),
});
// 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 injection in &injections {
assert_detected_once(injection, &contributors);
}
}
/// A slow view's draw is journaled under its type name with its own time,
/// excluding a slow view nested inside it, even when it's embedded through
/// an `AnyView`; fast phases aren't journaled, and the draw records how
/// long each of its phases took.
#[gpui::test]
fn slow_views_are_journaled_with_their_own_time(cx: &mut TestAppContext) {
let (journal, _journal_guard) = install_test_foreground_journal(1024, 16);
let mut collector = journal.collector();
let (_view, cx) = cx.add_window_view(|_, cx| SlowParent {
child: cx.new(|_| SlowChild).into(),
});
draw_window(cx);
let events: Vec<ForegroundEvent> = collector
.collect_unseen()
.entries
.into_iter()
.filter_map(|entry| match entry {
ForegroundJournalEntry::Event(event) => Some(event),
_ => None,
})
.collect();
let view_timing = |suffix: &str, phase: ViewPhase| {
events
.iter()
.rev()
.find_map(|event| match event {
ForegroundEvent::View(timing)
if timing.name.ends_with(suffix) && timing.phase == phase =>
{
Some(*timing)
}
_ => None,
})
.unwrap_or_else(|| panic!("expected a {phase:?} timing for {suffix}"))
};
let parent = view_timing("::SlowParent", ViewPhase::RequestLayout);
let child = view_timing("::SlowChild", ViewPhase::RequestLayout);
let parent_duration = parent.end.duration_since(parent.start);
let child_duration = child.end.duration_since(child.start);
assert!(child.self_duration >= SLOW_CHILD_RENDER);
assert!(parent.self_duration >= SLOW_PARENT_RENDER);
assert!(parent_duration >= child_duration + parent.self_duration);
assert!(!events.iter().any(|event| matches!(
event,
ForegroundEvent::View(timing) if timing.phase == ViewPhase::Paint
)));
let draw = events
.iter()
.rev()
.find_map(|event| match event {
ForegroundEvent::Draw(timing) => Some(*timing),
_ => None,
})
.expect("a draw");
assert!(draw.phases.request_layout >= SLOW_PARENT_RENDER + SLOW_CHILD_RENDER);
assert!(
draw.phases.request_layout + draw.phases.prepaint + draw.phases.paint
<= draw.draw_duration()
);
}
const SLOW_PARENT_RENDER: Duration = Duration::from_millis(3);
const SLOW_CHILD_RENDER: Duration = Duration::from_millis(2);
struct SlowParent {
child: AnyView,
}
impl Render for SlowParent {
fn render(&mut self, _: &mut Window, _: &mut Context<Self>) -> impl IntoElement {
thread::sleep(SLOW_PARENT_RENDER);
div().size_full().child(self.child.clone())
}
}
struct SlowChild;
impl Render for SlowChild {
fn render(&mut self, _: &mut Window, _: &mut Context<Self>) -> impl IntoElement {
thread::sleep(SLOW_CHILD_RENDER);
div().size_full()
}
}
struct Injection {
kind: HangKind,
duration: Duration,
window: std::ops::Range<scheduler::Instant>,
}
/// Exactly one contributor of the injected kind must fall inside the
/// injection's window, and it must be at least as long as the injected
/// sleep (sleeps never wake early). Contributors outside every window are
/// ignored: on a loaded machine, uninjected work can legitimately exceed
/// the threshold, and reporting it is correct.
fn assert_detected_once(injection: &Injection, contributors: &[ForegroundEvent]) {
let Injection {
kind,
duration,
window,
} = injection;
let matches: Vec<&ForegroundEvent> = contributors
.iter()
.filter(|event| {
matches_kind(event, *kind)
&& window.start <= event.start_time()
&& event.end_time() <= window.end
})
.collect();
assert_eq!(
matches.len(),
1,
"expected injected {kind:?} hang of {duration:?} to be reported exactly once; \
observed {:?}",
matches
.iter()
.map(|event| event.duration())
.collect::<Vec<_>>(),
);
if let Some(event) = matches.first() {
assert!(
event.duration() >= *duration,
"injected {kind:?} hang of {duration:?} was reported as {:?}",
event.duration(),
);
}
}
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 {
refresh_interval: None,
signal_at: None,
window_id,
dirty_at: Some(draw_end - Duration::from_millis(2)),
invalidations: 1,
draw_start: draw_end - Duration::from_millis(1),
draw_end,
phases: Default::default(),
}
}
}