include/boost/corosio/detail/buffer_param.hpp

100.0% Lines (26/26) 100.0% List of functions (25/25) 86.0% Branches (43/50)

[ ] prev/next file n p prev/next uncovered line

buffer_param.hpp

f(x) Functions (25)

Function Calls Lines Branches Blocks

Line	Branch	Hits	Source Code
1			//
2			// Copyright (c) 2025 Vinnie Falco ([email protected])
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/corosio
9			//
10
11			#ifndef BOOST_COROSIO_DETAIL_BUFFER_PARAM_HPP
12			#define BOOST_COROSIO_DETAIL_BUFFER_PARAM_HPP
13
14			#include <boost/corosio/detail/config.hpp>
15			#include <boost/capy/buffers.hpp>
16
17			#include <cstddef>
18
19			namespace boost::corosio {
20
21			/** A type-erased buffer sequence for I/O system call boundaries.
22
23			This class enables I/O objects to accept any buffer sequence type
24			across a virtual function boundary, while preserving the caller's
25			typed buffer sequence at the call site. The implementation can
26			then unroll the type-erased sequence into platform-native
27			structures (e.g., `iovec` on POSIX, `WSABUF` on Windows) for the
28			actual system call.
29
30			@par Purpose
31
32			When building coroutine-based I/O abstractions, a common pattern
33			emerges: a templated awaitable captures the caller's buffer
34			sequence, and at `await_suspend` time, must pass it across a
35			virtual interface to the I/O implementation. This class solves
36			the type-erasure problem at that boundary without heap allocation.
37
38			@par Restricted Use Case
39
40			This is NOT a general-purpose composable abstraction. It exists
41			solely for the final step in a coroutine I/O call chain where:
42
43			@li A templated awaitable captures the caller's buffer sequence
44			@li The awaitable's `await_suspend` passes buffers across a
45			virtual interface to an I/O object implementation
46			@li The implementation immediately unrolls the buffers into
47			platform-native structures for the system call
48
49			@par Lifetime Model
50
51			The safety of this class depends entirely on coroutine parameter
52			lifetime extension. When a coroutine is suspended, parameters
53			passed to the awaitable remain valid until the coroutine resumes
54			or is destroyed. This class exploits that guarantee by holding
55			only a pointer to the caller's buffer sequence.
56
57			The referenced buffer sequence is valid ONLY while the calling
58			coroutine remains suspended at the exact suspension point where
59			`buffer_param` was created. Once the coroutine resumes,
60			returns, or is destroyed, all referenced data becomes invalid.
61
62			@par Const Buffer Handling
63
64			This class accepts both `ConstBufferSequence` and
65			`MutableBufferSequence` types. However, `copy_to` always produces
66			`mutable_buffer` descriptors, casting away constness for const
67			buffer sequences. This design matches platform I/O structures
68			(`iovec`, `WSABUF`) which use non-const pointers regardless of
69			the operation direction.
70
71			@warning The caller is responsible for ensuring the type system
72			is not violated. When the original buffer sequence was const
73			(e.g., for a write operation), the implementation MUST NOT write
74			to the buffers obtained from `copy_to`. The const-cast exists
75			solely to provide a uniform interface for platform I/O calls.
76
77			@note Do NOT `reinterpret_cast` the `mutable_buffer` array to
78			`iovec`/`WSABUF` and pass it to the OS, even when the layouts
79			match: no object of the target type exists in that storage, so the
80			access is undefined behavior (and `mutable_buffer` is not an
81			implicit-lifetime type, so `std::start_lifetime_as_array` cannot
82			rescue it). Copy field by field into a real platform array instead.
83
84			@code
85			// For write operations (const buffers):
86			void submit_write(buffer_param p)
87			{
88			capy::mutable_buffer bufs[8];
89			auto n = p.copy_to(bufs, 8);
90			iovec iov[8];
91			for (std::size_t i = 0; i < n; ++i)
92			{
93			// bufs[] may reference const data - DO NOT WRITE through iov
94			iov[i].iov_base = bufs[i].data();
95			iov[i].iov_len = bufs[i].size();
96			}
97			writev(fd, iov, n); // read-only
98			}
99
100			// For read operations (mutable buffers):
101			void submit_read(buffer_param p)
102			{
103			capy::mutable_buffer bufs[8];
104			auto n = p.copy_to(bufs, 8);
105			iovec iov[8];
106			for (std::size_t i = 0; i < n; ++i)
107			{
108			// bufs[] references mutable data - safe to write
109			iov[i].iov_base = bufs[i].data();
110			iov[i].iov_len = bufs[i].size();
111			}
112			readv(fd, iov, n); // writing
113			}
114			@endcode
115
116			@par Correct Usage
117
118			The implementation receiving `buffer_param` MUST:
119
120			@li Call `copy_to` immediately upon receiving the parameter
121			@li Use the unrolled buffer descriptors for the I/O operation
122			@li Never store the `buffer_param` object itself
123			@li Never store pointers obtained from `copy_to` beyond the
124			immediate I/O operation
125
126			@par Example: Correct Usage
127
128			@code
129			// Templated awaitable at the call site
130			template<class Buffers>
131			struct write_awaitable
132			{
133			Buffers bufs;
134			io_stream* stream;
135
136			bool await_ready() { return false; }
137
138			void await_suspend(std::coroutine_handle<> h)
139			{
140			// CORRECT: Pass to virtual interface while suspended.
141			// The buffer sequence 'bufs' remains valid because
142			// coroutine parameters live until resumption.
143			stream->async_write_some_impl(bufs, h);
144			}
145
146			io_result await_resume() { return stream->get_result(); }
147			};
148
149			// Virtual implementation - unrolls immediately
150			void stream_impl::async_write_some_impl(
151			buffer_param p,
152			std::coroutine_handle<> h)
153			{
154			// CORRECT: Unroll immediately into platform structure.
155			// Copy field by field; do NOT reinterpret_cast the
156			// mutable_buffer array to iovec* (see the @note above).
157			capy::mutable_buffer bufs[16];
158			std::size_t n = p.copy_to(bufs, 16);
159			iovec vecs[16];
160			for (std::size_t i = 0; i < n; ++i)
161			{
162			vecs[i].iov_base = bufs[i].data();
163			vecs[i].iov_len = bufs[i].size();
164			}
165
166			// CORRECT: Use unrolled buffers for system call now
167			submit_to_io_uring(vecs, n, h);
168
169			// After this function returns, 'p' must not be used again.
170			// The iovec array is safe because it contains copies of
171			// the pointer/size pairs, not references to 'p'.
172			}
173			@endcode
174
175			@par UNSAFE USAGE: Storing buffer_param
176
177			@warning Never store `buffer_param` for later use.
178
179			@code
180			class broken_stream
181			{
182			buffer_param saved_param_; // UNSAFE: member storage
183
184			void async_write_impl(buffer_param p, ...)
185			{
186			saved_param_ = p; // UNSAFE: storing for later
187			schedule_write_later();
188			}
189
190			void do_write_later()
191			{
192			// UNSAFE: The calling coroutine may have resumed
193			// or been destroyed. saved_param_ now references
194			// invalid memory!
195			capy::mutable_buffer bufs[8];
196			saved_param_.copy_to(bufs, 8); // UNDEFINED BEHAVIOR
197			}
198			};
199			@endcode
200
201			@par UNSAFE USAGE: Storing Unrolled Pointers
202
203			@warning The pointers obtained from `copy_to` point into the
204			caller's buffer sequence. They become invalid when the caller
205			resumes.
206
207			@code
208			class broken_stream
209			{
210			capy::mutable_buffer saved_bufs_[8]; // UNSAFE
211			std::size_t saved_count_;
212
213			void async_write_impl(buffer_param p, ...)
214			{
215			// This copies pointer/size pairs into saved_bufs_
216			saved_count_ = p.copy_to(saved_bufs_, 8);
217
218			// UNSAFE: scheduling for later while storing the
219			// buffer descriptors. The pointers in saved_bufs_
220			// will dangle when the caller resumes!
221			schedule_for_later();
222			}
223
224			void later()
225			{
226			// UNSAFE: saved_bufs_ contains dangling pointers
227			for(std::size_t i = 0; i < saved_count_; ++i)
228			write(fd_, saved_bufs_[i].data(), ...); // UB
229			}
230			};
231			@endcode
232
233			@par UNSAFE USAGE: Using Outside a Coroutine
234
235			@warning This class relies on coroutine lifetime semantics.
236			Using it with callbacks or non-coroutine async patterns is
237			undefined behavior.
238
239			@code
240			// UNSAFE: No coroutine lifetime guarantee
241			void bad_callback_pattern(std::vector<char>& data)
242			{
243			capy::mutable_buffer buf(data.data(), data.size());
244
245			// UNSAFE: In a callback model, 'buf' may go out of scope
246			// before the callback fires. There is no coroutine
247			// suspension to extend the lifetime.
248			stream.async_write(buf, [](error_code ec) {
249			// 'buf' is already destroyed!
250			});
251			}
252			@endcode
253
254			@par UNSAFE USAGE: Passing to Another Coroutine
255
256			@warning Do not pass `buffer_param` to a different coroutine
257			or spawn a new coroutine that captures it.
258
259			@code
260			void broken_impl(buffer_param p, std::coroutine_handle<> h)
261			{
262			// UNSAFE: Spawning a new coroutine that captures 'p'.
263			// The original coroutine may resume before this new
264			// coroutine uses 'p'.
265			co_spawn([p]() -> task<void> {
266			capy::mutable_buffer bufs[8];
267			p.copy_to(bufs, 8); // UNSAFE: original caller may
268			// have resumed already!
269			co_return;
270			});
271			}
272			@endcode
273
274			@par UNSAFE USAGE: Multiple Virtual Hops
275
276			@warning Minimize indirection. Each virtual call that passes
277			`buffer_param` without immediately unrolling it increases
278			the risk of misuse.
279
280			@code
281			// Risky: multiple hops before unrolling
282			void layer1(buffer_param p) {
283			layer2(p); // Still haven't unrolled...
284			}
285			void layer2(buffer_param p) {
286			layer3(p); // Still haven't unrolled...
287			}
288			void layer3(buffer_param p) {
289			// Finally unrolling, but the chain is fragile.
290			// Any intermediate layer storing 'p' breaks everything.
291			}
292			@endcode
293
294			@par UNSAFE USAGE: Fire-and-Forget Operations
295
296			@warning Do not use with detached or fire-and-forget async
297			operations where there is no guarantee the caller remains
298			suspended.
299
300			@code
301			task<void> caller()
302			{
303			char buf[1024];
304			// UNSAFE: If async_write is fire-and-forget (doesn't
305			// actually suspend the caller), 'buf' may be destroyed
306			// before the I/O completes.
307			stream.async_write_detached(capy::mutable_buffer(buf, 1024));
308			// Returns immediately - 'buf' goes out of scope!
309			}
310			@endcode
311
312			@par Passing Convention
313
314			Pass by value. The class contains only two pointers (16 bytes
315			on 64-bit systems), making copies trivial and clearly
316			communicating the lightweight, transient nature of this type.
317
318			@code
319			// Preferred: pass by value
320			void process(buffer_param buffers);
321
322			// Also acceptable: pass by const reference
323			void process(buffer_param const& buffers);
324			@endcode
325
326			@see capy::ConstBufferSequence, capy::MutableBufferSequence
327			*/
328			class buffer_param
329			{
330			public:
331			/** Construct from a const buffer sequence.
332
333			@param bs The buffer sequence to adapt.
334			*/
335			template<capy::ConstBufferSequence BS>
336		2454634x	buffer_param(BS const& bs) noexcept : bs_(&bs)
337		1227317x	, fn_(&copy_impl<BS>)
338		1227317x	{
339		2454634x	}
340
341			/** Fill an array with buffers from the sequence.
342
343			Copies buffer descriptors from the sequence into the
344			destination array, skipping any zero-size buffers.
345			This ensures the output contains only buffers with
346			actual data, suitable for direct use with system calls.
347
348			@param dest Pointer to array of mutable buffer descriptors.
349			@param n Maximum number of buffers to copy.
350
351			@return The number of non-zero buffers copied.
352			*/
353			std::size_t
354		1227317x	copy_to(capy::mutable_buffer* dest, std::size_t n) const noexcept
355			{
356	1/2 ✓ Branch 0 taken 1227317 times. ✗ Branch 1 not taken.	1227317x	return fn_(bs_, dest, n);
357			}
358
359			private:
360			template<capy::ConstBufferSequence BS>
361			static std::size_t
362		1227317x	copy_impl(void const* p, capy::mutable_buffer* dest, std::size_t n)
363			{
364		1227317x	auto const& bs = static_cast<BS const>(p);
365		1227317x	auto it = capy::begin(bs);
366		1227317x	auto const end_it = capy::end(bs);
367
368		1227317x	std::size_t i = 0;
369			if constexpr (capy::MutableBufferSequence<BS>)
370			{
371	8/8 ✓ Branch 0 taken 552482 times. ✓ Branch 1 taken 552482 times. ✓ Branch 2 taken 552482 times. ✓ Branch 3 taken 552482 times. ✓ Branch 4 taken 22 times. ✓ Branch 5 taken 32 times. ✓ Branch 6 taken 32 times. ✓ Branch 7 taken 22 times.	1105018x	for (; it != end_it && i < n; ++it)
372			{
373		552514x	capy::mutable_buffer buf(*it);
374	4/4 ✓ Branch 0 taken 552467 times. ✓ Branch 1 taken 15 times. ✓ Branch 2 taken 30 times. ✓ Branch 3 taken 2 times.	552514x	if (buf.size() == 0)
375		17x	continue;
376		552497x	dest[i++] = buf;
377		552497x	}
378			}
379			else
380			{
381	22/24 ✓ Branch 0 taken 531812 times. ✓ Branch 1 taken 531812 times. ✓ Branch 2 taken 531812 times. ✓ Branch 3 taken 531812 times. ✓ Branch 4 taken 5 times. ✓ Branch 5 taken 10 times. ✓ Branch 6 taken 10 times. ✓ Branch 7 taken 5 times. ✓ Branch 8 taken 142986 times. ✓ Branch 9 taken 142987 times. ✓ Branch 10 taken 142987 times. ✓ Branch 11 taken 142986 times. ✓ Branch 12 taken 5 times. ✓ Branch 13 taken 15 times. ✓ Branch 14 taken 15 times. ✓ Branch 15 taken 5 times. ✓ Branch 16 taken 3 times. ✓ Branch 17 taken 12 times. ✓ Branch 18 taken 11 times. ✓ Branch 19 taken 4 times. ✓ Branch 20 taken 1 time. ✗ Branch 21 not taken. ✗ Branch 22 not taken. ✓ Branch 23 taken 1 time.	1349648x	for (; it != end_it && i < n; ++it)
382			{
383		674835x	capy::const_buffer buf(*it);
384	8/12 ✓ Branch 0 taken 531796 times. ✓ Branch 1 taken 16 times. ✓ Branch 2 taken 7 times. ✓ Branch 3 taken 3 times. ✓ Branch 4 taken 142987 times. ✗ Branch 5 not taken. ✓ Branch 6 taken 15 times. ✗ Branch 7 not taken. ✓ Branch 8 taken 6 times. ✓ Branch 9 taken 5 times. ✗ Branch 10 not taken. ✗ Branch 11 not taken.	674835x	if (buf.size() == 0)
385		24x	continue;
386		674811x	dest[i++] = capy::mutable_buffer(
387		674811x	const_cast<char>(static_cast<char const>(buf.data())),
388		674811x	buf.size());
389		674811x	}
390			}
391		1227317x	return i;
392			}
393
394			using fn_t =
395			std::size_t ()(void const, capy::mutable_buffer*, std::size_t);
396
397			void const* bs_;
398			fn_t fn_;
399			};
400
401			} // namespace boost::corosio
402
403			#endif
404