Skip to content

refactor: split tasks/threads actor.rs, supervision.rs and macros lib.rs into submodules - #278

Merged
unbalancedparentheses merged 20 commits into
mainfrom
refactor/split-large-files
Nov 16, 2026
Merged

unbalancedparentheses merged 20 commits into
mainfrom
refactor/split-large-files

Conversation

@unbalancedparentheses

@unbalancedparentheses unbalancedparentheses commented Nov 16, 2026 •

Copy link
Copy Markdown
Contributor

Splits the four largest source files mechanically, with no change to behaviour, public API or test names.

What moved where

Before After
concurrency/src/tasks/actor.rs (5.0k) actor.rs (traits, Context/ActorShared/ActorRef definitions, ActorStart, warn_on_block; 490 lines) + actor/envelope.rs, actor/context.rs, actor/actor_ref.rs, actor/lifecycle.rs (spawn, DeathFirst, run_actor*) + one file per test module (tests.rs, api_coverage.rs, stop_receive_probe.rs, ...)
concurrency/src/threads/actor.rs (3.3k) same layout under threads/actor/ (plus stop_wakeup_regression.rs)
concurrency/src/supervision.rs (3.6k) supervision.rs (public spec types: RestartMode, Backoff, SupervisorConfig, ChildSpec, ...; 415 lines) + supervision/child.rs (recovery queue, view, SupervisedChild), state.rs (Core, budget, failures), builder.rs (SupervisorBuilder, Supervisor), run.rs (run_supervisor, run_child, ...), policy_tests.rs; nested.rs is unchanged
macros/src/lib.rs (2.3k) lib.rs keeps the documented #[proc_macro_attribute] entry points, each delegating to <module>::expand; protocol.rs, actor.rs, lints.rs, send_handler.rs, sim_test.rs

How it was done: a script moved line ranges verbatim and made every private item it moved pub(super). A private item in the parent and a pub(super) item in a child are visible in exactly the same modules, so the visibility is unchanged. Test modules kept their names, so their paths (tasks::actor::stop_receive_probe::..., which verification.yml checks) are the same. Public items are still at the same paths, via pub use child::*. Generics, #[inline], crates and monomorphization are unchanged. The only non-move edit is that the macro entry points now call expand.

I did not extract a shared tasks/threads lifecycle module. The two dispatch loops look alike but differ in their receive and wakeup mechanics, so neither half is clearly identical, and merging them here would not be a pure move.

Also updated

  • verification/model-map.toml: tasks/actor/** and threads/actor/** are mapped to Lifecycle (and tasks/actor/** to ReplyTimer). supervision/** was already mapped. No floors or allowlists changed, and check-model-sync.py events/models pass locally.
  • Planted patches 01-03 and 05-08 are retargeted to supervision/state.rs and supervision/run.rs, and INDEX.tsv is updated. They apply again; the ones already stale on main (04, 10-17, 19, 20) are unchanged.
  • benchmarks/experiments/backend-experiments.patch is rebased onto the split. In a prepared tree, clippy passes with backend-experiments and the turn_regressions tests pass.
  • The cargo mutants file list, the semantics.md "Checked by" paths, and TESTING.md, the TLA README, CLAUDE.md and CHANGELOG.

Checks run locally

clippy with -D warnings on the workspace (default and --all-features), on --no-default-features + metrics, and on lifecycle-trace,failpoints,metrics,diagnostics. cargo check --tests under --cfg spawned_sim and --cfg spawned_scheduler_loom. cargo test -p spawned-concurrency --lib (243 passed, the same as before), the protocol_compile trybuild UI tests, and cargo fmt --check.

Model: no change because this only moves code between files (no behaviour change); the moved paths are mapped in model-map.toml so they stay covered.

@unbalancedparentheses unbalancedparentheses added the no-model-change Modelled code changed without a model change; the PR body says why (Model: no change because ...) label Nov 16, 2026
…files

# Conflicts:
#	benchmarks/experiments/backend-experiments.patch
#	concurrency/src/tasks/actor.rs
@unbalancedparentheses
unbalancedparentheses marked this pull request as ready for review November 16, 2026 14:19
@github-actions

Copy link
Copy Markdown

🤖 Gemini Code Review

⚠️ Warning: Diff was truncated from 27592 to 10000 lines. Some changes were not reviewed.

This PR is a clean mechanical refactor splitting supervision.rs, tasks/actor.rs, threads/actor.rs, and macros into smaller, focused submodules without altering behavior, visibility contracts, or public APIs.

  • All moved supervision state, builder, runner, child control, and test code in concurrency/src/supervision/{child,state,builder,run,policy_tests}.rs preserves the exact logic, lock ordering, and lifecycle trace points from supervision.rs.
  • .github/workflows/verification.yml is properly updated to include the new supervision/{child,state,builder,run}.rs files in cargo mutants.
  • benchmarks/experiments/backend-experiments.patch is updated to match the new tasks/actor/* module layout.

Looks good to merge.


Automated review by Gemini · gemini-4-argon · custom prompt

@github-actions

Copy link
Copy Markdown

🤖 Claude Code Review

⚠️ Warning: Diff was truncated from 27592 to 10000 lines. Some changes were not reviewed.

Review: PR #278, split the largest source files

The parts of the diff I could see are a faithful mechanical move. RecoveryQueue, View, Core, run_supervisor, run_recoveries, run_child, the builder and the policy tests match the removed code token for token. Function bodies are unchanged; only pub(super) visibility was added. I found no correctness or concurrency changes. Test paths are unchanged too: supervision::policy_tests::* and tasks::actor::<mod>::* keep their module_path!() names.

The diff is truncated partway through tasks/actor.rs. I did not see the threads/actor.rs split or the macros split. The comments below cover only what is shown.

Suggestions

1. Glob re-exports widen the public API surface (concurrency/src/supervision.rs:34-41)

pub use child::*;
pub(crate) use state::*;
pub use builder::*;
use run::*;

This is correct today, because only SupervisedChild, SupervisorBuilder, Supervisor and SupervisorReport are pub. The risk is future changes:

  • Any item later marked pub in child.rs or builder.rs silently becomes crate-root public API.
  • That is a semver hazard in a crate that otherwise seals traits for exactly this reason.

Prefer explicit lists:

pub use child::SupervisedChild;
pub use builder::{Supervisor, SupervisorBuilder, SupervisorReport};
pub(crate) use child::RecoveryQueue;   // used outside supervision (Kani/proofs?)
pub(crate) use state::admit_in_window;
use child::*; use state::*; use run::*; // module-internal

This also stops the pub(crate) use state::* glob from implicitly deciding which state items are crate-visible.

2. Mutation coverage likely regressed for the split actor files (.github/workflows/verification.yml)

The supervision cargo mutants job was updated with the new files. However:

  • If another mutants job filters on -f concurrency/src/tasks/actor.rs or threads/actor.rs, it now misses actor/{envelope,context,actor_ref,lifecycle}.rs. Those files hold the entire run loop.
  • Because of || true, that loss would be silent.

Please grep the workflows, plus any Kani/Loom or script configs that reference paths, for the old file names.

The new supervision file list is also easy to drift from. -f 'concurrency/src/supervision/*.rs' (cargo-mutants accepts globs) would avoid that. Exclude policy_tests.rs with -e if desired.

3. backend-experiments.patch is rebased by hand

The patch was regenerated against the new layout:

  • the use lifecycle::MessageTurn hook;
  • MessageTurn fields made pub(super) so turn_regressions.rs can construct it;
  • run_actor made pub(super).

The hunks look consistent with the new actor.rs (around lines 42 and 444) and lifecycle.rs. Nothing enforces that prepare.sh keeps applying, though. A cheap CI step would catch the next refactor that breaks it:

git apply --check benchmarks/experiments/backend-experiments.patch

Better still, apply the patch and run cargo check --features backend-experiments.

4. CLAUDE.md layout is now incomplete

The tree only mentions supervision/. Add tasks/actor/ and threads/actor/ (envelope, context, actor_ref, lifecycle, per-test files) and the per-macro modules in the macros crate. The CHANGELOG already describes these.

Minor

  • run.rs is still about 1.1k lines, and run_child alone is about 600. That is fine for a no-behaviour-change PR. A natural follow-up is to extract the "published → wait for stop → cleanup" block and the decision block into helpers.
  • Every submodule uses use super::*, and the parent globs the submodules back. Circular globs compile, but they hide real dependencies. Explicit imports in child.rs/state.rs would make the layering visible: child depends on nothing, state depends on child, run depends on both.
  • #[cfg(test)] use lifecycle::run_actor; in tasks/actor.rs exists only for test modules. A #[cfg(test)] pub(super) use block grouping all test-only re-exports (run_actor, test_context, and MessageTurn under experiments) would keep the test plumbing in one place.

Overall this is good to merge once (1) and (2) are addressed or confirmed.


Automated review by Claude · claude-opus-5-5 · custom prompt

@github-actions

Copy link
Copy Markdown

🤖 Codex Code Review

⚠️ Warning: Diff was truncated from 27592 to 10000 lines. Some changes were not reviewed.

No actionable findings. The split appears to preserve actor lifecycle, cancellation, message ordering, and supervision behavior. The updated experiment patch also applies cleanly.

Tests could not run: the pinned toolchain requires an update blocked by filesystem permissions, and the installed stable toolchain lacks the cached ctrlc dependency for offline builds.


Automated review by OpenAI Codex · gpt-6.1-sol · custom prompt

@github-actions

Copy link
Copy Markdown

🤖 DeepSeek Code Review

⚠️ Warning: Diff was truncated from 27592 to 10000 lines. Some changes were not reviewed.

This is a large mechanical split with a few issues worth addressing.

Critical issue: re-export visibility in concurrency/src/supervision.rs

Near the top of the file (the new module declarations), you have:

mod child;
pub use child::*;
mod state;
pub(crate) use state::*;
mod builder;
pub use builder::*;

The submodules define almost everything as pub(super) (visible only to the parent supervision module and its descendants). Examples from the diff:

  • child.rs: pub(super) struct RecoveryMeta, pub(super) struct View, pub(super) trait ChildControl, etc.
  • state.rs: pub(super) struct Core, pub(super) struct RetryBudget, etc.
  • builder.rs: pub(super) struct StartupGuard, pub(super) field core on SupervisorBuilder, etc.

Rust forbids re-exporting an item with a visibility broader than the item’s own visibility. pub use child::* tries to make those pub(super) items fully public, and pub(crate) use state::* tries to make them pub(crate) — both are broader than pub(super). This will not compile.

Fix: Change the re-exports to pub(super) use (or simply use) for child, state, and builder, or change the visibility of the items in those modules to pub/pub(crate) as appropriate. For example:

mod child;
pub(super) use child::*;
mod state;
pub(super) use state::*;
mod builder;
pub(super) use builder::*;

Keep in mind that SupervisedChild and SupervisorBuilder need to remain public for the API, so those structs and their public methods must be marked pub in their files, but you can leave internal items as pub(super).

benchmarks/experiments/backend-experiments.patch duplicates an existing change

The patch file includes a hunk that adds:

+#[cfg(all(test, feature = "backend-experiments"))]
+use lifecycle::MessageTurn;

to concurrency/src/tasks/actor.rs. However, the main PR diff already adds exactly those lines to that file. If someone runs the experiment preparation script (benchmarks/experiments/prepare.sh) which applies this patch on top of the current source, the context will not match (the lines are already present) and the patch will fail to apply.

Fix: Remove that hunk from the patch file, or adjust the patch workflow to expect the lines already present.

Potential logic mismatch in MessageTurn::after_message vs. its test

The partial diff of after_message shows a check like:

if self.completed >= self.limit {
    self.completed = 0;
    yield_now().await;
}
self.completed += 1;

If that is the actual order, then the test count_only_turn_never_starts_a_clock_and_yields_at_its_count (in concurrency/src/tasks/actor/turn_regressions.rs) would fail, because after three successful calls completed is 3, and on the fourth call the condition 3 >= 4 is false, so it would increment to 4 and return Ready instead of pending. The test expects the fourth poll to be Pending.

Recommendation: Verify the increment/check order in after_message. It should either increment before the limit check (self.completed += 1; if self.completed >= self.limit { ... }) or use > with a post-increment. Make sure the test and implementation agree.

Minor observations

  • MessageTurn::from_env reads environment variables every time it’s called (likely per actor spawn). For experiments this is acceptable, but consider caching the parsed values or documenting that env changes after startup are ignored.
  • The split itself is clean and appears to preserve behavior for default builds. The new modules are well-separated and maintainable.

Please address the visibility issue before merging; it is a compile blocker.


Automated review by DeepSeek · deepseek-v4-pro · custom prompt

@github-actions

Copy link
Copy Markdown

🤖 Kimi Code Review

⚠️ Warning: Diff was truncated from 27592 to 10000 lines. Some changes were not reviewed.

No blocking issues found in the shown diff. The supervision split preserves the public re-exports and effective visibility, and the locking, cancellation, and shutdown logic appears unchanged. The experimental run_actor parameter is also consistently propagated through the visible call sites.

Non-blocking suggestion: benchmarks/experiments/backend-experiments.patch now contains substantial code and tests—including MessageTurn and turn_regressions.rs—that are not compiled in the normal source tree. If not already covered elsewhere, add a CI check that applies the patch and runs the experimental tests, at least the turn_regressions tests with backend-experiments enabled. Otherwise patch-application failures or experimental regressions can go unnoticed.


Automated review by Kimi (Moonshot AI) · kimi-k3.1-pro · custom prompt

@github-actions

Copy link
Copy Markdown

🤖 Grok Code Review

⚠️ Warning: Diff was truncated from 27592 to 10000 lines. Some changes were not reviewed.

The supervision move is behavior-preserving on the concurrency paths I can check (same locks, cancellation, and shutdown order). The problems are name resolution after the split, and one visibility narrowing.

Broken relative paths in lifecycle.rs. The moved loop and spawn still call sibling modules as if they were children of actor.rs. The experiments patch context still shows both of these inside concurrency/src/tasks/actor/lifecycle.rs:

  • warn_on_block::WarnOnBlocking::new(...) (debug spawn path)
  • stop_receive_probe::before_receive() (receive gate)

warn_on_block and stop_receive_probe live under actor, not lifecycle. use super::* will not import those private modules. This fails under debug_assertions and under the stop-receive test cfg. Use super::warn_on_block and super::stop_receive_probe (same check for threads/actor/lifecycle.rs if that body was moved verbatim).

Test helpers are not in the parent scope. concurrency/src/tasks/actor.rs only does use lifecycle::run_actor (and MessageTurn behind the experiment cfg). turn_regressions.rs and the existing regression modules call test_context(...) via use super::*, and the new test also builds MessageEnvelope. use envelope::* does not pull in private/pub(super) envelope types. Import the test helpers explicitly, and make MessageEnvelope (and anything else those tests construct) pub(super):

#[cfg(test)]
use lifecycle::{run_actor, test_context};

RecoveryQueue is no longer pub(crate) at supervision::. It moved to private mod child (child.rs ~line 29) as pub(crate), but supervision.rs only does pub use child::* (public names only) and pub(crate) use state::*. Anything outside supervision that used supervision::RecoveryQueue no longer compiles, and child itself is private so the new path is not a substitute. Re-export it the same way as admit_in_window:

pub(crate) use child::RecoveryQueue;

Public API is now implicit. pub use child::* and pub use builder::* will pick up any future pub item in those files. The changelog says the API is unchanged; list the re-exports (SupervisedChild, SupervisorBuilder, Supervisor, SupervisorReport) so that stays true.

Batch yield placement at the end of the successful-dispatch arm is the right spot: the next iteration still hits the existing post-receive stop check, which is what stop_during_batch_yield_does_not_execute_the_next_queued_message is locking in. Default builds do not take that path. The mutants file list matches the new supervision modules.


Automated review by Grok (xAI) · grok-4.7 · custom prompt

@unbalancedparentheses
unbalancedparentheses added this pull request to the merge queue Nov 16, 2026
Merged via the queue into main with commit 8bbe1c7 Nov 16, 2026
45 of 46 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

no-model-change Modelled code changed without a model change; the PR body says why (Model: no change because ...)

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant