From fbc4969bbd7f07d0173cb77d54e3c21308485809 Mon Sep 17 00:00:00 2001 From: Andrzej Krzemienski Date: Mon, 18 May 2026 17:42:55 +0200 Subject: [PATCH 1/2] 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 161361dc4bc455fdedc865b2d7b0f8f1305250b4 Mon Sep 17 00:00:00 2001 From: Andrzej Krzemienski Date: Mon, 18 May 2026 22:03:44 +0200 Subject: [PATCH 2/2] 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