RTI Persistence Service  Version 6.1.2
RTI Persistence Service for RTI Connext Messaging
rti_logo.gif
Real-Time Innovations, Inc.

Available Documentation

This document contains:

For additional information, please see the following PDF documents:

Please do not hesitate to contact RTI with questions or comments about this release. We welcome any input on how to improve RTI Persistence Service to suit your needs.


Overview

RTI Persistence Service is an optional package that saves data samples so that they can be delivered to subscribing applications that join the system at a later time – even if the publishing application has already terminated.

RTI Persistence Service runs as a separate application; you can run it on the same node as the publishing application, the subscribing application, or some other node in the network.

When configured to run in PERSISTENT mode, RTI Persistence Service can use the filesystem or a relational database that provides an ODBC driver. For each persistent topic, it collects all the data written by the corresponding persistent DataWriters and stores them into persistent storage.

Refer to the RTI Persistence Service Release Notes for the list of supported relational databases.

When configured to run in TRANSIENT mode, RTI Persistence Service stores the data in memory.


Using RTI Persistence Service

To use RTI Persistence Service in your RTI Connext Messaging application, you need to modify the DURABILITY QosPolicy of the DataReader and/or DataWriter. You may optionally modify the DURABILITY_SERVICE QosPolicy, which can be used to configure RTI Persistence Service.

For more information, please see the Core Libraries User's Manual.


Running RTI Persistence Service

You can run RTI Persistence Service on any node in the network; it does not have to be run on the same node as the publishing or subscribing applications for which it is saving/delivering data. If you run RTI Persistence Service on a separate node, however, make sure that the other applications can find it during the discovery process – that is, it must be in one of the NDDS_DISCOVERY_PEERS lists.

A script to run the RTI Persistence Service executable is located in $NDDSHOME/bin.

To run RTI Persistence Service:

rtipersistenceservice [options]
Options:
 -cfgFile              <file>  Configuration file. This parameter is optional
                               since the configuration can be loaded from
                               other locations
 -cfgName              <name>  Configuration name. This parameter is required
                               and it is used to find a <persistence_service>
                               matching tag in the configuration files
 -appName              <name>  Application name. Used to identify this
                               execution for remote administration and to
                               name the DDS participants
                               Default: -cfgName
 -identifyExecution            Appends the host name and process ID to the
                               appName to help ensure unique names
 -domainId             <int>   DDS domain ID for the domain participants
                               created by the service
                               Default: Use XML value
 -remoteAdministrationDomainId <int>   Enables remote administration and
                               sets the domain ID for the communication
                               Default: Use XML value
 -restore              <0|1>   Indicates whether or not persistence service
                               must restore its state from the persistent
                               storage
                               Default: Use XML value
 -noAutoStart                  Use this option if you plan to start
                               RTI Persistence Service remotely
 -infoDir              <dir>   The info directory of the running persistence
                               service. The service writes a ps.pid file into this
                               directory when is started. When the service finalizes
                               the file is deleted
                               Default: None
 -maxObjectsPerThread  <int>   DomainParticipantFactory parameter
                               Default: DDS default
 -serviceThreadStackSize     <int>   Service thread stack size
                               Default: OS default
 -disableDatabaseLocking       Disable database locking
                               Default: Enabled
 -heapSnapshotPeriod   <sec>   Enables heap monitoring. Persistence Service
                               will generate a heap snapshot every <sec>
                               Default: heap monitoring is disabled
                               Valid range: [1, 86400]
 -heapSnapshotDir      <dir>   When heap monitoring is enabled this parameter
                               configures the directory where the snapshots
                               will be stored. The snapshot file
                               name format is RTI_heap_<appName>_<processId>_<index>.log
                               Default: current working directory
 -verbosity            [0-6]   RTI Persistence Service verbosity
                                0 - silent
                                1 - exceptions (DDS and service)
                                2 - warnings (service)
                                3 - information (service)
                                4 - warnings (DDS and service)
                                5 - tracing (service)
                                6 - tracing (DDS and service)
                               Default: 1 (exceptions)
 -version                      Prints the RTI Persistence Service version
 -licenseFile         <file>   License file. This parameter is optional.
 -help                         Displays this information

For the syntax of the configuration file and details about each option, please see Configuring RTI Persistence Service, or the RTI Core Libraries and Utilities User's Manual.


Finding Example Applications

A simple example is available to show the how data can be persisted with RTI Persistence Service.

C: See the example in <path to examples>/persistence_service/c/hello_world_persistence.

C++: See the example in <path to examples>/persistence_service/c++/hello_world_persistence.

Java: See the example in <path to examples>/persistence_service/java/hello_world_persistence.

Configuring RTI Persistence Service

To use RTI Persistence Service:

1) Modify your RTI Connext Messaging applications. The DURABILITY QosPolicy controls whether or not, and how, published samples are stored by RTI Persistence Service for delivery to late-joining DataReaders.

  • For each DataWriter whose data must be stored, set the Durability QosPolicy kind to DDS_PERSISTENT_DURABILITY_QOS or DDS_TRANSIENT_DURABILITY_QOS.

  • For each DataReader that needs to receive stored data, set the Durability QosPolicy kind to DDS_PERSISTENT_DURABILITY_QOS or DDS_TRANSIENT_DURABILITY_QOS.

