Merge branch 'feature/persistence' into 'master'

Refs #2721. Persistence documentation See merge request eProsima/fastrtps-docs!4
eProsima · Jun 7, 2018 · edb62f7 · edb62f7
2 parents 0ab5173 + 7d72112
commit edb62f7
Show file tree

Hide file tree

Showing 6 changed files with 110 additions and 6 deletions.
diff --git a/docs/advanced.rst b/docs/advanced.rst
@@ -253,7 +253,7 @@ The full list of fields for readers and writers includes the following parameter
     - name: text value.
     - data type: text value.
     - kind: text value.
-* **durabilityQos**: *VOLATILE_DURABILITY_QOS* or *TRANSIENT_LOCAL_DURABILITY_QOS*.
+* **durabilityQos**: *VOLATILE_DURABILITY_QOS*, *TRANSIENT_LOCAL_DURABILITY_QOS* or *TRANSIENT_DURABILITY_QOS*.
 * **ownershipQos**
     - kind: *SHARED_OWNERSHIP_QOS* or *EXCLUSIVE_OWNERSHIP_QOS*.
 * **partitionQos**: text value.
@@ -428,4 +428,4 @@ These examples come with their own `Readme.txt` that explains how the implementa
 
 
 This marks the end of this document. We recommend you to take a look at the doxygen API reference and
-the embedded examples that come with the distribution. If you need more help, send us an email it `support@eprosima.com`.
+the embedded examples that come with the distribution. If you need more help, send us an email to `support@eprosima.com`.
diff --git a/docs/conf.py b/docs/conf.py
@@ -49,7 +49,7 @@
 
 # General information about the project.
 project = u'Fast RTPS'
-copyright = u'2016, eProsima'
+copyright = u'2018, eProsima'
 author = u'eProsima'
 
 # The version info for the project you're documenting, acts as replacement for

diff --git a/docs/index.rst b/docs/index.rst
@@ -57,6 +57,7 @@ This documentation is organized into the following sections:
    rtps
    advanced
    security
+   persistence
    fastrtpsgen
 
 

