. /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   // 4   //
4   // Distributed under the Boost Software License, Version 1.0. (See accompanying 5   // 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   // file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
6   // 7   //
7   // Official repository: https://github.com/cppalliance/corosio 8   // Official repository: https://github.com/cppalliance/corosio
8   // 9   //
9   10  
10   #ifndef BOOST_COROSIO_WAIT_TRAITS_HPP 11   #ifndef BOOST_COROSIO_WAIT_TRAITS_HPP
11   #define BOOST_COROSIO_WAIT_TRAITS_HPP 12   #define BOOST_COROSIO_WAIT_TRAITS_HPP
12   13  
13   #include <boost/corosio/detail/config.hpp> 14   #include <boost/corosio/detail/config.hpp>
14   15  
15   #include <concepts> 16   #include <concepts>
16   17  
17   namespace boost::corosio { 18   namespace boost::corosio {
18   19  
19   /** Default wait traits for clock-based delays. 20   /** Default wait traits for clock-based delays.
20   21  
21   Controls how much of the remaining time a single underlying 22   Controls how much of the remaining time a single underlying
22   steady-clock wait may cover before `Clock::now()` is re-read. 23   steady-clock wait may cover before `Clock::now()` is re-read.
23   A larger value costs fewer wakeups; a smaller value bounds how 24   A larger value costs fewer wakeups; a smaller value bounds how
24   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
25   clock ) is observed. The default covers the full remaining 26   clock ) is observed. The default covers the full remaining
26   duration, which is exact for clocks that advance in lockstep 27   duration, which is exact for clocks that advance in lockstep
27   with the machine's monotonic clock. 28   with the machine's monotonic clock.
28   29  
29   @par Example 30   @par Example
30 - @code 31 + @par !example capped_traits
31 - // Observe wall-clock steps within one second  
32 - struct capped_traits  
33 - {  
34 - static std::chrono::system_clock::duration  
35 - to_wait_duration(std::chrono::system_clock::duration d)  
36 - {  
37 - return (std::min)(d,  
38 - std::chrono::system_clock::duration(  
39 - std::chrono::seconds(1)));  
40 - }  
41 - };  
42 -  
43 - auto [ec] = co_await delay<capped_traits>(  
44 - std::chrono::system_clock::now() + std::chrono::hours(1));  
45 - @endcode  
46   32  
47   @tparam Clock The clock type whose durations are converted. 33   @tparam Clock The clock type whose durations are converted.
48   34  
49   @see delay 35   @see delay
50   */ 36   */
51   template<class Clock> 37   template<class Clock>
52   struct wait_traits 38   struct wait_traits
53   { 39   {
54   /** Convert a remaining duration into a wait duration. 40   /** Convert a remaining duration into a wait duration.
55   41  
56   Should return a positive duration when @p d is positive; a 42   Should return a positive duration when @p d is positive; a
57   non-positive result degrades to reactor-rate re-checking. 43   non-positive result degrades to reactor-rate re-checking.
58   44  
59   @par Preconditions 45   @par Preconditions
60   Must not throw and must not block — invoked on the 46   Must not throw and must not block — invoked on the
61   io_context's run thread, including from the timer 47   io_context's run thread, including from the timer
62   completion path. 48   completion path.
63   49  
64   @param d The remaining time until the deadline. 50   @param d The remaining time until the deadline.
65   51  
66   @return The duration the next underlying wait may cover. 52   @return The duration the next underlying wait may cover.
67   */ 53   */
68   static typename Clock::duration 54   static typename Clock::duration
HITCBC 69   5 to_wait_duration(typename Clock::duration d) 55   5 to_wait_duration(typename Clock::duration d)
70   { 56   {
HITCBC 71   5 return d; 57   5 return d;
72   } 58   }
73   }; 59   };
74   60  
75   /** Concept for wait-traits policies usable with `Clock`. 61   /** Concept for wait-traits policies usable with `Clock`.
76   62  
77   Satisfied when `Traits::to_wait_duration` accepts a 63   Satisfied when `Traits::to_wait_duration` accepts a
78   `Clock::duration` and returns something convertible back to it. 64   `Clock::duration` and returns something convertible back to it.
79   `Traits::to_wait_duration` must not throw. 65   `Traits::to_wait_duration` must not throw.
80   */ 66   */
81   template<class Traits, class Clock> 67   template<class Traits, class Clock>
82   concept WaitTraits = requires(typename Clock::duration d) 68   concept WaitTraits = requires(typename Clock::duration d)
83   { 69   {
84   { Traits::to_wait_duration(d) } 70   { Traits::to_wait_duration(d) }
85   -> std::convertible_to<typename Clock::duration>; 71   -> std::convertible_to<typename Clock::duration>;
86   }; 72   };
87   73  
88   } // namespace boost::corosio 74   } // namespace boost::corosio
89   75  
90   #endif 76   #endif