Ciclo de vida da sessão

Documentação da versão v0.1.0-beta.3Ver fonte no GitHub

Tradução da página original em inglês do OmsiLaunch 0.1.0-beta3. A página em inglês é a referência normativa: se as duas divergirem, valem a página em inglês e o código.

Esta página descreve como uma sessão do OmsiLaunch percorre SessionState de Created até Completed ou Failed: qual componente define cada estado, quais eventos de telemetria do plugin conduzem as transições, como funciona o timeout de inicialização, o que significa a parada (encerramento forçado), o que WaitForAsync retorna, quais estados são terminais, quais estados nunca ou quase nunca são observáveis e quais garantias o proprietário da CLI oferece. Tudo aqui foi extraído de OmsiLaunchService.StartAsync, SuperviseAsync e ApplyTelemetry (src/OmsiLaunch.Core/OmsiLaunchService.cs), PluginRuntime (src/OmsiLaunch.Plugin/PluginRuntime.cs) e OwnerSession (tools/OmsiLaunch.Cli/Program.cs).

Páginas relacionadas: API pública, códigos de erro, transações e recuperação, plugin permanente, controle de runtime, plano de controle local, bandeja do Windows, referência da CLI, status da validação em runtime, o diretório .omsilaunch.

Visão geral#

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

Referência de SessionState#

Valores na ordem de declaração. "Definido por" indica o código que chama Move/Fail; "Observável" diz se GetStatusAsync/WaitForAsync conseguem vê-lo na prática.

Estados terminais: Completed e Failed. Depois de qualquer um deles, WaitForAsync retorna imediatamente e CloseAsync retorna sem solicitar uma parada.

Verificação de "nunca definido": uma busca no código-fonte por SessionState.ValidatingPlatform, SessionState.Planning e SessionState.EnteringGameplay encontra apenas a declaração do enum; SessionState.Snapshotting aparece uma vez, imediatamente seguido de Move(SessionState.ApplyingConfiguration).

Fase de inicialização (StartSessionAsync)#

1. Rejeitar um plano não apto para execução (OL_E_PLAN_NOT_RUNNABLE), replanejar a especificação (recalculando o hash do Omsi.exe, resolvendo o conteúdo novamente, verificando de novo o conjunto de arquivos do plugin) e rejeitar novamente se ele não estiver mais apto para execução. Registrar a sessão ativa (Created).
2. Criar o trace do host <root>\.omsilaunch\diagnostics\<sessionId>-host.log (arquivos mais antigos com prefixo de sessão além das 50 sessões mais recentes são eliminados). Rejeitar StartupTimeoutSeconds fora de 1..600 (ArgumentOutOfRangeException; o registro da sessão é desfeito).
3. AcquiringInstallationLock → lease. RecoveringPreviousTransaction → recuperar um journal pendente (um journal anterior aos fingerprints que não consegue provar a propriedade é adiado e tentado de novo assim que os overlays desta sessão existirem), validar o conjunto de arquivos do plugin permanente, calcular o hash do executável, remover um closecheck obsoleto, montar a transação (overlays: patches de options.cfg, BMPs de splash gerenciado, Texture\standard.itx; exclusões: alvos de ITX, Texture\standard.ipr, closecheck quando ele não existe).
4. Snapshotting → ApplyingConfiguration → DeployingRuntime → CreatingStartupHandoff → StartingProcess → WaitingForPlugin; em seguida a tarefa do supervisor é iniciada e o handle é retornado.
5. Qualquer exceção nas etapas 3–4 é capturada: a sessão fica Failed com OL_E_START_SESSION (mensagem interna), um processo já criado é encerrado e aguardado, os stores são descartados, a transação é restaurada (OL_E_RESTORE_FAILED em caso de falha) ou, se não foi possível confirmar a saída do OMSI, mantida pendente com OL_E_RESTORE_DEFERRED; o lease é liberado. StartSessionAsync ainda retorna o handle nesse caso; consulte GetStatusAsync.

O replanejamento mantém o SessionId do chamador, portanto o id no handle é igual a plan.SessionId.

Supervisão (SuperviseAsync)#

