include/boost/capy/write.hpp

100.0% Lines (2/0/2) 75.0% List of functions (9/0/12)

[ ] prev/next file

write.hpp

f(x) Functions (12)

Function Calls Lines Blocks

Line	Hits	Source Code
1		//
2		// Copyright (c) 2025 Vinnie Falco (vinnie.falco@gmail.com)
3		// Copyright (c) 2026 Michael Vandeberg
4		//
5		// Distributed under the Boost Software License, Version 1.0. (See accompanying
6		// file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
7		//
8		// Official repository: https://github.com/cppalliance/capy
9		//
10
11		#ifndef BOOST_CAPY_WRITE_HPP
12		#define BOOST_CAPY_WRITE_HPP
13
14		#include <boost/capy/detail/config.hpp>
15		#include <boost/capy/io_task.hpp>
16		#include <boost/capy/buffers.hpp>
17		#include <boost/capy/buffers/consuming_buffers.hpp>
18		#include <boost/capy/concept/write_stream.hpp>
19		#include <system_error>
20
21		#include <cstddef>
22
23		namespace boost {
24		namespace capy {
25
26		/** Write an entire buffer sequence to a stream.
27
28		@par Await-effects
29
30		Writes the contents of `buffers` to `stream` via awaiting
31		`stream.write_some` with consecutive portions of data from `buffers`
32		until:
33
34		@li either the full content of @c buffers is processed,
35		@li or a contingency in `stream.write_some` occurs.
36
37		If `buffer_size(buffers) == 0` then no awaiting `stream.write_some`
38		is performed. This is not a contingency.
39
40
41		@par Await-returns
42
43		An object of type `io_result<std::size_t>` destructuring as `[ec, n]`.
44
45		Upon a contingency, `n` represents the number of bytes written
46		so far.
47
48		Otherwise `n` represents the number of bytes written.
49
50		Contingencies:
51
52		@li The first contingency reported from awaiting @c stream.write_some
53		while not all bytes have been written. A contingency that accompanies
54		the write which transfers the last bytes is not reported: a completed
55		transfer is a success.
56
57		Notable conditions:
58
59		@li @c cond::canceled — Operation was cancelled,
60		@li @c std::errc::broken_pipe — Peer closed connection.
61
62
63		@par Await-postcondition
64
65		If `n == buffer_size(buffers)` the transfer completed and `ec` is
66		success; otherwise `ec` is set.
67
68
69		@param stream The stream to write to. If the lifetime of `stream` ends
70		before the coroutine finishes, the behavior is undefined.
71
72		@param buffers The buffer sequence to write. If the lifetime of the buffer
73		sequence represented by `buffers` ends
74		before the coroutine finishes, the behavior is undefined.
75
76		@return A task yielding `io_result<std::size_t>` whose second element
77		is the number of bytes written.
78
79		@par Remarks
80
81		Supports _IoAwaitable cancellation_.
82
83		@par Example
84
85		@code
86		capy::task<> send_response(capy::WriteStream auto& stream, std::string_view body)
87		{
88		auto [ec, n] = co_await capy::write(stream, capy::make_buffer(body));
89		if (ec)
90		throw std::system_error(ec);
91
92		// All bytes written successfully
93		}
94		@endcode
95
96		@see WriteStream, ConstBufferSequence, IoAwaitable, io_result, cond.
97		*/
98		template <WriteStream S, ConstBufferSequence CB>
99	70x	auto write(S& stream, CB buffers) -> io_task<std::size_t>
100		{
101		consuming_buffers consuming(buffers);
102		std::size_t const total_size = buffer_size(buffers);
103		std::size_t total_written = 0;
104
105		while(total_written < total_size)
106		{
107		auto [ec, n] = co_await stream.write_some(consuming.data());
108		consuming.consume(n);
109		total_written += n;
110		// A contingency that still completed the transfer is a success:
111		// report it only when not all bytes were written.
112		if(ec && total_written < total_size)
113		co_return {ec, total_written};
114		}
115
116		co_return {{}, total_written};
117	140x	}
118
119		} // namespace capy
120		} // namespace boost
121
122		#endif
123