evt_dispatcher
==============

Event queue and dispatcher routing events to active objects.

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_dispatcher_3b62a8e6-96c4-4b62-95cf-7cd61813bb5c_uml.svg
   :alt: UML class diagram for evt_dispatcher
   :class: dblclick-open-image


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


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

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

   * - Relation
     - UML Type
     - Visibility
     - Source Unit
     - Description
   * - :doc:`SWR-001 </generated/detailed_design/relations/swr-001-9e36aec0-c9a4-4e36-8d10-272503709949>`
     - composition
     - private
     - :doc:`ao_runtime_supervisor </generated/detailed_design/units/ao-runtime-supervisor-46acab8f-6426-46ac-9b10-6f02a2ca442d>`
     - Runtime supervisor owns event dispatch lifecycle.

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

.. _dt-049db2e2-5656-449d-8123-888805e1d28c:

.. raw:: html

   <span id="dt-049db2e2-5656-449d-8123-888805e1d28c"></span><div class="sw-dt-title"><span class="sw-dt-name">evt_dispatcher_context</span><span class="sw-dt-badge sw-dt-badge-struct">struct</span></div>

Internal runtime context for evt_dispatcher.

.. rubric:: Struct Members

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

   * - Name
     - Type
     - Description
   * - queue_depth
     - :ref:`uint16_t <dt-036d66c4-d7f5-436d-8f41-bf413e2d3351>`
     - Current queue depth.
   * - max_queue_depth
     - :ref:`uint16_t <dt-036d66c4-d7f5-436d-8f41-bf413e2d3351>`
     - Configured queue capacity.
   * - overflow_flag
     - :ref:`bool <dt-c71dfd1b-cce2-471d-a034-2a7bdc7b8d25>`
     - Queue overflow indicator.
   * - last_dispatch_tick
     - :ref:`uint32_t <dt-9930f975-8f88-4930-9e5b-64c21de2689a>`
     - Last dispatch tick.

.. _dt-e4a7aff3-4599-44a7-9b50-aa3632eebf13:

.. raw:: html

   <span id="dt-e4a7aff3-4599-44a7-9b50-aa3632eebf13"></span><div class="sw-dt-title"><span class="sw-dt-name">evt_dispatcher_event</span><span class="sw-dt-badge sw-dt-badge-struct">struct</span></div>

Event payload handled by evt_dispatcher.

.. rubric:: Struct Members

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

   * - Name
     - Type
     - Description
   * - signal_id
     - :ref:`uint16_t <dt-036d66c4-d7f5-436d-8f41-bf413e2d3351>`
     - Dispatcher event id.
   * - target_unit_id
     - :ref:`uint16_t <dt-036d66c4-d7f5-436d-8f41-bf413e2d3351>`
     - Target unit id.
   * - priority
     - :ref:`uint8_t <dt-45402023-5ffe-4540-ba19-64896d87b3dc>`
     - Dispatch priority class.
   * - enqueue_request
     - :ref:`bool <dt-c71dfd1b-cce2-471d-a034-2a7bdc7b8d25>`
     - True when event enqueued.

.. _dt-20dc741e-d05e-40dc-9bf1-fd13b805c25c:

.. raw:: html

   <span id="dt-20dc741e-d05e-40dc-9bf1-fd13b805c25c"></span><div class="sw-dt-title"><span class="sw-dt-name">evt_dispatcher_result</span><span class="sw-dt-badge sw-dt-badge-enum">enum</span></div>

Result code for evt_dispatcher operations.

.. rubric:: Enum Members

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

   * - Name
     - Value
     - Description
   * - OK
     - 0
     - Event dispatched.
   * - QUEUE_FULL
     - 1
     - Queue full at enqueue.
   * - TARGET_UNKNOWN
     - 2
     - No route for target unit.



Attributes
----------

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

   * - Attribute
     - Type
     - Visibility
     - Description
   * - ctx
     - :ref:`evt_dispatcher_context <dt-049db2e2-5656-449d-8123-888805e1d28c>`
     - private
     - Runtime context for evt_dispatcher state timing and error tracking.

Methods
-------

dispatch
~~~~~~~~

- **Return Type:** :ref:`evt_dispatcher_result <dt-20dc741e-d05e-40dc-9bf1-fd13b805c25c>`
- **Visibility:** public
- **Description:** Process one evt_dispatcher event and update runtime outputs.