Optionally, modify the DURABILITY_SERVICE QosPolicy, which can be used to configure RTI Persistence Service.

By default, the HISTORY and RESOURCE_LIMITS QosPolicies for the Persistence Service DataWriter and DataReader (known as PRSTDataWriter and PRSTDataReader, respectively) with topic 'A' will be configured using the values specified in the XML file used to configure RTI Persistence Service. To overwrite those values and use the values in the DURABILITY_SERVICE QosPolicy of the first-discovered DataWriter that is publishing 'A', use the tag <use_durability_service> in the persistence group definition).

2) Create a configuration file, as described in XML Configuration File.

3) Start RTI Persistence Service with your configuration file. You can start it on the node for either application, or even an entirely different node (provided that node is included in the NDDS_DISCOVERY_PEERS lists for one of the applications).


How to Load XML Configuration

RTI Persistence Service loads its XML configuration from multiple locations. This section presents the various approaches, listed in load order.

The first three locations only contain QoS Profiles and are inherited from RTI Connext:

  • <NDDSHOME>/resource/xml/NDDS_QOS_PROFILES.xml
  • File specified in NDDS_QOS_PROFILES Environment Variable
  • <working directory>/USER_QOS_PROFILES.xml

The next locations are specific to RTI Persistence Service:

  • <NDDSHOME>/resource/xml/RTI_PERSISTENCE_SERVICE.xml
  • <working directory>/USER_PERSISTENCE_SERVICE.xml
  • File specified using the command line option, -cfgFile


XML Configuration File

The configuration file uses XML format. Let's look at a very basic configuration file, just to get an idea of its contents. You will learn the meaning of each line as you read the rest of this section:

Example Configuration File

<?xml version="1.0" encoding="ISO-8859-1"?>
<!-- A Configuration file may be used by several 
     persistence services specifying multiple 
         <persistence_service> entries 
-->

<dds>
    <!-- QoS LIBRARY SECTION -->
    <qos_library name="QosLib1">
        <qos_profile name="QosProfile1">
            <datawriter_qos name="WriterQos1">
                <history>
                    <kind>DDS_KEEP_ALL_HISTORY_QOS</kind>
                </history>
            </datawriter_qos>
            <datareader_qos name="ReaderQos1">
                <reliability>
                    <kind>DDS_RELIABLE_RELIABILITY_QOS</kind>
                </reliability>
                <history>
                    <kind>DDS_KEEP_ALL_HISTORY_QOS</kind>
                </history>
            </datareader_qos>
        </qos_profile>
    </qos_library>

    <!-- PERSISTENCE SERVICE SECTION -->
    <persistence_service name="Srv1">
        <!-- REMOTE ADMINISTRATION -->
        <administration>
            <domain_id>72</domain_id>
        </administration>
        
        <!-- PERSISTENT STORAGE SECTION -->
        <persistent_storage>
            <filesystem>
                <directory>/tmp</directory>
                <file_prefix>PS</file_prefix>
            </filesystem>
        </persistent_storage>

        <!-- DOMAIN PARTICIPANT SECTION -->
        <participant name="Part1">
            <domain_id>71</domain_id>

            <!-- PERSISTENCE GROUP SECTION -->
            <persistence_group name="PerGroup1" filter="*">
                <single_publisher>true</single_publisher>
                <single_subscriber>true</single_subscriber>
                <datawriter_qos base_name="QosLib1::QosProfile1"/>
                <datareader_qos base_name="QosLib1::QosProfile1"/>
           </persistence_group>
        </participant>
    </persistence_service>
</dds>


Configuration File Syntax

The configuration file must follow these syntax rules:

  • The syntax is XML and the character encoding is UTF-8.
  • Opening tags are enclosed in <>; closing tags are enclosed in </>.
  • A value is a UTF-8 encoded string. Legal values are alphanumeric characters. All leading and trailing spaces are removed from the string before it is processed. For example,
    " <tag> value </tag>"
    is the same as 
    "<tag>value</tag>"
  • All values are case-sensitive unless otherwise stated.
  • Comments are enclosed as follows:
    <!-- comment -->.
  • The root tag of the configuration file must be
    <dds>
    and end with 
    </dds>
  • The primitive types support for tag values are specified in the following table.
Supported Tag Values
Type Format Notes
DDS_Boolean yes, 1, true, BOOLEAN_TRUE, or DDS_BOOLEAN_TRUE: true;
no, 0, false, BOOLEAN_FALSE, or DDS_BOOLEAN_FALSE: false

Not case-sensitive

DDS_Enum A string

Legal values are those listed in the online (HTML) documentation for the C or Java API

DDS_Long -2147483648 to 2147483647
or 0x80000000 to 0x7fffffff
or LENGTH_UNLIMITED
or DDS_LENGTH_UNLIMITED

A 32-bit signed integer

DDS_UnsignedLong 0 - 4294967296;
0 - 0xffffffff

A 32-bit unsigned integer

String UTF-8 character string All leading and trailing spaces are ignored between two tags

XML Validation

Validation at Run-Time

RTI Persistence Service validates the input XML files using a builtin Document Type Definition (DTD). You can find a copy of the builtin DTD in <NDDSHOME>/resource/schema/rti_persistence_service.dtd. (This is only a copy of what the RTI Persistence Service core uses. Changing this file has no effect unless you specify its path with the DOCTYPE tag, described below.)

You can overwrite the builtin DTD by using the XML tag, <!DOCTYPE>. For example, the following indicates that RTI Persistence Service must use a different DTD file to perform validation: 

   <!DOCTYPE dds SYSTEM "/local/usr/rti/dds/modified_rtipersistenceservice.dtd">

If you do not specify the DOCTYPE tag in the XML file, the builtin DTD is used.

The DTD path can be absolute or relative to the current working directory of the application.

Validation During Editing

RTI Persistence Service provides DTD and XSD files that describe the format of the XML content. We recommend including a reference to one of these documents in the XML file that contains the persistence service configuration; this provides helpful features in code editors such as Visual Studio and Eclipse, including validation and auto-completion while you are editing the XML file. Including a reference to the XSD file in the XML documents provides stricter validation and better auto-completion than the corresponding DTD file.

The DTD and XSD definitions of the XML elements are in <NDDSHOME>/resource/schema/rti_persistence_service.dtd and <NDDSHOME>/resource/schema/rti_persistence_service.xsd, respectively.

To include a reference to the XSD document in your XML file, use the attribute xsi:noNamespaceSchemaLocation in the <dds> tag. For example (in the following, replace NDDSHOME with the RTI Connext installation directory):

<?xml version="1.0" encoding="UTF-8"?>
<dds xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
xsi:noNamespaceSchemaLocation= 
$(NDDSHOME)/resource/schema/rti_persistence_service.xsd">
   ...
</dds>

The following sections provide details on the XML file syntax:

QoS Configuration

Each persistence group and DomainParticipant will have a set of DDS QoSs. There are six tags:

  • <participant_qos>
  • <publisher_qos>
  • <subscriber_qos>
  • <topic_qos>
  • <datawriter_qos>
  • <datareader_qos>

Each QoS is identified by a name. The QoS can inherit its values from other QoSs or QoS Profiles described in the XML file. For example:

<datawriter_qos name="DerivedWriterQos" base_name="QosLib::BaseWriterQos">
    <history>
        <kind>DDS_KEEP_ALL_HISTORY_QOS</kind>
    </history>
</datawriter_qos>

In the above example, the writer QoS named 'DerivedWriterQos' inherits the values from the writer QoS 'BaseWriterQos' contained in the library 'Lib'. The HistoryQosPolicy kind is set to DDS_KEEP_ALL_HISTORY_QOS.

Each XML tag with an associated name can be uniquely identified by its fully qualified name in C++ style.

See the chapter on Configuring QoS with XML in Core Libraries User's Manual for further information on XML QoS configuration.


Configuring the RTI Persistence Service Application

Each execution of the RTI Persistence Service application is configured using the content of a persistence service application tag (<persistence_service>). When RTI Persistence Service is started, you must specify which <persistence_service> tag to use for configuring the service.

For example:

<dds>
    <persistence_service name="Srv1">
        ...
    </persistence_service>
</dds>

Because a configuration file may contain multiple <persistence_service> tags, one file can be used to configure multiple RTI Persistence Service executions.

The following table lists the tags you can specify for a persistence service.

Persistence Service Application Tags
Tag Description

Number of Tags Allowed

<annotation>

Provides a description for the persistence service configuration. Example:

<annotation>
    <documentation>
        Persists in the file system all topics published with PERSISTENT durability
    </documentation>
</annotation>

0 or 1

<administration>

Enables and configure remote administration. See Configuring Remote Administration.

Default: Administration is disabled.

0 or 1

<purge_samples_after_acknowledgment>

Indicates if persistence service must purge samples after they are acknowledged.

When RTI Persistence Service runs with this flag set to true, samples are removed from the PRSTDataWriters' queues as soon as they are acknowledged by all of the active/matching DataReaders and all the Durable Subscriptions.

When persistence service runs with this flag set to false, the persistence service will keep the samples in the PRSTDataWriters' queues even after being acknoweledged. Acknowledged samples will be purged from the PRSTDataWriters' queues only when the PRSTDataWriters needs these resources for new samples.

Default: false

0 or 1

<persistent_storage>

When this tag is present, the topic data will be persisted to disk. You can select between file storage and relational database storage. See Configuring the Persistent Storage.

Default: No persistent storage.

0 or 1

<participant> The participant tag describes a DomainParticipant created by the persistence service to monitor a domain ID.

1 or more

<synchronization>

