Index/include / boost / corosio / io / io_stream.hpp

include/boost/corosio/io/io_stream.hpp

100.0% Lines (7/0/7) 100.0% List of functions (4/0/4)
[ ] prev/next file
io_stream.hpp
f(x) Functions (4)
Function Calls Lines Blocks
boost::corosio::io_stream::io_stream() :92 10480x 100.0% 100.0% boost::corosio::io_stream::do_read_some(std::__n4861::coroutine_handle<void>, boost::capy::executor_ref, boost::corosio::buffer_param, std::stop_token, std::error_code*, unsigned long*) :98 203131x 100.0% 82.0% boost::corosio::io_stream::do_write_some(std::__n4861::coroutine_handle<void>, boost::capy::executor_ref, boost::corosio::buffer_param, std::stop_token, std::error_code*, unsigned long*) :110 202386x 100.0% 82.0% boost::corosio::io_stream::get() const :123 405517x 100.0% 100.0%
Line TLA Hits Source Code
1 //
2 // Copyright (c) 2025 Vinnie Falco (vinnie.falco@gmail.com)
3 // Copyright (c) 2026 Steve Gerbino
4 // Copyright (c) 2026 Michael Vandeberg
5 //
6 // Distributed under the Boost Software License, Version 1.0. (See accompanying
7 // file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
8 //
9 // Official repository: https://github.com/cppalliance/corosio
10 //
11
12 #ifndef BOOST_COROSIO_IO_IO_STREAM_HPP
13 #define BOOST_COROSIO_IO_IO_STREAM_HPP
14
15 #include <boost/corosio/detail/config.hpp>
16 #include <boost/corosio/io/io_read_stream.hpp>
17 #include <boost/corosio/io/io_write_stream.hpp>
18 #include <boost/corosio/detail/buffer_param.hpp>
19 #include <boost/capy/ex/executor_ref.hpp>
20
21 #include <coroutine>
22 #include <cstddef>
23 #include <stop_token>
24 #include <system_error>
25
26 namespace boost::corosio {
27
28 /** Platform stream with read/write operations.
29
30 Combines @ref io_read_stream and @ref io_write_stream into
31 a single bidirectional stream. The `read_some` and `write_some`
32 operations are inherited from the base classes and dispatch
33 through `do_read_some` / `do_write_some`, which this class
34 implements by forwarding to the platform `implementation`.
35
36 The implementation hierarchy stays linear (no diamond):
37 `io_object::implementation` -> `io_stream::implementation`
38 -> `tcp_socket::implementation` -> backend impl.
39
40 @par Semantics
41 Concrete classes wrap direct platform I/O completed by the kernel.
42 Functions taking `io_stream&` signal "platform implementation
43 required" - use this when you need actual kernel I/O rather than
44 a mock or test double.
45
46 For generic stream algorithms that work with test mocks,
47 use `template<capy::Stream S>` instead of `io_stream&`.
48
49 @par Thread Safety
50 Distinct objects: Safe.
51 Shared objects: Unsafe. All calls to a single stream must be made
52 from the same implicit or explicit serialization context.
53
54 @par Example
55 @par !example io_stream
56
57 @see io_read_stream, io_write_stream, tcp_socket
58 */
59 class BOOST_COROSIO_DECL io_stream
60 : public io_read_stream
61 , public io_write_stream
62 {
63 public:
64 /** Platform-specific stream implementation interface.
65
66 Derived classes implement this interface to provide kernel-level
67 read and write operations for each supported platform (IOCP,
68 epoll, kqueue, io_uring).
69 */
70 struct implementation : io_object::implementation
71 {
72 /// Initiate platform read operation.
73 virtual std::coroutine_handle<> read_some(
74 std::coroutine_handle<>,
75 capy::executor_ref,
76 buffer_param,
77 std::stop_token,
78 std::error_code*,
79 std::size_t*) = 0;
80
81 /// Initiate platform write operation.
82 virtual std::coroutine_handle<> write_some(
83 std::coroutine_handle<>,
84 capy::executor_ref,
85 buffer_param,
86 std::stop_token,
87 std::error_code*,
88 std::size_t*) = 0;
89 };
90
91 protected:
92 10480x io_stream() noexcept = default;
93
94 /// Construct stream from a handle.
95 explicit io_stream(handle h) noexcept : io_object(std::move(h)) {}
96
97 /// Dispatch read through implementation vtable.
98 203131x std::coroutine_handle<> do_read_some(
99 std::coroutine_handle<> h,
100 capy::executor_ref ex,
101 buffer_param buffers,
102 std::stop_token token,
103 std::error_code* ec,
104 std::size_t* bytes) override
105 {
106 203131x return get().read_some(h, ex, buffers, std::move(token), ec, bytes);
107 }
108
109 /// Dispatch write through implementation vtable.
110 202386x std::coroutine_handle<> do_write_some(
111 std::coroutine_handle<> h,
112 capy::executor_ref ex,
113 buffer_param buffers,
114 std::stop_token token,
115 std::error_code* ec,
116 std::size_t* bytes) override
117 {
118 202386x return get().write_some(h, ex, buffers, std::move(token), ec, bytes);
119 }
120
121 private:
122 /// Return implementation downcasted to stream interface.
123 405517x implementation& get() const noexcept
124 {
125 405517x return *static_cast<implementation*>(h_.get());
126 }
127 };
128
129 } // namespace boost::corosio
130
131 #endif
132