Skip to content

docs: add the design notes page for the parallel execution layer - #69

Merged
wenh06 merged 1 commit into
masterfrom
docs-design-page
Nov 4, 2026
Merged

wenh06 merged 1 commit into
masterfrom
docs-design-page

Conversation

@wenh06

@wenh06 wenh06 commented Nov 4, 2026

Copy link
Copy Markdown
Owner

Summary

Distill the parallel-execution design document from the maintainer's scratch area into a finalized documentation page (docs/source/parallel_execution_design.rst) — no intermediate revision or review history, describing the shipped system:

  • requirements and the three schools of prior work;
  • the two state-ownership invariants (I1 client-task enclosure, I2 server single-threadedness) and the arithmetic-equivalence corollary;
  • the executor abstraction (in-order map, main-thread completion callbacks, fail-fast, context-manager resource handling) and why map-instead-of-futures;
  • the per-round task decomposition, including the independence of uplink skipping from downlink broadcast and from training/evaluation;
  • the backend table with measured speedups;
  • the reproducibility ladder (L0 / L1 per-client generators / L2 rejected) and the configuration surface;
  • implementation notes (named model_state exchange, the APFL fix found by the bitwise migration harness, the L1 loader-rebuild choice, the legacy-hook shim) and the outlook for the processes and ray backends.

Wired into the Advanced Topics toctree and cross-linked from parallel_execution.rst. zh_CN translation included.

Note: this PR is based on master before #68; the two zh build warnings on the theory pages are fixed there and are unrelated to this change.

Validation

Distilled from the design document in the repository scratch area into
a finalized page (no intermediate revision or review history):

- requirements and the three schools of prior work;
- the two state-ownership invariants (client-task enclosure, server
  single-threadedness) and the arithmetic-equivalence corollary;
- the executor abstraction (in-order map, main-thread completion
  callbacks, fail-fast, context-manager resource handling) and why
  map-instead-of-futures;
- the per-round task decomposition, including the independence of
  uplink skipping from downlink broadcast and from training/evaluation;
- the backend table (sequential / threads / processes / ray) with
  measured speedups;
- the reproducibility ladder (L0 default, L1 per-client generators,
  L2 rejected) and the configuration surface;
- implementation notes (named model_state exchange, the APFL fix found
  by the bitwise migration harness, the L1 loader-rebuild choice, the
  legacy-hook shim) and the outlook for the processes and ray backends.

Wired into the Advanced Topics toctree and cross-linked from
parallel_execution.rst; zh_CN translation included.
@wenh06
wenh06 merged commit f561a20 into master Nov 4, 2026
28 checks passed
@wenh06
wenh06 deleted the docs-design-page branch November 4, 2026 17:53
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant