For each data sample accessed via a read or take, DDS provides you with a SampleInfo. This SampleInfo contains meta-information about the Sample, such as timestamp, lifecycle information, etc., and tells you if the data is valid or not.
The lifecycle information can be used to filter the data received by a DataReader (state based selection).
Remember that we can also filter by content.
- Sample, Instance, View State
Along with data samples, DataReaders provides state information allowing to detect relevant transitions in the life-cycle of data as well as data writers
- Sample State (READ | NOT_READ): Determines wether a sample has already been read by this DataReader or not.
- Instance State (ALIVE, NOT_ALIVE_NO_WRITERS, NOT_ALIVE_ DISPOSED). Determines wether (1) writer exist for the specific instance, or (2) no matched writers are currently available, or (3) the instance has been disposed
- View State (NEW, NOT_NEW). Determines wether this is the first sample of a new (or re-born) instance
- StatusCondition vs ReadCondition
- Both a StatusCondition as well as a Read Condition can be used to wait for data to be available on a DataReader
- The main difference is that a ReadCondition allows to set the exact SAMPLE, VIEW and INSTANCE status for which the condition should trigger, while the StatusCondition triggers when a sample is received.
- If what you really care is getting a condition that triggers for the state ANY_SAMPLE_STATE, ANY_VIEW_STATE and ANY_INSTANCE_STATE than use a StatusCondition as this is more efficient than a ReadCondition
- If you are interested in having a condition that triggers for a specific status then use the ReadCondition Guidelines
Sample state and view state are easy to understand. For Instance State, it is useful to bring more precise explanations in order to use correctly the state based selection of received data.
The diagram below shows how the Instance State is managed via the DataWriter API.
Topic Instance lifecycle explicit management
The following example (in isoCpp) assumes a DataWriter “fooDW” is available that can write samples of type Foo.
class Foo { int myKey; String myName; };
1- The instance is created by setting the key values.
example::Foo myFoo(); myFoo.myKey = 10; // key value set : instance is created
2- Register this instance in the DataWriter.
dds::core::InstanceHandle myHandle; myHandle = fooDW.register_instance(myFoo); // instance is ALIVE
3- Initialize a sample of type Foo (sample of the previously created instance).
myFoo.myName = "OpenSplice DDS";
4- Write the 1st sample.
fooDW.write(myFoo, myHandle);
5- Write some more samples of the same instance …
...
6- Unregister the instance in the current Writer, which will nomore update it. */
fooDW.unregister_instance(myHandle); // instance is NOT_ALIVE_NO_WRITERS // (all the writers have unregistered - here fooDW is the only writer)
7- Dispose the instance in all Readers.
fooDW.dispose_instance(myHandle); // instance is NOT_ALIVE_DISPOSED
NOT_ALIVE_DISPOSED state indicates that the instance is no more relevant for the system and should basically be wiped from all storage. The big difference with the NOT_ALIVE_NO_WRITERS state is that the latter only indicates that nobody intends to update the instance and does not say anything about the validity of the last known state.