|
RTI Persistence Service
Version 5.3.0
|
|
RTI Persistence Service
Version 5.3.0
|
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.
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.
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 and Utilities User's Manual.
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.
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.
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.
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).
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:
The next locations are specific to RTI Persistence Service:
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>
The configuration file must follow these syntax rules:
" <tag> value </tag>"is the same as
"<tag>value</tag>"
<!-- comment -->.
<dds>and end with
</dds>
| 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:
Each persistence group and DomainParticipant will have a set of DDS QoSs. There are six tags:
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 and Utilities User's Manual for further information on XML QoS configuration.
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.
| 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 |
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:
The <administration> tag is used to enable remote administration and configure its behavior.
The following table further describes the <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) | 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 | 0 or 1 |
| <distributed_logger> | Configures RTI Distributed Logger. For additional information on distributed logger see the Core Libraries and Utilities 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 and Utilities User's Manual.
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.
| 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 Addendum for Extensible Types. Default: 10488576 | 0 or 1 |
The following table describes the <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:
| 0 or 1 |
| <vacuum> | Sets the auto-vacuum status of the storage. This tag can take these values:
Default: FULL | 0 or 1 |
| <synchronization> | Determines the level of synchronization with the physical disk. This tag can take three values:
| 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.
| 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 UNIX/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 UNIX/Linux systems, the Windows ODBC driver manager on Windows systems). | 0 or 1 |
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:
The following table describes the <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 |
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.
| 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 and Utilities 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 |
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.
| 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 |
| <single_publisher> | Indicates if the persistence service should create one Publisher per persistence group or one Publisher per PRSTDataWriter inside the persistence group. Default: 1 | 0 or 1 |
| <single_subscriber> | Indicates if the persistence service should create one Subscriber per persistence group or one Subscriber per PRSTDataReader in the persistence group. Default: 1 | 0 or 1 |
| <use_durability_service> | 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. Default: 0 | 0 or 1 |
| <share_database_connection> | 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. When <single_publisher> is 0 and <share_database_connection> is 1, there is a single database connection per group. All the PRSTDataWriters will share the same connection. When <single_publisher> is 1 or <share_database_connection> 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 <external_database> in <persistent_storage>. Default: 0 | 0 or 1 |
| <reader_checkpoint_frequency> | 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 <database_connection> tag is present). Default: 1 | 0 or 1 |
| <writer_in_memory_state> | 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 <database_connection> 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. | 0 or 1 |
| <memory_management> | This tag configures the memory allocation policy for samples in the PRSTDataReaders and PRSTDataWriters. | 0 or 1 |
| <propagate_dispose> | Specifies whether or not the persistence service should propagate the dispose messages it receives from data writers to the data readers. Default: 1 | 0 or 1 |
| <propagate_source_timestamp> | Controls whether or not the persistence service propagates the source timestamp of the received samples. Default: false | 0 or 1 |
| <propagate_unregister> | Specifies whether or not the persistence service should propagate the unregister messages it receives from data writers to the data readers. Default: 0 | 0 or 1 |
| <topic_qos> | Topic QoS. Default: DDS defaults | 0 or 1 |
| <publisher_qos> | Publisher QoS. Default: DDS defaults | 0 or 1 |
| <subscriber_qos> | Subscriber QoS. Default: DDS defaults | 0 or 1 |
| <datawriter_qos> | PRSTDataWriter QoS. Default: DDS defaults. Note: These fields cannot be set and are assigned automatically: protocol.virtual_guid, protocol.rtps_object_id, durability.kind. | 0 or 1 |
| <datareader_qos> | PRSTDataReader QoS. Default: DDS defaults. Note: These fields cannot be set and are assigned automatically: protocol.virtual_guid, protocol.rtps_object_id, durability.kind. | 0 or 1 |
| <writer_checkpoint_period> | 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 | 0 or 1 |
| <writer_checkpoint_volume> | 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 | 0 or 1 |
| <writer_ack_period> | Controls how often (expressed in milliseconds) samples are marked as ACK'd in the database by the PRSTDataWriter. Default: 0 | 0 or 1 |
| <late_joiner_read_batch> | 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 | 0 or 1 |
| <sample_logging> | 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 Sample Logging Default: Sample log is disabled. | 0 or 1 |
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 and Utilities User's Manual.
| 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:
This tag indicates how often (in milliseconds) the read bookmark is persisted into disk. Default: 1000 milliseconds | 0 or 1 |
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>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:
| 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 |
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:
RTI Persistence Service Version 5.3.0
Copyright © Sun Jun 25 2017
Real-Time Innovations, Inc