Implements DDS communication using RTI DDS. More...
#include <ddsSubscriber.hpp>
Public Member Functions | |
| DdsSubscriber (const DdsParams ¶ms) | |
| Constructs a DDS subscriber from given configuration parameters. More... | |
| virtual | ~DdsSubscriber () noexcept |
| Destroys the DDS subscriber and releases all RTI DDS resources. More... | |
| DdsSubscriber (DdsSubscriber &&rhs)=default | |
| DdsSubscriber & | operator= (DdsSubscriber &&rhs)=default |
| std::error_code | TakeSamples (std::vector< std::vector< const rtctk::AgnosticTopic * >> &samples, std::chrono::nanoseconds timeout) const noexcept override |
| Retrieves the buffers for the next data samples received from DDS. More... | |
| std::error_code | ReturnSamples (const std::vector< const rtctk::AgnosticTopic * > &samples) const noexcept override |
| Releases buffers for previously retrieved data samples. More... | |
| size_t | GetNumberOfTopics () const noexcept override |
| Returns the number of configured topics. More... | |
| const std::string & | GetTopicName (size_t index) const noexcept override |
| Returns a string containing the name of a configured topic. More... | |
 Public Member Functions inherited from rtctk::telSub::DdsSubscriberIf | |
| DdsSubscriberIf () | |
| virtual | ~DdsSubscriberIf () noexcept |
Detailed Description
Implements DDS communication using RTI DDS.
Constructor & Destructor Documentation
◆ DdsSubscriber() [1/2]
| rtctk::telSub::DdsSubscriber::DdsSubscriber | ( | const DdsParams & | params | ) |
Constructs a DDS subscriber from given configuration parameters.
The constructor will initialise the DDS subsystem and allocate necessary resources by constructing appropriate RTI DDS objects, such as the domain participant and RTI DDS subscriber. Individual DDS topic objects and DDS readers are created for each topic found in the params.m_topics vector.
There is a one to one correspondence between the topic in params.m_topics and the DDS reader and DDS topic object created. The order of the topics matters and is preserved, meaning that the n'th topic in params.m_topics will equal GetTopicName(n) after successful construction. In addition, the TakeSamples method will return DDS samples for the n'th DDS reader in its output parameter samples[n], which also corresponds to the configured topic GetTopicName(n).
- Parameters
-
params The structure containing all needed parameters to construct the DDS objects.
- Postcondition
- GetNumberOfTopics() == params.m_topics.size(), i.e. the number of topics and corresponding DDS readers created will match the topic names passed in as configuration parameters.
◆ ~DdsSubscriber()
|
virtualnoexcept |
Destroys the DDS subscriber and releases all RTI DDS resources.
The destructor will release all resources associate with this subscriber object that were allocated by RTI DDS. This is done by deleting all RTI DDS object that were created and then calling the finalize_instance() method to shutdown the RTI DDS subsystem. Errors during this procedure cannot be propagated as exceptions, therefore the errors will simply be logged and execution allowed to continue.
◆ DdsSubscriber() [2/2]
|
default |
Member Function Documentation
◆ GetNumberOfTopics()
|
overridevirtualnoexcept |
Returns the number of configured topics.
This returns the number of topics that were configured during construction of the subscriber object. This corresponds to the size of the DdsParams::m_topics vector passed to the constructor.
- Returns
- The number of configured topics.
Implements rtctk::telSub::DdsSubscriberIf.
◆ GetTopicName()
|
overridevirtualnoexcept |
Returns a string containing the name of a configured topic.
This returns the name of a configured DDS topic as a string. The topic name is associated with the index'th DDS reader and will also identify the topic for samples[index], which is the output parameter vector filled by TakeSamples containing newly arrived DDS samples for the index'th DDS reader.
- Parameters
-
[in] index This selects which topic name to fetch. The value must be in the range 0 <= index and index < GetNumberOfTopics().
- Returns
- The index'th topic name.
Implements rtctk::telSub::DdsSubscriberIf.
◆ operator=()
|
default |
◆ ReturnSamples()
|
overridevirtualnoexcept |
Releases buffers for previously retrieved data samples.
This method must be called to release any internal resources allocated, that are associated with the samples previously returned by a call to TakeSamples. It is allowed to call this method on subsets of the AgnosticTopic pointers returned by TakeSamples over multiple invocations. In the extreme case one can call ReturnSamples on individual AgnosticTopic pointers. However, it will be more efficient to batch the calls as much as possible.
An empty / zero error code is returned if the resources were successfully released. Otherwise an appropriate error code is returned if the resources could not be released.
- Parameters
-
[in] samples Contains a vector of AgnosticTopic pointers previously returned by a call to TakeSamples.
- Returns
- An error code indicating the success or failure of the operation.
The following is a list of possible error codes returned:
0- Resources were successfully released.
std::errc::protocol_error- A call to the RTI DDS API failed.
std::errc::bad_address- Could not find associated resourced for a sample given in the
samplesvector.
Implements rtctk::telSub::DdsSubscriberIf.
◆ TakeSamples()
|
overridevirtualnoexcept |
Retrieves the buffers for the next data samples received from DDS.
The method waits for new DDS samples to become available on one or more of the DDS topic readers. For any samples received the output samples parameter structure is filled with pointers to the AgnosticTopic structures received from DDS. An empty / zero error code is returned if the operation completed successfully, meaning at least on sample for any DDS topic reader has been received. If no samples were available within the timeout period then a std::errc::timed_out error code is returned. If some other error occurred, an appropriate error code is returned.
- Parameters
-
[out] samples This should be a vector of vectors prepared by the caller that will be filled with AgnosticTopic pointers corresponding to samples received from DDS. The first dimension of the double vector structure corresponds to the configured DDS topics, i.e. samples[n] will contain all the samples received for the n'th topic and n'th reader. Individual topic names can be fetched with GetTopicName. It is possible that no samples were received for a particular topic, e.g. samples[i], in which case the vector will be empty, i.e. samples[i].empty() == true. [in] timeout The maximum amount of time to wait for this operation to complete, measured in nanoseconds.
- Returns
- An error code indicating success, failure or timeout of the operation.
The following is the list of possible error codes returned:
0- At least one samples was successfully returned.
std::errc::timed_out- The operation timed out while waiting for DDS samples.
std::errc::protocol_error- A call to the RTI DDS API failed.
std::errc::bad_address- Could not identify the associated topic reader for a sample.
- Precondition
samples.size()== GetNumberOfTopics().
- Note
- All AgnosticTopic pointers received by the caller in
samplesmust eventually be returned with a call to ReturnSamples to release the underlying RTI DDS buffers.
Implements rtctk::telSub::DdsSubscriberIf.
The documentation for this class was generated from the following files:
- reusableComponents/telSub/library/src/include/rtctk/telSub/ddsSubscriber.hpp
- reusableComponents/telSub/library/src/ddsSubscriber.cpp