.. rubric:: Parameters

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

   * - Name
     - Type
     - Direction
     - Description
   * - event
     - :ref:`evt_dispatcher_event <dt-e4a7aff3-4599-44a7-9b50-aa3632eebf13>`
     - in
     - Process one evt_dispatcher event and update runtime outputs.

init
~~~~

- **Return Type:** :ref:`evt_dispatcher_result <dt-20dc741e-d05e-40dc-9bf1-fd13b805c25c>`
- **Visibility:** public
- **Description:** Initialize evt_dispatcher runtime state and dependencies.



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



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

evt_dispatcher_activity
^^^^^^^^^^^^^^^^^^^^^^^

.. uml::

   @startuml
   start
   :Receive event enqueue request;
   :Push event into queue;
   while (queue not empty?) is (yes)
     :Pop next event (FIFO);
     :Resolve target active object;
     :Call target dispatch(event);
   endwhile (no)
   stop
   @enduml


This activity diagram describes dispatcher queue semantics and event routing policy showing enqueue dequeue target resolution and dispatch invocation ordering that underpins determinism across active objects.



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

evt_dispatcher_timing
^^^^^^^^^^^^^^^^^^^^^

.. uml::

   @startuml
   robust "evt_dispatcher" as DISP
   scale max 1200 width
   concise "event queue" as Q
   
   @0
   Q is enqueued
   DISP is waiting
   
   @50
   DISP is dequeue
   
   @120
   DISP is route_target
   
   @220
   DISP is dispatch_call
   
   @300
   DISP is idle
   
   @enduml


This timing diagram characterizes enqueue to dispatch latency segments and highlights where backlog or routing overhead can affect downstream deadline compliance for control and safety events.



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.


SEQ-006_Degraded_Entry_And_Recovery
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. uml::

   @startuml
   hide footbox
   participant ao_runtime_supervisor
   participant evt_dispatcher
   participant ao_control
   participant ao_safety
   participant ao_diagnostics
   
   ao_runtime_supervisor -> evt_dispatcher : dispatch cycle
   alt degraded entry criteria met
     note over ao_runtime_supervisor: init_timeout OR required_service_failed OR fatal_fault
     ao_runtime_supervisor -> ao_control : EVT_DEGRADED
     ao_runtime_supervisor -> ao_safety : EVT_DEGRADED
     ao_runtime_supervisor -> ao_diagnostics : EVT_DEGRADED
     ao_runtime_supervisor -> evt_dispatcher : restrict noncritical events
   end
   
   ao_runtime_supervisor -> evt_dispatcher : periodic degraded dispatch
   
   alt recovery criteria met
     note over ao_runtime_supervisor: fault_cleared AND watchdog_ok AND required_services_ready
     ao_runtime_supervisor -> evt_dispatcher : EVT_RESET
     ao_runtime_supervisor -> ao_control : EVT_RECOVERY
     ao_runtime_supervisor -> ao_safety : EVT_RECOVERY
     ao_runtime_supervisor -> ao_diagnostics : EVT_RECOVERY
   end
   @enduml


Lifecycle sequence for degraded entry triggers and guarded recovery back to Run.


SEQ-007_Controlled_Shutdown
^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. uml::

   @startuml
   hide footbox
   participant ao_runtime_supervisor
   participant evt_dispatcher
   participant ao_control
   participant ao_safety
   participant ao_diagnostics
   participant ao_modbus_server
   
   ao_runtime_supervisor -> evt_dispatcher : EVT_SHUTDOWN_REQ
   ao_runtime_supervisor -> ao_control : stop outputs to safe state
   ao_runtime_supervisor -> ao_safety : keep protective policy active
   ao_runtime_supervisor -> ao_diagnostics : publish shutdown status
   ao_runtime_supervisor -> ao_modbus_server : stop comm servicing
   
   ao_modbus_server --> ao_runtime_supervisor : EVT_STOPPED
   ao_diagnostics --> ao_runtime_supervisor : EVT_STOPPED
   ao_safety --> ao_runtime_supervisor : EVT_STOPPED
   ao_control --> ao_runtime_supervisor : EVT_STOPPED
   evt_dispatcher --> ao_runtime_supervisor : EVT_STOPPED
   
   ao_runtime_supervisor -> ao_runtime_supervisor : EVT_ALL_STOPPED / Shutdown complete
   @enduml


Controlled shutdown sequence defining stop ordering and completion criteria.