.. _architecture_execution:

Execution module
================

.. raw:: html

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

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

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

Safe DDS provides a set of interfaces to allow the application to implement their own execution model.
This allows for integrating Safe DDS into specific execution models such as leveraging the library within threaded environments.

.. include:: ../safety_manual/rules/RULE_THREADING.inc
.. include:: ../safety_manual/rules/RULE_ENABLING_ORDER.inc

.. note::

    Safe DDS cannot be used in a threaded environment as it does not provide any kind of thread locking mechanism.

    In order to use Safe DDS in a threaded environment, it must be assumed that all provided APIs are non thread safe, and application locking mechanisms shall be implemented to protect every concurrent API call.

The Safe DDS execution model is based on ``ISpinnable`` interface, which provides:

* A non-blocking ``has_pending_work`` method that enables the entities to check if they have pending work to be done.
* A blocking with timeout ``spin`` method that enables the entities to perform their internal tasks including :ref:`transport <architecture_transport>` operations.

By means of these two methods, the entities can be integrated into any kind of execution model, including blocking and non-blocking ones.

.. _architecture_execution_ispinnable:

ISpinnable interface
--------------------

.. admonition:: API Reference
   :class: seealso

   For more information about ``execution::ISpinnable`` interface, check API Reference `execution::ISpinnable <../doxygen/classeprosima_1_1safedds_1_1execution_1_1_i_spinnable.html>`__


In general, most of the entities in Safe DDS are ``ISpinnable`` and implement the interface methods.

.. _architecture_execution_has_pending_work:

has_pending_work
^^^^^^^^^^^^^^^^

This method returns ``true`` if the entity has pending work to be done, and ``false`` otherwise.
It takes no arguments and returns a ``bool``.

.. _architecture_execution_get_next_work_timepoint:

get_next_work_timepoint
^^^^^^^^^^^^^^^^^^^^^^^

This method returns ``TimePoint`` with next work ``TimePoint`` of the spinnable entity.

.. _architecture_execution_spin:

spin
^^^^

This method performs the entity internal tasks, including possible :ref:`transport <architecture_transport>` operations.
This method takes as argument:

* Timepoint as ``execution::Timepoint``
  Timeout for the spin operation to be performed.

.. _architecture_execution_default_executor:

Default Execution Model
-----------------------

.. include:: ../safety_manual/rules/RULE_DEFAULT_EXECUTOR.inc
.. include:: ../safety_manual/rules/RULE_CREATION_ORDER.inc
.. include:: ../safety_manual/rules/RULE_OPERATION_PHASE_ACTIONS.inc
.. include:: ../safety_manual/rules/RULE_HANDLING_STATUS.inc

Safe DDS provides a default executor at the ``BasicExecutor`` class.

.. admonition:: API Reference
   :class: seealso

   For more information about ``execution::BasicExecutor`` interface, check API Reference `execution::BasicExecutor <../doxygen/classeprosima_1_1safedds_1_1execution_1_1_basic_executor.html>`__

This executor can be instantiated using the ``create_default_executor`` member function of :ref:`dds_layers_domain_participant_factory`, and can be used as follows:

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

Executor example
----------------

A naive implementation of a custom executor could be as follows:

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