The SampleInfo Structure

You are here:

The SampleInfo Structure

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.

DDS_SampleInfo Structure
Type	Field Name	Description
DDS_SampleStateKind	sample_state	See Sample States
DDS_ViewStateKind	view_state	See View States
DDS_InstanceStateKind	instance_state	See Instance States
DDS_Time_t	source_timestamp	Time stored by the DataWriter when the DDS sample was written.
DDS_InstanceHandle_t	instance_handle	Handle to the data-instance corresponding to the DDS sample.
DDS_InstanceHandle_t	publication_handle	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	disposed_generation_count	See Generation Counts and Ranks.
	no_writers_generation_count
	sample_rank
	generation_rank
	absolute_generation_rank
DDS_Boolean	valid_data	Indicates whether the DDS data sample includes valid data. See Valid Data Flag.
DDS_Time_t	reception_timestamp	Time stored when the DDS sample was committed by the DataReader. See Reception Timestamp.
DDS_SequenceNumber_t	publication_sequence_number	Publication sequence number assigned when the DDS sample was written by the DataWriter.
DDS_SequenceNumber_t	reception_sequence_number	Reception sequence number assigned when the DDS sample was committed by the DataReader. See Reception Timestamp.
struct DDS_GUID_t	original_publication_ virtual_guid	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	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	topic_query_guid	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	flag	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.

Reception Timestamp

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.

Sample States

For each DDS sample received, Connext DDS keeps a sample_state relative to each DataReader. The sample_state can be either:

READ: The DataReader has already accessed that DDS sample by means of read().
NOT_READ: The DataReader has never accessed that DDS sample before.

The DDS samples retrieved by a read() or take() need not all have the same sample_state.

View States

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:

NEW: Either this is the first time the DataReader has ever accessed DDS samples of the instance, or the DataReader has accessed previous DDS samples of the instance, but the instance has since been reborn (i.e. become not-alive and then alive again). These two cases are distinguished by examining the disposed_generation_count and the no_writers_generation_count (see Generation Counts and Ranks).
NOT_NEW:The DataReader has already accessed DDS samples of the same instance and the instance has not been reborn since.

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.

Instance States

As seen in Figure: Instance States , Connext DDS keeps an instance_state for each instance; it can be:

ALIVE: The following are all true: (a) DDS samples have been received for the instance, (b) there are live DataWriters writing the instance, and (c) the instance has not been explicitly disposed (or more DDS samples have been received after it was disposed).
NOT_ALIVE_DISPOSED: The instance was explicitly disposed by a DataWriter by means of the dispose() operation.
NOT_ALIVE_NO_WRITERS: The instance has been declared as not-alive by the DataReader because it has determined that there are no live DataWriter entities writing that instance.

The events that cause the instance_state to change can depend on the setting of the OWNERSHIP QosPolicy:

If OWNERSHIP QoS is set to EXCLUSIVE, the instance_state becomes NOT_ALIVE_DISPOSED only if the DataWriter that currently “owns” the instance explicitly disposes it. The instance_state will become ALIVE again only if the DataWriter that owns the instance writes it. Note that ownership of the instance is determined by a combination of the OWNERSHIP and OWNERSHIP_STRENGTH QosPolicies. Ownership of an instance can dynamically change.
If OWNERSHIP QoS is set to SHARED, the instance_state becomes NOT_ALIVE_DISPOSED if any DataWriter explicitly disposes the instance. The instance_state becomes ALIVE as soon as any DataWriter writes the instance again.

Figure: Instance States

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

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):

disposed_generation_count: Counts how many times the instance_state of the corresponding instance changes from NOT_ALIVE_DISPOSED to ALIVE. The counter is reset when the instance resource is reclaimed.
no_writers_generation_count: Counts how many times the instance_state of the corresponding instance changes from NOT_ALIVE_NO_WRITERS to ALIVE. The counter is reset when the instance resource is reclaimed.

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():

sample_rank: Indicates how many DDS samples of the same instance follow the current one in the sequence. The DDS samples are always time-ordered, thus the newest DDS sample of an instance will have a sample_rank of 0. Depending on what you have configured read() and take() to return, a sample_rank of 0 may or may not be the newest DDS sample that was ever received. It is just the newest DDS sample in the sequence that was returned.
generation_rank: Indicates the difference in ‘generations’ between the DDS sample and the newest DDS sample of the same instance as returned in the sequence. If a DDS sample belongs to the same generation as the newest DDS sample in the sequence returned by read() and take(), then generation_rank will be 0.
absolute_generation_rank: Indicates the difference in ‘generations’ between the DDS sample and the newest DDS sample of the same instance ever received by the DataReader. Recall that the data sequence returned by read() and take() may not contain all of the data in the DataReader’s receive queue. Thus, a DDS sample that belongs to the newest generation of the instance will have an absolute_generation_rank of 0.

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:

A DDS sample with sample_rank = 0 is the newest DDS sample of the instance in the returned sequence.
DDS samples that belong to the same generation will have the same generation_rank (as well as absolute_generation_rank).
DDS samples with absolute_generation_rank = 0 belong to the newest generation for the instance received by the DataReader.

Valid Data Flag

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.