include/boost/corosio/native/native_stream_file.hpp

91.3% Lines (42/46) 100.0% List of functions (34/34) 40.0% Branches (16/40)

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

native_stream_file.hpp

f(x) Functions (34)

Function Calls Lines Branches Blocks

Line	Branch	Hits	Source Code
1			//
2			// Copyright (c) 2026 Steve Gerbino
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_NATIVE_NATIVE_STREAM_FILE_HPP
11			#define BOOST_COROSIO_NATIVE_NATIVE_STREAM_FILE_HPP
12
13			#include <boost/corosio/stream_file.hpp>
14			#include <boost/corosio/backend.hpp>
15
16			#ifndef BOOST_COROSIO_MRDOCS
17			#if BOOST_COROSIO_HAS_EPOLL \|\| BOOST_COROSIO_HAS_SELECT \|\| \
18			BOOST_COROSIO_HAS_KQUEUE
19			#include <boost/corosio/native/detail/posix/posix_stream_file_service.hpp>
20			#endif
21
22			#if BOOST_COROSIO_HAS_IO_URING
23			#include <boost/corosio/native/detail/io_uring/io_uring_stream_file.hpp>
24			#endif
25
26			#if BOOST_COROSIO_HAS_IOCP
27			#include <boost/corosio/native/detail/iocp/win_file_service.hpp>
28			#endif
29			#endif // !BOOST_COROSIO_MRDOCS
30
31			namespace boost::corosio {
32
33			/** A sequential file with devirtualized async I/O operations.
34
35			This class template inherits from @ref stream_file and shadows
36			`read_some` / `write_some` with versions that call the backend
37			implementation directly, allowing the compiler to inline through
38			the entire call chain.
39
40			Non-async operations (`open`, `close`, `size`, `resize`, `seek`,
41			`sync_data`, `sync_all`) remain unchanged and dispatch through
42			the compiled library.
43
44			A `native_stream_file` IS-A `stream_file` and can be passed to
45			any function expecting `stream_file&` or `io_stream&`, in which
46			case virtual dispatch is used transparently.
47
48			@note On POSIX platforms, file I/O is dispatched to a thread
49			pool regardless of the chosen reactor backend, so all three
50			reactor tags (`epoll`, `select`, `kqueue`) resolve to the same
51			underlying implementation. The `Backend` template parameter
52			exists for API symmetry with @ref native_tcp_socket and friends.
53			The vtable savings are smaller relative to the thread-pool /
54			overlapped-I/O cost than they are for socket operations.
55
56			@tparam Backend A backend tag value (e.g., `epoll`, `iocp`).
57
58			@par Thread Safety
59			Same as @ref stream_file.
60
61			@par Example
62			@code
63			#include <boost/corosio/native/native_stream_file.hpp>
64
65			native_io_context<epoll> ctx;
66			native_stream_file<epoll> f(ctx);
67			f.open("data.bin", file_base::read_only);
68			char buf[4096];
69			auto [ec, n] = co_await f.read_some(
70			capy::mutable_buffer(buf, sizeof(buf)));
71			@endcode
72
73			@see stream_file, epoll_t, iocp_t
74			*/
75			template<auto Backend>
76			class native_stream_file : public stream_file
77			{
78			using backend_type = decltype(Backend);
79			using impl_type = typename backend_type::stream_file_type;
80			using service_type = typename backend_type::stream_file_service_type;
81
82		4x	impl_type& get_impl() noexcept
83			{
84		4x	return static_cast<impl_type>(h_.get());
85			}
86
87			template<class MutableBufferSequence>
88			struct native_read_awaitable
89			{
90			native_stream_file& self_;
91			MutableBufferSequence buffers_;
92			std::stop_token token_;
93			mutable std::error_code ec_;
94		2x	mutable std::size_t bytes_transferred_ = 0;
95
96		6x	native_read_awaitable(
97			native_stream_file& self,
98			MutableBufferSequence buffers) noexcept
99		2x	: self_(self)
100		2x	, buffers_(std::move(buffers))
101		2x	{
102		4x	}
103
104		2x	bool await_ready() const noexcept
105			{
106		2x	return token_.stop_requested();
107			}
108
109		2x	capy::io_result<std::size_t> await_resume() const noexcept
110			{
111	2/4 ✗ Branch 0 not taken. ✓ Branch 1 taken 1 time. ✗ Branch 2 not taken. ✓ Branch 3 taken 1 time.	2x	if (token_.stop_requested())
112		✗	return {make_error_code(std::errc::operation_canceled), 0};
113	2/4 ✓ Branch 0 taken 1 time. ✗ Branch 1 not taken. ✓ Branch 2 taken 1 time. ✗ Branch 3 not taken.	2x	return {ec_, bytes_transferred_};
114		2x	}
115
116		2x	auto await_suspend(std::coroutine_handle<> h, capy::io_env const* env)
117			-> std::coroutine_handle<>
118			{
119		2x	token_ = env->stop_token;
120	4/8 ✓ Branch 0 taken 1 time. ✗ Branch 1 not taken. ✓ Branch 2 taken 1 time. ✗ Branch 3 not taken. ✓ Branch 4 taken 1 time. ✗ Branch 5 not taken. ✓ Branch 6 taken 1 time. ✗ Branch 7 not taken.	4x	return self_.get_impl().read_some(
121		2x	h, env->executor, buffers_, token_, &ec_, &bytes_transferred_);
122		✗	}
123			};
124
125			template<class ConstBufferSequence>
126			struct native_write_awaitable
127			{
128			native_stream_file& self_;
129			ConstBufferSequence buffers_;
130			std::stop_token token_;
131			mutable std::error_code ec_;
132		2x	mutable std::size_t bytes_transferred_ = 0;
133
134		6x	native_write_awaitable(
135			native_stream_file& self,
136			ConstBufferSequence buffers) noexcept
137		2x	: self_(self)
138		2x	, buffers_(std::move(buffers))
139		2x	{
140		4x	}
141
142		2x	bool await_ready() const noexcept
143			{
144		2x	return token_.stop_requested();
145			}
146
147		2x	capy::io_result<std::size_t> await_resume() const noexcept
148			{
149	2/4 ✗ Branch 0 not taken. ✓ Branch 1 taken 1 time. ✗ Branch 2 not taken. ✓ Branch 3 taken 1 time.	2x	if (token_.stop_requested())
150		✗	return {make_error_code(std::errc::operation_canceled), 0};
151	2/4 ✓ Branch 0 taken 1 time. ✗ Branch 1 not taken. ✓ Branch 2 taken 1 time. ✗ Branch 3 not taken.	2x	return {ec_, bytes_transferred_};
152		2x	}
153
154		2x	auto await_suspend(std::coroutine_handle<> h, capy::io_env const* env)
155			-> std::coroutine_handle<>
156			{
157		2x	token_ = env->stop_token;
158	4/8 ✓ Branch 0 taken 1 time. ✗ Branch 1 not taken. ✓ Branch 2 taken 1 time. ✗ Branch 3 not taken. ✓ Branch 4 taken 1 time. ✗ Branch 5 not taken. ✓ Branch 6 taken 1 time. ✗ Branch 7 not taken.	4x	return self_.get_impl().write_some(
159		2x	h, env->executor, buffers_, token_, &ec_, &bytes_transferred_);
160		✗	}
161			};
162
163			public:
164			/** Construct a native stream file from an execution context.
165
166			@param ctx The execution context that will own this file.
167			*/
168		20x	explicit native_stream_file(capy::execution_context& ctx)
169		10x	: io_object(create_handle<service_type>(ctx))
170		20x	{
171		10x	}
172
173			/** Construct a native stream file from an executor.
174
175			@param ex The executor whose context will own this file.
176			*/
177			template<class Ex>
178			requires(!std::same_as<std::remove_cvref_t<Ex>, native_stream_file>) &&
179			capy::Executor<Ex>
180			explicit native_stream_file(Ex const& ex) : native_stream_file(ex.context())
181			{
182			}
183
184			/// Move construct.
185			native_stream_file(native_stream_file&&) noexcept = default;
186
187			/// Move assign.
188			native_stream_file& operator=(native_stream_file&&) noexcept = default;
189
190			native_stream_file(native_stream_file const&) = delete;
191			native_stream_file& operator=(native_stream_file const&) = delete;
192
193			/** Asynchronously read data from the file.
194
195			Calls the backend implementation directly, bypassing virtual
196			dispatch. Otherwise identical to @ref io_stream::read_some.
197			*/
198			template<capy::MutableBufferSequence MB>
199		2x	auto read_some(MB const& buffers)
200			{
201		2x	return native_read_awaitable<MB>(*this, buffers);
202			}
203
204			/** Asynchronously write data to the file.
205
206			Calls the backend implementation directly, bypassing virtual
207			dispatch. Otherwise identical to @ref io_stream::write_some.
208			*/
209			template<capy::ConstBufferSequence CB>
210		2x	auto write_some(CB const& buffers)
211			{
212		2x	return native_write_awaitable<CB>(*this, buffers);
213			}
214			};
215
216			} // namespace boost::corosio
217
218			#endif // BOOST_COROSIO_NATIVE_NATIVE_STREAM_FILE_HPP
219