Sitzungslebenszyklus

Dokumentation für Version v0.1.0-beta.3Quelle auf GitHub ansehen

Übersetzung der englischen Originalseite für OmsiLaunch 0.1.0-beta3. Maßgeblich ist die englische Seite: Bei Abweichungen gelten die englische Seite und der Code.

Diese Seite beschreibt, wie eine OmsiLaunch-Sitzung SessionState von Created bis Completed oder Failed durchläuft: welche Komponente jeden Zustand setzt, welche Telemetrieereignisse des Plugins die Übergänge auslösen, wie das Start-Timeout funktioniert, was Stoppen bedeutet (erzwungene Beendigung), was WaitForAsync zurückgibt, welche Zustände terminal sind, welche Zustände nie oder kaum beobachtbar sind und welche Garantien der CLI-Eigentümer gibt. Alles hier stammt aus OmsiLaunchService.StartAsync, SuperviseAsync und ApplyTelemetry (src/OmsiLaunch.Core/OmsiLaunchService.cs), PluginRuntime (src/OmsiLaunch.Plugin/PluginRuntime.cs) und OwnerSession (tools/OmsiLaunch.Cli/Program.cs).

Verwandte Seiten: öffentliche API, Fehlercodes, Transaktionen und Recovery, permanentes Plugin, Runtime-Steuerung, lokale Steuerungsebene, Windows-Tray, CLI-Referenz, Runtime-Validierungsstatus, das .omsilaunch-Verzeichnis.

Überblick#

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

SessionState-Referenz#

Werte in Deklarationsreihenfolge. „Gesetzt von“ nennt den Code, der Move/Fail aufruft; „Beobachtbar“ gibt an, ob GetStatusAsync/WaitForAsync den Zustand in der Praxis sehen können.

Terminale Zustände: Completed und Failed. Nach einem dieser Zustände kehrt WaitForAsync sofort zurück, und CloseAsync kehrt zurück, ohne einen Stopp anzufordern.

Überprüfung von „nie gesetzt“: Eine Suche in der Codebasis nach SessionState.ValidatingPlatform, SessionState.Planning und SessionState.EnteringGameplay findet nur die Enum-Deklaration; SessionState.Snapshotting kommt einmal vor, unmittelbar gefolgt von Move(SessionState.ApplyingConfiguration).

Startphase (StartSessionAsync)#

1. Einen nicht ausführbaren Plan ablehnen (OL_E_PLAN_NOT_RUNNABLE), die Spezifikation erneut planen (Omsi.exe erneut hashen, Inhalte erneut auflösen, die Plugin-Closure erneut prüfen) und erneut ablehnen, wenn sie nicht mehr ausführbar ist. Die aktive Sitzung registrieren (Created).
2. Den Host-Trace <root>\.omsilaunch\diagnostics\<sessionId>-host.log anlegen (ältere Dateien mit Sitzungspräfix jenseits der 50 neuesten Sitzungen werden bereinigt). StartupTimeoutSeconds außerhalb von 1..600 ablehnen (ArgumentOutOfRangeException; die Registrierung der Sitzung wird aufgehoben).
3. AcquiringInstallationLock → Lease. RecoveringPreviousTransaction → ein ausstehendes Journal wiederherstellen (ein Journal aus der Zeit vor dem Fingerprint, das die Eigentümerschaft nicht nachweisen kann, wird zurückgestellt und erneut versucht, sobald die Overlays dieser Sitzung existieren), die Plugin-Closure des permanenten Plugins validieren, die ausführbare Datei hashen, ein veraltetes closecheck entfernen, die Transaktion aufbauen (Overlays: options.cfg-Patches, verwaltete Startbild-BMPs, Texture\standard.itx; Löschungen: ITX-Ziele, Texture\standard.ipr, closecheck, wenn es nicht existiert).
4. Snapshotting → ApplyingConfiguration → DeployingRuntime → CreatingStartupHandoff → StartingProcess → WaitingForPlugin; danach startet der Supervisor-Task, und das Handle wird zurückgegeben.
5. Jede Ausnahme in den Schritten 3–4 wird abgefangen: Die Sitzung ist Failed mit OL_E_START_SESSION (innere Meldung), ein bereits erstellter Prozess wird terminiert und abgewartet, die Speicher werden freigegeben, die Transaktion wird wiederhergestellt (OL_E_RESTORE_FAILED bei Fehlschlag) oder, falls das Beenden von OMSI nicht bestätigt werden konnte, mit OL_E_RESTORE_DEFERRED ausstehend belassen; die Lease wird freigegeben. StartSessionAsync gibt auch in diesem Fall das Handle zurück; lesen Sie GetStatusAsync.

Die erneute Planung behält die SessionId des Aufrufers bei, sodass die ID im Handle gleich plan.SessionId ist.

Überwachung (SuperviseAsync)#

Der Supervisor läuft in einem Thread-Pool-Task und durchläuft alle 100 ms eine Schleife, bis OMSI beendet ist oder ein Stopp angefordert wurde:

