. /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 + //
  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
HITGNC   69 + 5 to_wait_duration(typename Clock::duration d)
  70 + {
HITGNC   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