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
8 changes: 8 additions & 0 deletions .github/workflows/verification.yml
Original file line number Diff line number Diff line change
Expand Up @@ -190,6 +190,14 @@ jobs:
- uses: Swatinem/rust-cache@v2
with:
key: mailbox-loom
# Under the Loom cfg every `sync` shim type is Loom's, so a std or
# parking_lot atomic/lock left in a core is a direct use the model
# cannot see (concurrency/clippy.toml; the harnesses deny it on the
# included core). Other clippy lints are the ci.yml job's business.
- name: Loom-checked cores synchronize only through their shim
env:
RUSTFLAGS: --cfg spawned_scheduler_loom
run: cargo clippy --locked -p spawned-concurrency --no-default-features --test mailbox_admission_loom --test reply_slot_loom --test registry_turn_loom --test job_core_loom --test link_fence_loom --test stop_token_loom -- -A clippy::all
- name: Model-check the production mailbox admission algorithm
env:
RUSTFLAGS: --cfg spawned_scheduler_loom
Expand Down
5 changes: 5 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,11 @@

- Clarify dispatch admission when a stop races a message, and check deferred
token ownership before drop callbacks in debug builds. Release behavior is unchanged.
- Keep the Loom models from drifting: a clippy ban (`concurrency/clippy.toml`,
checked under the Loom cfg) on direct std/`parking_lot` synchronization in the
Loom-checked cores, and `model-sync` now requires a PR changing such a core to
update its Loom harness (`[loom.*]` in `verification/model-map.toml`) or carry
the `no-model-change` waiver.

## 0.8.0 — 2026-11-15

Expand Down
6 changes: 6 additions & 0 deletions concurrency/Cargo.toml
Original file line number Diff line number Diff line change
Expand Up @@ -89,6 +89,12 @@ loom = { version = "0.7", features = ["futures"] }
[lints.rust]
unexpected_cfgs = { level = "warn", check-cfg = ['cfg(spawned_scheduler_loom)', 'cfg(spawned_sim)', 'cfg(kani)', 'cfg(kani_slow)'] }

# clippy.toml bans direct std/parking_lot synchronization in the Loom-checked
# cores; only the Loom harnesses deny it (on the included core), see there.
[lints.clippy]
disallowed_types = "allow"
disallowed_methods = "allow"

[[bench]]
name = "lifecycle_soak"
harness = false
Expand Down
45 changes: 45 additions & 0 deletions concurrency/clippy.toml
Original file line number Diff line number Diff line change
@@ -0,0 +1,45 @@
# Synchronization the Loom models must see (docs/TESTING.md, Loom).
#
# The Loom-checked cores (reply/turn.rs, reply/slot.rs, reply/job_core.rs,
# stop_token/core.rs, link/table.rs, monitor/fence.rs, mailbox_admission.rs)
# take every atomic, lock and condition variable from a `sync` shim: the
# parent module's re-exports of the std/parking_lot types in production (so
# zero cost), Loom's types in the tests/*_loom.rs harness that includes the
# core with `#[path]`. A direct std or parking_lot type in a core is invisible
# to Loom, so the model would silently stop covering it.
#
# Because the production shim *re-exports* the same types, the lint cannot
# tell a shim use from a direct one in an ordinary build, so the package
# allows both lints (Cargo.toml [lints.clippy]) and each Loom harness denies
# them on the included core's `mod` item. The verification workflow runs
# clippy on those harnesses with `--cfg spawned_scheduler_loom`, where every
# shim type is Loom's and anything left on these lists is a direct use.
disallowed-types = [
{ path = "std::sync::Mutex", reason = "Loom-checked core: use the `sync` shim" },
{ path = "std::sync::MutexGuard", reason = "Loom-checked core: use the `sync` shim" },
{ path = "std::sync::RwLock", reason = "Loom-checked core: use the `sync` shim" },
{ path = "std::sync::Condvar", reason = "Loom-checked core: use the `sync` shim" },
{ path = "std::sync::Barrier", reason = "Loom-checked core: use the `sync` shim" },
{ path = "std::sync::atomic::AtomicBool", reason = "Loom-checked core: use the `sync` shim" },
{ path = "std::sync::atomic::AtomicU8", reason = "Loom-checked core: use the `sync` shim" },
{ path = "std::sync::atomic::AtomicU16", reason = "Loom-checked core: use the `sync` shim" },
{ path = "std::sync::atomic::AtomicU32", reason = "Loom-checked core: use the `sync` shim" },
{ path = "std::sync::atomic::AtomicU64", reason = "Loom-checked core: use the `sync` shim" },
{ path = "std::sync::atomic::AtomicUsize", reason = "Loom-checked core: use the `sync` shim" },
{ path = "std::sync::atomic::AtomicI8", reason = "Loom-checked core: use the `sync` shim" },
{ path = "std::sync::atomic::AtomicI16", reason = "Loom-checked core: use the `sync` shim" },
{ path = "std::sync::atomic::AtomicI32", reason = "Loom-checked core: use the `sync` shim" },
{ path = "std::sync::atomic::AtomicI64", reason = "Loom-checked core: use the `sync` shim" },
{ path = "std::sync::atomic::AtomicIsize", reason = "Loom-checked core: use the `sync` shim" },
{ path = "std::sync::atomic::AtomicPtr", reason = "Loom-checked core: use the `sync` shim" },
{ path = "parking_lot::Mutex", reason = "Loom-checked core: use the `sync` shim" },
{ path = "parking_lot::MutexGuard", reason = "Loom-checked core: use the `sync` shim" },
{ path = "parking_lot::RwLock", reason = "Loom-checked core: use the `sync` shim" },
{ path = "parking_lot::Condvar", reason = "Loom-checked core: use the `sync` shim" },
{ path = "parking_lot::ReentrantMutex", reason = "Loom-checked core: use the `sync` shim" },
]
disallowed-methods = [
{ path = "std::sync::atomic::fence", reason = "Loom-checked core: use the `sync` shim" },
{ path = "std::thread::spawn", reason = "Loom-checked core: use the `sync` shim" },
{ path = "std::thread::yield_now", reason = "Loom-checked core: use the `sync` shim" },
]
2 changes: 2 additions & 0 deletions concurrency/tests/job_core_loom.rs
Original file line number Diff line number Diff line change
Expand Up @@ -131,10 +131,12 @@ mod model_arc {
}

#[allow(dead_code)]
#[deny(clippy::disallowed_types, clippy::disallowed_methods)] // concurrency/clippy.toml
#[path = "../src/reply/job_core.rs"]
mod job_core;

#[allow(dead_code)]
#[deny(clippy::disallowed_types, clippy::disallowed_methods)] // concurrency/clippy.toml
#[path = "../src/reply/slot.rs"]
mod slot;

Expand Down
2 changes: 2 additions & 0 deletions concurrency/tests/link_fence_loom.rs
Original file line number Diff line number Diff line change
Expand Up @@ -57,10 +57,12 @@ pub(crate) struct SignalTarget {
}

#[allow(dead_code)]
#[deny(clippy::disallowed_types, clippy::disallowed_methods)] // concurrency/clippy.toml
#[path = "../src/link/table.rs"]
mod table;

#[allow(dead_code)]
#[deny(clippy::disallowed_types, clippy::disallowed_methods)] // concurrency/clippy.toml
#[path = "../src/monitor/fence.rs"]
mod fence;

Expand Down
1 change: 1 addition & 0 deletions concurrency/tests/mailbox_admission_loom.rs
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,7 @@ use loom::sync::{
atomic::{AtomicUsize, Ordering},
Arc, Condvar, Mutex,
};
#[deny(clippy::disallowed_types, clippy::disallowed_methods)] // concurrency/clippy.toml
#[path = "../src/mailbox_admission.rs"]
mod admission;

Expand Down
1 change: 1 addition & 0 deletions concurrency/tests/registry_turn_loom.rs
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,7 @@ mod sync {
}

#[allow(dead_code)]
#[deny(clippy::disallowed_types, clippy::disallowed_methods)] // concurrency/clippy.toml
#[path = "../src/reply/turn.rs"]
mod turn;

Expand Down
1 change: 1 addition & 0 deletions concurrency/tests/reply_slot_loom.rs
Original file line number Diff line number Diff line change
Expand Up @@ -59,6 +59,7 @@ mod sync {
}

#[allow(dead_code)]
#[deny(clippy::disallowed_types, clippy::disallowed_methods)] // concurrency/clippy.toml
#[path = "../src/reply/slot.rs"]
mod slot;

