RTI Connext Modern C++ API Version 7.2.0

<<value-type>> Information that accompanies each sample received by a DataReader More...

#include "dds/sub/SampleInfo.hpp"

Public Member Functions

dds::core::Time source_timestamp () const
 Get the timestamp when the sample was written by a DataWriter. More...
 
dds::sub::status::DataState state () const
 Get the dds::sub::status::DataState of the sample. More...
 
dds::sub::GenerationCount generation_count () const
 Get the dds::sub::GenerationCount of the sample. More...
 
dds::sub::Rank rank () const
 Get the dds::sub::Rank of the sample. More...
 
bool valid () const
 Indicates whether the DataSample contains data or else it is only used to communicate a change in the dds::sub::status::InstanceState of the instance. More...
 
dds::core::InstanceHandle instance_handle () const
 Identifies locally the corresponding instance. More...
 
dds::core::InstanceHandle publication_handle () const
 Identifies locally the DataWriter that modified the instance. More...
 
dds::core::Time reception_timestamp () const
 <<extension>> The timestamp when the sample was committed by a dds::sub::DataReader. More...
 
rti::core::SequenceNumber publication_sequence_number () const
 <<extension>> The publication sequence number. More...
 
rti::core::SequenceNumber reception_sequence_number () const
 <<extension>> The reception sequence number when sample was committed by a dds::sub::DataReader More...
 
rti::core::Guid original_publication_virtual_guid () const
 <<extension>> The original publication virtual GUID. More...
 
rti::core::SequenceNumber original_publication_virtual_sequence_number () const
 <<extension>> The original publication virtual sequence number. More...
 
rti::core::SampleIdentity original_publication_virtual_sample_identity () const
 <<extension>> Retrieves the information provided by original_publication_virtual_guid() and original_publication_virtual_sequence_number() combined in a SampleIdentity instance More...
 
rti::core::Guid related_original_publication_virtual_guid () const
 <<extension>> The original publication virtual GUID of a related sample More...
 
rti::core::SequenceNumber related_original_publication_virtual_sequence_number () const
 <<extension>> The original publication virtual sequence number of a related sample More...
 
rti::core::SampleIdentity related_original_publication_virtual_sample_identity () const
 <<extension>> Retrieves the information provided by related_original_publication_virtual_guid() and related_original_publication_virtual_sequence_number() combined in a SampleIdentity instance More...
 
rti::core::SampleFlag flag () const
 <<extension>> Flags associated with the sample. More...
 
rti::core::Guid source_guid () const
 <<extension>> The application logical data source associated with the sample. More...
 
rti::core::Guid related_source_guid () const
 <<extension>> The application logical data source that is related to the sample. More...
 
rti::core::Guid related_subscription_guid () const
 <<extension>> The related_reader_guid associated with the sample. More...
 
rti::core::Guid topic_query_guid () const
 <<extension>> The GUID of the rti::sub::TopicQuery that is related to the sample. More...
 
rti::core::EncapsulationId encapsulation_id () const
 <<extension>> The encapsulation kind. More...
 
rti::core::optional_value< rti::core::CoherentSetInfocoherent_set_info () const
 <<extension>> When set, this field provides the information about the coherent set associated with the sample. More...
 

Detailed Description

<<value-type>> Information that accompanies each sample received by a DataReader

Information that accompanies each sample that is read or taken.

Interpretation of the SampleInfo

The dds::sub::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)
  • dds::sub::SampleInfo::valid 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::sub::status::InstanceState::alive()) 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 source_timestamp of the sample. This is the timestamp provided by the dds::pub::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::sub::GenerationCount::disposed() and dds::sub::GenerationCount::no_writers(), relative to each DataReader:

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

