SampleInfo Class Reference

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

Inheritance diagram for SampleInfo:

Public Member Functions
Object	copy_from (Object other)
Object	copy_from (Object src)
	Copy value of a data type from source. More...

Public Attributes
int	sample_state
	The sample state of the sample. More...
int	view_state
	The view state of the instance. More...
int	instance_state
	The instance state of the instance. More...
final Time_t	source_timestamp
	The timestamp when the sample was written by a DataWriter. More...
final InstanceHandle_t	instance_handle
	Identifies locally the corresponding instance. More...
final InstanceHandle_t	publication_handle
	Identifies locally the DataWriter that modified the instance. More...
int	disposed_generation_count
	The disposed generation count of the instance at the time of sample reception. More...
int	no_writers_generation_count
	The no writers generation count of the instance at the time of sample reception. More...
int	sample_rank
	The sample rank of the sample. More...
int	generation_rank
	The generation rank of the sample. More...
int	absolute_generation_rank
	The absolute generation rank of the sample. More...
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. More...
final Time_t	reception_timestamp
	<<extension>> The timestamp when the sample was committed by a DataReader. More...
final SequenceNumber_t	publication_sequence_number
	<<extension>> The publication sequence number. More...
final SequenceNumber_t	reception_sequence_number
	<<extension>> The reception sequence number when sample was committed by a DataReader More...
final GUID_t	original_publication_virtual_guid
	<<extension>> The original publication virtual GUID. More...
final SequenceNumber_t	original_publication_virtual_sequence_number
	<<extension>> The original publication virtual sequence number. More...
final GUID_t	related_original_publication_virtual_guid
	<<extension>> The original publication virtual GUID of a related sample. More...
final SequenceNumber_t	related_original_publication_virtual_sequence_number
	<<extension>> The original publication virtual sequence number of a related sample. More...
int	flag
	<<extension>> Flags associated with the sample. More...
GUID_t	source_guid
	<<extension>> The application logical data source associated with the sample. More...
GUID_t	related_source_guid
	<<extension>> The application logical data source that is related to the sample. More...
GUID_t	related_subscription_guid
	<<extension>> The related_reader_guid associated with the sample. More...
final GUID_t	topic_query_guid
	<<extension>> The GUID of the com.rti.dds.subscription.TopicQuery that is related to the sample. More...
CoherentSetInfo_t	coherent_set_info
	<<extension>> The information about the coherent set that this sample is a part of. More...

Detailed Description

Information that accompanies each sample that is read or taken.

Interpretation of the SampleInfo

The com.rti.dds.subscription.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)

• com.rti.dds.subscription.SampleInfo.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= com.rti.dds.subscription.InstanceStateKind.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 com.rti.dds.subscription.DataReader. This rank provides a preview of what is available within the com.rti.dds.subscription.DataReader.

• The source_timestamp of the sample. This is the timestamp provided by the com.rti.dds.publication.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 com.rti.dds.subscription.SampleInfo.disposed_generation_count and com.rti.dds.subscription.SampleInfo.no_writers_generation_count, relative to each DataReader:

• The com.rti.dds.subscription.SampleInfo.disposed_generation_count and com.rti.dds.subscription.SampleInfo.no_writers_generation_count are initialized to zero when the com.rti.dds.subscription.DataReader first detects the presence of a never-seen-before instance.

• The com.rti.dds.subscription.SampleInfo.disposed_generation_count is incremented each time the instance_state of the corresponding instance changes from com.rti.dds.subscription.InstanceStateKind.NOT_ALIVE_DISPOSED_INSTANCE_STATE to com.rti.dds.subscription.InstanceStateKind.ALIVE_INSTANCE_STATE.

• The com.rti.dds.subscription.SampleInfo.no_writers_generation_count is incremented each time the instance_state of the corresponding instance changes from com.rti.dds.subscription.InstanceStateKind.NOT_ALIVE_NO_WRITERS_INSTANCE_STATE to com.rti.dds.subscription.InstanceStateKind.ALIVE_INSTANCE_STATE.

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

The com.rti.dds.subscription.SampleInfo.disposed_generation_count and com.rti.dds.subscription.SampleInfo.no_writers_generation_count available in the com.rti.dds.subscription.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 com.rti.dds.subscription.SampleInfo.sample_rank and com.rti.dds.subscription.SampleInfo.generation_rank available in the com.rti.dds.subscription.SampleInfo are computed based solely on the actual samples in the ordered collection returned by read or take.

• The com.rti.dds.subscription.SampleInfo.sample_rank indicates the number of samples of the same instance that follow the current one in the collection.

• The com.rti.dds.subscription.SampleInfo.generation_rank available in the com.rti.dds.subscription.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 com.rti.dds.subscription.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 com.rti.dds.subscription.SampleInfo.absolute_generation_rank available in the com.rti.dds.subscription.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 com.rti.dds.subscription.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

