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