RTI Connext Modern C++ API  Version 5.3.0
 All Classes Namespaces Functions Variables Typedefs Enumerations Enumerator Friends Groups Pages
dds::core::policy::WriterDataLifecycle Class Reference

Controls how a dds::pub::DataWriter handles the lifecycle of the instances (keys) that it writes. More...

#include <dds/core/policy/CorePolicy.hpp>

Public Member Functions

 WriterDataLifecycle ()
 Creates the default policy.
 
 WriterDataLifecycle (bool autodispose)
 Creates an instance with a value for auto-dispose unregistered instances and default values for the rest of parameters.
 
WriterDataLifecycleautodispose_unregistered_instances (bool b)
 Indicates whether the DataWriter should automatically dispose an instance when it unregisters it.
 
bool autodispose_unregistered_instances () const
 Getter (see setter with the same name)
 
dds::core::policy::WriterDataLifecycleautopurge_unregistered_instances_delay (const dds::core::Duration &duration)
 <<extension>> Maximum duration for which the DataWriter will maintain information regarding an instance once it has unregistered the instance.
 
dds::core::Duration autopurge_unregistered_instances_delay () const
 <<extension>> Getter (see setter with the same name)
 
dds::core::policy::WriterDataLifecycleautopurge_disposed_instances_delay (const dds::core::Duration &duration)
 <<extension>> Maximum duration for which the DataWriter will maintain information regarding an instance once it has disposed the instance.
 
dds::core::Duration autopurge_disposed_instances_delay () const
 <<extension>> Getter (see setter with the same name)
 

Static Public Member Functions

static WriterDataLifecycle AutoDisposeUnregisteredInstances ()
 Creates WriterDataLifecycle(true)
 
static WriterDataLifecycle ManuallyDisposeUnregisteredInstances ()
 Creates WriterDataLifecycle(false)
 

Detailed Description

Controls how a dds::pub::DataWriter handles the lifecycle of the instances (keys) that it writes.

Entity:
dds::pub::DataWriter
Properties:
RxO = N/A
Changeable = YES

Usage

This policy determines how the dds::pub::DataWriter acts with regards to the lifecycle of the data instances it manages (data instances that have been either explicitly registered with the dds::pub::DataWriter or implicitly registered by directly writing the data).

Since the deletion of a DataWriter automatically unregisters all data instances it manages, the setting of the autodispose_unregistered_instances flag will only determine whether instances are ultimately disposed when the dds::pub::DataWriter is deleted either directly by means of the dds::pub::DataWriter::close() operation or indirectly as a consequence of calling dds::pub::Publisher::delete_contained_entities or dds::domain::DomainParticipant::delete_contained_entities that contains the DataWriter.

You may use dds::pub::DataWriter::unregister_instance to indicate that the dds::pub::DataWriter no longer wants to send data for a dds::topic::Topic.

The behavior controlled by this QoS policy applies on a per instance (key) basis for keyed Topics, so that when a dds::pub::DataWriter unregisters an instance, RTI Connext can automatically also dispose that instance. This is the default behavior.

In many cases where the ownership of a Topic is shared (see dds::core::policy::Ownership), DataWriters may want to relinquish their ownership of a particular instance of the Topic to allow other DataWriters to send updates for the value of that instance regardless of Ownership Strength. In that case, you may only want a DataWriter to unregister an instance without disposing the instance. Disposing an instance is a statement that an 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.

Constructor & Destructor Documentation

dds::core::policy::WriterDataLifecycle::WriterDataLifecycle ( )
inline

Creates the default policy.

dds::core::policy::WriterDataLifecycle::WriterDataLifecycle ( bool  autodispose)
inlineexplicit

Creates an instance with a value for auto-dispose unregistered instances and default values for the rest of parameters.

Member Function Documentation

WriterDataLifecycle& dds::core::policy::WriterDataLifecycle::autodispose_unregistered_instances ( bool  b)
inline

Indicates whether the DataWriter should automatically dispose an instance when it unregisters it.

  • true (default)
    The dds::pub::DataWriter will dispose the instance each time it is unregistered. The behavior is identical to explicitly calling one of the dispose operations on the instance prior to calling the unregister operation.
  • false

    The dds::pub::DataWriter will not dispose the instance. The application can still call one of the dispose operations prior to unregistering the instance and accomplish the same effect.

[default] true

bool dds::core::policy::WriterDataLifecycle::autodispose_unregistered_instances ( ) const
inline

Getter (see setter with the same name)

static WriterDataLifecycle dds::core::policy::WriterDataLifecycle::AutoDisposeUnregisteredInstances ( )
inlinestatic

Creates WriterDataLifecycle(true)

static WriterDataLifecycle dds::core::policy::WriterDataLifecycle::ManuallyDisposeUnregisteredInstances ( )
inlinestatic

Creates WriterDataLifecycle(false)

dds::core::policy::WriterDataLifecycle & autopurge_unregistered_instances_delay ( const dds::core::Duration duration)

<<extension>> Maximum duration for which the DataWriter will maintain information regarding an instance once it has unregistered the instance.

Determines how long the dds::pub::DataWriter will maintain information regarding an instance that has been unregistered. By default, the dds::pub::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 dds::core::policy::ResourceLimits::max_instances is exceeded. This behavior can be changed by setting autopurge_unregistered_instance_delay to a value other than dds::core::Duration::infinite().

After this time elapses, the dds::pub::DataWriter will purge all internal information regarding the instance, including historical samples, even if dds::core::policy::ResourceLimits::max_instances has not been reached.

[default] dds::core::Duration::infinite() (disabled) for all dds::pub::DataWriter except for the built-in discovery DataWriters dds::core::Duration::zero() for built-in discovery DataWriters (see rti::core::policy::DiscoveryConfig::publication_writer_data_lifecycle and rti::core::policy::DiscoveryConfig::subscription_writer_data_lifecycle).

[range] [0, 1 year] or dds::core::Duration::infinite()

dds::core::Duration autopurge_unregistered_instances_delay ( ) const

<<extension>> Getter (see setter with the same name)

dds::core::policy::WriterDataLifecycle & autopurge_disposed_instances_delay ( const dds::core::Duration duration)

<<extension>> Maximum duration for which the DataWriter will maintain information regarding an instance once it has disposed the instance.

Determines how long the dds::pub::DataWriter will maintain information regarding an instance that has been disposed. By default, disposing an instance does not make it elegible to be purged. By setting autopurge_disposed_instance_delay to a value other than dds::core::Duration::infinite() the DataWriter will delete the resources associated to an instance, including historical samples, once the time has elapsed and all matching DataReaders have acknowledged all the samples for this instance.

[default] dds::core::Duration::infinite() (disabled)

[range] [0, 1 year] or dds::core::Duration::infinite() (currently only 0 or dds::core::Duration::infinite() are supported)

dds::core::Duration autopurge_disposed_instances_delay ( ) const

<<extension>> Getter (see setter with the same name)


RTI Connext Modern C++ API Version 5.3.0 Copyright © Sun Jun 25 2017 Real-Time Innovations, Inc