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.
See Standard QoS Policies for a list of the available policies and their description.
See Safe DDS QoS Policies for a list of custom Safe DDS QoS policies and their description.
The configured QoS of an entity can be retrieved using the function get_qos().
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:
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 does not allow the deletion of entities, as they will finish their operation when the application is terminated.
DomainParticipantFactory
The DomainParticipantFactory serves as the entry-point of the DDS API and functions as a factory for DomainParticipants.
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.
Publisher
The Publisher entity functions as a factory for DataWriters, as explained in Publication layer.
Subscriber
The Subscriber entity operates as a factory for DataReaders, as described in Subscription layer.
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.
Note
In Safe DDS, compatible Data Readers and DataWriters associated with the same Topic object will communicate via intraprocess communication.