.. _architecture_platform:

Platform module
===============

.. raw:: html

   <style>
        .layer_group:not(#platform_group) path {
            fill: #aaa;
            stroke: #888 !important;
        }

        .layer_group {
            opacity: 1;
            transition: opacity 0.1s;
        }

        svg:hover .layer_group:not(#platform_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

.. include:: ../safety_manual/rules/RULE_PLATFORM_MODULE_NOT_ALLOW.inc
.. include:: ../safety_manual/rules/RULE_PLATFORMS_ALLOWED.inc

In Safe DDS, all operations related to the platform are executed by the Platform module, which has been designed to be responsible for the following tasks:

* **Management of memory allocation calls**, ensuring that all the possible memory allocations are performed via platform interfaces.
* **Handling of fatal errors**, allowing for appropriate responses to critical issues that may arise during the library's operation.
* **Control of timing mechanisms**, providing platform specific timekeeping for various processes within the library.

By delegating these essential functions to the platform module, it is possible to maintain a streamlined and organized structure within Safe DDS, ultimately contributing to its reliability, performance and portability.

.. _architecture_platform_default_platform:

Default platform
-----------------

If Safe DDS has been built with any built-in platform support using the ``SAFEDDS_PLATFORM`` flag via :ref:`installation_cmake_options`, the default platform can be retrieved using the system-wide ``get_platform`` method.
Analogously, a system-wide default platform can be set using the ``set_platform`` method.
This API will be used internally by multiple Safe DDS modules to perform platform related operations.

.. literalinclude:: ../code/architecture_reference/main.cpp
   :language: c++
   :start-after: // HANDLING_DEFAULT_SYSTEM_PLATFORM
   :end-before: //! HANDLING_DEFAULT_SYSTEM_PLATFORM
   :dedent: 4


.. _architecture_platform_iplatform:

IPlatform interface
-------------------

``IPlatform`` is the interface that all platform module implementation must implement.

.. admonition:: API Reference
   :class: seealso

   For more information about ``transport::IPlatform`` interface, check API Reference:

   - `transport::IPlatform <../doxygen/classeprosima_1_1safedds_1_1platform_1_1_i_platform.html>`__

.. _architecture_platform_memory_management:

Memory management
^^^^^^^^^^^^^^^^^
Safe DDS memory operations are performed using the ``allocate`` method of the platform module.
This method is responsible for allocating memory blocks of the specified size with a certain alignment, and returning a pointer to the beginning of the allocated memory.

It is important to note that the memory allocated will not be deallocated, meaning that Safe DDS will provide mechanisms for controlling the memory allocations performed by the different modules.

At DDS level, these memory allocations can be controlled by means of the :ref:`dds_layers_infrastructure_safedds_preallocmemoryconfig` and related QoS policies.
Those policies allows for specifying the maximum amount of elements that a certain entity will be able to allocate, and also allow for the application to specify how many of those elements shall be preallocated at creation time.

.. note::

   Note that the Safe DDS static API, detailed at :ref:`StaticDomainParticipant <dds_layers_create_domain_participant_static>`, :ref:`StaticTopic <dds_layers_create_topic_static>`, :ref:`StaticPublisher <dds_layers_create_publisher_static>`, :ref:`StaticSubscriber <dds_layers_create_subscriber_static>`, :ref:`StaticDataWriter <dds_layers_create_datawriter_static>` and  :ref:`StaticDataReader <dds_layers_create_datareader_static>`, does not leverage the memory allocation mechanism provided by the platform module.

   If the Safe DDS :ref:`architecture_dds_static` is used, it is recommended to override the ``allocate`` method of the platform module to trigger an assertion.

.. note::

   For a complete reference of the different memory objects used in Safe DDS, please refer to :ref:`architecture_memory`.

The ``allocate`` function of ``platform::IPlatform`` returns a ``void *`` pointer to the beginning of the allocated memory and takes the following arguments:

* ``size`` as ``uint32_t``
    The size of the memory block to be allocated.
* ``alignment`` as ``uint32_t``
    The alignment of the memory block to be allocated.

.. _architecture_platform_error_handling:

Error handling
^^^^^^^^^^^^^^

Safe DDS will use the ``fatal_error`` method of the platform module to handle fatal errors during the library's operation.
This method shall not return as it is called when the library is in an unrecoverable state.

.. _architecture_platform_timekeeping:

Time keeping
^^^^^^^^^^^^

Safe DDS will use the ``get_current_timepoint`` method of the platform module to retrieve the current time.
This method shall return a monotonic timepoint as an ``execution::TimePoint`` object and takes no arguments.

Example implementation
----------------------

A naive ``IPlatform`` interface implementation could be:

.. literalinclude:: ../code/architecture_reference/main.cpp
   :language: c++
   :start-after: // REFERENCE_PLATFORM_IMPLEMENTATION
   :end-before: //! REFERENCE_PLATFORM_IMPLEMENTATION