When you invoke the read/take operations, for every DDS data sample that is returned, a corresponding SampleInfo is also returned. SampleInfo structures provide you with additional information about the DDS data samples received by Connext DDS.
DDS_SampleInfo Structure shows the format of the SampleInfo structure.
Type |
Field Name |
Description |
DDS_SampleStateKind |
See Sample States |
|
DDS_ViewStateKind |
See View States |
|
DDS_InstanceStateKind |
See Instance States |
|
DDS_Time_t |
Time stored by the DataWriter when the DDS sample was written. |
|
DDS_InstanceHandle_t |
Handle to the data-instance corresponding to the DDS sample. |
|
DDS_InstanceHandle_t |
Local handle to the DataWriter that modified the instance. This is the same instance handle returned by get_matched_publications(). You can use this handle when calling get_matched_publication_data(). |
|
DDS_Long |
||
DDS_Boolean |
Indicates whether the DDS data sample includes valid data. See Valid Data Flag. |
|
DDS_Time_t |
Time stored when the DDS sample was committed by the DataReader. See Reception Timestamp. |
|
DDS_SequenceNumber_t |
Publication sequence number assigned when the DDS sample was written by the DataWriter. |
|
DDS_SequenceNumber_t |
Reception sequence number assigned when the DDS sample was committed by the DataReader. See Reception Timestamp. |
|
struct DDS_GUID_t |
Original publication virtual GUID. If the Publisher’s access_scope is GROUP, this field contains the Publisher virtual GUID that uniquely identifies the DataWriter group. |
|
struct DDS_SequenceNumber_t |
Original publication virtual sequence number. If the Publisher’s access_scope is GROUP, this field contains the Publisher virtual sequence number that uniquely identifies a DDS sample within the DataWriter group. |
|
DDS_GUID_t |
The GUID of the DDS_TopicQuery that is related to the sample. This GUID indicates whether a sample is part of the response to a DDS_TopicQuery or a regular ("live") sample: If the sample was written for the TopicQuery stream, this field contains the GUID of the target TopicQuery. If the sample was written for the live stream, this field will be set to DDS_GUID_UNKNOWN. |
|
DDS_Long |
Flags associated with the DDS sample; set by using the flag field in DDS_WriteParams_t when writing a DDS sample with FooDataWriter_write_w_params() (see Writing Data). RTI reserves least-significant bits [0-7] for middleware-specific usage. The application can use least significant bits [8-15]. The first bit, REDELIVERED_SAMPLE, is reserved to mark a DDS sample as redelivered when using RTI Queuing Service. The second bit, INTERMEDIATE_REPLY_SEQUENCE_SAMPLE, is used to indicate that a response DDS sample is not the last response DDS sample for a given request. This bit is usually set by Connext DDS Repliers sending multiple responses for a request. The third bit, REPLICATE_SAMPLE, indicates if a sample must be broadcast by one Queuing Service replica to other replicas. The fourth bit, LAST_SHARED_READER_QUEUE_SAMPLE, indicates that a sample is the last sample in a SharedReaderQueue for a QueueConsumer DataReader. The fifth bit, INTERMEDIATE_TOPIC_QUERY_SAMPLE, indicates that a sample for a TopicQuery will be followed by more samples. This flag only applies to samples that have been published as a response to a TopicQuery. When this bit is not set and topic_query_guid is different from GUID_UNKNOWN, this sample is the last sample for that TopicQuery coming from the DataWriter identified by original_publication_virtual_guid. |
|
struct DDS_GUID_t |
source_guid |
The application logical data source associated with the sample. |
struct DDS_GUID_t |
related_source_guid |
The application logical data source that is related to the sample. |
struct DDS_GUID_t |
related_subscription_guid |
The related_reader_guid associated with the sample. |
In reliable communication, if DDS data samples are received out received of order, Connext DDS will not deliver them until all the previous DDS data samples have been received. For example, if DDS sample 2 arrives before DDS sample 1, DDS sample 2 cannot be delivered until DDS sample 1 is received. The reception_timestamp is the time when all previous DDS samples has been received—the time at which the DDS sample is committed. If DDS samples are all received in order, the committed time will be same as reception time. However, if DDS samples are lost on the wire, then the committed time will be later than the initial reception time.
For each DDS sample received, Connext DDS keeps a sample_state relative to each DataReader. The sample_state can be either:
The DDS samples retrieved by a read() or take() need not all have the same sample_state.
For each instance (identified by a unique key value), Connext DDS keeps a view_state relative to each DataReader. The view_state can be either:
The view_state in the SampleInfo structure is really a per-instance concept (as opposed to the sample_state which is per DDS sample). Thus all DDS data samples related to the same instance that are returned by read() or take() will have the same value for view_state.
As seen in Figure 20, Connext DDS keeps an instance_state for each instance; it can be:
The events that cause the instance_state to change can depend on the setting of the OWNERSHIP QosPolicy:
Since the instance_state in the SampleInfo structure is a per-instance concept, all DDS data samples related to the same instance that are returned by read() or take() will have the same value for instance_state.
Generation counts and ranks allow your application to distinguish DDS samples belonging to different ‘generations’ of the instance. It is possible for an instance to become alive, be disposed and become not-alive, and then to cycle again from alive to not-alive states during the operation of an application. Each time an instance becomes alive defines a new generation for the instance.
It is possible that an instance may cycle through alive and not-alive states multiple times before the application accesses the DDS data samples for the instance. This means that the DDS data samples returned by read() and take() may cross generations. That is, some DDS samples were published when the instance was alive in one generation and other DDS samples were published when the instance transitioned through the non-alive state into the alive state again. It may be important to your application to distinguish the DDS data samples by the generation in which they were published.
Each DataReader keeps two counters for each new instance it detects (recall that instances are distinguished by their key values):
The disposed_generation_count and no_writers_generation_count fields in the SampleInfo structure capture a snapshot of the corresponding counters at the time the corresponding DDS sample was received.
The sample_rank and generation_rank in the SampleInfo structure are computed relative to the sequence of DDS samples returned by read() or take():
Like the ‘generation count’ values, the ‘rank’ values are also reset to 0 if the instance resource is reclaimed.
By using the sample_rank, generation_rank and absolute_generation_rank information in the SampleInfo structure, your application can determine exactly what happened to the instance and thus make appropriate decisions of what to do with the DDS data samples received for the instance. For example:
The SampleInfo structure’s valid_data flag indicates whether the DDS sample contains data or is only used to communicate a change in the instance_state of the instance.
Normally, each DDS sample contains both a SampleInfo structure and some data. However, there are situations in which the DDS sample only contains the SampleInfo and does not have any associated data. This occurs when Connext DDS notifies the application of a change of state for an instance that was caused by some internal mechanism (such as a timeout) for which there is no associated data. An example is whenConnext DDS detects that an instance has no writers and changes the corresponding instance_state to NOT_ALIVE_NO_WRITERS.
If this flag is TRUE, then the DDS sample contains valid Data. If the flag is FALSE, the DDS Sample contains no data.
To ensure correctness and portability, your application must check the valid_data flag prior to accessing the data associated with the DDS sample, and only access the data if it is TRUE.
© 2017 RTI