DDS Samples, Instances, and Keys

The value of data associated with a Topic can change over time. The different values of the Topic passed between applications are called DDS samples. In our stock-price example, DDS samples show the price of a stock at a certain point in time. So each DDS sample may show a different price.

For a data type, you can select one or more fields within the data type to form a key. A key is something that can be used to uniquely identify one instance of a Topic from another instance of the same Topic. Think of a key as a way to sub-categorize or group related data values for the same Topic. Note that not all data types are defined to have keys, and thus, not all topics have keys. For topics without keys, there is only a single instance of that topic.

However, for Topics with keys, a unique value for the key identifies a unique instance of the Topic. DDS samples are then updates to particular instances of a Topic. Applications can subscribe to a Topic and receive DDS samples for many different instances. Applications can publish DDS samples of one, all, or any number of instances of a Topic. Many quality of service parameters actually apply on a per instance basis. Keys are also useful for subscribing to a group of related data streams (instances) without pre-knowledge of which data streams (instances) exist at runtime.

For example, let’s change the StockPrice data type to include the symbol of the stock. Then instead of having a Topic for every stock, which would result in hundreds or thousands of Topics and related DataWriters and DataReaders, each application would only have to publish or subscribe to a single Topic, say “StockPrices.” Successive values of a stock would be presented as successive DDS samples of an instance of “StockPrices”, with each instance corresponding to a single stock symbol.

Data Type: StockPrice

struct StockPrice {
    float price;
    Time  timeStamp;
   @key char  *symbol;

Instance 1 = (Topic: “StockPrices”) + (Key: “MSFT”)

sample a, price = $28.00

sample b, price = $27.88

Instance 2 = (Topic: “StockPrices”) + (Key: “IBM”)

sample a, price = $74.02

sample b, price = $73.50


Just by subscribing to “StockPrices,” an application can get values for all of the stocks through a single topic. In addition, the application does not have to subscribe explicitly to any particular stock, so that if a new stock is added, the application will immediately start receiving values for that stock as well.

To summarize, the unique values of data being passed using DCPS are called DDS samples. A DDS sample is a combination of a Topic (distinguished by a Topic name), an instance (distinguished by a key), and the actual user data of a certain data type. As seen in Figure: Relationship of Topics, Keys, and Instances, a Topic identifies data of a single type, ranging from one single instance to a whole collection of instances of that given topic for keyed data types. For more information, see Data Types and DDS Data Samples and Working with Topics.

Figure: Relationship of Topics, Keys, and Instances

By using keys, a Topic can identify a collection of data-object instances.

© 2018 RTI