DDS::SampleInfo Class Reference
[Data Samples]

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

#include <managed_subscription.h>

List of all members.

Properties

SampleStateKind sample_state [get, set]
 The sample state of the sample.
ViewStateKind view_state [get, set]
 The view state of the instance.
InstanceStateKind instance_state [get, set]
 The instance state of the instance.
Time_t source_timestamp [get, set]
 The timestamp when the sample was written by a DataWriter.
InstanceHandle_t instance_handle [get, set]
 Identifies locally the corresponding instance.
InstanceHandle_t publication_handle [get, set]
 Identifies locally the DataWriter that modified the instance.
System::Int32 disposed_generation_count [get, set]
 The disposed generation count of the instance at the time of sample reception.
System::Int32 no_writers_generation_count [get, set]
 The no writers generation count of the instance at the time of sample reception.
System::Int32 sample_rank [get, set]
 The sample rank of the sample.
System::Int32 generation_rank [get, set]
 The generation rank of the sample.
System::Int32 absolute_generation_rank [get, set]
 The absolute generation rank of the sample.
System::Boolean valid_data [get, set]
 Indicates whether the DataSample contains data or else it is only used to communicate a change in the instance_state of the instance.
Time_t reception_timestamp [get, set]
 <<eXtension>> The timestamp when the sample was committed by a DataReader.
SequenceNumber_t publication_sequence_number [get, set]
 <<eXtension>> The publication sequence number.
SequenceNumber_t reception_sequence_number [get, set]
 <<eXtension>> The reception sequence number when sample was committed by a DataReader

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:

Interpretation of the SampleInfo disposed_generation_count and no_writers_generation_count

For each instance, RTI Data Distribution Service internally maintains two counts, the DDS::SampleInfo::disposed_generation_count and DDS::SampleInfo::no_writers_generation_count, relative to each DataReader:

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

Property Documentation

SampleStateKind DDS::SampleInfo::sample_state [get, set]

The sample state of the sample.

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

See also:
DDS::SampleStateKind

ViewStateKind DDS::SampleInfo::view_state [get, set]

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

InstanceStateKind DDS::SampleInfo::instance_state [get, set]

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

Time_t DDS::SampleInfo::source_timestamp [get, set]

The timestamp when the sample was written by a DataWriter.

InstanceHandle_t DDS::SampleInfo::instance_handle [get, set]

Identifies locally the corresponding instance.

InstanceHandle_t DDS::SampleInfo::publication_handle [get, set]

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.

System:: Int32 DDS::SampleInfo::disposed_generation_count [get, set]

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

System:: Int32 DDS::SampleInfo::no_writers_generation_count [get, set]

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

System:: Int32 DDS::SampleInfo::sample_rank [get, set]

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

System:: Int32 DDS::SampleInfo::generation_rank [get, set]

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

System:: Int32 DDS::SampleInfo::absolute_generation_rank [get, set]

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

System:: Boolean DDS::SampleInfo::valid_data [get, set]

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 Data Distribution Service 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 Data Distribution Service detects that an instance has no writers and changes the corresponding instance_state to DDS::InstanceStateKind::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 true, then the DataSample contains valid Data. If the flag is set to 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 false, the application should not access the Data associated with the DataSample, that is, the application should access only the DDS::SampleInfo.

Time_t DDS::SampleInfo::reception_timestamp [get, set]

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

SequenceNumber_t DDS::SampleInfo::publication_sequence_number [get, set]

<<eXtension>> The publication sequence number.

SequenceNumber_t DDS::SampleInfo::reception_sequence_number [get, set]

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

RTI Data Distribution Service .Net APIs Version 4.5e Copyright © 23 Oct 2011 Real-Time Innovations, Inc