3.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.

3.1.1.1. Types of Entities

  • DomainParticipant: This entity is the entry-point of the Service and acts as a factory for Publishers, Subscribers, and Topics. See DomainParticipant for further details.

  • Publisher: It acts as a factory that can create any number of DataWriters. See Publisher for further details.

  • Subscriber: It acts as a factory that can create any number of DataReaders. See Subscriber for further details.

  • Topic: This entity fits between the publication and subscription entities and acts as a channel. See Topic for further details.

  • DataWriter: Is the object responsible for the data distribution. See DataWriter for further details.

  • DataReader: Is the object used to access the received data. See DataReader for further details.

The following figure shows the hierarchy between all DDS entities:

../../../../_images/entity_diagram.svg

3.1.1.2. Common Entity Characteristics

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

3.1.1.2.1. 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().

3.1.1.2.2. 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()). See Policy for a list of the available policies and their description. The QoS classes and the policies they contain are explained in the documentation for each entity type.

3.1.1.2.3. 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 following diagram:

../../../../_images/listeners_inheritance_diagram.svg

Listeners inheritance diagram.

Note

The on_data_on_readers() callback intercepts messages before on_data_available(). This implies that if DomainParticipantListener is enabled, users should take into account that by default the listener uses StatusMask::all(). As the callback entity hierarchy is kept, the on_data_on_readers() is going to be called in this case. If an application wants to use on_data_available() instead, the corresponding bit of StatusMask should be disabled.

Warning

Only one thread is created to listen for every listener implemented, so it is encouraged to keep listener functions simple, leaving the process of such information to the proper class.

Warning

Do not create or delete any Entity within the scope of a Listener member function, since it could lead to an undefined behavior. It is recommended instead to use the Listener class as an information channel and the upper Entity class to encapsulate such behaviour.

3.1.1.2.4. 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. See Status for a list of all the status objects and a description of their content. There you can also find which status applies to which entity type.

3.1.1.2.5. 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. See section Conditions and Wait-sets for more information.

3.1.1.2.6. Enabling Entities

All the entities can be created either enabled or not enabled. By default, the factories are configured to create the entities enabled, but it can be changed using the EntityFactoryQosPolicy on enabled factories. A disabled factory creates disabled entities regardless of its QoS. A disabled entity has its operations limited to the following ones:

  • Set/Get the entity QoS Policy.

  • Set/Get the entity Listener.

  • Create/Delete subentities.

  • Get the Status of the entity, even if they will not change.

  • Lookup operations.

Any other function called in this state will return NOT_ENABLED.