Enables synchronization in redundant persistence service instances. See Configuring Persistence Service Synchronization.

Default: Synchronization is disabled.

1 or more

Configuring Remote Administration

RTI Persistence Service can be controlled remotely by sending commands through a special DDS topic. Any DDS application can be implemented to send these commands and receive the corresponding responses. A shell application called rtipssh that sends/receives this command is provided with RTI Persistence Service.

The following remote commands are supported:

  • START
  • STOP
  • SHUTDOWN
  • STATUS

The <administration> tag is used to enable remote administration and configure its behavior.

The following table further describes the <administration> tags.

Administration Tags
Tag Description

Number of Tags Allowed

<domain_id> Specifies which domain ID RTI Persistence Service will use to enable remote administration

1

<participant_qos>

Configures the DomainParticipant QoS for remote administration.

If the tag is not defined, RTI Persistence Service will use the RTI Connext defaults.

0 or 1

<publisher_qos>

Configures the Publisher QoS for remote administration.

If the tag is not defined, RTI Persistence Service will use the RTI Connext defaults.

0 or 1

<subscriber_qos>

Configures the Subscriber QoS for remote administration.

If the tag is not defined, RTI Persistence Service will use the RTI Connext defaults.

0 or 1

<datareader_qos>

Configures the DataReader QoS for remote administration.

If the tag is not defined, RTI Persistence Service will use the RTI Connext defaults with the following changes:

reliability.kind = DDS_RELIABLE_RELIABILITY_QOS (this value cannot be changed)
history.kind = DDS_KEEP_ALL_HISTORY_QOS
resource_limits.max_samples = 32

0 or 1

<datawriter_qos>

Configures the DataWriter QoS for remote administration.

If the tag is not defined, RTI Persistence Service will use the RTI Connext defaults with the following changes:

history.kind = DDS_KEEP_ALL_HISTORY_QOS
resource_limits.max_samples = 32

0 or 1

<distributed_logger>

Configures RTI Distributed Logger.

For additional information on distributed logger see the Core Libraries User's Manual.

Default: Without this tag distributed logger is disabled.

0 or 1

For additional details on remote administration of RTI Persistence Service see please see the Core Libraries User's Manual.

Configuring the Persistent Storage

The <persistent_storage> tag is used to persist samples into permanent storage. If the <persistence_storage> tag is not specified, the service will operate in TRANSIENT mode and all the data will be kept in memory. Otherwise, the persistence service will operate in PERSISTENT mode and all the topic data will be stored in the file-system or in a relational database that provides an ODBC driver.

The following table further describes the <persistent_storage> tags.

Persistent Storage Tags
Tag Description

Number of Tags Allowed

<filesystem> When this tag is present, the topic data will be persisted into files. This tag is required if <external_database> is not specified

0 or 1

<external_database> When this tag is present, the topic data will be persisted in a relational database. This tag is required if <filesystem> is not specified.

0 or 1

<restore> Indicates if the topic data associated with a previous execution of the persistence service must be restored or not. If the topic data is not restored, it will be deleted from the database.
Default: 1 		0 or 1
<type_object_max_ serialized_length>

Defines the length in bytes of the database column used to store the TypeObjects associated with PRSTDataWriters and PRSTDataReader.

For additional information on TypeObjects, see the Extensible Types Guide .

Default: 10488576

0 or 1

The following table describes the <filesystem> tags.

Filesystem Tags
Tag Description

Number of Tags Allowed

<directory> Specifies the directory of the files in which topic data will be persisted. There will be one file per PRSTDataWriter/PRSTDataReader pair.
Default: current working directory

0 or 1

<file_prefix> A name prefix associated with all the files created by RTI Persistence Service.
Default: PS

0 or 1

<journal_mode> Sets the journal mode. This tag can take these values:
  • DELETE: Deletes the rollback journal at the conclusion of each transaction.
  • TRUNCATE: Commits transactions by truncating the rollback journal to zero-length instead of deleting it.
  • PERSIST: Prevents the rollback journal from being deleted at the end of each transaction. Instead, the header of the journal is overwritten with zeros.
  • MEMORY: Stores the rollback journal in volatile RAM. This saves disk I/O, but at the expense of database safety and integrity.
  • WAL: Uses a write-ahead log instead of a rollback journal to implement transactions.
  • OFF: Disables the rollback journal completely. If the persistence service crashes in the middle of a transaction when the OFF journaling mode is set, then the files containing the samples will very likely be corrupted.
Default: DELETE

0 or 1

<vacuum>

Sets the auto-vacuum status of the storage. This tag can take these values:

  • NONE: When data is deleted from the storage files, the files remain the same size.
  • FULL: The storage files are compacted after every transaction.

Default: FULL

0 or 1

<synchronization> Determines the level of synchronization with the physical disk. This tag can take three values:
  • FULL: Every sample is written into physical disk as RTI Persistence Service receives it.
  • NORMAL: Samples are written into disk at critical moments.
  • OFF: No synchronization is enforced. Data will be written to physical disk when the OS flushes its buffers.