Expand Down
1 change: 1 addition & 0 deletions concurrency/tests/stop_token_loom.rs
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,7 @@
mod sync {
pub(crate) use loom::sync::atomic::{AtomicBool, Ordering};
}
#[deny(clippy::disallowed_types, clippy::disallowed_methods)] // concurrency/clippy.toml
#[path = "../src/stop_token/core.rs"]
mod core;
use self::core::StopFlag;
Expand Down
11 changes: 11 additions & 0 deletions docs/TESTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -1058,6 +1058,17 @@ RUSTFLAGS="--cfg spawned_scheduler_loom" cargo test --release -p spawned-concurr
--test link_fence_loom --test stop_token_loom
```

Two checks keep these models in step with the cores. A direct std or
`parking_lot` atomic, lock or condvar in a core would bypass the shim and be
invisible to Loom: `concurrency/clippy.toml` bans them, and each harness denies
the lint on the `#[path]`-included core, so clippy under the Loom cfg (the
`mailbox-loom` job in `verification.yml`) rejects any that is left; production
shims re-export the same types, so the ordinary build pays nothing and the lint
is allowed there. And `verification/model-map.toml` maps every harness to the
cores it includes (`[loom.*]`): the required `model-sync` check fails a PR that
changes a core without changing one of its harnesses, unless it carries the
`no-model-change` waiver.

`stop_token_loom` shares the private actor stop flag (`src/stop_token/core.rs`).
A stop publishes its flag before notifying Tokio's cancellation waiter; the
message loop checks that flag with one acquire load after receiving and before
Expand Down
100 changes: 85 additions & 15 deletions scripts/check-model-sync.py
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,8 @@

`paths`: fails if the PR changes a code file a model covers without changing
any of that file's models (model, MC configurations, inductive/coverage
modules or trace spec). Exempt: changes to comments only or only inside a
modules or trace spec) and, for a Loom-checked core (`[loom.*]`), without
changing a Loom harness that includes it (both sides are required). Exempt: changes to comments only or only inside a
`#[cfg(test)] mod` block, and PRs with the `no-model-change` label AND a body
line `Model: no change because <reason>`. Labels and body come from
`GITHUB_EVENT_PATH` in Actions, `--pr N` (gh CLI) or `--labels`/`--body`.
Expand All @@ -25,7 +26,9 @@
validation (a Trace*.tla spec that trace_check.py runs and recorded events
reach), unless it has a `tlc_only` allowlist entry with a reason and a
tracking item; and each model's covered action keys in
coverage-baseline.json may not drop below its `coverage_floor`.
coverage-baseline.json may not drop below its `coverage_floor`. Every Loom
harness that `#[path]`-includes production code needs a `[loom.*]` entry whose
`code` is exactly what it includes.

Standard library only; Python 3.9+ (a TOML subset parser is used when
`tomllib` is unavailable).
Expand Down Expand Up @@ -357,11 +360,21 @@ def tla_content(src):
return [l.strip() for l in src.splitlines() if l.strip()]


def rust_content(src):
"""Rust source without `//` comment lines and blank lines."""
return [l.strip() for l in src.splitlines() if l.strip() and not l.strip().startswith("//")]


def model_file_changed(root, base, head, path):
"""A model-side file counts as updated unless its change is comments only."""
if base is None or not path.endswith(".tla"):
"""A model-side file (TLA+ module or Loom harness) counts as updated
unless its change is comments only."""
if base is None:
return True
return tla_content(show(root, base, path)) != tla_content(show(root, head, path))
if path.endswith(".tla"):
return tla_content(show(root, base, path)) != tla_content(show(root, head, path))
if path.endswith(".rs"):
return rust_content(show(root, base, path)) != rust_content(show(root, head, path))
return True


