Actor as a pull-driven generator: one-turn protocol, close(), scheduler without global new

[kotbegemot]

Summary

The actor becomes a pull-driven generator: its message loop is a coroutine in a frame from the actor's memory resource, and resume() pulls one step of it, like next(). The turn — the right to call resume() — lives in the mailbox; the send() that unblocks a parked mailbox takes it (needs_sched). A suspended behavior keeps the turn (verdict resume), and the actor parks only once its frame is suspended. Results never wake anyone. docs/LIFECYCLE.md describes the model end to end.

Protocol and lifecycle

• detail/actor_protocol.hpp: one participant counter plus destroying; no CAS loops. The actor_state word, resume_impl and their helpers are gone.
• Contract violations stop the process instead of corrupting it:
  • in every build: resume() without a turn, after close(), or from inside a behavior; a second delete; a delete that cannot drain (bounded wait);
  • in debug builds only: two resume() calls at once, and an actor awaiting its own send().
• close() → unique_future<void>: a marker queued behind everything sent so far; idempotent. Once its future is ready, destroying the actor is safe while the scheduler runs.
• delete is a destroying operator delete; actor classes must be final. A suspended chain unwinds before ~Actor, and its callers get broken_pipe.
• A message lives as long as its behavior. dispatch() is [[nodiscard]] and passes a method's error code (co_return ec;) on to the caller instead of aborting.

Memory and scheduler

• sharing_scheduler(resource, threads, max_throughput): the job queue (a ring of job_ptr values) and the workers come from resource. Once warmed up, send → enqueue → resume does no global allocation.
• Any T&& method parameter is a compile error.
• Other fixes:
  • a promise nobody took a future from frees its state;
  • dropping a unique_future cancels a suspended producer;
  • try_complete_finalize() no longer leaks.

Removed

• ref_counted, intrusive_ptr, make_counted;
• unique_future::actor_promise;
• dead behavior_t members (is_awaited_ready() is merged into take_awaited_continuation());
• mailbox push_front, size, empty and message::prev;
• test/contended-resume, test/intrusive_ptr, tests_stress_intrusive_ptr, test/race-condition/TESTING.md.

Breaking changes

Migration guides are in CHANGELOG.md.

• The scheduler constructor takes a std::pmr::memory_resource* first.
• Actor classes must be final.
• No T&& method parameters.
• A contended or nested resume(), or one without a turn, is a contract violation. Before, it returned awaiting.

Test plan

• Debug ctest (clang, macOS): 170/170.
• Sanitizer matrix on the final dispatch() version: Release 171, ASan 170, TSan 169 + rt_tuple run alone, UBSan 170, exceptions ON 170.
• GCC 11.5 and GCC 13 in Docker: full ctest 170/170 each, 0 warnings. GCC 12 and Clang 14 (libstdc++ 12): smoke build and run.
• Relacy model (Docker gcc:13): 5/5, all four mutants caught.
• leaks --atExit: 0 across every test binary and balancer.
• Benchmarks: step 4 at 0.84–0.87 of the original; step 7 within noise.
• CI: Clang 16–18, and the full suite on GCC 12 and Clang 14.

Deferred, not in this PR:

• destroying an actor while its job sits in a running scheduler's queue — the actor cannot detect it; the rule is close() or stop() first;
• trimming the mailbox API to push_back/pop_front/park/close.

🤖 Generated with Claude Code