com.rti.dds.subscription.SampleStateKind, com.rti.dds.subscription.InstanceStateKind, com.rti.dds.subscription.ViewStateKind, com.rti.dds.subscription.SampleInfo.valid_data

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

Member Function Documentation

copy_from()

Object copy_from

(

Object

other

)

Implementation of the Copyable interface.

See also

com.rti.dds.infrastructure.Copyable::copy_from(java.lang.Object)

Implements Copyable.

References SampleInfo.absolute_generation_rank, SampleInfo.coherent_set_info, InstanceHandle_t.copy_from(), SampleInfo.disposed_generation_count, SampleInfo.flag, SampleInfo.generation_rank, SampleInfo.instance_handle, SampleInfo.instance_state, Time_t.nanosec, SampleInfo.no_writers_generation_count, SampleInfo.original_publication_virtual_guid, SampleInfo.original_publication_virtual_sequence_number, SampleInfo.publication_handle, SampleInfo.publication_sequence_number, SampleInfo.reception_sequence_number, SampleInfo.reception_timestamp, SampleInfo.related_original_publication_virtual_guid, SampleInfo.related_original_publication_virtual_sequence_number, SampleInfo.related_source_guid, SampleInfo.related_subscription_guid, SampleInfo.sample_rank, SampleInfo.sample_state, Time_t.sec, SampleInfo.source_guid, SampleInfo.source_timestamp, SampleInfo.topic_query_guid, SampleInfo.valid_data, and SampleInfo.view_state.

Member Data Documentation

sample_state

int sample_state

The sample state of the sample.

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

See also

com.rti.dds.subscription.SampleStateKind

Referenced by SampleInfo.copy_from().

view_state

int view_state

The view state of the instance.

Indicates whether the com.rti.dds.subscription.DataReader has already seen samples for the most-current generation of the related instance.

See also

com.rti.dds.subscription.ViewStateKind

Referenced by SampleInfo.copy_from().

instance_state

int 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

com.rti.dds.subscription.InstanceStateKind

Referenced by SampleInfo.copy_from().

source_timestamp

final Time_t source_timestamp

The timestamp when the sample was written by a DataWriter.

Referenced by SampleInfo.copy_from().

instance_handle

final InstanceHandle_t instance_handle

Identifies locally the corresponding instance.

The handle is equal to com.rti.dds.infrastructure.InstanceHandle_t.HANDLE_NIL for unkeyed topics.

Referenced by SampleInfo.copy_from().

publication_handle

final InstanceHandle_t publication_handle

Identifies locally the DataWriter that modified the instance.

The publication_handle is the same com.rti.dds.infrastructure.InstanceHandle_t that is returned by the operation com.rti.dds.subscription.DataReader.get_matched_publications and can also be used as a parameter to the operation com.rti.dds.subscription.DataReader.get_matched_publication_data.

Referenced by SampleInfo.copy_from().

disposed_generation_count

int disposed_generation_count

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

Indicates how many times the instance_state of the corresponding instance changed from com.rti.dds.subscription.InstanceStateKind.NOT_ALIVE_DISPOSED_INSTANCE_STATE to com.rti.dds.subscription.InstanceStateKind.ALIVE_INSTANCE_STATE. The counter is reset when the instance resource is reclaimed (removed from the DataReader cache).

See also

Interpretation of the SampleInfo disposed_generation_count and no_writers_generation_count Interpretation of the SampleInfo counters and ranks

Referenced by SampleInfo.copy_from().

no_writers_generation_count

int no_writers_generation_count

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

Indicates how many times the instance_state of the corresponding instance changed from com.rti.dds.subscription.InstanceStateKind.NOT_ALIVE_NO_WRITERS_INSTANCE_STATE to com.rti.dds.subscription.InstanceStateKind.ALIVE_INSTANCE_STATE. The counter is reset when the instance resource is reclaimed (removed from the DataReader cache).

See also

Interpretation of the SampleInfo disposed_generation_count and no_writers_generation_count Interpretation of the SampleInfo counters and ranks

Referenced by SampleInfo.copy_from().

sample_rank

int 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

Referenced by SampleInfo.copy_from().

generation_rank

int generation_rank

The generation rank of the sample.

