TLA  Line data    Source code

       1                 : //
       2                 : // Copyright (c) 2026 Steve Gerbino
       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/corosio
       8                 : //
       9                 : 
      10                 : #ifndef BOOST_COROSIO_WAIT_TRAITS_HPP
      11                 : #define BOOST_COROSIO_WAIT_TRAITS_HPP
      12                 : 
      13                 : #include <boost/corosio/detail/config.hpp>
      14                 : 
      15                 : #include <concepts>
      16                 : 
      17                 : namespace boost::corosio {
      18                 : 
      19                 : /** Default wait traits for clock-based delays.
      20                 : 
      21                 :     Controls how much of the remaining time a single underlying
      22                 :     steady-clock wait may cover before `Clock::now()` is re-read.
      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
      25                 :     clock ) is observed. The default covers the full remaining
      26                 :     duration, which is exact for clocks that advance in lockstep
      27                 :     with the machine's monotonic clock.
      28                 : 
      29                 :     @par Example
      30                 :     @code
      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                 : 
      47                 :     @tparam Clock The clock type whose durations are converted.
      48                 : 
      49                 :     @see delay
      50                 : */
      51                 : template<class Clock>
      52                 : struct wait_traits
      53                 : {
      54                 :     /** Convert a remaining duration into a wait duration.
      55                 : 
      56                 :         Should return a positive duration when @p d is positive; a
      57                 :         non-positive result degrades to reactor-rate re-checking.
      58                 : 
      59                 :         @par Preconditions
      60                 :         Must not throw and must not block — invoked on the
      61                 :         io_context's run thread, including from the timer
      62                 :         completion path.
      63                 : 
      64                 :         @param d The remaining time until the deadline.
      65                 : 
      66                 :         @return The duration the next underlying wait may cover.
      67                 :     */
      68                 :     static typename Clock::duration
      69 HIT           5 :     to_wait_duration(typename Clock::duration d)
      70                 :     {
      71               5 :         return d;
      72                 :     }
      73                 : };
      74                 : 
      75                 : /** Concept for wait-traits policies usable with `Clock`.
      76                 : 
      77                 :     Satisfied when `Traits::to_wait_duration` accepts a
      78                 :     `Clock::duration` and returns something convertible back to it.
      79                 :     `Traits::to_wait_duration` must not throw.
      80                 : */
      81                 : template<class Traits, class Clock>
      82                 : concept WaitTraits = requires(typename Clock::duration d)
      83                 : {
      84                 :     { Traits::to_wait_duration(d) }
      85                 :         -> std::convertible_to<typename Clock::duration>;
      86                 : };
      87                 : 
      88                 : } // namespace boost::corosio
      89                 : 
      90                 : #endif