The way buffers are introduced, motivated and specified in Capy is above average for C++ libraries, but they still require a more precise and accurate description.
One. It looks like the contract is: user manages the lifetime of the memory chuncks that represent the read/written bytes; the library manages the lifetime of handles to buffers and buffer handle sequences. This should be spelled out. We probably need to introduce and socialize the notion of a buffer handle.
Two. It is not clear what the intended balance between type-safety and convenience is.
-
The docs (https://develop.capy.cpp.al/capy/5.buffers/5a.overview.html) claim that std::string_view models a ConstBufferSequence (that alegedly "string_view converts to single buffer" but when tested ConstBufferSequence<string_view>isfalse`. This is clearly a bug, but it is not clear which way it should be fixed.
-
const_buffer models ConstBufferSequence. This is like saying that every type T can be interpretted and used a single-element sequence of Ts. This position could be defended under the view that "we favour convenience", but in that case this convenience shoud be stated as the one of primary design goals and applied consistently to other trade-offs.
Three. The choice to use void* as the pointer type need to be accompanied by a clearer rationale. While the page clearly describes why span<span<byte>> is a bad choice for representing sequences of buffers, the motivation for not using span<byte> for buffers is too weak. My guess is that the motivation is:
- Because the concrete types provided by platforms (such as
iovec) use void* anyway
- Because we want the user to be able to provide arrays of
char, unsigned char, byte, and they all need to be erased to the one common type.
The way buffers are introduced, motivated and specified in Capy is above average for C++ libraries, but they still require a more precise and accurate description.
One. It looks like the contract is: user manages the lifetime of the memory chuncks that represent the read/written bytes; the library manages the lifetime of handles to buffers and buffer handle sequences. This should be spelled out. We probably need to introduce and socialize the notion of a buffer handle.
Two. It is not clear what the intended balance between type-safety and convenience is.
The docs (https://develop.capy.cpp.al/capy/5.buffers/5a.overview.html) claim that
std::string_viewmodels aConstBufferSequence(that alegedly "string_viewconverts to single buffer" but when tested ConstBufferSequence<string_view>isfalse`. This is clearly a bug, but it is not clear which way it should be fixed.const_buffermodelsConstBufferSequence. This is like saying that every typeTcan be interpretted and used a single-element sequence ofTs. This position could be defended under the view that "we favour convenience", but in that case this convenience shoud be stated as the one of primary design goals and applied consistently to other trade-offs.Three. The choice to use
void*as the pointer type need to be accompanied by a clearer rationale. While the page clearly describes whyspan<span<byte>>is a bad choice for representing sequences of buffers, the motivation for not usingspan<byte>for buffers is too weak. My guess is that the motivation is:iovec) usevoid*anywaychar,unsigned char,byte, and they all need to be erased to the one common type.