RTI Connext C API  Version 5.1.0
Data Fields
DDS_SampleInfo Struct Reference
Data Samples

Information that accompanies each sample that is read or taken. More...

Data Fields

DDS_SampleStateKind sample_state
 The sample state of the sample.
 
DDS_ViewStateKind view_state
 The view state of the instance.
 
DDS_InstanceStateKind instance_state
 The instance state of the instance.
 
struct DDS_Time_t source_timestamp
 The timestamp when the sample was written by a DataWriter.
 
DDS_InstanceHandle_t instance_handle
 Identifies locally the corresponding instance.
 
DDS_InstanceHandle_t publication_handle
 Identifies locally the DataWriter that modified the instance.
 
DDS_Long disposed_generation_count
 The disposed generation count of the instance at the time of sample reception.
 
DDS_Long no_writers_generation_count
 The no writers generation count of the instance at the time of sample reception.
 
DDS_Long sample_rank
 The sample rank of the sample.
 
DDS_Long generation_rank
 The generation rank of the sample.
 
DDS_Long absolute_generation_rank
 The absolute generation rank of the sample.
 
DDS_Boolean valid_data
 Indicates whether the DataSample contains data or else it is only used to communicate a change in the instance_state of the instance.
 
struct DDS_Time_t reception_timestamp
 <<eXtension>> The timestamp when the sample was committed by a DataReader.
 
struct DDS_SequenceNumber_t publication_sequence_number
 <<eXtension>> The publication sequence number.
 
struct DDS_SequenceNumber_t reception_sequence_number
 <<eXtension>> The reception sequence number when sample was committed by a DataReader
 
struct DDS_GUID_t original_publication_virtual_guid
 <<eXtension>> The original publication virtual GUID.
 
struct DDS_SequenceNumber_t original_publication_virtual_sequence_number
 <<eXtension>> The original publication virtual sequence number.
 
struct DDS_GUID_t related_original_publication_virtual_guid
 <<eXtension>> The original publication virtual GUID of a related sample
 
struct DDS_SequenceNumber_t related_original_publication_virtual_sequence_number
 <<eXtension>> The original publication virtual sequence number of a related sample
 

Detailed Description

Information that accompanies each sample that is read or taken.

Interpretation of the SampleInfo

The DDS_SampleInfo contains information pertaining to the associated Data instance sample including:

  • the sample_state of the Data value (i.e., if it has already been read or not)

  • the view_state of the related instance (i.e., if the instance is new or not)

  • the instance_state of the related instance (i.e., if the instance is alive or not)

  • the valid_data flag. This flag indicates whether there is data associated with the sample. Some samples do not contain data indicating only a change on the instance_state of the corresponding instance.

  • The values of disposed_generation_count and no_writers_generation_count for the related instance at the time the sample was received. These counters indicate the number of times the instance had become ALIVE (with instance_state= DDS_ALIVE_INSTANCE_STATE) at the time the sample was received.

  • The sample_rank and generation_rank of the sample within the returned sequence. These ranks provide a preview of the samples that follow within the sequence returned by the read or take operations.

  • The absolute_generation_rank of the sample within the DDS_DataReader. This rank provides a preview of what is available within the DDS_DataReader.

  • The source_timestamp of the sample. This is the timestamp provided by the DDS_DataWriter at the time the sample was produced.

Interpretation of the SampleInfo disposed_generation_count and no_writers_generation_count

For each instance, RTI Connext internally maintains two counts, the DDS_SampleInfo::disposed_generation_count and DDS_SampleInfo::no_writers_generation_count, relative to each DataReader:

  • These 'generation counts' are reset to zero when the instance resource is reclaimed.

The DDS_SampleInfo::disposed_generation_count and DDS_SampleInfo::no_writers_generation_count available in the DDS_SampleInfo capture a snapshot of the corresponding counters at the time the sample was received.

Interpretation of the SampleInfo sample_rank, generation_rank and absolute_generation_rank

The DDS_SampleInfo::sample_rank and DDS_SampleInfo::generation_rank available in the DDS_SampleInfo are computed based solely on the actual samples in the ordered collection returned by read or take.

  • The DDS_SampleInfo::generation_rank available in the DDS_SampleInfo indicates the difference in "generations" between the sample (S) and the Most Recent Sample of the same instance that appears in the returned Collection (MRSIC). That is, it counts the number of times the instance transitioned from not-alive to alive in the time from the reception of the S to the reception of MRSIC.
  • These 'generation ranks' are reset to zero when the instance resource is reclaimed.

The DDS_SampleInfo::generation_rank is computed using the formula: 

generation_rank = (MRSIC.disposed_generation_count
                          + MRSIC.no_writers_generation_count)
                    - (S.disposed_generation_count
                          + S.no_writers_generation_count)

The DDS_SampleInfo::absolute_generation_rank available in the DDS_SampleInfo indicates the difference in "generations" between the sample (S) and the Most Recent Sample of the same instance that the middleware has received (MRS). That is, it counts the number of times the instance transitioned from not-alive to alive in the time from the reception of the S to the time when the read or take was called. 

absolute_generation_rank = (MRS.disposed_generation_count
                                  + MRS.no_writers_generation_count)
                             - (S.disposed_generation_count
                                  + S.no_writers_generation_count)

Interpretation of the SampleInfo counters and ranks

These counters and ranks allow the application to distinguish samples belonging to different "generations" of the instance. Note that it is possible for an instance to transition from not-alive to alive (and back) several times before the application accesses the data by means of read or take. In this case, the returned collection may contain samples that cross generations (i.e. some samples were received before the instance became not-alive, other after the instance re-appeared again). Using the information in the DDS_SampleInfo, the application can anticipate what other information regarding the same instance appears in the returned collection, as well as in the infrastructure and thus make appropriate decisions.

For example, an application desiring to only consider the most current sample for each instance would only look at samples with sample_rank == 0. Similarly, an application desiring to only consider samples that correspond to the latest generation in the collection will only look at samples with generation_rank == 0. An application desiring only samples pertaining to the latest generation available will ignore samples for which absolute_generation_rank != 0. Other application-defined criteria may also be used.

See Also
DDS_SampleStateKind, DDS_InstanceStateKind, DDS_ViewStateKind, DDS_SampleInfo::valid_data
DDSInstanceViewStates.png
Statechart of the instance_state and view_state of a single instance

Field Documentation

DDS_SampleStateKind DDS_SampleInfo::sample_state

The sample state of the sample.

Indicates whether or not the corresponding data sample has already been read.

See Also
DDS_SampleStateKind
DDS_ViewStateKind DDS_SampleInfo::view_state

The view state of the instance.

Indicates whether the DDS_DataReader has already seen samples for the most-current generation of the related instance.

See Also
DDS_ViewStateKind
DDS_InstanceStateKind DDS_SampleInfo::instance_state

The instance state of the instance.

Indicates whether the instance is currently in existence or, if it has been disposed, the reason why it was disposed.

See Also
DDS_InstanceStateKind
struct DDS_Time_t DDS_SampleInfo::source_timestamp

The timestamp when the sample was written by a DataWriter.

DDS_InstanceHandle_t DDS_SampleInfo::instance_handle

Identifies locally the corresponding instance.

DDS_InstanceHandle_t DDS_SampleInfo::publication_handle

Identifies locally the DataWriter that modified the instance.

The publication_handle is the same DDS_InstanceHandle_t that is returned by the operation DDS_DataReader_get_matched_publications and can also be used as a parameter to the operation DDS_DataReader_get_matched_publication_data.

DDS_Long DDS_SampleInfo::disposed_generation_count

The disposed generation count of the instance at the time of sample reception.

Indicates the number of times the instance had become alive after it was disposed explicitly by a DDS_DataWriter, at the time the sample was received.

See Also
Interpretation of the SampleInfo disposed_generation_count and no_writers_generation_count Interpretation of the SampleInfo counters and ranks
DDS_Long DDS_SampleInfo::no_writers_generation_count

The no writers generation count of the instance at the time of sample reception.

Indicates the number of times the instance had become alive after it was disposed because there were no writers, at the time the sample was received.