1. Die neueste Telemetrieprobe lesen (ein Slot für den jeweils neuesten Wert mit einer Produzenten-Sequenznummer; inkonsistente Proben werden übersprungen; identische aufeinanderfolgende Ereignisse sind unterscheidbar, weil sich die Sequenznummer unterscheidet). Jede neue Probe wird an RuntimeEvents angehängt und von ApplyTelemetry zugeordnet.
2. Ist die Sitzung Failed, die Schleife verlassen.
3. Ist die Sitzung noch nicht Running und ist die Frist (StartupTimeoutSeconds nach Eintritt in den Supervisor) abgelaufen: Fail mit OL_E_STARTUP_TIMEOUT, wenn PluginBootstrap erreicht wurde, andernfalls OL_E_PLUGIN_NOT_LOADED; die Schleife verlassen.

Nach der Schleife: Wurde OMSI vor Running beendet und kein Fehler erfasst, Fail mit OL_E_PROCESS_EXITED_EARLY. Danach, unabhängig davon, ob die Sitzung fehlgeschlagen ist: OMSI terminieren, falls es noch läuft, auf das Beenden warten, das Journal als ProcessExited markieren, zu ProcessExited wechseln, wiederherstellen (Restoring → CleaningRuntime) oder OL_E_RESTORE_FAILED/OL_E_RESTORE_DEFERRED erfassen, das Prozess-Handle, die Übergabe, den Telemetrie-Slot und die Runtime-Mailbox freigeben, die Lease freigeben und zu Completed wechseln, sofern der Zustand nicht Failed ist. Ein Fehler im Supervisor selbst wird als OL_E_PROCESS_SUPERVISION erfasst (Bereinigungsprobleme als OL_E_PROCESS_CLEANUP_FAILED), und derselbe Terminierungs-/Wiederherstellungspfad wird ausgeführt.

Da Failed dauerhaft ist, ist der einzige Nachweis dafür, dass eine fehlgeschlagene Sitzung wiederhergestellt wurde, das Fehlen von OL_E_RESTORE_FAILED/OL_E_RESTORE_DEFERRED in ihren Diagnosen (und das Fehlen von journal.json); Wiederherstellungshinweise (restore.session-artifact-removed, OL_W_RESTORE_FOREIGN_FILE_RETAINED) erscheinen in beiden Fällen.

Telemetrieereignisse#

Das Plugin veröffentlicht JSON-Proben { "name": ..., "data": {...} } im Telemetrie-Slot; der Host erfasst jede neue Probe als RuntimeEvent(Type = name, TimestampUtc = host receipt time, Sequence, Data).

Einschränkungen: Der Slot enthält eine einzige Probe, sodass Ereignisse, die innerhalb einer Host-Abfrage von 100 ms gesendet werden, verloren gehen können (das Plugin unterdrückt Lebenszyklusereignisse für 2 s nach gameplay.entered und veröffentlicht nie ein D3D-Ereignis in dem Tick, in dem gameplay.entered veröffentlicht wird, sodass die Running-Grenze nicht verpasst wird). RuntimeEvents behält die 256 neuesten Ereignisse; ältere werden verworfen. Es ist kein verlustfreies Protokoll. Lesen Sie Ereignisse über GetStatusAsync, session.events auf der Steuerungsebene oder events read|watch in der CLI.

Start-Timeout#

ShutdownTimeoutSeconds wird in der Spezifikation mitgeführt, aber nicht ausgewertet: Es gibt kein Warten auf ein Herunterfahren.

Stopp-Semantik#

Jede Stoppanforderung ist dieselbe kanonische Anforderung: StopAsync(handle) aus der API, CloseAsync auf einer nicht terminalen Sitzung, session.stop auf der lokalen Steuerungsebene (an die ID der aktiven Sitzung gebunden), „End session“ („Sitzung beenden“) im Tray, Ctrl+C oder Schließen der Konsole beim CLI-Eigentümer und das Ende von /observe-seconds.

WaitForAsync-Semantik#

Das Abfrageintervall beträgt 100 ms, sodass beobachtete Übergänge den tatsächlichen um bis zu 100 ms nachlaufen.

Lebenszyklusgarantien des Eigentümers (CLI)#

OwnerSession.RunAsync in tools/OmsiLaunch.Cli/Program.cs ist der Referenz-Eigentümer.

Integratoren, die einen eigenen Eigentümer schreiben, müssen die ersten beiden Garantien nachbilden: jeweils nur ein StartSessionAsync pro Installation und CloseAsync auf jedem Pfad.

Fehlerübersicht#

Jeder Fehlerpfad versucht dennoch Terminierung und Wiederherstellung; ein verbleibendes Journal wird beim nächsten Start oder durch RecoverPendingAsync / /recover per Recovery (Absturzwiederherstellung) verarbeitet (Transaktionen und Recovery).