105 lines
6.4 KiB
Markdown
105 lines
6.4 KiB
Markdown
# Private same-executable process protocol
|
|
|
|
0.1.12 uses anonymous stdin/stdout pipes, with no listening ports or public endpoint.
|
|
Roles are `--worker`, `--presentation-host`, `--keep-awake`; only the parent-created
|
|
pipe handles connect them. They must use the same executable build. This is an
|
|
internal unversioned wire protocol, not a stable external API; mixed builds are
|
|
unsupported. Persistent disk representations have independent version contracts.
|
|
|
|
Messages are little-endian u32 byte length followed by UTF-8 JSON (16 MiB maximum).
|
|
Worker replies declare `bytes`; frame pixels follow as raw RGBA8, at most 64 MiB,
|
|
validated against returned dimensions. No payload is allowed without frame metadata.
|
|
Open/render carry generation epochs; supervisor completions retain generation and
|
|
job tags so stale results cannot replace a newer document. Notes are requested
|
|
separately. Settings, file pickers and cached-frame reads also run in workers.
|
|
|
|
Supervisors bound command/result queues, kill/reap on deadlines, and recreate failed
|
|
workers on the next job. Foreground/background deadlines are 30 s, settings/cache
|
|
reads 10 s, native chooser 300 s. Linux workers die with the parent; Unix workers
|
|
attempt a 3 GiB address-space limit. Windows memory job limits remain outstanding.
|
|
No worker I/O or process wait is performed in a rendering/input callback.
|
|
|
|
Presentation HostState contains sequence, page, verified frame paths, neighbour
|
|
preloads, monitor IDs, fullscreen and blank flags. It contains no notes or operator
|
|
UI text. ACKs report only frames submitted successfully to all active output windows;
|
|
this is not optical proof that a projector displayed a frame. Heartbeats detect a
|
|
stopped host after 8 s; at most three starts, recovery blanked. A presenter crash
|
|
leaves the independent host displaying its last frame. Normal exit sends quit and
|
|
allows bounded shutdown outside the UI loop. Reconnection to an orphan is pending.
|
|
|
|
## Whole-deck buffering in 0.1.13
|
|
|
|
Preview requests first check the verified target-resolution artifact, falling back to
|
|
512 only on a miss. Replies identify the actual requested render edge and cache-hit
|
|
status. The two workers prepare the remaining deck concurrently with foreground
|
|
navigation able to supersede outstanding work.
|
|
|
|
HostState now carries a document/resolution generation, decoded RAM budget and the
|
|
currently resident target-frame preload list. Since 0.1.19 the host mirrors this
|
|
working set, retires evicted entries and discards stale read completions. It can
|
|
free distant cached frames to admit a replacement while protecting the displayed
|
|
and requested frames. Its acknowledgment counts actual resident entries for that
|
|
generation, rather than all previously processed slides. READY requires both presenter and host
|
|
counts to reach the deck total. Stale acknowledgments cannot mark another resolution
|
|
ready. The bounded JSON envelope and raw-frame limits remain unchanged. This protocol
|
|
still requires the same executable build at both ends.
|
|
|
|
|
|
## File chooser ownership and admission, 0.1.15
|
|
|
|
`Pick` carries `folder` and optional `owner` (a signed native Windows HWND integer;
|
|
null on other platforms). This identifier belongs to the parent presenter process,
|
|
is never dereferenced as worker memory, and is passed to the Windows common dialog
|
|
as its owner. Only the active presenter (or first available presenter) supplies it;
|
|
an audience window is never the owner. Windows requests without an owner fail clearly.
|
|
The protocol remains private and requires matching executable builds.
|
|
|
|
The shared Studio admits exactly one outstanding chooser job, including across
|
|
mirrored presenters and alternating PDF/folder requests. Repeated Open actions are
|
|
ignored and the corresponding menu controls are disabled until a completion arrives.
|
|
Success, cancellation, worker error and the existing 300-second deadline all release
|
|
the guard; submission failure never sets it. The native host re-enables presenter
|
|
input and restores owner focus after completion, including a worker killed while the
|
|
common dialog had disabled its owner. Existing slide-browser windows temporarily
|
|
lose topmost status while the chooser is active. Rendering/output stay independent.
|
|
|
|
|
|
## Output shutdown and lost presenter, 0.1.16
|
|
|
|
No wire fields change. EOF/failed input drops the host command sender; the native
|
|
host detects receiver disconnection instead of treating it as an empty queue forever.
|
|
An established output keeps its last frame after unexpected connection loss, while
|
|
Close or Escape requests exit on the next event-loop tick. A disconnected host with
|
|
no windows exits immediately. B still blanks. With a live presenter, output Close or
|
|
Escape retains the existing emergency-blank behavior.
|
|
|
|
Normal presenter shutdown signals the supervisor and allows 500 ms for graceful
|
|
completion, then terminates/reaps the owned child through a separate shared process
|
|
handle. The handle is never locked during pipe writes, so a blocked writer cannot
|
|
prevent termination. A further one-second manager completion wait is bounded.
|
|
Event-loop errors and OutputLink destruction use this cleanup path as well. OS process
|
|
termination/reaping still relies on OS responsiveness; these bounds are not a promise
|
|
against kernel/driver failure. Unexpected presenter death deliberately does not use
|
|
parent-death termination for the audience, to preserve the last usable frame.
|
|
|
|
|
|
## Display setup recovery, 0.1.21
|
|
|
|
HostState adds default-false `setup_controls` and optional `route_trial` (u64 trial
|
|
identifier). Startup controls allow an output-side right-click swap only before the
|
|
first explicit navigation/show action; a pending trial always exposes minimal
|
|
Keep/Revert controls. Output ACKs can carry `display_action` (`Swap`, `Keep`, `Revert`)
|
|
and `route_trial`. The parent validates startup eligibility and trial identity;
|
|
stale confirmations cannot commit a later trial. The parent owns the 15-second
|
|
monotonic deadline and does not persist routes/fullscreen flags until confirmed.
|
|
A late Keep is treated as rollback. Host EOF clears recovery controls so orphan
|
|
Escape/Close remains available. Notes, source paths and operator layout data are
|
|
still absent from this control payload. Private same-build IPC only.
|
|
|
|
## Slide background colors, 0.1.26
|
|
|
|
HostState carries `slide_colors` with `page_background` and `fit_padding` RGB byte
|
|
triples (default white/black). Color updates use the existing state sequence and
|
|
repaint existing textures without changing buffer generation or reading slide files.
|
|
Blank output remains black. Same-executable protocol only.
|