Default: OFF

0 or 1

<trace_file>

Specifies the name of a trace file for debugging purposes. The trace file contains information about all SQL statements executed by the persistence service

Default: No trace file is generated

0 or 1

The following table describes the <external_database> tags.

External Database Tags
Tag Description

Number of Tags Allowed

<dsn> DSN used to connect to the database using ODBC. You should create this DSN through the ODBC settings on Windows systems, or in your .odbc.ini file on Linux systems.
This tag is REQUIRED.

1

<username> Username to connect to the database.
Default: No username is used.

0 or 1

<password> Password to connect to the database.
Default: No password is used.

0 or 1

<restore> Indicates if the topic data associated with a previous execution of the persistence service must be restored or not. If the topic data is not restored, it will be deleted from the database.
Default: 1

0 or 1

<odbc_library> Specifies the ODBC driver to load. By default, RTI Connext will try to use the standard ODBC driver manager library (UnixOdbc on Linux systems, the Windows ODBC driver manager on Windows systems).

0 or 1

Configuring Persistence Service Synchronization

By default, different Persistence Service instances do not synchronize with each other. For example, in a scenario with two Persistence Service instances, the first persistence service could receive a sample 'S1' from the original DataWriter that is not received by the second persistence service. If the disk where the first persistence service stores its samples fails, 'S1' will be lost. To enable synchronization between Persistence Servic instances, use the tag <synchronization> under <persistence_service>. When it comes to synchronization, there are two different kinds of information that can be synchronized independently:

  • Information about Durable Subscriptions and their states
  • Data samples

The following table describes the <synchronization> tags.

Synchronization Tags
Tag Description Number of Tags Allowed
<synchronize_data>

Enables synchronization of data samples in redundant Persistence Service instances.

When set to 1, samples lost on the way to one service instance can be repaired by another without impacting the original publisher of that message.

To synchronize the instances, the tag <synchronize_data> must be set to 1 in every instance involved in the synchronization.

Note: This sample synchronization mechanism is not equivalent to database replication. The extent to which database instances have identical contents depends on the destination ordering and other QoS settings for the Persistence Service instances.

Default: 0

0 or 1

<synchronize_durable_subscriptions>

Enables synchronization of Durable Subscriptions in redundant Persistence Service instances.

When set to 1, the different Persistence Service instances will synchronize their Durable Subscription information. This information includes the set of Durable Subscriptions as well as information about the Durable Subscription's state, such as the samples that have already been received by the Durable Subscriptions.

Default: 0

0 or 1

<durable_ subscription_ synchronization_ period>

The period (in milliseconds) at which the information about Durable Subscriptions is synchronized.

Default: 5000 milliseconds

0 or 1

Configuring Participants

An XML <persistence_service> tag will contain a set of DomainParticipants. The persistence service will persist topics published in the domainIDs associated with these participants.

For example:

<persistence_service name="Srv1">
    <participant name="Part1">
        <domain_id>71</domain_id>
       ...
    </participant>
    <participant name="Part2">
        <domain_id>72</domain_id>
        ...
    </participant>
</persistence_service>

In the previous example, the persistence service will create two domain participants on domains 71 and 72. After the domain participants are created, the persistence service will monitor the discovery traffic looking for topics to persist.

The <domain_id> tag can also be specified as an attribute of <participant>. For example:

<persistence_service name="Srv1">
    <participant name="Part1" domain_id="71">
        ...
    </participant>
</persistence_service>

The following table describes the participant tags.

Participant Tags
Tag Description

Number of Tags Allowed

<domain_id> Domain ID associated with the Participant. The domain ID can be specified as an attribute of the participant tag. Default: 0

0 or 1

<participant_qos> Participant QoS. Default: DDS defaults.

0 or 1

<persistence_group> A persistence group describes a set of topics whose data that must be persisted by the persistence service.

1 or more

<durable_subscriptions>

Configures a set of durable subscriptions for a given topic. This is a sequence of <element> tags, each of which has a <name>, a <topic_name>, and a <quorum>.

For additional information on durable subscriptions see the Persistence Service chapters in the Core Libraries User's Manual.

For example:

<durable_subscriptions> 
    <element>
        <name>DurSub1</name> 
        <topic_name>Example MyType</topic_name> 
        <quorum>2</quorum>
    </element> 
    <element>
        <name>DurSub2</name>
        <topic_name>Example MyType</topic_name> 
    </element>
</durable_subscriptions>

0 or 1

Configuring Persistence Groups

The topics that must be persisted in a specific domain id are specified using <persistence_group> tags. A <persistence_group> tag defines a set of topics identified by a POSIX expression.

For example:

<participant name="Part1">
    <domain_id>71</domain_id>
    <persistence_group name="PerGroup1" filter="H*">
       ...
    </persistence_group>
</participant>

In the previous example, the persistence group 'PerGroup1' has associated all the topics published in the domain 71 whose name starts with 'H'.

