Sessielevenscyclus

Documentatie voor versie v0.1.0-beta.3Bron bekijken op GitHub

Vertaling van de oorspronkelijke Engelse pagina voor OmsiLaunch 0.1.0-beta3. De Engelse pagina is normatief: bij verschillen gelden de Engelse pagina en de code.

Deze pagina beschrijft hoe een OmsiLaunch-sessie via SessionState van Created naar Completed of Failed gaat: welk onderdeel elke toestand instelt, welke telemetrie-events van de plugin de overgangen aansturen, hoe de opstart-timeout werkt, wat stoppen betekent (geforceerde beëindiging), wat WaitForAsync retourneert, welke toestanden eindtoestanden zijn, welke toestanden nooit of nauwelijks waarneembaar zijn en welke garanties de CLI-eigenaar geeft. Alles hier is ontleend aan OmsiLaunchService.StartAsync, SuperviseAsync en ApplyTelemetry (src/OmsiLaunch.Core/OmsiLaunchService.cs), PluginRuntime (src/OmsiLaunch.Plugin/PluginRuntime.cs) en OwnerSession (tools/OmsiLaunch.Cli/Program.cs).

Gerelateerde pagina's: openbare API, foutcodes, transacties en recovery, permanente plugin, runtimebesturing, lokaal control plane, Windows-systeemvak, CLI-referentie, status van de runtimevalidatie, de map .omsilaunch.

Overzicht#

PlanSessionAsync                       (no state; returns a SessionPlan)
StartSessionAsync ─ caller thread ─────────────────────────────────────────────
  Created
  AcquiringInstallationLock            lease Local\OmsiLaunch.Installation.<hash>
  RecoveringPreviousTransaction        stale journal restored before anything is read
  Snapshotting → ApplyingConfiguration journal Prepared, overlays written, deletions removed, Applied
  DeployingRuntime                     journal RuntimeDeployed (plugin is permanent; nothing copied)
  CreatingStartupHandoff               handoff, telemetry slot, runtime mailbox; journal HandoffCreated
  StartingProcess                      CreateProcessW Omsi.exe
  WaitingForPlugin                     journal ProcessStarted (PID, creation time, exe path) → handle returned
SuperviseAsync ─ background task ──────────────────────────────────────────────
  PluginBootstrap                      telemetry plugin.started
  StartingWorld                        telemetry world.starting (NEW_MAP only)
  Running                              telemetry gameplay.entered
  ProcessExited                        OMSI exited or was terminated; journal ProcessExited
  Restoring                            exact restore of every session-owned file
  CleaningRuntime                      restore verified; journal removed; backups removed
  Completed                            stores disposed, lease released
  Failed                               from any point above; restore still runs

Referentie van SessionState#

Waarden in declaratievolgorde. "Ingesteld door" noemt de code die Move/Fail aanroept; "Waarneembaar" geeft aan of GetStatusAsync/WaitForAsync de toestand in de praktijk kan zien.

Eindtoestanden: Completed en Failed. Na een van beide keert WaitForAsync onmiddellijk terug en keert CloseAsync terug zonder een stop aan te vragen.

Verificatie van "nooit ingesteld": een zoekactie in de codebase naar SessionState.ValidatingPlatform, SessionState.Planning en SessionState.EnteringGameplay vindt alleen de enum-declaratie; SessionState.Snapshotting komt één keer voor, direct gevolgd door Move(SessionState.ApplyingConfiguration).

Startfase (StartSessionAsync)#

1. Een niet-uitvoerbaar plan wordt afgewezen (OL_E_PLAN_NOT_RUNNABLE); de specificatie wordt opnieuw gepland (opnieuw de hash van Omsi.exe berekenen, content opnieuw resolven, de plugin-closure opnieuw controleren) en opnieuw afgewezen als ze niet langer uitvoerbaar is. De live sessie wordt geregistreerd (Created).
2. De host-trace <root>\.omsilaunch\diagnostics\<sessionId>-host.log wordt aangemaakt (oudere bestanden met sessievoorvoegsel buiten de 50 nieuwste sessies worden opgeschoond). StartupTimeoutSeconds buiten 1..600 wordt afgewezen (ArgumentOutOfRangeException; de registratie van de sessie wordt ongedaan gemaakt).
3. AcquiringInstallationLock → lease. RecoveringPreviousTransaction → een openstaand journal herstellen (een journal van vóór de vingerafdrukken dat het eigendom niet kan bewijzen, wordt uitgesteld en opnieuw geprobeerd zodra de overlays van deze sessie bestaan), de plugin-closure van de permanente plugin valideren, de hash van het uitvoerbare bestand berekenen, een verouderde closecheck verwijderen en de transactie opbouwen (overlays: patches van options.cfg, BMP's van het beheerde opstartscherm, Texture\standard.itx; verwijderingen: ITX-doelen, Texture\standard.ipr, closecheck als die niet bestaat).
4. Snapshotting → ApplyingConfiguration → DeployingRuntime → CreatingStartupHandoff → StartingProcess → WaitingForPlugin, waarna de supervisortaak start en de handle wordt geretourneerd.
5. Elke exceptie in stap 3–4 wordt opgevangen: de sessie wordt Failed met OL_E_START_SESSION (inner message), een aangemaakt proces wordt beëindigd en er wordt op gewacht, stores worden vrijgegeven, de transactie wordt hersteld (OL_E_RESTORE_FAILED bij een fout) of, als het afsluiten van OMSI niet kon worden bevestigd, openstaand gelaten met OL_E_RESTORE_DEFERRED; de lease wordt vrijgegeven. StartSessionAsync retourneert in dit geval toch de handle; lees GetStatusAsync.

Bij het opnieuw plannen blijft de SessionId van de aanroeper behouden, zodat de id in de handle gelijk is aan plan.SessionId.

Supervisie (SuperviseAsync)#

De supervisor draait als taak in de threadpool en doorloopt elke 100 ms een lus totdat OMSI is afgesloten of een stop is aangevraagd:

1. Het meest recente telemetriemonster lezen (een slot met alleen de laatste waarde en een producentvolgnummer; half geschreven monsters worden overgeslagen; identieke opeenvolgende events zijn verschillend omdat het volgnummer verschilt). Elk nieuw monster wordt aan RuntimeEvents toegevoegd en door ApplyTelemetry toegewezen.
2. Als de sessie Failed is, wordt de lus verlaten.
3. Als de sessie nog niet Running is en de deadline (StartupTimeoutSeconds na het binnengaan van de supervisor) is verstreken: Fail met OL_E_STARTUP_TIMEOUT als PluginBootstrap was bereikt, anders OL_E_PLUGIN_NOT_LOADED; de lus wordt verlaten.

Na de lus: als OMSI vóór Running is afgesloten en er geen fout is vastgelegd, volgt Fail met OL_E_PROCESS_EXITED_EARLY. Daarna, ongeacht of de sessie is mislukt: OMSI beëindigen als het nog leeft, wachten tot het is afgesloten, het journal op ProcessExited zetten, naar ProcessExited gaan, herstellen (Restoring → CleaningRuntime) of OL_E_RESTORE_FAILED/OL_E_RESTORE_DEFERRED vastleggen, de proceshandle, handoff, het telemetrieslot en de runtime-mailbox vrijgeven, de lease vrijgeven en naar Completed gaan, tenzij de toestand Failed is. Een fout in de supervisor zelf wordt vastgelegd als OL_E_PROCESS_SUPERVISION (problemen bij het opruimen als OL_E_PROCESS_CLEANUP_FAILED) en hetzelfde pad voor beëindiging en herstel wordt doorlopen.

Omdat Failed blijvend is, is het enige bewijs dat een mislukte sessie is hersteld het ontbreken van OL_E_RESTORE_FAILED/OL_E_RESTORE_DEFERRED in haar diagnoses (en het ontbreken van journal.json); herstelnotities (restore.session-artifact-removed, OL_W_RESTORE_FOREIGN_FILE_RETAINED) verschijnen in beide gevallen.

Telemetrie-events#

De plugin publiceert JSON-monsters { "name": ..., "data": {...} } in het telemetrieslot; de host legt elk nieuw monster vast als een RuntimeEvent(Type = name, TimestampUtc = host receipt time, Sequence, Data).

Kanttekeningen: het slot bevat één monster, zodat events die binnen één poll van 100 ms door de host worden verzonden, verloren kunnen gaan (de plugin onderdrukt lifecycle-events gedurende 2 s na gameplay.entered en publiceert nooit een D3D-event in de tick die gameplay.entered publiceert, zodat de grens Running niet wordt gemist). RuntimeEvents bewaart de 256 meest recente events; oudere worden verwijderd. Het is geen verliesvrij logboek. Lees events via GetStatusAsync, session.events op het control plane of events read|watch in de CLI.

Opstart-timeout#

ShutdownTimeoutSeconds wordt in de specificatie meegegeven, maar niet gebruikt: er is geen wachttijd bij het afsluiten.

Stopsemantiek#

Elke stopaanvraag is dezelfde canonieke aanvraag: StopAsync(handle) vanuit de API, CloseAsync op een sessie die zich niet in een eindtoestand bevindt, session.stop op het lokale control plane (gebonden aan de actieve sessie-id), "End session" (sessie beëindigen) in het systeemvak, Ctrl+C of het sluiten van de console bij de CLI-eigenaar, en het einde van /observe-seconds.

Semantiek van WaitForAsync#

Het poll-interval is 100 ms, zodat waargenomen overgangen tot 100 ms achterlopen op de werkelijke.

Levenscyclusgaranties van de eigenaar (CLI)#

OwnerSession.RunAsync in tools/OmsiLaunch.Cli/Program.cs is de referentie-eigenaar.

Integrators die hun eigen eigenaar schrijven, moeten de eerste twee garanties reproduceren: één StartSessionAsync per installatie tegelijk, en CloseAsync op elk pad.

Foutenoverzicht#

Elk foutpad probeert nog steeds te beëindigen en te herstellen; een journal dat overblijft, wordt bij de volgende start of door RecoverPendingAsync / /recover hersteld (transacties en recovery).