vios-deep-lifecycle git:20260603.14e198cA

Immutable. This exact content is served forever at /api/v1/blob/903514d5533f37b6.

---
description: "Deep reference: VIOS application lifecycle, initialization sequence, and shutdown flow"
globs: "src/app/**"
alwaysApply: false
---

# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
# SPDX-License-Identifier: Apache-2.0
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

# Application Lifecycle

## Boot Sequence (Main.cpp)

1. `getAvailableMemory()` -- baseline memory snapshot
2. `CmdLineParser::parseCommandLine()` -- CLI args (`--viosConfigFile`, `--adaptorConfigFile`, `--debug-level 1-5`, `--log-to-file`)
3. `GET_CONFIG()` -- first call loads `vst_config.json` via `VmsConfigManager` singleton
4. `getCurrentModuleId(MODULE_ID)` -- resolve module from build define
5. `VmsServer(module_id)` -- full server construction
6. `Server->start()` -- blocks until shutdown signal

## VmsServer Constructor (server.cpp:371-416)

| Step | Call | Purpose |
|------|------|---------|
| 1 | `SignalHandler(signal_handler)` | Register SIGINT/SIGTERM |
| 2 | `initBacktraceGenerator()` | SIGSEGV/SIGABRT/SIGBUS backtrace (non-DEBUG) |
| 3 | `startGLoop()` | `async::spawn` GMainLoop thread, then `gst_init()` + `curl_global_init()` |
| 4 | `detectGPU()` | GPU availability check |
| 5 | `initialize()` | ModuleLoader + WebServer + REST API registration |
| 6 | `checkLibsSanity()` | NvBufWrapper/CudaLoader/OSD validation |
| 7 | SensorManagement, DeviceManager, DB, WebSocket, API objects | Core services |

## initialize() (server.cpp:112-164)

1. `ModuleLoader::initialize()` -- loads adaptor via `AdaptorLoader::loadAdaptor()`, then `dlopen` for each module
2. `WebServer()` -- CivetServer with SSL, CORS, auth
3. `m_webServer->registerRESTAPIs(m_func)` -- core APIs
4. Per-module API registration (RTSP, PeerConnection, StreamBridge, Recorder, Storage)

## Main Event Loop (server.cpp:281-296)

- Main thread blocks on `g_mainWait.wait(lk)` (condition variable)
- SIGINT/SIGTERM -> `signal_handler()` -> `stopServer()` -> `g_mainWait.notify_all()`

## Shutdown Sequence

1. `m_serverReady = false`
2. `SystemMonitoringTask::stop()`
3. `stopGLoop()` -> `g_main_loop_quit()`, `gst_deinit()`, `curl_global_cleanup()`, join GMainLoop thread
4. `VmsServer` destructor: DecoderPool, VideoSenderPool, UdpClientPool cleanup, gRPC reset, API reset, `m_webServer.reset()` (CivetServer close + `mg_exit_library()`), `m_moduleLoader->deInitialize()` (`dlclose` all modules)

## Health Probes (health_probes.cpp)

- `checkCivetWebServerRunning()` -- Civetweb context/ports via `mg_get_context`
- `checkReadinessProbe()` -- Civetweb + DB connected
- Endpoints: `/v1/live`, `/v1/ready`, `/v1/startup`

## Threads Created at Startup

| Thread | Source | Purpose |
|--------|--------|---------|
| GMainLoop | `async::spawn` in `startGLoop()` | GLib event loop for GStreamer |
| Civetweb workers | `CivetServer` constructor | HTTP request handling |
| SystemMonitoring | `SystemMonitoringTask::start()` | CPU/RAM/GPU/storage metrics |
| SensorManagement | `m_sensorManagement->start()` | Sensor discovery |