Using Hot Path Shortcuts

Using Hot-Path Shortcuts

Scope: Testing a guarded bypass against its maintained general/reference route.

For saved settings, requested/effective state, CLI overrides, persistent caches, restart-latched policies and general evidence campaigns, see Using Performance Controls.

This page applies only when the mechanism is classified as a shortcut in Hot-Path Shortcuts.

The central question is:

Does skipping this specific piece of general-path work change correctness, ordering, guest progress, frame tails or resource use when both routes run in the same Release executable?

1. Name the exact bypass

Do not begin with a setting label such as “Vulkan fast path.” State the operation that is omitted.

Good examples:

Exact 32-bit fence read bypasses pgraph.lock.
Eligible color download bypasses a separate submit/wait boundary.
Clean texture stage bypasses normal per-stage bind/update work.
Full scanout key hit bypasses render_display().
Exact QPC scale bypasses muldiv64().

A valid experiment must identify:

Entry point
General/reference route
Optimized bypass route
Eligibility guard
Fallback
Failure if guard is wrong

2. Prove the reference route is real

The Off/Disabled side is not useful merely because a UI checkbox changed.

It must execute the maintained route that the shortcut bypasses.

flowchart TD
    A[Same operation and same binary] --> B{Shortcut policy}
    B -->|Reference| R[General route counter increments]
    B -->|Optimized| O[Bypass counter increments]
    R --> V[Same correctness/order oracle]
    O --> V

Loading

Reject the campaign when:

• the optimized side never attempts the shortcut;
• the reference side never enters the general route;
• the route is unavailable on the selected backend/platform;
• a restart-pending value means the requested mode is not active;
• another setting changes the same dependency chain.

3. Guards are part of the result

A shortcut is not “enabled” simply because policy permits it.

policy permits shortcut
    + operation reaches shortcut site
    + every mandatory guard passes
    = optimized route actually taken

Required counter classes:

attempts
eligible
optimized route
forced reference route
blocked by reason
fallback after optimized-route failure

For a fixed policy window, an accounting identity should normally exist, for example:

eligible = optimized + forced_reference

The exact identity must match the implementation. Do not invent a universal equation when fallback or retry paths overlap.

4. Do not turn safety checks into controls

A shortcut control may select the final policy gate. It must not disable the guard that proves the shortcut safe.

flowchart TD
    A[Operation state] --> G[Mandatory correctness/capability/lifetime guards]
    G -->|Fail| R[General route]
    G -->|Pass| P[Policy gate]
    P -->|Permit| O[Shortcut]
    P -->|Force reference| R

Loading

The following are not valid performance switches:

• dirty-memory publication;
• DMA/source-address revalidation;
• surface overlap and required readback;
• object lifetime generations;
• complete vertex-fetch bounds;
• original event-handle readiness;
• timer failure fallback;
• query/report ordering;
• exact QPC divisibility;
• capability and format support checks.

If the experiment must disable one of those, it is a correctness research branch, not a normal shortcut comparison.

5. Identify side-effectful guards

Some checks mutate state while deciding eligibility.

Examples include:

• test-and-clear dirty-memory operations;
• consuming or resetting event state;
• retiring retry state;
• invalidating a retained-output key;
• publishing a completed resource generation.

Do not call a side-effectful guard twice—once for the route and once for telemetry. Capture its result once, then use that result for both the decision and counters.

6. Classify constants before testing

A shortcut may use constants, but the constant must be labeled correctly.

Constant class	Example	Test requirement
Semantic	Exact register width or format block size	Specification/source proof
Capability-derived	Host format feature or QPC divisibility	Startup/device proof
Heuristic	1.25 ms short-wait threshold	Sensitivity sweep across hosts/workloads
Current-model assumption	PFIFO status modeled as constant	Preserve current behavior and state limitation explicitly
Capacity/resource tuning	8 MiB initial buffer	Resource sweep; does not make mechanism a shortcut

A hard-coded value without a classification is a documentation defect.

7. Choose the correct experiment

Deterministic correctness isolation

Use for stale output, wrong shader, missed wake, crash or ordering failures.

same binary
same input/snapshot
reference route reproduces or avoids symptom
shortcut route does the opposite
route counters prove both paths
oracle identifies exact difference

Same-binary performance ABBA/BAAB

