Update shared_mutex docs (#413)

* Refs 15766: update shared_mutex docs Signed-off-by: Miguel Barro <miguelbarro@eprosima.com> * Refs 15766: fixing typos to pass CI Signed-off-by: Miguel Barro <miguelbarro@eprosima.com> * Refs 15766: addressing reviewer's comments Signed-off-by: Miguel Barro <miguelbarro@eprosima.com> Signed-off-by: Miguel Barro <miguelbarro@eprosima.com>
eProsima · Nov 14, 2022 · f56f5ed · f56f5ed
1 parent f43925b
commit f56f5ed
Show file tree

Hide file tree

Showing 2 changed files with 21 additions and 8 deletions.
diff --git a/docs/conf.py b/docs/conf.py
@@ -86,10 +86,10 @@ def select_css(html_css_dir):
     common_css = '_static/css/eprosima_rtd_theme.css'
     local_css = '_static/css/fiware_readthedocs.css'
     if download_css(html_css_dir):
-        print('Appliying common CSS style file: {}'.format(common_css))
+        print('Applying common CSS style file: {}'.format(common_css))
         ret.append(common_css)
     else:
-        print('Appliying local CSS style file: {}'.format(local_css))
+        print('Applying local CSS style file: {}'.format(local_css))
         ret.append(local_css)
 
     return ret

diff --git a/docs/installation/configuration/cmake_options.rst b/docs/installation/configuration/cmake_options.rst
@@ -126,11 +126,24 @@ dependency on other options.
         - ``ON`` ``OFF``
         - ``OFF``
     *   - :class:`USE_THIRDPARTY_SHARED_MUTEX`
-        - When ``ON`` a Boost-like implementation of ``shared_mutex`` is used instead of |br|
-          the STL one. This flag prevents thread sanitizer reports on GCC/Clang STL |br|
-          implementations.
+        - When ``ON`` a custom implementation of ``shared_mutex`` is used instead of the STL one. |br|
+          The C++ Standard has not yet (C++20) imposed any requirements on ``shared_mutex`` |br|
+          priority policies implementation, as POSIX_ does, thus each platform made its own choices: |br| |br|
+
+          - Windows & Boost defaults to ``PTHREAD_RWLOCK_PREFER_WRITER_NONRECURSIVE_NP``.
+          - Linux & Mac defaults to ``PTHREAD_RWLOCK_PREFER_READER_NP``.
+
+          Fast-DDS requires the use of ``PTHREAD_RWLOCK_PREFER_READER_NP`` which is the one enforced |br|
+          in its deadlock prevention logic. |br| |br|
+          Fast-DDS will test the framework STL implementation (if available) and will only use it if |br|
+          it enforces ``PTHREAD_RWLOCK_PREFER_READER_NP``. Otherwise it will automatically fallback to |br|
+          a custom implementation. |br| |br|
+          This flag will enforce the use of the custom implementation in all cases. |br| |br|
+          Note that setting the flag ``OFF`` will not prevent the use of the custom implementation |br|
+          in those frameworks that default to ``PTHREAD_RWLOCK_PREFER_WRITER_NONRECURSIVE_NP``. |br| |br|
+          This flag prevents spurious thread sanitizer reports on *GCC/Clang* STL implementations. |br|
         - ``ON`` ``OFF``
-        - ``OFF``
+        - ``OFF`` (Linux & Mac), ``ON`` (Windows)
     *   - :class:`SANITIZER`
         - Adds run-time instrumentation to the code. Supported options are:
 
@@ -139,6 +152,8 @@ dependency on other options.
         - ``OFF`` |br| ``Address`` |br| ``Thread``
         - ``OFF``
 
+.. _POSIX: https://man7.org/linux/man-pages/man3/pthread_rwlockattr_setkind_np.3.html
+
 Log options
 ^^^^^^^^^^^
 
@@ -331,5 +346,3 @@ The building and execution of these tests is specified by the *Fast DDS* CMake o
           use for installing and running the tests.
         - ``Valid Unix filesystem path string``
         - ``""``
-
-