Skip to content

0.10.0: a timeout records the program's processes, asks it to end, and then ends it - #25

Merged
Sunrisepeak merged 3 commits into
mainfrom
timeout-requests-end
Nov 19, 2026
Merged

Sunrisepeak merged 3 commits into
mainfrom
timeout-requests-end

Conversation

@Sunrisepeak

@Sunrisepeak Sunrisepeak commented Nov 19, 2026 •

Copy link
Copy Markdown
Member

The rule "a timeout first requests the end, then terminates" for the programs the engine runs
(mcpp design record 2026-11-19, §12 and §14.2 row 4). Intermittent timeouts on mcpp's CI (a test
ended with status 137) left no state the first time they occurred.

At a program's timeout

  1. The record, before anything changes the processes. On Linux, from /proc: the program,
    every process it started, and every other member of the process group it leads (its unit). Each
    process states its parent, group, command, state, the kernel function it sleeps in (wchan), its
    processor time, what SIGTERM does to it (ends, caught, ignored, from the masks in
    status), its threads (state, wchan, processor time) and, where the system lets it be read,
    its kernel stack. On macOS, Windows, or where /proc cannot be read, the program alone, as
    mcpplibs.os describes it (identifier, processor time), and the record says so (seen).
  2. The request: openkal's kal_process_terminate through process::terminate() (SIGTERM on
    Linux and macOS; TerminateProcess on Windows, which openkal-windows uses for it).
  3. The grace: the engine waits for the program at most its grace.
  4. The end: what still runs in the unit is recorded again (remaining), and the unit is ended
    (end_unit).

mtest measure (the engine's own process that starts a program judged by its exit status, to
measure it, natively on Linux and macOS) takes the request over and passes it on. Through 0.9.0 the
request ended mtest measure and not the test, which the unit's end then killed without the
request.

mcpplibs.os's bounded run has no point between the request and the end, so the engine composes the
same parts (spawn, bounded reads, wait_for, terminate, end_unit) with the record between them;
the output limits and the drain are that run's (os::process::bounds{}).

Configuration

  • grace: a key of [programs.*] and [discover.*] beside timeout, in the same duration words,
    and mtest run --grace beside --timeout (a catalog parameter, so the service and the MCP tools
    take it too). Default 2 s: bounds::grace, which the engine gave through 0.9.0.
  • timeout_record: a boolean key of the same tables, default true; false takes no record.

Neither is a case attribute: the request and the grace act on a process, not a case, and the
library's attributes are SPEC-017 P3.3 words, which a grace would extend.

Where the record appears

  • The case's reason: asked to end, it ended within its grace of 2s, or asked to end, it was still running after its grace of 2s, and was ended.
  • The terminal summary, under the first case the timeout ended (at most 40 lines).
  • mtest explain: timeout in the JSON, and the text.
  • The store: the program's timeout object (limit_ms, grace_ms, ended, seen, processes,
    remaining) in programs.ndjson and the failure's program.json.
  • The Markdown report: a <details> block per program below the failures.

Tests (engine/tests/engine.cpp)

  • A program that ends on the request (sleep 30 under bash, --grace 60s): timeout, ended: requested; on Linux the tree holds the sleep (sleeping, request: ends), and remaining
    holds it, since the request did not reach it.
  • A program that ignores the request (trap '' TERM; grace from mtest.toml): ended: terminated after the timeout and the grace; on Linux its processes state request: ignored. On
    Windows the request cannot be declined, and the test holds requested there.
  • A protocol program's case at the timeout says how it was ended; timeout_record = false records
    nothing.

Locally (Linux x86_64, mcpp 2026.11.18.1): mcpp test of the library (97 cases passed, 4
skipped), the manifest (14), the engine (55) and conformance (14); the conformance suite against
the Bash, Python, C ABI and GoogleTest implementations; the engine's run of mtest's own programs and
gate --set full; the working tree clean after them.

CI

The first run's native job failed outside this change, twice the same way: it restored the package
store the Web job had saved first under their common key (mcpp-store-Linux-X64-<mcpp>-<manifests>),
which lacked the base GCC builds against; its first mcpp build installed it, and the next
invocation (mcpp test -p mcpplibs.mtest) reported Replaced target/x86_64-linux-gnu/... (273.0 MiB): the base changed and emptied the build directory, so the conformance step found no
capi-fixture (MTEST_CTS_PROGRAM named the checkout's directory: permission denied). The cache
key now states the job (github.job), so each job restores what a job of its own saved. Main's runs
did not meet it only because the native job restored before the Web job saved. That the record of
the base written during a first run's toolchain install differs from the next invocation's is
mcpp's behaviour (2026.11.14.1), reported here and not changed.

Not covered

  • The request reaches the program the engine started, not its unit. openkal has no request to a
    unit that a member can observe: kal_process_job_terminate is SIGKILL by its stated decision,
    and kal_process_terminate refuses a handle opened by identifier. A descendant receives the
    request only from the program. So an e2e script (bash, then mcpp, then okrun) passes it on itself
    (trap), or openkal gains a request to a unit, for okrun's report on the request (§12) to appear
    under a script.
  • Windows: the request is TerminateProcess; no program observes it.
  • macOS and Windows: mcpplibs.os lists no other process, so the record holds the program
    alone.
  • The listing's 60 s limit and the library's e2e::run keep mcpplibs.os's bounded run: they
    request the end and end the program after 2 s, and take no record.

…hat still runs after its grace

At a program's timeout the engine records the processes of its unit (on Linux from /proc: the
program, what it started and the rest of its process group, each with its state, the kernel
function it sleeps in, its threads and what SIGTERM does to it; elsewhere the program alone),
requests its end through openkal, waits at most its grace, records what still runs, and ends the
unit. `mtest measure` passes the request on to the program it starts. `grace` and
`timeout_record` are keys of [programs.*] and [discover.*] beside `timeout`; `mtest run --grace`
beside `--timeout`. The record is stated in the case's reason, the terminal summary, `mtest
explain`, the store and the Markdown report.
The native job restored the store the Web job had saved under their common key, which lacked the
base GCC builds against; its first build installed it, the next build found the base it had
recorded changed and emptied the build directory, and the conformance step found no capi or
gtest fixture. The key states the job.
@Sunrisepeak
Sunrisepeak merged commit dad6c1b into main Nov 19, 2026
18 checks passed
Sunrisepeak added a commit to openxlings/xim-pkgindex that referenced this pull request Nov 19, 2026
…ore it is ended (#1199)

On Linux the record names the program, the processes it started and its process group, with each one's state, the kernel function it waits in, its processor time and what the request to end did to it; elsewhere, the program itself. A grace period (2 s by default) separates the request from the end of the program's unit (mcpp-community/mtest#25). The bundle is mirrored at gitcode.com/xlings-res/mtest under the same sha256.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant