Buffer Sequences

Every I/O operation ultimately comes down to moving bytes between your program and the outside world—​a socket, a file, a pipe. The question is: how do you describe where those bytes live in memory?

The obvious answer is a pointer and a size. And for a single contiguous buffer, that works. But real I/O is rarely that tidy. An HTTP response has headers in one buffer and a body in another. A message might be assembled from a protocol header, a payload, and a checksum—​each produced by different parts of your code, each sitting in its own memory. The operating system even supports scatter/gather I/O specifically to handle this: a single system call that reads into or writes from multiple non-contiguous buffers.

Capy’s buffer model is designed for this reality. Instead of forcing you to copy data into a single contiguous allocation, Capy uses buffer sequences--lightweight, zero-copy abstractions that let you describe any arrangement of memory and pass it directly to the OS. The design is concept-driven, meaning the compiler verifies correctness at compile time with no runtime overhead.

This section covers everything you need to work with memory in Capy’s I/O model. You will learn the fundamental buffer types, how to compose them into sequences for scatter/gather I/O, and how they map to operating system primitives. You will also meet the algorithms that manipulate buffer data and the dynamic buffer abstractions that grow as data arrives. Understanding buffers is essential for everything that follows—​streams, I/O operations, and protocol implementations all build on the abstractions introduced here.