zacheryasc/swactor
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
swactor/CLAUDE/notes/constraints.md
Developer ef87f7e1b9 feat: per-actor message budget for tick fairness 
Research across ractor, tokio, Erlang/OTP BEAM, Linux CFS, and libuv
revealed that tick_all drained the entire mailbox per actor per tick,
allowing one hot actor to starve all others on the same worker.

- Add `actor_message_budget` to RuntimeConfig (default: 64 msgs/actor/tick)
- Modify tick_all to break after budget messages, yielding to next actor
- budget=0 restores unlimited (backward compatible) behavior
- 3 new fairness tests validating hot-cold actor scenarios
- New fairness benchmark group (cold_latency_under_pressure, throughput_by_budget)
- Fix RuntimeConfig struct literals across workspace crates

Inspired by BEAM's 4000-reduction budget and tokio's 128-op cooperative budget.
All 45 tests pass (42 original + 3 new).

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-02-12 11:11:30 +00:00

1.4 KiB
Raw Blame History

Task Constraints (from user)

Scope of Study

  • Broad survey: Not just Rust actor frameworks — include:
    • Rust: ractor, actix, kameo, coerce, stakker, xactor, bastion
    • Non-actor runtimes: tokio, C++ node/libuv event loop
    • OS-level: process scheduling/logic in operating systems
    • Classic actor systems: Erlang/OTP, Akka/Pekko (JVM)
    • Any widely-used, well-reputed system

Priority & Approach

  • Interleaved: Pick a topic → analyze competitors → benchmark swactor → improve → repeat
  • Also improve testing methodology and coverage based on analysis
  • Look at bug report histories of competitor projects for insights
  • Behavioral tests only (Given/When/Then), no white-box/structural tests

Code Structure Rules

  • src/ is frozen: No new files, no new modules, no structural changes. Only modify existing files in-place.
  • No new dependencies on the root crate (swactor's Cargo.toml)
  • May add new crates to crates/ but they must NOT be pulled into src/
  • Cap at ~5 new crates — if approaching that, prune back
  • Integration tests in tests/, benchmarks in benches/
  • Benchmark execution capped at 2 minutes max
  • All notes go in CLAUDE/notes/
  • Report architecture changes in docs/

Commit Rules

  • All cargo test must pass (including feature-gated)
  • Never skip/delete tests for active code
  • If a fix takes >3 attempts, log and move on