From 6fcf766c34ac1e490f465d79fca913ab808b1789 Mon Sep 17 00:00:00 2001 From: Rain Date: Tue, 17 Dec 2024 22:37:28 +0000 Subject: [PATCH] [docs] update docs for 0.9.87 Make a few updates to the docs for 0.9.87, and change "major" to "substantive" in signal docs to indicate the last revision to the semantics. --- site/src/docs/design/architecture/runner-loop.md | 2 +- .../src/docs/design/architecture/signal-handling.md | 7 ++++++- site/src/docs/features/slow-tests.md | 13 +++++++++++-- 3 files changed, 18 insertions(+), 4 deletions(-) diff --git a/site/src/docs/design/architecture/runner-loop.md b/site/src/docs/design/architecture/runner-loop.md index b6e12cea2b4..c270ff0896d 100644 --- a/site/src/docs/design/architecture/runner-loop.md +++ b/site/src/docs/design/architecture/runner-loop.md @@ -198,4 +198,4 @@ sustainably high-quality over time. runner is to handle all of the ways tests can fail, just like the primary job of a compiler is to handle all the ways users can write incorrect code. -_Last major revision: 2024-12-06_ +_Last substantive revision: 2024-12-06_ diff --git a/site/src/docs/design/architecture/signal-handling.md b/site/src/docs/design/architecture/signal-handling.md index 779bea08677..1fd8889f719 100644 --- a/site/src/docs/design/architecture/signal-handling.md +++ b/site/src/docs/design/architecture/signal-handling.md @@ -228,7 +228,12 @@ When a test times out, nextest calls `TerminateJobObject` on the job object associated with the test immediately. In the future, it would be interesting to send a Ctrl-C (or maybe a `WM_CLOSE`?) to the test process first. +When nextest receives a Ctrl-C, it assumes that child tests will also receive +the same Ctrl-C and terminate themselves. If tests don't exit within the grace +period (by default, 10 seconds), nextest will terminate them via their +corresponding job object. + [job objects]: https://learn.microsoft.com/en-us/windows/win32/procthread/job-objects [terminate-job-object]: https://docs.microsoft.com/en-us/windows/win32/api/jobapi2/nf-jobapi2-terminatejobobject -_Last major revision: 2024-12-06_ +_Last substantive revision: 2024-12-17_ diff --git a/site/src/docs/features/slow-tests.md b/site/src/docs/features/slow-tests.md index 1510455e3a6..4c8a789653a 100644 --- a/site/src/docs/features/slow-tests.md +++ b/site/src/docs/features/slow-tests.md @@ -80,11 +80,20 @@ To send SIGKILL to a process immediately, without a grace period, set `slow-time slow-timeout = { period = "60s", terminate-after = 5, grace-period = "0s" } ``` - The `slow-timeout.grace-period` setting is also applied to terminations due to Ctrl-C or other signals. With older versions, nextest always waits 10 seconds before sending SIGKILL. + For terminations due to Ctrl-C or other signals, the +`slow-timeout.grace-period` setting is applied. With older versions, nextest +always waits 10 seconds before sending SIGKILL. #### Termination on Windows -On Windows, nextest terminates the test immediately in a manner akin to SIGKILL. (On Windows, nextest uses [job objects] to kill the test process and all its descendants.) The `slow-timeout.grace-period` configuration setting is ignored. +On Windows, nextest terminates the test immediately in a manner akin to SIGKILL. +(Nextest uses Windows [job objects] to kill the test process and all its +descendants.) For termination due to timeouts, the `slow-timeout.grace-period` +configuration setting is ignored. + + For terminations due to Ctrl-C, the +`slow-timeout.grace-period` setting is applied. With older versions, nextest +waits indefinitely for the test to shut down. [process group]: https://en.wikipedia.org/wiki/Process_group [job objects]: https://docs.microsoft.com/en-us/windows/win32/procthread/job-objects