RTI Connext C API  Version 5.3.1
 All Data Structures Functions Variables Typedefs Enumerations Enumerator Groups Pages
Subscription Module

Contains the DDS_Subscriber, DDS_DataReader, DDS_ReadCondition, DDS_QueryCondition, and DDS_TopicQuery classes, as well as the DDS_SubscriberListener and DDS_DataReaderListener interfaces, and more generally, all that is needed on the subscription side. More...

Modules

 Subscribers
 DDS_Subscriber entity and associated elements
 
 DataReaders
 DDS_DataReader entity and associated elements
 
 Data Samples
 DDS_SampleInfo, DDS_SampleStateKind, DDS_ViewStateKind, DDS_InstanceStateKind and associated elements
 

Detailed Description

Contains the DDS_Subscriber, DDS_DataReader, DDS_ReadCondition, DDS_QueryCondition, and DDS_TopicQuery classes, as well as the DDS_SubscriberListener and DDS_DataReaderListener interfaces, and more generally, all that is needed on the subscription side.

DDSSubscriptionPackage.png
DCPS Subscription package

Access to data samples

Data is made available to the application by the following operations on DDS_DataReader objects: FooDataReader_read, FooDataReader_read_w_condition, FooDataReader_take, FooDataReader_take_w_condition, and the other variants of read() and take().

The general semantics of the read() operation is that the application only gets access to the corresponding data (i.e. a precise instance value); the data remains the responsibility of RTI Connext and can be read again.

The semantics of the take() operations is that the application takes full responsibility for the data; that data will no longer be available locally to RTI Connext. Consequently, it is possible to access the same information multiple times only if all previous accesses were read() operations, not take().

Each of these operations returns a collection of Data values and associated DDS_SampleInfo objects. Each data value represents an atom of data information (i.e., a value for one instance). This collection may contain samples related to the same or different instances (identified by the key). Multiple samples can refer to the same instance if the settings of the HISTORY QoS allow for it.

These operations reset the read communication statuses; see Changes in read communication status.

To return the memory back to the middleware, every read() or take() that retrieves a sequence of samples must be followed with a call to FooDataReader_return_loan.

See Also
Interpretation of the SampleInfo

Data access patterns

The application accesses data by means of the operations read or take on the DDS_DataReader. These operations return an ordered collection of DataSamples consisting of a DDS_SampleInfo part and a Data part.

The way RTI Connext builds the collection depends on QoS policies set on the DDS_DataReader and DDS_Subscriber, as well as the source_timestamp of the samples, and the parameters passed to the read() / take() operations, namely:

The read() and take() operations are non-blocking and just deliver what is currently available that matches the specified states.

The read_w_condition() and take_w_condition() operations take a DDS_ReadCondition object as a parameter instead of sample, view or instance states. The behaviour is that the samples returned will only be those for which the condition is DDS_BOOLEAN_TRUE. These operations, in conjunction with DDS_ReadCondition objects and a DDS_WaitSet, allow performing waiting reads.

Once the data samples are available to the data readers, they can be read or taken by the application. The basic rule is that the application may do this in any order it wishes. This approach is very flexible and allows the application ultimate control.

To access data coherently, or in order, the PRESENTATION QoS must be set properly.


RTI Connext C API Version 5.3.1 Copyright © Mon Feb 19 2018 Real-Time Innovations, Inc