The dds::sub::GenerationCount::disposed() and dds::sub::GenerationCount::no_writers() available in the dds::sub::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::sub::Rank::sample() and dds::sub::Rank::generation() available in the dds::sub::SampleInfo are computed based solely on the actual samples in the ordered collection returned by read or take.

  • The dds::sub::Rank::sample() indicates the number of samples of the same instance that follow the current one in the collection.
  • The dds::sub::Rank::generation() available in the dds::sub::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::sub::Rank::generation() 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::sub::Rank::absolute_generation() available in the dds::sub::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::sub::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::sub::status::SampleState, dds::sub::status::InstanceState, dds::sub::status::ViewState, dds::sub::SampleInfo::valid

"Statechart of the \p instance_state and \p view_state of a single instance"

Member Function Documentation

◆ source_timestamp()

dds::core::Time dds::sub::SampleInfo::source_timestamp ( ) const
inline

Get the timestamp when the sample was written by a DataWriter.

◆ state()

dds::sub::status::DataState dds::sub::SampleInfo::state ( ) const
inline

◆ generation_count()

dds::sub::GenerationCount dds::sub::SampleInfo::generation_count ( ) const
inline

Get the dds::sub::GenerationCount of the sample.

◆ rank()

dds::sub::Rank dds::sub::SampleInfo::rank ( ) const
inline

Get the dds::sub::Rank of the sample.

◆ valid()

bool dds::sub::SampleInfo::valid ( ) const
inline

Indicates whether the DataSample contains data or else it is only used to communicate a change in the dds::sub::status::InstanceState of the instance.

Normally each DataSample contains both a dds::sub::SampleInfo and some Data. However there are situations where a DataSample contains only the dds::sub::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::sub::status::InstanceState::not_alive_no_writers().

The application can distinguish whether a particular DataSample has data by examining the value of the dds::sub::SampleInfo::valid. 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.

Applications should check the valid() flag before accessing the data. An attempt to access rti::sub::LoanedSample::data() or dds::sub::Sample::data() when valid() is false will throw dds::core::PreconditionNotMetError.

See also
Foo_subscriber.cxx
rti::sub::LoanedSample::info()
dds::sub::Sample::info()

Referenced by rti::sub::LoanedSample< T >::operator<<().

◆ instance_handle()

dds::core::InstanceHandle dds::sub::SampleInfo::instance_handle ( ) const
inline

Identifies locally the corresponding instance.

The handle is equal to dds::core::InstanceHandle::nil() for unkeyed topics.

◆ publication_handle()

dds::core::InstanceHandle dds::sub::SampleInfo::publication_handle ( ) const
inline

Identifies locally the DataWriter that modified the instance.

The publication_handle is the same dds::core::InstanceHandle that is returned by the operation dds::sub::matched_publications and can also be used as a parameter to the operation dds::sub::DataReader::matched_publication_data.

◆ reception_timestamp()

dds::core::Time reception_timestamp ( ) const

<<extension>> The timestamp when the sample was committed by a dds::sub::DataReader.

Note
This function is an extension, it must be called via the extensions() member function

◆ publication_sequence_number()

rti::core::SequenceNumber publication_sequence_number ( ) const

<<extension>> The publication sequence number.

Note
This function is an extension, it must be called via the extensions() member function

◆ reception_sequence_number()

rti::core::SequenceNumber reception_sequence_number ( ) const

<<extension>> The reception sequence number when sample was committed by a dds::sub::DataReader

Note
This function is an extension, it must be called via the extensions() member function

◆ original_publication_virtual_guid()

rti::core::Guid original_publication_virtual_guid ( ) const

<<extension>> The original publication virtual GUID.

Note
This function is an extension, it must be called via the extensions() member function

If the dds::core::policy::Presentation::access_scope of the dds::pub::Publisher is dds::core::policy::PresentationAccessScopeKind_def::GROUP, this field contains the dds::pub::Publisher virtual GUID that uniquely identifies the DataWriter group.

See also
Sample::identity

◆ original_publication_virtual_sequence_number()

rti::core::SequenceNumber original_publication_virtual_sequence_number ( ) const

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

Note
This function is an extension, it must be called via the extensions() member function

