Ciclo de vida de la sesión

Documentación de la versión v0.1.0-beta.3Ver código fuente en GitHub

Traducción de la página original en inglés de OmsiLaunch 0.1.0-beta3. La página en inglés es la referencia normativa: si hay diferencias, prevalecen la página en inglés y el código.

Esta página describe cómo una sesión de OmsiLaunch avanza por SessionState desde Created hasta Completed o Failed: qué componente establece cada estado, qué eventos de telemetría del plugin impulsan las transiciones, cómo funciona el timeout de arranque, qué significa detener (terminación forzada), qué devuelve WaitForAsync, qué estados son terminales, qué estados nunca o apenas son observables y qué garantías ofrece el propietario de la CLI. Todo lo que aparece aquí se toma de OmsiLaunchService.StartAsync, SuperviseAsync y ApplyTelemetry (src/OmsiLaunch.Core/OmsiLaunchService.cs), PluginRuntime (src/OmsiLaunch.Plugin/PluginRuntime.cs) y OwnerSession (tools/OmsiLaunch.Cli/Program.cs).

Páginas relacionadas: API pública, códigos de error, transacciones y recuperación, plugin permanente, control de runtime, plano de control local, bandeja de Windows, referencia de la CLI, estado de la validación en runtime, el directorio .omsilaunch.

Descripción general#

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

Referencia de SessionState#

Valores en orden de declaración. "Establecido por" nombra el código que llama a Move/Fail; "Observable" indica si GetStatusAsync/WaitForAsync pueden verlo en la práctica.

Estados terminales: Completed y Failed. Después de cualquiera de ellos, WaitForAsync retorna de inmediato y CloseAsync retorna sin solicitar una detención.

Verificación de "nunca establecido": una búsqueda en el código base de SessionState.ValidatingPlatform, SessionState.Planning y SessionState.EnteringGameplay encuentra solo la declaración del enum; SessionState.Snapshotting aparece una vez, seguido inmediatamente por Move(SessionState.ApplyingConfiguration).

Fase de inicio (StartSessionAsync)#

1. Rechazar un plan no ejecutable (OL_E_PLAN_NOT_RUNNABLE), volver a planificar la especificación (recalculando el hash de Omsi.exe, volviendo a resolver el contenido y volviendo a comprobar el conjunto de archivos del plugin) y rechazarla de nuevo si ya no es ejecutable. Registrar la sesión activa (Created).
2. Crear la traza del host <root>\.omsilaunch\diagnostics\<sessionId>-host.log (los archivos más antiguos con prefijo de sesión que superan las 50 sesiones más recientes se eliminan). Rechazar StartupTimeoutSeconds fuera de 1..600 (ArgumentOutOfRangeException; se anula el registro de la sesión).
3. AcquiringInstallationLock → lease. RecoveringPreviousTransaction → recuperar un journal pendiente (un journal anterior a las huellas de propiedad que no puede probar la propiedad se posterga y se reintenta cuando ya existen los overlays de esta sesión), validar el conjunto de archivos del plugin permanente, calcular el hash del archivo ejecutable, eliminar un closecheck obsoleto, construir la transacción (overlays: parches de options.cfg, BMP de splash administrados, Texture\standard.itx; eliminaciones: destinos de ITX, Texture\standard.ipr, closecheck cuando no existe).
4. Snapshotting → ApplyingConfiguration → DeployingRuntime → CreatingStartupHandoff → StartingProcess → WaitingForPlugin; luego se inicia la tarea del supervisor y se devuelve el handle.
5. Cualquier excepción en los pasos 3–4 se captura: la sesión queda Failed con OL_E_START_SESSION (mensaje interno), un proceso ya creado se termina y se espera su salida, los almacenes se liberan, la transacción se restaura (OL_E_RESTORE_FAILED si falla) o, si no se pudo confirmar la salida de OMSI, queda pendiente con OL_E_RESTORE_DEFERRED; el lease se libera. En este caso StartSessionAsync igualmente devuelve el handle; consulte GetStatusAsync.

La nueva planificación conserva el SessionId del llamador, por lo que el id del handle es igual a plan.SessionId.

