corosio

Directory: ../corosio_lcov_PR-139/
Coverage: low: ≥ 0% medium: ≥ 75.0% high: ≥ 90.0%
Coverage Exec / Excl / Total
Lines: 100.0% 7 / 0 / 7
Functions: 100.0% 4 / 0 / 4
Branches: -% 0 / 0 / 0
include/boost/corosio/io_object.hpp
Line Branch Exec Source
1 //
2 // Copyright (c) 2025 Vinnie Falco (vinnie.falco@gmail.com)
3 //
4 // 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 //
7 // Official repository: https://github.com/cppalliance/corosio
8 //
9
10 #ifndef BOOST_COROSIO_IO_OBJECT_HPP
11 #define BOOST_COROSIO_IO_OBJECT_HPP
12
13 #include <boost/corosio/detail/config.hpp>
14 #include <boost/capy/ex/execution_context.hpp>
15
16 namespace boost::corosio {
17
18 /** Base class for platform I/O objects.
19
20 Provides common infrastructure for I/O objects that wrap kernel
21 resources (sockets, timers, signal handlers, acceptors). Derived
22 classes dispatch operations through a platform-specific vtable
23 (IOCP, epoll, kqueue, io_uring).
24
25 @par Semantics
26 Only concrete platform I/O types should inherit from `io_object`.
27 Test mocks, decorators, and stream adapters must not inherit from
28 this class. Use concepts or templates for generic I/O algorithms.
29
30 @par Thread Safety
31 Distinct objects: Safe.
32 Shared objects: Unsafe. All operations on a single I/O object
33 must be serialized.
34
35 @note Intended as a protected base class. The implementation
36 pointer `impl_` is accessible to derived classes.
37
38 @see io_stream, tcp_socket, tcp_acceptor
39 */
40 class BOOST_COROSIO_DECL io_object
41 {
42 public:
43 /// Forward declaration for platform-specific implementation.
44 struct implementation;
45
46 class handle;
47
48 /** Service interface for I/O object lifecycle management.
49
50 Platform backends implement this interface to manage the
51 creation, opening, closing, and destruction of I/O object
52 implementations.
53 */
54 struct io_service
55 {
56 /// Open the I/O object for use.
57 virtual void open(handle&) = 0;
58
59 /// Close the I/O object, releasing kernel resources.
60 virtual void close(handle&) = 0;
61
62 /// Destroy the implementation, freeing memory.
63 virtual void destroy(implementation*) = 0;
64
65 /// Construct a new implementation instance.
66 virtual implementation* construct() = 0;
67 };
68
69 /** RAII wrapper for I/O object implementation lifetime.
70
71 Manages ownership of the platform-specific implementation,
72 automatically destroying it when the handle goes out of scope.
73 */
74 class handle
75 {
76 capy::execution_context* ctx_ = nullptr;
77 io_service* svc_ = nullptr;
78 implementation* impl_ = nullptr;
79
80 public:
81 /// Destroy the handle and its implementation.
82 ~handle()
83 {
84 if(impl_)
85 svc_->destroy(impl_);
86 }
87
88 /// Construct an empty handle.
89 handle() = default;
90
91 /// Construct a handle bound to a context and service.
92 handle(
93 capy::execution_context& ctx,
94 io_service& svc)
95 : ctx_(&ctx)
96 , svc_(&svc)
97 , impl_(svc_->construct())
98 {
99 }
100
101 /// Move construct from another handle.
102 handle(handle&& other)
103 : ctx_(std::exchange(other.ctx_, nullptr))
104 , svc_(std::exchange(other.svc_, nullptr))
105 , impl_(std::exchange(other.impl_, nullptr))
106 {
107 }
108
109 /// Move assign from another handle.
110 handle& operator=(handle&& other) noexcept
111 {
112 ctx_ = std::exchange(other.ctx_, nullptr);
113 svc_ = std::exchange(other.svc_, nullptr);
114 impl_ = std::exchange(other.impl_, nullptr);
115 return *this;
116 }
117
118 /// Return the execution context.
119 capy::execution_context& context() const noexcept
120 {
121 return *ctx_;
122 }
123
124 /// Return the associated I/O service.
125 io_service& service() const noexcept
126 {
127 return *svc_;
128 }
129
130 /// Return the platform implementation.
131 implementation& get() const noexcept
132 {
133 return *impl_;
134 }
135 };
136
137 /** Base interface for platform I/O implementations.
138
139 Derived classes provide platform-specific operation dispatch.
140 */
141 struct io_object_impl
142 {
143 15352 virtual ~io_object_impl() = default;
144
145 /// Release associated resources without closing.
146 virtual void release() = 0;
147 };
148
149 /// Return the execution context.
150 capy::execution_context&
151 195 context() const noexcept
152 {
153 195 return *ctx_;
154 }
155
156 protected:
157 23627 virtual ~io_object() = default;
158
159 /// Construct an I/O object bound to the given context.
160 explicit
161 23625 io_object(
162 capy::execution_context& ctx) noexcept
163 23625 : ctx_(&ctx)
164 {
165 23625 }
166
167 capy::execution_context* ctx_ = nullptr;
168 io_object_impl* impl_ = nullptr;
169 };
170
171 } // namespace boost::corosio
172
173 #endif
174