19.2 QoS Configuration and Instances
Some QoS policies are applied per instance, and other QoS policies configure instance management:
19.2.1 QoS Policies that are Applied per Instance
Several QoS policies (listed below) are applied per instance. This means that the QoS policy that’s specified on the DataWriter or DataReader is applied separately for each instance created. QoS policies cannot be specified uniquely per instance, however. For example, if you are representing airline flights as different instances, you can't have a DEADLINE period of 1 second applied to one flight and a DEADLINE period of 2 seconds applied to another flight. The DEADLINE period (of, say, 1 second) is applied to each flight. In other words, you want to be notified if the flight position DataReader does not get an update about each individual flight within 1 second: the DEADLINE period is applied per instance, for all instances.
19.2.1.1 DEADLINE QosPolicy
The 47.7 DEADLINE QosPolicy is checked separately for every instance. When notified of a missed deadline, a DataWriter or DataReader can check the last instance that missed the deadline using the instance handle in the status.
This allows a DataWriter to detect that it has not written a particular instance as frequently as it has offered in its deadline period, even if it has updated other instances.
This allows a DataReader to detect that it has not seen an update of an individual instance within the deadline period, even if it has seen updates from other instances during that time. This can be used to detect errors due to the DataWriter failing to write a particular instance. It can also detect network errors, where updates for a particular instance have been dropped or delayed.
19.2.1.2 DESTINATION_ORDER QosPolicy
The 47.8 DESTINATION_ORDER QosPolicy contains a configuration option that allows a DataWriter or DataReader to order data across the whole Topic for each instance.
19.2.1.3 HISTORY QosPolicy
The 47.12 HISTORY QosPolicy depth is applied for each instance created. For example, if depth = 1, the DataWriter or DataReader will keep one sample for each instance.
This allows an application to specify how much history it wants to keep per instance for reliability purposes. For example, if data is modeled as state data—meaning that only the most recent sample of the data is important—the DataWriter and DataReader can set the history depth to 1. This allows them to send and receive only the most recent state for each instance.
19.2.1.4 DURABILITY QosPolicy
The 47.9 DURABILITY QosPolicy writer_depth is applied for each instance created. For example, if writer_depth = 1, the DataWriter will keep one sample for each instance, for late-joining DataReaders.
This allows an application to specify how many samples it wants to keep per instance for later joiners. For example, if data is modeled as state data—meaning that only the most recent sample of the data is important—the DataWriter can set the writer_depth to 1. This allows it to send only the most recent state for each instance to late-joining DataReaders.
19.2.1.5 PRESENTATION QosPolicy
The 46.6 PRESENTATION QosPolicy contains a configuration option to determine the scope of coherency and ordering of data in the DataReader’s queue. If coherency is enabled, this allows a Publisher or Subscriber to specify whether each coherent set is per instance. If ordered access is enabled, this allows a Publisher or Subscriber to specify whether data should be ordered per Topic or per instance.
19.2.1.6 TIME_BASED_FILTER QosPolicy
The 48.4 TIME_BASED_FILTER QosPolicy filters out samples of each instance that arrive within the specified minimum_separation. For example, if the minimum_separation is 1 second, the DataReader will receive samples of instance A at most once a second, and samples of instance B at most once a second. A sample of instance A may arrive immediately after a sample of instance B, and will not be filtered out.
19.2.2 QoS Policies that Affect Instance Management
There are additional QoS policies that affect instances, primarily by controlling the limits or memory growth of instances, or by controlling which instance information is sent over the network.
19.2.2.1 DataWriter and DataReader
The following policies affect both the DataWriter and DataReader.
19.2.2.1.1 OWNERSHIP QosPolicy
If DataWriters have 47.17 OWNERSHIP QosPolicy set to EXCLUSIVE, a DataWriter with higher OWNERSHIP_STRENGTH is the owner of any instances it writes. If a DataWriter calls unregister_instance(), it gives up ownership of the instance. If it calls dispose(), it does not give up ownership of the instance, so no other DataWriter can update that instance or its state.
19.2.2.1.2 RESOURCE_LIMITS QosPolicy
The 47.22 RESOURCE_LIMITS QosPolicy contains a field named max_instances that controls the maximum number of instances that may be stored for the DataWriter or DataReader.
19.2.2.2 DataWriter
The following policies apply to the DataWriter.
19.2.2.2.1 OWNERSHIP_STRENGTH QosPolicy
The DataWriter with highest 47.18 OWNERSHIP_STRENGTH QosPolicy will own the instances that it writes. This means that if a lower-strength DataWriter attempts to update any of those instances by writing or calling dispose on the instance, it does not affect the instance or its state.
19.2.2.2.2 DATA_WRITER_RESOURCE_LIMITS QosPolicy
The instance_replacement and replace_empty_instances fields in the 47.6 DATA_WRITER_RESOURCE_LIMITS QosPolicy (DDS Extension) control how instances can be replaced and the memory reclaimed if max_instances is reached. See 47.6.1 Configuring DataWriter Instance Replacement for more information.
The autoregister_instances field controls whether to automatically register instances when a non-NIL handle is passed to the write() call.
19.2.2.2.3 WRITER_DATA_LIFECYCLE QosPolicy
The autodispose_unregistered_instances field in the 47.31 WRITER_DATA_LIFECYCLE QoS Policy controls whether a DataWriter automatically disposes instances when they are unregistered. (By default, it doesn't.)
The autopurge_unregistered_instances_delay and autopurge_disposed_instances_delay fields control whether/when a DataWriter purges instances if they are NOT_ALIVE_NO_WRITERS or NOT_ALIVE_DISPOSED. Once all samples for an instance have been fully acknowledged by existing DataReaders, both the instance and the samples for that instance will be purged (see 31.8.2 write() behavior with KEEP_LAST and KEEP_ALL for a definition of "fully ACK'ed").
See 31.14.7 Instance Memory Management for more information on how this affects DataWriter memory usage.
19.2.2.2.4 DATA_WRITER_PROTOCOL QosPolicy
The disable_inline_keyhash field in the 47.5 DATA_WRITER_PROTOCOL QosPolicy (DDS Extension) controls whether or not a keyhash is propagated on the wire with each sample. This field allows the user to control whether bandwidth is used to send the keyhash with every sample, or CPU is used by the subscribing application to calculate the keyhash for every sample.
The serialize_key_with_dispose field controls whether or not the serialized key is propagated on the wire with dispose samples. This field is useful when propagate_dispose_of_unregistered_instances in the 48.1 DATA_READER_PROTOCOL QosPolicy (DDS Extension) is also true.
19.2.2.3 DataReader
The following policies apply to the DataReader.
19.2.2.3.1 DATA_READER_PROTOCOL QosPolicy
The propagate_unregister_of_disposed_instances and propagate_dispose_of_unregistered_instances fields in the 48.1 DATA_READER_PROTOCOL QosPolicy (DDS Extension) control whether a DataReader can see state transitions between NOT_ALIVE instance states. See 19.1 Instance States for more information.
19.2.2.3.2 DATA_READER_RESOURCE_LIMITS QosPolicy
The initial_remote_writers_per_instance and max_remote_writers_per_instance fields in the 48.2 DATA_READER_RESOURCE_LIMITS QosPolicy (DDS Extension) control the number of DataWriters from which a DataReader may receive samples for a single instance.
The max_total_instances field controls the maximum number of instances that a DataReader will maintain state for. See 40.8.6 Instance Resource Limits and Memory Management for more information.
The max_remote_virtual_writers_per_instance field controls the maximum number of virtual remote writers that can be associated with an instance.
The instance_replacement field controls how instances can be replaced and the memory reclaimed if max_instances is reached. See 48.2.3 Configuring DataReader Instance Replacement for more information.
19.2.2.3.3 READER_DATA_LIFECYCLE QosPolicy
The autopurge_nowriter_samples_delay and autopurge_disposed_samples_delay fields in the 48.3 READER_DATA_LIFECYCLE QoS Policy control whether/when to purge samples that are associated with instances in the NOT_ALIVE_NO_WRITERS or NOT_ALIVE_DISPOSED states, freeing up queue space and allowing instance information to be purged.
The autopurge_disposed_instances_delay field controls whether to purge instance memory when an instance becomes NOT_ALIVE_DISPOSED. The autopurge_nowriter_instances_delay field controls whether to purge instance memory when an instance becomes NOT_ALIVE_NOWRITERS.