When a persistence service discovers a topic 'A' that matches a specific persistence group, it creates a PRSTDataReader and PRSTDataWriter to persist that topic. The QoSs associated with these DataReaders and DataWriters, as well as the corresponding Publishers and Subscribers, can be configured inside the persistence group using QoS tags.

For example:

<participant name="Part1">
    <domain_id>71</domain_id>
    <persistence_group name="PerGroup1" filter="*">
        ...
        <publisher_qos base_qos_name="QosLib1::PubQos1"/>
        <subscriber_qos base_qos_name="QosLib1::SubQos1"/>
        <datawriter_qos base_qos_name="QosLib1::WriterQos1"/>
        <datareader_qos base_qos_name="QosLib1::ReaderQos1"/>
       ...
    </persistence_group>
</participant>

For instance, the number of samples saved by RTI Persistence Service is configurable through the HISTORY QosPolicy of the PRSTDataWriters. If a QoS tag is not specified the persistence service will use the corresponding RTI Connext default values.

A <participant> tag can contain multiple persistence groups; the set of topics that each one represents can intersect.

The following table further describes the persistence group tags.

Persistence Group Tags
Tag Description

Number of Tags Allowed

<allow_durable_ subscriptions>

Enables support for durable subscriptions in the PRSTDataWriters created in a persistence group.

When Durable Subscriptions are not required, setting this property to 0 will increase performance.

Default: 1

0 or 1

<filter> A list of POSIX expressions separated by commas that describe the set of topics allowed in the persistence group. The filter can be specified as an attribute of persistence_group as well. Default: *

0 or 1

<deny_filter> A list of POSIX expressions separated by commas that describe the set of topics denied in the persistence group. This "black" list is applied after 'filter'. Default: empty

0 or 1

<content_filter> Content filter topic expression. A persistence group can subscribe to a specific set of data based on the value of this expression. A filter expression is similar to the WHERE clause in SQL. For more information on the syntax, please see the online documentation (From the Modules page, select DDS API Reference, Queries and Filters Syntax.) Default: no expression

0 or 1 

<TR>
            <TD>&lt;single_publisher&gt;</TD>
            <TD>Indicates if the persistence service should create one Publisher per 
                    persistence group or one Publisher per PRSTDataWriter inside the 
                    persistence group. <br>
                    Default: 1</TD>
            <TD>0 or 1</TD>
</TR>

<TR>
            <TD>&lt;single_subscriber&gt;</TD>
            <TD>Indicates if the persistence service should create one Subscriber per 
                    persistence group or one Subscriber per PRSTDataReader in the persistence 
                    group. <br>
                    Default: 1 </TD>
            <TD>0 or 1</TD>
</TR>

<TR>
            <TD>&lt;use_durability_service&gt;</TD>
            <TD>Indicates if the HISTORY and RESOURCE_LIMITS QosPolicies of the 
                    PRSTDataWriters and PRSTDataReaders should be configured based on the 
                    DURABILITY_SERVICE value of the discovered DataWriters. <br>
                    Default: 0 </TD>
    <TD>0 or 1</TD>
</TR>

<TR>
            <TD>&lt;share_database_connection&gt;</TD>
            <TD>A boolean that indicates if the persistence service
            will create an independent database connection per
            PRSTDataWriter in the group (0) or per Publisher (1) 
            in the group.
            <br>

            When &lt;single_publisher&gt; is 0 and
            &lt;share_database_connection&gt; is 1, there 
            is a single database connection per group. All the
            PRSTDataWriters will share the same connection.

            When &lt;single_publisher&gt; is 1 or 
            &lt;share_database_connection&gt; is 0, there is a 
            database connection per PRSTDataWriter.

            This parameter is only applicable to configurations
            persisting the data into a relational database using
            the tag &lt;external_database&gt; in
            &lt;persistent_storage&gt;.

            Default: 0 </TD>
            <TD>0 or 1 </TD>
</TR>

<TR>
            <TD>&lt;reader_checkpoint_frequency&gt;</TD>
            <TD>This property controls how often (expressed in number
                of samples) the PRSTDataReader state is stored in the
                database. The PRSTDataReaders are the DDS DataReaders 
                created by the persistence service.

                A high frequency will provide better performance. 
                However, if the persistence service is restarted, 
                it may receive some duplicate samples. The persistence
                service will send these duplicates samples on the wire
                but they will be filtered by the DDS DataReaders and
                they will not be propagated to the application.

                This property is only applicable when the persistence 
                service operates in persistent mode (the 
                &lt;database_connection&gt; tag is present).

                Default: 1 </TD>
            <TD>0 or 1</TD>
</TR>

<TR>
            <TD>&lt;writer_in_memory_state&gt;</TD>
            <TD>
            This property determines how much state will be kept in
            memory by the PRSTDataWriters in order to avoid accessing 
            the database.

            The property is only applicable when the persistence
            service operates in persistent mode 
            (the &lt;database_connection&gt; tag is present).

            When writer_in_memory_state is true, the PRSTDataWriters 
            will keep a copy of the meta-data about all the instances
        in memory. They will also keep a fixed state overhead of 
        24 bytes per sample. However, user data samples will always
        be stored in the database, not in memory.   This mode 
        provides the best performance. However, the restore 
        operation will be slower and the maximum number of 
            samples that a PRSTDataWriter can manage will be limited by 
            the available physical memory.

            If in_memory_state is false, all the state will be kept in 
            the underlying database. In this mode, the maximum number 
            of samples that a PRSTDataWriter can manage will not
            be limited by the available physical memory unless the
            underlying database is an in-memory database (TimesTen).

            Default: For KEEP_LAST or 
            ResourceLimitsQosPolicy.max_samples != DS_UNLIMITED_LENGTH, 
            the default is true. Otherwise, the default is false. </TD>
            <TD>0 or 1</TD>
</TR>

<TR>
    <TD>&lt;memory_management&gt;</TD>
    <TD>
    This tag configures the memory allocation policy for samples
    in the PRSTDataReaders and PRSTDataWriters.

    See \ref memory_management
    </TD>
    <TD>0 or 1</TD>
</TR>

<TR>
            <TD>\<propagate_dispose\></TD>
            <TD>Specifies whether or not the persistence service should propagate the 
                dispose messages it receives from data writers to the data readers.<br>
                Default: 1 </TD>
            <TD>0 or 1 </TD>
</TR>


<TR>
            <TD>\<propagate_source_timestamp\></TD>
            <TD>Controls whether or not the persistence service propagates the source 
                timestamp of the received samples. 
                Default: false </TD>
            <TD>0 or 1 </TD>
</TR>

<TR>
            <TD>\<propagate_unregister\></TD>
            <TD>Specifies whether or not the persistence service should propagate the 
                unregister messages it receives from data writers to the data readers.<br>
                Default: 0 </TD>
            <TD>0 or 1 </TD>
</TR>

<TR>
            <TD>&lt;topic_qos&gt;</TD>
            <TD>Topic QoS. Default: DDS defaults</TD>
            <TD>0 or 1 </TD>
</TR>

<TR>
            <TD>&lt;publisher_qos&gt;</TD>
            <TD>Publisher QoS. Default: DDS defaults</TD>
            <TD>0 or 1 </TD>
</TR>

<TR>
            <TD>&lt;subscriber_qos&gt;</TD>
            <TD>Subscriber QoS. Default: DDS defaults</TD>
            <TD>0 or 1 </TD>
</TR>

<TR>
            <TD>&lt;datawriter_qos&gt;</TD>
            <TD>PRSTDataWriter QoS. 
                    Default: DDS defaults.
                    Note: These fields cannot be set and are assigned automatically: 
                    protocol.virtual_guid, protocol.rtps_object_id, durability.kind.</TD>
            <TD>0 or 1 </TD>
</TR>

<TR>
            <TD>&lt;datareader_qos&gt;</TD>
            <TD>PRSTDataReader QoS. Default: DDS defaults. 
        Note: These fields cannot be set and are assigned automatically: 
        protocol.virtual_guid, protocol.rtps_object_id, durability.kind.</TD>
            <TD>0 or 1 </TD>
</TR>

<TR>
            <TD>&lt;writer_checkpoint_period&gt;</TD>
            <TD>Controls how often (expressed in milliseconds) transactions are 
                committed for a PRSTDataWriter.

                A value of 0 indicates that transactions will be committed 
                immediately. This is the recommended setting to avoid losing 
                data in the case of an unex- pected error in 
                Persistence Service and/or the underlying hardware/software 
                infrastructure.

                For applications that can tolerate some data losses, 
                setting this tag to a value greater than 0 will increase 
                performance.                    

                Default: 0
            </TD>
            <TD>0 or 1 </TD>
</TR>

<TR>
            <TD>&lt;writer_checkpoint_volume&gt;</TD>
            <TD> Controls how often (expressed as a number of samples) 
                 transactions are committed for a PRSTDataWriter.

                 A value of 1 indicates that samples will be persisted by 
                 the PRSTDataWrit- ers immediately. This is the recommended 
                 setting to avoid losing data in the case of an unexpected 
                 error in persistence service and/or the underlying 
                 hardware/software infrastructure.                     

                 For application that can tolerate some data losses, 
                 setting this tag to a value greater than 1 will increase 
                 performance.

                 Default: 1
            </TD>
            <TD>0 or 1 </TD>
</TR>

<TR>
            <TD>&lt;writer_ack_period&gt;</TD>
            <TD> Controls how often (expressed in milliseconds) samples are marked as 
                 ACK'd in the database by the PRSTDataWriter.
                 Default: 0
            </TD>
            <TD>0 or 1 </TD>
</TR>

<TR>
    <TD>&lt;late_joiner_read_batch&gt;</TD>
    <TD>
    Defines how many samples will be pre-fetched by a PRSTDataWriter to 
    satisfy requests from late-joiners.

    When a DataReader requests samples from a PRSTDataWriter by sending 
    a NACK message, the PRSTDataWriter may retrieve additional samples from 
    the database to minimize disk access. This paramater determines that 
    amount of samples that will be retrieved preemptively from the database 
    by the PRSTDataWriter.

    Default: 20000
    </TD>
    <TD>0 or 1 </TD>
