evt_timer_service
=================

Time-event service generating periodic and timeout events.

Inherited Component
-------------------

- :doc:`Runtime_Manager </generated/architecture/runtime-manager-67b5054c-aedb-47b5-8258-c8d97c4f7d69>`

Inherited Requirements
----------------------

- :doc:`REQ-REL-001 </generated/requirements/req-rel-001-2e6b7004-be8f-4e6b-8d4e-e4b18a08ff41>`
- :doc:`REQ-REL-004 </generated/requirements/req-rel-004-6f23cf0d-e838-4f23-b798-f39b79b8042a>`

Relationship Diagram
--------------------

.. image:: /_static/sw_unit_uml/evt_timer_service_2c6052c1-a0af-4c60-9a3f-846e9498d908_uml.svg
   :alt: UML class diagram for evt_timer_service
   :class: dblclick-open-image


SW Unit Relations
-----------------


Incoming Relations
~~~~~~~~~~~~~~~~~~

.. list-table::
   :header-rows: 1

   * - Relation
     - UML Type
     - Visibility
     - Source Unit
     - Description
   * - :doc:`SWR-002 </generated/detailed_design/relations/swr-002-88436ca5-e2fa-4843-8d75-ab617c159b6e>`
     - composition
     - private
     - :doc:`ao_runtime_supervisor </generated/detailed_design/units/ao-runtime-supervisor-46acab8f-6426-46ac-9b10-6f02a2ca442d>`
     - Runtime supervisor owns timer event service.

Data Types
----------

.. _dt-a60c6bc8-02a9-460c-9fc7-03ca038d298c:

.. raw:: html

   <span id="dt-a60c6bc8-02a9-460c-9fc7-03ca038d298c"></span><div class="sw-dt-title"><span class="sw-dt-name">evt_timer_service_context</span><span class="sw-dt-badge sw-dt-badge-struct">struct</span></div>

Internal runtime context for evt_timer_service.

.. rubric:: Struct Members

.. list-table::
   :header-rows: 1

   * - Name
     - Type
     - Description
   * - tick_period_ms
     - :ref:`uint32_t <dt-9930f975-8f88-4930-9e5b-64c21de2689a>`
     - Scheduler tick period.
   * - tick_counter
     - :ref:`uint32_t <dt-9930f975-8f88-4930-9e5b-64c21de2689a>`
     - Tick counter.
   * - timer_running
     - :ref:`bool <dt-c71dfd1b-cce2-471d-a034-2a7bdc7b8d25>`
     - Timer active state.
   * - missed_tick_flag
     - :ref:`bool <dt-c71dfd1b-cce2-471d-a034-2a7bdc7b8d25>`
     - Missed tick indicator.

.. _dt-70119d66-ea6f-4011-bcfb-c97c4dfa346d:

.. raw:: html

   <span id="dt-70119d66-ea6f-4011-bcfb-c97c4dfa346d"></span><div class="sw-dt-title"><span class="sw-dt-name">evt_timer_service_event</span><span class="sw-dt-badge sw-dt-badge-struct">struct</span></div>

Event payload handled by evt_timer_service.

.. rubric:: Struct Members

.. list-table::
   :header-rows: 1

   * - Name
     - Type
     - Description
   * - signal_id
     - :ref:`uint16_t <dt-036d66c4-d7f5-436d-8f41-bf413e2d3351>`
     - Timer event id.
   * - tick_index
     - :ref:`uint32_t <dt-9930f975-8f88-4930-9e5b-64c21de2689a>`
     - Tick sequence number.
   * - source_timer_id
     - :ref:`uint8_t <dt-45402023-5ffe-4540-ba19-64896d87b3dc>`
     - Source timer identifier.
   * - timeout_flag
     - :ref:`bool <dt-c71dfd1b-cce2-471d-a034-2a7bdc7b8d25>`
     - Timeout indicator.

.. _dt-617122c6-076c-4171-adaa-e55f04163533:

.. raw:: html

   <span id="dt-617122c6-076c-4171-adaa-e55f04163533"></span><div class="sw-dt-title"><span class="sw-dt-name">evt_timer_service_result</span><span class="sw-dt-badge sw-dt-badge-enum">enum</span></div>

Result code for evt_timer_service operations.

.. rubric:: Enum Members

.. list-table::
   :header-rows: 1

   * - Name
     - Value
     - Description
   * - OK
     - 0
     - Tick processed.
   * - TIMER_FAULT
     - 1
     - Underlying timer fault.
   * - MISSED_TICK
     - 2
     - Tick deadline missed.



Attributes
----------

.. list-table::
   :header-rows: 1

   * - Attribute
     - Type
     - Visibility
     - Description
   * - ctx
     - :ref:`evt_timer_service_context <dt-a60c6bc8-02a9-460c-9fc7-03ca038d298c>`
     - private
     - Runtime context for evt_timer_service state timing and error tracking.

Methods
-------

dispatch
~~~~~~~~

