Re: [capy] the Buffer nomenclature

On Sun, Jun 21, 2026 at 9:36 PM Andrzej Krzemienski via Boost <
[email protected]> 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.
_______________________________________________
Boost mailing list -- [email protected]
To unsubscribe send an email to [email protected]
https://lists.boost.org/mailman3/lists/boost.lists.boost.org/
Archived at: https://lists.boost.org/archives/list/[email protected]/message/C57HA7XU76FMGW6T57GHFFRTPFAL7HRX/