Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 2 additions & 1 deletion src/native/bindings/python/model_bindings.c
Original file line number Diff line number Diff line change
Expand Up @@ -354,12 +354,13 @@ PyObject *py_parallel_plan(PyObject *self, PyObject *arg) {
BeamPlanIn in;
beam_plan_inputs(&in);
return Py_BuildValue(
"{s:i,s:i,s:O,s:i,s:i,s:i}",
"{s:i,s:i,s:O,s:i,s:i,s:O,s:i}",
"plan", beam_plan_threads(&in),
"user_cap", in.user_cap,
"omp_num_threads", in.omp_env ? Py_True : Py_False,
"cores", in.cores,
"available", in.available,
"available_measured", in.available_measured ? Py_True : Py_False,
"max_width", beam_plan_max_width());
}

Expand Down
13 changes: 11 additions & 2 deletions src/native/core/avail.c
Original file line number Diff line number Diff line change
Expand Up @@ -351,10 +351,18 @@ static int available_pin(void) {
return (int)n;
}

int beam_available_cores(void) {
int beam_available_cores(void) { return beam_available_cores_ex(NULL); }

int beam_available_cores_ex(int *measured) {
if (measured) *measured = 0;
const int allowed = beam_allowed_cores();
const int pin = available_pin();
if (pin > 0) return pin < allowed ? pin : allowed;
if (pin > 0) {
/* A pin is a measurement in the only sense that matters here: the
* estimate came from outside rather than from the fallback. */
if (measured) *measured = 1;
return pin < allowed ? pin : allowed;
}

int nr = -1;
#if defined(__linux__)
Expand All @@ -371,5 +379,6 @@ int beam_available_cores(void) {
*/
nr = sampled_competitors(allowed);
#endif
if (measured && nr >= 1) *measured = 1;
return beam_available_from(allowed, nr);
}
2 changes: 1 addition & 1 deletion src/native/core/threads.c
Original file line number Diff line number Diff line change
Expand Up @@ -98,7 +98,7 @@ void beam_plan_inputs(BeamPlanIn *in) {
#else
in->omp_max = 1;
#endif
in->available = beam_available_cores();
in->available = beam_available_cores_ex(&in->available_measured);
}

int beam_plan_enter_default(void) {
Expand Down
17 changes: 17 additions & 0 deletions src/native/internal/beam/avail.h
Original file line number Diff line number Diff line change
Expand Up @@ -185,4 +185,21 @@ int beam_competitors_from_samples(BeamAvailSample *prev, uint64_t sys,
*/
int beam_available_cores(void);

/**
* The same estimate, also reporting whether it was MEASURED or assumed.
* `*measured` becomes 1 when the machine answered and 0 when the estimate fell
* back to "assume no contention". `measured` may be NULL.
*
* One read, both answers, which is the point: asking a second time would take
* a second sample, and on the sampled platforms a sample consumes the window
* it is measured over -- so a probe that re-read would report "not measured"
* almost always, and would perturb the signal it claims to describe.
*
* This exists because an idle machine and a dead code path produce the same
* number. On a quiet runner `available == allowed` whether the reading worked
* or returned -1, so without this flag there is no way to tell a working
* estimate from one that never ran -- and CI would pass either way.
*/
int beam_available_cores_ex(int *measured);

#endif /* BEAM_INTERNAL_AVAIL_H */
7 changes: 7 additions & 0 deletions src/native/internal/beam/plan.h
Original file line number Diff line number Diff line change
Expand Up @@ -44,6 +44,13 @@ typedef struct {
int cores; /**< Cores present, from omp_get_num_procs(). */
int omp_max; /**< omp_get_max_threads(): respects OMP_NUM_THREADS.*/
int available; /**< Estimated free cores. */
/**
* 1 when `available` was measured, 0 when it is the "assume no contention"
* fallback. REPORTING ONLY: beam_plan_threads() does not read it, and must
* not -- a plan that behaved differently depending on whether the estimate
* was measured would make the fallback a second policy.
*/
int available_measured;
} BeamPlanIn;

/**
Expand Down
40 changes: 40 additions & 0 deletions tests/native/test_avail.c
Original file line number Diff line number Diff line change
Expand Up @@ -393,6 +393,44 @@ static void test_the_estimate_does_not_exceed_the_cores_present(void) {

/* ── Pinning the estimate ────────────────────────────────────── */

static void test_the_estimate_reports_whether_it_measured(void) {
/*
* An idle machine and a reading that never happened produce the same
* number, so the flag is the only way to tell them apart -- and the
* platforms without /proc spent their whole existence on the fallback
* without a test noticing.
*
* A pin counts as measured: the estimate came from outside rather than
* from "assume no contention", which is the distinction the flag draws.
* This part holds on every platform, unlike a bare reading.
*/
setenv("BEAM_AVAILABLE_CORES", "3", 1);
int measured = -1;
const int got = beam_available_cores_ex(&measured);
unsetenv("BEAM_AVAILABLE_CORES");
ASSERT_MSG(got == 3 || got == beam_cores_present(),
"a pin of three is honoured, or clamped to a smaller machine");
ASSERT_MSG(measured == 1, "a pin is a measurement, not a fallback");
PASS();
}

static void test_the_two_spellings_of_the_estimate_agree(void) {
/*
* beam_available_cores() must be exactly beam_available_cores_ex(NULL).
* They are read per call on the sampled platforms, so a second reading can
* legitimately differ -- the pin removes that freedom and makes the
* comparison exact.
*/
setenv("BEAM_AVAILABLE_CORES", "2", 1);
const int plain = beam_available_cores();
const int with_flag = beam_available_cores_ex(NULL);
unsetenv("BEAM_AVAILABLE_CORES");
ASSERT_MSG(plain == with_flag, "the two spellings must not drift apart");
ASSERT_MSG(with_flag == 2 || with_flag == beam_cores_present(),
"and both honour the pin");
PASS();
}

static void test_a_pinned_estimate_overrides_the_measurement(void) {
/*
* A load-aware plan is not reproducible between runs, which the design
Expand Down Expand Up @@ -472,6 +510,8 @@ int main(int argc, char **argv) {
RUN_TEST(test_more_competitors_never_frees_more_cores);
RUN_TEST(test_the_machine_reports_a_usable_estimate);
RUN_TEST(test_the_estimate_does_not_exceed_the_cores_present);
RUN_TEST(test_the_estimate_reports_whether_it_measured);
RUN_TEST(test_the_two_spellings_of_the_estimate_agree);
RUN_TEST(test_a_pinned_estimate_overrides_the_measurement);
RUN_TEST(test_a_nonsense_pin_is_ignored_rather_than_obeyed);
RUN_TEST(test_a_pin_above_the_cores_present_is_clamped);
Expand Down
36 changes: 35 additions & 1 deletion tests/suites/model/test_runtime.py
Original file line number Diff line number Diff line change
Expand Up @@ -107,7 +107,7 @@ def test_the_plan_reports_every_input_it_used():

plan = BEAM.parallel_plan()
for key in ("plan", "user_cap", "omp_num_threads", "cores",
"available", "max_width"):
"available", "available_measured", "max_width"):
assert key in plan, f"{key} missing from {sorted(plan)}"
assert plan["plan"] >= 1
assert plan["cores"] >= 1
Expand Down Expand Up @@ -155,6 +155,40 @@ def test_the_plan_is_capped_by_the_scaling_ceiling():
BEAM.set_threads(before)


def test_the_estimate_says_whether_it_measured_the_machine():
"""An idle machine and a dead code path report the same number.

On a quiet machine `available == cores` whether the reading worked or fell
back to "assume no contention", so the number alone cannot tell a working
estimate from one that never ran -- and every CI leg would pass either
way. That is how the platforms without /proc went from "always assumes an
idle machine" to "reads the machine" without a single test noticing the
difference, in both directions.

The platforms that sample need a window to measure over, so the first
reading on a thread is only a baseline. Two calls either side of one are
enough on every platform: Linux measures immediately, and the sampled
platforms measure by the second.
"""
import time

import BEAM

before = BEAM.threads()
try:
BEAM.set_threads(0)
BEAM.parallel_plan() # baseline, where one is needed
time.sleep(0.03) # longer than the 20 ms minimum
plan = BEAM.parallel_plan()
assert plan["available_measured"] is True, (
"availability was never measured, so the plan is running on the "
f"fallback rather than on this machine: {plan}"
)
assert 1 <= plan["available"] <= plan["cores"]
finally:
BEAM.set_threads(before)


def test_a_pinned_availability_is_visible_in_the_plan(monkeypatch):
"""`BEAM_AVAILABLE_CORES` is how a benchmark or a CI run buys back the
reproducibility that a load-aware plan costs, so it must be observable."""
Expand Down
51 changes: 51 additions & 0 deletions verification/baseline/RERECORDED.md
Original file line number Diff line number Diff line change
Expand Up @@ -3614,3 +3614,54 @@ gate only NOTES a new internal symbol, so leaving these unrecorded would have
cost nothing today and 2 permanent notes thereafter -- which is how 30 symbols
drifted across four merges before they were recorded in #7. Previous versions
kept as `c_cases.availsample.txt` and `c_symbols.availsample.txt`.

## The estimate says whether it measured (2026-11-15)

A follow-up to the section above, and the reason it was needed: CI passed on
all fifteen checks with the new sampled estimate, and that proved nothing about
whether the estimate ever ran. On a quiet runner `available == cores` whether
the reading worked or fell back to "assume no contention", so a working
estimate and a dead code path produce identical output — which is how those
platforms could have stayed on the fallback with every leg green, in both
directions.

`parallel_plan()` therefore reports `available_measured`, filled from the same
single reading (`beam_available_cores_ex`) rather than from a second one: on the
sampled platforms a sample CONSUMES the window it is measured over, so a probe
that re-read would report "not measured" almost always and would perturb the
signal it describes.

Three files moved, all inventory. No recorded NUMBER changed.

### `pytest_cases.txt`: 1243 -> 1244

- `tests/suites/model/test_runtime.py::test_the_estimate_says_whether_it_measured_the_machine`

Mutated against the real build, which is the only reason it is worth having:
pointing the Linux reader at `/proc/loadavg_absent` makes the machine never
answer, and the test fails with `assert False is True`. Restored, it passes. So
a pass on the macOS and Windows legs is evidence that the sampled path
measures, and not merely that it compiles.

### `c_cases.txt`: 450 -> 452

- `test_the_estimate_reports_whether_it_measured`
- `test_the_two_spellings_of_the_estimate_agree`

The first pins that a pin counts as measured (the estimate came from outside,
not from the fallback), which holds on every platform unlike a bare reading.
The second pins `beam_available_cores()` against
`beam_available_cores_ex(NULL)` under a pin, which removes the per-call freedom
the sampled platforms otherwise have and makes the comparison exact.

### `c_symbols.txt`: 263 -> 264

- `beam_available_cores_ex`

Previous versions kept as `c_cases.measuredflag.txt`,
`pytest_cases.measuredflag.txt` and `c_symbols.measuredflag.txt`.

`BeamPlanIn` gained `available_measured` to carry it. The field is reporting
only: `beam_plan_threads()` does not read it and must not, since a plan that
behaved differently depending on whether the estimate was measured would make
the fallback a second policy.
Loading
Loading