User Guide#

Introduction#

What is the Launch Manager?#

The Launch Manager is a system daemon responsible for managing the execution of software components on an embedded target. It is designed to run for the lifetime of the target and take care of platform initialization, ordered start-up and shutdown of components, and recovery from unexpected failures.

Responsibilities#

The Launch Manager is responsible for:

  • Component lifecycle control - spawning and terminating OS processes according to their configured parameters (executable path, user/group identity, environment, scheduling policy).

  • 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.

  • 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 Control Client.

Key concepts#

Components#

A Component is an independent, deployable software unit managed by the Launch Manager. This can be a long-running daemon developed with the lifecycle API, a one-shot application, or any arbitrary binary such as ls. Components are defined independently of the systems they run on, which allows the same component to be deployed across multiple target configurations without modification.

The specific deployment parameters of a component (such as which run targets it is included in, its startup timeout, or its termination behavior) are kept separate from the component’s inherent properties. This separation allows for reusability across different system configurations.

Ready state#

Each component has a Ready State. A component reaches the Ready State when it has started successfully and has satisfied its configured ready condition. A ready condition can be Running or Terminated. To report a successful start and achieve the Running condition, the binary has to call the API provided by the life cycle library. Currently the following languages are supported C, C++, Rust, note that a process has to first report a successful start before termination for the Terminated condition to be achieved.

A component can also be configured to be non-reporting. The Launch Manager considers it to be in the Ready State as soon as its process has been spawned. This is useful for integrating third-party binaries or system utilities where the source code cannot be modified to report the running state.

It is important to understand that the Ready State reflects a component’s functional availability, not merely the existence of its OS process. For example, a component that mounts a file system remains in the Ready State for as long as the mount is active, even if the process that performed the mount has already exited.

Reaching the Ready State signals to the Launch Manager that the component is fully operational and capable of providing its services, this point is decided by the application developer. This allows for other components to safely rely on other components services and for the startup procedure to be evaluated by the Launch Manager.

Run targets#

A Run Target defines a named collection of components that are intended to be active together. Only one Run Target can be active at a time. When a Run Target is activated, the Launch Manager transitions the system exclusively to that target, any components not assigned to it are terminated.

When a Run Target is activated, the Launch Manager performs the following:

  • All components currently in the Ready State that are not assigned to the new Run Target are terminated.

  • All components that are assigned to the new Run Target but are not yet in the Ready State are started.

Starting Components#

With the definitions of Components, Run Targets, and Ready State established, let us clarify the conditions under which the Launch Manager will initiate a component’s startup sequence. Components will be started for two primary reasons:

  • A component is directly assigned to a Run Target that is currently being activated.

  • Another component, which is assigned to a Run Target being activated, explicitly depends on that component.

Note

The exact interleaving of terminations and starts during a transition is not defined, new components may be started before, after, or concurrently with the termination of outgoing components. If a component depends on another being fully stopped or fully ready before it proceeds, this should be expressed using dependencies between components or run-targets rather than relying on transition ordering.

Dependencies#

A fundamental aspect of Launch Manager configuration involves understanding how components are assigned to a Run Target and how dependencies are declared.

When a component is said to be assigned to a Run Target, it means the Run Target’s configuration explicitly lists the component’s name within its depends_on parameter.

Similarly, when a component depends on another component, its own component_properties.depends_on configuration parameter will list the name of the other component it requires.

Additionally, a Run Target can declare a dependency on another Run Target. In this scenario, the name of the dependent Run Target is listed within the depends_on configuration parameter of the primary Run Target. The most effective way to conceptualize this relationship is to imagine that the list of components assigned to the dependent Run Target is effectively included in the list of components of the primary Run Target.

Rules for Configuring Dependencies#

When configuring dependencies within the Launch Manager, the following rules must be observed to ensure correct system behavior:

  • A Component can depend on another Component.

  • A Run Target can depend on a Component.

  • A Run Target can depend on another Run Target.

  • A Component cannot depend on a Run Target.

Example#

The following diagram illustrates two Run Targets sharing some components and each having components exclusive to them. When transitioning from Startup to Full, the Launch Manager deactivates components not assigned to Full and activates those that are.

The order in which components are started and stopped within a transition is determined by their configured dependencies. And so the following is the sequence diagram showing the processes being started: