WRITER_DATA_LIFECYCLE QoS Policy

You are here:

7.5.31 WRITER_DATA_LIFECYCLE QoS Policy

This QoS policy controls how a DataWriter handles the lifecycle of the instances (keys) that the DataWriter is registered to manage. This QoS policy includes the members in Table 7.78 DDS_WriterDataLifecycleQosPolicy.

Table 7.78 DDS_WriterDataLifecycleQosPolicy
Type	Field Name	Description
DDS_Boolean	autodispose_unregistered_instances	Controls what happens when the DataWriter unregisters an instance explicitly by means of the unregister operations or implicitly during DataWriter deletion. RTI_TRUE (default): The DataWriter disposes of the instance each time it is unregistered. This behavior is identical to explicitly calling one of the dispose operations on the instance prior to calling the unregister operation. When a DataWriter is deleted, a dispose is sent for every instance. In addition, DataReaders will automatically unregister this DataWriter from all instances when they recognize that the DataWriter has been deleted. RTI_FALSE: The DataWriter does not dispose of the instance each time it is unregistered. The application can still call one of the dispose operations prior to unregistering the instance and dispose of the instance that way. When a DataWriter is deleted, no extra messages are sent. DataReaders will automatically unregister this DataWriter from all instances when they recognize that the DataWriter has been deleted.
struct DDS_Duration_t	autopurge_unregistered_ instances_delay	Determines how long the DataWriter will maintain information regarding an instance that has been unregistered. By default, the DataWriter resources associated with an instance (e.g., the space needed to remember the Instance Key or KeyHash) are released lazily. This means the resources are only reclaimed when the space is needed for another instance because max_instances (7.5.22 RESOURCE_LIMITS QosPolicy) is exceeded. This behavior can be changed by setting autopurge_unregistered_instance_delay to a value other than INFINITE. After this time elapses, the DataWriter will purge all internal information regarding the instance, including historical DDS samples even if max_instances has not been reached. The purging of the unregistered instances can be done based on the unregistered sample source timestamp or the time when the unregistered sample was added to the DataWriter queue, by setting the following property to 1 or 0 respectively: dds.data_writer.history.source_timestamp_based_autopurge_instances_delay. Default value is 0. The source timestamp can differ from the time that the sample was added to the queue if a timestamp was provided along with the sample when it was written (using the write_with_timestamp() or write_with_params() operations). This is the case, for example, in RTI Routing Service when samples are routed with the original publisher information. autopurge_unregistered_instances_delay is not supported with durable DataWriter queues.
struct DDS_Duration_t	autopurge_disposed_instances_delay	Determines the maximum duration for which the DataWriter will maintain information regarding an instance once it has disposed of the instance. By default, disposing of an instance does not make it eligible to be purged. By setting autopurge_disposed_instances_delay to a value other than DDS_DURATION_INFINITE, the DataWriter will reclaim the resources associated with an instance (including historical samples) once the time has elapsed and all matching DataReaders have acknowledged all the samples for this instance, including the dispose sample. The purging of the disposed instances can be done based on the dispose sample source timestamp or the time when the dispose sample was added to the DataWriter queue, by setting the following property to 1 or 0 respectively: dds.data_writer.history.source_timestamp_based_autopurge_instances_delay. Default value is 0. The source timestamp can differ from the time that the sample was added to the queue if a timestamp was provided along with the sample when it was written (using the write_with_timestamp() or write_with_params() operations). This is the case, for example, in Routing Service when samples are routed with the original publisher information. autopurge_disposed_instances_delay is supported with durable DataWriter queues only for 0 and INFINITE values (finite values are not supported).

7.5.31.1 Unregistering vs. Disposing

