GCC Code Coverage Report

Directory: ./
Coverage: low: ≥ 0% medium: ≥ 75.0% high: ≥ 90.0%
Coverage Exec / Excl / Total
Lines: 91.0% 61 / 0 / 67
Functions: 100.0% 6 / 0 / 6
Branches: -% 0 / 0 / 0
libs/capy/include/boost/capy/buffers/buffer_param.hpp
Line Branch Exec Source
1 //
2 // Copyright (c) 2025 Vinnie Falco (vinnie.falco@gmail.com)
3 //
4 // Distributed under the Boost Software License, Version 1.0. (See accompanying
5 // file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
6 //
7 // Official repository: https://github.com/cppalliance/capy
8 //
9
10 #ifndef BOOST_CAPY_BUFFERS_BUFFER_PARAM_HPP
11 #define BOOST_CAPY_BUFFERS_BUFFER_PARAM_HPP
12
13 #include <boost/capy/detail/config.hpp>
14 #include <boost/capy/buffers.hpp>
15 #include <boost/assert.hpp>
16
17 #include <array>
18 #include <span>
19 #include <type_traits>
20
21 namespace boost {
22 namespace capy {
23
24 /** A type-erased const buffer sequence for function call boundaries.
25
26 This class enables functions to accept any const buffer sequence
27 type across a non-template interface, while the caller retains
28 ownership of the underlying buffer data. The class provides
29 incremental access to the buffer sequence through a sliding
30 window, allowing efficient processing of arbitrarily large
31 sequences without copying all buffer descriptors upfront.
32
33 @par Purpose
34
35 When building I/O abstractions, a common need arises: accepting
36 buffer sequences of any type through a non-template function
37 signature. This class solves the type-erasure problem by storing
38 function pointers that operate on the concrete buffer sequence
39 type, while presenting a uniform interface to the callee.
40
41 @par Lifetime Model
42
43 @warning This class has DANGEROUS lifetime semantics. The safety
44 of this class depends entirely on the lifetime of the object
45 returned by @ref make_const_buffer_param. When that object is
46 destroyed, this class becomes invalid and any use is undefined
47 behavior.
48
49 The intended usage pattern exploits C++ temporary lifetime
50 extension: when passing the result of @ref make_const_buffer_param
51 directly to a function taking `const_buffer_param` by value,
52 slicing occurs and the temporary implementation object lives
53 until the function returns. This is safe:
54
55 @code
56 void write_some(const_buffer_param buffers);
57
58 // SAFE: temporary lives through the function call
59 write_some(make_const_buffer_param(my_buffers));
60 @endcode
61
62 @par Correct Usage
63
64 The implementation receiving `const_buffer_param` MUST:
65
66 @li Use `data()` and `consume()` immediately within the call
67 @li Never store the `const_buffer_param` object
68 @li Never return the `const_buffer_param` from the function
69 @li Complete all buffer processing before returning
70
71 @par Example: Correct Usage
72
73 @code
74 // Function accepts type-erased buffer parameter
75 std::size_t write_all(socket& sock, const_buffer_param buffers)
76 {
77 std::size_t total = 0;
78 while(true)
79 {
80 auto bufs = buffers.data();
81 if(bufs.empty())
82 break;
83 auto n = sock.write_some(bufs);
84 total += n;
85 buffers.consume(n);
86 }
87 return total;
88 }
89
90 // Caller creates temporary that lives through the call
91 std::vector<const_buffer> chunks = get_chunks();
92 auto n = write_all(sock, make_const_buffer_param(chunks));
93 @endcode
94
95 @par UNSAFE USAGE: Storing const_buffer_param
96
97 @warning Never store `const_buffer_param` for later use.
98
99 @code
100 class broken_writer
101 {
102 const_buffer_param saved_; // UNSAFE: member storage
103
104 void start_write(const_buffer_param buffers)
105 {
106 saved_ = buffers; // UNSAFE: storing for later
107 schedule_write();
108 }
109
110 void do_write()
111 {
112 // UNSAFE: The temporary from make_const_buffer_param
113 // was destroyed when start_write returned!
114 auto bufs = saved_.data(); // UNDEFINED BEHAVIOR
115 }
116 };
117 @endcode
118
119 @par UNSAFE USAGE: Returning const_buffer_param
120
121 @warning Never return `const_buffer_param` from a function.
122
123 @code
124 // UNSAFE: Returning causes the temporary to be destroyed
125 const_buffer_param get_buffers()
126 {
127 std::vector<const_buffer> bufs = prepare_buffers();
128 return make_const_buffer_param(bufs); // UNSAFE!
129 // The temporary AND the vector are destroyed here
130 }
131
132 void caller()
133 {
134 auto bp = get_buffers(); // Receives invalid object
135 bp.data(); // UNDEFINED BEHAVIOR
136 }
137 @endcode
138
139 @par UNSAFE USAGE: Storing in a Container
140
141 @warning Never store `const_buffer_param` in containers or
142 data structures.
143
144 @code
145 std::vector<const_buffer_param> pending; // UNSAFE
146
147 void queue_write(const_buffer_param buffers)
148 {
149 pending.push_back(buffers); // UNSAFE: storing
150 }
151
152 void process_pending()
153 {
154 for(auto& bp : pending)
155 bp.data(); // UNDEFINED BEHAVIOR
156 }
157 @endcode
158
159 @par UNSAFE USAGE: Assigning to a Variable
160
161 @warning Assigning to a named variable extends the wrong
162 lifetime.
163
164 @code
165 void broken()
166 {
167 auto bp = make_const_buffer_param(my_buffers);
168 // bp is valid here...
169
170 some_function(); // ...but if this modifies my_buffers...
171
172 bp.data(); // ...this may see inconsistent state
173 }
174
175 void also_broken()
176 {
177 const_buffer_param bp = make_const_buffer_param(
178 std::vector<const_buffer>{{data, size}});
179 // UNSAFE: The temporary vector is destroyed immediately!
180 bp.data(); // UNDEFINED BEHAVIOR
181 }
182 @endcode
183
184 @par Passing Convention
185
186 Pass by value. The class contains only three pointers (24 bytes
187 on 64-bit systems), making copies trivial. Pass-by-value also
188 makes the slicing behavior explicit at call sites.
189
190 @see make_const_buffer_param, mutable_buffer_param
191 */
192 class const_buffer_param
193 {
194 protected:
195 void* ctx_;
196 std::span<const_buffer>(*data_)(void*);
197 bool (*consume_)(void*, std::size_t);
198
199 public:
200 /** Return the current window of buffer descriptors.
201
202 Returns a span of buffer descriptors representing the
203 currently available portion of the buffer sequence. The
204 span may contain fewer buffers than the total sequence;
205 call @ref consume to advance through the sequence and
206 then call `data()` again to get the next window.
207
208 @return A span of const buffer descriptors. Empty span
209 indicates no more data is available.
210 */
211 std::span<const_buffer>
212 19 data() const noexcept
213 {
214 19 return data_(ctx_);
215 }
216
217 /** Consume bytes from the buffer sequence.
218
219 Advances the current position by `n` bytes, consuming
220 data from the front of the sequence. After consuming,
221 call @ref data to get the updated window of remaining
222 buffers.
223
224 @param n Number of bytes to consume.
225
226 @return `true` if more data remains in the sequence,
227 `false` if the sequence is exhausted.
228 */
229 bool
230 12 consume(std::size_t n)
231 {
232 12 return consume_(ctx_, n);
233 }
234 };
235
236 /** A type-erased mutable buffer sequence for function call boundaries.
237
238 This class is identical to @ref const_buffer_param except it
239 operates on mutable buffer sequences, allowing the callee to
240 write into the buffers.
241
242 @warning This class has the same dangerous lifetime semantics
243 as @ref const_buffer_param. Read that documentation carefully
244 before using this class.
245
246 @see make_buffer_param, const_buffer_param
247 */
248 class mutable_buffer_param
249 {
250 protected:
251 void* ctx_;
252 std::span<mutable_buffer>(*data_)(void*);
253 bool (*consume_)(void*, std::size_t);
254
255 public:
256 /** Return the current window of buffer descriptors.
257
258 @return A span of mutable buffer descriptors. Empty span
259 indicates no more data is available.
260
261 @see const_buffer_param::data
262 */
263 std::span<mutable_buffer>
264 4 data() const noexcept
265 {
266 4 return data_(ctx_);
267 }
268
269 /** Consume bytes from the buffer sequence.
270
271 @param n Number of bytes to consume.
272
273 @return `true` if more data remains in the sequence,
274 `false` if the sequence is exhausted.
275
276 @see const_buffer_param::consume
277 */
278 bool
279 3 consume(std::size_t n)
280 {
281 3 return consume_(ctx_, n);
282 }
283 };
284
285 /** Create a const buffer parameter from a buffer sequence.
286
287 Constructs a type-erased buffer parameter that provides
288 incremental access to the given buffer sequence. The returned
289 object inherits from @ref const_buffer_param and can be passed
290 to functions accepting that type by value (causing slicing).
291
292 @warning The returned object contains pointers to internal
293 state. The object MUST remain alive while any sliced
294 @ref const_buffer_param copy is in use. The intended pattern
295 is to pass the result directly to a function:
296
297 @code
298 void process(const_buffer_param bp);
299
300 // CORRECT: temporary lives through the call
301 process(make_const_buffer_param(buffers));
302
303 // DANGEROUS: storing extends the wrong lifetime
304 auto bp = make_const_buffer_param(buffers);
305 process(bp); // Works, but fragile
306 @endcode
307
308 @par Thread Safety
309 Not thread-safe. The returned object and any sliced copies
310 must not be used concurrently.
311
312 @param bs The buffer sequence to wrap. Must remain valid
313 for the lifetime of the returned object.
314
315 @return An implementation object that inherits from
316 @ref const_buffer_param.
317 */
318 template<ConstBufferSequence BS>
319 [[nodiscard]] auto
320 8 make_const_buffer_param(BS const& bs)
321 {
322 class impl : public const_buffer_param
323 {
324 std::array<const_buffer, 16> arr_;
325 decltype(begin(std::declval<BS const&>())) it_;
326 decltype(end(std::declval<BS const&>())) end_;
327 std::size_t size_ = 0;
328 std::size_t pos_ = 0;
329 std::size_t offset_ = 0;
330
331 void
332 refill_window()
333 {
334 pos_ = 0;
335 size_ = 0;
336 offset_ = 0;
337 for(; it_ != end_ && size_ < 16; ++it_)
338 {
339 const_buffer buf(*it_);
340 if(buf.size() == 0)
341 continue;
342 arr_[size_++] = buf;
343 }
344 }
345
346 static
347 std::span<const_buffer>
348 data_impl(void* ctx)
349 {
350 auto& self = *static_cast<impl*>(ctx);
351 if(self.pos_ >= self.size_)
352 self.refill_window();
353 if(self.size_ == 0)
354 return {};
355 if(self.offset_ > 0)
356 {
357 auto& buf = self.arr_[self.pos_];
358 buf = const_buffer(
359 static_cast<char const*>(buf.data()) + self.offset_,
360 buf.size() - self.offset_);
361 self.offset_ = 0;
362 }
363 return { self.arr_.data() + self.pos_, self.size_ - self.pos_ };
364 }
365
366 static
367 bool
368 consume_impl(void* ctx, std::size_t n)
369 {
370 auto& self = *static_cast<impl*>(ctx);
371 while(n > 0 && self.pos_ < self.size_)
372 {
373 auto const avail = self.arr_[self.pos_].size() - self.offset_;
374 if(n < avail)
375 {
376 self.offset_ += n;
377 n = 0;
378 }
379 else
380 {
381 n -= avail;
382 self.offset_ = 0;
383 ++self.pos_;
384 }
385 }
386 if(self.pos_ >= self.size_ && self.it_ != self.end_)
387 self.refill_window();
388 return self.pos_ < self.size_;
389 }
390
391 static
392 std::span<const_buffer>
393 data_after_destroy(void*)
394 {
395 BOOST_ASSERT(!"const_buffer_param used after impl destroyed");
396 return {};
397 }
398
399 static
400 bool
401 consume_after_destroy(void*, std::size_t)
402 {
403 BOOST_ASSERT(!"const_buffer_param used after impl destroyed");
404 return false;
405 }
406
407 public:
408 impl(impl const&) = delete;
409 impl(impl&&) = delete;
410 impl& operator=(impl const&) = delete;
411 impl& operator=(impl&&) = delete;
412
413 explicit
414 impl(BS const& bs)
415 : it_(begin(bs))
416 , end_(end(bs))
417 {
418 ctx_ = this;
419 data_ = &data_impl;
420 consume_ = &consume_impl;
421 refill_window();
422 }
423
424 ~impl()
425 {
426 ctx_ = nullptr;
427 data_ = &data_after_destroy;
428 consume_ = &consume_after_destroy;
429 }
430 };
431
432 8 return impl(bs);
433 }
434
435 /** @copydoc make_const_buffer_param(BS const&)
436 @note Deleted overload to prevent passing temporary buffer sequences.
437 */
438 template<class BS>
439 requires ConstBufferSequence<std::remove_cvref_t<BS>> &&
440 (!std::is_lvalue_reference_v<BS>)
441 auto
442 make_const_buffer_param(BS&&) = delete;
443
444 /** Create a mutable buffer parameter from a buffer sequence.
445
446 Constructs a type-erased buffer parameter that provides
447 incremental access to the given mutable buffer sequence.
448
449 @warning The returned object has the same dangerous lifetime
450 semantics as @ref make_const_buffer_param. Read that
451 documentation carefully.
452
453 @par Thread Safety
454 Not thread-safe.
455
456 @param bs The mutable buffer sequence to wrap. Must remain
457 valid for the lifetime of the returned object.
458
459 @return An implementation object that inherits from
460 @ref mutable_buffer_param.
461
462 @see make_const_buffer_param, mutable_buffer_param
463 */
464 template<MutableBufferSequence BS>
465 [[nodiscard]] auto
466 2 make_buffer_param(BS const& bs)
467 {
468 class impl : public mutable_buffer_param
469 {
470 std::array<mutable_buffer, 16> arr_;
471 decltype(begin(std::declval<BS const&>())) it_;
472 decltype(end(std::declval<BS const&>())) end_;
473 std::size_t size_ = 0;
474 std::size_t pos_ = 0;
475 std::size_t offset_ = 0;
476
477 void
478 3 refill_window()
479 {
480 3 pos_ = 0;
481 3 size_ = 0;
482 3 offset_ = 0;
483 7 for(; it_ != end_ && size_ < 16; ++it_)
484 {
485 4 mutable_buffer buf(*it_);
486 4 if(buf.size() == 0)
487 ✗ continue;
488 4 arr_[size_++] = buf;
489 }
490 3 }
491
492 static
493 std::span<mutable_buffer>
494 4 data_impl(void* ctx)
495 {
496 4 auto& self = *static_cast<impl*>(ctx);
497 4 if(self.pos_ >= self.size_)
498 1 self.refill_window();
499 4 if(self.size_ == 0)
500 1 return {};
501 3 if(self.offset_ > 0)
502 {
503 1 auto& buf = self.arr_[self.pos_];
504 3 buf = mutable_buffer(
505 1 static_cast<char*>(buf.data()) + self.offset_,
506 1 buf.size() - self.offset_);
507 1 self.offset_ = 0;
508 }
509 6 return { self.arr_.data() + self.pos_, self.size_ - self.pos_ };
510 }
511
512 static
513 bool
514 3 consume_impl(void* ctx, std::size_t n)
515 {
516 3 auto& self = *static_cast<impl*>(ctx);
517 8 while(n > 0 && self.pos_ < self.size_)
518 {
519 5 auto const avail = self.arr_[self.pos_].size() - self.offset_;
520 5 if(n < avail)
521 {
522 2 self.offset_ += n;
523 2 n = 0;
524 }
525 else
526 {
527 3 n -= avail;
528 3 self.offset_ = 0;
529 3 ++self.pos_;
530 }
531 }
532 3 if(self.pos_ >= self.size_ && self.it_ != self.end_)
533 ✗ self.refill_window();
534 3 return self.pos_ < self.size_;
535 }
536
537 static
538 std::span<mutable_buffer>
539 ✗ data_after_destroy(void*)
540 {
541 ✗ BOOST_ASSERT(!"mutable_buffer_param used after impl destroyed");
542 return {};
543 }
544
545 static
546 bool
547 ✗ consume_after_destroy(void*, std::size_t)
548 {
549 ✗ BOOST_ASSERT(!"mutable_buffer_param used after impl destroyed");
550 return false;
551 }
552
553 public:
554 impl(impl const&) = delete;
555 impl(impl&&) = delete;
556 impl& operator=(impl const&) = delete;
557 impl& operator=(impl&&) = delete;
558
559 explicit
560 2 impl(BS const& bs)
561 2 : it_(begin(bs))
562 4 , end_(end(bs))
563 {
564 2 ctx_ = this;
565 2 data_ = &data_impl;
566 2 consume_ = &consume_impl;
567 2 refill_window();
568 2 }
569
570 2 ~impl()
571 {
572 2 ctx_ = nullptr;
573 2 data_ = &data_after_destroy;
574 2 consume_ = &consume_after_destroy;
575 2 }
576 };
577
578 2 return impl(bs);
579 }
580
581 /** @copydoc make_buffer_param(BS const&)
582 @note Deleted overload to prevent passing temporary buffer sequences.
583 */
584 template<class BS>
585 requires MutableBufferSequence<std::remove_cvref_t<BS>> &&
586 (!std::is_lvalue_reference_v<BS>)
587 auto
588 make_buffer_param(BS&&) = delete;
589
590 } // namespace capy
591 } // namespace boost
592
593 #endif
594