O supervisor é executado em uma tarefa do thread pool e repete o ciclo a cada 100 ms até o OMSI terminar ou uma parada ser solicitada:

1. Ler a amostra de telemetria mais recente (um slot de último valor com uma sequência do produtor; amostras corrompidas durante a cópia são ignoradas; eventos consecutivos idênticos são distintos porque a sequência difere). Cada nova amostra é acrescentada a RuntimeEvents e mapeada por ApplyTelemetry.
2. Se a sessão estiver Failed, sair do ciclo.
3. Se a sessão ainda não estiver Running e o prazo (StartupTimeoutSeconds após a entrada do supervisor) tiver passado: Fail com OL_E_STARTUP_TIMEOUT quando PluginBootstrap foi alcançado, caso contrário OL_E_PLUGIN_NOT_LOADED; sair do ciclo.

Após o ciclo: se o OMSI terminou antes de Running e nenhuma falha foi registrada, Fail com OL_E_PROCESS_EXITED_EARLY. Então, independentemente de a sessão ter falhado ou não: encerrar o OMSI se ele ainda estiver ativo, aguardar a saída, marcar o journal como ProcessExited, passar para ProcessExited, restaurar (Restoring → CleaningRuntime) ou registrar OL_E_RESTORE_FAILED/OL_E_RESTORE_DEFERRED, descartar o handle do processo, o handoff, o slot de telemetria e o mailbox de runtime, liberar o lease e passar para Completed, a menos que o estado seja Failed. Uma falha dentro do próprio supervisor é registrada como OL_E_PROCESS_SUPERVISION (problemas de limpeza como OL_E_PROCESS_CLEANUP_FAILED) e o mesmo caminho de encerramento/restauração é executado.

Como Failed é persistente, a única evidência de que uma sessão com falha foi restaurada é a ausência de OL_E_RESTORE_FAILED/OL_E_RESTORE_DEFERRED em seus diagnósticos (e a ausência de journal.json); as notas de restauração (restore.session-artifact-removed, OL_W_RESTORE_FOREIGN_FILE_RETAINED) aparecem em ambos os casos.

Eventos de telemetria#

O plugin publica amostras JSON { "name": ..., "data": {...} } no slot de telemetria; o host registra cada nova amostra como um RuntimeEvent(Type = name, TimestampUtc = host receipt time, Sequence, Data).

Ressalvas: o slot guarda uma única amostra, portanto eventos emitidos dentro de uma mesma consulta de 100 ms do host podem ser perdidos (o plugin suprime eventos de ciclo de vida por 2 s após gameplay.entered e nunca publica um evento D3D no mesmo tick que publica gameplay.entered, de modo que a fronteira de Running não é perdida). RuntimeEvents mantém os 256 eventos mais recentes; os mais antigos são descartados. Não é um log sem perdas. Leia os eventos por meio de GetStatusAsync, session.events no plano de controle ou events read|watch na CLI.

Timeout de inicialização#

ShutdownTimeoutSeconds é transportado na especificação, mas não é consumido: não há espera de desligamento.

Semântica de parada#

Toda solicitação de parada é a mesma solicitação canônica: StopAsync(handle) pela API, CloseAsync em uma sessão não terminal, session.stop no plano de controle local (vinculado ao id da sessão ativa), "End session" (encerrar sessão) na bandeja, Ctrl+C ou fechamento do console no proprietário da CLI, e o fim de /observe-seconds.

Semântica de WaitForAsync#

O intervalo de consulta é de 100 ms, portanto as transições observadas atrasam em até 100 ms em relação às reais.

Garantias do ciclo de vida do proprietário (CLI)#

OwnerSession.RunAsync em tools/OmsiLaunch.Cli/Program.cs é o proprietário de referência.

Integradores que escrevem seu próprio proprietário devem reproduzir as duas primeiras garantias: um StartSessionAsync por instalação de cada vez e CloseAsync em todo caminho.

Mapa de falhas#

Todo caminho de falha ainda tenta o encerramento e a restauração; um journal que permaneça é recuperado na próxima inicialização ou por RecoverPendingAsync / /recover (transações e recuperação).