.. _architecture:

Architecture
============

.. raw:: html

   <style>
        .layer_group {
            opacity: 1;
            transition: opacity 0.1s;
        }

        svg:hover .layer_group {
            opacity: 0.6;
        }

        .layer_group:hover:not(#system_group):not(#toolchain_group) {
            opacity: 1 !important;
        }
    </style>

.. raw:: html
   :file: ../figures/svg_href_loader.html

.. raw:: html
   :file: ../figures/stack_diagram.svg

The architecture of Safe DDS is characterized by a layered structure, which relies on interfaces.
Each layer within this architecture offers a set of interfaces that are utilized by the layer above in order to implement its designated functionality.

Two distinct types of layers can be identified within this structure: functional layers and support layers.

Possible errors that may occur while using the different interfaces are communicated through error codes called :ref:`architecture_returncode`.

Functional layers serve as the primary providers of the library's core functionality.
These layers consist of:

* :ref:`architecture_transport`
    This layer offers abstractions for lower-level communication protocols, handling message reception and transmission to and from destinations (locators).
* :ref:`architecture_protocol`
    This layer introduces a low-level concept of the publication-subscription communication paradigm, encompassing the notions of sample, endpoint, reliability, acknowledgements, fragmentation, and transport message processing.
    By default, an `RTPS <https://www.omg.org/spec/DDSI-RTPS/>`__ implementation of the protocol layer interfaces is provided.
* :ref:`architecture_datacentric`
    This layer abstracts the publication-subscription paradigm, delivering the concepts of topic history, serialization, and deserialization.
    In conjunction with the protocol layer, it establishes a type-agnostic publication-subscription paradigm without DDS concepts.
* :ref:`architecture_discovery`
    This layer separates the notions of remote communication node discovery from remote endpoint discovery, offering default implementations for the two phases of the default DDS standard Simple Discovery Protocol (SDP), i.e. Simple Participant Discovery Phase (SPDP), and Simple Endpoint Discovery Phase (SEDP).
* :ref:`architecture_dds`
    This layer constructs a DDS-compliant API on top of the :ref:`architecture_datacentric`, incorporating the DDS concepts of domain, topic, publisher, subscriber, datawriter, datareader, QoS policies, status, and listener, as documented in the :ref:`DDS Layer <dds>` section.

Support layers, on the other hand, are responsible for providing assistance to the functional layers. These layers include:

* :ref:`architecture_portable`
    This layer offers abstractions for the toolchain, encapsulating elements typically provided by a standard library but not universally available across all supported/available toolchains.
* :ref:`architecture_platform`
    This module encapsulates platform-specific code, presenting abstractions for the operating system, fatal error handling, timing, and memory management.
* :ref:`architecture_memory`
    This layer abstracts memory access to avoid the use of memory pointers, introducing the concepts of buffer view, memory mutability, and constancy.
* :ref:`architecture_execution`
    This layer outlines the execution model of Safe DDS, delivering a flexible and configurable means of executing entities, timers, and events that can be built upon various platform threading or execution paradigms.
* :ref:`architecture_serialization`
    This layer abstracts the serialization and deserialization of data, offering the concepts of serializer and deserializer as well as implementations for the CDR specification.

.. toctree::
   :maxdepth: 1
   :hidden:

   /architecture/dds
   /architecture/discovery
   /architecture/datacentric
   /architecture/protocol
   /architecture/transport
   /architecture/platform
   /architecture/portable
   /architecture/memory
   /architecture/execution
   /architecture/serialization
   /architecture/returncode