. /include/boost/corosio /resolver_results.hpp
100.00% Lines (23/23) 100.00% Functions (9/9)
[ ] prev/next file n p prev/next uncovered line
TLA Baseline Branch
Line Hits Code Line Hits Code
1   // 1   //
2   // Copyright (c) 2025 Vinnie Falco (vinnie.falco@gmail.com) 2   // Copyright (c) 2025 Vinnie Falco (vinnie.falco@gmail.com)
  3 + // Copyright (c) 2026 Michael Vandeberg
3   // 4   //
4   // Distributed under the Boost Software License, Version 1.0. (See accompanying 5   // 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   // file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
6   // 7   //
7   // Official repository: https://github.com/cppalliance/corosio 8   // Official repository: https://github.com/cppalliance/corosio
8   // 9   //
9   10  
10   #ifndef BOOST_COROSIO_RESOLVER_RESULTS_HPP 11   #ifndef BOOST_COROSIO_RESOLVER_RESULTS_HPP
11   #define BOOST_COROSIO_RESOLVER_RESULTS_HPP 12   #define BOOST_COROSIO_RESOLVER_RESULTS_HPP
12   13  
13   #include <boost/corosio/detail/config.hpp> 14   #include <boost/corosio/detail/config.hpp>
14   #include <boost/corosio/endpoint.hpp> 15   #include <boost/corosio/endpoint.hpp>
15 - #include <cstddef>  
16 - #include <memory>  
17   16  
18   #include <string> 17   #include <string>
19   #include <string_view> 18   #include <string_view>
20   #include <vector> 19   #include <vector>
21   20  
22   namespace boost::corosio { 21   namespace boost::corosio {
23   22  
24   /** A single entry produced by a resolver. 23   /** A single entry produced by a resolver.
25   24  
26   This class represents one resolved endpoint along with 25   This class represents one resolved endpoint along with
27   the host and service names used in the query. 26   the host and service names used in the query.
28   27  
29   @par Thread Safety 28   @par Thread Safety
30   Distinct objects: Safe.@n 29   Distinct objects: Safe.@n
31   Shared objects: Safe. 30   Shared objects: Safe.
32   */ 31   */
33   class resolver_entry 32   class resolver_entry
34   { 33   {
35   endpoint ep_; 34   endpoint ep_;
36   std::string host_name_; 35   std::string host_name_;
37   std::string service_name_; 36   std::string service_name_;
38   37  
39   public: 38   public:
40   /// Construct a default empty entry. 39   /// Construct a default empty entry.
41   resolver_entry() = default; 40   resolver_entry() = default;
42   41  
43   /** Construct with endpoint, host name, and service name. 42   /** Construct with endpoint, host name, and service name.
44   43  
45   @param ep The resolved endpoint. 44   @param ep The resolved endpoint.
46   @param host The host name from the query. 45   @param host The host name from the query.
47   @param service The service name from the query. 46   @param service The service name from the query.
48   */ 47   */
HITCBC 49   21 resolver_entry(endpoint ep, std::string_view host, std::string_view service) 48   21 resolver_entry(endpoint ep, std::string_view host, std::string_view service)
HITCBC 50   21 : ep_(ep) 49   21 : ep_(ep)
HITCBC 51   42 , host_name_(host) 50   42 , host_name_(host)
HITCBC 52   42 , service_name_(service) 51   42 , service_name_(service)
53   { 52   {
HITCBC 54   21 } 53   21 }
55   54  
56   /// Return the resolved endpoint. 55   /// Return the resolved endpoint.
HITCBC 57   6 endpoint get_endpoint() const noexcept 56   6 endpoint get_endpoint() const noexcept
58   { 57   {
HITCBC 59   6 return ep_; 58   6 return ep_;
60   } 59   }
61   60  
62   /// Convert to endpoint. 61   /// Convert to endpoint.
HITCBC 63   1 operator endpoint() const noexcept 62   1 operator endpoint() const noexcept
64   { 63   {
HITCBC 65   1 return ep_; 64   1 return ep_;
66   } 65   }
67   66  
68   /// Return the host name from the query. 67   /// Return the host name from the query.
HITCBC 69   2 std::string const& host_name() const noexcept 68   2 std::string const& host_name() const noexcept
70   { 69   {
HITCBC 71   2 return host_name_; 70   2 return host_name_;
72   } 71   }
73   72  
74   /// Return the service name from the query. 73   /// Return the service name from the query.
HITCBC 75   2 std::string const& service_name() const noexcept 74   2 std::string const& service_name() const noexcept
76   { 75   {
HITCBC 77   2 return service_name_; 76   2 return service_name_;
78   } 77   }
79   }; 78   };
80   79  
81   /** A range of entries produced by a resolver. 80   /** A range of entries produced by a resolver.
82   81  
83 - This class holds the results of a DNS resolution query. 82 + This is an alias for `std::vector<resolver_entry>`: a contiguous,
84 - It provides a range interface for iterating over the 83 + owning range of the endpoints resolved by a query. It supports the
85 - resolved endpoints. 84 + full `std::vector` interface (iteration, `size()`, `empty()`, etc.).
  85 +
  86 + @note Copying a `resolver_results` deep-copies every entry, and each
  87 + entry owns two `std::string`s (the host and service names). When you
  88 + want to hand a result to a sink that takes the range by value — such
  89 + as `corosio::connect` — pass an rvalue (`std::move(results)`) or use
  90 + the iterator-based `connect` overloads to avoid the copy.
86   91  
87   @par Thread Safety 92   @par Thread Safety
88   Distinct objects: Safe.@n 93   Distinct objects: Safe.@n
89 - Shared objects: Safe (immutable after construction). 94 + Shared objects: Unsafe.
90   */ 95   */
91 - class resolver_results 96 + using resolver_results = std::vector<resolver_entry>;
92 - {  
93 - public:  
94 - /// The entry type.  
95 - using value_type = resolver_entry;  
96 -  
97 - /// Const reference to an entry.  
98 - using const_reference = value_type const&;  
99 -  
100 - /// Reference to an entry (always const).  
101 - using reference = const_reference;  
102 -  
103 - /// Const iterator over entries.  
104 - using const_iterator = std::vector<resolver_entry>::const_iterator;  
105 -  
106 - /// Iterator over entries (always const).  
107 - using iterator = const_iterator;  
108 -  
109 - /// Signed difference type.  
110 - using difference_type = std::ptrdiff_t;  
111 -  
112 - /// Unsigned size type.  
113 - using size_type = std::size_t;  
114 -  
115 - private:  
116 - std::shared_ptr<std::vector<resolver_entry>> entries_;  
117 -  
118 - public:  
119 - /// Construct an empty results range.  
DCB 120 - 86 resolver_results() = default;  
121 -  
122 - /** Construct from a vector of entries.  
123 -  
124 - @param entries The resolved entries.  
125 - */  
DCB 126 - 18 explicit resolver_results(std::vector<resolver_entry> entries)  
DCB 127 - 18 : entries_(  
DCB 128 - 18 std::make_shared<std::vector<resolver_entry>>(std::move(entries)))  
129 - {  
DCB 130 - 18 }  
131 -  
132 - /// Return the number of entries.  
DCB 133 - 11 size_type size() const noexcept  
134 - {  
DCB 135 - 11 return entries_ ? entries_->size() : 0;  
136 - }  
137 -  
138 - /// Check if the results are empty.  
DCB 139 - 11 bool empty() const noexcept  
140 - {  
DCB 141 - 11 return !entries_ || entries_->empty();  
142 - }  
143 -  
144 - /// Return an iterator to the first entry.  
DCB 145 - 9 const_iterator begin() const noexcept  
146 - {  
DCB 147 - 9 if (entries_)  
DCB 148 - 8 return entries_->begin();  
DCB 149 - 1 return std::vector<resolver_entry>::const_iterator();  
150 - }  
151 -  
152 - /// Return an iterator past the last entry.  
DCB 153 - 5 const_iterator end() const noexcept  
154 - {  
DCB 155 - 5 if (entries_)  
DCB 156 - 4 return entries_->end();  
DCB 157 - 1 return std::vector<resolver_entry>::const_iterator();  
158 - }  
159 -  
160 - /// Return an iterator to the first entry.  
DCB 161 - 1 const_iterator cbegin() const noexcept  
162 - {  
DCB 163 - 1 return begin();  
164 - }  
165 -  
166 - /// Return an iterator past the last entry.  
DCB 167 - 2 const_iterator cend() const noexcept  
168 - {  
DCB 169 - 2 return end();  
170 - }  
171 -  
172 - /// Swap with another results object.  
DCB 173 - 1 void swap(resolver_results& other) noexcept  
174 - {  
DCB 175 - 1 entries_.swap(other.entries_);  
DCB 176 - 1 }  
177 -  
178 - /// Test for equality.  
179 - friend bool  
180 - operator==(resolver_results const& a, resolver_results const& b) noexcept  
181 - {  
182 - return a.entries_ == b.entries_;  
183 - }  
184 -  
185 - /// Test for inequality.  
186 - friend bool  
187 - operator!=(resolver_results const& a, resolver_results const& b) noexcept  
188 - {  
189 - return !(a == b);  
190 - }  
191 - };  
192   97  
193   /** The result of a reverse DNS resolution. 98   /** The result of a reverse DNS resolution.
194   99  
195   This class holds the result of resolving an endpoint 100   This class holds the result of resolving an endpoint
196   into a hostname and service name. 101   into a hostname and service name.
197   102  
198   @par Thread Safety 103   @par Thread Safety
199   Distinct objects: Safe.@n 104   Distinct objects: Safe.@n
200   Shared objects: Safe. 105   Shared objects: Safe.
201   */ 106   */
202   class reverse_resolver_result 107   class reverse_resolver_result
203   { 108   {
204   corosio::endpoint ep_; 109   corosio::endpoint ep_;
205   std::string host_; 110   std::string host_;
206   std::string service_; 111   std::string service_;
207   112  
208   public: 113   public:
209   /// Construct a default empty result. 114   /// Construct a default empty result.
HITCBC 210   19 reverse_resolver_result() = default; 115   19 reverse_resolver_result() = default;
211   116  
212   /** Construct with endpoint, host name, and service name. 117   /** Construct with endpoint, host name, and service name.
213   118  
214   @param ep The endpoint that was resolved. 119   @param ep The endpoint that was resolved.
215   @param host The resolved host name. 120   @param host The resolved host name.
216   @param service The resolved service name. 121   @param service The resolved service name.
217   */ 122   */
HITCBC 218   10 reverse_resolver_result( 123   10 reverse_resolver_result(
219   corosio::endpoint ep, std::string host, std::string service) 124   corosio::endpoint ep, std::string host, std::string service)
HITCBC 220   10 : ep_(ep) 125   10 : ep_(ep)
HITCBC 221   10 , host_(std::move(host)) 126   10 , host_(std::move(host))
HITCBC 222   10 , service_(std::move(service)) 127   10 , service_(std::move(service))
223   { 128   {
HITCBC 224   10 } 129   10 }
225   130  
226   /// Return the endpoint that was resolved. 131   /// Return the endpoint that was resolved.
227   corosio::endpoint endpoint() const noexcept 132   corosio::endpoint endpoint() const noexcept
228   { 133   {
229   return ep_; 134   return ep_;
230   } 135   }
231   136  
232   /// Return the resolved host name. 137   /// Return the resolved host name.
HITCBC 233   5 std::string const& host_name() const noexcept 138   5 std::string const& host_name() const noexcept
234   { 139   {
HITCBC 235   5 return host_; 140   5 return host_;
236   } 141   }
237   142  
238   /// Return the resolved service name. 143   /// Return the resolved service name.
HITCBC 239   4 std::string const& service_name() const noexcept 144   4 std::string const& service_name() const noexcept
240   { 145   {
HITCBC 241   4 return service_; 146   4 return service_;
242   } 147   }
243   }; 148   };
244   149  
245   } // namespace boost::corosio 150   } // namespace boost::corosio
246   151  
247   #endif 152   #endif