CTest: Clarify that resource requirements can be split

Add a note to the documentation to clarify this, and add test cases
to ensure it.

Fixes: #19987

Help/prop_test/RESOURCE_GROUPS.rst

@@ -38,6 +38,22 @@ This single group requires 4 slots from a single GPU and 2 slots from a
 single cryptography chip. In total, 3 resource groups are specified for this
 test, each with its own unique requirements.
 
+Note that the number of slots following the resource type specifies slots from
+a *single* instance of the resource. If the resource group can tolerate
+receiving slots from different instances of the same resource, it can indicate
+this by splitting the specification into multiple requirements of one slot. For
+example:
+
+.. code-block:: cmake
+
+  add_test(NAME MyTest COMMAND MyExe)
+  set_property(TEST MyTest PROPERTY RESOURCE_GROUPS
+    "gpus:1,gpus:1,gpus:1,gpus:1")
+
+In this case, the single resource group indicates that it needs four GPU slots,
+all of which may come from separate GPUs (though they don't have to; CTest may
+still assign slots from the same GPU.)
+
 When CTest sets the :ref:`environment variables
 <ctest-resource-environment-variables>` for a test, it assigns a group number
 based on the group description, starting at 0 on the left and the number of

Tests/CMakeLib/testCTestResourceGroups.cxx

@@ -74,6 +74,9 @@ static const std::vector<ExpectedParseResult> expectedResults{
   { "1,threads:1,", true, {
     { { "threads", 1, 1 } },
   } },
+  { "threads:1,threads:1", true, {
+    { { "threads", 1, 1 }, { "threads", 1, 1 } },
+  } },
   { "threads:1;;threads:2", true, {
     { { "threads", 1, 1 } },
     { { "threads", 2, 1 } },

Tests/RunCMake/CTestResourceAllocation/RunCMakeTest.cmake

@@ -160,6 +160,8 @@ run_ctest_resource(checkfree1 2 0)
 run_ctest_resource(checkfree2 1 0)
 run_ctest_resource(notenough1 1 0)
 run_ctest_resource(notenough2 1 0)
+run_ctest_resource(notenough3 1 0)
+run_ctest_resource(combine 1 0)
 run_ctest_resource(ensure_parallel 2 0)
 
 set(ENV{CTEST_RESOURCE_GROUP_COUNT} 2)

Tests/RunCMake/CTestResourceAllocation/combine.cmake

@@ -0,0 +1,5 @@
+setup_resource_tests()
+
+add_resource_test(Test1 0 "widgets:8,widgets:4")
+
+cleanup_resource_tests()

Tests/RunCMake/CTestResourceAllocation/notenough1.cmake

@@ -1,5 +1,5 @@
 setup_resource_tests()
 
-add_resource_test(Test1 1 "fluxcapacitors:200")
+add_resource_test(Test1 0 "fluxcapacitors:200")
 
 cleanup_resource_tests()

Tests/RunCMake/CTestResourceAllocation/notenough2.cmake

@@ -1,5 +1,5 @@
 setup_resource_tests()
 
-add_resource_test(Test1 1 "terminators:2")
+add_resource_test(Test1 0 "terminators:2")
 
 cleanup_resource_tests()

Tests/RunCMake/CTestResourceAllocation/notenough3-ctest-s-res-check.cmake

@@ -0,0 +1,3 @@
+if(EXISTS "${RunCMake_TEST_BINARY_DIR}/ctresalloc.log")
+  set(RunCMake_TEST_FAILED "ctresalloc.log should not exist")
+endif()

Tests/RunCMake/CTestResourceAllocation/notenough3-ctest-s-res-result.txt

@@ -0,0 +1 @@
+(-1|255)

Tests/RunCMake/CTestResourceAllocation/notenough3-ctest-s-res-stderr.txt

@@ -0,0 +1,4 @@
+^Insufficient resources
+CMake Error at [^
+]*/Tests/RunCMake/CTestResourceAllocation/notenough3-ctest-s-res/test\.cmake:[0-9]+ \(message\):
+  Tests did not pass$

Tests/RunCMake/CTestResourceAllocation/notenough3.cmake

@@ -0,0 +1,5 @@
+setup_resource_tests()
+
+add_resource_test(Test1 0 "widgets:12")
+
+cleanup_resource_tests()