セッションのライフサイクル

ドキュメントのバージョン v0.1.0-beta.3GitHub でソースを見る

このページは OmsiLaunch 0.1.0-beta3 の英語版の原文ページの翻訳です。規範となるのは英語版です。内容が異なる場合は、英語版のページとコードが優先されます。

このページでは、OmsiLaunch のセッションが SessionState 上で Created から Completed または Failed へどのように遷移するかを説明します。具体的には、各状態をどのコンポーネントが設定するか、どのプラグインテレメトリイベントが遷移を駆動するか、起動タイムアウトの仕組み、停止が何を意味するか（強制終了）、WaitForAsync が何を返すか、どの状態が終端状態か、どの状態がまったく（またはほとんど）観測できないか、そして CLI オーナーがどのような保証を提供するかを扱います。ここに記載する内容はすべて OmsiLaunchService.StartAsync、SuperviseAsync および ApplyTelemetry（src/OmsiLaunch.Core/OmsiLaunchService.cs）、PluginRuntime（src/OmsiLaunch.Plugin/PluginRuntime.cs）、OwnerSession（tools/OmsiLaunch.Cli/Program.cs）に基づいています。

関連ページ: 公開 API、エラーコード、トランザクションとリカバリ、常駐プラグイン、ランタイム制御、ローカルコントロールプレーン、Windows トレイ、CLI リファレンス、ランタイム検証ステータス、.omsilaunch ディレクトリ。

概要#

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 リファレンス#

値は宣言順に並んでいます。「設定元」は Move/Fail を呼び出すコードを示し、「観測可能」は GetStatusAsync/WaitForAsync から実際にその状態が見えるかどうかを示します。

終端状態は Completed と Failed です。いずれかに達した後は、WaitForAsync は即座に戻り、CloseAsync は停止を要求せずに戻ります。

「設定されることはない」ことの確認: コードベースで SessionState.ValidatingPlatform、SessionState.Planning、SessionState.EnteringGameplay を検索しても、見つかるのは列挙型の宣言だけです。SessionState.Snapshotting は 1 回だけ出現し、その直後に Move(SessionState.ApplyingConfiguration) が続きます。

開始フェーズ（StartSessionAsync）#

1. 実行不可のプランを拒否し（OL_E_PLAN_NOT_RUNNABLE）、スペックを再プランニングし（Omsi.exe のハッシュを再計算し、コンテンツを再解決し、プラグインのクロージャーを再チェックします）、実行可能でなくなっていれば再度拒否します。ライブセッションを登録します（Created）。
2. ホストトレース <root>\.omsilaunch\diagnostics\<sessionId>-host.log を作成します（最新 50 セッションより古い、セッション ID を接頭辞とするファイルは削除されます）。1..600 の範囲外の StartupTimeoutSeconds を拒否します（ArgumentOutOfRangeException。セッションの登録は解除されます）。
3. AcquiringInstallationLock → リースを取得します。RecoveringPreviousTransaction → 保留中のジャーナルをリカバリし（所有権を証明できないフィンガープリント導入前のジャーナルは後回しにされ、このセッションのオーバーレイが作成された時点で再試行されます）、常駐プラグインのクロージャーを検証し、実行ファイルのハッシュを計算し、古い closecheck を削除し、トランザクションを構築します（オーバーレイ: options.cfg のパッチ、管理対象のスプラッシュ BMP、Texture\standard.itx。削除対象: ITX のターゲット、Texture\standard.ipr、存在しない場合の closecheck）。
4. Snapshotting → ApplyingConfiguration → DeployingRuntime → CreatingStartupHandoff → StartingProcess → WaitingForPlugin と進み、その後スーパーバイザータスクが開始され、ハンドルが返されます。
5. 手順 3–4 で発生した例外はすべて捕捉されます。セッションは OL_E_START_SESSION（内部メッセージ付き）で Failed となり、作成済みのプロセスは強制終了されてその終了が待機され、ストアは破棄され、トランザクションは復元されます（失敗時は OL_E_RESTORE_FAILED）。OMSI の終了を確認できなかった場合は、OL_E_RESTORE_DEFERRED とともに保留のまま残されます。リースは解放されます。この場合も StartSessionAsync はハンドルを返すため、GetStatusAsync を参照してください。

再プランニングでは呼び出し元の SessionId が維持されるため、ハンドル内の ID は plan.SessionId と一致します。

監視（SuperviseAsync）#

スーパーバイザーはスレッドプールのタスク上で動作し、OMSI が終了するか停止が要求されるまで 100 ms ごとにループします。

1. 最新のテレメトリサンプルを読み取ります（プロデューサーのシーケンス番号を持つ最新値スロットです。書き込み途中で読み取られたサンプルはスキップされます。シーケンス番号が異なるため、同一のイベントが連続しても別々のイベントとして扱われます）。新しいサンプルはすべて RuntimeEvents に追加され、ApplyTelemetry によってマッピングされます。
2. セッションが Failed であれば、ループを抜けます。
3. セッションがまだ Running ではなく、期限（スーパーバイザー開始から StartupTimeoutSeconds 後）を過ぎている場合: PluginBootstrap に到達していれば OL_E_STARTUP_TIMEOUT、そうでなければ OL_E_PLUGIN_NOT_LOADED で Fail し、ループを抜けます。

ループ終了後: Running より前に OMSI が終了し、失敗が記録されていなかった場合は、OL_E_PROCESS_EXITED_EARLY で Fail します。その後、セッションが失敗したかどうかにかかわらず、OMSI がまだ生存していれば強制終了し、終了を待機し、ジャーナルを ProcessExited とし、ProcessExited に遷移し、復元を行う（Restoring → CleaningRuntime）か OL_E_RESTORE_FAILED/OL_E_RESTORE_DEFERRED を記録し、プロセスハンドル、ハンドオフ、テレメトリスロット、ランタイムメールボックスを破棄し、リースを解放し、状態が Failed でなければ Completed に遷移します。スーパーバイザー自体の内部で障害が発生した場合は OL_E_PROCESS_SUPERVISION（クリーンアップの問題は OL_E_PROCESS_CLEANUP_FAILED）として記録され、同じ終了・復元の経路が実行されます。

Failed は固定されるため、失敗したセッションが復元されたことを示す唯一の根拠は、その診断に OL_E_RESTORE_FAILED/OL_E_RESTORE_DEFERRED が存在しないこと（および journal.json が存在しないこと）です。復元に関する注記（restore.session-artifact-removed、OL_W_RESTORE_FOREIGN_FILE_RETAINED）はどちらの場合にも表示されます。

テレメトリイベント#

プラグインは JSON の { "name": ..., "data": {...} } サンプルをテレメトリスロットに公開します。ホストは新しいサンプルをそれぞれ RuntimeEvent(Type = name, TimestampUtc = host receipt time, Sequence, Data) として記録します。

注意事項: スロットは 1 つのサンプルしか保持しないため、ホストの 1 回の 100 ms ポーリング内に発行された複数のイベントは失われる可能性があります（プラグインは gameplay.entered の後 2 s の間ライフサイクルイベントを抑制し、gameplay.entered を公開したティックでは D3D イベントを決して公開しないため、Running の境界が見落とされることはありません）。RuntimeEvents は最新 256 件のイベントを保持し、それより古いものは破棄されます。これは欠落のないログではありません。イベントは GetStatusAsync、コントロールプレーンの session.events、または CLI の events read|watch で読み取ってください。

起動タイムアウト#

ShutdownTimeoutSeconds はスペックに含まれていますが、使用されません。シャットダウンの待機は存在しません。

停止のセマンティクス#

停止要求はすべて同一の正規の要求です。API からの StopAsync(handle)、終端状態でないセッションに対する CloseAsync、ローカルコントロールプレーンの session.stop（アクティブなセッション ID に紐付く）、トレイの "End session"、CLI オーナーでの Ctrl+C またはコンソールのクローズ、そして /observe-seconds の終了がこれに当たります。

WaitForAsync のセマンティクス#

ポーリング間隔は 100 ms であるため、観測される遷移は実際の遷移より最大 100 ms 遅れます。

オーナーのライフサイクル保証（CLI）#

tools/OmsiLaunch.Cli/Program.cs の OwnerSession.RunAsync がリファレンスとなるオーナー実装です。

独自のオーナーを実装するインテグレーターは、最初の 2 つの保証を再現する必要があります。すなわち、インストール環境ごとに同時に 1 つの StartSessionAsync のみとすること、そしてすべての経路で CloseAsync を呼び出すことです。

失敗の対応表#

どの失敗経路でも終了処理と復元は試行されます。残ったジャーナルは、次回の開始時、または RecoverPendingAsync / /recover によってリカバリされます（トランザクションとリカバリ）。