diff --git a/docs/persistence.rst b/docs/persistence.rst
@@ -0,0 +1,102 @@
+.. |br| raw:: html
+
+   <br />
+
+.. _persistence:
+
+Persistence
+===========
+
+Fast RTPS can be configured to provide persistence to the history of a writer 
+and the highest sequence number notified by a reader.
+
+We recommend you to look at the example of how to use this feature the distribution comes with while reading
+this section. It is located in `examples/RTPSTest_persistent`
+
+You can select and configure the persistence plugin through :class:`eprosima::fastrtps::rtps::RTPSParticipant` attributes using properties.
+A :class:`eprosima::fastrtps::rtps::Property` is defined by its name (:class:`std::string`) and its value (:class:`std::string`).
+Throughout this page there are tables showing you the properties used by each persistence plugin.
+
+Configuration
+-------------
+
+In order for the persistence service to work, some specific :class:`eprosima::fastrtps::rtps::Writer` or
+:class:`eprosima::fastrtps::rtps::Reader` attributes should be set:
+
+* ``durabilityKind`` should be set to ``TRANSIENT``
+* ``persistence_guid`` should not be all zeros
+* A persistence plugin should be configured either on the :class:`eprosima::fastrtps::rtps::Writer`, the :class:`eprosima::fastrtps::rtps::Reader` or the :class:`eprosima::fastrtps::rtps::RTPSParticipant`
+
+Built-in plugins
+----------------
+
+Current version comes out with one persistence built-in plugin:
+
+* **SQLITE3**: this plugin provides persistence on a local file using SQLite3 API.
+
+.. _persistence-sqlite3:
+
+PERSISTENCE:SQLITE3
+^^^^^^^^^^^^^^^^^^^
+
+This built-in plugin provides persistence on a local file using SQLite3 API.
+
+You can activate this plugin using RTPSParticipant, Reader or Writer property ``dds.persistence.plugin`` with the value ``builtin.SQLITE3``.
+Next table shows you the properties used by this persistence plugin.
+
+.. list-table:: **Properties to configure Persistence::SQLITE3**
+   :header-rows: 1
+   :align: left
+
+   * - Property name |br|
+       (all properties have "dds.persistence.sqlite3." prefix)
+     - Property value
+   * - filename
+     - Name of the file used for persistent storage. |br|
+       Default value: *persistence.db*
+
+Example
+^^^^^^^
+
+This example shows you how to configure a RTPSParticipant to activate and configure :ref:`persistence-sqlite3` plugin.
+It also configures a Writer to persist its history on local storage, and a Reader to persist the highest notified
+sequence number on local storage.
+
+**RTPSParticipant attributes**
+
+.. code-block:: c++
+
+   eprosima::fastrtps::rtps::RTPSParticipantAttributes part_attr;
+
+   // Activate Persistence:SQLITE3 plugin
+   part_attr.properties.properties().emplace_back("dds.persistence.plugin", "builtin.SQLITE3");
+
+   // Configure Persistence:SQLITE3 plugin
+   part_attr.properties.properties().emplace_back("dds.persistence.sqlite3.filename", "example.db");
+
+**Writer attributes**
+
+.. code-block:: c++
+
+   eprosima::fastrtps::rtps::WriterAttributes writer_attr;
+
+   // Set durability to TRANSIENT
+   writer_attr.endpoint.durabilityKind = TRANSIENT;
+
+   // Set persistence_guid
+   writer_attr.endpoint.persistence_guid.guidPrefix.value[11] = 1;
+   writer_attr.endpoint.persistence_guid.entityId = 0x12345678;
+
+**Reader attributes**
+
+.. code-block:: c++
+
+   eprosima::fastrtps::rtps::ReaderAttributes reader_attr;
+
+   // Set durability to TRANSIENT
+   reader_attr.endpoint.durabilityKind = TRANSIENT;
+
+   // Set persistence_guid
+   reader_attr.endpoint.persistence_guid.guidPrefix.value[11] = 1;
+   reader_attr.endpoint.persistence_guid.entityId = 0x3456789A;
+
diff --git a/docs/pubsub.rst b/docs/pubsub.rst
@@ -311,8 +311,8 @@ Durability configuration of the endpoint defines how it behaves regarding sample
 subscriber joins
 
    * Volatile: Past samples are ignored, a joining subscriber receives samples generated after the moment it matches.
-
    * Transient Local (Default): When a new subscriber joins, its History is filled with past samples.
+   * Transient: When a new subscriber joins, its History is filled with past samples, which are stored on persistent storage (see :ref:`persistence`).
 
    +--------------------------------------------+----------------------------------------------------------+
    | C++                                        | XML                                                      |

diff --git a/docs/rtps.rst b/docs/rtps.rst
@@ -154,10 +154,11 @@ For example, you can set a Writer or a Reader as a Reliable or Best-Effort endpo
 Setting the data durability kind
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-The Durability parameter defines the behaviour of the Writer regarding samples already sent when a new Reader matches. *eProsima Fast RTPS* offers two Durability options:
+The Durability parameter defines the behaviour of the Writer regarding samples already sent when a new Reader matches. *eProsima Fast RTPS* offers three Durability options:
 
 * VOLATILE (default): Messages are discarded as they are sent. If a new Reader matches after message *n*, it will start received from message *n+1*.
 * TRANSIENT_LOCAL: The Writer saves a record of the lask *k* messages it has sent. If a new reader matches after message *n*, it will start receiving from message *n-k*
+* TRANSIENT: As TRANSIENT_LOCAL, but the record of messages will be saved to persistent storage, so it will be available if the writer is destroyed and recreated, or in case of an application crash (see :ref:`persistence`)
 
 To choose your preferred option:
 
@@ -166,7 +167,7 @@ To choose your preferred option:
     WriterAttributes Wparams;
     Wparams.endpoint.durabilityKind = TRANSIENT_LOCAL;
 
-Because in the Writer-Reader layer you have control over the History, in TRANSIENT_LOCAL mode the Writer send all changes you have not explicitly released from the History.
+Because in the Writer-Reader layer you have control over the History, in TRANSIENT_LOCAL and TRANSIENT modes the Writer sends all changes you have not explicitly released from the History.
 
 Configuring the History
 -----------------------