PdfRenderTrace class
One end-to-end, per-phase record of a single page render, spanning both isolates.
A page render is a pipeline whose phases live on different threads:
parse → interpret → serialize → transfer → deserialize → replay → rasterize └───────────── worker/isolate half ──────────────┘ └──── main-isolate half ────┘
Before this type there was no shared record: the worker filled an isolate-
private PdfWorkerPhaseTimings and the main isolate assembled its own
separate string log, so nothing yielded one comparable breakdown. This
value type is the single record both halves fill - the worker attaches its
phases (via addWorker/direct field writes), and the main isolate completes
the transfer, deserialize, replay, and rasterize phases - and is the surface
the CI perf gate asserts against (see test/render_trace_gate_test.dart).
All phase fields are microseconds. They are mutable accumulators because one
worker job can serialize both a transcript and its image-bearing buffer, and
a progressive page is recorded in more than one pass; sum with +=. The
worker sub-phases (streamUs, interpretUs, decodeUs, serializeUs,
binUs) are a breakdown within workerUs (the worker's total wall time),
not additional to it; endToEndUs adds the phases that happen outside the
worker.
Constructors
- PdfRenderTrace({int pageIndex = -1})
Properties
- binUs ↔ int
-
Strip-binning time (
StripPlanBinner), when the job binned strips.getter/setter pair - cosStats ↔ PdfPerfStats?
-
A deep copy - a stable snapshot of a still-mutating accumulator.
The COS-layer PdfPerf delta recorded across this capture (per-filter
decode times, object loads, cache-relevant counters), attached by
captureOffThread when
PdfPerf.enabled. Null otherwise. Carried by copy; min keeps whichever side has one (it is a breakdown, not a timing to minimize).getter/setter pair - decodeUs ↔ int
-
Off-thread image decode time (pure-Dart / browser codec).
getter/setter pair
- deserializeUs ↔ int
-
Command-buffer deserialization time (
deserializeCommands).getter/setter pair - endToEndUs → int
-
Whole-pipeline wall time: the queue wait, the worker, the transfer, and
the main-isolate finish. Uses workerUs when the backend reported it,
otherwise the worker sub-phase sum (the captureOffThread case).
no setter
- hashCode → int
-
The hash code for this object.
no setterinherited
- imageDecodeSummary ↔ String?
-
How the browser image codec fared on this job, web-only diagnostics for
#458 (e.g.
codec=2orcodec=0 declined=2(noCapability)). Null on the native backend and the VM captureOffThread path, which never invoke it. A silently-declined browser decode is otherwise indistinguishable from one that ran, so it is surfaced next to decodeUs in the phase log. Carried like cosStats (keep-whichever), not summed, since only the image-bearing pass of a progressive page fills it.getter/setter pair - interpretUs ↔ int
-
Interpreter walk time. In captureOffThread this is the content + annotation
walk; in the worker's async path it is the annotation pass only (the
content walk is folded into streamUs).
getter/setter pair
- mainPhasesUs → int
-
Sum of the main-isolate phases done after the buffer arrives.
no setter
- pageIndex ↔ int
-
The page this trace describes, or -1 when not attributed to one page.
getter/setter pair
- parseUs ↔ int
-
Content-stream tokenize time, when measured separately from interpret.
getter/setter pair
- queueUs ↔ int
-
Time the request waited in the main-side priority queue before dispatch.
getter/setter pair
- rasterizeUs ↔ int
-
Rasterization time (
Picture.toImage+ readback). Only filled by a Flutter-hosted capture; 0 in the pure-Dart captureOffThread.getter/setter pair - replayUs ↔ int
-
Command-replay time - walking the deserialized commands into a device (a
ui.Pictureon the main isolate; a headless walk in captureOffThread).getter/setter pair - runtimeType → Type
-
A representation of the runtime type of the object.
no setterinherited
- serializeUs ↔ int
-
Command-buffer serialization time (
serializeCommands).getter/setter pair - streamUs ↔ int
-
Combined content-stream parse + interpret time (the worker's async path).
getter/setter pair
- transcriptHit ↔ bool
-
Whether the worker served this page from its retained transcript cache.
getter/setter pair
- transferUs ↔ int
-
Cross-isolate transfer time (round trip minus workerUs).
getter/setter pair
- workerPhasesUs → int
-
Sum of the worker sub-phases. Approximates workerUs (which also carries
scheduling/yield overhead the sub-phases don't).
no setter
- workerUs ↔ int
-
The worker's total wall time for the job, when the backend reports it.
getter/setter pair
Methods
-
add(
PdfRenderTrace other) → void - Folds another trace's phases into this one (used to accumulate a progressive page's several worker passes into one record).
-
copy(
) → PdfRenderTrace -
format(
) → String - One-line, human-readable breakdown; omits phases that never ran.
-
min(
PdfRenderTrace other) → PdfRenderTrace -
The per-phase minimum of
thisandother(each field taken from whichever trace is faster). Best-of-N over repeated captures defeats the GC/scheduler jitter that would otherwise make a wall-clock gate flaky. -
noSuchMethod(
Invocation invocation) → dynamic -
Invoked when a nonexistent method or property is accessed.
inherited
-
toString(
) → String -
A string representation of this object.
override
Operators
-
operator ==(
Object other) → bool -
The equality operator.
inherited
Static Methods
-
captureOffThread(
PdfDocument document, int pageIndex, {bool annotations = true, bool decodeImages = false}) → PdfRenderTrace? - Captures the VM-measurable, off-thread half of a page render as a single trace - the one interface that yields an end-to-end per-phase breakdown of one page without a browser, an isolate, or a raster backend.