Skip to content

docs(design): evaluate Actor pattern for Generator/Sender/Receiver (#2136)#4210

Merged
oferchen merged 1 commit into
masterfrom
docs/actor-pattern-generator-sender-receiver-2136
May 17, 2026
Merged

docs(design): evaluate Actor pattern for Generator/Sender/Receiver (#2136)#4210
oferchen merged 1 commit into
masterfrom
docs/actor-pattern-generator-sender-receiver-2136

Conversation

@oferchen
Copy link
Copy Markdown
Owner

Summary

  • Reframes docs/design/actor-pattern-generator-sender-receiver.md around the post-async-migration target: supervised tokio tasks with bounded mailboxes and a supervisor that restarts crashed actors (Erlang / Akka style).
  • Maps today's blocking topology (Generator, Sender, Receiver as OS threads connected by lock-free SPSC) onto the proposed actor sketch and weighs the tradeoffs.
  • Recommendation: reject for the production hot path; adopt for multi-host fan-out and fault-injection tests only, behind --features async-pipeline.

The load-bearing objection is that rsync's wire protocol is sequential and has no resume primitive: restarting a Generator mid-transfer cannot reconstruct the file-list cursor, NDX window, phase toggle, multiplex frame state, or partial varint, so the supervisor's defining feature is a no-op. The other axes (mailbox backpressure, observability, fault injection, multi-host fan-out) are real wins but are addressable behind a feature flag without reshaping the production transfer loop.

Cross-references #4186 async migration plan, #4196 spawn_blocking bridge, #2134 type-state for protocol phases (recently merged), #1935 async daemon listener impl. Aligns with the bounded type-state recommendation #2134 settled on, and slots into phase 4.5 / phase 5 of the migration plan.

Closes #2136.

Test plan

  • CI fmt + clippy passes (docs-only change).
  • Confirm referenced docs exist: docs/design/async-migration-plan.md, docs/design/spawn-blocking-bridge.md, docs/design/async-channel-abstraction.md, docs/design/type-state-protocol-phases.md, docs/architecture/parallelization.md, docs/audits/async-ssh-transport.md, docs/audits/tokio-dependency-boundary-2026.md, docs/plans/2026-03-28-parallel-chunks-design.md.
  • Confirm file:line citations resolve: crates/transfer/src/generator/transfer.rs:731, crates/transfer/src/receiver/transfer.rs:55,519,680, crates/transfer/src/disk_commit/thread.rs:47,172, crates/transfer/src/pipeline/spsc.rs, crates/engine/src/concurrent_delta/work_queue/bounded.rs:88-104.

…2136)

Reframe the actor-pattern evaluation around supervised tokio tasks
(Erlang/Akka style with bounded mailboxes and a supervisor that
restarts crashed actors) to match the post-async-migration target
the migration plan commits us to.

The recommendation stays: reject the actor reshape for the
production hot path because rsync's wire protocol is sequential
with no resume primitive, so supervisor restart is a no-op; adopt
the actor surface only for multi-host fan-out and fault-injection
tests, behind --features async-pipeline.

Cross-references #4186 (async migration plan), #4196 (spawn_blocking
bridge), #2134 (type-state for protocol phases, recently merged),
and #1935 (async daemon listener).
@github-actions github-actions Bot added the documentation Improvements or additions to documentation label May 17, 2026
@oferchen oferchen merged commit 264a2c1 into master May 17, 2026
8 checks passed
@oferchen oferchen deleted the docs/actor-pattern-generator-sender-receiver-2136 branch May 17, 2026 18:51
oferchen added a commit that referenced this pull request May 18, 2026
…2136) (#4210)

Reframe the actor-pattern evaluation around supervised tokio tasks
(Erlang/Akka style with bounded mailboxes and a supervisor that
restarts crashed actors) to match the post-async-migration target
the migration plan commits us to.

The recommendation stays: reject the actor reshape for the
production hot path because rsync's wire protocol is sequential
with no resume primitive, so supervisor restart is a no-op; adopt
the actor surface only for multi-host fan-out and fault-injection
tests, behind --features async-pipeline.

Cross-references #4186 (async migration plan), #4196 (spawn_blocking
bridge), #2134 (type-state for protocol phases, recently merged),
and #1935 (async daemon listener).
oferchen added a commit that referenced this pull request May 18, 2026
…2136) (#4210)

Reframe the actor-pattern evaluation around supervised tokio tasks
(Erlang/Akka style with bounded mailboxes and a supervisor that
restarts crashed actors) to match the post-async-migration target
the migration plan commits us to.

The recommendation stays: reject the actor reshape for the
production hot path because rsync's wire protocol is sequential
with no resume primitive, so supervisor restart is a no-op; adopt
the actor surface only for multi-host fan-out and fault-injection
tests, behind --features async-pipeline.

Cross-references #4186 (async migration plan), #4196 (spawn_blocking
bridge), #2134 (type-state for protocol phases, recently merged),
and #1935 (async daemon listener).
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant