Task: 2026/10/31/stop-a-widget-on-its-last-picture-when-the-paint-bounds-refuse-its-frames
24 KiB
test_widget_host
Type: Reusable API. Source contract: test_widget_host.h.
Use when
A scenario needs what a widget message's twidget::WidgetHost was built with
and what it reported, exactly: the options as they entered the Job that
builds the host, after an optional override of the measurement options (the
stress kit's measure pass), and the host's own onChange readings: its
SandboxStats, the validator's node count, loaded with the host's
loadedMs, the first dead reason verbatim with when it arrived, the diag
kinds with their counts and the first 20 console texts of level error.
Nothing else gives these: WidgetHost keeps its options private,
Tgw::Runtime::Host is incomplete outside tgw_runtime.cpp, the runtime log
(Runtime::logText(), _summary) rounds and clips the readings, and the
validated-ops tap sees only what reaches the renderer.
The watch also times the renderer's own work on that host's widget: a
disposable overlay puts a WidgetWorkScope into three Tgw::RendererCore
calls, and each scope of the core the watch's attachment registered records
one event into the watch's work log (Renderer work).
Callers: the widget fixture arms a watch for a record whose watchHost is
set (test_widget_fixture). Its consumers are the
stress-kit runner (test_widget_stress), which reads
the applied options for config.applied, the host readings for each run
entry and the work log for its renderer figures, and the widget conformance
runner (test_widget_conformance), which arms
an empty-override watch on every run, so every option stays the product's,
and reads it once, in the run's log stage before the removal, for each
construction's applied contentSafeArea (its safeArea extra).
Use something else when:
- the validated ops, their counts or a widget's published result matter: test_widget_ops;
- whether a card is live, interactive or painted now matters: the fixture's
card readings and
Tgw::Runtime::state(); - the runtime's own log text is enough: the fixture's
RequestRuntimeLog().
Preconditions and limits
- Arm before construction.
ArmWidgetHostWatch(id, measure)acts on the constructionsTgw::Runtime::construct()starts from then on, matched againstHistoryItem::globalId(): the message'sFullMsgIdplus its session'suniqueId(), as for the tap. The fixture arms it next to the tap, beforeHistory::addNewLocalMessage(). Arming an armed id returns its watch with its first override. - Active harness. Both seams return the options unchanged or do nothing
unless
Test::Active()and the id is armed. - What the override changes. Only the fields it gives:
policy,features,memoryLimitBytes,cpuLimitMs,cpuQuotaMs,cpuQuotaWindowMs,mainThreadQuotaMs,maxTimers.cpuKillAfterMs,visible,devicePixelRatio,locale,contentSafeArea,storage,dataandcontextstay whatDefaultHostOptions()andRuntime::construct()set. In a Debug build the product multipliescpuLimitMs,cpuQuotaMs,cpuQuotaWindowMsandmainThreadQuotaMsbykCpuLimitScale(4); that scale stays in every field the override does not give, andappliedshows it. - What
appliedis. The options right after the override: exactly what theJob's.optionsholds, whichBuild()passes to theWidgetHostconstructor unchanged. Only the measurement fields are kept; storage, data, context and any id never are. - One host per measurement. Each armed options call adds one
appliedentry and each attachment onehostsentry, in order, never merged. A construction whose build the runtime discards (Runtime::constructed()'s early returns: a newer generation, a failed build, quitting or no current content, crashes, a changed theme, storage or data) leaves anappliedentry without a host. A consumer that measures one host accepts a reading only with exactly one entry of each. More name a rebuilt or replaced host: that reading is invalid for it, and the helper does no replacement-host recovery. An older host's callback keeps writing only its own record. - Freshness.
statsare the last stats the host delivered. The engine posts them at most every 200 ms, with a trailing post, and refreshesmemoryBytesat most once a second;statsChangedAtis when a merge last found them changed, not a fresh observation at read time. - Load and death times.
loadedMsis the host's own, from its creation toloaded.diedAtMsis steady-clock time from the host's creation to the merge that first sawdead, on the host thread right after the host stored it: the same clock and origin asloadedMs. The creation isWidgetHost::createdAt_, read once by value with the private-member accessor of test_chat_show and the fixture; the options call runs before thecrl::asyncbuild and is not the creation. - Death reason.
deadis the first reason seen, verbatim (a counted strict cap reads likeOps limit exceeded: 12000 operations in one batch (max 10000)), not the renderer's localized stopped label. Destroying a host that is still alive ends its engine withterminated, which arrives as one more change: read the widget's own death before the removal;terminatedafter it is the destruction.deadcomes only from the host'sWidgetDiagnostics::dead. A stop the desktop decides itself, such as a paint bound's refusal of the widget's frames, stops theRendererCoreand retires the runtime without the host: the watch keepsdeadnull, orterminatedwith that destruction'sdiedAtMsonce the retired host is destroyed. The runners read such a stop with the fixture'sWidgetDesktopStop()(test_widget_fixture), never from this record. - Logs and diags.
errorskeeps the first 20 console texts of levelerror, verbatim;errorLogscounts them all. The host keeps at most 5000 console entries (logs), so later ones reach neither.diagsis kind to count, as the host's diagnostics have them. - Not measured. No window frame, presentation or host-thread timing, no
JS time beyond
stats.jsMs, and no renderer timing at all unless the disposable overlay places the work scopes (Renderer work).
Minimal use
Through the fixture, with the stress kit's measure options; the fixture's
gates, its Runner::onFinish release and the stage that opens the chat come
first (test_widget_fixture):
const auto message = Test::AddWidgetFixtureMessage(*fixture, u"stress"_q);
message->watchHost = Test::WidgetHostOverride{
.policy = "compat",
.memoryLimitBytes = size_t(64) << 20,
.cpuQuotaMs = 10000.,
.cpuQuotaWindowMs = 1000.,
.mainThreadQuotaMs = 10000.,
.maxTimers = 256,
};
runner->add({
.name = u"inject the watched widget"_q,
.run = [=] {
const auto error = Test::InjectWidgetMessage(
*fixture,
*message,
state->html,
390,
0);
Test::Check(error.isEmpty(), u"the widget is injected"_q, error);
},
});
runner->add({
.name = u"wait for loaded or dead"_q,
.run = [=] { state->started = crl::now(); },
.until = [=] {
const auto r = message->host
? Test::ReadWidgetHost(*message->host)
: Test::WidgetHostReading();
const auto done = !r.hosts.empty()
&& (r.hosts.front().loaded || r.hosts.front().dead);
return done || (crl::now() - state->started > kLoadBound);
},
.then = [=] {
const auto r = message->host
? Test::ReadWidgetHost(*message->host)
: Test::WidgetHostReading();
Test::Check(
(r.applied.size() == 1) && (r.hosts.size() == 1),
u"one options call and one host"_q,
u"applied=%1 hosts=%2"_q.arg(
QString::number(int(r.applied.size())),
QString::number(int(r.hosts.size()))));
},
.timeout = kLoadBound + Test::kDefaultStageTimeout,
});
// With the renderer overlay applied, time one level's renderer work:
runner->add({
.name = u"start the measuring window"_q,
.run = [=] {
Test::ReserveWidgetWork(*message->host, 65536);
state->windowStart = crl::profile();
},
});
// ... after the window:
// const auto work = Test::ReadWidgetWork(
// *message->host,
// state->windowStart);
// Test::Check(
// !work.dropped && (work.registered == 1) && !work.events.empty(),
// u"the renderer work was timed whole"_q);
// ... then remove the message and assert the barrier:
runner->add({
.name = u"remove the widget and wait for its host"_q,
.run = [=] { Test::RemoveFixtureMessage(*fixture, *message); },
.until = [=] { return Test::FixtureBarrierDecided(*message); },
.then = [=] {
Test::Check(
message->tap
&& Test::WidgetTapFinished(Test::ReadWidgetOps(*message->tap)),
u"the widget's hosts are gone"_q);
},
.timeout = Test::kWidgetBarrierBound + Test::kDefaultStageTimeout,
});
Readings and refusals
ReadWidgetHost(watch) returns a WidgetHostReading snapshot on the main
thread: applied, one WidgetHostApplied per armed options call, and
hosts, one WidgetHostSample per attached host, each copied under its own
record's lock. The helper refuses nothing; it records, and the consumer
decides.
WidgetHostApplied field |
Meaning |
|---|---|
policy, features |
The policy and opt-in features the host was built with. |
memoryLimitBytes, cpuLimitMs, cpuQuotaMs, cpuQuotaWindowMs, cpuKillAfterMs, mainThreadQuotaMs, maxTimers |
The limits, as the Job got them. |
visible, devicePixelRatio, locale, contentSafeArea |
The product's values, never overridden; recorded so a consumer can show they were kept. |
WidgetHostSample field |
Meaning |
|---|---|
core |
The RendererCore address WatchWidgetHost() got, compared with a card reading's core, never dereferenced. |
attachedAt |
crl::profile() at the attachment. |
stats, statsChangedAt, statsChanges |
The last SandboxStats, when a merge last found them changed and how many merges did. |
nodes |
The validator's node count of the last merge. |
loaded, loadedMs, loadedAt |
The host reported loaded; its own loadedMs; crl::profile() of the first merge that saw it. |
dead, diedAtMs, deadAt |
The first dead reason, verbatim; steady-clock ms from the host's creation to the merge that saw it; that merge's crl::profile(). |
diags |
Diag kind to count. |
errors, errorLogs, logs |
The first 20 error console texts; every error entry; every console entry the host kept. |
changes |
onChange calls merged, the attachment's snapshot not counted. |
Every ...At stamp is 0 until its event. A reading with more than one
applied or hosts entry is diagnostic only for a single-host consumer.
Renderer work
The renderer's own work on one widget, as the stress kit's
packages/stress/CLIENTS.md ("The renderer's own work") asks an own
renderer to time it, recorded as raw events; turning them into per-frame
samples is the consumer's (the stress runner groups each frame() attempt
with the work since the previous one, counts the attempts that replayed
apart and documents that grouping next to its figures).
The overlay
No retained code times anything: tgw_renderer.cpp has no scope, counter
or condition, and without the harness this module defines no
WidgetWorkScope member. A task that measures applies a disposable hunk to
tgw/tgw_renderer.cpp, never commits it and restores the file afterwards.
Every added line sits inside #if defined _DEBUG || defined TDESKTOP_RELEASE_TEST_HARNESS, so the hunk compiles in both harness
configurations and nowhere else:
#include "test/test_widget_host.h";RendererCore::hostMessage(): right after the stopped,requestFrameandfrozenreturns,const auto workScope = Test::WidgetWorkScope(this, Test::WidgetWorkKind::Message);;RendererCore::tick(): at entry, the same withWidgetWorkKind::Tick;RendererCore::frame(): right after the cached-framereturn _frame;,auto workScope = Test::WidgetWorkScope(this, Test::WidgetWorkKind::Frame);, right afterconst auto list = _renderer->paint();,workScope.displayList(list.size());, and right afterauto painted = PaintFrame(list, *_backend, size, _renderer->dpr());,workScope.replayed(!painted.image.isNull());. The flag reads the image this attempt's replay produced, before it is moved into_frame, never the retained_frame: a frame the paint bounds refuse keeps the card's last picture that fits it in_frame, so!_frame.isNull()would count that refusal as a replay.
Without the overlay a registered core records nothing, so an empty log for a widget whose content changes is a missing overlay: an invalid measurement, never zero renderer work.
What the events include
All three run on the main thread, from the scope's construction to its destruction:
Message: one host message applied.beginCanvasBatch()and TwidgetCore'sreceive()(the batch's ops, ananimor a query, and, when no frame is due, the settle it starts at once: style, layout and the display list), the settled viewport answer on the load, thenfinish(): forwarding the answers to the host link (a post to the host thread), the clock refresh and the synchronousupdates()handler,Tgw::Runtime::coreUpdated(), whose repaint or resize request and height memory are therefore included. The message's JSON parse on the host thread (HostRenderer::send()) and itscrl::on_mainhop come before it.Tick: the wholeRendererCore::tick(), run bystep()on the app's animation timer or bywake(): TwidgetCore'stick()(its timers, animations and a build a due frame deferred), forwarding its output and theframemessage that answers the widget'srequestAnimationFrame, and posting the change notice.Frame: one attempt at a picture past the cache, while the chat list paints.paint()(the settle: style, layout and the display list, or its reuse),PaintFrame()(the QPainter replay into an ARGB32 image on the CPU),RoundFrame()and, after a settle,flushQueued(). A size the list has not laid out yet runspaint()and keeps the earlier picture without a replay; that call is aFrameevent too, withreplayedfalse, while an attempt whosePaintFrame()returned an image hasreplayedtrue. One the paint bounds refused returned none, so it isreplayedfalse, whatever picture the card keeps.displayListis the size of the listpaint()returned.
Not included: the chat list's own painting around the card and its
drawImage() of the returned picture, the window's backing-store flush
(BitBlt) and DWM composition, hostTheme(), hostLoaded(), input
forwarding, every early return named above (a cached frame() included),
any host-thread or JS-thread work (stats.jsMs, the ops tap's parse and
scan) and other widgets' cores.
Overhead: an event runs from the constructor's last act, its clock read, to
the destructor's first, so it holds about one crl::profile() read
(QueryPerformanceCounter) and the registry lookup of any scope nested in it.
The lookup and the log reference copy before the start and the append after
the end are outside every event but are main-thread time the app's frames
see. A scope of a core nobody registered costs a walk of the registered
addresses, none while nothing is registered.
Registration, nesting and storage
- Which core.
WatchWidgetHost()of an armed watch (so only with an active harness) registers thecoreaddress it got, for its attachment's index inhosts; scopes compare theirthiswith the registered addresses and never dereference either.DisarmWidgetHostWatch()unregisters every core of the watch. An address belongs to one live core, so a newer attachment of the same address, by any watch, replaces an older registration. - Replaced hosts and address reuse. Each event carries its attachment's
hostindex, so a second host's work is never merged silently, and a single-host consumer refuses a reading with more than one host. A core destroyed while its watch stays armed leaves its address registered: another message's core later allocated there would be timed into this log until the watch is disarmed or that core attached. Disarm when the level's message is removed (the fixture does) and measure one widget alive at a time. - Nesting. Only the outermost open scope of a watch records; one opened inside it is inert, its time already in the outer event, so no work is counted twice. Scopes of different watches record independently.
- Storage.
ReserveWidgetWork(watch, capacity)starts the log over for one level: it forgets earlier events and drops, allocates room forcapacityevents at once, so recording never allocates, and stampsreservedAt. The firstcapacityevents to close after it are kept; each later one only counts indropped, and a nonzerodroppedmakes the level invalid. Before the first reservation the capacity is 0 and every event is dropped. Size the capacity for the whole period the level reads: the app's animation tick runs every 8 ms (about 125 ticks a second), and messages and rebuilt frames come at most about as often, so 65536 events (2 MiB at 32 bytes each) cover more than two minutes at that pace. - Reading.
ReadWidgetWork(watch, since)copies the events whosefinishedis at or aftersince, in the order they finished: with one open scope per watch at a time,finishednever decreases.
WidgetWorkEvent field |
Meaning |
|---|---|
kind |
Message, Tick or Frame, by the scope's place. |
started, finished |
crl::profile() microseconds at the scope's construction and destruction. |
displayList |
The display list size a Frame scope was given; -1 otherwise. |
replayed |
A Frame scope whose PaintFrame() ran and returned an image; false for an attempt that returned before the replay, for one the paint bounds refused, and for every other kind. |
host |
The index in WidgetHostReading::hosts of the attachment that registered the core. |
WidgetWorkReading field |
Meaning |
|---|---|
events |
The recorded events finished at or after the stamp asked for. |
reservedAt, capacity |
The last reservation's stamp (0 before one) and room. |
dropped |
Events that found the log full since that reservation; nonzero: incomplete. |
registered |
Cores of this watch's attachments still registered. |
Production seams
.options = Test::OverrideWidgetHostOptions(_item->globalId(), std::move(options))is theJob's options initializer inTgw::Runtime::construct(), on the main thread, before thecrl::asyncbuild: one call per construction.Test::WatchWidgetHost(_item->globalId(), *_host->pointer, _live.get())inTgw::Runtime::constructed(), on the main thread, after the stale-build checks, theRuntime::Hostcreation andsyncHostVisibility(), immediately beforeRendererCore::bindHost()andWidgetHost::start().- Inactive harness: one
Active()check each. An active harness with an unarmed id: one lookup of the armed map each, no clock read, lock, insertion, diagnostics copy or callback change. The options identity still costs a call and a move of the options; it is not free. - Without the harness, a build that is neither Debug nor configured with
TDESKTOP_RELEASE_TEST_HARNESS(Release builds with the harness),test_widget_host.cppdefines only these two functions, the identity and a no-op; every other declaration of the header is left undefined there. - The work scopes are not production seams: they exist only in the disposable overlay (The overlay), and no retained product file calls anything of the timing API.
Threads and lifetime
- Arming, disarming, reading and both seams run on the main thread; the armed
map, keyed by
GlobalMsgId, and each watch'sappliedand host list are main-only. - The attachment runs one synchronous
WidgetHost::onHostThread()call from main: it merges the host'sdiagnostics()and setsonChangethere, so no change falls between the snapshot and the callback, and a diag the host posted from its constructor (a stale validator bytecode does) cannot race the callback's assignment. Beforestart()the host thread runs at most such a diag and no task of it waits on main, so the hop is short and cannot deadlock. The product makes its own synchronous host calls off main (ApplyTheme()runs on a worker, because itsprobe()can wait on the engine); this one is the harness's, for armed hosts only. - Each host's record has its own mutex. The callback merges into it on the
host thread (
twidget-host), reading its two clocks before taking the lock and calling nothing while holding it; reads copy it on main. - The callback captures the record, the host's creation time by value and the
product's earlier
onChange, which this tree never sets. It holds noWidgetHostpointer, noHostPointeror weak pointer and noReservationslot, so it never prolongs the host or its slot. It is destroyed with the host in~WidgetHoston theHostDeleterworker, after the host thread was joined, so no merge follows it. - Observer cost: with
onChangeset,WidgetHost::changed()copies the whole diagnostics (up to 5000 console entries, the actions and bridge calls) on the host thread for every change, which the product deliberately avoids (HostLinkreads the resize anchor in place for this reason). Stats changes come at most about five times a second, plus each log, diag, load and death. It is host-thread work, not JS or main-thread work, and a measurement discloses it. - The work registry, each work log and every scope are main-thread only,
with no lock: registration in
WatchWidgetHost(), unregistration inDisarmWidgetHostWatch(),ReserveWidgetWork(),ReadWidgetWork()and theRendererCorecalls that hold the scopes all run there. A scope keeps a reference to its log, so a disarm or a released watch while it is open cannot leave it writing freed memory; its event still lands in that log.
Lifetime and cleanup
ArmWidgetHostWatch() returns a shared watch that the armed map keeps until
DisarmWidgetHostWatch(); keep the caller's copy (the fixture's
WidgetFixtureMessage::host) until its last reading. Disarming stops later
constructions and unregisters the watch's cores, so their scopes record
nothing more; hosts already attached keep merging into their records until
they are destroyed. A work log keeps its reserved room until the watch is
released. The fixture disarms in RemoveFixtureMessage() and
ReleaseWidgetFixture(); a direct caller disarms on its Runner::onFinish
path. Nothing is written to the account, the disk or the clipboard.
Verification
Executed in the app: the stress runner's Release dry runs and both measured
passes (one options call and one host per level, unscaled production
defaults, the measure override with the product's visibility, locale, DPR
and safe area kept, loaded with loadedMs, verbatim dead with
diedAtMs, and with the overlay nonempty work logs without drops); the
replayed flag and its overlay line are compiled (Debug, Win32, MSVC), not
yet run in the app, and the stress self-check counts it on synthetic events.
The overlay line on PaintFrame()'s PaintedFrame result above is a
description: the retained tree has no such line, so it compiles only in
the overlay of a task that applies it.
Executed by the conformance task
2026/10/29/report-the-desktop-conformance-and-run-the-stress-kit-at-widget-sandbox-v0-3-0,
recorded in its work/smoke.md: the watch's first in-app run, on macOS
arm64 in a Release build with TDESKTOP_RELEASE_TEST_HARNESS and no LTO,
through the conformance runner's empty-override watch. Every loaded run of
auto/04-values-units, auto/31-stop-text, auto/36-safe-area and
visual/17-time-corner had one applied entry with the product's
contentSafeArea: all 0 for the two messages with a caption below the
widget, bottom 26 with cornerRight 118 for the two safeArea entries,
equal to auto/36-safe-area's own contentSafeAreaInset reading.
Related guidance
Validated-ops tap; widget fixture; Release builds with the harness; scenario teardown.