1 - 
//
 
2 - 
// Copyright (c) 2026 Michael Vandeberg
 
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/capy
 
8 - 
//
 
9 -
 
10 - 
#ifndef BOOST_CAPY_TIMEOUT_HPP
 
11 - 
#define BOOST_CAPY_TIMEOUT_HPP
 
12 -
 
13 - 
#include <boost/capy/detail/config.hpp>
 
14 - 
#include <boost/capy/concept/io_awaitable.hpp>
 
15 - 
#include <boost/capy/delay.hpp>
 
16 - 
#include <boost/capy/error.hpp>
 
17 - 
#include <boost/capy/io_result.hpp>
 
18 - 
#include <boost/capy/task.hpp>
 
19 - 
#include <boost/capy/when_any.hpp>
 
20 -
 
21 - 
#include <chrono>
 
22 - 
#include <system_error>
 
23 - 
#include <type_traits>
 
24 -
 
25 - 
namespace boost {
 
26 - 
namespace capy {
 
27 -
 
28 - 
namespace detail {
 
29 -
 
30 - 
template<typename T>
 
31 - 
struct is_io_result : std::false_type {};
 
32 -
 
33 - 
template<typename... Args>
 
34 - 
struct is_io_result<io_result<Args...>> : std::true_type {};
 
35 -
 
36 - 
template<typename T>
 
37 - 
inline constexpr bool is_io_result_v = is_io_result<T>::value;
 
38 -
 
39 - 
} // detail
 
40 -
 
41 - 
/** Race an awaitable against a deadline.
 
42 -
 
43 - 
    Starts the awaitable and a timer concurrently. If the
 
44 - 
    awaitable completes first, its result is returned. If the
 
45 - 
    timer fires first, stop is requested for the awaitable and
 
46 - 
    a timeout error is produced.
 
47 -
 
48 - 
    @par Return Type
 
49 -
 
50 - 
    The return type matches the inner awaitable's result type:
 
51 -
 
52 - 
    @li For `io_result<...>` types: returns `io_result` with
 
53 - 
        `ec == error::timeout` and default-initialized values
 
54 - 
    @li For non-void types: throws `std::system_error(error::timeout)`
 
55 - 
    @li For void: throws `std::system_error(error::timeout)`
 
56 -
 
57 - 
    @par Precision
 
58 -
 
59 - 
    The timeout fires at or after the specified duration.
 
60 -
 
61 - 
    @par Cancellation
 
62 -
 
63 - 
    If the parent's stop token is activated, the inner awaitable
 
64 - 
    is cancelled normally (not a timeout). The result reflects
 
65 - 
    the inner awaitable's cancellation behavior.
 
66 -
 
67 - 
    @par Example
 
68 - 
    @code
 
69 - 
    auto [ec, n] = co_await timeout(sock.read_some(buf), 50ms);
 
70 - 
    if (ec == cond::timeout) {
 
71 - 
        // handle timeout
 
72 - 
    }
 
73 - 
    @endcode
 
74 -
 
75 - 
    @tparam A An IoAwaitable whose result type determines
 
76 - 
        how timeouts are reported.
 
77 -
 
78 - 
    @param a The awaitable to race against the deadline.
 
79 - 
    @param dur The maximum duration to wait.
 
80 -
 
81 - 
    @return `task<awaitable_result_t<A>>`.
 
82 -
 
83 - 
    @throws std::system_error with `error::timeout` if the timer
 
84 - 
        fires first and the result type is not `io_result`.
 
85 - 
        Exceptions thrown by the inner awaitable propagate
 
86 - 
        unchanged.
 
87 -
 
88 - 
    @see delay, when_any, cond::timeout
 
89 - 
*/
 
90 - 
template<IoAwaitable A, typename Rep, typename Period>
 
91 - 
auto timeout(A a, std::chrono::duration<Rep, Period> dur)
 
92 - 
    -> task<awaitable_result_t<A>>
 
93 - 
{
 
94 - 
    using T = awaitable_result_t<A>;
 
95 -
 
96 - 
    auto result = co_await when_any(
 
97 - 
        std::move(a), delay(dur));
 
98 -
 
99 - 
    if(result.index() == 0)
 
100 - 
    {
 
101 - 
        // Task completed first
 
102 - 
        if constexpr (std::is_void_v<T>)
 
103 - 
            co_return;
 
104 - 
        else
 
105 - 
            co_return std::get<0>(std::move(result));
 
106 - 
    }
 
107 - 
    else
 
108 - 
    {
 
109 - 
        // Timer won
 
110 - 
        if constexpr (detail::is_io_result_v<T>)
 
111 - 
        {
 
112 - 
            T timeout_result{};
 
113 - 
            timeout_result.ec = make_error_code(error::timeout);
 
114 - 
            co_return timeout_result;
 
115 - 
        }
 
116 - 
        else if constexpr (std::is_void_v<T>)
 
117 - 
        {
 
118 - 
            throw std::system_error(
 
119 - 
                make_error_code(error::timeout));
 
120 - 
        }
 
121 - 
        else
 
122 - 
        {
 
123 - 
            throw std::system_error(
 
124 - 
                make_error_code(error::timeout));
 
125 - 
        }
 
126 - 
    }
 
127 - 
}
 
128 -
 
129 - 
} // capy
 
130 - 
} // boost
 
131 -
 
132 - 
#endif