refactor!: make buffer_param an implementation detail

doc/.vale/styles/config/vocabularies/Corosio/accept.txt

@@ -189,7 +189,7 @@
 # pages that named an English/technical term rather than a documented entity. Names
 # that DO have a generated reference page are deliberately absent -- they are B1
 # defects and must keep alerting until they become `cpp:` links (io_stream,
-# signal_set, buffer_param, worker_base and friends).
+# signal_set, worker_base and friends).
 (?i)hostnames?
 (?i)loopback
 (?i)multicast
@@ -255,8 +255,6 @@
 (?i)results
 (?i)const_buffer
 (?i)mutable_buffer
-(?i)buffer_slice
-(?i)consuming_buffers
 (?i)execution_context
 (?i)any_executor
 (?i)stop_tokens?

doc/modules/ROOT/pages/4.guide/4g.composed-operations.adoc

@@ -83,30 +83,6 @@ include::example$snippets/4g_composed_operations.cpp[tag=write_full,indent=0]
 2. If an error occurs, returns immediately with bytes written so far
 3. On success, returns total bytes (equals `buffer_size(buffers)`)
 
-== buffer_slice Helper
-
-Both `read()` and `write()` use `capy::consuming_buffers` internally to
-track progress through a buffer sequence. A related helper,
-`capy::buffer_slice`, returns a view over a byte range of the underlying
-sequence. The result is itself a buffer sequence covering only that
-range, so it can be passed directly to any I/O operation:
-
-[source,cpp]
-----
-include::example$snippets/4g_composed_operations.cpp[tag=slice_helper,indent=0]
-----
-
-The returned `slice_type` models the same buffer-sequence concept as
-`seq`, and is mutable when `seq` is a mutable buffer sequence. Slicing a
-single buffer yields an adjusted buffer of the same kind. Any other
-sequence yields a borrowed view. `offset` is clamped to the total
-size, and `length` defaults to the end of the sequence.
-
-NOTE: Except for the single-buffer case, the result borrows `seq`: it
-stores iterators into the sequence, not a copy, so `seq` must outlive
-it. Passing a temporary buffer sequence is rejected at compile time;
-hoist it into a named variable first.
-
 == Error Handling Patterns
 
 === Structured Bindings with EOF Check

doc/modules/ROOT/pages/4.guide/4n.buffers.adoc

@@ -107,51 +107,6 @@ Get the total size of a buffer sequence:
 include::example$snippets/4n_buffers.cpp[tag=buffer_size,indent=0]
 ----
 
-== buffer_slice
-
-`capy::buffer_slice` returns a byte sub-range of a buffer sequence, as a
-value. The result is itself a buffer sequence, so it can be passed directly
-to any I/O operation:
-
-[source,cpp]
-----
-include::example$snippets/4n_buffers.cpp[tag=buffer_slice_include]
-include::example$snippets/4n_buffers.cpp[tag=buffer_slice,indent=0]
-----
-
-Except for the single-buffer case, the result borrows the underlying
-sequence, which must outlive the slice.
-
-== consuming_buffers
-
-When transferring data incrementally, `capy::consuming_buffers` is a cursor
-that tracks progress through a sequence. It exposes the bytes not yet
-transferred via `data()` and advances past completed bytes with
-`consume(n)`:
-
-[source,cpp]
-----
-include::example$snippets/4n_buffers.cpp[tag=consuming_buffers_include]
-include::example$snippets/4n_buffers.cpp[tag=consuming_buffers,indent=0]
-----
-
-This is used internally by `read()` and `write()` but can be used directly.
-The underlying sequence must outlive the cursor and any view obtained from
-its `data()`.
-
-== buffer_param
-
-The cpp:buffer_param[] class type-erases buffer sequences:
-
-[source,cpp]
-----
-include::example$snippets/4n_buffers.cpp[tag=buffer_param_include]
-include::example$snippets/4n_buffers.cpp[tag=buffer_param]
-include::example$snippets/4n_buffers.cpp[tag=buffer_param_call,indent=0]
-----
-
-This enables non-templated code to work with any buffer type.
-
 == Memory Safety
 
 === Lifetime

doc/modules/ROOT/pages/glossary.adoc

@@ -26,10 +26,6 @@ Affinity::
 The binding of a coroutine to a specific executor. A coroutine with affinity
 to executor `ex` has all its resumptions dispatched through `ex`.
 
