include/boost/corosio/io/io_object.hpp

100.0% Lines (67/67) 100.0% List of functions (22/23) 70.8% Branches (17/24)

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

io_object.hpp

f(x) Functions (23)

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			/** Owns the platform-specific handle and execution context that a derived
23			socket, timer, signal handler, or acceptor type uses to dispatch
24			operations.
25
26			Provides common infrastructure for I/O objects that wrap kernel
27			resources (sockets, timers, signal handlers, acceptors). Derived
28			classes dispatch operations through a platform-specific vtable
29			(IOCP, epoll, kqueue, io_uring).
30
31			@par Semantics
32			Only concrete platform I/O types should inherit from `io_object`.
33			Test mocks, decorators, and stream adapters must not inherit from
34			this class. Use concepts or templates for generic I/O algorithms.
35
36			@par Thread Safety
37			Distinct objects: Safe.
38			Shared objects: Unsafe. All operations on a single I/O object
39			must be serialized.
40
41			@note Intended as a protected base class. The handle member
42			`h_` is accessible to derived classes.
43
44			@see io_stream, tcp_socket, tcp_acceptor
45			*/
46			class BOOST_COROSIO_DECL io_object
47			{
48			public:
49			class handle;
50
51			/** Derived types dispatch platform-specific I/O operations through it.
52			*/
53			struct implementation
54			{
55			/// Destroy the implementation; called only through @ref io_service.
56		30382x	virtual ~implementation() = default;
57			};
58
59			/** Constructs, closes, and destroys platform implementations on
60			behalf of an I/O object. Platform backends implement this
61			interface.
62			*/
63			struct BOOST_COROSIO_DECL io_service
64			{
65			/// Destroy the service; the execution context outlives it.
66		6681x	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* impl) = 0;
73
74			/// Close the I/O object, releasing kernel resources without deallocating.
75		12628x	virtual void close([[maybe_unused]] handle& h) {}
76			};
77
78			/** Owns a platform-specific I/O implementation and destroys it
79			when the handle goes out of scope.
80			*/
81			class handle
82			{
83		10x	capy::execution_context* ctx_ = nullptr;
84		10x	io_service* svc_ = nullptr;
85		10x	implementation* impl_ = nullptr;
86
87			public:
88			/// Destroy the handle and its implementation.
89		144435x	~handle()
90		72217x	{
91	2/2 ✓ Branch 0 taken 38771 times. ✓ Branch 1 taken 33447 times.	72218x	if (impl_)
92			{
93	2/2 ✓ Branch 0 taken 33445 times. ✓ Branch 1 taken 2 times.	33449x	svc_->close(*this);
94	2/2 ✓ Branch 0 taken 33447 times. ✓ Branch 1 taken 2 times.	33445x	svc_->destroy(impl_);
95		33447x	}
96		144435x	}
97
98			/// Construct an empty handle.
99		30x	handle() = default;
100
101			/// Construct a handle bound to a context and service.
102		67680x	handle(capy::execution_context& ctx, io_service& svc)
103		33840x	: ctx_(&ctx)
104		33840x	, svc_(&svc)
105		33840x	, impl_(svc_->construct())
106		33840x	{
107		67680x	}
108
109			/// Move construct from another handle.
110		76860x	handle(handle&& other) noexcept
111		38430x	: ctx_(std::exchange(other.ctx_, nullptr))
112		38430x	, svc_(std::exchange(other.svc_, nullptr))
113		38430x	, impl_(std::exchange(other.impl_, nullptr))
114		38430x	{
115		76860x	}
116
117			/// Move assign from another handle.
118		354x	handle& operator=(handle&& other) noexcept
119			{
120	1/2 ✗ Branch 0 not taken. ✓ Branch 1 taken 354 times.	354x	if (this != &other)
121			{
122	2/2 ✓ Branch 0 taken 1 time. ✓ Branch 1 taken 353 times.	354x	if (impl_)
123			{
124	1/2 ✓ Branch 0 taken 353 times. ✗ Branch 1 not taken.	353x	svc_->close(*this);
125	1/2 ✓ Branch 0 taken 353 times. ✗ Branch 1 not taken.	353x	svc_->destroy(impl_);
126		353x	}
127		354x	ctx_ = std::exchange(other.ctx_, nullptr);
128		354x	svc_ = std::exchange(other.svc_, nullptr);
129		354x	impl_ = std::exchange(other.impl_, nullptr);
130		354x	}
131		354x	return *this;
132			}
133
134			/// Copy construction is disabled; the implementation is uniquely owned.
135			handle(handle const&) = delete;
136			/// Copy assignment is disabled; the implementation is uniquely owned.
137			handle& operator=(handle const&) = delete;
138
139			/// Return true if the handle owns an implementation.
140		93720x	explicit operator bool() const noexcept
141			{
142		93720x	return impl_ != nullptr;
143			}
144
145			/// Return the associated I/O service.
146		38124x	io_service& service() const noexcept
147			{
148		38124x	return *svc_;
149			}
150
151			/// Return the platform implementation.
152		2217278x	implementation* get() const noexcept
153			{
154		2217278x	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		8120x	void reset(implementation* p) noexcept
162			{
163	1/2 ✗ Branch 0 not taken. ✓ Branch 1 taken 8043 times.	8120x	if (impl_)
164			{
165	1/2 ✓ Branch 0 taken 8043 times. ✗ Branch 1 not taken.	8120x	svc_->close(*this);
166	1/2 ✓ Branch 0 taken 8043 times. ✗ Branch 1 not taken.	8120x	svc_->destroy(impl_);
167		8120x	}
168		8120x	impl_ = p;
169		8120x	}
170
171			/// Return the execution context.
172		37x	capy::execution_context& context() const noexcept
173			{
174		37x	return *ctx_;
175			}
176			};
177
178			/// Return the execution context.
179		37x	capy::execution_context& context() const noexcept
180			{
181		37x	return h_.context();
182			}
183
184			protected:
185			/// Destroy the object; protected, so only a derived type destroys one.
186		38062x	virtual ~io_object() = default;
187
188			/// Default construct for virtual base initialization.
189		10x	io_object() noexcept = default;
190
191			/** Create a handle bound to a service found in the context.
192
193			@tparam Service The service type whose key_type is used for lookup.
194			@param ctx The execution context to search for the service.
195
196			@return A handle owning a freshly constructed implementation.
197
198			@throws std::logic_error if the service is not installed.
199			*/
200			template<class Service>
201		12384x	static handle create_handle(capy::execution_context& ctx)
202			{
203		12384x	auto* svc = ctx.find_service<Service>();
204	2/2 ✓ Branch 0 taken 12380 times. ✓ Branch 1 taken 4 times.	12384x	if (!svc)
205		4x	detail::throw_logic_error(
206			"io_object::create_handle: service not installed");
207		12380x	return handle(ctx, *svc);
208			}
209
210			/// Construct an I/O object from a handle.
211		33840x	explicit io_object(handle h) noexcept : h_(std::move(h)) {}
212
213			/// Move construct from another I/O object.
214		4252x	io_object(io_object&& other) noexcept : h_(std::move(other.h_)) {}
215
216			/// Move assign from another I/O object.
217		4x	io_object& operator=(io_object&& other) noexcept
218			{
219	1/2 ✗ Branch 0 not taken. ✓ Branch 1 taken 4 times.	4x	if (this != &other)
220		4x	h_ = std::move(other.h_);
221		4x	return *this;
222			}
223
224			/// Copy construction is disabled; the handle is uniquely owned.
225			io_object(io_object const&) = delete;
226			/// Copy assignment is disabled; the handle is uniquely owned.
227			io_object& operator=(io_object const&) = delete;
228
229			/// The platform I/O handle owned by this object.
230			BOOST_COROSIO_MSVC_WARNING_PUSH
231			BOOST_COROSIO_MSVC_WARNING_DISABLE(4251)
232			handle h_;
233			BOOST_COROSIO_MSVC_WARNING_POP
234			};
235
236			} // namespace boost::corosio
237
238			#endif
239