From: Matthias Maier <tamiko@43-1.org>
Date: Tue, 8 Feb 2022 23:59:14 +0000 (-0600)
Subject: Update documentation, pass through variables
X-Git-Tag: v9.4.0-rc1~518^2~4
X-Git-Url: https://gitweb.dealii.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=87daf61f95e5f8aed9afd4c4460aed95b074e265;p=dealii.git

Update documentation, pass through variables
---

diff --git a/cmake/macros/macro_deal_ii_add_test.cmake b/cmake/macros/macro_deal_ii_add_test.cmake
index 97d5a77b2f..427f592761 100644
--- a/cmake/macros/macro_deal_ii_add_test.cmake
+++ b/cmake/macros/macro_deal_ii_add_test.cmake
@@ -69,17 +69,20 @@
 #     - Complete path to the numdiff binary.
 #
 #   TEST_TIME_LIMIT
-#     - specifying the maximal wall clock time in seconds a test is allowed
-#       to run
+#     - Specifies the maximal wall clock time in seconds a test is allowed
+#       to run.
 #
 #   TEST_MPI_RANK_LIMIT
 #     - Specifies the maximal number of MPI ranks that can be used. If a
 #       test variant configures a larger number of MPI ranks (via
 #       .mpirun=N. in the output file) than this limit the test will be
 #       dropped. The special value 0 enforces no limit. Defaults to 0.
+
 #   TEST_THREAD_LIMIT
-#     - Specifies the maximal number of worker threads that can be used by
-#       the threading backend. Defaults to 3.
+#     - Specifies the maximal number of worker threads that can should be
+#       used by the threading backend. Note that individual tests might
+#       exceed this limit by calling MultithreadInfo::set_thread_limit(), or
+#       by manually creating additional threads. Defaults to 3.
 #
 # Usage:
 #     DEAL_II_ADD_TEST(category test_name comparison_file)
diff --git a/cmake/macros/macro_deal_ii_pickup_tests.cmake b/cmake/macros/macro_deal_ii_pickup_tests.cmake
index 3655ca1bc6..6fefd66af3 100644
--- a/cmake/macros/macro_deal_ii_pickup_tests.cmake
+++ b/cmake/macros/macro_deal_ii_pickup_tests.cmake
@@ -42,8 +42,10 @@
 #         .mpirun=N. in the output file) than this limit the test will be
 #         dropped. The special value 0 enforces no limit. Defaults to 0.
 #     TEST_THREAD_LIMIT
-#       - Specifies the maximal number of worker threads that can be used
-#         by the threading backend. Defaults to 3.
+#       - Specifies the maximal number of worker threads that can should be
+#         used by the threading backend. Note that individual tests might
+#         exceed this limit by calling MultithreadInfo::set_thread_limit(),
+#         or by manually creating additional threads. Defaults to 3.
 #
 #     TEST_PICKUP_REGEX
 #       - A regular expression to select only a subset of tests during setup.
diff --git a/doc/developers/testsuite.html b/doc/developers/testsuite.html
index 7cb75e2450..96b0724dba 100644
--- a/doc/developers/testsuite.html
+++ b/doc/developers/testsuite.html
@@ -841,7 +841,8 @@ MAKEOPTS
   - Additional options that will be passed directly to make (or ninja).
 </pre>
 
-      Furthermore, the variables TEST_TIME_LIMIT and TEST_PICKUP_REGEX (as
+      Furthermore, the variables TEST_TIME_LIMIT, TEST_MPI_RANK_LIMIT,
+      TEST_THREAD_LIMIT and TEST_PICKUP_REGEX (as
       described <a href="#setupbuild">above</a>), DIFF_DIR, and NUMDIFF_DIR
       can also be set and will be handed automatically down
       to <code>cmake</code>. For more details on the different tracks, see
diff --git a/doc/users/testsuite.html b/doc/users/testsuite.html
index db7780158a..dca3c60c6e 100644
--- a/doc/users/testsuite.html
+++ b/doc/users/testsuite.html
@@ -312,8 +312,20 @@ NUMDIFF_EXECUTABLE
   - pointing to a valid "numdiff" executable
 
 TEST_TIME_LIMIT
-  - specifying the maximal wall clock time in seconds a test is allowed
-    to run</pre>
+  - Specifies the maximal wall clock time in seconds a test is allowed
+    to run.
+
+TEST_MPI_RANK_LIMIT
+  - Specifies the maximal number of MPI ranks that can be used. If a
+    test variant configures a larger number of MPI ranks (via
+    .mpirun=N. in the output file) than this limit the test will be
+    dropped. The special value 0 enforces no limit. Defaults to 0.
+
+TEST_THREAD_LIMIT
+  - Specifies the maximal number of worker threads that can should be used
+    by the threading backend. Note that individual tests might exceed this
+    limit by calling MultithreadInfo::set_thread_limit(), or by manually
+    creating additional threads. Defaults to 3.</pre>
     <hr />
     <div class="right">
       <a href="http://validator.w3.org/check?uri=referer" target="_top">
diff --git a/tests/CMakeLists.txt b/tests/CMakeLists.txt
index 1a88e3423a..73ce994f9a 100644
--- a/tests/CMakeLists.txt
+++ b/tests/CMakeLists.txt
@@ -100,7 +100,7 @@ FILE(WRITE ${CMAKE_CURRENT_BINARY_DIR}/CTestTestfile.cmake "")
 #
 # Always undefine the following variables in the setup_tests target:
 #
-FOREACH(_var DIFF_DIR NUMDIFF_DIR TEST_PICKUP_REGEX TEST_TIME_LIMIT)
+FOREACH(_var DIFF_DIR NUMDIFF_DIR TEST_PICKUP_REGEX TEST_TIME_LIMIT TEST_MPI_RANK_LIMIT TEST_THREAD_LIMIT)
   LIST(APPEND _options "-U${_var}")
   IF(NOT "${${_var}}" STREQUAL "")
     LIST(APPEND _options "-D${_var}=${${_var}}")
diff --git a/tests/setup_testsubproject.cmake b/tests/setup_testsubproject.cmake
index df74de81d3..bebdd255e7 100644
--- a/tests/setup_testsubproject.cmake
+++ b/tests/setup_testsubproject.cmake
@@ -3,7 +3,7 @@ FIND_PACKAGE(deal.II 9.2.0 REQUIRED HINTS ${DEAL_II_DIR})
 SET(CMAKE_BUILD_TYPE ${DEAL_II_BUILD_TYPE} CACHE STRING "" FORCE)
 DEAL_II_INITIALIZE_CACHED_VARIABLES()
 
-FOREACH(_var DIFF_DIR NUMDIFF_DIR TEST_PICKUP_REGEX TEST_TIME_LIMIT)
+FOREACH(_var DIFF_DIR NUMDIFF_DIR TEST_PICKUP_REGEX TEST_TIME_LIMIT TEST_MPI_RANK_LIMIT TEST_THREAD_LIMIT)
   SET_IF_EMPTY(${_var} "$ENV{${_var}}")
   SET(${_var} "${${_var}}" CACHE STRING "" FORCE)
 ENDFOREACH()