.. _dds_layers_topic:

Topic
=====

.. include:: ../../../safety_manual/rules/RULE_DDS_INCONSISTENTTOPICSTATUS.inc

A Topic conceptually fits between publications and subscriptions.
Each publication channel must be unambiguously identified by the subscriptions in order to receive only the data flow they are interested in, and not data from other publications.

A Topic serves this purpose, allowing publications and subscriptions that share the same Topic to match and start communicating.
In that sense, the **Topic acts as a description for a data flow**.

Keys and Instances
------------------

By definition, a Topic is linked to a single data type, so each data sample related to a Topic could be understood as an update on the information described by the data type.

However, it is possible to include a logical separation and have, within the same Topic, several instances referring to the same data type.
Thus, the received data sample will be an update for a specific instance of that Topic.

Therefore, a Topic identifies data of a single type, ranging from one single instance to a whole collection of instances of that given type.

The different instances gathered under the same topic are distinguishable by means of one or more data fields that form the key to that data set.
The key description has to be indicated to the middleware.

The rule is simple: different data values with the same key value represent successive data samples for the same instance, while different data values with different keys represent different topic instances.

If no key is provided, the data set associated with the Topic is restricted to a single instance.

Please refer to :ref:`typesupport` for more information about how enable and get key values in Safe DDS.

Instance lifecycle
^^^^^^^^^^^^^^^^^^

When reading or taking data from a :ref:`dds_layers_subscription_datareader` (as explained in
:ref:`dds_layers_subscription_accessing_data`), a :ref:`dds_layers_subscription_sampleinfo` is also returned.
This ``SampleInfo`` provides additional information about the instance lifecycle.
The diagram below shows the state chart of ``SampleInfo::instance_state`` and ``SampleInfo::view_state`` for a single instance.

.. image:: ../../../figures/instance_lifecycle.png
  :align: center

.. _dds_layers_topic_qos:

TopicQos
--------

``TopicQos`` controls the behavior of the Topic.
Internally it contains the following :ref:`dds_layers_infrastructure_policies` objects:

* ``durability`` as :ref:`durabilityqospolicy`
    Defines the durability of the Topic.
* ``deadline`` as :ref:`deadlineqospolicy`
    Defines the deadline for the Topic.
* ``liveliness`` as :ref:`livelinessqospolicy`
    Defines the liveliness of the Topic.
* ``reliability`` as :ref:`reliabilityqospolicy`
    Defines the reliability of the Topic.
* ``history`` as :ref:`historyqospolicy`
    Defines the history of the Topic.
* ``resource_limits`` as :ref:`resourcelimitsqospolicy`
    Defines the resource limits of the Topic.
* ``allocations`` as :ref:`dds_layers_infrastructure_safedds_policies_topicallocationsqospolicy`
    Defines the memory configuration of the Topic.

.. include:: ../../../safety_manual/rules/RULE_TOPIC_ALLOCATIONSQOS.inc
.. include:: ../../../safety_manual/rules/RULE_PREALLOCMEMORYCONFIG.inc
.. include:: ../../../safety_manual/rules/RULE_DDS_REQUESTEDINCOMPATIBLEQOSSTATUS.inc
.. include:: ../../../safety_manual/rules/RULE_DDS_OFFEREDINCOMPATIBLEQOSSTATUS.inc

.. note::

   Check :ref:`architecture_platform_memory_management` to understand how memory is managed in Safe DDS.

Example
^^^^^^^

.. literalinclude:: ../../../code/policies_examples/main.cpp
   :language: c++
   :dedent: 8
   :start-after: // DDS_TOPIC_QOS
   :end-before: //! DDS_TOPIC_QOS

.. include:: ./topiclistener.inc
.. include:: ./create_topic.inc