Use when route state does not contaminate later processes.

A1 reference
B1 shortcut
B2 shortcut
A2 reference

Then reverse order:

B3 shortcut
A3 reference
A4 reference
B4 shortcut

Keep fixed:

• executable SHA-256;
• source commit;
• Release build profile;
• matching workload/snapshot/input;
• renderer and selected GPU/driver;
• fixed guest-progress window;
• unrelated performance controls.

Live-transition test

Use when policy changes can leave shortcut-owned state behind.

optimized route active
    -> change policy
    -> generation/invalidation observed
    -> next operation forced through fresh/reference work
    -> no pre-change cached object crosses boundary incorrectly

8. Read evidence in dependency order

Do not start with frame percentages.

1. Binary identity — same executable and source?
2. Effective policy — did requested mode become active?
3. Availability — was the route supported?
4. Reachability — did the shortcut site execute?
5. Eligibility — did guards pass often enough to test it?
6. Reference proof — did the comparison side run the general route?
7. Fallbacks — did the optimized route silently fail back?
8. Correctness/order/lifetime — equivalent?
9. Local avoided work — did the intended operation fall?
10. End-to-end effect — guest progress, p50/p95/p99/max, CPU/GPU/resources?

9. Interpret common outcomes

Result	Meaning
Attempts = 0	Workload did not reach the shortcut
Attempts > 0, eligible = 0	Guards rejected every attempt; inspect block reasons
Eligible > 0, optimized = 0	Policy publication/gate/counter defect
Reference = 0 in reference mode	Comparison did not force the general route
Local work falls, frame time unchanged	Bypassed work is not end-to-end limiting
Average improves, p99 worsens	Shortcut changes tails or contention; not a simple pass
More guest work and more host CPU	Efficiency requires fixed-work normalization
Fallbacks high	Optimized mechanism is unreliable or workload is outside its intended domain
Output differs	Stop performance interpretation; shortcut failed correctness

10. Feature-specific proof

Lock bypasses

Prove exact address/width selection, publication ordering, reset/load behavior and unsupported-access fallback.

Reuse/early-return shortcuts

Prove complete dependency keys, invalidation, object lifetime, completion state and fresh work after policy transitions.

Submission folding

Prove producer order, barriers, capacity-growth recomputation and CPU visibility at the same caller-visible completion point.

Capability fast paths

Prove host support, effective representation, all unsupported-layout fallbacks and equivalent output.

Arithmetic specializations

Prove equality over the complete admitted input domain, monotonicity/overflow properties and no extra hot-path policy lookup.

Heuristic shortcuts

Sweep the threshold. Report CPU and latency tails separately. A threshold that wins on one host is not automatically a product constant.

11. Acceptance checklist

[ ] Mechanism is actually a shortcut, not merely another optimization class
[ ] General/reference route identified
[ ] Exact bypassed work identified
[ ] Guard and fallback documented
[ ] Constant/threshold classified
[ ] Same Release executable used
[ ] Optimized attempts > 0
[ ] Eligible count > 0
[ ] Optimized route count > 0
[ ] Reference route count > 0
[ ] Block and fallback reasons understood
[ ] Correctness oracle matches
[ ] Ordering and lifetime checks pass
[ ] Local avoided work measured
[ ] Fixed-work guest progress measured
[ ] p50/p95/p99/max reviewed
[ ] CPU/GPU/RAM/VRAM reviewed where relevant
[ ] Reference route remains maintained and tested

Final mental model

shortcut
    = maintained correct route
    + narrow proof
    + explicit bypass
    + safe fallback
    + evidence that both routes executed

A resource policy, cache, prepared plan or cleaner algorithm can be an excellent optimization without being a shortcut.

Related pages

• Performance Optimization Catalog
• Hot-Path Shortcuts
• Using Performance Controls
• Performance Methodology
• Debugging Tools & Commands

Equivalent versus approximate shortcuts

A shortcut campaign must declare its acceptance class before measurement. Equivalent shortcuts require independently seeded reference/candidate state and no unexplained output, ordering, interrupt, fault or lifetime difference. Approximate shortcuts require an explicit error or quality budget, compatibility scope, recovery behavior, and a maintained exact route; output equality is not their claim. See Assumption-Based Shortcut Validation.