Cykl życia sesji

Dokumentacja wersji v0.1.0-beta.3Zobacz źródło na GitHubie

Tłumaczenie oryginalnej strony w języku angielskim dla OmsiLaunch 0.1.0-beta3. Wiążąca jest strona angielska: w razie rozbieżności obowiązują strona angielska i kod.

Ta strona opisuje, jak sesja OmsiLaunch przechodzi przez stany SessionState od Created do Completed lub Failed: który komponent ustawia każdy stan, które zdarzenia telemetrii wtyczki wyzwalają przejścia, jak działa limit czasu uruchamiania, co oznacza zatrzymanie (wymuszone zakończenie procesu), co zwraca WaitForAsync, które stany są końcowe, które stany nigdy nie są lub prawie nie są obserwowalne oraz jakie gwarancje daje właściciel w CLI. Wszystkie informacje pochodzą z OmsiLaunchService.StartAsync, SuperviseAsync i ApplyTelemetry (src/OmsiLaunch.Core/OmsiLaunchService.cs), PluginRuntime (src/OmsiLaunch.Plugin/PluginRuntime.cs) oraz OwnerSession (tools/OmsiLaunch.Cli/Program.cs).

Powiązane strony: publiczne API, kody błędów, transakcje i odzyskiwanie, stała wtyczka, sterowanie runtime, lokalna płaszczyzna sterowania, obszar powiadomień Windows, dokumentacja CLI, stan walidacji runtime, katalog .omsilaunch.

Przegląd#

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

Opis SessionState#

Wartości w kolejności deklaracji. Kolumna „Ustawiany przez” wskazuje kod, który wywołuje Move/Fail; kolumna „Obserwowalny” mówi, czy GetStatusAsync/WaitForAsync może go w praktyce zobaczyć.

Stany końcowe: Completed i Failed. Po każdym z nich WaitForAsync zwraca wynik natychmiast, a CloseAsync kończy się bez żądania zatrzymania.

Weryfikacja stwierdzenia „nigdy nie jest ustawiany”: przeszukanie kodu pod kątem SessionState.ValidatingPlatform, SessionState.Planning i SessionState.EnteringGameplay znajduje wyłącznie deklarację enum; SessionState.Snapshotting występuje raz, bezpośrednio przed Move(SessionState.ApplyingConfiguration).

Faza uruchamiania (StartSessionAsync)#

1. Odrzucenie planu niemożliwego do uruchomienia (OL_E_PLAN_NOT_RUNNABLE), ponowne zaplanowanie specyfikacji (ponowne obliczenie hasha Omsi.exe, ponowne rozwiązanie zawartości, ponowne sprawdzenie zestawu plików wtyczki) i ponowne odrzucenie, jeśli plan nie jest już możliwy do uruchomienia. Rejestracja aktywnej sesji (Created).
2. Utworzenie śladu hosta <root>\.omsilaunch\diagnostics\<sessionId>-host.log (starsze pliki z prefiksem sesji poza 50 najnowszymi sesjami są usuwane). Odrzucenie StartupTimeoutSeconds spoza zakresu 1..600 (ArgumentOutOfRangeException; rejestracja sesji jest cofana).
3. AcquiringInstallationLock → dzierżawa. RecoveringPreviousTransaction → odzyskanie oczekującego dziennika (dziennik sprzed wprowadzenia odcisków, który nie może udowodnić własności, jest odraczany, a odzyskiwanie jest ponawiane, gdy nakładki tej sesji już istnieją), walidacja zestawu plików stałej wtyczki, obliczenie hasha pliku wykonywalnego, usunięcie nieaktualnego closecheck, zbudowanie transakcji (nakładki: poprawki options.cfg, zarządzane pliki BMP ekranu startowego, Texture\standard.itx; usunięcia: cele ITX, Texture\standard.ipr, closecheck, gdy nie istnieje).
4. Snapshotting → ApplyingConfiguration → DeployingRuntime → CreatingStartupHandoff → StartingProcess → WaitingForPlugin, po czym uruchamiane jest zadanie nadzorcy i zwracany jest uchwyt.
5. Każdy wyjątek w krokach 3–4 jest przechwytywany: sesja przechodzi w stan Failed z OL_E_START_SESSION (komunikat wewnętrzny), utworzony proces jest kończony i następuje oczekiwanie na jego zakończenie, magazyny są zwalniane, transakcja jest przywracana (OL_E_RESTORE_FAILED w razie błędu) lub, jeśli nie można było potwierdzić zakończenia OMSI, pozostawiana jako oczekująca z OL_E_RESTORE_DEFERRED; dzierżawa jest zwalniana. StartSessionAsync nadal zwraca w tym przypadku uchwyt; należy odczytać GetStatusAsync.

Ponowne planowanie zachowuje SessionId wywołującego, więc identyfikator w uchwycie jest równy plan.SessionId.

Nadzór (SuperviseAsync)#

Nadzorca działa jako zadanie w puli wątków i wykonuje pętlę co 100 ms, dopóki OMSI nie zakończy działania lub nie zostanie zażądane zatrzymanie:

1. Odczytanie najnowszej próbki telemetrii (slot przechowujący najnowszą wartość z numerem sekwencyjnym producenta; rozerwane próbki są pomijane; identyczne kolejne zdarzenia są rozróżniane, ponieważ numer sekwencyjny jest inny). Każda nowa próbka jest dopisywana do RuntimeEvents i mapowana przez ApplyTelemetry.
2. Jeśli sesja jest w stanie Failed, wyjście z pętli.
3. Jeśli sesja nie jest jeszcze w stanie Running, a termin (StartupTimeoutSeconds od wejścia nadzorcy) minął: Fail z OL_E_STARTUP_TIMEOUT, gdy osiągnięto PluginBootstrap, w przeciwnym razie OL_E_PLUGIN_NOT_LOADED; wyjście z pętli.

Po pętli: jeśli OMSI zakończył działanie przed Running i nie zarejestrowano żadnego błędu, następuje Fail z OL_E_PROCESS_EXITED_EARLY. Następnie, niezależnie od tego, czy sesja zakończyła się błędem: zakończenie OMSI, jeśli nadal działa, oczekiwanie na zakończenie, oznaczenie dziennika jako ProcessExited, przejście do ProcessExited, przywrócenie (Restoring → CleaningRuntime) lub zarejestrowanie OL_E_RESTORE_FAILED/OL_E_RESTORE_DEFERRED, zwolnienie uchwytu procesu, handoffu, slotu telemetrii i skrzynki runtime, zwolnienie dzierżawy oraz przejście do Completed, chyba że stan to Failed. Błąd wewnątrz samego nadzorcy jest rejestrowany jako OL_E_PROCESS_SUPERVISION (problemy ze sprzątaniem jako OL_E_PROCESS_CLEANUP_FAILED) i wykonywana jest ta sama ścieżka zakończenia procesu i przywracania.

Ponieważ Failed jest stanem trwałym, jedynym dowodem, że sesja zakończona błędem została przywrócona, jest brak OL_E_RESTORE_FAILED/OL_E_RESTORE_DEFERRED w jej komunikatach diagnostycznych (oraz brak journal.json); uwagi dotyczące przywracania (restore.session-artifact-removed, OL_W_RESTORE_FOREIGN_FILE_RETAINED) pojawiają się w obu przypadkach.

Zdarzenia telemetrii#

Wtyczka publikuje w slocie telemetrii próbki JSON { "name": ..., "data": {...} }; host rejestruje każdą nową próbkę jako RuntimeEvent(Type = name, TimestampUtc = host receipt time, Sequence, Data).

Zastrzeżenia: slot przechowuje jedną próbkę, więc zdarzenia wyemitowane w trakcie jednego 100-milisekundowego odpytania hosta mogą zostać utracone (wtyczka wstrzymuje zdarzenia cyklu życia przez 2 s po gameplay.entered i nigdy nie publikuje zdarzenia D3D w tym samym tyknięciu, w którym publikuje gameplay.entered, więc granica Running nie zostaje przeoczona). RuntimeEvents przechowuje 256 najnowszych zdarzeń; starsze są odrzucane. Nie jest to bezstratny log. Zdarzenia należy odczytywać przez GetStatusAsync, session.events na płaszczyźnie sterowania lub events read|watch w CLI.

Limit czasu uruchamiania#

ShutdownTimeoutSeconds jest przenoszony w specyfikacji, ale nie jest wykorzystywany: nie ma oczekiwania na zamknięcie.

Semantyka zatrzymania#

Każde żądanie zatrzymania jest tym samym kanonicznym żądaniem: StopAsync(handle) z API, CloseAsync na sesji w stanie niekońcowym, session.stop na lokalnej płaszczyźnie sterowania (powiązane z identyfikatorem aktywnej sesji), „End session” w obszarze powiadomień, Ctrl+C lub zamknięcie konsoli we właścicielu w CLI oraz upływ /observe-seconds.

Semantyka WaitForAsync#

Interwał odpytywania wynosi 100 ms, więc obserwowane przejścia są opóźnione względem rzeczywistych o maksymalnie 100 ms.

Gwarancje cyklu życia właściciela (CLI)#

OwnerSession.RunAsync w tools/OmsiLaunch.Cli/Program.cs jest referencyjnym właścicielem.

Integratorzy piszący własnego właściciela muszą odtworzyć dwie pierwsze gwarancje: jedno StartSessionAsync na instalację w danym momencie oraz CloseAsync na każdej ścieżce.

Mapa błędów#

Każda ścieżka błędu nadal podejmuje próbę zakończenia procesu i przywrócenia; dziennik, który pozostanie, jest odzyskiwany przy następnym uruchomieniu lub przez RecoverPendingAsync / /recover (transakcje i odzyskiwanie).