From c9272b2a70d77777b56731ac6fa10b821da61050 Mon Sep 17 00:00:00 2001 From: Raquel Alvarez Date: Tue, 25 Jun 2019 16:31:51 +0200 Subject: [PATCH 1/3] Adding liveliness documentation [5731] (#37) * Refs #5290 Adding liveliness documentation * Refs #5290 Fixing line too long error * Refs #5290 Fixing spelling * Refs #5290 Fixing code tester * Update docs/pubsub.rst Co-Authored-By: Luis Gasco * Update docs/pubsub.rst Co-Authored-By: Luis Gasco * Refs #5290 Addressing review comments * Update docs/pubsub.rst Co-Authored-By: Luis Gasco --- code/CodeTester.cpp | 9 ++++ code/XMLTester.xml | 35 +++++++++++++- docs/fullxmloptions.xml | 6 +-- docs/pubsub.rst | 66 ++++++++++++++++++++++++- docs/xmlprofiles.rst | 103 ++++++++++++++-------------------------- 5 files changed, 145 insertions(+), 74 deletions(-) diff --git a/code/CodeTester.cpp b/code/CodeTester.cpp index d40ef5e2e..f9c75d9e5 100644 --- a/code/CodeTester.cpp +++ b/code/CodeTester.cpp @@ -644,6 +644,15 @@ publisher_attr.qos.m_disablePositiveACKs.duration = 1; subscriber_attr.qos.m_disablePositiveACKs.enabled = true; //!-- +//PUBSUB_API_CONF_PUBSUB_LIVELINESS +publisher_attr.qos.m_liveliness.announcement_period = 0.5; +publisher_attr.qos.m_liveliness.lease_duration = 1; +publisher_attr.qos.m_liveliness.kind = AUTOMATIC_LIVELINESS_QOS; + +subscriber_attr.qos.m_liveliness.lease_duration = 1; +subscriber_attr.qos.m_liveliness.kind = AUTOMATIC_LIVELINESS_QOS; +//!-- + //PUBSUB_API_CONF_PUBSUB_RESOURCE_LIMITS publisher_attr.topic.resourceLimitsQos.max_samples = 200; diff --git a/code/XMLTester.xml b/code/XMLTester.xml index 29243ac9f..b35c8356b 100644 --- a/code/XMLTester.xml +++ b/code/XMLTester.xml @@ -177,6 +177,34 @@ <--> +PUBSUB_API_CONF_PUBSUB_LIVELINESS<--> + + + + + 0 + 1000000 + + + 1 + + AUTOMATIC + + + + + + + + + 1 + + AUTOMATIC + + + +<--> + PUBSUB_API_CONF_PUBSUB_RESOURCE_LIMITS<--> @@ -1153,8 +1181,13 @@ - AUTOMATIC + + 1 + + + 1 + diff --git a/docs/fullxmloptions.xml b/docs/fullxmloptions.xml index fdb45924a..0509d9195 100644 --- a/docs/fullxmloptions.xml +++ b/docs/fullxmloptions.xml @@ -287,10 +287,10 @@ AUTOMATIC - + 500 0 - + DURATION_INFINITY @@ -496,4 +496,4 @@ 66 - \ No newline at end of file + diff --git a/docs/pubsub.rst b/docs/pubsub.rst index 2286ccc4d..8a9ebd4fa 100644 --- a/docs/pubsub.rst +++ b/docs/pubsub.rst @@ -370,6 +370,66 @@ When the lifespan period expires, data is removed from the history. | :end-before: <--> | +---------------------------------------------------------+ +.. _liveliness-qos: + +Liveliness +********** + +Liveliness is a quality of service that can be used to ensure that particular entities on the network are "alive". +There are different settings that allow distinguishing between applications where data is updated periodically and +applications where data is changed sporadically. It also allows customizing the application regarding the kind of +failures that should be detected by the liveliness mechanism. + +The AUTOMATIC liveliness kind is suitable for applications that only need to detect whether a remote application +is still running. Therefore, as long as the local process where the participant is running and the link connecting +it to remote participants exists, the entities within the remote participant will be considered alive. + +The two manual settings require that liveliness is asserted periodically on the publishing side to consider that remote +entities are alive. Liveliness can be asserted explicitly by calling the *assert_liveliness* operations on the +publisher, or implicitly by writing data. The MANUAL_BY_PARTICIPANT setting only requires that one entity in the +publishing side asserts liveliness to deduce that all other entities within that participant are also alive. The +MANUAL_BY_TOPIC mode is more restrictive and requires that at least one instance within the publisher is asserted to +consider that the publisher is alive. + +Besides the liveliness kind, two additional parameters allow defining the application behavior. They are all listed +in the table below. + ++---------------------------+----------------------------------+---------------------------+-------------------------+ +| Name | Description | Values | Default | ++===========================+==================================+===========================+=========================+ +| ```` | Specifies how | :class:`AUTOMATIC`, | :class:`AUTOMATIC` | +| | to manage liveliness. | :class:`MANUAL_BY_TOPIC`, | | +| | | :class:`MANUAL_BY_TOPIC` | | ++---------------------------+----------------------------------+---------------------------+-------------------------+ +| ```` | Amount of time to wait since the | :ref:`DurationType` | :class:`c_TimeInfinite` | +| | last message from a writer to | | | +| | consider that it is no longer | | | +| | alive. | | | ++---------------------------+----------------------------------+---------------------------+-------------------------+ +| ```` | Amount of time between | :ref:`DurationType` | :class:`c_TimeInfinite` | +| | consecutive liveliness messages | | | +| | sent by the publisher. Only used | | | +| | for AUTOMATIC and | | | +| | MANUAL_BY_PARTICIPANT liveliness | | | +| | kinds. | | | ++---------------------------+----------------------------------+---------------------------+-------------------------+ + ++--------------------------------------------------------------+ +| **C++** | ++--------------------------------------------------------------+ +| .. literalinclude:: ../code/CodeTester.cpp | +| :language: c++ | +| :start-after: //PUBSUB_API_CONF_PUBSUB_LIVELINESS | +| :end-before: //!-- | ++--------------------------------------------------------------+ +| **XML** | ++--------------------------------------------------------------+ +| .. literalinclude:: ../code/XMLTester.xml | +| :language: xml | +| :start-after: PUBSUB_API_CONF_PUBSUB_LIVELINESS | +| :end-before: <--> | ++--------------------------------------------------------------+ + .. _resourceLimits-qos: Resource limits @@ -534,5 +594,7 @@ the possible callbacks that can be implemented in both cases: +---------------------------------+-----------+------------+ | `on_requested_deadline_missed` | N | Y | +---------------------------------+-----------+------------+ - - +| `on_liveliness_lost` | Y | N | ++---------------------------------+-----------+------------+ +| `on_liveliness_changed` | N | Y | ++---------------------------------+-----------+------------+ diff --git a/docs/xmlprofiles.rst b/docs/xmlprofiles.rst index c1e19766e..53b719b6e 100644 --- a/docs/xmlprofiles.rst +++ b/docs/xmlprofiles.rst @@ -709,9 +709,9 @@ This section of the :class:`Participant's rtps` configuration allows defining bu | ```` | DomainId to be used by | ``UInt32`` | 0 | | | the RTPSParticipant. | | | +---------------------------+---------------------------------------+-------------------------+-----------------------+ -| ```` | Indicates how much time remote | :ref:`DurationType` | 130 s | -| | RTPSParticipants should consider this | | | -| | RTPSParticipant alive. | | | +| ```` | Indicates how long this | :ref:`DurationType` | 130 s | +| | RTPSParticipant should consider | | | +| | remote RTPSParticipants alive. | | | +---------------------------+---------------------------------------+-------------------------+-----------------------+ | ```` | The period for the RTPSParticipant | :ref:`DurationType` | 40 s | | | to send its Discovery Message to all | | | @@ -1149,40 +1149,38 @@ The quality of service (QoS) handles the restrictions applied to the application :start-after: XML-QOS<--> :end-before: <--> -+--------------------------+----------------------------------+-------------------------+-------------------------+ -| Name | Description | Values | Default | -+==========================+==================================+=========================+=========================+ -| ```` | It is defined in |:class:`VOLATILE`, | :class:`VOLATILE` | -| | :ref:`SettingDataDurability` |:class:`TRANSIENT_LOCAL` | | -| | section. |:class:`TRANSIENT` | | -| | | | | -+--------------------------+----------------------------------+-------------------------+-------------------------+ -| ```` | Defines the liveliness of the | :ref:`LivelinessType` | | -| | participant. | | | -+--------------------------+----------------------------------+-------------------------+-------------------------+ -| ```` | It is defined in | :class:`RELIABLE`, | :class:`RELIABLE` | -| | :ref:`reliability` section. | :class:`BEST_EFFORT` | | -| | | | | -| | | | | -+--------------------------+----------------------------------+-------------------------+-------------------------+ -| ```` | It allows the introduction of | | ``List `` | -| | a logical partition concept | | | -| | inside the `physical` partition | | | -| | induced by a domain. | | | -+--------------------------+----------------------------------+-------------------------+-------------------------+ -| ```` | It is defined in | | | -| | :ref:`deadline-qos` | Deadline period as a | :class:`c_TimeInfinite` | -| | section. | :ref:`DurationType` | | -+--------------------------+----------------------------------+-------------------------+-------------------------+ -| ```` | It is defined in | Lifespan duration as a | :class:`c_TimeInfinite` | -| | :ref:`lifespan-qos` section. | :ref:`DurationType` | | -+--------------------------+----------------------------------+-------------------------+-------------------------+ -| ````| It is defined in | | It is disabled by | -| | section | | default and | -| | :ref:`disable-positive-acks-qos` | | ``duration`` is set | -| | | | to | -| | | | :class:`c_TimeInfinite` | -+--------------------------+----------------------------------+-------------------------+-------------------------+ ++--------------------------+----------------------------------+-------------------------------+------------------------+ +| Name | Description | Values | Default | ++==========================+==================================+===============================+========================+ +| ```` | It is defined in |:class:`VOLATILE`, | :class:`VOLATILE` | +| | :ref:`SettingDataDurability` |:class:`TRANSIENT_LOCAL` | | +| | section. |:class:`TRANSIENT` | | +| | | | | ++--------------------------+----------------------------------+-------------------------------+------------------------+ +| ```` | Defines the liveliness of the | :ref:`liveliness-qos` | | +| | publisher. | | | ++--------------------------+----------------------------------+-------------------------------+------------------------+ +| ```` | It is defined in | :class:`RELIABLE`, | :class:`RELIABLE` | +| | :ref:`reliability` section. | :class:`BEST_EFFORT` | | ++--------------------------+----------------------------------+-------------------------------+------------------------+ +| ```` | It allows the introduction of | | ``List `` | +| | a logical partition concept | | | +| | inside the `physical` partition | | | +| | induced by a domain. | | | ++--------------------------+----------------------------------+-------------------------------+------------------------+ +| ```` | It is defined in | | | +| | :ref:`deadline-qos` | Deadline period as a | :class:`c_TimeInfinite`| +| | section. | :ref:`DurationType` | | ++--------------------------+----------------------------------+-------------------------------+------------------------+ +| ```` | It is defined in | Lifespan duration as a | :class:`c_TimeInfinite`| +| | :ref:`lifespan-qos` section. | :ref:`DurationType` | | ++--------------------------+----------------------------------+-------------------------------+------------------------+ +| ````| It is defined in | | It is disabled by | +| | section | | default and | +| | :ref:`disable-positive-acks-qos` | | ``duration`` is set | +| | | | to | +| | | | :class:`c_TimeInfinite`| ++--------------------------+----------------------------------+-------------------------------+------------------------+ .. .. note:: @@ -1240,37 +1238,6 @@ The quality of service (QoS) handles the restrictions applied to the application - ````: Allows establishing the maximum number of samples per history instance. -.. _LivelinessType: - -LivelinessType -^^^^^^^^^^^^^^ - -This parameter defines who is responsible for issues of liveliness packets. - -.. literalinclude:: ../code/XMLTester.xml - :language: xml - :start-after: XML-LIVELINESS<--> - :end-before: <--> - - -+---------------------------+----------------------------------+---------------------------+--------------------+ -| Name | Description | Values | Default | -+===========================+==================================+===========================+====================+ -| ```` | Specifies how | :class:`AUTOMATIC`, | :class:`AUTOMATIC` | -| | to manage liveliness. | :class:`MANUAL_BY_TOPIC`, | | -| | | :class:`MANUAL_BY_TOPIC` | | -+---------------------------+----------------------------------+---------------------------+--------------------+ -| ```` | Amount of time that the remote | :ref:`DurationType` | 130 s | -| | RTPSParticipants should consider | | | -| | this RTPSParticipant to be alive | | | -| | since the last message. | | | -+---------------------------+----------------------------------+---------------------------+--------------------+ -| ```` | The period to send its Discovery | :ref:`DurationType` | 40 s | -| | Message to all other | | | -| | discovered RTPSParticipants as | | | -| | well as to all Multicast ports. | | | -+---------------------------+----------------------------------+---------------------------+--------------------+ - .. _Throughput: Throughput Configuration From 53c336ac0727d74233ba56b0b22e5dbd8875e728 Mon Sep 17 00:00:00 2001 From: Miguel Company Date: Wed, 26 Jun 2019 08:49:44 +0200 Subject: [PATCH 2/3] Refs #5759. Bump version to 1.8.1 --- docs/conf.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index b929cae75..bee63850c 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -68,9 +68,9 @@ # built documents. # # The short X.Y version. -version = u'1.8.0' +version = u'1.8.1' # The full version, including alpha/beta/rc tags. -release = u'1.8.0' +release = u'1.8.1' # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. From 404757306aab5a406e225f0fd59647adbc4583a2 Mon Sep 17 00:00:00 2001 From: Raquel Alvarez Date: Wed, 26 Jun 2019 12:02:47 +0200 Subject: [PATCH 3/3] Adds release notes for v1.8.1 (#38) * Refs #5759 Adding release notes * Refs #5759 Updating DurationType documentation * Refs #5759 Updates to release notes * Review suggestions Co-Authored-By: MiguelCompany --- docs/notes.rst | 28 ++++++++++++++++++++++++---- docs/xmlprofiles.rst | 13 ++++--------- 2 files changed, 28 insertions(+), 13 deletions(-) diff --git a/docs/notes.rst b/docs/notes.rst index 269d5cbd0..fb716a885 100644 --- a/docs/notes.rst +++ b/docs/notes.rst @@ -1,8 +1,31 @@ -Version 1.8.0 +Version 1.8.1 ============= This release includes the following features: +* Implementation of :ref:`liveliness-qos` QoS + +It also adds the following bug fixes and improvements: + +* Fix for get_change on history, which was causing issues during discovery +* Fix for announcement of participant state, which was sending ParticipantBuiltinData twice +* Fix for closing multicast UDP channel +* Fix for race conditions in SubscriberHistory, UDPTransportInterface and StatefulReader +* Fix for lroundl error on Windows in Time_t +* CDR & IDL submodules update +* Use of java 1.8 or greater for fastrtpsgen.jar generation + +**Note:** If you are upgrading from a version older than 1.7.0, it is **required** to regenerate generated source +from IDL files using *fastrtpsgen* + +Previous versions +----------------- + +Version 1.8.0 +^^^^^^^^^^^^^ + +This release included the following features: + * Implementation of IDL 4.2 * Implementation of :ref:`deadline-qos` QoS * Implementation of :ref:`lifespan-qos` QoS @@ -33,9 +56,6 @@ It also adds the following improvements and bug fixes: **Note:** If you are upgrading from a version older than 1.7.0, it is **required** to regenerate generated source from IDL files using *fastrtpsgen* -Previous versions ------------------ - Version 1.7.2 ^^^^^^^^^^^^^ diff --git a/docs/xmlprofiles.rst b/docs/xmlprofiles.rst index 53b719b6e..30aeab41b 100644 --- a/docs/xmlprofiles.rst +++ b/docs/xmlprofiles.rst @@ -1029,19 +1029,14 @@ Instead, it is used inside other configuration parameter labels that give it sen :start-after: XML-DURATION<--> :end-before: <--> -Duration time can be defined through a constant value directly (:class:`INFINITE`, :class:`ZERO`, or :class:`INVALID`), -or by ```` plus ```` labels: - -- :class:`INFINITE`: Constant value, represents an infinite period of time. - -- :class:`ZERO`: Constant value, represents 0.0 seconds. - -- :class:`INVALID`: Constant value, represents an invalid period of time. +Duration time can be defined through ```` plus ```` labels (see table below). An infinite value can be +specified by using the values :class:`DURATION_INFINITY`, :class:`DURATION_INFINITE_SEC` and +:class:`DURATION_INFINITE_NSEC`. +----------------+-----------------------------------------------------------------+------------+---------+ | Name | Description | Values | Default | +================+=================================================================+============+=========+ -| ```` | Number of seconds. | ``Int32`` | 0 | +| ```` | Number of seconds. | ``Int32`` | 0 | +----------------+-----------------------------------------------------------------+------------+---------+ | ```` | Number of nanoseconds. | ``UInt32`` | 0 | +----------------+-----------------------------------------------------------------+------------+---------+