Entities

The following DDS entities are supported in Safe DDS:

Common characteristics

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

Unique 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 as a InstanceHandle type and can be accessed using the function get_instance_handle().

QoS policies

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. Instances of these QoS classes can be created and modified to configure the entities during the creation process.

The configured QoS of an entity can be retrieved using the function get_qos().

Safe DDS Usage

In Safe DDS, entities won’t allow the modification of their QoS policies after they have been created.

Listeners

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.

Those notifications are propagated using callback functions defined on the provided listener interfaces. Implementations can be linked to an entity at its creation or at a later time with the set_listener() function that every entity exposes.

API Reference

For more information about the listener interfaces, check the API Reference of each provided interface:

When an event occurs it is handled by the lowest level entity that has a non-null listener with the corresponding callback enabled in its StatusMask. Otherwise the event is forwarded to the following entity on the hierarchy, as higher level listeners inherit from the lower level ones as shown in the following diagram:

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

Status

Each entity is associated with a set of status objects whose values represent communication events of that entity. Changes on these status values trigger the invocation of the appropriate listener callback to asynchronously inform the application.

See Status for a list and description of all the available statuses for each entity type.

Enabling entities

All the entities can be created either enabled or disabled. A disabled entity has its operations limited to:

  • Get the entity QoS Policy.

  • Set or get the entity Listener.

  • Create sub-entities.

  • Get the Status of the entity, even if it will never change.

  • Lookup operations.

  • Any other function called in this state will return NOT_ENABLED.

By default, the factories are configured to auto enable its created entities, this behaviour can be configured using the EntityFactoryQosPolicy configuration. In order to enable an entity, the enable() function must be called.

Deleting entities

Safe DDS Usage

In Safe DDS, entities cannot be deleted once they have been created.

../../../_images/entities_diagram.png

DomainParticipantFactory

The DomainParticipantFactory serves as the entry-point of the DDS API and functions as a factory for DomainParticipants.

Safe DDS Usage

In Safe DDS, a DomainParticipantFactory represents an utility for creating DomainParticipants following the DDS API definition. This indicates that only one DomainParticipantFactory can be instantiated per application.

This factory will automatically link the constructed DomainParticipants with the transport (refer to Transport layer) and a default executor (refer to Execution layer).

DomainParticipant

The DomainParticipant entity represents the connection to the DDS domain, which is explained in Domain layer.

This entity serves as a factory for Publishers, Subscribers, and Topics.

Safe DDS Usage

In Safe DDS, only one DomainParticipant is allowed per application.

Publisher

The Publisher entity functions as a factory for DataWriters, as explained in Publication layer.

Safe DDS Usage

In Safe DDS, it is highly recommended to have only one Publisher per DomainParticipant.

Subscriber

The Subscriber entity operates as a factory for DataReaders, as described in Subscription layer.

Safe DDS Usage

In Safe DDS, it is highly recommended to have only one Subscriber per DomainParticipant.

DataWriter

The DataWriter entity is responsible for data distribution, as detailed in Publication layer. It enables writing data samples to the DDS Domain.

DataReader

The DataReader entity is utilized for accessing received data, as elaborated in Subscription layer. It allows reading data samples from the DDS Domain.

Topic

The Topic entity represents the data type being published or subscribed to within the DDS environment. More details can be found in Publication layer and Subscription layer.

Safe DDS Usage

In Safe DDS, compatible Data Readers and DataWriters associated with the same Topic object will communicate via intraprocess communication.