Index/include / boost / corosio / io / io_object.hpp

include/boost/corosio/io/io_object.hpp

98.3% Lines (57/58) 100.0% Functions (26/26) 53.6% Branches (15/28)
include/boost/corosio/io/io_object.hpp
Prev Index Next
Line Branch TLA Hits Source Code
1 //
2 // Copyright (c) 2025 Vinnie Falco ([email protected])
3 // Copyright (c) 2026 Steve Gerbino
4 //
5 // Distributed under the Boost Software License, Version 1.0. (See accompanying
6 // file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
7 //
8 // Official repository: https://github.com/cppalliance/corosio
9 //
10
11 #ifndef BOOST_COROSIO_IO_IO_OBJECT_HPP
12 #define BOOST_COROSIO_IO_IO_OBJECT_HPP
13
14 #include <boost/corosio/detail/config.hpp>
15 #include <boost/corosio/detail/except.hpp>
16 #include <boost/capy/ex/execution_context.hpp>
17
18 #include <utility>
19
20 namespace boost::corosio {
21
22 /** Base class for platform I/O objects.
23
24 Provides common infrastructure for I/O objects that wrap kernel
25 resources (sockets, timers, signal handlers, acceptors). Derived
26 classes dispatch operations through a platform-specific vtable
27 (IOCP, epoll, kqueue, io_uring).
28
29 @par Semantics
30 Only concrete platform I/O types should inherit from `io_object`.
31 Test mocks, decorators, and stream adapters must not inherit from
32 this class. Use concepts or templates for generic I/O algorithms.
33
34 @par Thread Safety
35 Distinct objects: Safe.
36 Shared objects: Unsafe. All operations on a single I/O object
37 must be serialized.
38
39 @note Intended as a protected base class. The handle member
40 `h_` is accessible to derived classes.
41
42 @see io_stream, tcp_socket, tcp_acceptor
43 */
44 class BOOST_COROSIO_DECL io_object
45 {
46 public:
47 class handle;
48
49 /** Base interface for platform I/O implementations.
50
51 Derived classes provide platform-specific operation dispatch.
52 */
53 struct implementation
54 {
55 22881 virtual ~implementation() = default;
56 };
57
58 /** Service interface for I/O object lifecycle management.
59
60 Platform backends implement this interface to manage the
61 creation, closing, and destruction of I/O object
62 implementations.
63 */
64 struct io_service
65 {
66 2300 virtual ~io_service() = default;
67
68 /// Construct a new implementation instance.
69 virtual implementation* construct() = 0;
70
71 /// Destroy the implementation, closing kernel resources and freeing memory.
72 virtual void destroy(implementation*) = 0;
73
74 /// Close the I/O object, releasing kernel resources without deallocating.
75 7434 virtual void close(handle&) {}
76 };
77
78 /** RAII wrapper for I/O object implementation lifetime.
79
80 Manages ownership of the platform-specific implementation,
81 automatically destroying it when the handle goes out of scope.
82 */
83 class handle
84 {
85 capy::execution_context* ctx_ = nullptr;
86 io_service* svc_ = nullptr;
87 implementation* impl_ = nullptr;
88
89 public:
90 /// Destroy the handle and its implementation.
91 110212 ~handle()
92 55106 {
93
2/2
✓ Branch 0 taken 32321 times.
✓ Branch 1 taken 22785 times.
 55106 if (impl_)
94 {
95
1/2
✓ Branch 0 taken 22785 times.
✗ Branch 1 not taken.
 22785 svc_->close(*this);
96
1/2
✓ Branch 0 taken 22785 times.
✗ Branch 1 not taken.
 22785 svc_->destroy(impl_);
97 22785 }
98 110212 }
99
100 /// Construct an empty handle.
101 handle() = default;
102
103 /// Construct a handle bound to a context and service.
104 45698 handle(capy::execution_context& ctx, io_service& svc)
105 22849 : ctx_(&ctx)
106 22849 , svc_(&svc)
107 22849 , impl_(svc_->construct())
108 22849 {
109 45698 }
110
111 /// Move construct from another handle.
112 64514 handle(handle&& other) noexcept
113 32257 : ctx_(std::exchange(other.ctx_, nullptr))
114 32257 , svc_(std::exchange(other.svc_, nullptr))
115 32257 , impl_(std::exchange(other.impl_, nullptr))
116 32257 {
117 64514 }
118
119 /// Move assign from another handle.
120 64 handle& operator=(handle&& other) noexcept
121 {
122
1/2
✗ Branch 0 not taken.
✓ Branch 1 taken 64 times.
 64 if (this != &other)
123 {
124
1/2
✗ Branch 0 not taken.
✓ Branch 1 taken 64 times.
 64 if (impl_)
125 {
126
1/2
✓ Branch 0 taken 64 times.
✗ Branch 1 not taken.
 64 svc_->close(*this);
127
1/2
✓ Branch 0 taken 64 times.
✗ Branch 1 not taken.
 64 svc_->destroy(impl_);
128 64 }
129 64 ctx_ = std::exchange(other.ctx_, nullptr);
130 64 svc_ = std::exchange(other.svc_, nullptr);
131 64 impl_ = std::exchange(other.impl_, nullptr);
132 64 }
133 64 return *this;
134 }
135
136 handle(handle const&) = delete;
137 handle& operator=(handle const&) = delete;
138
139 /// Return true if the handle owns an implementation.
140 59672 explicit operator bool() const noexcept
141 {
142 59672 return impl_ != nullptr;
143 }
144
145 /// Return the associated I/O service.
146 23487 io_service& service() const noexcept
147 {
148 23487 return *svc_;
149 }
150
151 /// Return the platform implementation.
152 1673763 implementation* get() const noexcept
153 {
154 1673763 return impl_;
155 }
156
157 /** Replace the implementation, destroying the old one.
158
159 @param p The new implementation to own. May be nullptr.
160 */
161 7135 void reset(implementation* p) noexcept
162 {
163
1/2
✗ Branch 0 not taken.
✓ Branch 1 taken 7135 times.
 7135 if (impl_)
164 {
165
1/2
✓ Branch 0 taken 7135 times.
✗ Branch 1 not taken.
 7135 svc_->close(*this);
166
1/2
✓ Branch 0 taken 7135 times.
✗ Branch 1 not taken.
 7135 svc_->destroy(impl_);
167 7135 }
168 7135 impl_ = p;
169 7135 }
170
171 /// Return the execution context.
172 10 capy::execution_context& context() const noexcept
173 {
174 10 return *ctx_;
175 }
176 };
177
178 /// Return the execution context.
179 10 capy::execution_context& context() const noexcept
180 {
181 10 return h_.context();
182 }
183
184 protected:
185 24842 virtual ~io_object() = default;
186
187 /// Default construct for virtual base initialization.
188 io_object() noexcept = default;
189
190 /** Create a handle bound to a service found in the context.
191
192 @tparam Service The service type whose key_type is used for lookup.
193 @param ctx The execution context to search for the service.
194
195 @return A handle owning a freshly constructed implementation.
196
197 @throws std::logic_error if the service is not installed.
198 */
199 template<class Service>
200 15544 static handle create_handle(capy::execution_context& ctx)
201 {
202 15544 auto* svc = ctx.find_service<Service>();
203
4/8
✓ Branch 0 taken 15508 times.
✗ Branch 1 not taken.
✓ Branch 2 taken 14 times.
✗ Branch 3 not taken.
✓ Branch 4 taken 8 times.
✗ Branch 5 not taken.
✓ Branch 6 taken 14 times.
✗ Branch 7 not taken.
 15544 if (!svc)
204 ✗ detail::throw_logic_error(
205 "io_object::create_handle: service not installed");
206 15544 return handle(ctx, *svc);
207 }
208
209 /// Construct an I/O object from a handle.
210 22849 explicit io_object(handle h) noexcept : h_(std::move(h)) {}
211
212 /// Move construct from another I/O object.
213 1993 io_object(io_object&& other) noexcept : h_(std::move(other.h_)) {}
214
215 /// Move assign from another I/O object.
216 io_object& operator=(io_object&& other) noexcept
217 {
218 if (this != &other)
219 h_ = std::move(other.h_);
220 return *this;
221 }
222
223 io_object(io_object const&) = delete;
224 io_object& operator=(io_object const&) = delete;
225
226 handle h_;
227 };
228
229 } // namespace boost::corosio
230
231 #endif
232