Skip to content

Commit 04dcae8

Browse files
emiliocuestafemiliocuestaf
authored
Adding documentation for properties of persistence mode (#1236)
* Adding documentation for properties of persistence mode Signed-off-by: Emilio Cuesta <emiliocuesta@eprosima.com> * Adding QoS for correct functioning Signed-off-by: Emilio Cuesta <emiliocuesta@eprosima.com> * Clarify behavior of persistence properties Signed-off-by: Emilio Cuesta <emiliocuesta@eprosima.com> * Update XML example Signed-off-by: Emilio Cuesta <emiliocuesta@eprosima.com> * Apply revision Signed-off-by: Emilio Cuesta <emiliocuesta@eprosima.com> * Apply revision 2 + fix Signed-off-by: Emilio Cuesta <emiliocuesta@eprosima.com> * Update line number for XML refs Signed-off-by: Emilio Cuesta <emiliocuesta@eprosima.com> * Last fix Signed-off-by: Emilio Cuesta <emiliocuesta@eprosima.com> --------- Signed-off-by: Emilio Cuesta <emiliocuesta@eprosima.com>
1 parent 8f50ac6 commit 04dcae8

4 files changed

Lines changed: 133 additions & 21 deletions

File tree

‎code/DDSCodeTester.cpp‎

Lines changed: 13 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -7358,7 +7358,7 @@ void dds_persistence_examples()
73587358
// Configure persistence service plugin for DomainParticipant
73597359
DomainParticipantQos pqos;
73607360
pqos.properties().properties().emplace_back("dds.persistence.plugin", "builtin.SQLITE3");
7361-
pqos.properties().properties().emplace_back("dds.persistence.sqlite3.filename", "persistence.db");
7361+
pqos.properties().properties().emplace_back("dds.persistence.sqlite3.filename", "part_persistence_service.db");
73627362
DomainParticipant* participant = DomainParticipantFactory::get_instance()->create_participant(0, pqos);
73637363

73647364
/********************************************************************************************************
@@ -7415,16 +7415,26 @@ void dds_persistence_examples()
74157415

74167416
// Configure DataWriter's durability and persistence GUID so it can use the persistence service
74177417
DataWriterQos dwqos = DATAWRITER_QOS_DEFAULT;
7418+
dwqos.history().kind = KEEP_LAST_HISTORY_QOS;
7419+
dwqos.history().depth = 20;
7420+
dwqos.reliability().kind = RELIABLE_RELIABILITY_QOS;
74187421
dwqos.durability().kind = TRANSIENT_DURABILITY_QOS;
7422+
dwqos.properties().properties().emplace_back("dds.persistence.plugin", "builtin.SQLITE3");
74197423
dwqos.properties().properties().emplace_back("dds.persistence.guid",
7420-
"77.72.69.74.65.72.5f.70.65.72.73.5f|67.75.69.64");
7424+
"77.72.69.74.65.72.5f.71.65.72.73.5f|67.75.69.64");
7425+
dwqos.properties().properties().emplace_back("dds.persistence.sqlite3.filename", "dw_persistence_service.db");
74217426
DataWriter* writer = publisher->create_datawriter(topic, dwqos);
74227427

74237428
// Configure DataReaders's durability and persistence GUID so it can use the persistence service
74247429
DataReaderQos drqos = DATAREADER_QOS_DEFAULT;
7430+
drqos.history().kind = KEEP_LAST_HISTORY_QOS;
7431+
drqos.history().depth = 20;
7432+
drqos.reliability().kind = RELIABLE_RELIABILITY_QOS;
74257433
drqos.durability().kind = TRANSIENT_DURABILITY_QOS;
7434+
drqos.properties().properties().emplace_back("dds.persistence.plugin", "builtin.SQLITE3");
74267435
drqos.properties().properties().emplace_back("dds.persistence.guid",
7427-
"72.65.61.64.65.72.5f.70.65.72.73.5f|67.75.69.64");
7436+
"77.72.69.74.65.72.5f.71.65.72.73.5f|67.75.69.65");
7437+
drqos.properties().properties().emplace_back("dds.persistence.sqlite3.filename", "dr_persistence_service.db");
74287438
DataReader* reader = subscriber->create_datareader(topic, drqos);
74297439
//!--
74307440
}

‎code/XMLTester.xml‎

Lines changed: 39 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -3591,10 +3591,10 @@
35913591
<name>dds.persistence.plugin</name>
35923592
<value>builtin.SQLITE3</value>
35933593
</property>
3594-
<!-- Database file name -->
3594+
<!-- Filename will only be used if endpoint does not define its own -->
35953595
<property>
35963596
<name>dds.persistence.sqlite3.filename</name>
3597-
<value>persistence_service.db</value>
3597+
<value>part_persistence_service.db</value>
35983598
</property>
35993599
</properties>
36003600
</propertiesPolicy>
@@ -3603,36 +3603,71 @@
36033603

36043604
<!-- DataWriter configuration -->
36053605
<data_writer profile_name="persistence_service_data_writer">
3606+
<topic>
3607+
<historyQos>
3608+
<kind>KEEP_LAST</kind>
3609+
<depth>20</depth>
3610+
</historyQos>
3611+
</topic>
36063612
<qos>
3613+
<reliability>
3614+
<kind>RELIABLE</kind>
3615+
</reliability>
36073616
<!-- Set durability to TRANSIENT_DURABILITY_QOS -->
36083617
<durability>
36093618
<kind>TRANSIENT</kind>
36103619
</durability>
36113620
</qos>
36123621
<propertiesPolicy>
36133622
<properties>
3623+
<property>
3624+
<name>dds.persistence.plugin</name>
3625+
<value>builtin.SQLITE3</value>
3626+
</property>
36143627
<!-- Persistence GUID -->
36153628
<property>
36163629
<name>dds.persistence.guid</name>
3617-
<value>77.72.69.74.65.72.5f.70.65.72.73.5f|67.75.69.64</value>
3630+
<value>77.72.69.74.65.72.5f.71.65.72.73.5f|67.75.69.64</value>
3631+
</property>
3632+
<property>
3633+
<name>dds.persistence.sqlite3.filename</name>
3634+
<value>dw_persistence_service.db</value>
36183635
</property>
36193636
</properties>
36203637
</propertiesPolicy>
36213638
</data_writer>
36223639

3640+
<!-- DataReader configuration -->
36233641
<data_reader profile_name="persistence_service_data_reader">
3642+
<topic>
3643+
<historyQos>
3644+
<kind>KEEP_LAST</kind>
3645+
<depth>20</depth>
3646+
</historyQos>
3647+
</topic>
36243648
<qos>
3649+
<reliability>
3650+
<kind>RELIABLE</kind>
3651+
</reliability>
36253652
<!-- Set durability to TRANSIENT_DURABILITY_QOS -->
36263653
<durability>
36273654
<kind>TRANSIENT</kind>
36283655
</durability>
36293656
</qos>
36303657
<propertiesPolicy>
36313658
<properties>
3659+
<property>
3660+
<name>dds.persistence.plugin</name>
3661+
<value>builtin.SQLITE3</value>
3662+
</property>
36323663
<!-- Persistence GUID -->
36333664
<property>
36343665
<name>dds.persistence.guid</name>
3635-
<value>72.65.61.64.65.72.5f.70.65.72.73.5f|67.75.69.64</value>
3666+
<value>77.72.69.74.65.72.5f.71.65.72.73.5f|67.75.69.65</value>
3667+
</property>
3668+
<property>
3669+
<name>dds.persistence.sqlite3.filename</name>
3670+
<value>dr_persistence_service.db</value>
36363671
</property>
36373672
</properties>
36383673
</propertiesPolicy>

‎docs/fastdds/persistence/persistence.rst‎

Lines changed: 28 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -29,6 +29,14 @@ in which they were when the shutdown occurred.
2929
This means that they will resume operation where they left, but they will not have the previous information, since
3030
that was already notified to the application.
3131

32+
.. note::
33+
It may be necessary to configure the history depth of the DataWriter and DataReader to a value large enough to
34+
guarantee that all the changes stored in the database are enough for a correct recovery of the application.
35+
36+
.. note::
37+
|RELIABLE_RELIABILITY_QOS-api| reliability is required to allow a full recovery, since it guarantees that all the changes are stored in
38+
the database and that they will be available for the DataWriter/DataReader upon restart.
39+
3240

3341
.. _persistence_service_conf:
3442

@@ -42,7 +50,8 @@ or DataReader) |PropertyPolicyQos|.
4250
* For the :ref:`persistence_service` to have any effect, the |DurabilityQosPolicyKind-api| needs to be set to
4351
|TRANSIENT_DURABILITY_QOS-api| or |PERSISTENT_DURABILITY_QOS-api|.
4452

45-
* A persistence identifier (|Guid_t-api|) must be set for the entity using the property ``dds.persistence.guid``.
53+
* A persistence identifier (|Guid_t-api|) must be set on the endpoint (|DataWriter-api| or
54+
|DataReader-api|) using the property ``dds.persistence.guid``.
4655
This identifier is used to load the appropriate data from the database, and also to synchronize DataWriter and
4756
DataReader between restarts.
4857
The GUID consists of 16 bytes separated into two groups:
@@ -56,8 +65,9 @@ or DataReader) |PropertyPolicyQos|.
5665
For selecting an appropriate GUID for the DataReader and DataWriter, please refer to
5766
`RTPS standard <https://www.omg.org/spec/DDSI-RTPS/2.2/PDF>`_ (section *9.3.1 The Globally Unique Identifier (GUID)*).
5867

59-
If no ``dds.persistence.guid`` is specified,
60-
the durability behavior will fallback to |TRANSIENT_LOCAL_DURABILITY_QOS-api|.
68+
This property must be defined at the endpoint level.
69+
If absent, the durability behaviour falls back to |TRANSIENT_LOCAL_DURABILITY_QOS-api|,
70+
regardless of any plugin configuration.
6171

6272
* A persistence plugin must be configured for managing the database using property ``dds.persistence.plugin`` (see
6373
:ref:`persistence_sqlite3_builtin_plugin`):
@@ -69,9 +79,9 @@ PERSISTENCE:SQLITE3 built-in plugin
6979

7080
This plugin provides persistence through a local database file using *SQLite3* API.
7181
To activate the plugin, ``dds.persistence.plugin`` property must be added to the PropertyPolicyQos of the
72-
DomainParticipant, DataWriter, or DataReader with value ``builtin.SQLITE3``.
73-
Furthermore, ``dds.persistence.sqlite3.filename`` property must be added to the entities PropertyPolicyQos,
74-
specifying the database file name.
82+
DataWriter or DataReader with value ``builtin.SQLITE3``.
83+
Optionally, ``dds.persistence.sqlite3.filename`` property can be added to the entity's PropertyPolicyQos
84+
to specify the database file name; if omitted, the default value ``persistence.db`` is used.
7585
These properties are summarized in the following table:
7686

7787
.. list-table:: **Persistence::SQLITE3 configuration properties**
@@ -87,13 +97,19 @@ These properties are summarized in the following table:
8797
Default value: ``persistence.db``
8898

8999
.. note::
90-
To avoid undesired delays caused by concurrent access to the SQLite3 database, it is advisable to specify a
91-
different database file for each DataWriter and DataReader.
100+
To avoid undesired delays caused by concurrent access to the SQLite3 database, it is strongly recommended to
101+
specify a different database file for each DataWriter and DataReader.
92102

93103
.. important::
94-
The plugin set in the PropertyPolicyQos of DomainParticipant only applies if that of the
95-
DataWriter/DataReader does no exist or is invalid.
96-
104+
``dds.persistence.plugin`` and ``dds.persistence.sqlite3.filename`` are resolved as a pair:
105+
if ``dds.persistence.plugin`` is not set at the endpoint (DataWriter/DataReader) level,
106+
both properties are taken from the |DomainParticipant-api| instead; a
107+
``dds.persistence.sqlite3.filename`` defined at the endpoint without a
108+
``dds.persistence.plugin`` at the same level is ignored.
109+
``dds.persistence.guid`` must be defined at the endpoint level; if absent, the behaviour
110+
falls back to |TRANSIENT_LOCAL_DURABILITY_QOS-api|, regardless of any plugin configuration.
111+
It is strongly recommended to set all three properties directly on the endpoint for
112+
predictable behaviour.
97113

98114
.. _persistence_example:
99115

@@ -115,7 +131,7 @@ from C++ and using *eProsima Fast DDS* XML profile files (see :ref:`xml_profiles
115131
:language: xml
116132
:start-after: <!-->CONF-PERSISTENCE-SERVICE-SQLITE3-EXAMPLE<-->
117133
:end-before: <!--><-->
118-
:lines: 2-4, 6-61, 63-64
134+
:lines: 2-4, 6-96, 98-99
119135

120136
.. note::
121137
For instructions on how to create DomainParticipants, DataReaders, and DataWriters, please refer to

‎docs/fastdds/property_policies/persistence.rst‎

Lines changed: 53 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -6,5 +6,56 @@
66
Persistence Service Settings
77
----------------------------
88

9-
.. warning::
10-
This section is still under work.
9+
When using the :ref:`persistence_service`, the following properties must be set on the
10+
|DomainParticipant-api|, |DataWriter-api|, or |DataReader-api| via their |PropertyPolicyQos|.
11+
12+
.. important::
13+
14+
It is strongly recommended to define all three properties at the endpoint
15+
(|DataWriter-api| or |DataReader-api|) level for predictable behaviour.
16+
``dds.persistence.plugin`` and ``dds.persistence.sqlite3.filename`` are resolved
17+
as a pair from the first level where ``dds.persistence.plugin`` is present
18+
(endpoint first, then |DomainParticipant-api|); a ``dds.persistence.sqlite3.filename``
19+
defined at the endpoint level without a ``dds.persistence.plugin`` at the same level
20+
is ignored.
21+
``dds.persistence.guid`` must be defined at the endpoint level; if absent, the behaviour
22+
falls back to |TRANSIENT_LOCAL_DURABILITY_QOS-api|, regardless of any plugin configuration.
23+
24+
* Property ``dds.persistence.plugin`` selects the persistence plugin to use.
25+
It can be set on the |DomainParticipant-api|, a |DataWriter-api|, or a |DataReader-api|.
26+
If this property is absent at the endpoint level, both ``dds.persistence.plugin`` and
27+
``dds.persistence.sqlite3.filename`` are taken from the |DomainParticipant-api| instead.
28+
Setting it at the endpoint level is strongly recommended.
29+
At the moment, the only valid value is ``builtin.SQLITE3``
30+
(see :ref:`persistence_sqlite3_builtin_plugin`).
31+
32+
* Property ``dds.persistence.sqlite3.filename`` specifies the path to the SQLite3 database
33+
file used for persistent storage when the SQLite3 plugin is used.
34+
This property is optional; the default value is ``persistence.db``.
35+
To avoid undesired delays caused by concurrent access, it is advisable to use a different
36+
database file for each DataWriter and DataReader.
37+
38+
* Property ``dds.persistence.guid`` sets the persistence identifier (|Guid_t-api|) for a
39+
DataWriter or DataReader.
40+
This identifier is used to load the appropriate data from the database and to synchronize
41+
the entity between restarts.
42+
This property must be defined at the endpoint level.
43+
If absent, the durability behaviour falls back to |TRANSIENT_LOCAL_DURABILITY_QOS-api|,
44+
regardless of any plugin configuration.
45+
46+
The following example shows how to configure the persistence service properties along with the
47+
required QoS settings for a correct operation of the service (see :ref:`persistence_example`).
48+
49+
.. tab-set-code::
50+
51+
.. literalinclude:: /../code/DDSCodeTester.cpp
52+
:language: c++
53+
:start-after: //CONF-PERSISTENCE-SERVICE-SQLITE3-EXAMPLE
54+
:end-before: //!--
55+
:dedent: 4
56+
57+
.. literalinclude:: /../code/XMLTester.xml
58+
:language: xml
59+
:start-after: <!-->CONF-PERSISTENCE-SERVICE-SQLITE3-EXAMPLE<-->
60+
:end-before: <!--><-->
61+
:lines: 2-4, 6-96, 98-99

0 commit comments

Comments
 (0)