|
RTI Connext C API
Version 6.1.1
|
<<experimental>> <<extension>> Utility to concurrently read and process the data samples received by DDS_DataReader. More...
Data Structures | |
| struct | DDS_SampleHandler |
| <<experimental>> <<extension>> <<interface>> Handler called by a sample dispatcher, such as DDS_SampleProcessor. More... | |
Macros | |
| #define | DDS_SampleHandler_INITIALIZER |
| <<experimental>> <<extension>> Initializer for new DDS_SampleHandler. More... | |
Typedefs | |
| typedef struct DDS_SampleProcessorImpl | DDS_SampleProcessor |
| <<extension>> <<interface>> A class for reading the samples in DDS_DataReader's cache concurrently. This class allows associating a DDS_SampleHandler with a DDS_DataReader and notify it for each sample individually. More... | |
<<experimental>> <<extension>> Utility to concurrently read and process the data samples received by DDS_DataReader.
| #define DDS_SampleHandler_INITIALIZER |
<<experimental>> <<extension>> Initializer for new DDS_SampleHandler.
No memory is allocated. New DDS_SampleHandler instances stored in the stack should be initialized with this value before they are passed to any functions.
| typedef struct DDS_SampleProcessorImpl DDS_SampleProcessor |
<<extension>> <<interface>> A class for reading the samples in DDS_DataReader's cache concurrently. This class allows associating a DDS_SampleHandler with a DDS_DataReader and notify it for each sample individually.
A DDS_SampleProcessor relies on an underlying DDS_AsyncWaitSet to read and dispatch the data from the DataReaders. It internally creates a DDS_ReadCondition for each attached DataReader, an associates a custom handler that contains state to read samples and notify the corresponding handler.
The SampleProcessor uses this ReadCondition to wait for data and then calls FooDataReader_take_w_condition to take all the available data.
Notifications to any handler may be concurrent if the thread pool size set in DDS_AsyncWaitSetProperty_t::thread_pool_size is greater than 1. The same or different handlers may be called in parallel. The SampleProcessor cycles through all attached DataReaders dispatching a sample at a time with the next available thread. This mechanism guarantees concurrent dispatching of the samples accross all DataReaders.
The DDS_SampleProcessor internally creates and uses a DDS_ReadCondition for each attached DDS_DataReader to read the data. It's recommended to perform all the reading of the DDS_DataReader's samples through the DDS_SampleProcessor and avoid reading with through other mechanisms in different part of your applications. Similarly, your application must be careful to not modify the DDS_ReadCondition associated with an attached DDS_DataReader.
In general, avoid or beware of using the following operations in combination with a DDS_SampleProcessor:
On the other hand, you can externally provide the underlying DDS_SampleProcessor's DDS_AsyncWaitSet if you want to access additional capabilities of the DDS_AsyncWaitSet and use it to attach other DDS_Condition to handle other aspects of your application.
Similar to the DDS_AsyncWaitSet, the DDS_SampleProcessor provides a thread-safe interface. All the operations of this class can be called concurrently from multiple threads.
Because the DDS_SampleProcessor relies on an DDS_AsyncWaitSet to dispatch the samples the same threading concepts apply. This means that operations on a DDS_SampleProcessor may require synchronizing with the thread pool for safety. DDS_SampleProcessor also relies on the asynchrnous completion pattern to effectively interact with the underlying thread pool.
For instance to detach a DDS_DataReader, the DDS_SampleProcessor generates an internal request to its thread pool to process it. As soon as the detachment completes, the thread pool provides the notification through an associated completion token on which the DDS_SampleProcessor waits and blocks until it completes.
Due to the concurrent processing nature of operations on a DDS_SampleProcessor as well as the sample handling, it's important to keep in mind the following aspects:
The handler operation can be called concurrently for each sample. Therefore, handler implementations may need to apply thread synchronization strategies to protect shared resources.
Note that the interface of the DDS_SampleProcessor is similar to that of the DDS_AsyncWaitSet but reduced and simplified. As noted above, if more advanced use and control of the thread pool is required, you can always create the DDS_AsyncWaitSet externally when calling DDS_SampleProcessor_new_with_aws.
| DDS_ReturnCode_t DDS_SampleProcessor_attach_reader | ( | DDS_SampleProcessor * | self, |
| DDS_DataReader * | reader, | ||
| const struct DDS_SampleHandler * | handler | ||
| ) |
Attaches the specified DDS_DataReader with an associated sample handler to this DDS_SampleProcessor.
This operation will block until the attach request completes. Upon successful return, it is guaranteed that the specified DDS_DataReader is attached and notifications to the handler may occur.
If this operation is called multiple times for an already attached DDS_DataReader, it will result in no-op and return sucessfully, ignoring the specified handler. So if the handler is different, it will not be updated.
| self | <<in>> Cannot be NULL. |
| reader | <<in>> DDS_DataReader to be attached. |
| handler | <<in>> handler to be notified on dispatching of the reader samples. |
| DDS_ReturnCode_t DDS_SampleProcessor_detach_reader | ( | DDS_SampleProcessor * | self, |
| DDS_DataReader * | reader | ||
| ) |
Detaches the specified DDS_DataReader from this DDS_SampleProcessor.
Once the DDS_DataReader is detached, it is guaranteed that the DDS_SampleProcessor will no longer process it so it is safe for your application to release any resources associated with the detached DDS_DataReader.
This operation blocks until the detach request completes. Upon successful return, it is guaranteed that the specified DDS_DataReader is detached.
DDS_DataReader may be detached at any time independently of the state of the DDS_SampleProcessor.
| self | <<in>> Cannot be NULL. |
| reader | <<in>> DDS_DataReader to be detached. |
| DDS_ReturnCode_t DDS_SampleProcessor_lookup_sample_handler | ( | DDS_SampleProcessor * | self, |
| struct DDS_SampleHandler * | handler_out, | ||
| DDS_DataReader * | reader | ||
| ) |
Finds the associated DDS_SampleHandler of the specified attached DDS_DataReader.
The operation will fail with DDS_RETCODE_PRECONDITION_NOT_MET. if the specified reader is not currently attached.
| self | <<in>> Cannot be NULL. |
| handler_out | <<inout>> a DDS_SampleHandler object that contains the found associated handler. |
| reader | DDS_DataReader The attached reader for which the associated DDS_SampleHandler is retrieved. |
| DDS_ReturnCode_t DDS_SampleProcessor_get_datareaders | ( | DDS_SampleProcessor * | self, |
| struct DDS_DataReaderSeq * | attached_readers | ||
| ) |
Retrieves the list of attached DDS_DataReader (s).
| self | <<in>> Cannot be NULL. |
| attached_readers | <<inout>> a DDS_DataReaderSeq object where the list of attached readers will be returned. |
| DDS_ReturnCode_t DDS_SampleProcessor_delete | ( | DDS_SampleProcessor * | self | ) |
Deletes a DDS_SampleProcessor.
This will delete the underlying DDS_AsyncWaitSet only if it owns it. That is, if the DDS_AsyncWaitSet was not provided externally.
The deletion will fail if there are outstanding DDS_AsyncWaitSetCompletionToken that have not been deleted.
Any outstanding DDS_SampleProcessor must be deleted before finalizing the DDS_DomainParticipantFactory. Otherwise undefined behavior may occur.
| self | <<in>> Cannot be NULL. |
| DDS_SampleProcessor* DDS_SampleProcessor_new | ( | const struct DDS_AsyncWaitSetProperty_t * | aws_property | ) |
Single-argument constructor that allows creating a a DDS_SampleProcessor with the configuration of the underlying DDS_AsyncWaitSet.
You can provide DDS_ASYNC_WAITSET_PROPERTY_DEFAULT as property to create the underlying DDS_AsyncWaitSet with default behavior.
This constructor creates DDS_AsyncWaitSet with no listener installed and will call DDS_AsyncWaitSet_start rigt after its creation.
| aws_property | <<in>> configuraiton of the underlying DDS_AsyncWaitSet. |
| DDS_SampleProcessor* DDS_SampleProcessor_new_with_aws | ( | DDS_AsyncWaitSet * | aws | ) |
Constructor that allows specifying an externally created DDS_AsyncWaitSet.
Creates a new DDS_SampleProcessor with the specified DDS_AsyncWaitSet.
Tnis constructor flavor decouples the lifecycle of the DDS_SampleProcessor from the DDS_AsyncWaitSet. It allows the application to have more control on the DDS_AsyncWaitSet, such as to install an DDS_AsyncWaitSetListener, a custom DDS_ThreadFactory, and controlling when it starts or stops.
Note that this constructor will not call DDS_AsyncWaitSet_start, so it's the caller responsiblity to start and stop it. You can provide the external DDS_AsyncWaitSet_start in either started or stopped state.
| aws | <<in>> the externally created DDS_AsyncWaitSet. |