Skip to content

Module 08: Async Pipelines, Backpressure, and Fairness

Page Maps

graph LR
  family["Python Programming"]
  program["Python Functional Programming"]
  section["Async Pipelines Backpressure Fairness"]
  page["Module 08: Async Pipelines, Backpressure, and Fairness"]
  capstone["Capstone evidence"]

  family --> program --> section --> page
  page -.applies in.-> capstone
flowchart LR
  orient["Orient on the page map"] --> read["Read the main claim and examples"]
  read --> inspect["Inspect the related code, proof, or capstone surface"]
  inspect --> verify["Run or review the verification path"]
  verify --> apply["Apply the idea back to the module and capstone"]

Read the first diagram as a placement map: this page sits between the course promise, the lesson pages listed below, and the capstone surfaces that pressure-test the module. Read the second diagram as the study route for this page, so the diagrams point you toward the Lesson map, Exercises, and Closing criteria instead of acting like decoration.

Keep These Pages Open

Use these support surfaces while reading so async coordination stays reviewable and does not quietly become magical concurrency vocabulary:

Carry this question into the module:

Which async behavior is being coordinated explicitly, and where would hidden scheduling or buffering make the system harder to reason about?

This module treats async code as a coordination problem, not a style choice. You move from effect boundaries to bounded concurrency, fairness, and testable async plans that do not smear runtime behavior across the whole codebase.

Learning outcomes

  • distinguish a replayable AsyncPlan from a coroutine object and a running task;
  • trace how an AsyncGen pulls source values only when a consumer asks;
  • defend where FuncPipe introduces concurrency and where it deliberately stays synchronous;
  • prove that BackpressurePolicy limits in-flight embedding while preserving ordered Result values; and
  • keep retry and timeout policy local to each injected embedding plan; and
  • use injected clocks, sleepers, and adapters to test coordination without depending on wall-clock timing.

Begin with the application pressure

Read Module 08 Capstone Delta before the individual combinators. Module 07 can describe and interpret effects, but its RAG indexing path remains synchronous. Module 08 adds one application path, rag/async_rag.py, because embedding is the first stage with a useful independent concurrency boundary.

flowchart LR
  source["Async source<br/>Result[RawDoc]"]
  prepare["filter → clean → chunk<br/>synchronous and demand-driven"]
  embed["embedding plans<br/>bounded async work"]
  output["ordered<br/>Result[Chunk]"]

  source --> prepare --> embed --> output

The diagram is intentionally asymmetric. Cleaning and chunking remain the tested synchronous core. The module coordinates injected embedding plans; it does not convert every RAG function to async def.

Lesson map

Exercises

Use Module 08 Exercises after each core. Each prompt names a focused test in the Module 08 reference state and an earlier contract that must remain true. Consult Exercise Answers only after producing your own execution evidence. Finish with the cumulative indexing-policy lab: it requires you to explain filtering, three distinct failure positions, bounded overlap, and later-value continuity in one proof. The retry and deterministic testing exercises add a second review layer: whether repeating one effect is safe and whether a fake proves only the claim assigned to it.

Capstone checkpoints

  • Establish the Module 07-to-08 application pressure with Module 08 Capstone Delta before reading the combinators.
  • Inspect rag/async_rag.py beside domain/effects/async_/combinators.py.
  • Identify the exact boundary between synchronous document preparation and asynchronous embedding plans.
  • Run all seven async RAG application proofs:
make capstone-async-rag-proof
  • Isolate the three retry/timeout application proofs:
make capstone-embedding-resilience-proof
  • Compare the Module 07 and Module 08 reference states using the route in the Refactoring Guide.

Before moving on

You should be able to explain how async coordination stays reviewable, what protects embedding from runaway fan-out, and why a typed failure does not erase later valid work. You should also be able to show why retry repeats one chunk rather than the stream, and why a logical timeout test does not prove real cancellation. Use the Refactoring Guide and compare the generated Module 07 and Module 08 worktrees before moving forward.

Closing criteria

  • You can explain how concurrency stays bounded instead of accidental.
  • You can identify which async abstractions describe work and which consumer action actually drives execution.
  • You can defend an async design in terms of fairness, backpressure, and testability.
  • You can separate retry permission from the idempotency argument.
  • You can state the exact boundary of a timing fake.
  • You can state which synchronous RAG laws Module 08 preserves and point to the executable evidence.

Directory glossary

Use Glossary when you want the recurring language in this module kept stable while you move between lessons, exercises, and capstone checkpoints.