Cycle de vie de la session

Documentation de la version v0.1.0-beta.3Voir la source sur GitHub

Traduction de la page originale en anglais d’OmsiLaunch 0.1.0-beta3. La page anglaise fait foi : en cas de divergence, la page anglaise et le code prévalent.

Cette page décrit comment une session OmsiLaunch parcourt SessionState de Created jusqu'à Completed ou Failed : quel composant définit chaque état, quels événements de télémétrie du plugin déclenchent les transitions, comment fonctionne le timeout de démarrage, ce que signifie l'arrêt (arrêt forcé), ce que renvoie WaitForAsync, quels états sont terminaux, quels états ne sont jamais ou à peine observables, et quelles garanties offre le propriétaire CLI. Tout ce qui suit est tiré de OmsiLaunchService.StartAsync, SuperviseAsync et ApplyTelemetry (src/OmsiLaunch.Core/OmsiLaunchService.cs), de PluginRuntime (src/OmsiLaunch.Plugin/PluginRuntime.cs) et de OwnerSession (tools/OmsiLaunch.Cli/Program.cs).

Pages associées : API publique, codes d'erreur, transactions et récupération, plugin permanent, contrôle runtime, plan de contrôle local, zone de notification Windows, référence CLI, état de la validation à l'exécution, le répertoire .omsilaunch.

Vue d'ensemble#

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

Référence de SessionState#

Valeurs dans l'ordre de déclaration. « Défini par » nomme le code qui appelle Move/Fail ; « Observable » indique si GetStatusAsync/WaitForAsync peut le voir en pratique.

États terminaux : Completed et Failed. Après l'un ou l'autre, WaitForAsync retourne immédiatement et CloseAsync retourne sans demander d'arrêt.

Vérification de « jamais défini » : une recherche dans le code source de SessionState.ValidatingPlatform, SessionState.Planning et SessionState.EnteringGameplay ne trouve que la déclaration de l'enum ; SessionState.Snapshotting apparaît une seule fois, immédiatement suivi de Move(SessionState.ApplyingConfiguration).

Phase de démarrage (StartSessionAsync)#

