Stream Concepts

Data flows. It arrives from a network socket in unpredictable chunks. It leaves through a file descriptor as fast as the disk allows. It passes through encryption, compression, and framing layers—​each transforming it before handing it off to the next. Modeling this flow well is one of the most important things an I/O library can do.

Capy organizes data flow around six concepts, arranged in three complementary pairs. The design reflects a truth about I/O that most libraries gloss over: partial operations and complete operations are fundamentally different things, and conflating them leads to bugs.

A socket might give you 47 bytes when you asked for 1024. That is not an error—​it is the nature of the hardware. Some code needs to handle those 47 bytes immediately and ask for more. Other code needs exactly 1024 bytes and should not return until it has them (or an error occurs). These are different operations with different contracts, and Capy gives them different names: streams for partial I/O, and sources and sinks for complete I/O.

On top of this, Capy adds buffer sources and buffer sinks--concepts that work with dynamic buffers, enabling protocol parsers and message builders to grow their storage as needed without manual bookkeeping.

This section introduces the concepts that form Capy’s vocabulary for data flow. You will learn the distinction between partial and complete I/O, how the concept pairs relate to each other, and how transfer algorithms and physical isolation let you write I/O logic that is composable, testable, and independent of any particular transport. Once you understand these concepts, every I/O operation in the library will feel familiar.