Portable and high-performance implementation of the Lifecycle feature for the S-CORE project.
High level functionality provided by Lifecycle:
- Launch Manager
- Portability: LaunchManager works with multiple operating systems including Linux and QNX8.
- Component Lifecycle Control: Spawning and terminating OS processes according to their configured parameters (executable path, user/group identity, environment, scheduling policy, etc.).
- Run Target Management: Determining which components are active at any given time by activating and deactivating named Run Targets in response to requests from a StateManager.
- Dependency Resolution: Ensuring components start and stop in the correct order based on declared startup and shutdown dependencies.
- Failure Recovery: Detecting unexpected process termination and executing configured recovery actions such as restarting a component or switching to a recovery Run Target.
- External Watchdog Integration: Compatible with external watchdogs through a configurable watchdog device file.
- Health Monitor
- Supervision Types: Supports Heartbeat, Deadline, and Logical supervision to verify the timing and control flow of process execution.
- Alive Notifications: Supervision results are translated into alive notifications sent to the Launch Manager to communicate supervision status and report failures.
Health Monitoring API
//score/health_monitor:health_monitoring_cc
//score/health_monitor:health_monitoring_rust
The Health Monitoring library provides APIs for the following supervisions:
- Heartbeat Supervision
- Deadline Supervision
- Logical Supervision
These supervision results are translated to alive notifications that are sent to the Launch Manager via its Alive API.
See the C++ Supervised Example Application and Rust Supervised Example Application.
Alive API
//score/launch_manager:alive_cc
//score/launch_manager:alive_rust
The Alive API allows applications to report alive notifications to the Launch Manager. Applications may either use the higher-level Health Monitoring APIs or directly report alive notifications to the Launch Manager via the Alive API.
Lifecycle API
//score/launch_manager:lifecycle_cc
//score/launch_manager:lifecycle_rust
Applications can report the Running state to the Launch Manager to signal that initialization is finished and dependent applications can now be started.
Applications may either use the higher-level score::mw::lifecycle::Application API or the lower-level score::mw::lifecycle::report_running function.
See examples Application Example and report_running example.
Control API
//score/launch_manager:control_cc
The Control API is intended for implementing a State Manager that controls which Run Target is currently active.
See the Example StateManager.
Launch Manager
//score/launch_manager:launch_manager
The launch_manager target contains the daemon executable.
The Launch Manager is configured with a JSON file that is compiled to a binary format using the bazel macro:
load("//:defs.bzl", "launch_manager_config")
launch_manager_config(
name = "examples_test_config",
config = ":lifecycle_demo_test.json",
flatbuffer_out_dir = "etc",
)See the demo scenario for an example.
Mocks
//score/launch_manager:mock_application_context_cc
//score/launch_manager:mock_lifecycle_cc
//score/launch_manager:mock_report_running_cc
It is recommended to use the devcontainer for building the project. See eclipse-score/devcontainer/README.md#inside-the-container for setup instructions.
Build all components for different platforms:
QNX
Building and testing for QNX requires a QNX license and a myQNX account. If you don't have a QNX license, you can get a free non-commercial license by following this guide.
Either use a .netrc file to provide the login credentials for your myQNX account or provide them as environment variables SCORE_QNX_USER and SCORE_QNX_PASSWORD.
Example ~/.netrc:
machine qnx.com
login <myQNX user>
password <myQNX password>
The QNX toolchain is automatically downloaded when building for QNX.
If the automatic download via Bazel fails for some reason you can also provide the manually downloaded file in a directory which you then pass via the --distdir command line option.
Make sure your QNX license file is available as /opt/score_qnx/license/licenses (e.g. by copying it from your ~/.qnx/license/licenses)
bazel build --config=x86_64-qnx //score/...
bazel build --config=arm64-qnx //score/...Unit and integration tests via QEMU:
Outside the devcontainer QEMU has to be installed (e.g. sudo apt install qemu-system-x86 qemu-system-arm).
bazel test --config=x86_64-qnx //score/... //tests/integration/...
bazel test --config=arm64-qnx //score/... //tests/integration/...//score/... contains the unit tests, //tests/integration/... the integration tests.
The unit and integration tests do not have to run together. Each path can also be tested on its own.
Linux
bazel build --config=x86_64-linux //score/...
bazel build --config=arm64-linux //score/...- For generating a code coverage report, see quality/coverage/README.md.
- For running tests with sanitizers enabled, see quality/sanitizer/README.md.
See instructions here on how to execute a demo scenario.
score_lifecycle/
├── score/ # Lifecycle implementation
│ ├── launch_manager/ # Launch Manager daemon + library implementation + unit/component tests
│ └── health_monitor/ # Health Monitoring library implementation + unit/component tests
├── external/ # Third party software
├── examples/ # Example applications
├── scripts/ # Launch Manager Configuration generation
├── quality/ # Quality specific infrastructure code (e.g. code coverage)
└── tests/ # Feature Integration tests
We welcome contributions! See our Contributing Guide for details.
- Issues: Report bugs and request features via GitHub Issues
- Discussions: Join lifecycle slack channel