Skip to main content

Module overlay_worker

lattice_host

Module overlay_worker 

Source
Expand description

Background overlay worker — static-overlay bucketing off the UI thread.

Phase 5.8.AF.5 / Slice X2.3 (origin); display-line B4.2 (gut + rename).

§Why this exists

Per paramount goal #1 in CLAUDE.md:

Performance. UI thread does no I/O, no parsing, no shaping.

This worker pre-buckets the active document’s static overlay layers (hlsearch matches, LSP document-highlights, :s/// substitute preview) into per-row quad lists so neither renderer peer has to walk every overlay range against every visible row inside its per-frame paint body.

§History (B4.2 gut + rename)

Until display-line slice B4.2 this module was highlights_worker and carried TWO jobs:

  • the span / row prepaint cache (VisibleSpans / VisibleRows / RowPrepaint, built by build_rows / build_rows_with_cache / weave_row) — consumed by the renderers’ shaping path. The cells / display-matrix migration (B-series) severed every read of that cache, so B4.2 deleted it wholesale.
  • the static-overlay bucket (bucket_static_overlays) — still consumed every frame by both renderers’ overlay paint paths (TUI render.rs, GPUI editor_element.rs). This is the live half and is all that remains here.

The module was renamed overlay_worker because it no longer produces highlights — only overlay quads.

§Design

  • Dispatch’s publish_render_state populates crate::render_state::SyntaxRenderState inputs (syntax_handle, scroll, viewport_height, fold_hash, text_version, doc_highlights, static_overlay_version) and fires crate::editor::OverlayWake’s Notify.
  • The worker notified().awaits the wake signal. Notify is permit-style: a burst of publishes wakes the worker exactly once, after which the worker re-reads the latest snapshot.
  • On wake the worker reads render_state.load_full().syntax, constructs a crate::render_state::VisibleHighlightsKey, compares it against the key in the currently-published crate::render_state::StaticOverlayQuads, and short-circuits on cache-hit.
  • On cache-miss with a current snapshot: re-buckets the overlay layers into per-row quad lists and stores a fresh StaticOverlayQuads into the durable syntax_static_overlay_quads_cell Arc<ArcSwap<…>>.
  • On cache-miss with a stale snapshot (snapshot’s text_version < document’s text_version): the worker applies the stale-snapshot HOLD — it stores the new key but preserves the previously-published quads, so a mid-edit window doesn’t recolour overlay backgrounds against pre-edit data.

§Renderer contract

Renderer peers read with:

let rs = editor.render_state.load_full();
let quads = rs.syntax.static_overlay_quads.load();
// quads.quads[i] = per-row RowOverlayQuad list for visible line i

Empty quads is the legal “no overlays yet” state (initial boot, no overlay layers active, or a pre-first-worker-tick window). Renderers paint no overlay backgrounds in that case.

Enums§

WorkerDecision
Recompute decision the worker takes on a wake. Visible for testing; the production loop calls recompute directly.

Functions§

recompute
Pure synchronous recompute. Reads the current published SyntaxRenderState, decides whether to recompute, and updates static_overlay_quads_cell accordingly. Returns the decision taken so tests can assert cache-hit / stale-snapshot HOLD / recompute paths without driving the async loop.
run
Worker entry point spawned at boot. Loops forever, awaiting the wake Notify. Each wake re-reads the latest RenderState.syntax inputs and calls recompute.