ctest: Optionally terminate tests with a custom signal on timeout

CTest normally terminates test processes on timeout using `SIGKILL`.
Offer tests a chance to exit gracefully, on platforms supporting POSIX
signals, by setting `TIMEOUT_SIGNAL_{NAME,GRACE_PERIOD}` properties.

Fixes: #17288

6 files changed, 69 insertions, 0 deletions

diff --git a/Help/manual/cmake-properties.7.rst b/Help/manual/cmake-properties.7.rst
index b2a27a0..4e2e7d5 100644
--- a/Help/manual/cmake-properties.7.rst
+++ b/Help/manual/cmake-properties.7.rst
@@ -522,6 +522,8 @@ Properties on Tests
    /prop_test/SKIP_RETURN_CODE
    /prop_test/TIMEOUT
    /prop_test/TIMEOUT_AFTER_MATCH
+   /prop_test/TIMEOUT_SIGNAL_GRACE_PERIOD
+   /prop_test/TIMEOUT_SIGNAL_NAME
    /prop_test/WILL_FAIL
    /prop_test/WORKING_DIRECTORY
 
diff --git a/Help/prop_test/TIMEOUT.rst b/Help/prop_test/TIMEOUT.rst
index 385539b..175c0fb 100644
--- a/Help/prop_test/TIMEOUT.rst
+++ b/Help/prop_test/TIMEOUT.rst
@@ -10,3 +10,6 @@ setting takes precedence over :variable:`CTEST_TEST_TIMEOUT`.
 
 An explicit ``0`` value means the test has no timeout, except as
 necessary to honor :option:`ctest --stop-time`.
+
+See also :prop_test:`TIMEOUT_AFTER_MATCH` and
+:prop_test:`TIMEOUT_SIGNAL_NAME`.
diff --git a/Help/prop_test/TIMEOUT_AFTER_MATCH.rst b/Help/prop_test/TIMEOUT_AFTER_MATCH.rst
index aa17590..edee2ef 100644
--- a/Help/prop_test/TIMEOUT_AFTER_MATCH.rst
+++ b/Help/prop_test/TIMEOUT_AFTER_MATCH.rst
@@ -39,3 +39,5 @@ If the required resource can be controlled by CTest you should use
 :prop_test:`RESOURCE_LOCK` instead of ``TIMEOUT_AFTER_MATCH``.
 This property should be used when only the test itself can determine
 when its required resources are available.
+
+See also :prop_test:`TIMEOUT_SIGNAL_NAME`.
diff --git a/Help/prop_test/TIMEOUT_SIGNAL_GRACE_PERIOD.rst b/Help/prop_test/TIMEOUT_SIGNAL_GRACE_PERIOD.rst
new file mode 100644
index 0000000..858be5d
--- /dev/null
+++ b/Help/prop_test/TIMEOUT_SIGNAL_GRACE_PERIOD.rst
@@ -0,0 +1,14 @@
+TIMEOUT_SIGNAL_GRACE_PERIOD
+---------------------------
+
+.. versionadded:: 3.27
+
+If the :prop_test:`TIMEOUT_SIGNAL_NAME` test property is set, this property
+specifies the number of seconds to wait for a test process to terminate after
+sending the custom signal.  Otherwise, this property has no meaning.
+
+The grace period may be any real value greater than ``0.0``, but not greater
+than ``60.0``.  If this property is not set, the default is ``1.0`` second.
+
+This is available only on platforms supporting POSIX signals.
+It is not available on Windows.
diff --git a/Help/prop_test/TIMEOUT_SIGNAL_NAME.rst b/Help/prop_test/TIMEOUT_SIGNAL_NAME.rst
new file mode 100644
index 0000000..6294d27
--- /dev/null
+++ b/Help/prop_test/TIMEOUT_SIGNAL_NAME.rst
@@ -0,0 +1,41 @@
+TIMEOUT_SIGNAL_NAME
+-------------------
+
+.. versionadded:: 3.27
+
+Specify a custom signal to send to a test process when its timeout is reached.
+This is available only on platforms supporting POSIX signals.
+It is not available on Windows.
+
+The name must be one of the following:
+
+  ``SIGINT``
+    Interrupt.
+
+  ``SIGQUIT``
+    Quit.
+
+  ``SIGTERM``
+    Terminate.
+
+  ``SIGUSR1``
+    User defined signal 1.
+
+  ``SIGUSR2``
+    User defined signal 2.
+
+The custom signal is sent to the test process to give it a chance
+to exit gracefully during a grace period:
+
+* If the test process created any children, it is responsible for
+  terminating them too.
+
+* The grace period length is determined by the
+  :prop_test:`TIMEOUT_SIGNAL_GRACE_PERIOD` test property.
+
+* If the test process does not terminate before the grace period ends,
+  :manual:`ctest(1)` will force termination of its entire process tree
+  via ``SIGSTOP`` and ``SIGKILL``.
+
+See also :variable:`CTEST_TEST_TIMEOUT`,
+:prop_test:`TIMEOUT`, and :prop_test:`TIMEOUT_AFTER_MATCH`.
diff --git a/Help/release/dev/ctest-timeout-signal.rst b/Help/release/dev/ctest-timeout-signal.rst
new file mode 100644
index 0000000..f182429
--- /dev/null
+++ b/Help/release/dev/ctest-timeout-signal.rst
@@ -0,0 +1,7 @@
+ctest-timeout-signal
+--------------------
+
+* The :prop_test:`TIMEOUT_SIGNAL_NAME` and
+  :prop_test:`TIMEOUT_SIGNAL_GRACE_PERIOD` test properties were added
+  to specify a POSIX signal to send to a test process when its timeout
+  is reached.