- **Return Type:** :ref:`evt_timer_service_result <dt-617122c6-076c-4171-adaa-e55f04163533>`
- **Visibility:** public
- **Description:** Process one evt_timer_service event and update runtime outputs.

.. rubric:: Parameters

.. list-table::
   :header-rows: 1

   * - Name
     - Type
     - Direction
     - Description
   * - event
     - :ref:`evt_timer_service_event <dt-70119d66-ea6f-4011-bcfb-c97c4dfa346d>`
     - in
     - Process one evt_timer_service event and update runtime outputs.

init
~~~~

- **Return Type:** :ref:`evt_timer_service_result <dt-617122c6-076c-4171-adaa-e55f04163533>`
- **Visibility:** public
- **Description:** Initialize evt_timer_service runtime state and dependencies.



Dynamic Behaviour
-----------------



Activity Diagrams
~~~~~~~~~~~~~~~~~

evt_timer_service_activity
^^^^^^^^^^^^^^^^^^^^^^^^^^

.. uml::

   @startuml
   start
   :Register periodic and one-shot timers;
   :Advance tick counter;
   if (timer expired?) then (yes)
     :Create timer event;
     :Enqueue event to dispatcher;
     if (periodic?) then (yes)
       :Reload timer deadline;
     else (no)
       :Remove one-shot timer;
     endif
   endif
   stop
   @enduml


This activity diagram specifies timer management behavior for periodic and one shot timers including tick advancement expiry detection event emission and periodic reload policy.



Timing Diagrams
~~~~~~~~~~~~~~~

evt_timer_service_timing
^^^^^^^^^^^^^^^^^^^^^^^^

.. uml::

   @startuml
   robust "evt_timer_service" as TIMER
   scale max 1200 width
   concise "tick" as T
   
   @0
   T is 0ms
   TIMER is counting
   
   @500
   T is 500ms
   TIMER is emit_sampling_event
   
   @1000
   T is 1000ms
   TIMER is emit_protection_deadline_event
   
   @1500
   TIMER is emit_housekeeping_event
   
   @enduml


This timing diagram captures expected timer event emission points for sampling protection and housekeeping deadlines and supports validation of temporal orchestration across runtime services.



Sequence Diagrams
~~~~~~~~~~~~~~~~~

SEQ-001_Runtime_Event_Orchestration
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. uml::

   @startuml
   
   hide footbox
   title Runtime Event Orchestration
   
   participant ao_runtime_supervisor
   participant evt_timer_service
   participant evt_dispatcher
   participant ao_monitoring
   participant ao_control
   participant ao_safety
   participant ao_diagnostics
   participant ao_modbus_server
   
   ao_runtime_supervisor -> evt_timer_service : init periodic tick
   ao_runtime_supervisor -> evt_dispatcher : init event loop
   loop each scheduler tick
     evt_timer_service -> ao_runtime_supervisor : tick event
     ao_runtime_supervisor -> evt_dispatcher : dispatch cycle
     evt_dispatcher -> ao_monitoring : monitor_event
     evt_dispatcher -> ao_control : control_event
     evt_dispatcher -> ao_safety : safety_event
     evt_dispatcher -> ao_diagnostics : diagnostics_event
     evt_dispatcher -> ao_modbus_server : comms_event
   end
   
   @enduml


Primary runtime interoperability sequence showing scheduler tick propagation through dispatcher fan-out and deterministic active-object processing order across monitoring control safety diagnostics and communication units.


SEQ-005_Startup_To_Ready
^^^^^^^^^^^^^^^^^^^^^^^^

.. uml::

   @startuml
   hide footbox
   participant ao_runtime_supervisor
   participant evt_timer_service
   participant evt_dispatcher
   participant ao_monitoring
   participant ao_control
   participant ao_safety
   participant ao_diagnostics
   participant ao_modbus_server
   
   ao_runtime_supervisor -> evt_timer_service : init()
   ao_runtime_supervisor -> evt_dispatcher : init()
   ao_runtime_supervisor -> ao_monitoring : init()
   ao_runtime_supervisor -> ao_control : init()
   ao_runtime_supervisor -> ao_safety : init()
   ao_runtime_supervisor -> ao_diagnostics : init()
   ao_runtime_supervisor -> ao_modbus_server : init()
   
   group readiness gates
     evt_timer_service --> ao_runtime_supervisor : EVT_TIMER_READY
     evt_dispatcher --> ao_runtime_supervisor : EVT_DISPATCH_READY
     ao_monitoring --> ao_runtime_supervisor : EVT_AO_READY
     ao_control --> ao_runtime_supervisor : EVT_AO_READY
     ao_safety --> ao_runtime_supervisor : EVT_AO_READY
     ao_diagnostics --> ao_runtime_supervisor : EVT_AO_READY
     ao_modbus_server --> ao_runtime_supervisor : EVT_AO_READY
   end
   
   ao_runtime_supervisor -> evt_dispatcher : EVT_INIT_OK / start Run
   @enduml


Startup lifecycle sequence with explicit readiness gates before entering Run state.