If the dds::core::policy::Presentation::access_scope of the dds::pub::Publisher is dds::core::policy::PresentationAccessScopeKind_def::GROUP, this field contains the dds::pub::Publisher virtual sequence number that uniquely identifies a sample within the DataWriter group.

See also
Sample::identity

◆ original_publication_virtual_sample_identity()

rti::core::SampleIdentity original_publication_virtual_sample_identity ( ) const

<<extension>> Retrieves the information provided by original_publication_virtual_guid() and original_publication_virtual_sequence_number() combined in a SampleIdentity instance

Note
This function is an extension, it must be called via the extensions() member function

Referenced by rti::request::Replier< RequestType, ReplyType >::send_reply().

◆ related_original_publication_virtual_guid()

rti::core::Guid related_original_publication_virtual_guid ( ) const

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

Note
This function is an extension, it must be called via the extensions() member function

◆ related_original_publication_virtual_sequence_number()

rti::core::SequenceNumber related_original_publication_virtual_sequence_number ( ) const

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

Note
This function is an extension, it must be called via the extensions() member function

◆ related_original_publication_virtual_sample_identity()

rti::core::SampleIdentity related_original_publication_virtual_sample_identity ( ) const

<<extension>> Retrieves the information provided by related_original_publication_virtual_guid() and related_original_publication_virtual_sequence_number() combined in a SampleIdentity instance

Note
This function is an extension, it must be called via the extensions() member function

Referenced by rti::request::IsReplyRelatedPredicate< T >::operator()().

◆ flag()

rti::core::SampleFlag flag ( ) const

<<extension>> Flags associated with the sample.

Note
This function is an extension, it must be called via the extensions() member function

The flags can be set by using the field rti::pub::WriteParams::flag when writing a sample using the method dds::pub::DataWriter::write(const T&,rti::pub::WriteParams&).

◆ source_guid()

rti::core::Guid source_guid ( ) const

<<extension>> The application logical data source associated with the sample.

Note
This function is an extension, it must be called via the extensions() member function

The source_guid can be set by using the field rti::pub::WriteParams::source_guid when writing a sample using the method dds::pub::DataWriter::write(const T&,rti::pub::WriteParams&).

◆ related_source_guid()

rti::core::Guid related_source_guid ( ) const

<<extension>> The application logical data source that is related to the sample.

Note
This function is an extension, it must be called via the extensions() member function

The source_guid can be set by using the field rti::pub::WriteParams::source_guid when writing a sample using the method dds::pub::DataWriter::write(const T&,rti::pub::WriteParams&).

◆ related_subscription_guid()

rti::core::Guid related_subscription_guid ( ) const

<<extension>> The related_reader_guid associated with the sample.

Note
This function is an extension, it must be called via the extensions() member function

The related_reader_guid can be set by using the field rti::pub::WriteParams::related_reader_guid when writing a sample using the method dds::pub::DataWriter::write(const T&,rti::pub::WriteParams&).

◆ topic_query_guid()

rti::core::Guid topic_query_guid ( ) const

<<extension>> The GUID of the rti::sub::TopicQuery that is related to the sample.

Note
This function is an extension, it must be called via the extensions() member function

This GUID indicates whether a sample is part of the response to a rti::sub::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 rti::core::Guid::unknown().

◆ encapsulation_id()

rti::core::EncapsulationId encapsulation_id ( ) const

<<extension>> The encapsulation kind.

Note
This function is an extension, it must be called via the extensions() member function

◆ coherent_set_info()

rti::core::optional_value< rti::core::CoherentSetInfo > coherent_set_info ( ) const

<<extension>> When set, this field provides the information about the coherent set associated with the sample.

This field is set for all samples that are part of a coherent set. Coherent sets are initiated using the operation dds::pub::CoherentSet::CoherentSet and finalized using the operation dds::pub::CoherentSet::end().

See also
dds::pub::CoherentSet::CoherentSet for additional information on coherent sets.