include/boost/corosio/detail/cancel_at_awaitable.hpp

94.5% Lines (52/55) 90.6% List of functions (29/32) 50.0% Branches (19/38)

[ ] prev/next file n p prev/next uncovered line

cancel_at_awaitable.hpp

f(x) Functions (32)

Function Calls Lines Branches Blocks

Line	Branch	Hits	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_DETAIL_CANCEL_AT_AWAITABLE_HPP
11			#define BOOST_COROSIO_DETAIL_CANCEL_AT_AWAITABLE_HPP
12
13			#include <boost/corosio/detail/timeout_coro.hpp>
14			#include <boost/corosio/detail/except.hpp>
15			#include <boost/capy/ex/io_env.hpp>
16
17			#include <chrono>
18			#include <coroutine>
19			#include <new>
20			#include <optional>
21			#include <stdexcept>
22			#include <stop_token>
23			#include <type_traits>
24			#include <utility>
25
26			/* Races an inner IoAwaitable against a timer via a shared
27			stop_source. await_suspend arms the timer by launching a
28			fire-and-forget timeout_coro, then starts the inner op with
29			an interposed stop_token. Whichever completes first signals
30			the stop_source, cancelling the other.
31
32			Parent cancellation is forwarded through a stop_callback
33			stored in a placement-new buffer (stop_callback is not
34			movable, but the awaitable must be movable for
35			transform_awaiter). The buffer is inert during moves
36			(before await_suspend) and constructed in-place once the
37			awaitable is pinned on the coroutine frame.
38
39			The timeout_coro can outlive this awaitable — it owns its
40			env and self-destroys via suspend_never. When Owning is
41			false the caller-supplied timer must outlive both; when
42			Owning is true the timer lives in std::optional and is
43			constructed lazily in await_suspend. */
44
45			namespace boost::corosio::detail {
46
47			/** Awaitable adapter that cancels an inner operation after a deadline.
48
49			Races the inner awaitable against a timer. A shared stop_source
50			ties them together: whichever completes first cancels the other.
51			Parent cancellation is forwarded via stop_callback.
52
53			When @p Owning is `false` (default), the caller supplies a timer
54			reference that must outlive the awaitable. When @p Owning is
55			`true`, the timer is constructed internally in `await_suspend`
56			from the execution context in `io_env`.
57
58			@tparam A The inner IoAwaitable type (decayed).
59			@tparam Timer The timer type (`timer` or `native_timer<B>`).
60			@tparam Owning When `true`, the awaitable owns its timer.
61			*/
62			template<typename A, typename Timer, bool Owning = false>
63			struct cancel_at_awaitable
64			{
65			struct stop_forwarder
66			{
67			std::stop_source* src_;
68		2x	void operator()() const noexcept
69			{
70		2x	src_->request_stop();
71		2x	}
72			};
73
74			using time_point = std::chrono::steady_clock::time_point;
75			using stop_cb_type = std::stop_callback<stop_forwarder>;
76			using timer_storage =
77			std::conditional_t<Owning, std::optional<Timer>, Timer*>;
78
79			A inner_;
80			timer_storage timer_;
81			time_point deadline_;
82			std::stop_source stop_src_;
83			capy::io_env inner_env_;
84			alignas(stop_cb_type) unsigned char cb_buf_[sizeof(stop_cb_type)];
85		60x	bool cb_active_ = false;
86
87			/// Construct with a caller-supplied timer reference.
88	2/4 ✓ Branch 0 taken 18 times. ✗ Branch 1 not taken. ✓ Branch 2 taken 18 times. ✗ Branch 3 not taken.	54x	cancel_at_awaitable(A&& inner, Timer& timer, time_point deadline)
89			requires(!Owning)
90		18x	: inner_(std::move(inner))
91		18x	, timer_(&timer)
92		18x	, deadline_(deadline)
93		18x	{
94		36x	}
95
96			/// Construct without a timer (created in `await_suspend`).
97	6/12 ✓ Branch 0 taken 9 times. ✗ Branch 1 not taken. ✓ Branch 2 taken 9 times. ✗ Branch 3 not taken. ✓ Branch 4 taken 9 times. ✗ Branch 5 not taken. ✓ Branch 6 taken 3 times. ✗ Branch 7 not taken. ✓ Branch 8 taken 3 times. ✗ Branch 9 not taken. ✓ Branch 10 taken 3 times. ✗ Branch 11 not taken.	48x	cancel_at_awaitable(A&& inner, time_point deadline)
98			requires Owning
99		12x	: inner_(std::move(inner))
100		12x	, deadline_(deadline)
101		12x	{
102		24x	}
103
104		120x	~cancel_at_awaitable()
105		60x	{
106		60x	destroy_parent_cb();
107		120x	}
108
109			// Only moved before await_suspend, when cb_active_ is false
110		90x	cancel_at_awaitable(cancel_at_awaitable&& o) noexcept(
111			std::is_nothrow_move_constructible_v<A>)
112		30x	: inner_(std::move(o.inner_))
113		30x	, timer_(std::move(o.timer_))
114		30x	, deadline_(o.deadline_)
115		30x	, stop_src_(std::move(o.stop_src_))
116		30x	{
117		60x	}
118
119			cancel_at_awaitable(cancel_at_awaitable const&) = delete;
120			cancel_at_awaitable& operator=(cancel_at_awaitable const&) = delete;
121			cancel_at_awaitable& operator=(cancel_at_awaitable&&) = delete;
122
123		30x	bool await_ready() const noexcept
124			{
125		30x	return false;
126			}
127
128		30x	auto await_suspend(std::coroutine_handle<> h, capy::io_env const* env)
129			{
130			if constexpr (Owning)
131			{
132			// The deadline timer is built here from the awaiting
133			// coroutine's executor context, the first point at which it
134			// is known. await_suspend is driven through a noexcept
135			// wrapper, so a failure cannot be surfaced as a catchable
136			// exception. An executor whose context is not an io_context
137			// cannot supply a timer service; silently running the
138			// operation with no deadline would be a worse failure than
139			// aborting, so translate the service-lookup error into a
140			// clear precondition diagnostic. This terminates by design
141			// (a usage error) rather than dropping the requested timeout.
142			try
143			{
144	2/4 ✓ Branch 0 taken 9 times. ✗ Branch 1 not taken. ✓ Branch 2 taken 3 times. ✗ Branch 3 not taken.	12x	timer_.emplace(env->executor.context());
145		12x	}
146			catch (std::logic_error const&)
147			{
148		✗	throw_logic_error(
149			"cancel_after/cancel_at requires an "
150			"io_context-backed executor");
151		✗	}
152			}
153
154		30x	timer_->expires_at(deadline_);
155
156			// Launch fire-and-forget timeout (starts suspended)
157	3/6 ✓ Branch 0 taken 21 times. ✗ Branch 1 not taken. ✓ Branch 2 taken 3 times. ✓ Branch 2 taken 6 times. ✗ Branch 3 not taken. ✗ Branch 3 not taken.	30x	auto timeout = make_timeout(*timer_, stop_src_);
158	2/4 ✓ Branch 0 taken 21 times. ✗ Branch 1 not taken. ✓ Branch 2 taken 21 times. ✗ Branch 3 not taken.	60x	timeout.h_.promise().set_env_owned(
159		30x	{env->executor, stop_src_.get_token(), env->frame_allocator});
160			// Runs synchronously until timer.wait() suspends
161		30x	timeout.h_.resume();
162			// timeout goes out of scope; destructor is a no-op,
163			// the coroutine self-destroys via suspend_never
164
165			// Forward parent cancellation
166		30x	new (cb_buf_) stop_cb_type(env->stop_token, stop_forwarder{&stop_src_});
167		30x	cb_active_ = true;
168
169			// Start the inner op with our interposed stop_token
170		120x	inner_env_ = {
171		90x	env->executor, stop_src_.get_token(), env->frame_allocator};
172		30x	return inner_.await_suspend(h, &inner_env_);
173		✗	}
174
175		30x	decltype(auto) await_resume()
176			{
177			// Cancel whichever is still pending (idempotent)
178		30x	stop_src_.request_stop();
179		30x	destroy_parent_cb();
180		30x	return inner_.await_resume();
181			}
182
183		90x	void destroy_parent_cb() noexcept
184			{
185	4/4 ✓ Branch 0 taken 42 times. ✓ Branch 1 taken 21 times. ✓ Branch 2 taken 18 times. ✓ Branch 3 taken 9 times.	90x	if (cb_active_)
186			{
187		30x	std::launder(reinterpret_cast<stop_cb_type*>(cb_buf_))
188		30x	->~stop_cb_type();
189		30x	cb_active_ = false;
190		30x	}
191		90x	}
192			};
193
194			} // namespace boost::corosio::detail
195
196			#endif
197