From ecbd21acedcc5a53b7c209a255f1a83a9c0a2450 Mon Sep 17 00:00:00 2001
From: MiguelCompany <miguelcompany@eprosima.com>
Date: Fri, 15 Feb 2019 09:18:54 +0100
Subject: [PATCH] Added documentation for matchedSubscribersAllocation [4572]
 (#19)

* Refs #4572. Added documentation for matchedSubscribersAllocation.

* Refs #4572. Fixing linters.

* Refs #4572. Fixing linters.

* Refs #4572. Apply suggestions from code review

Co-Authored-By: MiguelCompany <miguelcompany@eprosima.com>
---
 code/XMLTester.xml   |   7 +++
 docs/xmlprofiles.rst | 128 +++++++++++++++++++++++++++++--------------
 2 files changed, 93 insertions(+), 42 deletions(-)

diff --git a/code/XMLTester.xml b/code/XMLTester.xml
index 18aa660d4..9eeda4511 100644
--- a/code/XMLTester.xml
+++ b/code/XMLTester.xml
@@ -783,6 +783,13 @@
     <userDefinedID>55</userDefinedID> <!-- Int16 -->
 
     <entityID>66</entityID> <!-- Int16 -->
+
+    <matchedSubscribersAllocation>
+        <initial>0</initial> <!-- uint32 -->
+        <maximum>0</maximum> <!-- uint32 -->
+        <increment>1</increment> <!-- uint32 -->
+    </matchedSubscribersAllocation>
+
 </publisher>
 <!--><-->
 <!-->XML-SUBSCRIBER<-->
diff --git a/docs/xmlprofiles.rst b/docs/xmlprofiles.rst
index 0edefc57a..00d08f8bd 100644
--- a/docs/xmlprofiles.rst
+++ b/docs/xmlprofiles.rst
@@ -646,48 +646,59 @@ as shown in the :ref:`loadingapplyingprofiles` section.
 
     - :class:`TOPIC_TYPE` is detailed in section :ref:`TopicType`.
 
-+----------------------------+---------------------------+-------------------------------------+-----------------------+
-| Name                       | Description               | Values                              | Default               |
-+============================+===========================+=====================================+=======================+
-| ``<topic>``                | :ref:`TopicType`          | :ref:`TopicType`                    |                       |
-|                            | configuration of the      |                                     |                       |
-|                            | publisher.                |                                     |                       |
-+----------------------------+---------------------------+-------------------------------------+-----------------------+
-| ``<qos>``                  | Publisher                 | :ref:`CommonQOS`                    |                       |
-|                            | :ref:`CommonQOS`          |                                     |                       |
-|                            | configuration.            |                                     |                       |
-+----------------------------+---------------------------+-------------------------------------+-----------------------+
-| ``<times>``                | It allows configuring     | :ref:`Times <pubtimes>`             |                       |
-|                            | some time related         |                                     |                       |
-|                            | parameters of the         |                                     |                       |
-|                            | publisher.                |                                     |                       |
-+----------------------------+---------------------------+-------------------------------------+-----------------------+
-| ``<unicastLocatorList>``   | List of input unicast     | List of :ref:`LocatorListType`      |                       |
-|                            | locators. It expects      |                                     |                       |
-|                            | a :ref:`LocatorListType`. |                                     |                       |
-+----------------------------+---------------------------+-------------------------------------+-----------------------+
-| ``<multicastLocatorList>`` | List of input multicast   | List of :ref:`LocatorListType`      |                       |
-|                            | locators. It expects      |                                     |                       |
-|                            | a :ref:`LocatorListType`. |                                     |                       |
-+----------------------------+---------------------------+-------------------------------------+-----------------------+
-| ``<throughputController>`` | Limits the output         | `Throughput`_                       |                       |
-|                            | bandwidth of              |                                     |                       |
-|                            | the publisher.            |                                     |                       |
-+----------------------------+---------------------------+-------------------------------------+-----------------------+
-| ``<historyMemoryPolicy>``  | Memory allocation kind    | :class:`PREALLOCATED`,              | :class:`PREALLOCATED` |
-|                            | for publisher's history.  | :class:`PREALLOCATED_WITH_REALLOC`, |                       |
-|                            |                           | :class:`DYNAMIC`                    |                       |
-|                            |                           |                                     |                       |
-+----------------------------+---------------------------+-------------------------------------+-----------------------+
-| ``<propertiesPolicy>``     | Additional configuration  | :ref:`PropertiesPolicyType`         |                       |
-|                            | properties.               |                                     |                       |
-+----------------------------+---------------------------+-------------------------------------+-----------------------+
-| ``<userDefinedID>``        | Used for                  | ``Int16``                           | -1                    |
-|                            | StaticEndpointDiscovery.  |                                     |                       |
-+----------------------------+---------------------------+-------------------------------------+-----------------------+
-| ``<entityID>``             | EntityId of the           | ``Int16``                           | -1                    |
-|                            | *endpoint*.               |                                     |                       |
-+----------------------------+---------------------------+-------------------------------------+-----------------------+
+
+.. list-table::
+   :header-rows: 1
+   :align: left
+
+   * - Name
+     - Description
+     - Values
+     - Default
+   * - ``<topic>``
+     - :ref:`TopicType` configuration of the publisher.
+     - :ref:`TopicType`
+     -
+   * - ``<qos>``
+     - Publisher :ref:`CommonQOS` configuration.
+     - :ref:`CommonQOS`
+     -
+   * - ``<times>``
+     - It allows configuring some time related parameters of the publisher.
+     - :ref:`Times <pubtimes>`
+     -
+   * - ``<unicastLocatorList>``
+     - List of input unicast locators. It expects a :ref:`LocatorListType`.
+     - List of :ref:`LocatorListType`
+     -
+   * - ``<multicastLocatorList>``
+     - List of input multicast locators. It expects a :ref:`LocatorListType`.
+     - List of :ref:`LocatorListType`
+     -
+   * - ``<throughputController>``
+     - Limits the output bandwidth of the publisher.
+     - `Throughput`_
+     -
+   * - ``<historyMemoryPolicy>``
+     - Memory allocation kind for publisher's history.
+     - :class:`PREALLOCATED`, :class:`PREALLOCATED_WITH_REALLOC`, :class:`DYNAMIC`
+     - :class:`PREALLOCATED`
+   * - ``<propertiesPolicy>``
+     - Additional configuration properties.
+     - :ref:`PropertiesPolicyType`
+     -
+   * - ``<userDefinedID>``
+     - Used for StaticEndpointDiscovery.
+     - ``Int16``
+     - -1
+   * - ``<entityID>``
+     - EntityId of the *endpoint*.
+     - ``Int16``
+     - -1
+   * - ``<matchedSubscribersAllocation>``
+     - Publisher :ref:`CommonAlloc` related to the number of matched subscribers.
+     - :ref:`CommonAlloc`
+     -
 
 .. _pubtimes:
 
@@ -1127,6 +1138,39 @@ Throughput Configuration allows to limit the output bandwidth.
 |                       | bytes are allowed.                                        |            |            |
 +-----------------------+-----------------------------------------------------------+------------+------------+
 
+.. _CommonAlloc:
+
+Allocation Configuration
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+Allocation Configuration allows to control the allocation behavior of internal collections for which the number
+of elements depends on the number of entities in the system.
+
+For instance, there are collections inside a publisher which depend on the number of subscribers matching with it.
+
+.. TODO: Add reference to allocation tuning section
+
+.. list-table::
+   :header-rows: 1
+   :align: left
+
+   * - Name
+     - Description
+     - Values
+     - Default
+   * - ``<initial>``
+     - Number of elements for which space is initially allocated.
+     - ``UInt32``
+     - 0
+   * - ``<maximum>``
+     - Maximum number of elements for which space will be allocated.
+     - ``UInt32``
+     - 0 (means no limit)
+   * - ``<increment>``
+     - Number of new elements that will be allocated when more space is necessary.
+     - ``UInt32``
+     - 1
+
 .. _examplexml:
 
 Example