Index/include / boost / corosio / stream_file.hpp

include/boost/corosio/stream_file.hpp

100.0% Lines (14/14) 100.0% List of functions (8/8) 75.0% Branches (3/4)
[ ] prev/next file n p prev/next uncovered line
stream_file.hpp
f(x) Functions (8)
Function Calls Lines Branches Blocks
boost::corosio::stream_file::implementation::implementation() :69 635x 100.0% – 100.0% boost::corosio::stream_file::implementation::~implementation() :69 635x 100.0% – 100.0% boost::corosio::stream_file::stream_file<boost::corosio::io_context::executor_type>(boost::corosio::io_context::executor_type const&) :149 2x 100.0% – 100.0% boost::corosio::stream_file::stream_file(boost::corosio::stream_file&&) :155 2x 100.0% – 100.0% boost::corosio::stream_file::operator=(boost::corosio::stream_file&&) :161 2x 100.0% 50.0% 100.0% boost::corosio::stream_file::is_open() const :209 2712x 100.0% 100.0% 100.0% boost::corosio::stream_file::stream_file() :353 16x 100.0% – 100.0% boost::corosio::stream_file::get() const :362 4198x 100.0% – 100.0%
Line Branch TLA Hits Source Code
1 //
2 // Copyright (c) 2026 Michael Vandeberg
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_STREAM_FILE_HPP
11 #define BOOST_COROSIO_STREAM_FILE_HPP
12
13 #include <boost/corosio/detail/config.hpp>
14 #include <boost/corosio/detail/platform.hpp>
15 #include <boost/corosio/detail/except.hpp>
16 #include <boost/corosio/detail/native_handle.hpp>
17 #include <boost/corosio/error.hpp>
18 #include <boost/corosio/file_base.hpp>
19 #include <boost/corosio/io/io_stream.hpp>
20 #include <boost/capy/ex/execution_context.hpp>
21 #include <boost/capy/concept/executor.hpp>
22 #include <boost/capy/io_result.hpp>
23
24 #include <concepts>
25 #include <cstdint>
26 #include <filesystem>
27 #include <system_error>
28
29 namespace boost::corosio {
30
31 /** Reads and writes a file sequentially, from a coroutine.
32
33 Provides asynchronous read and write operations on a regular
34 file with an implicit position that advances after each
35 operation.
36
37 Inherits from @ref io_stream, so `read_some` and `write_some`
38 are available and work with any algorithm that accepts an
39 `io_stream&`.
40
41 On POSIX platforms, file I/O is dispatched to a thread pool
42 (blocking `preadv`/`pwritev`) with completion posted back to
43 the scheduler. On Windows, true overlapped I/O is used via IOCP.
44
45 On Windows, while the file is open, its handle is bound to the
46 execution context's completion port. Every overlapped call on the
47 handle queues a packet to that port. Do not issue your own
48 overlapped I/O on `native_handle()` (`DeviceIoControl`,
49 `ReadFile`) unless the `OVERLAPPED`'s `hEvent` has its low-order
50 bit set, which suppresses the packet.
51
52 @par Thread Safety
53 Distinct objects: Safe.@n
54 Shared objects: Unsafe. Only one asynchronous operation
55 may be in flight at a time.
56
57 @par Example
58 @par !example stream_file
59 */
60 class BOOST_COROSIO_DECL stream_file : public io_stream
61 {
62 public:
63 /** Defines the file operations a platform backend implements.
64
65 Backends derive from this to provide file I/O.
66 `read_some` and `write_some` are inherited from
67 @ref io_stream::implementation.
68 */
69 struct implementation : io_stream::implementation
70 {
71 /// Return the platform file descriptor or handle.
72 virtual native_handle_type native_handle() const noexcept = 0;
73
74 /// Cancel pending asynchronous operations.
75 virtual void cancel() noexcept = 0;
76
77 /** Return the file size in bytes.
78
79 @return The current size of the file, in bytes.
80
81 @throws std::system_error if the underlying size query fails.
82 */
83 virtual std::uint64_t size() const = 0;
84
85 /** Resize the file to @p new_size bytes.
86
87 @param new_size The requested size in bytes.
88
89 @return The error code, empty on success.
90 */
91 virtual std::error_code resize(std::uint64_t new_size) noexcept = 0;
92
93 /** Synchronize file data to stable storage.
94
95 @return The error code, empty on success.
96 */
97 virtual std::error_code sync_data() noexcept = 0;
98
99 /** Synchronize file data and metadata to stable storage.
100
101 @return The error code, empty on success.
102 */
103 virtual std::error_code sync_all() noexcept = 0;
104
105 /** Release ownership of the native handle.
106
107 @return The native handle, which the caller now owns.
108
109 @throws std::system_error if the file is not open.
110 */
111 virtual native_handle_type release() = 0;
112
113 /** Adopt an existing native handle.
114
115 @param handle The native handle to adopt. The implementation takes
116 ownership and closes it.
117
118 @return The error code, empty on success.
119 */
120 virtual std::error_code assign(native_handle_type handle) noexcept = 0;
121
122 /** Move the file position.
123
124 @param offset Signed offset from @p origin.
125 @param origin The reference point for the seek.
126 @return The error code and new absolute position.
127 */
128 virtual capy::io_result<std::uint64_t>
129 seek(std::int64_t offset, file_base::seek_basis origin) noexcept = 0;
130 };
131
132 /** Closes the file if open, cancelling any pending operations.
133 */
134 ~stream_file() override;
135
136 /** Construct from an execution context.
137
138 @param ctx The execution context that owns this file.
139 */
140 explicit stream_file(capy::execution_context& ctx);
141
142 /** Construct from an executor.
143
144 @param ex The executor whose context owns this file.
145 */
146 template<class Ex>
147 requires(!std::same_as<std::remove_cvref_t<Ex>, stream_file>) &&
148 capy::Executor<Ex>
149 2x explicit stream_file(Ex const& ex) : stream_file(ex.context())
150 {
151 2x }
152
153 /** Transfers ownership of the file resources.
154 */
155 2x stream_file(stream_file&& other) noexcept : io_object(std::move(other)) {}
156
157 /** Closes any existing file and transfers ownership.
158
159 @return Reference to this object.
160 */
161 2x stream_file& operator=(stream_file&& other) noexcept
162 {
163
1/2
✗ Branch 0 not taken.
✓ Branch 1 taken 2 times.
 2x if (this != &other)
164 {
165 2x close();
166 2x h_ = std::move(other.h_);
167 2x }
168 2x return *this;
169 }
170
171 /// Copy construction is disabled; the handle is uniquely owned.
172 stream_file(stream_file const&) = delete;
173 /// Copy assignment is disabled; the handle is uniquely owned.
174 stream_file& operator=(stream_file const&) = delete;
175
176 // read_some() inherited from io_read_stream
177 // write_some() inherited from io_write_stream
178
179 /** Open a file.
180
181 Failures such as a missing file or insufficient permissions
182 are expected runtime conditions and are reported through the
183 returned error code. If the file is already open, it is
184 closed first.
185
186 @param path The filesystem path to open.
187 @param mode Bitmask of @ref file_base::flags specifying
188 access mode and creation behavior.
189
190 @return The error code, empty on success.
191 */
192 [[nodiscard]] std::error_code open(
193 std::filesystem::path const& path,
194 file_base::flags mode = file_base::read_only) noexcept;
195
196 /** Close the file.
197
198 Releases file resources. Pending operations complete through the
199 same path as @ref cancel: one still in flight completes with
200 `errc::operation_canceled`. An operation whose result is already
201 decided reports that result.
202 */
203 void close() noexcept;
204
205 /** Check if the file is open.
206
207 @return `true` if the file is open and ready for I/O.
208 */
209 2712x bool is_open() const noexcept
210 {
211 #if BOOST_COROSIO_HAS_IOCP && !defined(BOOST_COROSIO_MRDOCS)
212 return h_ && get().native_handle() != ~native_handle_type(0);
213 #else
214
2/2
✓ Branch 0 taken 4 times.
✓ Branch 1 taken 2634 times.
 2712x return h_ && get().native_handle() >= 0;
215 #endif
216 }
217
218 /** Cancel pending asynchronous operations.
219
220 Operations still in flight complete with
221 `errc::operation_canceled`; an operation whose result is
222 already decided reports that result.
223 */
224 void cancel() noexcept;
225
226 /** Get the native file descriptor or handle.
227
228 @return The native handle, or -1/INVALID_HANDLE_VALUE
229 if not open.
230 */
231 native_handle_type native_handle() const noexcept;
232
233 /** Return the file size in bytes.
234
235 @return The file size in bytes.
236
237 @throws std::system_error If the file is not open, or if the
238 underlying size query fails.
239 */
240 std::uint64_t size() const;
241
242 /** Resize the file to @p new_size bytes.
243
244 Failures such as insufficient disk space are reported
245 through the returned error code. A closed file reports
246 `errc::bad_file_descriptor`.
247
248 @param new_size The new file size.
249
250 @return The error code, empty on success.
251 */
252 [[nodiscard]] std::error_code resize(std::uint64_t new_size) noexcept;
253
254 /** Synchronize file data to stable storage.
255
256 Write-back failures such as device I/O errors surface here
257 and are reported through the returned error code. A closed
258 file reports `errc::bad_file_descriptor`.
259
260 @return The error code, empty on success.
261 */
262 [[nodiscard]] std::error_code sync_data() noexcept;
263
264 /** Synchronize file data and metadata to stable storage.
265
266 Write-back failures such as device I/O errors surface here
267 and are reported through the returned error code. A closed
268 file reports `errc::bad_file_descriptor`.
269
270 @return The error code, empty on success.
271 */
272 [[nodiscard]] std::error_code sync_all() noexcept;
273
274 /** Release ownership of the native handle.
275
276 The file object becomes not-open. The caller is
277 responsible for closing the returned handle.
278
279 `release()` cancels pending operations first. On Windows, the
280 object keeps the handle and this throws if one is still in
281 flight. It does the same if Windows refuses to detach the
282 handle from the execution context's completion port. Call
283 `release()` again once the cancelled operations have
284 completed. Detaching requires Windows 8.1 or later.
285
286 @return The native file descriptor or handle.
287
288 @throws std::system_error `errc::bad_file_descriptor` if the
289 file is not open. On Windows,
290 `errc::device_or_resource_busy` if an operation is still in
291 flight, or `errc::operation_not_supported` if the handle
292 cannot be detached.
293 */
294 native_handle_type release();
295
296 /** Adopt an existing native handle.
297
298 The object must be closed. To replace a held file, `close()`
299 or `release()` it first. On success the object takes
300 ownership of @p handle. Handles created elsewhere may be
301 unsuitable for asynchronous I/O. `assign()` reports most such
302 failures through the returned error code.
303
304 @param handle The native file descriptor or handle.
305
306 @return An error code describing the outcome.
307 `error::already_open` if this object is open.
308 `errc::bad_file_descriptor` if @p handle is invalid.
309 `errc::operation_not_supported` if a file object cannot
310 use it. On Windows, the rejected handles are a pipe, a
311 socket, a console, a directory, a handle opened without
312 `FILE_FLAG_OVERLAPPED`, or one
313 already in skip-completion-port-on-success mode. On
314 Windows, `errc::invalid_argument` when @p handle is
315 bound to another completion port. Any other failure is
316 the code reported by the system. Otherwise, the code is
317 empty.
318
319 @par Exception Safety
320 Throws nothing. On failure the object is unchanged and the
321 caller still owns @p handle.
322
323 @note On POSIX, the rejected descriptors are, in practice, a
324 directory, a pipe, a socket, or any other anonymous inode.
325 Adopt a pipe, a socket, or an anonymous inode into a
326 @ref posix_stream_descriptor instead. `assign()` accepts a
327 non-seekable character device such as a tty. Its first
328 read or write then fails with `ESPIPE` on the epoll,
329 kqueue, and select I/O backends.
330
331 @see release
332 */
333 [[nodiscard]] std::error_code assign(native_handle_type handle) noexcept;
334
335 /** Move the file position.
336
337 Positions beyond the end of the file are allowed. A
338 resulting negative position is reported through the error
339 code, as offsets often originate from file contents. A
340 closed file reports `errc::bad_file_descriptor`.
341
342 @param offset Signed offset from @p origin.
343 @param origin The reference point for the seek.
344
345 @return The error code and new absolute position.
346 */
347 [[nodiscard]] capy::io_result<std::uint64_t> seek(
348 std::int64_t offset,
349 file_base::seek_basis origin = file_base::seek_set) noexcept;
350
351 protected:
352 /// Default-construct (for derived types that initialize `io_object` directly).
353 16x stream_file() noexcept = default;
354
355 /** Construct from a pre-built handle (for `native_stream_file`).
356
357 @param h The pre-built handle to adopt.
358 */
359 explicit stream_file(handle h) noexcept : io_object(std::move(h)) {}
360
361 private:
362 4198x inline implementation& get() const noexcept
363 {
364 4198x return *static_cast<implementation*>(h_.get());
365 }
366 };
367
368 } // namespace boost::corosio
369
370 #endif // BOOST_COROSIO_STREAM_FILE_HPP
371