1. Rejeter un plan non exécutable (OL_E_PLAN_NOT_RUNNABLE), replanifier la spécification (nouveau calcul du hash de Omsi.exe, nouvelle résolution du contenu, nouvelle vérification de la closure du plugin) et rejeter à nouveau si elle n'est plus exécutable. Enregistrer la session active (Created).
2. Créer la trace de l'hôte <root>\.omsilaunch\diagnostics\<sessionId>-host.log (les anciens fichiers préfixés par une session au-delà des 50 sessions les plus récentes sont supprimés). Rejeter StartupTimeoutSeconds en dehors de 1..600 (ArgumentOutOfRangeException ; la session est désenregistrée).
3. AcquiringInstallationLock → bail. RecoveringPreviousTransaction → récupérer un journal en attente (un journal antérieur aux empreintes qui ne peut pas prouver la propriété est différé et retenté une fois que les overlays de cette session existent), valider la closure du plugin permanent, calculer le hash de l'exécutable, supprimer un closecheck obsolète, construire la transaction (overlays : correctifs de options.cfg, BMP gérés de l'écran de démarrage, Texture\standard.itx ; suppressions : cibles ITX, Texture\standard.ipr, closecheck lorsqu'il n'existe pas).
4. Snapshotting → ApplyingConfiguration → DeployingRuntime → CreatingStartupHandoff → StartingProcess → WaitingForPlugin, puis la tâche du superviseur démarre et le handle est renvoyé.
5. Toute exception aux étapes 3–4 est interceptée : la session passe à Failed avec OL_E_START_SESSION (message interne), un processus créé est arrêté et attendu, les stores sont libérés, la transaction est restaurée (OL_E_RESTORE_FAILED en cas d'échec) ou, si la fin d'OMSI n'a pas pu être confirmée, laissée en attente avec OL_E_RESTORE_DEFERRED ; le bail est libéré. StartSessionAsync renvoie quand même le handle dans ce cas ; lisez GetStatusAsync.

La nouvelle planification conserve le SessionId de l'appelant, de sorte que l'identifiant du handle est égal à plan.SessionId.

Supervision (SuperviseAsync)#

Le superviseur s'exécute dans une tâche du pool de threads et boucle toutes les 100 ms jusqu'à ce qu'OMSI se soit terminé ou qu'un arrêt ait été demandé :

1. Lire le dernier échantillon de télémétrie (un slot à dernière valeur avec une séquence de producteur ; les échantillons incohérents sont ignorés ; des événements consécutifs identiques restent distincts car la séquence diffère). Chaque nouvel échantillon est ajouté à RuntimeEvents et mappé par ApplyTelemetry.
2. Si la session est Failed, quitter la boucle.
3. Si la session n'est pas encore Running et que l'échéance (StartupTimeoutSeconds après l'entrée du superviseur) est dépassée : Fail avec OL_E_STARTUP_TIMEOUT lorsque PluginBootstrap a été atteint, sinon OL_E_PLUGIN_NOT_LOADED ; quitter la boucle.

Après la boucle : si OMSI s'est terminé avant Running et qu'aucun échec n'a été enregistré, Fail avec OL_E_PROCESS_EXITED_EARLY. Ensuite, que la session ait échoué ou non : arrêter OMSI s'il est encore actif, attendre sa fin, marquer le journal ProcessExited, passer à ProcessExited, restaurer (Restoring → CleaningRuntime) ou enregistrer OL_E_RESTORE_FAILED/OL_E_RESTORE_DEFERRED, libérer le handle de processus, le handoff, le slot de télémétrie et la boîte aux lettres runtime, libérer le bail, et passer à Completed sauf si l'état est Failed. Une erreur dans le superviseur lui-même est enregistrée comme OL_E_PROCESS_SUPERVISION (les problèmes de nettoyage comme OL_E_PROCESS_CLEANUP_FAILED) et le même chemin d'arrêt/restauration s'exécute.

Comme Failed est persistant, la seule preuve qu'une session en échec a été restaurée est l'absence de OL_E_RESTORE_FAILED/OL_E_RESTORE_DEFERRED dans ses diagnostics (et l'absence de journal.json) ; les notes de restauration (restore.session-artifact-removed, OL_W_RESTORE_FOREIGN_FILE_RETAINED) apparaissent dans les deux cas.

Événements de télémétrie#

Le plugin publie des échantillons JSON { "name": ..., "data": {...} } dans le slot de télémétrie ; l'hôte enregistre chaque nouvel échantillon comme un RuntimeEvent(Type = name, TimestampUtc = host receipt time, Sequence, Data).

Réserves : le slot contient un seul échantillon, de sorte que des événements émis au cours d'un même cycle d'interrogation de 100 ms de l'hôte peuvent être perdus (le plugin supprime les événements de cycle de vie pendant 2 s après gameplay.entered et ne publie jamais d'événement D3D dans le tick qui publie gameplay.entered, afin que la frontière Running ne soit pas manquée). RuntimeEvents conserve les 256 événements les plus récents ; les plus anciens sont abandonnés. Ce n'est pas un journal sans perte. Lisez les événements via GetStatusAsync, session.events sur le plan de contrôle, ou events read|watch dans la CLI.

Timeout de démarrage#

ShutdownTimeoutSeconds est transporté dans la spécification mais n'est pas utilisé : il n'y a pas d'attente d'arrêt.

Sémantique de l'arrêt#

Toute demande d'arrêt est la même demande canonique : StopAsync(handle) depuis l'API, CloseAsync sur une session non terminale, session.stop sur le plan de contrôle local (lié à l'identifiant de la session active), « End session » (Terminer la session) dans la zone de notification, Ctrl+C ou la fermeture de la console dans le propriétaire CLI, et la fin de /observe-seconds.

Sémantique de WaitForAsync#

L'intervalle d'interrogation est de 100 ms ; les transitions observées ont donc jusqu'à 100 ms de retard sur les transitions réelles.

Garanties du cycle de vie du propriétaire (CLI)#

OwnerSession.RunAsync dans tools/OmsiLaunch.Cli/Program.cs est le propriétaire de référence.

Les intégrateurs qui écrivent leur propre propriétaire doivent reproduire les deux premières garanties : un seul StartSessionAsync à la fois par installation, et CloseAsync sur chaque chemin.

Carte des échecs#

Chaque chemin d'échec tente quand même l'arrêt forcé et la restauration ; un journal restant est récupéré au démarrage suivant ou par RecoverPendingAsync / /recover (transactions et récupération).