Indicates the generation difference (number of times the instance was NOT_ALIVE 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

Referenced by SampleInfo.copy_from().

absolute_generation_rank

int 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

Referenced by SampleInfo.copy_from().

valid_data

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.

Normally each DataSample contains both a com.rti.dds.subscription.SampleInfo and some Data. However there are situations where a DataSample contains only the com.rti.dds.subscription.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 com.rti.dds.subscription.InstanceStateKind.NOT_ALIVE_NO_WRITERS_INSTANCE_STATE.

The application can distinguish whether a particular DataSample has data by examining the value of the com.rti.dds.subscription.SampleInfo.valid_data. If this flag is set to com.rti.dds.infrastructure.true, then the DataSample contains valid Data. If the flag is set to com.rti.dds.infrastructure.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 com.rti.dds.infrastructure.false, the application should not access the Data associated with the DataSample, that is, the application should access only the com.rti.dds.subscription.SampleInfo.

Referenced by SampleInfo.copy_from().

reception_timestamp

final Time_t reception_timestamp

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

Referenced by SampleInfo.copy_from().

publication_sequence_number

final SequenceNumber_t publication_sequence_number

<<extension>> The publication sequence number.

Referenced by SampleInfo.copy_from().

reception_sequence_number

final SequenceNumber_t reception_sequence_number

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

Referenced by SampleInfo.copy_from().

original_publication_virtual_guid

final GUID_t original_publication_virtual_guid

<<extension>> The original publication virtual GUID.

If the com.rti.dds.infrastructure.PresentationQosPolicy::access_scope of the com.rti.dds.publication.Publisher is com.rti.dds.infrastructure.PresentationQosPolicyAccessScopeKind.PresentationQosPolicyAccessScopeKind.GROUP_PRESENTATION_QOS, this field contains the com.rti.dds.publication.Publisher virtual GUID that uniquely identifies the DataWriter group.

See also

com.rti.connext.infrastructure.Sample<T>.getIdentity()

Referenced by SampleInfo.copy_from().

original_publication_virtual_sequence_number

final SequenceNumber_t original_publication_virtual_sequence_number

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

If the com.rti.dds.infrastructure.PresentationQosPolicy::access_scope of the com.rti.dds.publication.Publisher is com.rti.dds.infrastructure.PresentationQosPolicyAccessScopeKind.PresentationQosPolicyAccessScopeKind.GROUP_PRESENTATION_QOS, this field contains the com.rti.dds.publication.Publisher virtual sequence number that uniquely identifies a sample within the DataWriter group.

See also

com.rti.connext.infrastructure.Sample<T>.getIdentity()

Referenced by SampleInfo.copy_from().

related_original_publication_virtual_guid

final GUID_t related_original_publication_virtual_guid

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

See also

com.rti.connext.infrastructure.Sample<T>.getRelatedIdentity()

Referenced by SampleInfo.copy_from().

related_original_publication_virtual_sequence_number

final SequenceNumber_t related_original_publication_virtual_sequence_number

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

See also

com.rti.connext.infrastructure.Sample<T>.getRelatedIdentity()

Referenced by SampleInfo.copy_from().

flag

int flag

<<extension>> Flags associated with the sample.

The flags can be set by using the field com.rti.dds.infrastructure.WriteParams_t.flag when writing a sample using the method com.rti.ndds.example.FooDataWriter.write_w_params.

Referenced by SampleInfo.copy_from().

source_guid

GUID_t source_guid

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

The source_guid can be set by using the field com.rti.dds.infrastructure.WriteParams_t.source_guid when writing a sample using the method com.rti.ndds.example.FooDataWriter.write_w_params.

Referenced by SampleInfo.copy_from().

related_source_guid

GUID_t related_source_guid

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

The related_source_guid can be set by using the field com.rti.dds.infrastructure.WriteParams_t.related_source_guid when writing a sample using the method com.rti.ndds.example.FooDataWriter.write_w_params.

Referenced by SampleInfo.copy_from().

related_subscription_guid

GUID_t related_subscription_guid

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

The related_reader_guid can be set by using the field com.rti.dds.infrastructure.WriteParams_t.related_reader_guid when writing a sample using the method com.rti.ndds.example.FooDataWriter.write_w_params.

Referenced by SampleInfo.copy_from().

topic_query_guid

final GUID_t topic_query_guid

<<extension>> The GUID of the com.rti.dds.subscription.TopicQuery that is related to the sample.

This GUID indicates whether a sample is part of the response to a com.rti.dds.subscription.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 com.rti.dds.infrastructure.GUID_t.GUID_UNKNOWN.

Referenced by SampleInfo.copy_from().

coherent_set_info

CoherentSetInfo_t coherent_set_info

<<extension>> The information about the coherent set that this sample is a part of.

This field is set for all samples that are part of a coherent set. Coherent sets are initiated using the operation com.rti.dds.publication.Publisher.begin_coherent_changes and finalized using the operation com.rti.dds.publication.Publisher.end_coherent_changes.

See also

com.rti.dds.publication.Publisher.begin_coherent_changes for additional information on coherent sets.

Referenced by SampleInfo.copy_from().