def pr_context(args):
Expand Down Expand Up @@ -394,7 +407,10 @@ def check_paths(args, root):
print("model-sync: merge queue run; the pull_request run already enforced the check")
return 0
config = load_map(root)
models = config["models"]
# TLA+ models and Loom harnesses are separate checks of the same code:
# one updated covering model satisfies the TLA+ side, one updated
# covering harness the Loom side, and a file both cover needs both.
groups = [("", config["models"]), ("Loom ", config.get("loom", {}))]
if args.files is not None:
changed, base, head = list(args.files), None, None
else:
Expand All @@ -405,27 +421,35 @@ def check_paths(args, root):
print(f"model-sync: no merge base between {args.base or 'origin/main'} and {head}; fetch it or pass --base")
return 2
changed = git(root, "diff", "--name-only", "--no-renames", f"{base}...{head}").split()
entries = {prefix + name: m for prefix, group in groups for name, m in group.items()}
model_changes = [p for p in changed
if any(glob_match(p, g) for m in models.values() for g in m["files"])]
if any(glob_match(p, g) for m in entries.values() for g in m["files"])]
for p in model_changes:
if not model_file_changed(root, base, head, p):
print(f"note {p}: comments only, does not count as a model update")
model_changes = [p for p in model_changes if model_file_changed(root, base, head, p)]
touched = {name for name, m in models.items()
touched = {name for name, m in entries.items()
if any(glob_match(p, g) for p in model_changes for g in m["files"])}
missing = {}
for path in changed:
covering = sorted(name for name, m in models.items() if any(glob_match(path, g) for g in m["code"]))
if not covering:
stale, updated = [], []
for prefix, group in groups:
covering = sorted(prefix + name for name, m in group.items()
if any(glob_match(path, g) for g in m["code"]))
if covering and touched.intersection(covering):
updated += sorted(touched.intersection(covering))
elif covering:
stale += covering
if not stale and not updated:
continue
if touched.intersection(covering):
print(f"ok {path}: model updated ({', '.join(sorted(touched.intersection(covering)))})")
if not stale:
print(f"ok {path}: model updated ({', '.join(updated)})")
continue
kind = exempt_change(root, base, head, path) if base else None
if kind:
print(f"ok {path}: {kind} only")
continue
missing[path] = covering
missing[path] = stale
if not missing:
print("model-sync: every changed modelled file has its model updated (or is exempt)")
return 0
Expand All @@ -439,8 +463,9 @@ def check_paths(args, root):
return 0
print(f"""
model-sync: this PR changes modelled code without changing its model.
Models track the code: update the model (verification/tla/) in this PR, or,
if the behaviour the model specifies is unchanged, add the `{LABEL}` label
Models track the code: update the model (verification/tla/) or Loom harness
(concurrency/tests/*_loom.rs) in this PR, or, if the behaviour the model
specifies is unchanged, add the `{LABEL}` label
AND a PR body line `Model: no change because <reason>`.
Missing now: {'' if has_label else f'the `{LABEL}` label; '}{'' if has_reason else 'the `Model: no change because ...` line'}
Mapping: {MAP}""")
Expand Down Expand Up @@ -664,6 +689,48 @@ def trace_validation(root, config, model):
return None, "; ".join(reasons) or "no trace spec"


LOOM_HARNESSES = "*/tests/*_loom.rs"


def loom_includes(root, harness):
"""Repository paths of the sources a Loom harness compiles with
`#[path]` (the production cores it checks against Loom's types);
attributes in comments do not count."""
src = (root / harness).read_text()
masked, strings = rust_mask(src)
out = set()
for m in re.finditer(r'#\[path\s*=\s*"', masked):
target = Path(os.path.normpath((root / harness).parent / strings[m.end() - 1]))
out.add(target.relative_to(root).as_posix())
return out


def check_loom(config, root):
"""Every Loom harness that includes production code is in the map, and
each [loom.X] entry's `code` is exactly what its `files` include, so the
paths check cannot miss a core."""
errors, rows = [], []
loom = config.get("loom", {})
mapped = set()
for name, entry in sorted(loom.items()):
files, code = entry.get("files", []), set(entry.get("code", []))
included = set()
for f in files:
mapped.add(f)
if not (root / f).is_file():
errors.append(f"[loom.{name}]: harness {f} does not exist")
continue
included |= loom_includes(root, f)
if included != code:
errors.append(f"[loom.{name}]: `code` must list exactly the files its harness includes with #[path]: "
f"missing {sorted(included - code)}, extra {sorted(code - included)}")
rows.append(f"{'Loom ' + name:18} {', '.join(files)} -> {', '.join(sorted(code))}")
for harness in sorted(p.relative_to(root).as_posix() for p in root.glob(LOOM_HARNESSES)):
if harness not in mapped and loom_includes(root, harness):
errors.append(f"Loom harness {harness} includes production code but has no [loom.*] entry in {MAP}")
return errors, rows


def check_models(args, root):
config = load_map(root)
models = config["models"]
Expand Down Expand Up @@ -705,6 +772,9 @@ def check_models(args, root):
elif spec and key in baseline:
errors.append(f"{model}: trace-validated with a coverage baseline but no `coverage_floor` in {MAP}")
rows.append(f"{model:18} {status}")
loom_errors, loom_rows = check_loom(config, root)
errors += loom_errors
rows += loom_rows
for r in rows:
print(r)
for w in warnings:
Expand Down
Loading
Loading