docs: update to supported formats

docs/index.rst

@@ -21,6 +21,8 @@ Lifecycle
    :titlesonly:
 
    module/*/index
+   module/lifecycle_client_lib/lifecycle
+   module/lifecycle_client_lib/lifecyclemanager
    statistics.rst
 
 Overview

docs/module/lifecycle_client_lib/lifecycle.rst

@@ -0,0 +1,220 @@
+..
+   # *******************************************************************************
+   # Copyright (c) 2026 Contributors to the Eclipse Foundation
+   #
+   # See the NOTICE file(s) distributed with this work for additional
+   # information regarding copyright ownership.
+   #
+   # This program and the accompanying materials are made available under the
+   # terms of the Apache License Version 2.0 which is available at
+   # https://www.apache.org/licenses/LICENSE-2.0
+   #
+   # SPDX-License-Identifier: Apache-2.0
+   # *******************************************************************************
+
+.. _application_lifecycle:
+
+Application Lifecycle
+=====================
+
+Introduction
+------------
+
+Purpose of this component is to have a layer of abstraction, that unifies API, for execution managers and applications so in case of replacing lifecycle manager there will be no need to change applications.
+
+.. note::
+
+   This component has ``ASIL-B`` safety level.
+
+External interfaces
+-------------------
+
+Component consists of three main parts:
+
+* Application Base class ``score::mw::lifecycle::Application`` from which application developers shall subclass their own application.
+* Lifecycle manager class ``score::mw::lifecycle::LifecycleManager`` see :ref:`lifecyclemanager_class`.
+* Runner class ``score::mw::lifecycle::Run`` which instantiates the user provided application and decides which LifeCycleManager to use.
+
+Overview on how lifecycle application is related to execution manager.
+
+.. uml:: model/lifecycle_system_view.puml
+   :caption: Lifecycle Manager Application Overview
+
+AAS Interfaces
+~~~~~~~~~~~~~~
+
+N/A
+
+External C++ interfaces
+~~~~~~~~~~~~~~~~~~~~~~~
+
+``score:mw::Application`` methods which have to be implemented by the application:
+
+Initialize
+^^^^^^^^^^
+
+This method shall do basic initialization of application (what was not done in application :ref:`State Initializing <state-initializing>`). 
+Method returns a ``Result``, which either contains ``void`` on success or an error. In case of an error lifecycle manager will join all running threads and will return with non zero value.  
+Input parameter to this method is an instance of ``ApplicationContext``, which is a wrapper around the arguments, which have been given to ``main``.
+
+Run
+^^^
+
+This method implements the ``Run`` state of the app (see :ref:`State Run <state-run>`). This could be a long running
+functionality. In case ``Run()`` returns, this implicitly means, that the app has ended. If
+app implementations do spawn some worker threads in the context of ``Run()``, those threads
+are joined again before ``Run()`` returns.
+To be able to terminate an application ``Run()`` method from outside asynchronously in a cooperative manner, the ``Run()`` method
+gets a ``stop_token``, where it shall synchronize/listen on (see concepts in https://en.cppreference.com/w/cpp/thread/stop_token)
+This ``stop_token`` is controlled by an external ``stop_source`` owned by the ``LifecycleManager``.
+
+ApplicationContext class represents cmd line arguments of an Application that are passed during ``Initialize`` function call.
+
+get_argument
+^^^^^^^^^^^^
+
+Function gets a argument name as a string and returns it's value if it exists, otherwise empty string is returned.
+
+get_arguments
+^^^^^^^^^^^^^
+
+Returns list of cmd line arguments represented as a vector.
+
+Example code:
+
+.. code-block:: cpp
+
+   std::array<std::string, 3> in_args{};
+   if (context.get_arguments().empty())
+   {
+     score::mw::log::LogError() << "Incorrect arguments given\n";
+   } else
+   {
+     context.get_argument("-i", in_args[0]);
+     if (in_args[0].empty()) 
+     {
+       score::mw::log::LogError() << "Tsync Incorrect arguments given\n";
+     } else 
+     {
+       // argument is in in_args[0] to be used by application
+     }
+   }
+
+run_application template function
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+``run_application`` function abstracts initialization and running of an application with LifeCycleManager. This function should be used to start application, it take command line arguments as input parameters
+
+Hardware interfaces
+~~~~~~~~~~~~~~~~~~~
+
+N/A
+
+Interrupts
+~~~~~~~~~~
+
+N/A
+
+File system
+~~~~~~~~~~~
+
+N/A
+
+POSIX signals
+~~~~~~~~~~~~~
+
+SIGTERM see `lifecyclemanager.rst <lifecyclemanager.rst>`_
+
+Static architecture
+-------------------
+
+.. uml:: model/structural_view.puml
+   :caption: Structural View
+
+Dynamic architecture
+--------------------
+
+Activity sequencing
+~~~~~~~~~~~~~~~~~~~
+
+The following sequence diagram shows the interaction between OS and instances of ``Application`` class, which were
+decorated with a ``LifecycleManager``:
+
+.. uml:: model/sequence_view.puml
+   :caption: Sequence View
+
+Stateful behavior
+~~~~~~~~~~~~~~~~~
+
+The following state machine depicts the states/transitions of an application:
+
+.. uml:: model/app_lifecycle.puml
+   :caption: Application Lifecycle
+
+.. _state-terminated:
+
+State ``Terminated`` respectively ``Not Started``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This is the initial respectively final state of an application, before its executable has been started (forked, executed) and after it
+has terminated.
+
+.. _state-initializing:
+
+State ``Initializing``
+^^^^^^^^^^^^^^^^^^^^^^
+
+This state is automatically entered upon start of the executable (fork + exec). It is left towards state ``Run``
+if the application decides to do so via an active/explicit reporting to the platform, that it has entered ``Run``.
+
+What shall/can be done in this state
++++++++++++++++++++++++++++++++++++++
+
+* Initialize internal variables/memory
+* Access persistent storage to read/lookup configuration
+* Search for/start searching for other service instances to be used to provide application services
+
+  * Note: These operations must not be performed in a blocking manner! Otherwise the predefined maximum amount of time to be spent in machine state ``Initializing`` might be exceeded and the ECU will restart immediately once that becomes the case.
+
+* access remote service instances if available
+
+  * Also here, keep in mind the note from above!
+
+* access to low-level platform services, which are expected to be available, when an application starts.
+* call to exit. F.i. if initialization can't conclude.
+
+What must not be done in this state
+++++++++++++++++++++++++++++++++++++
+
+* Offer any service instance. Reason: If it would offer a service instance, an instant service call to this instance
+  could happen and would then be served during state ``Initializing``, which isn't acceptable.
+* Generally: Providing/Executing main application logic, which is assigned to ``Run`` state.
+
+.. _state-run:
+
+State ``Run``
+^^^^^^^^^^^^^
+
+As mentioned above: This state is entered, when the application reports ``Run`` state to the platform.
+An application should only enter this state, if it is able to provide its core/base functionality. If it isn't able to
+do so, it shall not report ``Run`` at all.
+
+Example of what could be done in this state
+++++++++++++++++++++++++++++++++++++++++++++
+
+* Assign invalid/dummy values as defaults to the fields/events of service(s) to be offered
+* Offer service(s)
+* Prepare DTCs
+* Wait for dependent services to become available via their generated proxy classes
+* connect to/lookup other required resources
+* run core logic
+
+Variability
+-----------
+
+* N/A
+
+Deployment
+----------
+
+* There is example app available that can help with deploying this library see `example application <https://github.com/eclipse-score/lifecycle/tree/main/examples>`_ subdirectory