Preview: Steps to Receiving Data

There are three ways to receive data:

• Your application can explicitly check for new data by calling a DataReader’s read() or take() operation. This method is also known as polling for data.
• Your application can be notified asynchronously whenever new DDS data samples arrive—this is done with a Listener on either the Subscriber or the DataReader. Connext DDS will invoke the Listener’s callback routine when there is new data. Within the callback routine, user code can access the data by calling read() or take() on the DataReader. This method is the way for your application to receive data with the least amount of latency.
• Your application can wait for new data by using Conditions and a WaitSet, then calling wait(). Connext DDS will block your application’s thread until the criteria (such as the arrival of DDS samples, or a specific status) set in the Condition becomes true. Then your application resumes and can access the data with read() or take().

The DataReader’s read() operation gives your application a copy of the data and leaves the data in the DataReader’s receive queue. The DataReader’s take() operation removes data from the receive queue before giving it to your application.

See Using DataReaders to Access Data (Read & Take) for details on using DataReaders to access received data.

See Conditions and WaitSets for details on using Conditions and WaitSets.

To prepare to receive data, create and configure the required Entities:

1. Create a DomainParticipant.
2. Register user data types1Type registration is not required for built-in types (see See "Registering Built-in Types"). with the DomainParticipant. For example, the ‘FooDataType’.
3. Use the DomainParticipant to create a Topic with the registered data type.
4. Optionally2You are not required to explicitly create a Subscriber; instead, you can use the 'implicit Subscriber' created from the DomainParticipant. See See "Creating Subscribers Explicitly vs. Implicitly". , use the DomainParticipant to create a Subscriber.
5. Use the Subscriber or DomainParticipant to create a DataReader for the Topic.
6. Use a type-safe method to cast the generic DataReader created by the Subscriber to a type-specific DataReader. For example, ‘FooDataReader’.

Then use one of the following mechanisms to receive data.

• To receive DDS data samples by polling for new data:
  • Using a FooDataReader, use the read() or take() operations to access the DDS data samples that have been received and stored for the DataReader. These operations can be invoked at any time, even if the receive queue is empty.
• To receive DDS data samples asynchronously:
  • Install a Listener on the DataReader or Subscriber that will be called back by an internal Connext DDS thread when new DDS data samples arrive for the DataReader.

1. Create a DDSDataReaderListener for the FooDataReader or a DDSSubscriberListener for Subscriber. In C++, C++/CLI, C# and Java, you must derive your own Listener class from those base classes. In C, you must create the individual functions and store them in a structure.

If you created a DDSDataReaderListener with the on_data_available() callback enabled: on_data_available() will be called when new data arrives for that DataReader.

If you created a DDSSubscriberListener with the on_data_on_readers() callback enabled: on_data_on_readers() will be called when data arrives for any DataReader created by the Subscriber.

2. Install the Listener on either the FooDataReader or Subscriber.

For the DataReader, the Listener should be installed to handle changes in the DATA_AVAILABLE status.

For the Subscriber, the Listener should be installed to handle changes in the DATA_ON_READERS status.

3. Only 1 Listener will be called back when new data arrives for a DataReader.

Connext DDS will call the Subscriber’s Listener if it is installed. Otherwise, the DataReader’s Listener is called if it is installed. That is, the on_data_on_readers() operation takes precedence over the on_data_available() operation.

If neither Listeners are installed or neither Listeners are enabled to handle their respective statuses, then Connext DDS will not call any user functions when new data arrives for the DataReader.

4. In the on_data_available() method of the DDSDataReaderListener, invoke read() or take() on the FooDataReader to access the data.

If the on_data_on_readers() method of the DDSSubscriberListener is called, the code can invoke read() or take() directly on the Subscriber’s DataReaders that have received new data. Alternatively, the code can invoke the Subscriber’s notify_datareaders() operation. This will in turn call the on_data_available() methods of the DataReaderListeners (if installed and enabled) for each of the DataReaders that have received new DDS data samples.

To wait (block) until DDS data samples arrive:

1. Use the DataReader to create a ReadCondition that describes the DDS samples for which you want to wait. For example, you can specify that you want to wait for never-before-seen DDS samples from DataReaders that are still considered to be ‘alive.’

Alternatively, you can create a StatusCondition that specifies you want to wait for the ON_DATA_AVAILABLE status.

2. Create a WaitSet.
3. Attach the ReadCondition or StatusCondition to the WaitSet.
4. Call the WaitSet’s wait() operation, specifying how long you are willing to wait for the desired DDS samples. When wait() returns, it will indicate that it timed out, or that the attached Condition become true (and therefore the desired DDS samples are available).
5. Using a FooDataReader, use the read() or take() operations to access the DDS data samples that have been received and stored for the DataReader.

© 2015 RTI