test(support): re-arm time_limit's alarm so a swallowed timeout cannot hang a worker (#1892)

[JarryShaw]

Please follow the guide below

• You will be asked some questions, please read them carefully and answer honestly

• Put an x into all the boxes [ ] relevant to your pull request (like that [x])

• Use Preview tab to see how your pull request will actually look like

• Searched for similar pull requests

• Followed the coding style (make pylint, make mypy, make isort)

• make test passes, and a test case covers the change. Narrow runs only, listed below.

• Added a changelog entry under docs/source/changelog/ and regenerated CHANGELOG.md, if the change is user-visible: N/A — centralised in docs(changelog): shared 1.5.0 changelog — long-lived, merges last (#610, #616, #617, #618, #620) #657

What is the purpose of your pull request?

Tick the commit type your subject line carries.

• fix — corrects a defect
• feat — adds a feature
• perf — changes performance, not behaviour
• refactor — changes neither behaviour nor performance
• test — tests only
• docs — documentation only
• ci — workflows or build tooling
• release — bumps the version or rolls up a distribution
• chore — anything else

---

tests/_support.time_limit armed one SIGALRM and raised TimeoutError once. As #1891 found for the generator's deadline, that single raise can be lost. A finaliser sends it to sys.unraisablehook, and an except OSError swallows it because TimeoutError is an OSError. The body then runs until pytest-timeout's 900s backstop kills the xdist worker.

Fix. The handler re-arms alarm(1) each time it raises. The first thing the exit path does is set a flag that makes any due repeat a no-op. After that it cancels the alarm, restores the previous handler, and restores the outer alarm minus the body's seconds, as before.

Tests. New TimeLimitTests cases cover:

• the re-arm;
• a first raise lost in a real __del__, gated with sys.version_info on 3.8+;
• a first raise caught by except OSError;
• nothing left armed after a normal, timed-out or exceptional exit;
• an outer alarm restored after repeats.

Every waiting body gives up after 10s, which includes the two existing unbounded while True: pass loops. Against main's _support.py, 5 of the new tests fail with "did not interrupt the body within 10s" or 5 != 1. The test file passed 20/20 runs.

Not done: sending pytest-timeout's stack dump somewhere visible under xdist. It could not be checked without xdist and pytest-timeout installed here.

Closes #1892

[JarryShaw]

Verdict: NEEDS CHANGES at 3c38d2690. The re-arm works. A Sonnet cross-review confirmed:

• the outer alarm is restored correctly after repeats (30 → 28 after a swallowed timeout plus a timeout);
• the new tests fail against main's _support.py without hanging;
• no caller catches TimeoutError inside the with;
• test_tier_guard.py passes.

Required: no test pins the leaving flag. Each of these mutations still passes all 42 tests:

• removing the handler's if leaving: return;
• never setting leaving;
• setting it only after the cancel and restore.

The flag is the exit-path race fix carried over from #1891's review, so it needs a test that fails without it. The reviewer validated one. It patches signal.alarm so that alarm(0) first does os.kill(os.getpid(), signal.SIGALRM), runs with time_limit(5): pass, and then asserts that nothing is left behind. That test passes on head and fails under all three mutations.

Not blocking: a fire between the body ending and the generator resuming, inside contextlib's __exit__, can still raise into the caller. That window cannot be closed in pure Python. Mention it in the docstring.

[JarryShaw]

Verdict: GOOD TO GO at a525629f1. The Sonnet reviewer re-checked the amend.

• The new test_a_repeat_due_as_the_block_is_left_does_nothing fails under each leaving mutation: the check removed, the flag never set, and the flag set after the restore. In each case TimeoutError escapes the with and the test fails rather than hangs. It also asserts the signal was actually sent.
• The docstring's new paragraph on the contextlib window matches what was measured in the first round, and it states no count.
• tests/test_support_helpers.py passed 5 of 5 runs with 43 passed; test_tier_guard.py passes.

[github-actions]

Coverage: 90.06% (unit tier, Python 3.15, a525629f1, Unit Tests run success)

Package	Statements	Missed	Branches	Partial	Cover
pcapkit (top level)	104	2	20	2	96.77%
pcapkit/const	19595	881	2618	867	92.11%
pcapkit/corekit	2462	69	780	35	96.55%
pcapkit/dumpkit	276	3	100	3	98.40%
pcapkit/foundation	2914	164	1016	34	93.59%
pcapkit/interface	138	7	52	5	93.68%
pcapkit/protocols	17406	224	4580	189	98.10%
pcapkit/toolkit	872	177	298	8	77.18%
pcapkit/utilities	512	2	158	4	99.10%
pcapkit/vendor	4429	2341	1018	156	43.62%

Per-file detail: the coverage-html artifact of this run.