Disposing an instance conveys an explicit state about an instance: for example, disposing a flight because it has landed. You can decide what dispose means for your system. See 7.3.14.3 Disposing Instances.
Unregistering an instance can be thought of as a DataWriter unregistering itself from the instance, indicating that the DataWriter has no more information/data on the instance. An example is when radar is no longer tracking a flight. In this example, the flight is still a valid, alive instance in the system, with the same location and trajectory, but this specific radar is simply no longer tracking it. Unregistering tells Connext DDS that the DataWriter does not intend to modify that instance anymore, allowing Connext DDS to recover any resources it allocated for the instance. See 7.3.14.4 Unregistering Instances.

By default, instances are automatically disposed of when they are unregistered. This behavior is controlled by the autodispose_unregistered_instances field in the 7.5.31 WRITER_DATA_LIFECYCLE QoS Policy.

7.5.31.2 Use Cases for Unregistering without Disposing

There are many situations in which you may want to set autodispose_unregistered_instances to FALSE, so that unregistering will not automatically dispose of the instance. In fact, it is a common recommendation to set this QoS setting to FALSE and manage all instance state transitions through explicit calls to dispose() and unregister_instance() in your application. For example:

In many cases where the ownership of a Topic is EXCLUSIVE (see the 7.5.17 OWNERSHIP QosPolicy), DataWriters may want to relinquish ownership of a particular instance of the Topic to allow other DataWriters to send updates for the value of that instance. In this case, you may want a DataWriter to just unregister an instance—without disposing it (since there are other writers). Unregistering an instance implies that the DataWriter no longer owns that instance, but it is a stronger statement to say that instance no longer exists.
User applications may be coded to trigger on the disposal of instances, thus the ability to unregister without disposing may be useful to properly maintain the semantic of disposal.

When you delete a DataWriter (7.3.1 Creating DataWriters), all of the instances managed by the DataWriter are automatically unregistered by matching DataReaders when the DataWriter’s liveliness is lost. Therefore, this QoS policy determines whether or not all of the instances are disposed of when the DataWriter is deleted when you call one of these operations:

Publisher’s delete_datawriter() (see 7.3.1 Creating DataWriters)
Publisher’s delete_contained_entities() (see 7.2.3.1 Deleting Contained DataWriters)
DomainParticipant’s delete_contained_entities() (see 9.3.3 Deleting Contained Entities)

Unlike the unregister messages, which are automatically generated by the DataReaders without having to be explicitly sent over the network, the dispose messages are sent during DataWriter deletion, causing a spike in network traffic equal to the number of instances that were registered with the DataWriter.

When autodispose_unregistered_instances is TRUE, Connext DDS will clean up all the resources associated with an unregistered instance (most notably, the DDS sample history of non-volatile DataWriters) when all the instance’s DDS samples have been acknowledged by all its live DataReaders, including the DDS sample that indicates the unregistration. By default, autopurge_unregistered_instances_delay is disabled (the delay is INFINITE). If the delay is set to zero, the DataWriter will clean up as soon as all the DDS samples are acknowledged after the call to unregister_instance(). A non-zero value for the delay can be useful in two ways:

To keep the historical DDS samples for late-joiners for a period of time.
In the context of discovery, if the applications temporarily lose the connection before the unregistration (which represents the remote entity destruction), to provide the DDS samples that indicate the dispose and unregister actions once the connection is reestablished.

This delay can also be set for discovery data through these fields in the 9.5.3 DISCOVERY_CONFIG QosPolicy (DDS Extension):

publication_writer_data_lifecycle.autopurge_unregistered_instances_delay
subscription_writer_data_lifecycle.autopurge_unregistered_instances_delay
publication_writer_data_lifecycle.autopurge_disposed_instances_delay
subscription_writer_data_lifecycle.autopurge_disposed_instances_delay

7.5.31.3 Properties

The WRITER_DATA_LIFECYCLE QoS Policy does not apply to DataReaders, so there is no requirement that the publishing and subscribing sides use compatible values.

This QoS policy may be modified after the DataWriter is enabled.

7.5.31.4 Related QoS Policies

None.

7.5.31.5 Applicable Entities

7.3 DataWriters

7.5.31.6 System Resource Considerations

None.