include/boost/corosio/connect.hpp

90.2% Lines (46/51) 100.0% List of functions (9/9) 44.3% Branches (131/296)

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

connect.hpp

f(x) Functions (9)

Function Calls Lines Branches Blocks

Line	Branch	Hits	Source Code
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/corosio
8			//
9
10			#ifndef BOOST_COROSIO_CONNECT_HPP
11			#define BOOST_COROSIO_CONNECT_HPP
12
13			#include <boost/corosio/detail/config.hpp>
14
15			#include <boost/capy/cond.hpp>
16			#include <boost/capy/io_result.hpp>
17			#include <boost/capy/task.hpp>
18
19			#include <concepts>
20			#include <iterator>
21			#include <ranges>
22			#include <system_error>
23			#include <utility>
24
25			/*
26			Range-based composed connect operation.
27
28			These free functions try each endpoint in a range (or iterator pair)
29			in order, returning on the first successful connect. Between attempts
30			the socket is closed so that the next attempt can auto-open with the
31			correct address family (e.g. going from IPv4 to IPv6 candidates).
32
33			The iteration semantics follow Boost.Asio's range/iterator async_connect:
34			on success, the successful endpoint (or its iterator) is returned; on
35			all-fail, the last attempt's error code is returned; on an empty range
36			(or when a connect_condition rejects every candidate),
37			std::errc::no_such_device_or_address is returned, matching the error
38			the resolver uses for "no results" in posix_resolver_service.
39
40			The operation is a plain coroutine; cancellation is propagated to the
41			inner per-endpoint connect via the affine awaitable protocol on io_env.
42			*/
43
44			namespace boost::corosio {
45
46			namespace detail {
47
48			/* Always-true connect condition used by the overloads that take no
49			user-supplied predicate. Kept at namespace-detail scope so it has a
50			stable linkage name across translation units. */
51			struct default_connect_condition
52			{
53			template<class Endpoint>
54		20x	bool operator()(std::error_code const&, Endpoint const&) const noexcept
55			{
56		20x	return true;
57			}
58			};
59
60			} // namespace detail
61
62			/* Forward declarations so the non-condition overloads can delegate
63			to the condition overloads via qualified lookup (qualified calls
64			bind to the overload set visible at definition, not instantiation). */
65
66			template<class Socket, std::ranges::input_range Range, class ConnectCondition>
67			requires std::convertible_to<
68			std::ranges::range_reference_t<Range>,
69			typename Socket::endpoint_type> &&
70			std::predicate<
71			ConnectCondition&,
72			std::error_code const&,
73			typename Socket::endpoint_type const&>
74			capy::task<capy::io_result<typename Socket::endpoint_type>>
75			connect(Socket& s, Range endpoints, ConnectCondition cond);
76
77			template<class Socket, std::input_iterator Iter, class ConnectCondition>
78			requires std::convertible_to<
79			std::iter_reference_t<Iter>,
80			typename Socket::endpoint_type> &&
81			std::predicate<
82			ConnectCondition&,
83			std::error_code const&,
84			typename Socket::endpoint_type const&>
85			capy::task<capy::io_result<Iter>>
86			connect(Socket& s, Iter begin, Iter end, ConnectCondition cond);
87
88			/** Asynchronously connect a socket by trying each endpoint in a range.
89
90			Each candidate is tried in order. Before each attempt the socket is
91			closed (so the next `connect` auto-opens with the candidate's
92			address family). On first successful connect, the operation
93			completes with the connected endpoint.
94
95			@par Cancellation
96			Supports cancellation via the affine awaitable protocol. If a
97			per-endpoint connect completes with `capy::cond::canceled` the
98			operation completes immediately with that error and does not try
99			further endpoints.
100
101			@param s The socket to connect. Must have a `connect(endpoint)`
102			member returning an awaitable, plus `close()` and `is_open()`.
103			If the socket is already open, it will be closed before the
104			first attempt.
105			@param endpoints A range of candidate endpoints. Taken by value
106			so temporaries (e.g. `resolver_results` returned from
107			`resolver::resolve`) remain alive for the coroutine's lifetime.
108			Because the range is owned by the coroutine, passing an lvalue
109			copies it; since `resolver_results` is a
110			`std::vector<resolver_entry>`, that is a deep copy of every entry.
111			Pass an rvalue (`std::move(results)`) or use the iterator overload
112			(`connect(s, results.begin(), results.end())`) to avoid the copy.
113
114			@return An awaitable completing with
115			`capy::io_result<typename Socket::endpoint_type>`:
116			- on success: default error_code and the connected endpoint;
117			- on failure of all attempts: the error from the last attempt
118			and a default-constructed endpoint;
119			- on empty range: `std::errc::no_such_device_or_address` and a
120			default-constructed endpoint.
121
122			@note The socket is closed and re-opened before each attempt, so
123			any socket options set by the caller (e.g. `no_delay`,
124			`reuse_address`) are lost. Apply options after this operation
125			completes.
126
127			If auto-opening the socket fails during an attempt, that attempt
128			completes with the open error (inherits the contract of
129			`Socket::connect`).
130
131			@par Example
132			@code
133			resolver r(ioc);
134			auto [rec, results] = co_await r.resolve("www.boost.org", "80");
135			if (rec) co_return;
136			tcp_socket s(ioc);
137			auto [cec, ep] = co_await corosio::connect(s, results);
138			@endcode
139			*/
140			template<class Socket, std::ranges::input_range Range>
141			requires std::convertible_to<
142			std::ranges::range_reference_t<Range>,
143			typename Socket::endpoint_type>
144			capy::task<capy::io_result<typename Socket::endpoint_type>>
145		12x	connect(Socket& s, Range endpoints)
146			{
147	1/2 ✓ Branch 0 taken 12 times. ✗ Branch 1 not taken.	12x	return corosio::connect(
148		12x	s, std::move(endpoints), detail::default_connect_condition{});
149		✗	}
150
151			/** Asynchronously connect a socket by trying each endpoint in a range,
152			filtered by a user-supplied condition.
153
154			For each candidate the condition is invoked as
155			`cond(last_ec, ep)` where `last_ec` is the error from the most
156			recent attempt (default-constructed before the first attempt). If
157			the condition returns `false` the candidate is skipped; otherwise a
158			connect is attempted.
159
160			@param s The socket to connect. See the non-condition overload for
161			requirements.
162			@param endpoints A range of candidate endpoints, taken by value. See
163			the non-condition overload for the deep-copy caveat when passing
164			an lvalue `resolver_results`.
165			@param cond A predicate invocable with
166			`(std::error_code const&, typename Socket::endpoint_type const&)`
167			returning a value contextually convertible to `bool`.
168
169			@return Same as the non-condition overload. If every candidate is
170			rejected, completes with `std::errc::no_such_device_or_address`.
171
172			If auto-opening the socket fails, the attempt completes with the
173			open error.
174			*/
175			template<class Socket, std::ranges::input_range Range, class ConnectCondition>
176			requires std::convertible_to<
177			std::ranges::range_reference_t<Range>,
178			typename Socket::endpoint_type> &&
179			std::predicate<
180			ConnectCondition&,
181			std::error_code const&,
182			typename Socket::endpoint_type const&>
183			capy::task<capy::io_result<typename Socket::endpoint_type>>
184	46/120 ✓ Branch 0 taken 12 times. ✗ Branch 1 not taken. ✓ Branch 2 taken 12 times. ✗ Branch 3 not taken. ✓ Branch 4 taken 12 times. ✗ Branch 5 not taken. ✗ Branch 6 not taken. ✓ Branch 7 taken 12 times. ✗ Branch 8 not taken. ✗ Branch 9 not taken. ✓ Branch 10 taken 12 times. ✗ Branch 11 not taken. ✗ Branch 12 not taken. ✗ Branch 13 not taken. ✓ Branch 14 taken 12 times. ✓ Branch 15 taken 12 times. ✓ Branch 16 taken 12 times. ✗ Branch 17 not taken. ✓ Branch 18 taken 16 times. ✓ Branch 19 taken 12 times. ✗ Branch 20 not taken. ✗ Branch 21 not taken. ✗ Branch 22 not taken. ✗ Branch 23 not taken. ✓ Branch 24 taken 1 time. ✗ Branch 25 not taken. ✓ Branch 26 taken 1 time. ✗ Branch 27 not taken. ✓ Branch 28 taken 1 time. ✗ Branch 29 not taken. ✗ Branch 30 not taken. ✓ Branch 31 taken 1 time. ✗ Branch 32 not taken. ✗ Branch 33 not taken. ✓ Branch 34 taken 1 time. ✗ Branch 35 not taken. ✗ Branch 36 not taken. ✗ Branch 37 not taken. ✓ Branch 38 taken 1 time. ✓ Branch 39 taken 1 time. ✓ Branch 40 taken 1 time. ✗ Branch 41 not taken. ✗ Branch 42 not taken. ✓ Branch 43 taken 1 time. ✗ Branch 44 not taken. ✗ Branch 45 not taken. ✗ Branch 46 not taken. ✗ Branch 47 not taken. ✓ Branch 48 taken 1 time. ✗ Branch 49 not taken. ✓ Branch 50 taken 1 time. ✗ Branch 51 not taken. ✓ Branch 52 taken 1 time. ✗ Branch 53 not taken. ✗ Branch 54 not taken. ✓ Branch 55 taken 1 time. ✗ Branch 56 not taken. ✗ Branch 57 not taken. ✓ Branch 58 taken 1 time. ✗ Branch 59 not taken. ✗ Branch 60 not taken. ✗ Branch 61 not taken. ✓ Branch 62 taken 1 time. ✓ Branch 63 taken 1 time. ✓ Branch 64 taken 1 time. ✗ Branch 65 not taken. ✗ Branch 66 not taken. ✓ Branch 67 taken 1 time. ✗ Branch 68 not taken. ✗ Branch 69 not taken. ✗ Branch 70 not taken. ✗ Branch 71 not taken. ✓ Branch 72 taken 1 time. ✗ Branch 73 not taken. ✓ Branch 74 taken 1 time. ✗ Branch 75 not taken. ✓ Branch 76 taken 1 time. ✗ Branch 77 not taken. ✗ Branch 78 not taken. ✓ Branch 79 taken 1 time. ✗ Branch 80 not taken. ✗ Branch 81 not taken. ✓ Branch 82 taken 1 time. ✗ Branch 83 not taken. ✗ Branch 84 not taken. ✗ Branch 85 not taken. ✓ Branch 86 taken 1 time. ✓ Branch 87 taken 1 time. ✓ Branch 88 taken 1 time. ✗ Branch 89 not taken. ✗ Branch 90 not taken. ✓ Branch 91 taken 1 time. ✗ Branch 92 not taken. ✗ Branch 93 not taken. ✗ Branch 94 not taken. ✗ Branch 95 not taken. ✓ Branch 96 taken 1 time. ✗ Branch 97 not taken. ✓ Branch 98 taken 1 time. ✗ Branch 99 not taken. ✓ Branch 100 taken 1 time. ✗ Branch 101 not taken. ✗ Branch 102 not taken. ✓ Branch 103 taken 1 time. ✗ Branch 104 not taken. ✗ Branch 105 not taken. ✓ Branch 106 taken 1 time. ✗ Branch 107 not taken. ✗ Branch 108 not taken. ✗ Branch 109 not taken. ✓ Branch 110 taken 1 time. ✓ Branch 111 taken 1 time. ✓ Branch 112 taken 1 time. ✗ Branch 113 not taken. ✗ Branch 114 not taken. ✓ Branch 115 taken 1 time. ✗ Branch 116 not taken. ✗ Branch 117 not taken. ✗ Branch 118 not taken. ✗ Branch 119 not taken.	80x	connect(Socket& s, Range endpoints, ConnectCondition cond)
185		16x	{
186			using endpoint_type = typename Socket::endpoint_type;
187
188		16x	std::error_code last_ec;
189
190	12/16 ✓ Branch 0 taken 4 times. ✓ Branch 1 taken 48 times. ✓ Branch 2 taken 24 times. ✓ Branch 3 taken 4 times. ✓ Branch 4 taken 1 time. ✓ Branch 5 taken 1 time. ✗ Branch 6 not taken. ✓ Branch 7 taken 2 times. ✓ Branch 8 taken 1 time. ✗ Branch 9 not taken. ✓ Branch 10 taken 1 time. ✓ Branch 11 taken 1 time. ✗ Branch 12 not taken. ✓ Branch 13 taken 2 times. ✓ Branch 14 taken 1 time. ✗ Branch 15 not taken.	86x	for (auto&& e : endpoints)
191			{
192		54x	endpoint_type ep = e;
193
194	7/10 ✓ Branch 0 taken 48 times. ✗ Branch 1 not taken. ✓ Branch 2 taken 2 times. ✗ Branch 3 not taken. ✓ Branch 4 taken 1 time. ✓ Branch 5 taken 1 time. ✓ Branch 6 taken 2 times. ✗ Branch 7 not taken. ✓ Branch 8 taken 1 time. ✓ Branch 9 taken 1 time.	52x	if (!cond(static_cast<std::error_code const&>(last_ec),
195			static_cast<endpoint_type const&>(ep)))
196		2x	continue;
197
198	4/6 ✓ Branch 0 taken 42 times. ✓ Branch 1 taken 6 times. ✓ Branch 2 taken 1 time. ✗ Branch 3 not taken. ✓ Branch 4 taken 1 time. ✗ Branch 5 not taken.	50x	if (s.is_open())
199		6x	s.close();
200
201	14/34 ✗ Branch 0 not taken. ✓ Branch 1 taken 48 times. ✗ Branch 2 not taken. ✓ Branch 3 taken 48 times. ✓ Branch 4 taken 16 times. ✓ Branch 5 taken 32 times. ✗ Branch 6 not taken. ✓ Branch 7 taken 16 times. ✗ Branch 8 not taken. ✗ Branch 9 not taken. ✓ Branch 10 taken 16 times. ✓ Branch 11 taken 16 times. ✗ Branch 12 not taken. ✓ Branch 13 taken 16 times. ✗ Branch 14 not taken. ✓ Branch 15 taken 1 time. ✓ Branch 16 taken 1 time. ✗ Branch 17 not taken. ✗ Branch 18 not taken. ✗ Branch 19 not taken. ✗ Branch 20 not taken. ✗ Branch 21 not taken. ✗ Branch 22 not taken. ✓ Branch 23 taken 1 time. ✗ Branch 24 not taken. ✓ Branch 25 taken 1 time. ✓ Branch 26 taken 1 time. ✗ Branch 27 not taken. ✗ Branch 28 not taken. ✗ Branch 29 not taken. ✗ Branch 30 not taken. ✗ Branch 31 not taken. ✗ Branch 32 not taken. ✓ Branch 33 taken 1 time.	50x	auto [ec] = co_await s.connect(ep);
202
203	4/6 ✓ Branch 0 taken 10 times. ✓ Branch 1 taken 6 times. ✗ Branch 2 not taken. ✓ Branch 3 taken 1 time. ✗ Branch 4 not taken. ✓ Branch 5 taken 1 time.	18x	if (!ec)
204	3/6 ✓ Branch 0 taken 6 times. ✗ Branch 1 not taken. ✓ Branch 2 taken 1 time. ✗ Branch 3 not taken. ✓ Branch 4 taken 1 time. ✗ Branch 5 not taken.	8x	co_return {std::error_code{}, std::move(ep)};
205
206	2/6 ✓ Branch 0 taken 2 times. ✓ Branch 1 taken 8 times. ✗ Branch 2 not taken. ✗ Branch 3 not taken. ✗ Branch 4 not taken. ✗ Branch 5 not taken.	10x	if (ec == capy::cond::canceled)
207	2/12 ✓ Branch 0 taken 2 times. ✗ Branch 1 not taken. ✓ Branch 2 taken 2 times. ✗ Branch 3 not taken. ✗ Branch 4 not taken. ✗ Branch 5 not taken. ✗ Branch 6 not taken. ✗ Branch 7 not taken. ✗ Branch 8 not taken. ✗ Branch 9 not taken. ✗ Branch 10 not taken. ✗ Branch 11 not taken.	4x	co_return {ec, endpoint_type{}};
208
209		8x	last_ec = ec;
210		22x	}
211
212	4/10 ✓ Branch 0 taken 2 times. ✓ Branch 1 taken 2 times. ✗ Branch 2 not taken. ✓ Branch 3 taken 1 time. ✗ Branch 4 not taken. ✗ Branch 5 not taken. ✗ Branch 6 not taken. ✓ Branch 7 taken 1 time. ✗ Branch 8 not taken. ✗ Branch 9 not taken.	6x	if (!last_ec)
213		4x	last_ec = std::make_error_code(std::errc::no_such_device_or_address);
214
215	3/10 ✓ Branch 0 taken 4 times. ✗ Branch 1 not taken. ✓ Branch 2 taken 1 time. ✗ Branch 3 not taken. ✗ Branch 4 not taken. ✗ Branch 5 not taken. ✓ Branch 6 taken 1 time. ✗ Branch 7 not taken. ✗ Branch 8 not taken. ✗ Branch 9 not taken.	6x	co_return {last_ec, endpoint_type{}};
216		64x	}
217
218			/** Asynchronously connect a socket by trying each endpoint in an
219			iterator range.
220
221			Behaves like the range overload, except the return value carries
222			the iterator to the successfully connected endpoint on success, or
223			`end` on failure. This mirrors Boost.Asio's iterator-based
224			`async_connect`.
225
226			@param s The socket to connect.
227			@param begin The first candidate.
228			@param end One past the last candidate.
229
230			@return An awaitable completing with `capy::io_result<Iter>`:
231			- on success: default error_code and the iterator of the
232			successful endpoint;
233			- on failure of all attempts: the error from the last attempt
234			and `end`;
235			- on empty range: `std::errc::no_such_device_or_address` and
236			`end`.
237
238			If auto-opening the socket fails, the attempt completes with the
239			open error.
240			*/
241			template<class Socket, std::input_iterator Iter>
242			requires std::convertible_to<
243			std::iter_reference_t<Iter>,
244			typename Socket::endpoint_type>
245			capy::task<capy::io_result<Iter>>
246		4x	connect(Socket& s, Iter begin, Iter end)
247			{
248		4x	return corosio::connect(
249		4x	s,
250		4x	std::move(begin),
251		4x	std::move(end),
252			detail::default_connect_condition{});
253			}
254
255			/** Asynchronously connect a socket by trying each endpoint in an
256			iterator range, filtered by a user-supplied condition.
257
258			@param s The socket to connect.
259			@param begin The first candidate.
260			@param end One past the last candidate.
261			@param cond A predicate invocable with
262			`(std::error_code const&, typename Socket::endpoint_type const&)`.
263
264			@return Same as the plain iterator overload. If every candidate is
265			rejected, completes with `std::errc::no_such_device_or_address`.
266
267			If auto-opening the socket fails, the attempt completes with the
268			open error.
269			*/
270			template<class Socket, std::input_iterator Iter, class ConnectCondition>
271			requires std::convertible_to<
272			std::iter_reference_t<Iter>,
273			typename Socket::endpoint_type> &&
274			std::predicate<
275			ConnectCondition&,
276			std::error_code const&,
277			typename Socket::endpoint_type const&>
278			capy::task<capy::io_result<Iter>>
279	10/24 ✓ Branch 0 taken 4 times. ✗ Branch 1 not taken. ✓ Branch 2 taken 4 times. ✗ Branch 3 not taken. ✓ Branch 4 taken 4 times. ✗ Branch 5 not taken. ✗ Branch 6 not taken. ✓ Branch 7 taken 4 times. ✗ Branch 8 not taken. ✗ Branch 9 not taken. ✓ Branch 10 taken 4 times. ✗ Branch 11 not taken. ✗ Branch 12 not taken. ✗ Branch 13 not taken. ✓ Branch 14 taken 4 times. ✓ Branch 15 taken 4 times. ✓ Branch 16 taken 4 times. ✗ Branch 17 not taken. ✓ Branch 18 taken 4 times. ✓ Branch 19 taken 4 times. ✗ Branch 20 not taken. ✗ Branch 21 not taken. ✗ Branch 22 not taken. ✗ Branch 23 not taken.	20x	connect(Socket& s, Iter begin, Iter end, ConnectCondition cond)
280		4x	{
281			using endpoint_type = typename Socket::endpoint_type;
282
283		4x	std::error_code last_ec;
284
285	4/4 ✓ Branch 0 taken 2 times. ✓ Branch 1 taken 12 times. ✓ Branch 2 taken 6 times. ✓ Branch 3 taken 2 times.	20x	for (Iter it = begin; it != end; ++it)
286			{
287		12x	endpoint_type ep = *it;
288
289	1/2 ✓ Branch 0 taken 12 times. ✗ Branch 1 not taken.	12x	if (!cond(static_cast<std::error_code const&>(last_ec),
290			static_cast<endpoint_type const&>(ep)))
291		✗	continue;
292
293	1/2 ✓ Branch 0 taken 12 times. ✗ Branch 1 not taken.	12x	if (s.is_open())
294		✗	s.close();
295
296	7/12 ✗ Branch 0 not taken. ✓ Branch 1 taken 12 times. ✓ Branch 2 taken 4 times. ✓ Branch 3 taken 8 times. ✗ Branch 4 not taken. ✓ Branch 5 taken 4 times. ✗ Branch 6 not taken. ✗ Branch 7 not taken. ✓ Branch 8 taken 4 times. ✓ Branch 9 taken 4 times. ✗ Branch 10 not taken. ✓ Branch 11 taken 4 times.	12x	auto [ec] = co_await s.connect(ep);
297
298	2/2 ✓ Branch 0 taken 2 times. ✓ Branch 1 taken 2 times.	4x	if (!ec)
299	1/2 ✓ Branch 0 taken 2 times. ✗ Branch 1 not taken.	2x	co_return {std::error_code{}, std::move(it)};
300
301	1/2 ✗ Branch 0 not taken. ✓ Branch 1 taken 2 times.	2x	if (ec == capy::cond::canceled)
302		✗	co_return {ec, std::move(end)};
303
304		2x	last_ec = ec;
305		4x	}
306
307	1/2 ✓ Branch 0 taken 2 times. ✗ Branch 1 not taken.	2x	if (!last_ec)
308		✗	last_ec = std::make_error_code(std::errc::no_such_device_or_address);
309
310	1/2 ✓ Branch 0 taken 2 times. ✗ Branch 1 not taken.	2x	co_return {last_ec, std::move(end)};
311		16x	}
312
313			} // namespace boost::corosio
314
315			#endif
316