See Also
Interpretation of the SampleInfo disposed_generation_count and no_writers_generation_count Interpretation of the SampleInfo counters and ranks
DDS_Long DDS_SampleInfo::sample_rank

The sample rank of the sample.

Indicates the number of samples related to the same instance that follow in the collection returned by read or take.

See Also
Interpretation of the SampleInfo sample_rank, generation_rank and absolute_generation_rank Interpretation of the SampleInfo counters and ranks
DDS_Long DDS_SampleInfo::generation_rank

The generation rank of the sample.

Indicates the generation difference (number of times the instance was disposed and become alive again) between the time the sample was received, and the time the most recent sample in the collection related to the same instance was received.

See Also
Interpretation of the SampleInfo sample_rank, generation_rank and absolute_generation_rank Interpretation of the SampleInfo counters and ranks
DDS_Long DDS_SampleInfo::absolute_generation_rank

The absolute generation rank of the sample.

Indicates the generation difference (number of times the instance was disposed and become alive again) between the time the sample was received, and the time the most recent sample (which may not be in the returned collection) related to the same instance was received.

See Also
Interpretation of the SampleInfo sample_rank, generation_rank and absolute_generation_rank Interpretation of the SampleInfo counters and ranks
DDS_Boolean DDS_SampleInfo::valid_data

Indicates whether the DataSample contains data or else it is only used to communicate a change in the instance_state of the instance.

Normally each DataSample contains both a DDS_SampleInfo and some Data. However there are situations where a DataSample contains only the DDS_SampleInfo and does not have any associated data. This occurs when the RTI Connext 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 of this situation is when the RTI Connext detects that an instance has no writers and changes the corresponding instance_state to DDS_NOT_ALIVE_NO_WRITERS_INSTANCE_STATE.

The application can distinguish whether a particular DataSample has data by examining the value of the valid_data flag. If this flag is set to DDS_BOOLEAN_TRUE, then the DataSample contains valid Data. If the flag is set to DDS_BOOLEAN_FALSE, the DataSample contains no Data.

To ensure correctness and portability, the valid_data flag must be examined by the application prior to accessing the Data associated with the DataSample and if the flag is set to DDS_BOOLEAN_FALSE, the application should not access the Data associated with the DataSample, that is, the application should access only the DDS_SampleInfo.

struct DDS_Time_t DDS_SampleInfo::reception_timestamp

<<eXtension>> The timestamp when the sample was committed by a DataReader.

struct DDS_SequenceNumber_t DDS_SampleInfo::publication_sequence_number

<<eXtension>> The publication sequence number.

struct DDS_SequenceNumber_t DDS_SampleInfo::reception_sequence_number

<<eXtension>> The reception sequence number when sample was committed by a DataReader

struct DDS_GUID_t DDS_SampleInfo::original_publication_virtual_guid

<<eXtension>> The original publication virtual GUID.

If the DDS_PresentationQosPolicy::access_scope of the DDS_Publisher is DDS_GROUP_PRESENTATION_QOS, this field contains the DDS_Publisher virtual GUID that uniquely identifies the DataWriter group.

See Also
DDS_SampleInfo_get_sample_identity
struct DDS_SequenceNumber_t DDS_SampleInfo::original_publication_virtual_sequence_number

<<eXtension>> The original publication virtual sequence number.

If the DDS_PresentationQosPolicy::access_scope of the DDS_Publisher is DDS_GROUP_PRESENTATION_QOS, this field contains the DDS_Publisher virtual sequence number that uniquely identifies a sample within the DataWriter group.

See Also
DDS_SampleInfo_get_sample_identity
struct DDS_GUID_t DDS_SampleInfo::related_original_publication_virtual_guid

<<eXtension>> The original publication virtual GUID of a related sample

See Also
DDS_SampleInfo_get_related_sample_identity
struct DDS_SequenceNumber_t DDS_SampleInfo::related_original_publication_virtual_sequence_number

<<eXtension>> The original publication virtual sequence number of a related sample

See Also
DDS_SampleInfo_get_related_sample_identity
RTI Connext C API Version 5.1.0 Copyright © Mon Feb 3 2014 Real-Time Innovations, Inc