On Sun, Jun 21, 2026 at 9:36 PM Andrzej Krzemienski via Boost < boost@lists.boost.org> wrote:
Hi All, The Capy+Corosio review has not yet started but, as Jeff pointed out, two weeks will likely not be enough, so I might as well post right now.
Disclosure: I am affiliated with the C++ Alliance, and have been contributing to Capy.
This post is to share a reflection on the naming around buffers present in Capy. Capy inherited the names from ASIO, and ASIO was strongly influenced by the naming in the operating systems. So this observation applies not only to Capy.
Philosophically, a buffer is a solution to the problem of producer producing and consumer consuming data at different paces. This is done via buffering and for this we use a "buffer", that is, some memory, not necessarily contiguous.
We have the following elements.
1. A contiguous region of memory whose lifetime is managed by the programmer. 2. We have a view-like handle providing access to this region of memory. 3. When a read or write operation needs access to space for buffering, it is given a "structure" of handles that together give access to all of the memory available for buffering. 4. A "dynamic" storage, which can be reallocated if needed, where some storage is devoted to a buffer for reading and another for a buffer for writing.
In Capy, #1 doesn't have a name, #2 is called const_buffer/mutable_buffer, and #3 is called ConstBufferSequence, MutableBufferSequence, Where a "buffer sequence" is either a buffer or a range of buffers. #4 is called DynamicBuffer.
This naming has been very confusing to me, and the library design only started to make sense for me, when I mentally used a different naming:
#1 doesn't need a name #2 read_region/write_region #3 ReadBufferView/WriteBufferView #4 DynamicStorage
The read/write vs const/mutable is secondary, but the regions and buffer views make a lot of things clearer:
All the OS apis (e.g. winapi ReadFile/WriteFile or posix' read/write) use a derivative of `buffer` as the name for the argument in their documentation, e.g.: ssize_t write(int *fildes*, const void **buf*, size_t *nbyte*); I think anything other than buffer would be confusing for people familiar with these APIs. Since `const` is encoded in the type here, it doesn't need to be named `cbuf`. I guess it could be a `readonly_buffer`, but since`const` means exactly that in C++ I think `const_buffer` is preferrable. The name for vectorized IO is either `buffers` (windows) or `iovec`, which would be short for `io vector`. The second of course makes sense , because it's a dynamic array. I think `view` is not correct, since I can pass the thing by value. E.g.: write(s, std::array<const_buffer, 2u>{ make_buffer("Hello"), make_buffer("World") }); Regarding the `sequence`, I think it's a pretty good name. It expresses something like `range<T>` with the slight distinction that `T` is also valid. That is: a sequence of T is either T or a range of T. An alternative name could be found (like series) but then we might as well stick to the asio one. Algorithm `write` needs a buffer: somewhere to write bytes to: it can be a
contiguous memory region or a sequence thereof. The buffer is all the memory the operation has at its disposal.
We avoid this recursive notion that a buffer is a buffer sequence. Names read more naturally:
template <ReadStream S, ReadBufferView B> auto read(S& stream, B buffer) { size_t size = capy::buffer_size(buffer); // ... }
template <ReadStream S, DynamicStorageParam Store> auto read(S& stream, Store&& storage) { ReadBufferView buffer = storage.prepare(1024); // ... }
If the goal of not confusing current ASIO users is more important than not confusing new users, then the current names had better stay, but the above description in the documentation might help new users to grasp the concepts. If, on the other hand, the library is prioritizing new users, maybe we could consider changing the nomenclature.
Prioritizing new users will depend on what these new users already know. If they're familiar with the posix or winapi nomenclature, I think they'll be just fine.