- topics registered in the domain
-
which data readers and writers connect and disconnect
-
the QoS settings of the entities in the domain
What are built-in topics?
Different DDS entities are found in separate built-in topics
The built-in topics are:
- DCPSParticipant
- DCPSTopic
- DCPSPublication
- DCPSSubscription
The DCPSParticipant topic is used to describe each instance of a Domain participant.
Each Topic entity is described by an instance of the DCPSTopic topic.
Information about Publishers and DataWriters comes in a joint built-in topic called DCPSPublication. This contains one instance for each DataWriter which embeds the relevant information from the Publisher that contains it. To get information about the writers in your system you should subscribe to the DCPSPublication topic.
Subscribers and DataReaders also come in a joint built-in topic called DCPSSubscription. This contains one instance for each DataReader which also contains the information from the Subscriber that contains it.
Internal Built-in Topics
OpenSplice also has a number of other built-in topics which it uses internally, for example DCPSDelivery, DCPSHeartbeat and potentially some others. These topics are proprietary and for internal use only. These should not be used in applications as the API is subject to change between versions. Using these topics in applications may also interfere with the internal mechanisms that rely on them and prevent OpenSplice running correctly
What information is contained in the built-in topics?
DCPSParticipant
The DCPSParticipant topic uses the ParticipantBuiltinTopicData datatype to keep track of DomainParticipants in a Domain. Each ParticipantBuiltinTopic data sample represents a DomainParticipant.
If you create a new DomainParticipant in a domain than a new ParticipantBuiltinTopicData instance is created.
If a new DomainParticipant is created then a new ParticipantBuiltinTopicData instance is created. If the DomainParticipant is then deleted the ParticipantBuiltinTopicData instance is disposed. If a DomainParticipant modifies its UserDataQosPolicy then an updated ParticipantBuiltinTopicData sample is written.
ParticipantBuiltinTopicData Members table
The following table shows the information contained in the DCPSParticipant topic.
| Name | Type | Description |
|---|---|---|
| key | BuiltinTopicKey_t | Globally unique identifier of the participant |
| user_data | UserDataQosPolicy | User-defined data attached to the participant via a QosPolicy |
DCPSTopic
The DCPSTopic topic communicates the existence of topics by the use of the TopicBuiltinTopicData datatype. A TopicBuiltinTopicData sample in a domain is a representation of a Topic in that Domain. When a new Topic is added to the domain a new TopicBuiltinTopic data instance is created.
This instance will not be disposed when a Topic is deleted by its participant because a topic lifecycle is tied to the lifecycle of the Domain rather than the lifecycle of the participant. Due to the nature of DDS the lifecycle of topics (and their samples) are not related to publishers and subscribers. Topics (and built-in topics) are immortal in DDS because applications that use them can join or leave at any moment in time. Topics will remain in the system even when all the applications that introduce them disappear. They will disappear if the entire Domain is brought down.
If a Topic modifies one or more of its QoSPolicy values a new TopicBuiltinTopicData sample will be written.
Information published in the DCPSTopicTopic is critical to the data distribution service, therefore it cannot be disabled by means of the Domain/BuiltinTopics element in the configuration file. See below for information on how this can be done.
TopicBuiltinTopicData members table
The following table shows the information contained in the TopicBuiltinTopicData topic.
| Name | Type | Description |
|---|---|---|
| key | BuiltinTopicKey_t | Global unique identifier of the Topic |
| name | String | Name of the Topic |
| type_name | String | Type name of the Topic (i.e. the fully scoped IDL name) |
| durability | DurabilityQosPolicy | QosPolicy attached to the Topic |
| durability_service | DurabilityServiceQosPolicy | QosPolicy attached to the Topic |
| deadline | DeadlineQosPolicy | QosPolicy attached to the Topic |
| latency_budget | LatencyBudgetQosPolicy | QosPolicy attached to the Topic |
| liveliness | LivelinessQosPolicy | QosPolicy attached to the Topic |
| reliability | ReliabilityQosPolicy | QosPolicy attached to the Topic |
| transport_priority | TransportPriorityQosPolicy | QosPolicy attached to the Topic |
| lifespan | LifespanQosPolicy | QosPolicy attached to the Topic |
| destination_order | DestinationOrderQosPolicy | QosPolicy attached to the Topic |
| history | HistoryQosPolicy | QosPolicy attached to the Topic |
| resource_limits | ResourceLimitsQosPolicy | QosPolicy attached to the Topic |
| ownership | OwnershipQosPolicy | QosPolicy attached to the Topic |
| topic_data | TopicDataQosPolicy | QosPolicy attached to the Topic |
DCPSPublication
The DCPSPublication topic keeps track of the existance of data writers. It does this using the PublicationBuiltinTopicData datatype. Every PublicationBuiltinTopicData sample in a Domain is a representation of a DataWriter.
If you create a new DataWriter you create a new PublicationBuiltinTopicData instance. If you delete a DataWriter then the PublicationBuiltinTopicData instance is disposed. If a DataWriter (or the publisher to which it belongs) modifies a QoSPolicy that applies to the entities connected to it an updated PublicationBuiltinTopicData sample is written. The PublicationBuiltinTopicData is also updated when the writer looses or regains its liveliness.
When you invoke the get_matched_publication_data operation on the DataReader, you actually get the PublicationBuiltinTopicData samples that describe the Writers to which your DataReader has connected.
PublicationBuiltinTopicData Members Table
| Name | Type | Description |
|---|---|---|
| key | BuiltinTopicKey_t | Global unique identifier of the DataWriter |
| participant_key | BuiltinTopicKey_t | Global unique identifier of the Participant to which the DataWriter belongs |
| topic_name | String | Name of the Topic used by the DataWriter |
| type_name | String | Type name of the Topic used by the DataWriter |
| durability | DurabilityQosPolicy | QosPolicy attached to the DataWriter |
| deadline | DeadlineQosPolicy | QosPolicy attached to the DataWriter |
| latency_budget | LatencyBudgetQosPolicy | QosPolicy attached to the DataWriter |
| liveliness | LivelinessQosPolicy | QosPolicy attached to the DataWriter |
| reliability | ReliabilityQosPolicy | QosPolicy attached to the DataWriter |
| lifespan | LifespanQosPolicy | QosPolicy attached to the DataWriter |
| destination_order | DestinationOrderQosPolicy | QosPolicy attached to the DataWriter |
| user_data | UserDataQosPolicy | QosPolicy attached to the DataWriter |
| ownership | OwnershipQosPolicy | QosPolicy attached to the DataWriter |
| ownership_strength | OwnershipStrengthQosPolicy | QosPolicy attached to the DataWriter |
| presentation | PresentationQosPolicy | QosPolicy attached to the Publisher to which the DataWriter belongs |
| partition | PartitionQosPolicy | QosPolicy attached to the Publisher to which the DataWriter belongs |
| topic_data | TopicDataQosPolicy | QosPolicy attached to the Topic used by the DataWriter |
| group_data | GroupDataQosPolicy | QosPolicy attached to the Topic used by the DataWriter |
DCPSSubscription
The DCPSSubscription topic uses the SubscriptionBuiltinTopicData datatype to communicate the existence of datareaders. Each SubscriptionBuiltinTopicData sample in a Domain represents a datareader in that Domain.
1When a new DataReader is enabled a new SubscriptionBuiltinTopicData instance is created. When the DataReader is deleted then the SubscriptionBuiltinTopicData is disposed. If the DataReader (or the Subscriber to which it belongs) modifies a QoSPolicy that applies to the entries connected to it then the SubscriptionBuiltinTopicData sample is updated.
SubscriptionBuiltinTopicData Members Table
| Name | Type | Description |
|---|---|---|
| key | BuiltinTopicKey_t | Global unique identifier of the DataReader |
| participant_key | BuiltinTopicKey_t | Global unique identifier of the Participant to which the DataReader belongs |
| topic_name | String | Name of the Topic used by the DataReader |
| type_name | String | Type name of the Topic used by the DataReader |
| durability | DurabilityQosPolicy | QosPolicy attached to the DataReader |
| deadline | DeadlineQosPolicy | QosPolicy attached to the DataReader |
| latency_budget | LatencyBudgetQosPolicy | QosPolicy attached to the DataReader |
| liveliness | LivelinessQosPolicy | QosPolicy attached to the DataReader |
| reliability | ReliabilityQosPolicy | QosPolicy attached to the DataReader |
| ownership | LifespanQosPolicy | QosPolicy attached to the DataReader |
| destination_order | DestinationOrderQosPolicy | QosPolicy attached to the DataReader |
| user_data | UserDataQosPolicy | QosPolicy attached to the DataReader |
| time_based_filter | TimeBasedFilterQosPolicy | QosPolicy attached to the DataReader |
| presentation | PresentationQosPolicy | QosPolicy attached to the Subscriber to which the DataReader belongs |
| partition | PartitionQosPolicy | QosPolicy attached to the Subscriber to which the DataReader belongs |
| topic_data | TopicDataQosPolicy | QosPolicy attached to the Topic used by the DataReader |
| group_data | GroupDataQosPolicy | QosPolicy attached to the Subscriber to which the DataReader belongs |
How do I access the built-in topics?
Built-in topics get created when a DomainParticipant is initialized. They keep track of discovery information about other DDS participants, Topics, Data Readers and Data Writers.
The built-in Subscriber contains the corresponding DataReader objects. In Java5 get the built-in subscriber you can call the DomainParticipant’s get_builtin_subscriber() operation, which will provide you with a built-in Subscriber. In ISOCPP2, to get the built-in Subscriber you can pass a DomainParticipant to the dds::sub::builtin_subscriber(...) method.
Alternatively, to find the DataReaders without the built-in Subscriber, use the lookup_datareader(...) method in Java5, passing the name of the built-in topic as the parameter
Is there a built-in topics example?
There is a built-in topics example which you can find inside the OpenSplice distribution. It is in the examples/dcps/BuiltinTopics directory. The readme file will show you how to build and run the example. The example shows how built-in topics can be used to monitor the number of nodes participating in a domain.
Can I run without built-in topics?
There may be times when you want to disable the use of built-in topics, for example to reduce network load. Some features of OpenSplice may not work if you do this.
You can disable built-in topics in the xml configuration file by using the //OpenSplice/Domain/BuiltinTopics section. By default BuiltinTopics are enabled so they are not shown in the xml file.
<Domain>
….
<BuiltinTopics enabled=”true”/>
</Domain>
It is always best to edit the xml file using the OpenSplice configuration tool as this will check to see it the xml file is valid before saving it.
How to disable built-in topics using the osplconf tool
Start the opslconf tool using the command osplconf from a command prompt where the opensplice environment is configured. This will bring up the GUI.
Click File > Open and choose the xml file you are using
On the Domain tab right click where it says Domain and choose Add >BuiltinTopics
The Builtin Topics should appear at the bottom of the domain tab. It is enabled by default.
To change it to disabled click on it. You should see enabled value true in the right hand pane.
Click on the value and you will get a drop down list and you can choose false.
Save the file using File > Save.
See section 12.2.17 BuiltinTopics in the deployment guide for more information on this configuration option.
In general it is good to realize that discovery by means of builtin topics is part of the standard ddsi discovery, and so it only makes sense to turn this off when using the native networking service. The native network service does not depend necessarily on discovery by means of builtin topics in order establish successful communication.