Design

Capy’s public interface—​tasks, buffers, streams—​is intentionally small. Behind that interface are design decisions that determine how concepts compose, where responsibility boundaries fall, and what guarantees the library can make. This section documents those decisions.

Each page in this section examines one concept or facility in depth. You will find the formal concept definition, the rationale for its design, the alternatives that were considered, and the tradeoffs that were made. If you have ever wondered why ReadStream requires read_some instead of read, or why buffer sinks and sources exist as separate concepts from streams, the answers are here.

What You Will Find

  • ReadStream — The partial-read concept. Why read_some is the correct primitive, how it composes with algorithms, and its relationship to ReadSource.

  • ReadSource — The complete-read concept. Guaranteed delivery semantics, EOF handling, and the contract between sources and consumers.

  • BufferSource — Pairing complete reads with dynamic buffers. How protocol parsers use BufferSource to accumulate data incrementally.

  • WriteStream — The partial-write concept. Symmetric design with ReadStream, and how write algorithms handle short writes.

  • WriteSink — The complete-write concept. Guaranteed delivery for outbound data, and the composition with serialization layers.

  • BufferSink — Dynamic buffer output. How message builders and serializers produce output without knowing the transport.

  • Run API — The entry points for executing coroutines: run, run_async, and the bridge between synchronous and asynchronous worlds.

  • Type-Erasing Awaitables — Erasing the concrete type of an awaitable behind a uniform interface. When type erasure is worth the cost, and how Capy implements it.

  • AnyBufferSink — A type-erased buffer sink. Combining the BufferSink concept with type erasure for runtime polymorphism.

  • Executor — The executor concept. Why dispatch returns void, why defer was dropped, how executor_ref achieves zero-allocation type erasure, and the I/O completion pattern that motivates the design.

These documents are reference material for library contributors and advanced users. They assume familiarity with the tutorial sections and focus on design reasoning rather than usage.

Edit this Page