2. DDS Layer

2.1 Core

2.1.1 Entity

Entity is the abstract base class for all the DDS entities, meaning an object that supports QoS policies, a listener, and statuses.

1. Types of Entities

   • DomainParticipant: This entity is the entry-point of the Service and acts as a factory for Publishers, Subscribers, and Topics.
   • Publisher: It acts as a factory that can create any number of DataWriters.
   • Subscriber: It acts as a factory that can create any number of DataReaders.
   • Topic: This entity fits between the publication and subscription entities and acts as a channel.
   • DataWriter: Is the object responsible for the data distribution.
   • DataReader: Is the object used to access the received data.

2. Common Entity Characteristics

   All entity types share some characteristics that are common to the concept of an entity. Those are:

   • Entity Identifier: Each entity is identified by a unique ID, which is shared between the DDS entity and its corresponding RTPS entity if it exists. That ID is stored on an Instance Handle object declared on Entity base class, which can be accessed using the getter function get_instance_handle().

   • QoS policy: The behavior of each entity can be configured with a set of configuration policies. For each entity type, there is a corresponding Quality of Service (QoS) class that groups all the policies that affect said entity type. Users can create instances of these QoS classes, modify the contained policies to their needs, and use them to configure the entities, either during their creation or at a later time with the set_qos() function that every entity exposes (DomainParticipant::set_qos(), Publisher::set_qos(), Subscriber::set_qos(), Topic::set_qos(), DataWriter::set_qos(), DataReader::set_qos()).

   • Listener: A listener is an object with functions that an entity will call in response to events. Therefore, the listener acts as an asynchronous notification system that allows the entity to notify the application about the Status changes in the entity.

     All entity types define an abstract listener interface, which contains the callback functions that the entity will trigger to communicate the Status changes to the application. Users can implement their own listeners inheriting from these interfaces and implementing the callbacks that are needed on their application. Then they can link these listeners to each entity, either during their creation or at a later time with the set_listener() function that every entity exposes (DomainParticipant::set_listener(), Publisher::set_listener(), Subscriber::set_listener(), Topic::set_listener(), DataWriter::set_listener(), DataReader::set_listener()). The listener interfaces that each entity type and their callbacks are explained in the documentation for each entity type. When an event occurs it is handled by the lowest level entity with a listener that is non-null and has the corresponding callback enabled in its StatusMask. Higher level listeners inherit from the lower level ones as shown in the diagram.

   • Status: Each entity is associated with a set of status objects whose values represent the communication status of that entity. The changes on these status values are the ones that trigger the invocation of the appropriate Listener callback to asynchronously inform the application.

   • StatusCondition: Every entity owns a StatusCondition that will be notified whenever its enabled statuses change. The StatusCondition provides the link between an Entity and a Wait-set.

   More information can be found here.

2.1.2 Policy

The Quality of Service (QoS) is used to specify the behavior of the Service, allowing the user to define how each entity will behave. To increase the flexibility of the system, the QoS is decomposed in several QoS Policies that can be configured independently. However, there may be cases where several policies conflict. Those conflicts are notified to the user through the ReturnCodes that the QoS setter functions returns.

Each Qos Policy has a unique ID defined in the QosPolicyId_t enumerator. This ID is used in some Status instances to identify the specific Qos Policy to which the Status refers.

There are QoS Policies that are immutable, which means that only can be specified either at the entity creation or before calling the enable operation.

Each DDS Entity has a specific set of QoS Policies that can be a mix of Standard QoS Policies, XTypes Extensions and eProsima Extensions.

More information can be found here.

2.1.3 Status

Each Entity is associated with a set of Status objects whose values represent the communication status of that Entity. Changes on the status values occur due to communication events related to each of the entities, e.g., when new data arrives, a new participant is discovered, or a remote endpoint is lost. The status is decomposed into several status objects, each concerning a different aspect of the communication, so that each of these status objects can vary independently of the others.

Changes on a status object trigger the corresponding Listener callbacks that allow the Entity to inform the application about the event. For a given status object with name fooStatus, the entity listener interface defines a callback function on_foo() that will be called when the status changes.

2.1.4 Conditions and Wait-sets

Conditions (in conjunction with wait-sets) provide an alternative mechanism to allow the middleware to notify communication status changes (including arrival of data) to the application.

More information can be found here.