From 10cdc59eda60c1ac7e46344bf1d7f709574b11e7 Mon Sep 17 00:00:00 2001 From: Andrzej Krzemienski Date: Mon, 18 May 2026 17:42:55 +0200 Subject: [PATCH 1/4] docs: prototype new specification for `write` This changes the declaration format and JavaDoc annotations for funciton capy::write. The goal is to show how an alternative specification would look like and render in the documentation. --- include/boost/capy/write.hpp | 65 ++++++++++++++++++++++++------------ 1 file changed, 43 insertions(+), 22 deletions(-) diff --git a/include/boost/capy/write.hpp b/include/boost/capy/write.hpp index 7521aa4c..7eccc479 100644 --- a/include/boost/capy/write.hpp +++ b/include/boost/capy/write.hpp @@ -22,30 +22,52 @@ namespace boost { namespace capy { -/** Asynchronously write the entire buffer sequence. +/** Make an awaitable for writing a buffer sequence to a stream. - Writes data to the stream by calling `write_some` repeatedly - until the entire buffer sequence is written or an error occurs. + @par Await-effects + + Writes the contents of `buffers` to `stream` via awaiting on + `stream.write_some` with consecutive portions of data form `buffers` + until: + + @li either the full content of @c buffers is processed, + @li or an irregular situation occurs. + + @par Irregular outcomes + + Whatever the first irregular outcome is reported from + awaiting on `stream.write_some`. + + Notable conditions: + + @li @c cond::canceled — Operation was cancelled, + @li @c std::errc::broken_pipe — Peer closed connection. + + @par Await-returns + + An object of type `io_result` destructuring as `[ec, n]`. + + Upon an irregular outcome, `n` represents the number of bytes written + so far. + + Otherwise `n` represents the number of bytes written. + + + @par Await-postcondition + + `ec || n == buffer_size(buffers)` is `true`. - @li The operation completes when: - @li The entire buffer sequence has been written - @li An error occurs - @li The operation is cancelled @par Cancellation Supports cancellation via `stop_token` propagated through the - IoAwaitable protocol. When cancelled, returns with `cond::canceled`. + `IoAwaitable` protocol. When cancelled, returns with `cond::canceled`. + + @param stream The stream to write to. If the lifetime of `stream` ends + before the coroutine finishes, the behavior is undefined. - @param stream The stream to write to. The caller retains ownership. - @param buffers The buffer sequence to write. The caller retains - ownership and must ensure validity until the operation completes. + @param buffers The buffer sequence to write. If the lifetime of `buffers` ends + before the coroutine finishes, the behavior is undefined. - @return An awaitable that await-returns `(error_code, std::size_t)`. - On success, `n` equals `buffer_size(buffers)`. On error, - `n` is the number of bytes written before the error. Compare - error codes to conditions: - @li `cond::canceled` - Operation was cancelled - @li `std::errc::broken_pipe` - Peer closed connection @par Example @@ -59,13 +81,12 @@ namespace capy { } @endcode + @return + @see write_some, WriteStream, ConstBufferSequence */ -auto -write( - WriteStream auto& stream, - ConstBufferSequence auto buffers) -> - io_task +template +auto write(S& stream, CB buffers) -> io_task { auto consuming = buffer_slice(buffers); std::size_t const total_size = buffer_size(buffers); From 651d6423516130f03798e17f5f308e2224f19e48 Mon Sep 17 00:00:00 2001 From: Andrzej Krzemienski Date: Mon, 18 May 2026 22:03:44 +0200 Subject: [PATCH 2/4] Use term "contingency" --- include/boost/capy/write.hpp | 34 ++++++++++++++++++---------------- 1 file changed, 18 insertions(+), 16 deletions(-) diff --git a/include/boost/capy/write.hpp b/include/boost/capy/write.hpp index 7eccc479..8850c47a 100644 --- a/include/boost/capy/write.hpp +++ b/include/boost/capy/write.hpp @@ -31,31 +31,32 @@ namespace capy { until: @li either the full content of @c buffers is processed, - @li or an irregular situation occurs. + @li or a contingency occurs. - @par Irregular outcomes - - Whatever the first irregular outcome is reported from - awaiting on `stream.write_some`. - - Notable conditions: - - @li @c cond::canceled — Operation was cancelled, - @li @c std::errc::broken_pipe — Peer closed connection. @par Await-returns An object of type `io_result` destructuring as `[ec, n]`. - Upon an irregular outcome, `n` represents the number of bytes written + Upon a contingency, `n` represents the number of bytes written so far. Otherwise `n` represents the number of bytes written. + Contingencies: + + @li Whatever the first contingency is reported from + awaiting on @c stream.write_some . + + Notable conditions: + + @li @c cond::canceled — Operation was cancelled, + @li @c std::errc::broken_pipe — Peer closed connection. + @par Await-postcondition - `ec || n == buffer_size(buffers)` is `true`. + `ec || n == buffer_size(buffers)`. @par Cancellation @@ -72,11 +73,12 @@ namespace capy { @par Example @code - task<> send_response( WriteStream auto& stream, std::string_view body ) + task<> send_response(capy::WriteStream auto& stream, std::string_view body) { - auto [ec, n] = co_await write( stream, make_buffer( body ) ); - if( ec ) - detail::throw_system_error( ec ); + auto [ec, n] = co_await capy::write(stream, capy::make_buffer(body)); + if (ec) + throw std::system_error(ec); + // All bytes written successfully } @endcode From 093e1319c4f23d6bc9867b8c3361ac828faadfef Mon Sep 17 00:00:00 2001 From: Andrzej Krzemienski Date: Wed, 20 May 2026 23:31:30 +0200 Subject: [PATCH 3/4] Claude review --- include/boost/capy/write.hpp | 14 +++++++++----- 1 file changed, 9 insertions(+), 5 deletions(-) diff --git a/include/boost/capy/write.hpp b/include/boost/capy/write.hpp index 8850c47a..f7b8072d 100644 --- a/include/boost/capy/write.hpp +++ b/include/boost/capy/write.hpp @@ -22,17 +22,20 @@ namespace boost { namespace capy { -/** Make an awaitable for writing a buffer sequence to a stream. +/** Write an entire buffer sequence to a stream. @par Await-effects Writes the contents of `buffers` to `stream` via awaiting on - `stream.write_some` with consecutive portions of data form `buffers` + `stream.write_some` with consecutive portions of data from `buffers` until: @li either the full content of @c buffers is processed, @li or a contingency occurs. + If `buffer_size(buffers) == 0` then no awaiting on `stream.write_some` + is performed. This is not a contingency. + @par Await-returns @@ -45,7 +48,7 @@ namespace capy { Contingencies: - @li Whatever the first contingency is reported from + @li The first contingency reported from awaiting on @c stream.write_some . Notable conditions: @@ -66,7 +69,8 @@ namespace capy { @param stream The stream to write to. If the lifetime of `stream` ends before the coroutine finishes, the behavior is undefined. - @param buffers The buffer sequence to write. If the lifetime of `buffers` ends + @param buffers The buffer sequence to write. If the lifetime of the buffer + sequence represented by `buffers` ends before the coroutine finishes, the behavior is undefined. @@ -85,7 +89,7 @@ namespace capy { @return - @see write_some, WriteStream, ConstBufferSequence + @see WriteStream, ConstBufferSequence, IoAwaitable, io_result, cond. */ template auto write(S& stream, CB buffers) -> io_task From c230174854f0449fe8f16241e02e6e8faed9a345 Mon Sep 17 00:00:00 2001 From: Andrzej Krzemienski Date: Thu, 21 May 2026 13:09:36 +0200 Subject: [PATCH 4/4] namespace prefix --- include/boost/capy/write.hpp | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/include/boost/capy/write.hpp b/include/boost/capy/write.hpp index f7b8072d..e3ff3e1e 100644 --- a/include/boost/capy/write.hpp +++ b/include/boost/capy/write.hpp @@ -77,7 +77,7 @@ namespace capy { @par Example @code - task<> send_response(capy::WriteStream auto& stream, std::string_view body) + capy::task<> send_response(capy::WriteStream auto& stream, std::string_view body) { auto [ec, n] = co_await capy::write(stream, capy::make_buffer(body)); if (ec)