-buffer_param::
-A type-erased buffer sequence parameter, allowing non-template code to
-work with any buffer type.
-
 any_executor::
 A type-erased wrapper for executors, enabling runtime polymorphism for
 executor types. See `capy::any_executor`.

include/boost/corosio/detail/buffer_param.hpp

@@ -16,7 +16,7 @@
 
 #include <cstddef>
 
-namespace boost::corosio {
+namespace boost::corosio::detail {
 
 /** Erases a buffer sequence to the pointer and length a system call takes.
 
@@ -362,8 +362,8 @@ class buffer_param
     copy_impl(void const* p, capy::mutable_buffer* dest, std::size_t n)
     {
         auto const& bs    = *static_cast<BS const*>(p);
-        auto it           = capy::begin(bs);
-        auto const end_it = capy::end(bs);
+        auto it           = capy::buffer_sequence_begin(bs);
+        auto const end_it = capy::buffer_sequence_end(bs);
 
         std::size_t i = 0;
         if constexpr (capy::MutableBufferSequence<BS>)
@@ -398,6 +398,6 @@ class buffer_param
     fn_t fn_;
 };
 
-} // namespace boost::corosio
+} // namespace boost::corosio::detail
 
 #endif

include/boost/corosio/io/io_read_stream.hpp

@@ -90,7 +90,7 @@ class BOOST_COROSIO_DECL io_read_stream : virtual public io_object
     virtual std::coroutine_handle<> do_read_some(
         capy::continuation& cont,
         capy::executor_ref ex,
-        buffer_param buffers,
+        detail::buffer_param buffers,
         std::stop_token token,
         std::error_code* ec,
         std::size_t* bytes) = 0;

include/boost/corosio/io/io_stream.hpp

@@ -87,7 +87,7 @@ class BOOST_COROSIO_DECL io_stream
         virtual std::coroutine_handle<> read_some(
             capy::continuation& cont,
             capy::executor_ref ex,
-            buffer_param buffers,
+            detail::buffer_param buffers,
             std::stop_token token,
             std::error_code* ec,
             std::size_t* bytes) = 0;
@@ -107,7 +107,7 @@ class BOOST_COROSIO_DECL io_stream
         virtual std::coroutine_handle<> write_some(
             capy::continuation& cont,
             capy::executor_ref ex,
-            buffer_param buffers,
+            detail::buffer_param buffers,
             std::stop_token token,
             std::error_code* ec,
             std::size_t* bytes) = 0;
@@ -135,7 +135,7 @@ class BOOST_COROSIO_DECL io_stream
     std::coroutine_handle<> do_read_some(
         capy::continuation& cont,
         capy::executor_ref ex,
-        buffer_param buffers,
+        detail::buffer_param buffers,
         std::stop_token token,
         std::error_code* ec,
         std::size_t* bytes) override
@@ -158,7 +158,7 @@ class BOOST_COROSIO_DECL io_stream
     std::coroutine_handle<> do_write_some(
         capy::continuation& cont,
         capy::executor_ref ex,
-        buffer_param buffers,
+        detail::buffer_param buffers,
         std::stop_token token,
         std::error_code* ec,
         std::size_t* bytes) override

include/boost/corosio/io/io_write_stream.hpp

@@ -89,7 +89,7 @@ class BOOST_COROSIO_DECL io_write_stream : virtual public io_object
     virtual std::coroutine_handle<> do_write_some(
         capy::continuation& cont,
         capy::executor_ref ex,
-        buffer_param buffers,
+        detail::buffer_param buffers,
         std::stop_token token,
         std::error_code* ec,
         std::size_t* bytes) = 0;

include/boost/corosio/local_datagram_socket.hpp

@@ -116,7 +116,7 @@ class BOOST_COROSIO_DECL local_datagram_socket : public io_object
         virtual std::coroutine_handle<> send_to(
             capy::continuation& cont,
             capy::executor_ref ex,
-            buffer_param buf,
+            detail::buffer_param buf,
             corosio::local_endpoint dest,
             int flags,
             std::stop_token token,
@@ -140,7 +140,7 @@ class BOOST_COROSIO_DECL local_datagram_socket : public io_object
         virtual std::coroutine_handle<> recv_from(
             capy::continuation& cont,
             capy::executor_ref ex,
-            buffer_param buf,
+            detail::buffer_param buf,
             corosio::local_endpoint* source,
             int flags,
             std::stop_token token,
@@ -181,7 +181,7 @@ class BOOST_COROSIO_DECL local_datagram_socket : public io_object
         virtual std::coroutine_handle<> send(
             capy::continuation& cont,
             capy::executor_ref ex,
-            buffer_param buf,
+            detail::buffer_param buf,
             int flags,
             std::stop_token token,
             std::error_code* ec,
@@ -203,7 +203,7 @@ class BOOST_COROSIO_DECL local_datagram_socket : public io_object
         virtual std::coroutine_handle<> recv(
             capy::continuation& cont,
             capy::executor_ref ex,
-            buffer_param buf,
+            detail::buffer_param buf,
             int flags,
             std::stop_token token,
             std::error_code* ec,
@@ -324,7 +324,7 @@ class BOOST_COROSIO_DECL local_datagram_socket : public io_object
 
         send_to_awaitable(
             local_datagram_socket& s,
-            buffer_param buf,
+            detail::buffer_param buf,
             corosio::local_endpoint dest,
             int flags = 0) noexcept
             : s_(s)
@@ -337,7 +337,7 @@ class BOOST_COROSIO_DECL local_datagram_socket : public io_object
         friend detail::bytes_op_base<send_to_awaitable>;
 
         local_datagram_socket& s_;
-        buffer_param buf_;
+        detail::buffer_param buf_;
         corosio::local_endpoint dest_;
         int flags_;
 
@@ -361,7 +361,7 @@ class BOOST_COROSIO_DECL local_datagram_socket : public io_object
 
         recv_from_awaitable(
             local_datagram_socket& s,
-            buffer_param buf,
+            detail::buffer_param buf,
             corosio::local_endpoint& source,
             int flags = 0) noexcept
             : s_(s)
@@ -374,7 +374,7 @@ class BOOST_COROSIO_DECL local_datagram_socket : public io_object
         friend detail::bytes_op_base<recv_from_awaitable>;
 
         local_datagram_socket& s_;
-        buffer_param buf_;
+        detail::buffer_param buf_;
         corosio::local_endpoint& source_;
         int flags_;
 
@@ -450,7 +450,9 @@ class BOOST_COROSIO_DECL local_datagram_socket : public io_object
         friend local_datagram_socket;
 
         send_awaitable(
-            local_datagram_socket& s, buffer_param buf, int flags = 0) noexcept
+            local_datagram_socket& s,
+            detail::buffer_param buf,
+            int flags = 0) noexcept
             : s_(s)
             , buf_(buf)
             , flags_(flags)
@@ -460,7 +462,7 @@ class BOOST_COROSIO_DECL local_datagram_socket : public io_object
         friend detail::bytes_op_base<send_awaitable>;
 
         local_datagram_socket& s_;
-        buffer_param buf_;
+        detail::buffer_param buf_;
         int flags_;
 
         std::coroutine_handle<>
@@ -481,7 +483,9 @@ class BOOST_COROSIO_DECL local_datagram_socket : public io_object
         friend local_datagram_socket;
 
         recv_awaitable(
-            local_datagram_socket& s, buffer_param buf, int flags = 0) noexcept
+            local_datagram_socket& s,
+            detail::buffer_param buf,
+            int flags = 0) noexcept
             : s_(s)
             , buf_(buf)
             , flags_(flags)
@@ -491,7 +495,7 @@ class BOOST_COROSIO_DECL local_datagram_socket : public io_object
         friend detail::bytes_op_base<recv_awaitable>;
 
         local_datagram_socket& s_;
-        buffer_param buf_;
+        detail::buffer_param buf_;
         int flags_;
 
         std::coroutine_handle<>

include/boost/corosio/random_access_file.hpp

@@ -87,7 +87,7 @@
             std::uint64_t offset,
             capy::continuation& cont,
             capy::executor_ref ex,
-            buffer_param buf,
+            detail::buffer_param buf,
             std::stop_token token,
             std::error_code* ec,
             std::size_t* bytes_out) = 0;
@@ -108,7 +108,7 @@
             std::uint64_t offset,
             capy::continuation& cont,
             capy::executor_ref ex,
-            buffer_param buf,
+            detail::buffer_param buf,
             std::stop_token token,
             std::error_code* ec,
             std::size_t* bytes_out) = 0;
@@ -143,7 +143,7 @@
         virtual std::error_code sync_all() noexcept = 0;
 
         /// Release ownership of the native handle.
         virtual capy::results<native_handle_type> release() noexcept = 0;
 
         /** Adopt an existing native handle.