Supervisión (SuperviseAsync)#

El supervisor se ejecuta en una tarea del thread pool y repite un ciclo cada 100 ms hasta que OMSI termina o se solicita una detención:

1. Leer la muestra de telemetría más reciente (un slot de último valor con una secuencia del productor; las muestras inconsistentes se descartan; eventos consecutivos idénticos se distinguen porque la secuencia difiere). Cada muestra nueva se agrega a RuntimeEvents y se mapea mediante ApplyTelemetry.
2. Si la sesión está Failed, salir del ciclo.
3. Si la sesión todavía no está en Running y el plazo (StartupTimeoutSeconds después de la entrada del supervisor) ya venció: Fail con OL_E_STARTUP_TIMEOUT cuando se alcanzó PluginBootstrap; de lo contrario, OL_E_PLUGIN_NOT_LOADED; salir del ciclo.

Después del ciclo: si OMSI terminó antes de Running y no se registró ninguna falla, Fail con OL_E_PROCESS_EXITED_EARLY. Luego, haya fallado o no la sesión: terminar OMSI si sigue vivo, esperar su salida, marcar el journal como ProcessExited, pasar a ProcessExited, restaurar (Restoring → CleaningRuntime) o registrar OL_E_RESTORE_FAILED/OL_E_RESTORE_DEFERRED, liberar el handle del proceso, el handoff, el slot de telemetría y el buzón de runtime, liberar el lease y pasar a Completed salvo que el estado sea Failed. Una falla dentro del propio supervisor se registra como OL_E_PROCESS_SUPERVISION (los problemas de limpieza, como OL_E_PROCESS_CLEANUP_FAILED) y se ejecuta la misma ruta de terminación y restauración.

Como Failed es persistente, la única evidencia de que una sesión fallida se restauró es la ausencia de OL_E_RESTORE_FAILED/OL_E_RESTORE_DEFERRED en sus diagnósticos (y la ausencia de journal.json); las notas de restauración (restore.session-artifact-removed, OL_W_RESTORE_FOREIGN_FILE_RETAINED) aparecen en ambos casos.

Eventos de telemetría#

El plugin publica muestras JSON { "name": ..., "data": {...} } en el slot de telemetría; el host registra cada muestra nueva como un RuntimeEvent(Type = name, TimestampUtc = host receipt time, Sequence, Data).

Advertencias: el slot contiene una sola muestra, por lo que los eventos emitidos dentro de un mismo sondeo de 100 ms del host pueden perderse (el plugin suprime los eventos de ciclo de vida durante 2 s después de gameplay.entered y nunca publica un evento D3D en el tick que publica gameplay.entered, de modo que no se pierde el límite de Running). RuntimeEvents conserva los 256 eventos más recientes; los más antiguos se descartan. No es un registro sin pérdidas. Lea los eventos mediante GetStatusAsync, session.events en el plano de control, o events read|watch en la CLI.

Timeout de arranque#

ShutdownTimeoutSeconds se incluye en la especificación pero no se consume: no hay espera de apagado.

Semántica de detención#

Toda solicitud de detención es la misma solicitud canónica: StopAsync(handle) desde la API, CloseAsync sobre una sesión no terminal, session.stop en el plano de control local (vinculado al id de la sesión activa), "End session" (finalizar sesión) en la bandeja, Ctrl+C o el cierre de la consola en el propietario de la CLI, y el fin de /observe-seconds.

Semántica de WaitForAsync#

El intervalo de sondeo es de 100 ms, por lo que las transiciones observadas se retrasan hasta 100 ms respecto de las reales.

Garantías del ciclo de vida del propietario (CLI)#

OwnerSession.RunAsync en tools/OmsiLaunch.Cli/Program.cs es el propietario de referencia.

Los integradores que escriban su propio propietario deben reproducir las dos primeras garantías: un solo StartSessionAsync por instalación a la vez y CloseAsync en toda ruta.

Mapa de fallas#

Toda ruta de falla igualmente intenta la terminación y la restauración; un journal que quede se recupera en el siguiente inicio o mediante RecoverPendingAsync / /recover (transacciones y recuperación).