</TR>    

<TR>
    <TD>&lt;sample_logging&gt;</TD>
    <TD>
    This tag can be used to enable and configure a sample log for the 
    PRSTDataWriters in a persistence group. A sample log is a buffer of 
    samples on disk that, when used in combination with 
    delegate reliability, allow decoupling the original DataWriters 
    from slow DataReaders.

    See \ref configuring_sample_logging

    Default: Sample log is disabled.
    </TD>
    <TD>0 or 1</TD>
</TR>

Sample Logging

Persistence Service can be configured to enable sample logging per persistence group using the <sample_logging> XML tag to specify the log's configuration parameters.

For additional information on sample logging see the persistence service chapters in the Core Libraries User's Manual.

Sample Logging Tags
Tag Description

Number of Tags Allowed

<enable>

Indicates whether or not sample logging is enabled in the container persistence group.

Default: 0

0 or 1

<log_file_size>

Specifies the maximum size of a sample log file in Mbytes. When a log file becomes full, Persistence Service creates a new log file.

Default: 60 MB

0 or 1

<log_flush_period>

The period (in milliseconds) at which Persistence Service removes sample log files whose full content have been written into the PRSTDataWriter by the sample log write thread.

Default: 10000 milliseconds

0 or 1

<log_read_batch>

Determines how many samples should be read and processed at once by the sample log write thread.

Default: 100 samples

0 or 1

<log_bookmark_period>

Samples in the sample log are identified by two attributes:

  • The file ID
  • The row ID (position within the file) The read bookmark indicates the most recently processed sample.

This tag indicates how often (in milliseconds) the read bookmark is persisted into disk.

Default: 1000 milliseconds

0 or 1

DurabilityService QosPolicy

The DURABILITY_SERVICE QosPolicy associated with a DataWriter is used to configure the HISTORY and the RESOURCE_LIMITS associated with the PRSTDataReaders and PRSTDataWriters.

By default, the HISTORY and RESOURCE_LIMITS of a PRSTDataReader and PRSTDataWriter with topic 'A' will be configured using the values specified in the XML file used to configure RTI Persistence Service. To overwrite those values and use the DURABILITY_SERVICE value of the first discovered DataWriter publishing 'A', you can use the tag <use_durability_service> in the persistence group definition:

<participant name="Part1">
    <domain_id>71</domain_id>
    <persistence_group name="PerGroup1" filter="*">
        ...
        <use_durability_service/>1</ use_durability_service>
        ...
    </persistence_group>
</participant>

Memory Management

The samples received and stored by the PRSTDataReaders and PRSTDataWriters are in serialized form.

The serialized size of a sample is the number of bytes that requires on the wire. The maximum serialized size of a sample is the number of bytes that the largest sample for a given type requires on the wire.

By default, The PRSTDataReaders and PRSTDataWriters created by the persistence service try to allocate multiple samples to their maximum serialized size. This may cause memory allocation issues when the maximum serialized size is significantly large.

For PRSTDataReaders, the number of samples in the DataReaders queues can be controlled using the QoS values resource_qos.resource_limits.max_samples and resource_qos.resource_limits.initial_samples.

The PRSTDataWriters keep a cache of samples so that they do not have to access the database every time. The minimum size of this cache is 32 samples.

In addition, each PRSTDataWriter keeps an additional sample called DB sample that is used to move information from the DataWriter cache to the database and viceversa.

The <memory_management> tag in a persistence group can be used to control the memory allocation policy for the samples created by PRStDataReaders and PRSTDataWriters in the persistence group.

The following table further describes the memory management tags:

Memory Management Tags
Tag Description

Number of Tags Allowed

<pool_sample_buffer_max_size>

This tag applies to both, PRSTDataReader and PRSTDataWriters. Its value determines the maximum size (in bytes) of the buffers that will be preallocated to store the samples. If the space required for a new sample is greater than this size, persistence service will allocate the memory dynamically to the exact size required by the sample.

This parameter is used to control the memory allocated for the samples in the PRSTDataReader queues and the PRSTDataWriter caches.

The size of the DB sample in the PRSTDataWriters is controlled by the value of the tag <persistent_sample_buffer_max_size>.

Default: LENGTH_UNLIMITED (samples are allocated to the maximum size)

0 or 1

<persistent_sample_buffer_max_size>

This tag is used to control the memory associated with the DB sample in a PRSTDataWriter. The persistence service will not be able to store a sample into persistent storage if the serialized size is greater than this value. Therefore, this parameter must be used carefully.

Default: LENGTH_UNLIMITED (DB sample is allocated to the maximum size)

0 or 1

Using the RTI Persistence Service library

Persistence can be deployed as a C library linked into your application in selected architectures.

Refer to the RTI Persistence Service Release Notes for the list of supported architectures.

You can configure, start and stop the service using the API described here: