Files
aevolution/docs/adr/0078-native-client-lifecycle.md
2026-10-08 12:08:53 -04:00

2.7 KiB

[Reviewed]

ADR-0078: Native client lifecycle and immutable presentation frames

Status

Accepted for M9.2 engineering client; no gameplay or protocol decision.

Context

SDL requires main-thread window/render ownership. A renderer must not retain mutable simulation stores, and DPI changes must not reinterpret world units.

Decision

Use one RAII application with a private SDL implementation, typed expected errors, and a synchronous bounded immutable frame of copied presentation primitives. Separate logical/drawable dimensions and content scale. Suspend rendering for hidden/minimized surfaces. Recreate on recoverable device reset; fail closed on device loss or adapter errors. Document the single-main-thread precondition. The executable owns pacing and exception handling. See CLIENT_ARCHITECTURE.md.

Linux X11 builds set SDL's supported SDL_X11_SHARED=OFF: link X11 libraries directly rather than repeatedly dlopen/dlclose them with SDL. Repeated init/quit with dynamic loading left 1,700,544 bytes reported by LeakSanitizer over this fixture (32 repeated lifecycles, a hidden window and failed renderer initialization). Preloading libX11 avoided the report; direct linking makes library lifetime explicit without a preload requirement or sanitizer suppression. This adds system X11 runtime dependencies when that backend is enabled; headless targets remain unaffected.

Alternatives considered

  • Public SDL handles: simple but leaks backend lifetime into callers; rejected.
  • Render thread / queued scene graph: unnecessary synchronization and lifetime complexity for this gate; defer until profiling justifies it.
  • Renderer directly reads world stores: violates the immutable view boundary.
  • Retry every failed frame: risks busy loops and hides fatal failures; rejected.

Benefits

Bounded memory and work, release-active failure tests, no graphical dependencies in headless targets. SDL can be replaced behind private source files.

Costs

Frame copy (bounded), one window, simple rectangles only. Native library/global state precludes embedding another SDL owner in the same process for this scope.

Risks

Synthetic events do not prove a real GPU reset or physical multi-monitor DPI. System driver allocations remain outside owned-code instrumentation. Direct linking addresses the observed unload/lifecycle case, not every platform library leak or arbitrary GPU driver. Re-run repeated native lifecycle checks on upgrades.

Consequences

M9.3 adds camera and input intentions; M9.4/5 add biology-derived projections. No current simulation interfaces, rules or formats change. Desktop packaging, hardware matrix and native driver recovery remain explicit qualification work.