From a8f998130425abd76f87a865ecd59bb414e6b750 Mon Sep 17 00:00:00 2001 From: thomas Date: Mon, 16 Nov 2026 08:22:57 +0200 Subject: [PATCH 1/2] Match exactly one recipe when checking the sanitiser's flags `test_the_instrumented_build_enables_avx` found the tsan recipe with `^tsan:.*?(?=^\w|\Z)` -- everything up to the next line starting with a word character. Make recipes are tab-indented and the comments between targets start with `#`, so that pattern does not stop at the end of the recipe: it runs through any following comment block and through a following rule whose target begins with `$(`, stopping only at the next target named by a bare word. Found while adding a target between `tsan` and `clean`, which grew the match from 10 lines to 26. The test still passed, but its claim had quietly become "-mavx appears somewhere in this stretch of the Makefile" rather than "the tsan recipe passes -mavx", and it would have gone on passing with the flag moved into a neighbouring recipe and out of this one. Now it matches the target line plus the tab-indented lines under it, which is exactly one recipe. The continuation-collapsing step above it runs first, so a backslash-continued line is already one line by the time this applies. Verified by moving `-mavx` out of the tsan recipe and into the neighbouring one: the test fails, where before the change it passed. --- verification/tests/test_tsan.py | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/verification/tests/test_tsan.py b/verification/tests/test_tsan.py index ddca8ba..cd2cfff 100644 --- a/verification/tests/test_tsan.py +++ b/verification/tests/test_tsan.py @@ -173,8 +173,13 @@ def test_the_instrumented_build_enables_avx(): warning should stand out.""" makefile = re.sub(r"\\\n\s*", " ", (ROOT / "Makefile").read_text(encoding="utf-8")) - recipe = re.search(r"^tsan:.*?(?=^\w|\Z)", makefile, - re.MULTILINE | re.DOTALL) + # Exactly one make recipe: the target line plus the tab-indented lines + # under it. An earlier version ran to the next line starting with a word + # character, which swallowed whatever target came next -- adding the + # teamwidth target between `tsan` and `clean` grew the match from 10 lines + # to 26, so this test would have passed on a Makefile where -mavx had + # drifted into a NEIGHBOURING recipe and out of this one. + recipe = re.search(r"^tsan:[^\n]*\n(?:\t[^\n]*\n)*", makefile, re.MULTILINE) assert recipe, "no tsan target in the Makefile" assert re.search(r"SANFLAGS=\"[^\"]*-mavx", recipe.group(0)), \ "the tsan recipe does not pass -mavx; vtrig.c will not compile" From 0cbd9f16bae90352599f9d98fc286730288af2d6 Mon Sep 17 00:00:00 2001 From: thomas Date: Mon, 16 Nov 2026 08:23:16 +0200 Subject: [PATCH 2/2] Measure the width of every team BEAM actually creates Every thread check in this repository was static. `thread counts` proves all 93 parallel regions NAME a thread count; `thread plan wiring` proves all 69 GIL-releasing regions RESOLVE a plan. Neither can see what the runtime granted, and that gap is not hypothetical: the nesting defect was live in a gate run where `thread counts` reported OK, because the clause was present and correct and only its value on a worker thread was wrong. verification/teamwidth.c interposes the two libgomp entry points BEAM creates teams through -- GOMP_parallel and the fused GOMP_parallel_loop_nonmonotonic_dynamic, the only two of its ten GOMP imports that create a team -- and records, per region entry, the count requested and the width that actually ran, split by whether the region itself is nested. It observes the SHIPPED extension through LD_PRELOAD, with no recompilation. A check that needed its own build would be checking a different binary, which is the same reason the gate hashes the artifact rather than trusting a clean tree. One entropy() call creates 949 teams. That number is the argument for measuring at all: reading 93 pragmas cannot tell you what happens 949 times, and a region inside a loop is one pragma and ten thousand entries. BOTH channels are recorded, and the mutation is why. With the nested-region guard removed from beam_threads(): nesting ON (OMP_MAX_ACTIVE_LEVELS=2) requested 16, nested ran 16, plan 8 nesting OFF (the default) requested 16, nested ran 1, plan 8 So in the environment every user actually gets, the defect was INVISIBLE in the width that ran -- libgomp declines to widen a nested region when nesting is off, so the teams were a blameless 8 and 1 -- while BEAM was still emitting num_threads(16) on them. The runtime's default policy was the only thing between the plan and sixteen-way oversubscription, which is luck rather than design. A check on the width that ran PASSES on that mutant; test_no_region_asks_for_more_than_the_plan fails it with no special environment at all, and is therefore the primary assertion rather than a second opinion. Two tests exist to stop the file lying. One reads the built extension's imports and fails if BEAM grows a third way to create a team, because the observer would then be blind AND quiet -- the worst failure a checking tool has. The other requires the measurement to have reached depth >= 2, since a dead path and a well-behaved one report the same zero; this is the same lesson as the availability estimate, where a quiet runner and a dead reader were indistinguishable. A third reports what the source scan cannot: zero of the 949 regions reached libgomp with nthreads == 0, which is what a missing num_threads clause looks like from the outside. `thread counts` covers regions whether or not they run; this covers regions that ran whether or not the scan understood them. Attribution rests on where the reset goes. LD_PRELOAD interposes libgomp process-wide, so a counter read at exit would mix in any other OpenMP user -- a BLAS built against libgomp, say. The child resets immediately before the one call under test and reads immediately after, with the model built before the reset, so every region counted is BEAM's. Runs in CI as a step in the Verification tooling job, which is the one job that can: it interposes libgomp through LD_PRELOAD, so it is Linux-only by nature. Without `make teamwidth` the tests skip, and a skipped check is not a check. Verified: C 454 tests passing, Python 1243 passed and 2 skipped, tooling 136 passed and 0 skipped, gate exit 0 with every recorded number byte-identical and no inventory line moved -- these tests live in verification/, which the baseline does not track. Both artifacts hash unchanged, the observer being a separate object that the shipped build never links. --- .github/workflows/tests.yml | 5 + Makefile | 24 +++- verification/README.md | 36 +++++ verification/teamwidth.c | 200 ++++++++++++++++++++++++++ verification/tests/test_teamwidth.py | 207 +++++++++++++++++++++++++++ 5 files changed, 471 insertions(+), 1 deletion(-) create mode 100644 verification/teamwidth.c create mode 100644 verification/tests/test_teamwidth.py diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml index 42cf448..1c6b183 100644 --- a/.github/workflows/tests.yml +++ b/.github/workflows/tests.yml @@ -171,6 +171,11 @@ jobs: # tests-only, not test: these tests ask the binaries what they contain. # Running the C suite is the `native` job's business. run: make -j"$(nproc)" tests-only + - name: Build the team-width observer + # Without it test_teamwidth.py skips, and a skipped check is not a + # check. Linux-only by nature: it interposes libgomp through + # LD_PRELOAD, so this is the one job that can run it. + run: make teamwidth - name: Tooling test suite run: python -m pytest verification/tests -q diff --git a/Makefile b/Makefile index df9bb78..ac0b778 100644 --- a/Makefile +++ b/Makefile @@ -243,8 +243,30 @@ tsan: @echo " running the binaries bare reports hundreds of races that are" @echo " not there -- see verification/tests/test_tsan.py)" +# ── The team-width observer ────────────────────────────────── +# +# Builds verification/teamwidth.c into an LD_PRELOAD library that records how +# wide every OpenMP team BEAM creates actually was. Every other thread check in +# this repository is static -- `thread counts` proves each of the 93 regions +# NAMES a count, the GIL scan proves each resolves a plan -- and neither can see +# what the runtime granted. The nesting defect lived in exactly that gap. +# +# Deliberately NOT built with $(OMPFLAG): the observer resolves libgomp through +# dlopen at run time, so linking a second OpenMP runtime into it would be both +# unnecessary and a way to end up measuring the wrong one. +$(BUILD)/teamwidth.so: verification/teamwidth.c + @mkdir -p $(dir $@) + $(CC) -O2 -Wall -Wextra -std=c11 -fPIC -shared -o $@ $< -ldl + +teamwidth: $(BUILD)/teamwidth.so + @echo + @echo "Built $(BUILD)/teamwidth.so" + @echo "Use it: LD_PRELOAD=$(BUILD)/teamwidth.so .venv/bin/python your_script.py" + @echo " (read the counters via ctypes.CDLL(None); see" + @echo " verification/tests/test_teamwidth.py)" + clean: rm -rf $(BUILD) -.PHONY: all clean test list-tests selftest tests-only tsan +.PHONY: all clean test list-tests selftest tests-only tsan teamwidth -include $(DEPS) diff --git a/verification/README.md b/verification/README.md index 84b0198..c8e0805 100644 --- a/verification/README.md +++ b/verification/README.md @@ -71,6 +71,42 @@ that set from the sources rather than listing it, and its last test is the one that matters: it runs a suite with Archer off and checks the reports appear, because a clean run is only evidence if a dirty one is reachable. +## Observing the teams that actually ran + +```bash +make teamwidth # build/teamwidth.so +python -m pytest verification/tests/test_teamwidth.py -q +``` + +Every other thread check here is static. `thread counts` proves each of the 93 +parallel regions *names* a thread count; `thread plan wiring` proves each +GIL-releasing region *resolves* a plan. Neither can see what the runtime +granted, and that is precisely where the nesting defect lived -- `thread +counts` was OK in the same gate run that the defect was live in, because the +clause was present and correct and only its value on a worker thread was wrong. + +`teamwidth.c` interposes the two libgomp entry points BEAM creates teams +through and records, for every region entry, the count requested and the width +that actually ran. One `entropy()` call creates **949 teams**, which is why +reading 93 pragmas could never have answered the question. It observes the +shipped extension through `LD_PRELOAD`, with no rebuild, so it measures the +same binary the gate hashes. + +Both numbers are recorded because the mutation says they are not +interchangeable. With the nested-region guard removed from `beam_threads()`, in +the **default** environment, BEAM asked for 16 threads against a plan of 8 and +every team that ran was still the correct width -- libgomp declines to widen a +nested region when nesting is off. A check on the width that ran passes on that +mutant; only the requested count catches it. The runtime's default policy was +the only thing between the plan and sixteen-way oversubscription, which is luck +rather than design, so the requested channel is the primary assertion. + +Two of the tests exist to stop the file lying to you. One reads the built +extension's imports and fails if BEAM ever grows a third way to create a team, +since the observer would then be blind *and* quiet. The other requires the +measurement to have reached a nested region, because a dead path and a +well-behaved one report the same zero. + ## Running the gate ```bash diff --git a/verification/teamwidth.c b/verification/teamwidth.c new file mode 100644 index 0000000..99a6bd0 --- /dev/null +++ b/verification/teamwidth.c @@ -0,0 +1,200 @@ +/* Observe the WIDTH of every OpenMP team BEAM actually creates. + * + * Every check BEAM had before this one was static. `check_lib.thread_count_clauses` + * proves all 93 parallel regions NAME a thread count, and the GIL scan proves + * every GIL-releasing region RESOLVES a plan. Neither can see what the runtime + * granted. That blind spot is not hypothetical: `beam_threads()` returned the + * configured cap to a worker thread for as long as the plan existed, so an + * 8-thread plan opened eight teams of sixteen under OMP_MAX_ACTIVE_LEVELS=2 -- + * and `thread counts` was OK in the same gate run, because the clause was + * present and correct and only its VALUE on a worker was wrong. + * + * This observes the shipped artifact rather than a special build. BEAM creates + * teams through exactly two libgomp entry points (`nm --undefined-only` on the + * extension: GOMP_parallel and the fused GOMP_parallel_loop_nonmonotonic_dynamic; + * the other eight GOMP imports are work-sharing, atomics and critical sections, + * which create no team). Interposing those two via LD_PRELOAD measures the real + * `_cbeam*.so` the gate hashes, with no recompilation -- a check that needed its + * own build would be checking a different binary. + * `test_teamwidth.py::test_the_observer_wraps_every_team_creating_entry_point` + * fails if a third ever appears, because the observer would then be blind and + * still report zero violations. + * + * REQUESTED vs ACTUAL, and why both. The `nthreads` argument is what BEAM's + * `num_threads(...)` clause evaluated to -- the plan's answer, which until now + * was only ever checked by reading the source. The team that runs can be + * narrower (the runtime is allowed to give less) but never wider, so the two + * numbers bracket the question: `requested` audits BEAM's arithmetic, `actual` + * audits the runtime's grant. Recording only one of them would leave either the + * plan or the runtime unexamined. + * + * Build: make teamwidth + * Use: LD_PRELOAD=build/teamwidth.so .venv/bin/python ... + * then read the counters through ctypes.CDLL(None) -- an LD_PRELOAD + * library is in the global symbol scope, so its exports resolve there. + */ +#define _GNU_SOURCE +#include +#include +#include +#include +#include + +/* Widths, split by whether the region ITSELF is nested. The split is the whole + * point: the defect that motivated this file was invisible in the outer team's + * width (a correct 8) and only showed in the inner one (16). */ +static atomic_uint_fast64_t w_outer = 0; /* widest depth-1 team */ +static atomic_uint_fast64_t w_nested = 0; /* widest team at depth >= 2 */ +static atomic_uint_fast64_t w_any = 0; /* widest team at any depth */ +static atomic_uint_fast64_t r_any = 0; /* largest `nthreads` requested */ +static atomic_uint_fast64_t n_unnamed = 0; /* entries with nthreads == 0 */ +static atomic_uint_fast64_t n_entries = 0; /* team creations observed */ +static atomic_uint_fast64_t d_max = 0; /* deepest level reached */ + +typedef int (*int_fn_t)(void); +typedef void (*fn_t)(void *); +typedef void (*plain_t)(fn_t, void *, unsigned, unsigned); +typedef void (*loop_t)(fn_t, void *, unsigned, long, long, long, long, unsigned); + +static plain_t real_plain; +static loop_t real_loop; +static int_fn_t omp_level; +static int_fn_t omp_width; + +/* + * RTLD_NEXT cannot find libgomp here: CPython dlopens extension modules with + * RTLD_LOCAL, so libgomp lands in a local scope RTLD_NEXT never searches and + * reports "undefined symbol". dlopen on the already-loaded library returns a + * handle to that same mapping, and dlsym through the handle works. + */ +static void *gomp(void) +{ + static void *h; + if (!h) { + h = dlopen("libgomp.so.1", RTLD_NOW | RTLD_NOLOAD); + if (!h) + h = dlopen("libgomp.so.1", RTLD_NOW); + if (!h) { + fprintf(stderr, "teamwidth: dlopen libgomp.so.1 failed: %s\n", + dlerror()); + _exit(96); + } + } + return h; +} + +static void *need(const char *sym, int code) +{ + void *p = dlsym(gomp(), sym); + if (!p) { + fprintf(stderr, "teamwidth: dlsym %s failed\n", sym); + _exit(code); + } + return p; +} + +static void resolve(void) +{ + if (!real_plain) real_plain = (plain_t)need("GOMP_parallel", 97); + if (!real_loop) + real_loop = (loop_t)need("GOMP_parallel_loop_nonmonotonic_dynamic", 98); + /* + * Both of these must come from libgomp, not from a thread-local counter of + * our own. A worker thread entering a region from inside its team sees its + * own TLS depth as 0 and would be charged as outermost -- the error that + * made an earlier shim report 755% of wall at 16 threads. + */ + if (!omp_level) omp_level = (int_fn_t)need("omp_get_level", 99); + if (!omp_width) omp_width = (int_fn_t)need("omp_get_num_threads", 95); +} + +static void bump_max(atomic_uint_fast64_t *slot, uint_fast64_t v) +{ + uint_fast64_t prev = atomic_load(slot); + while (v > prev && !atomic_compare_exchange_weak(slot, &prev, v)) + ; +} + +/* + * Runs as the team's body, once per thread. Every member of a team sees the + * same `omp_get_num_threads()`, so the atomic max collapses them to one + * observation per region and no count is needed. + */ +struct tramp { fn_t fn; void *data; }; + +static void observe(void *p) +{ + struct tramp *t = (struct tramp *)p; + /* + * Inside the region, so level 1 means this region is the outermost and + * level >= 2 means it is nested. An INACTIVE nested region -- the default, + * where OMP_MAX_ACTIVE_LEVELS is 1 -- still raises the level but has a + * width of 1, so it is recorded truthfully as a team of one and cannot + * look like a violation. + */ + const uint_fast64_t lvl = (uint_fast64_t)omp_level(); + const uint_fast64_t width = (uint_fast64_t)omp_width(); + + bump_max(&w_any, width); + bump_max(lvl >= 2 ? &w_nested : &w_outer, width); + bump_max(&d_max, lvl); + + t->fn(t->data); +} + +/* + * `t` lives on this frame, which is safe because GOMP_parallel is synchronous: + * it creates the team, runs the body on every member, joins, and only then + * returns. The trampoline cannot outlive the call that set it up. + */ +static void record_request(unsigned nthreads) +{ + atomic_fetch_add(&n_entries, 1); + if (nthreads == 0) + atomic_fetch_add(&n_unnamed, 1); + else + bump_max(&r_any, (uint_fast64_t)nthreads); +} + +void GOMP_parallel(fn_t fn, void *data, unsigned nthreads, unsigned flags) +{ + resolve(); + record_request(nthreads); + struct tramp t = { fn, data }; + real_plain(observe, &t, nthreads, flags); +} + +void GOMP_parallel_loop_nonmonotonic_dynamic(fn_t fn, void *data, + unsigned nthreads, long start, + long end, long incr, long chunk, + unsigned flags) +{ + resolve(); + record_request(nthreads); + struct tramp t = { fn, data }; + real_loop(observe, &t, nthreads, start, end, incr, chunk, flags); +} + +uint64_t beam_tw_outer(void) { return atomic_load(&w_outer); } +uint64_t beam_tw_nested(void) { return atomic_load(&w_nested); } +uint64_t beam_tw_widest(void) { return atomic_load(&w_any); } +uint64_t beam_tw_requested(void) { return atomic_load(&r_any); } +uint64_t beam_tw_unnamed(void) { return atomic_load(&n_unnamed); } +uint64_t beam_tw_entries(void) { return atomic_load(&n_entries); } +uint64_t beam_tw_depth(void) { return atomic_load(&d_max); } + +/* + * Reset before the call under test. Without this the counters would carry + * whatever `import BEAM` and the fixture build did, and the widest team in the + * process is not evidence about one API call. + */ +void beam_tw_reset(void) +{ + atomic_store(&w_outer, 0); + atomic_store(&w_nested, 0); + atomic_store(&w_any, 0); + atomic_store(&r_any, 0); + atomic_store(&n_unnamed, 0); + atomic_store(&n_entries, 0); + atomic_store(&d_max, 0); +} diff --git a/verification/tests/test_teamwidth.py b/verification/tests/test_teamwidth.py new file mode 100644 index 0000000..28bc864 --- /dev/null +++ b/verification/tests/test_teamwidth.py @@ -0,0 +1,207 @@ +"""The width of the teams BEAM actually creates, measured rather than read. + +Every thread check before this one was static. `check_lib.thread_count_clauses` +proves all 93 parallel regions NAME a thread count; the GIL scan proves every +GIL-releasing region RESOLVES a plan. Neither can see what the runtime granted, +and that gap is where the nesting defect lived: `beam_threads()` handed the +configured cap to a worker thread, so an 8-thread plan opened eight teams of +sixteen, while `thread counts` was OK in the very same gate run -- the clause +was present and correct and only its value on a worker was wrong. + +`verification/teamwidth.c` interposes the two libgomp entry points through which +BEAM creates teams and records, per region entry, the count REQUESTED and the +width that actually RAN. Measured on one `entropy()` call, plan pinned at 8: +**949 team creations**, which is why reading 93 pragmas was never going to +answer this. + +The two channels are not redundant, and the mutation that proves it is the +reason this file asserts on both. With the one-line guard removed from +`beam_threads()`: + + nesting ON (OMP_MAX_ACTIVE_LEVELS=2) requested 16, nested ran 16, plan 8 + nesting OFF (the default) requested 16, nested ran 1, plan 8 + +So in the environment every user actually gets, the defect was INVISIBLE in the +width that ran -- libgomp declines to widen a nested region when nesting is off, +so the actual teams were a blameless 8 and 1 -- and BEAM was still emitting +`num_threads(16)` on them. Only the runtime's default policy stood between the +plan and sixteen-way oversubscription. A check on the actual width alone would +have passed on the mutant; the requested channel catches it with no special +environment at all. That is why `test_no_region_asks_for_more_than_the_plan` is +the load-bearing test here and the actual-width tests back it up. + +`test_the_observer_wraps_every_team_creating_entry_point` is what keeps the +whole file honest: it reads the built extension's imports and fails if BEAM ever +grows a third way to create a team, because the observer would then be blind and +would go on reporting zero violations. And +`test_the_measurement_reached_a_nested_region` refuses to let a clean result +stand without evidence that the nested path ran at all -- a dead path and a +well-behaved one produce the same zero. +""" +import json +import os +import re +import subprocess +import sys +from pathlib import Path + +import pytest + +ROOT = Path(__file__).resolve().parents[1].parent +SHIM = ROOT / "build" / "teamwidth.so" +SHIM_SRC = ROOT / "verification" / "teamwidth.c" + +requires_shim = pytest.mark.skipif( + not SHIM.exists() or not sys.platform.startswith("linux"), + reason="needs Linux and build/teamwidth.so; run `make teamwidth` first") + + +# Builds a model, asks BEAM what it planned, resets the counters, makes ONE +# call, and reports. The reset matters: without it the widest team in the +# process would include the fixture's own build, and that is not evidence +# about the call under test. +_CHILD = """ +import ctypes, json, random +import BEAM +from BEAM import BeamModel + +lib = ctypes.CDLL(None) +NAMES = ("outer", "nested", "widest", "requested", "unnamed", "entries", "depth") +for n in NAMES: + f = getattr(lib, "beam_tw_" + n) + f.restype, f.argtypes = ctypes.c_uint64, [] +lib.beam_tw_reset.restype, lib.beam_tw_reset.argtypes = None, [] + +rng = random.Random(7) +seqs = ["TG" + "".join(rng.choice("ACGT") for _ in range(rng.randint(2, 20))) + "C" + for _ in range(800)] +m = BeamModel(seqs, abundances=[rng.randint(1, 40) for _ in seqs], + alphabet="nt", order=3, max_length=24) +plan = BEAM.parallel_plan()["plan"] + +lib.beam_tw_reset() +h = m.entropy() +out = {n: getattr(lib, "beam_tw_" + n)() for n in NAMES} +out["plan"] = plan +out["entropy"] = h +print(json.dumps(out)) +""" + +_CACHE: dict[bool, dict] = {} + + +def _observe(nesting: bool) -> dict: + """One child run, cached. `BEAM_AVAILABLE_CORES` pins the plan so the + assertions do not move with the load on the machine, and OMP_NUM_THREADS is + removed because setting it makes the policy stand aside entirely -- the plan + would then be the environment's number and the comparison vacuous. + + Attribution rests on where the reset goes. LD_PRELOAD interposes libgomp for + the whole process, so a counter read at exit would mix in anything else in + the process that uses OpenMP -- a BLAS built against libgomp, for instance. + The child resets immediately before the one call under test and reads + immediately after, and nothing else in that window calls out to another + library, so every region counted is BEAM's. The model is built BEFORE the + reset for the same reason.""" + if nesting in _CACHE: + return _CACHE[nesting] + env = dict(os.environ, BEAM_AVAILABLE_CORES="16", + LD_PRELOAD=str(SHIM)) + env.pop("OMP_NUM_THREADS", None) + if nesting: + env["OMP_MAX_ACTIVE_LEVELS"] = "2" + else: + env.pop("OMP_MAX_ACTIVE_LEVELS", None) + r = subprocess.run([sys.executable, "-c", _CHILD], capture_output=True, + text=True, encoding="utf-8", timeout=900, env=env) + assert r.returncode == 0, r.stderr[-3000:] + got = json.loads(r.stdout.strip().splitlines()[-1]) + if got["plan"] < 2: + pytest.skip(f"a plan of {got['plan']} cannot be exceeded by widening") + _CACHE[nesting] = got + return got + + +def test_the_observer_wraps_every_team_creating_entry_point(): + """The observer is only complete while BEAM creates teams through the entry + points it interposes. A third one would leave it blind AND quiet, which is + the worst failure a checking tool has: `nm` on the built extension is the + only thing that can tell the difference, so the set is derived from the + artifact and from the shim's own source, never written down here twice.""" + so = sorted(ROOT.glob("src/BEAM/_cbeam*.so")) + if not so: + pytest.skip("no built extension to read imports from") + out = subprocess.run(["nm", "--undefined-only", str(so[-1])], + capture_output=True, text=True, encoding="utf-8") + if out.returncode != 0: + pytest.skip("nm unavailable") + imported = {m.group(0) for m in + re.finditer(r"GOMP_parallel\w*", out.stdout)} + wrapped = set(re.findall(r"^void (GOMP_\w+)\(", SHIM_SRC.read_text( + encoding="utf-8"), re.MULTILINE)) + + missed = imported - wrapped + assert not missed, ( + f"BEAM creates teams through {sorted(missed)}, which the observer does " + f"not wrap: it would report zero violations while seeing none of them") + + +@requires_shim +def test_no_region_asks_for_more_than_the_plan(): + """The load-bearing one. A region's `num_threads(...)` is BEAM's own + arithmetic, and it is wrong independently of whether the runtime indulges + it: the mutant asks for 16 against a plan of 8 in the DEFAULT environment, + where every actual team is still the correct width. Catching that needs no + OMP_MAX_ACTIVE_LEVELS and no nesting -- only a count of what was asked.""" + got = _observe(nesting=False) + assert got["requested"] <= got["plan"], ( + f"a region asked for {got['requested']} threads against a plan of " + f"{got['plan']}; the runtime may have declined, which is luck, not " + f"design: {got}") + + +@requires_shim +def test_no_team_runs_wider_than_the_plan(): + got = _observe(nesting=False) + assert got["widest"] <= got["plan"], ( + f"a team ran {got['widest']} threads wide against a plan of " + f"{got['plan']}: {got}") + + +@requires_shim +def test_a_nesting_environment_widens_nothing(): + """`OMP_MAX_ACTIVE_LEVELS=2` is the environment the defect needed, and a + caller can set it: BEAM cannot pin it back without `omp_set_max_active_levels`, + process-global state that two calls on two threads would fight over. So the + guarantee has to hold under it rather than forbid it.""" + got = _observe(nesting=True) + assert got["nested"] <= got["plan"] and got["widest"] <= got["plan"], ( + f"nesting widened a team past the plan: {got}") + assert got["requested"] <= got["plan"], ( + f"nesting made a region ask past the plan: {got}") + + +@requires_shim +def test_every_region_that_ran_named_a_thread_count(): + """The runtime counterpart of `check_lib.thread_count_clauses`. That check + reads the sources and so covers regions whether or not they execute; this + one covers regions that executed whether or not the source scan understood + them. A zero here means no region reached libgomp with `nthreads == 0`, + which is what a missing clause looks like from the outside.""" + got = _observe(nesting=False) + assert got["unnamed"] == 0, ( + f"{got['unnamed']} of {got['entries']} regions ran without naming a " + f"thread count: {got}") + + +@requires_shim +def test_the_measurement_reached_a_nested_region(): + """Without this, every other assertion here could be passing because the + nested path never ran. A dead path and a well-behaved one both report + nothing, and the parallelism work has already been bitten once by a check + whose claim outran its evidence.""" + got = _observe(nesting=True) + assert got["entries"] > 0, f"the observer saw no teams at all: {got}" + assert got["depth"] >= 2, ( + f"no nested region was entered, so the nesting assertions prove " + f"nothing: {got}")