ilusha/Modules
1
0
Fork 0
Code Issues Pull requests 1 Projects Releases Packages Wiki Activity Actions 45

Diagnostics: hang watchdog with scoped reports and thread stacks #6

Closed
agent wants to merge 2 commits from Diagnostics into master
pull from: Diagnostics
merge into: ilusha:master
Conversation 0 Commits 2 Files changed 8 +817
agent commented 2026-10-27 23:15:28 +03:00
Collaborator
Copy link

Base: master @ ab5e4bc. Two commits, 8 files, +817/−0, all authored by agent.

Why

A frozen UI needs an actionable local report rather than only a stalled window. This adds the Diagnostics module and a HangWatchdog that records what the UI was doing, captures every thread through the merged Callstack/StackTrace, and leaves a report that can be inspected with gdb or eu-stack.

How it works

  • enterPhase(UiPhase) marks idle/input/draw/present; noteInputEvent() counts events handled in the current phase.
  • A watchdog thread checks every 100 ms. A non-idle phase longer than thresholdMs (2 s by default) creates a report; follow-ups default to 10 s and 30 s, and recovery is appended when the UI moves on.
  • summary.txt is written before thread sampling and contains the stuck phase, input count and open scope trail. threads.txt contains repeated per-thread stack samples with name, scheduler state and kernel wait channel.
  • Verdicts distinguish a repeatedly identical sleeping stack (blocked), a running/changing stack (busy), and sleeping at changing places (polling/lock contention).
  • Debugger pauses are discounted rather than reported as hangs; if a debugger is attached, sampling is skipped and the report says so. allowDebuggerAttach() permits same-user debuggers on Linux.
  • Contributors can add application-specific files. The newest 20 reports are kept.
  • Default location is $HOME/<process>/hangs, overridden by MODULES_HANG_DIR.

UiTrail is private to Diagnostics, and the directory logic is local, so there is no AppStorage dependency. The tests drive the trail directly instead of depending on the profiler.

Verification

Built the library and test executable locally and ran the UnitTest++ suite:

Success: 9 tests passed.
Test time: 4.90 seconds.

The root build registers add_subdirectory(Diagnostics). Tests are always built as on current master; no MODULES_BUILD_TESTS gate is introduced.

Closed: GraphicApplication is the watchdog's only consumer, so this logic belongs to the application layer. HangWatchdog and UiTrail moved into the local Graphics branch in e585c14; the standalone Diagnostics module is dropped. All 9 watchdog tests still pass.

**Base:** `master` @ `ab5e4bc`. Two commits, 8 files, +817/−0, all authored by `agent`. ## Why A frozen UI needs an actionable local report rather than only a stalled window. This adds the `Diagnostics` module and a `HangWatchdog` that records what the UI was doing, captures every thread through the merged `Callstack/StackTrace`, and leaves a report that can be inspected with `gdb` or `eu-stack`. ## How it works - `enterPhase(UiPhase)` marks idle/input/draw/present; `noteInputEvent()` counts events handled in the current phase. - A watchdog thread checks every 100 ms. A non-idle phase longer than `thresholdMs` (2 s by default) creates a report; follow-ups default to 10 s and 30 s, and recovery is appended when the UI moves on. - `summary.txt` is written **before** thread sampling and contains the stuck phase, input count and open scope trail. `threads.txt` contains repeated per-thread stack samples with name, scheduler state and kernel wait channel. - Verdicts distinguish a repeatedly identical sleeping stack (blocked), a running/changing stack (busy), and sleeping at changing places (polling/lock contention). - Debugger pauses are discounted rather than reported as hangs; if a debugger is attached, sampling is skipped and the report says so. `allowDebuggerAttach()` permits same-user debuggers on Linux. - Contributors can add application-specific files. The newest 20 reports are kept. - Default location is `$HOME/<process>/hangs`, overridden by `MODULES_HANG_DIR`. `UiTrail` is private to Diagnostics, and the directory logic is local, so there is no `AppStorage` dependency. The tests drive the trail directly instead of depending on the profiler. ## Verification Built the library and test executable locally and ran the UnitTest++ suite: ``` Success: 9 tests passed. Test time: 4.90 seconds. ``` The root build registers `add_subdirectory(Diagnostics)`. Tests are always built as on current master; no `MODULES_BUILD_TESTS` gate is introduced. --- **Closed:** `GraphicApplication` is the watchdog's only consumer, so this logic belongs to the application layer. `HangWatchdog` and `UiTrail` moved into the local Graphics branch in `e585c14`; the standalone Diagnostics module is dropped. All 9 watchdog tests still pass.
agent added 2 commits 2026-10-27 23:15:28 +03:00 
HangWatchdog watches UI phase timestamps and writes a report when a non-idle
phase exceeds its threshold. It records the phase, handled input count and open
scope trail, samples every thread through StackTrace, and classifies the UI as
blocked, busy or waiting repeatedly. Reports support follow-ups, recovery,
custom contributors and retention.

The scope trail is private to Diagnostics. The default report directory is
HOME/<process>/hangs, overridable with MODULES_HANG_DIR, so the module needs no
AppStorage dependency.
Diagnostics: cover hang reporting with unit tests
Some checks are pending
Windows / build (pull_request) Waiting to run
Details
CMake on a single platform / build (pull_request) Waiting to run
Details
CMake / build (pull_request) Waiting to run
Details
66c7b7c4a5 
The tests exercise blocked and busy reports, scope names, debugger pauses,
summary-before-sampling, input event counts, idle suppression, contributors and
report retention. They drive UiTrail directly and run with an injectable clock.
agent 2026-10-27 23:15:29 +03:00
  • closed this pull request
  • requested review from ilusha
Some checks are pending
Windows / build (pull_request) Waiting to run
Details
CMake on a single platform / build (pull_request) Waiting to run
Details
CMake / build (pull_request) Waiting to run
Details

Pull request closed

Please reopen this pull request to perform a merge.
Sign in to join this conversation.
Reviewers
No reviewers
ilusha
Labels
Clear labels
No items
No labels
Milestone
Clear milestone
No items
No milestone
Projects
Clear projects
No items
No project
Assignees
Clear assignees
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference: ilusha/Modules#6
No description provided.
Delete branch "Diagnostics"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?