[capy] the Buffer nomenclature

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:

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.

Regards,
&rzej;
_______________________________________________
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/N3SLMUSCT6MUH7TG7L2REPVXTYATF5OF/