Why Concepts, Not Spans

This section explains why Capy uses concept-driven buffer sequences instead of std::span, and why this design enables composition without allocation.

Prerequisites

  • Basic C++ experience with memory and pointers

  • Familiarity with C++20 concepts

The I/O Use Case

Buffers exist to interface with operating system I/O. When you read from a socket, write to a file, or transfer data through any I/O channel, you work with contiguous memory regions—addresses and byte counts.

The fundamental unit is a (pointer, size) pair. The OS reads bytes from or writes bytes to linear addresses.

The Reflexive Answer: span

The instinctive C++ answer to "how should I represent a buffer?" is std::span<std::byte>:

void write_data(std::span<std::byte const> data);
void read_data(std::span<std::byte> buffer);

This works for single contiguous buffers. But I/O often involves multiple buffers—a technique called scatter/gather I/O.

Scatter/Gather I/O

Consider assembling an HTTP message. The headers are in one buffer; the body is in another. With single-buffer APIs, you must:

  1. Allocate a new buffer large enough for both

  2. Copy headers into the new buffer

  3. Copy body after headers

  4. Send the combined buffer

This is wasteful. The data already exists—why copy it?

Scatter/gather I/O solves this. Operating systems provide vectored I/O calls (writev on POSIX, scatter/gather with IOCP on Windows) that accept multiple buffers and transfer them as a single logical operation.

The Span Reflex for Multiple Buffers

Extending the span reflex: std::span<std::span<std::byte>>:

void write_data(std::span<std::span<std::byte const> const> buffers);

This works, but introduces a composition problem.

The Composition Problem

Suppose you have:

using HeaderBuffers = std::array<std::span<std::byte const>, 2>;  // 2 buffers
using BodyBuffers = std::array<std::span<std::byte const>, 3>;    // 3 buffers

To send headers followed by body, you need 5 buffers total. With span<span<byte>>:

HeaderBuffers headers = /* ... */;
BodyBuffers body = /* ... */;

// To combine, you MUST allocate a new array:
std::array<std::span<std::byte const>, 5> combined;
std::copy(headers.begin(), headers.end(), combined.begin());
std::copy(body.begin(), body.end(), combined.begin() + 2);

write_data(combined);

Every composition allocates. This leads to:

  • Overload proliferation—separate functions for single buffer, multiple buffers, common cases

  • Performance overhead—allocation on every composition

  • Boilerplate—manual copying everywhere

The Concept-Driven Alternative

Instead of concrete types, use concepts. Define ConstBufferSequence as "any type that can produce a sequence of buffers":

template<ConstBufferSequence Buffers>
void write_data(Buffers const& buffers);

This single signature accepts:

  • A single const_buffer

  • A span<const_buffer>

  • A vector<const_buffer>

  • A string_view (converts to single buffer)

  • A custom composite type

  • Any composition of the above—without allocation

Zero-Allocation Composition

With concepts, composition creates views, not copies:

HeaderBuffers headers = /* ... */;
BodyBuffers body = /* ... */;

// cat() creates a view that iterates both sequences
auto combined = cat(headers, body);  // No allocation!

write_data(combined);  // Works because combined satisfies ConstBufferSequence

The cat function returns a lightweight object that, when iterated, first yields buffers from headers, then from body. The buffers themselves are not copied—only iterators are composed.

STL Parallel

This design follows Stepanov’s insight from the STL: algorithms parameterized on concepts (iterators), not concrete types (containers), enable composition that concrete types forbid.

The span reflex is a regression from thirty years of generic programming. Concepts restore the compositional power that concrete types lack.

The Middle Ground

Concepts provide flexibility at user-facing APIs. But at type-erasure boundaries—virtual functions, library boundaries—concrete types are necessary.

Capy’s approach:

  • User-facing APIs — Accept concepts for maximum flexibility

  • Type-erasure boundaries — Use concrete spans internally

  • Library handles conversion — Users get concepts; implementation uses spans

This gives users the composition benefits of concepts while hiding the concrete types needed for virtual dispatch.

Why Not std::byte?

Even std::byte imposes a semantic opinion. POSIX uses void* for semantic neutrality—"raw memory, I move bytes without opining on contents."

But span<void> doesn’t compile—C++ can’t express type-agnostic buffer abstraction with span.

Capy provides const_buffer and mutable_buffer as semantically neutral buffer types. They have known layout compatible with OS structures (iovec, WSABUF) without imposing std::byte semantics.

Summary

The reflexive span<span<byte>> approach:

  • Forces allocation on every composition

  • Leads to overload proliferation

  • Loses the compositional power of generic programming

The concept-driven approach:

  • Enables zero-allocation composition

  • Provides a single signature that accepts anything buffer-like

  • Follows proven STL design principles

Continue to Buffer Types to learn about const_buffer and mutable_buffer.

Edit this Page