include/boost/corosio/io/io_object.hpp

94.7% Lines (54/57) 93.5% List of functions (29/31) 58.3% Branches (7/12)

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

io_object.hpp

f(x) Functions (31)

Function Calls Lines Branches Blocks

Line	Branch	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		6077x	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		5940x	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		2405x	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		18610x	~handle()
92			{
93	2/2 ✓ Branch 2 → 3 taken 6768 times. ✓ Branch 2 → 5 taken 11842 times.	18610x	if (impl_)
94			{
95		6768x	svc_->close(*this);
96		6768x	svc_->destroy(impl_);
97			}
98		18610x	}
99
100			/// Construct an empty handle.
101		✗	handle() = default;
102
103			/// Construct a handle bound to a context and service.
104		6827x	handle(capy::execution_context& ctx, io_service& svc)
105		6827x	: ctx_(&ctx)
106		6827x	, svc_(&svc)
107		6827x	, impl_(svc_->construct())
108			{
109		6827x	}
110
111			/// Move construct from another handle.
112		11784x	handle(handle&& other) noexcept
113		11784x	: ctx_(std::exchange(other.ctx_, nullptr))
114		11784x	, svc_(std::exchange(other.svc_, nullptr))
115		11784x	, impl_(std::exchange(other.impl_, nullptr))
116			{
117		11784x	}
118
119			/// Move assign from another handle.
120		58x	handle& operator=(handle&& other) noexcept
121			{
122	1/2 ✓ Branch 2 → 3 taken 58 times. ✗ Branch 2 → 10 not taken.	58x	if (this != &other)
123			{
124	1/2 ✓ Branch 3 → 4 taken 58 times. ✗ Branch 3 → 6 not taken.	58x	if (impl_)
125			{
126		58x	svc_->close(*this);
127		58x	svc_->destroy(impl_);
128			}
129		58x	ctx_ = std::exchange(other.ctx_, nullptr);
130		58x	svc_ = std::exchange(other.svc_, nullptr);
131		58x	impl_ = std::exchange(other.impl_, nullptr);
132			}
133		58x	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		29044x	explicit operator bool() const noexcept
141			{
142		29044x	return impl_ != nullptr;
143			}
144
145			/// Return the associated I/O service.
146		9896x	io_service& service() const noexcept
147			{
148		9896x	return *svc_;
149			}
150
151			/// Return the platform implementation.
152		485030x	implementation* get() const noexcept
153			{
154		485030x	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		1369x	void reset(implementation* p) noexcept
162			{
163	1/2 ✓ Branch 2 → 3 taken 1369 times. ✗ Branch 2 → 5 not taken.	1369x	if (impl_)
164			{
165		1369x	svc_->close(*this);
166		1369x	svc_->destroy(impl_);
167			}
168		1369x	impl_ = p;
169		1369x	}
170
171			/// Return the execution context.
172		6x	capy::execution_context& context() const noexcept
173			{
174		6x	return *ctx_;
175			}
176			};
177
178			/// Return the execution context.
179		6x	capy::execution_context& context() const noexcept
180			{
181		6x	return h_.context();
182			}
183
184			protected:
185		9377x	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		4500x	static handle create_handle(capy::execution_context& ctx)
201			{
202		4500x	auto* svc = ctx.find_service<Service>();
203	1/2 ✗ Branch 3 → 4 not taken. ✓ Branch 3 → 5 taken 4500 times.	4500x	if (!svc)
204		✗	detail::throw_logic_error(
205			"io_object::create_handle: service not installed");
206		4500x	return handle(ctx, *svc);
207			}
208
209			/// Construct an I/O object from a handle.
210		6827x	explicit io_object(handle h) noexcept : h_(std::move(h)) {}
211
212			/// Move construct from another I/O object.
213		2551x	io_object(io_object&& other) noexcept : h_(std::move(other.h_)) {}
214
215			/// Move assign from another I/O object.
216		1x	io_object& operator=(io_object&& other) noexcept
217			{
218	1/2 ✓ Branch 2 → 3 taken 1 time. ✗ Branch 2 → 5 not taken.	1x	if (this != &other)
219		1x	h_ = std::move(other.h_);
220		1x	return *this;
221			}
222
223			io_object(io_object const&) = delete;
224			io_object& operator=(io_object const&) = delete;
225
226			/// The platform I/O handle owned by this object.
227			handle h_;
228			};
229
230			} // namespace boost::corosio
231
232			#endif
233