Skip to content

Lifecycle and quit reach the loop as a HostEvent - #1484

Merged
GLinnik21 merged 2 commits into
mainfrom
platform/w5a-host-lifecycle
Nov 20, 2026
Merged

GLinnik21 merged 2 commits into
mainfrom
platform/w5a-host-lifecycle

Conversation

@GLinnik21

@GLinnik21 GLinnik21 commented Nov 20, 2026 •

Copy link
Copy Markdown
Collaborator

Step W5a of the platform plan (discussion #1460), the first step of the event contract. Lifecycle and quit reach the loop as an app-private HostEvent instead of raw SDL codes. On Tizen the same function will receive the hosted stop as HostEvent::Quit. No behaviour change on webOS or the simulator.

What changes

  • app/events.rs gains pub(crate) enum HostEvent { Lifecycle(Lifecycle), Quit } and Lifecycle { WillBackground, DidBackground, WillForeground, DidForeground }, beside decode_key, plus decode_host_event(&[u8]) -> Option<HostEvent>:

    SDL type Variant
    0x100 (SDL_QUIT) Quit
    0x103 Lifecycle(WillBackground)
    0x104 Lifecycle(DidBackground)
    0x105 Lifecycle(WillForeground)
    0x106 Lifecycle(DidForeground)
    anything else None: the raw path, unchanged
  • app/run.rs: the drain decodes first. A HostEvent goes to one consumer, ingest_host_event, which runs host_background for both background edges and host_foreground for both foreground edges, and handles Quit. Every effect runs in the same order as before: telemetry, restore_window on 0x106, the park and resume of playback, the quit path, the recorder. Keys, text, pointer and wheel keep today's raw path; they are W5b and W5c. ingest_sdl_event_with_window keeps its name and signature, because ci/list-caps.ini keys an entry on it.

  • The recorder tape stays the SDL code. Lifecycle::sdl_code() feeds enc_lifecycle and the other SDL-coded sinks (window activity, telemetry), so recordings are byte-equal.

  • ui/src/fixture.rs: the source pin an_app_switch_suspends_every_body_and_the_loop_is_what_delivers_it used to look for the literal et == 0x103 || et == 0x104. It now finds host_background and host_foreground, bounded to each function's body, and asserts the same things. It also pins ingest_host_event's two dispatch arms: both edges of each pair reach their function.

  • No C ABI is added (the hosted entry is W9). No new process global, no ledger line, and the fnlen budgets are untouched.

Tests

New:

  • events.rs: the decode table, the lifecycle round-trip through sdl_code, and every other event staying on the raw path.
  • recorder.rs: a lifecycle edge is recorded as the SDL code it arrived as, for all four variants.
  • run.rs lifecycle_regression_tests, which feed each event both ways (SDL bytes, and a HostEvent handed to ingest_host_event) and compare what the loop leaves:
    • a host Quit takes an SDL_QUIT's path, also during playback and during a controlled replay;
    • a host lifecycle sequence parks and resumes as the SDL codes do, including the crash-step trail;
    • a WILL edge sent alone does its own work. WILL background parks the film, suspends the tree and dismisses the keyboard. WILL foreground resumes the tree and leaves the window and film restore to DID. This test fails when either arm is narrowed to its DID edge, and the narrowed foreground arm also fails the pin;
    • the tape is byte-equal for 0x103-0x106 in order, and a quit is not recorded.

Bounded runs on the committed tree (efad77e):

  • make test-crate C=app T=recorder: test result: ok. 55 passed; 0 failed; 0 ignored; 0 measured; 1435 filtered out.
  • make test-hostsim, whole suite. Two existing tests SIGSEGV on this Mac in the system libGL with no GL context: player_owner_events_record_and_replay_through_the_actual_app_host, and an_unregistered_product_screen_uses_generic_navigation_and_actual_store_effects, which also crashes on main. With both skipped, the built binary gives test result: ok. 1725 passed; 0 failed; 0 ignored; 0 measured; 2 filtered out in three runs.
    • A fourth run failed deeplink_route_tests::a_play_landing_waits_for_an_abandoning_preview and …_behind_a_preview_that_never_returns_gives_up. Both read the process-global plx_media::route::play_pending() without testlock::serial(), so they race under load. That is code this PR does not touch, and both passed on the rerun.
  • ci/check-deps.sh, ci/check-module-layers.py and ci/check-ledger-ratchet.py: green.

On the review-fix head 5d68d8e (committed, clean tree):

  • make test-hostsim T=a_host_: test result: ok. 7 passed; 0 failed; 0 ignored; 0 measured; 1721 filtered out.
  • lifecycle_regression_tests, with the known SIGSEGV test skipped: test result: ok. 171 passed; 0 failed; 0 ignored; 0 measured; 1557 filtered out.
  • make test-crate C=plx_ui T=an_app_switch_suspends: test result: ok. 1 passed; 0 failed.
  • make test-crate C=plx_telemetry T=window: test result: ok. 13 passed; 0 failed; 1 ignored.
  • ci/check-deps.sh, ci/check-module-layers.py and ci/check-ledger-ratchet.py: green.

Not run here: make check, check-nodef and the ARM cross-build. This PR's own CI gates them.

🤖 Generated with Claude Code

GLinnik21 and others added 2 commits November 20, 2026 12:13
…by the SDL drain (W5a)

Quit and the four lifecycle edges (WILL and DID enter background, WILL and DID enter foreground)
used to be read from SDL's event type inside one long ladder in ingest_sdl_event_with_window.
They now arrive as an app-private HostEvent (HostEvent::Quit, HostEvent::Lifecycle(WillBackground
| DidBackground | WillForeground | DidForeground), in app/events.rs): the SDL decoder
(decode_host_event, beside decode_key) maps SDL_QUIT and 0x103..0x106 to it, and one function in
the loop, run::ingest_host_event, consumes it. A hosted stop is the same HostEvent::Quit an
SDL_QUIT decodes to and takes the same path; no C ABI is added (plx_host_post and plx_host_stop
are W9's).

Nothing changes on webOS or in the simulator. The effects are the arms they were, moved
verbatim into host_background and host_foreground and run in the same order: the window gate,
telemetry's crash steps and session, the controlled-replay refusal, the damage note, the tape
record, the park and resume of the tree and playback, restore_window on DID foreground. The
SDL-coded readers (window activity, telemetry, and the tape, whose recorded codes are the format)
are fed Lifecycle::sdl_code(), the inverse of the decode table, so enc_lifecycle writes the same
code for each edge and every recorded tape replays as before. Key, text, pointer and wheel events
keep their raw path in ingest_sdl_event_with_window (W5b and W5c move them).

Tests: the decode table both ways and the raw events that must stay raw (events.rs); the four edges
recorded as the literal records an earlier build wrote (recorder.rs); and, on the hostsim rig, the
same events delivered as SDL bytes and as a HostEvent leave the same loop, the same crash steps,
the same tape and the same inputs to Exit::played, for Quit on a bare app, during playback and in a
controlled replay, and for a park and resume of a playing film. The source pin in plx_ui's
fixture follows the two arms to their new functions.

Co-Authored-By: Claude <noreply@anthropic.com>
…t_foreground in the window prose (W5a)

Review of the HostEvent change found that nothing tied a single edge to its arm. An
`ingest_host_event` arm narrowed to `Lifecycle::DidBackground => host_background(..)`, with
`WillBackground` falling to `{}`, would have passed every test: the plx_ui pin found only the two
function definitions, the sequence test reads its values after the DID edges (which repeat what
WILL did), and every other test sends WILL and DID as a pair.

`a_host_will_edge_does_its_arms_work_without_its_did_edge` sends WILL background alone to a
playing film, then WILL foreground alone, delivering each both as SDL bytes and as a HostEvent
and comparing what the loop leaves. WILL background alone parks the film, suspends the tree and
queues the keyboard dismissal; WILL foreground alone resumes the tree but leaves the film parked
and the window unpresented, since only the DID edge restores them. The plx_ui source pin also
now follows the consumer's dispatch (both edges of each pair reach their function), bounded to
that function.

telemetry's window.rs doc comments on its `background` and `foreground` fixtures named "the
run.rs background/foreground arm"; they now name `host_background` and `host_foreground` in
`app/run.rs`.

Co-Authored-By: Claude <noreply@anthropic.com>
@GLinnik21
GLinnik21 merged commit 1adff84 into main Nov 20, 2026
14 checks passed
@GLinnik21
GLinnik21 deleted the platform/w5a-host-lifecycle branch November 20, 2026 10:12
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant