Ciclo di vita della sessione

Documentazione della versione v0.1.0-beta.3Vedi il sorgente su GitHub

Traduzione della pagina originale in inglese di OmsiLaunch 0.1.0-beta3. La pagina inglese è normativa: in caso di differenze prevalgono la pagina inglese e il codice.

Questa pagina descrive come una sessione OmsiLaunch attraversa SessionState da Created a Completed o Failed: quale componente imposta ciascuno stato, quali eventi di telemetria del plugin guidano le transizioni, come funziona il timeout di avvio, che cosa significa l'arresto (terminazione forzata), che cosa restituisce WaitForAsync, quali stati sono terminali, quali stati non sono mai o quasi mai osservabili e quali garanzie offre l'owner della CLI. Tutto il contenuto è tratto da OmsiLaunchService.StartAsync, SuperviseAsync e ApplyTelemetry (src/OmsiLaunch.Core/OmsiLaunchService.cs), PluginRuntime (src/OmsiLaunch.Plugin/PluginRuntime.cs) e OwnerSession (tools/OmsiLaunch.Cli/Program.cs).

Pagine correlate: API pubblica, codici di errore, transazioni e recupero, plugin permanente, controllo runtime, piano di controllo locale, area di notifica di Windows, riferimento CLI, stato della validazione a runtime, la directory .omsilaunch.

Panoramica#

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

Riferimento di SessionState#

Valori nell'ordine di dichiarazione. «Impostato da» indica il codice che chiama Move/Fail; «Osservabile» indica se GetStatusAsync/WaitForAsync possono vederlo in pratica.

Stati terminali: Completed e Failed. Dopo uno qualsiasi dei due, WaitForAsync restituisce immediatamente e CloseAsync restituisce senza richiedere un arresto.

Verifica di «mai impostato»: una ricerca nel codice sorgente di SessionState.ValidatingPlatform, SessionState.Planning e SessionState.EnteringGameplay trova solo la dichiarazione dell'enum; SessionState.Snapshotting compare una sola volta, seguito immediatamente da Move(SessionState.ApplyingConfiguration).

Fase di avvio (StartSessionAsync)#

1. Rifiutare un piano non eseguibile (OL_E_PLAN_NOT_RUNNABLE), ripianificare la specifica (ricalcolando l'hash di Omsi.exe, risolvendo di nuovo i contenuti, ricontrollando la chiusura del plugin) e rifiutarla di nuovo se non è più eseguibile. Registrare la sessione attiva (Created).
2. Creare la traccia dell'host <root>\.omsilaunch\diagnostics\<sessionId>-host.log (i file più vecchi con prefisso di sessione oltre le 50 sessioni più recenti vengono eliminati). Rifiutare StartupTimeoutSeconds al di fuori di 1..600 (ArgumentOutOfRangeException; la registrazione della sessione viene annullata).
3. AcquiringInstallationLock → lease. RecoveringPreviousTransaction → recuperare un journal in sospeso (un journal precedente all'introduzione dell'impronta, che non può dimostrare la proprietà, viene rinviato e ritentato una volta che gli overlay di questa sessione esistono), validare la chiusura del plugin permanente, calcolare l'hash dell'eseguibile, rimuovere un closecheck obsoleto, costruire la transazione (overlay: patch di options.cfg, BMP della splash screen gestita, Texture\standard.itx; eliminazioni: destinazioni ITX, Texture\standard.ipr, closecheck quando non esiste).
4. Snapshotting → ApplyingConfiguration → DeployingRuntime → CreatingStartupHandoff → StartingProcess → WaitingForPlugin, quindi il task del supervisore si avvia e l'handle viene restituito.
5. Qualsiasi eccezione nei passaggi 3–4 viene intercettata: la sessione passa a Failed con OL_E_START_SESSION (messaggio interno), un processo eventualmente creato viene terminato e atteso, gli store vengono rilasciati, la transazione viene ripristinata (OL_E_RESTORE_FAILED in caso di errore) oppure, se non è stato possibile confermare l'uscita di OMSI, lasciata in sospeso con OL_E_RESTORE_DEFERRED; il lease viene rilasciato. Anche in questo caso StartSessionAsync restituisce l'handle; leggere GetStatusAsync.

La ripianificazione mantiene il SessionId del chiamante, quindi l'id nell'handle è uguale a plan.SessionId.

Supervisione (SuperviseAsync)#

Il supervisore viene eseguito su un task del thread pool ed esegue un ciclo ogni 100 ms finché OMSI non è terminato o non è stato richiesto un arresto:

1. Leggere il campione di telemetria più recente (uno slot a valore più recente con una sequenza del produttore; i campioni incoerenti vengono scartati; eventi consecutivi identici sono distinti perché la sequenza differisce). Ogni nuovo campione viene aggiunto a RuntimeEvents e mappato da ApplyTelemetry.
2. Se la sessione è Failed, uscire dal ciclo.
3. Se la sessione non è ancora Running e la scadenza (StartupTimeoutSeconds dopo l'ingresso nel supervisore) è trascorsa: Fail con OL_E_STARTUP_TIMEOUT se è stato raggiunto PluginBootstrap, altrimenti OL_E_PLUGIN_NOT_LOADED; uscire dal ciclo.

Dopo il ciclo: se OMSI è terminato prima di Running e non è stato registrato alcun errore, Fail con OL_E_PROCESS_EXITED_EARLY. Quindi, indipendentemente dal fatto che la sessione sia fallita o no: terminare OMSI se è ancora attivo, attenderne l'uscita, marcare il journal come ProcessExited, passare a ProcessExited, ripristinare (Restoring → CleaningRuntime) oppure registrare OL_E_RESTORE_FAILED/OL_E_RESTORE_DEFERRED, rilasciare l'handle del processo, l'handoff, lo slot di telemetria e la mailbox runtime, rilasciare il lease e passare a Completed a meno che lo stato non sia Failed. Un guasto all'interno del supervisore stesso viene registrato come OL_E_PROCESS_SUPERVISION (i problemi di pulizia come OL_E_PROCESS_CLEANUP_FAILED) e viene eseguito lo stesso percorso di terminazione/ripristino.

Poiché Failed è persistente, l'unica evidenza che una sessione fallita è stata ripristinata è l'assenza di OL_E_RESTORE_FAILED/OL_E_RESTORE_DEFERRED nella sua diagnostica (e l'assenza di journal.json); le note di ripristino (restore.session-artifact-removed, OL_W_RESTORE_FOREIGN_FILE_RETAINED) compaiono in entrambi i casi.

Eventi di telemetria#

Il plugin pubblica campioni JSON { "name": ..., "data": {...} } nello slot di telemetria; l'host registra ogni nuovo campione come RuntimeEvent(Type = name, TimestampUtc = host receipt time, Sequence, Data).

Avvertenze: lo slot contiene un solo campione, quindi gli eventi emessi durante un unico polling dell'host di 100 ms possono andare persi (il plugin sopprime gli eventi del ciclo di vita per 2 s dopo gameplay.entered e non pubblica mai un evento D3D nello stesso tick in cui pubblica gameplay.entered, quindi il confine Running non viene perso). RuntimeEvents conserva i 256 eventi più recenti; quelli più vecchi vengono scartati. Non è un log senza perdite. Leggere gli eventi tramite GetStatusAsync, session.events sul piano di controllo oppure events read|watch nella CLI.

Timeout di avvio#

ShutdownTimeoutSeconds è presente nella specifica ma non viene utilizzato: non esiste alcuna attesa di chiusura.

Semantica dell'arresto#

Ogni richiesta di arresto è la stessa richiesta canonica: StopAsync(handle) dall'API, CloseAsync su una sessione non terminale, session.stop sul piano di controllo locale (vincolato all'id della sessione attiva), «End session» nell'area di notifica, Ctrl+C o la chiusura della console nell'owner della CLI e la fine di /observe-seconds.

Semantica di WaitForAsync#

L'intervallo di polling è di 100 ms, quindi le transizioni osservate sono in ritardo rispetto a quelle reali fino a 100 ms.

Garanzie del ciclo di vita dell'owner (CLI)#

OwnerSession.RunAsync in tools/OmsiLaunch.Cli/Program.cs è l'owner di riferimento.

Gli integratori che scrivono un proprio owner devono riprodurre le prime due garanzie: un solo StartSessionAsync per installazione alla volta e CloseAsync su ogni percorso.

Mappa degli errori#

Ogni percorso di errore tenta comunque la terminazione e il ripristino; un journal che rimane viene recuperato all'avvio successivo oppure da RecoverPendingAsync / /recover (transazioni e recupero).