. /include/boost/corosio /wait_traits.hpp
100.00% Lines (2/2) 100.00% Functions (1/1)
[ ] prev/next file n p prev/next uncovered line
TLA Baseline Branch
Line Hits Code Line Hits Code
1   // 1   //
2   // Copyright (c) 2026 Steve Gerbino 2   // Copyright (c) 2026 Steve Gerbino
3   // Copyright (c) 2026 Michael Vandeberg 3   // Copyright (c) 2026 Michael Vandeberg
4   // 4   //
5   // Distributed under the Boost Software License, Version 1.0. (See accompanying 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) 6   // file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
7   // 7   //
8   // Official repository: https://github.com/cppalliance/corosio 8   // Official repository: https://github.com/cppalliance/corosio
9   // 9   //
10   10  
11   #ifndef BOOST_COROSIO_WAIT_TRAITS_HPP 11   #ifndef BOOST_COROSIO_WAIT_TRAITS_HPP
12   #define BOOST_COROSIO_WAIT_TRAITS_HPP 12   #define BOOST_COROSIO_WAIT_TRAITS_HPP
13   13  
14   #include <boost/corosio/detail/config.hpp> 14   #include <boost/corosio/detail/config.hpp>
15   15  
16   #include <concepts> 16   #include <concepts>
17   17  
18   namespace boost::corosio { 18   namespace boost::corosio {
19   19  
20 - /** Controls how much of the remaining time a single underlying 20 + /** Default wait traits for clock-based delays.
  21 +
  22 + Controls how much of the remaining time a single underlying
21   steady-clock wait may cover before `Clock::now()` is re-read. 23   steady-clock wait may cover before `Clock::now()` is re-read.
22   A larger value costs fewer wakeups; a smaller value bounds how 24   A larger value costs fewer wakeups; a smaller value bounds how
23   late an adjustment of `Clock` ( e.g. a stepped time-of-day 25   late an adjustment of `Clock` ( e.g. a stepped time-of-day
24   clock ) is observed. The default covers the full remaining 26   clock ) is observed. The default covers the full remaining
25   duration, which is exact for clocks that advance in lockstep 27   duration, which is exact for clocks that advance in lockstep
26   with the machine's monotonic clock. 28   with the machine's monotonic clock.
27   29  
28   @par Example 30   @par Example
29   @par !example capped_traits 31   @par !example capped_traits
30   32  
31   @tparam Clock The clock type whose durations are converted. 33   @tparam Clock The clock type whose durations are converted.
32   34  
33   @see delay 35   @see delay
34   */ 36   */
35   template<class Clock> 37   template<class Clock>
36   struct wait_traits 38   struct wait_traits
37   { 39   {
38   /** Convert a remaining duration into a wait duration. 40   /** Convert a remaining duration into a wait duration.
39   41  
40   Should return a positive duration when @p d is positive; a 42   Should return a positive duration when @p d is positive; a
41   non-positive result degrades to reactor-rate re-checking. 43   non-positive result degrades to reactor-rate re-checking.
42   44  
43 - @pre Must not throw and must not block — invoked on the 45 + @par Preconditions
44 - `io_context`'s run thread, including from the timer 46 + Must not throw and must not block — invoked on the
45 - completion path. 47 + io_context's run thread, including from the timer
  48 + completion path.
46   49  
47   @param d The remaining time until the deadline. 50   @param d The remaining time until the deadline.
48   51  
49   @return The duration the next underlying wait may cover. 52   @return The duration the next underlying wait may cover.
50   */ 53   */
HITCBC 51   5 static typename Clock::duration to_wait_duration(typename Clock::duration d) 54   5 static typename Clock::duration to_wait_duration(typename Clock::duration d)
52   { 55   {
HITCBC 53   5 return d; 56   5 return d;
54   } 57   }
55   }; 58   };
56   59  
57   /** Concept for wait-traits policies usable with `Clock`. 60   /** Concept for wait-traits policies usable with `Clock`.
58   61  
59   Satisfied when `Traits::to_wait_duration` accepts a 62   Satisfied when `Traits::to_wait_duration` accepts a
60   `Clock::duration` and returns something convertible back to it. 63   `Clock::duration` and returns something convertible back to it.
61 - `Traits::to_wait_duration` is expected not to throw; the 64 + `Traits::to_wait_duration` must not throw.
62 - requires-expression above does not enforce this.  
63   */ 65   */
64   template<class Traits, class Clock> 66   template<class Traits, class Clock>
65   concept WaitTraits = requires(typename Clock::duration d) { 67   concept WaitTraits = requires(typename Clock::duration d) {
66   { 68   {
67   Traits::to_wait_duration(d) 69   Traits::to_wait_duration(d)
68   } -> std::convertible_to<typename Clock::duration>; 70   } -> std::convertible_to<typename Clock::duration>;
69   }; 71   };
70   72  
71   } // namespace boost::corosio 73   } // namespace boost::corosio
72   74  
73   #endif 75   #endif