Using Hot Path Shortcuts

Using Hot-Path Shortcuts

Lifecycle indexes: Implemented · Researched · Unproven

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.

vCPU shortcut campaigns

For vCPU Shortcut Candidates, record both the selected route and the emitted/executed host work. A same-binary A/B is invalid when the candidate was selected but the relevant guest instruction or helper boundary was never reached.

Approximate routes—especially native reciprocal estimates—must report numerical divergence separately from performance. Exact routes must include a negative control that deliberately violates the admission assumption and proves that the reference/fallback path still protects the guest state.

Correctness invariants must run before route selection

Merged PR #123 is a direct shortcut-design lesson.

Disabling Process vertex packets in bulk exposed a path where oversized array packets could bypass dispatcher-level complete-packet capacity validation and reach scalar handlers. The preflight belonged to the operation, not to the optimized bulk route.

flowchart TD
    A[Incoming packet] --> B[Validate complete packet / capacity / atomicity]
    B -->|Invalid| C[Reject consistently]
    B -->|Valid| D{Shortcut policy}
    D -->|Bulk| E[Bulk handler]
    D -->|Reference| F[Scalar/trace handler]

Loading

A maintained reference route is not merely “the old code.” It must preserve every correctness invariant used by the optimized route.

Qualification should cover invalid/oversized input with optimized, forced-reference, and tracing routes and compare exact rejection/consumption behavior.