Ciclo de vida de la sesión

Documentación de la versión v0.1.0-beta.3Ver 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 difieren, prevalecen la página en inglés y el código.

Esta página describe cómo avanza una sesión de OmsiLaunch 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 no son observables nunca o casi nunca, y qué garantías ofrece el propietario de la CLI. Todo lo que aquí figura procede 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.

Visió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 el 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. Tras cualquiera de ellos, WaitForAsync retorna inmediatamente y CloseAsync retorna sin solicitar una detención.

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

Fase de inicio (StartSessionAsync)#

1. Se rechaza un plan no ejecutable (OL_E_PLAN_NOT_RUNNABLE), se vuelve a planificar la especificación (recalculando el hash de Omsi.exe, resolviendo de nuevo el contenido y volviendo a comprobar el conjunto de archivos del plugin) y se rechaza otra vez si ya no es ejecutable. Se registra la sesión activa (Created).
2. Se crea la traza del host <root>\.omsilaunch\diagnostics\<sessionId>-host.log (los archivos antiguos con prefijo de sesión que exceden las 50 sesiones más recientes se eliminan). Se rechaza un StartupTimeoutSeconds fuera de 1..600 (ArgumentOutOfRangeException; la sesión se da de baja del registro).
3. AcquiringInstallationLock → lease. RecoveringPreviousTransaction → se recupera un diario pendiente (un diario anterior a las huellas que no puede demostrar la propiedad se aplaza y se reintenta una vez que existen los overlays de esta sesión), se valida el conjunto de archivos del plugin permanente, se calcula el hash del ejecutable, se elimina un closecheck obsoleto y se construye la transacción (overlays: parches de options.cfg, BMP del splash gestionado, Texture\standard.itx; eliminaciones: destinos ITX, Texture\standard.ipr, closecheck cuando no existe).
4. Snapshotting → ApplyingConfiguration → DeployingRuntime → CreatingStartupHandoff → StartingProcess → WaitingForPlugin; después 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 pasa a Failed con OL_E_START_SESSION (mensaje interno), un proceso ya creado se termina y se espera su salida, se liberan los almacenes, se restaura la transacción (OL_E_RESTORE_FAILED si falla) o, si no se pudo confirmar la salida de OMSI, se deja pendiente con OL_E_RESTORE_DEFERRED; se libera el lease. En este caso StartSessionAsync sigue devolviendo el handle; consulta 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 grupo de threads y repite un bucle cada 100 ms hasta que OMSI ha terminado o se ha solicitado una detención:

1. Se lee la última muestra de telemetría (un slot de último valor con una secuencia del productor; las muestras incoherentes se omiten; los eventos consecutivos idénticos son distintos porque la secuencia difiere). Cada muestra nueva se añade a RuntimeEvents y se mapea mediante ApplyTelemetry.
2. Si la sesión está en Failed, se sale del bucle.
3. Si la sesión todavía no está en Running y ha vencido el plazo (StartupTimeoutSeconds desde la entrada en el supervisor): Fail con OL_E_STARTUP_TIMEOUT si se llegó a PluginBootstrap; en caso contrario, OL_E_PLUGIN_NOT_LOADED; se sale del bucle.

Después del bucle: si OMSI terminó antes de Running y no se registró ningún fallo, Fail con OL_E_PROCESS_EXITED_EARLY. A continuación, haya fallado o no la sesión: se termina OMSI si sigue vivo, se espera su salida, se marca el diario como ProcessExited, se pasa a ProcessExited, se restaura (Restoring → CleaningRuntime) o se registra OL_E_RESTORE_FAILED/OL_E_RESTORE_DEFERRED, se liberan el handle del proceso, el handoff, el slot de telemetría y el buzón de runtime, se libera el lease y se pasa a Completed, salvo que el estado sea Failed. Un fallo 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 tras 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. Lee 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 utiliza: no hay espera de cierre.

Semántica de la 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 la sesión) en la bandeja, Ctrl+C o el cierre de la consola en el propietario de la CLI, y el final de /observe-seconds.

Semántica de WaitForAsync#

El intervalo de sondeo es de 100 ms, por lo que las transiciones observadas van hasta 100 ms por detrás 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 único StartSessionAsync por instalación a la vez, y CloseAsync en todas las rutas.

Mapa de fallos#

Toda ruta de fallo sigue intentando la terminación y la restauración; un diario que permanezca se recupera en el siguiente inicio o mediante RecoverPendingAsync / /recover (transacciones y recuperación).