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

include/boost/corosio/io/io_object.hpp

98.0% Lines (50/51) 100.0% Functions (24/24)
include/boost/corosio/io/io_object.hpp
Line Hits Source Code
1 //
2 // Copyright (c) 2025 Vinnie Falco (vinnie.falco@gmail.com)
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 24102 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 1700 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 8730 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 58236 ~handle()
92 {
93 58236 if (impl_)
94 {
95 24646 svc_->close(*this);
96 24646 svc_->destroy(impl_);
97 }
98 58236 }
99
100 /// Construct an empty handle.
101 handle() = default;
102
103 /// Construct a handle bound to a context and service.
104 24668 handle(capy::execution_context& ctx, io_service& svc)
105 24668 : ctx_(&ctx)
106 24668 , svc_(&svc)
107 24668 , impl_(svc_->construct())
108 {
109 24668 }
110
111 /// Move construct from another handle.
112 33568 handle(handle&& other) noexcept
113 33568 : ctx_(std::exchange(other.ctx_, nullptr))
114 33568 , svc_(std::exchange(other.svc_, nullptr))
115 33568 , impl_(std::exchange(other.impl_, nullptr))
116 {
117 33568 }
118
119 /// Move assign from another handle.
120 22 handle& operator=(handle&& other) noexcept
121 {
122 22 if (this != &other)
123 {
124 22 if (impl_)
125 {
126 22 svc_->close(*this);
127 22 svc_->destroy(impl_);
128 }
129 22 ctx_ = std::exchange(other.ctx_, nullptr);
130 22 svc_ = std::exchange(other.svc_, nullptr);
131 22 impl_ = std::exchange(other.impl_, nullptr);
132 }
133 22 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 56486 explicit operator bool() const noexcept
141 {
142 56486 return impl_ != nullptr;
143 }
144
145 /// Return the associated I/O service.
146 23888 io_service& service() const noexcept
147 {
148 23888 return *svc_;
149 }
150
151 /// Return the platform implementation.
152 522785 implementation* get() const noexcept
153 {
154 522785 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 7874 void reset(implementation* p) noexcept
162 {
163 7874 if (impl_)
164 {
165 7874 svc_->close(*this);
166 7874 svc_->destroy(impl_);
167 }
168 7874 impl_ = p;
169 7874 }
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 24863 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 16055 static handle create_handle(capy::execution_context& ctx)
201 {
202 16055 auto* svc = ctx.find_service<Service>();
203 16055 if (!svc)
204 ✗ detail::throw_logic_error(
205 "io_object::create_handle: service not installed");
206 16055 return handle(ctx, *svc);
207 }
208
209 /// Construct an I/O object from a handle.
210 24668 explicit io_object(handle h) noexcept : h_(std::move(h)) {}
211
212 /// Move construct from another I/O object.
213 195 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