. /include/boost/corosio /io /io_stream.hpp
100.00% Lines (7/7) 100.00% Functions (4/4)
[ ] prev/next file n p prev/next uncovered line
TLA Baseline Branch
Line Hits Code Line Hits Code
1   // 1   //
2   // Copyright (c) 2025 Vinnie Falco (vinnie.falco@gmail.com) 2   // Copyright (c) 2025 Vinnie Falco (vinnie.falco@gmail.com)
3   // Copyright (c) 2026 Steve Gerbino 3   // Copyright (c) 2026 Steve Gerbino
4   // Copyright (c) 2026 Michael Vandeberg 4   // Copyright (c) 2026 Michael Vandeberg
5   // 5   //
6   // Distributed under the Boost Software License, Version 1.0. (See accompanying 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) 7   // file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
8   // 8   //
9   // Official repository: https://github.com/cppalliance/corosio 9   // Official repository: https://github.com/cppalliance/corosio
10   // 10   //
11   11  
12   #ifndef BOOST_COROSIO_IO_IO_STREAM_HPP 12   #ifndef BOOST_COROSIO_IO_IO_STREAM_HPP
13   #define BOOST_COROSIO_IO_IO_STREAM_HPP 13   #define BOOST_COROSIO_IO_IO_STREAM_HPP
14   14  
15   #include <boost/corosio/detail/config.hpp> 15   #include <boost/corosio/detail/config.hpp>
16   #include <boost/corosio/io/io_read_stream.hpp> 16   #include <boost/corosio/io/io_read_stream.hpp>
17   #include <boost/corosio/io/io_write_stream.hpp> 17   #include <boost/corosio/io/io_write_stream.hpp>
18   #include <boost/corosio/detail/buffer_param.hpp> 18   #include <boost/corosio/detail/buffer_param.hpp>
19   #include <boost/capy/ex/executor_ref.hpp> 19   #include <boost/capy/ex/executor_ref.hpp>
20   20  
21   #include <coroutine> 21   #include <coroutine>
22   #include <cstddef> 22   #include <cstddef>
23   #include <stop_token> 23   #include <stop_token>
24   #include <system_error> 24   #include <system_error>
25   25  
26   namespace boost::corosio { 26   namespace boost::corosio {
27   27  
28 - /** Reads and writes bytes through a platform I/O backend. 28 + /** Platform stream with read/write operations.
29   29  
30   Combines @ref io_read_stream and @ref io_write_stream into 30   Combines @ref io_read_stream and @ref io_write_stream into
31   a single bidirectional stream. The `read_some` and `write_some` 31   a single bidirectional stream. The `read_some` and `write_some`
32 - operations are inherited from the base classes and dispatch through 32 + operations are inherited from the base classes and dispatch
33 - `do_read_some` / `do_write_some`. This class implements those by 33 + through `do_read_some` / `do_write_some`, which this class
34 - forwarding to the platform `implementation`. 34 + implements by forwarding to the platform `implementation`.
35   35  
36   The implementation hierarchy stays linear (no diamond): 36   The implementation hierarchy stays linear (no diamond):
37   `io_object::implementation` -> `io_stream::implementation` 37   `io_object::implementation` -> `io_stream::implementation`
38   -> `tcp_socket::implementation` -> backend impl. 38   -> `tcp_socket::implementation` -> backend impl.
39   39  
40   @par Semantics 40   @par Semantics
41   Concrete classes wrap direct platform I/O completed by the kernel. 41   Concrete classes wrap direct platform I/O completed by the kernel.
42 - Functions taking `io_stream&` signal that platform implementation 42 + Functions taking `io_stream&` signal "platform implementation
43 - is required. Use this when you need actual kernel I/O rather than 43 + required" - use this when you need actual kernel I/O rather than
44   a mock or test double. 44   a mock or test double.
45   45  
46   For generic stream algorithms that work with test mocks, 46   For generic stream algorithms that work with test mocks,
47   use `template<capy::Stream S>` instead of `io_stream&`. 47   use `template<capy::Stream S>` instead of `io_stream&`.
48   48  
49   @par Thread Safety 49   @par Thread Safety
50   Distinct objects: Safe. 50   Distinct objects: Safe.
51   Shared objects: Unsafe. All calls to a single stream must be made 51   Shared objects: Unsafe. All calls to a single stream must be made
52   from the same implicit or explicit serialization context. 52   from the same implicit or explicit serialization context.
53   53  
54   @par Example 54   @par Example
55   @par !example io_stream 55   @par !example io_stream
56   56  
57   @see io_read_stream, io_write_stream, tcp_socket 57   @see io_read_stream, io_write_stream, tcp_socket
58   */ 58   */
59   class BOOST_COROSIO_DECL io_stream 59   class BOOST_COROSIO_DECL io_stream
60   : public io_read_stream 60   : public io_read_stream
61   , public io_write_stream 61   , public io_write_stream
62   { 62   {
63   public: 63   public:
64 - /** Declares the read and write operations a platform backend 64 + /** Platform-specific stream implementation interface.
65 - must implement.  
66   65  
67   Derived classes implement this interface to provide kernel-level 66   Derived classes implement this interface to provide kernel-level
68   read and write operations for each supported platform (IOCP, 67   read and write operations for each supported platform (IOCP,
69   epoll, kqueue, io_uring). 68   epoll, kqueue, io_uring).
70   */ 69   */
71   struct implementation : io_object::implementation 70   struct implementation : io_object::implementation
72   { 71   {
73 - /** Initiate platform read operation. 72 + /// Initiate platform read operation.
74 -  
75 - @param h Coroutine handle to resume on completion.  
76 - @param ex Executor for dispatching the completion.  
77 - @param buffers Target buffer sequence.  
78 - @param token Stop token for cancellation.  
79 - @param ec Output error code.  
80 - @param bytes Output bytes transferred.  
81 -  
82 - @return Coroutine handle to resume immediately.  
83 - */  
84   virtual std::coroutine_handle<> read_some( 73   virtual std::coroutine_handle<> read_some(
85 - std::coroutine_handle<> h, 74 + std::coroutine_handle<>,
86 - capy::executor_ref ex, 75 + capy::executor_ref,
87 - buffer_param buffers, 76 + buffer_param,
88 - std::stop_token token, 77 + std::stop_token,
89 - std::error_code* ec, 78 + std::error_code*,
90 - std::size_t* bytes) = 0; 79 + std::size_t*) = 0;
91 -  
92 - /** Initiate platform write operation.  
93 -  
94 - @param h Coroutine handle to resume on completion.  
95 - @param ex Executor for dispatching the completion.  
96 - @param buffers Source buffer sequence.  
97 - @param token Stop token for cancellation.  
98 - @param ec Output error code.  
99 - @param bytes Output bytes transferred.  
100   80  
101 - @return Coroutine handle to resume immediately. 81 + /// Initiate platform write operation.
102 - */  
103   virtual std::coroutine_handle<> write_some( 82   virtual std::coroutine_handle<> write_some(
104 - std::coroutine_handle<> h, 83 + std::coroutine_handle<>,
105 - capy::executor_ref ex, 84 + capy::executor_ref,
106 - buffer_param buffers, 85 + buffer_param,
107 - std::stop_token token, 86 + std::stop_token,
108 - std::error_code* ec, 87 + std::error_code*,
109 - std::size_t* bytes) = 0; 88 + std::size_t*) = 0;
110   }; 89   };
111   90  
112 - /// Default construct; the handle is supplied through @ref io_object.  
113   protected: 91   protected:
HITCBC 114   10475 io_stream() noexcept = default; 92   10243 io_stream() noexcept = default;
115   93  
116   /// Construct stream from a handle. 94   /// Construct stream from a handle.
117   explicit io_stream(handle h) noexcept : io_object(std::move(h)) {} 95   explicit io_stream(handle h) noexcept : io_object(std::move(h)) {}
118   96  
119 - /** Dispatch read through implementation vtable. 97 + /// Dispatch read through implementation vtable.
120 -  
121 - @param h Coroutine handle to resume on completion.  
122 - @param ex Executor for dispatching the completion.  
123 - @param buffers Target buffer sequence.  
124 - @param token Stop token for cancellation.  
125 - @param ec Output error code.  
126 - @param bytes Output bytes transferred.  
127 -  
128 - @return Coroutine handle to resume immediately.  
129 - */  
HITCBC 130   210578 std::coroutine_handle<> do_read_some( 98   220771 std::coroutine_handle<> do_read_some(
131   std::coroutine_handle<> h, 99   std::coroutine_handle<> h,
132   capy::executor_ref ex, 100   capy::executor_ref ex,
133   buffer_param buffers, 101   buffer_param buffers,
134   std::stop_token token, 102   std::stop_token token,
135   std::error_code* ec, 103   std::error_code* ec,
136   std::size_t* bytes) override 104   std::size_t* bytes) override
137   { 105   {
HITCBC 138   210578 return get().read_some(h, ex, buffers, std::move(token), ec, bytes); 106   220771 return get().read_some(h, ex, buffers, std::move(token), ec, bytes);
139   } 107   }
140   108  
141 - /** Dispatch write through implementation vtable. 109 + /// Dispatch write through implementation vtable.
142 -  
143 - @param h Coroutine handle to resume on completion.  
144 - @param ex Executor for dispatching the completion.  
145 - @param buffers Source buffer sequence.  
146 - @param token Stop token for cancellation.  
147 - @param ec Output error code.  
148 - @param bytes Output bytes transferred.  
149 -  
150 - @return Coroutine handle to resume immediately.  
151 - */  
HITCBC 152   209824 std::coroutine_handle<> do_write_some( 110   219993 std::coroutine_handle<> do_write_some(
153   std::coroutine_handle<> h, 111   std::coroutine_handle<> h,
154   capy::executor_ref ex, 112   capy::executor_ref ex,
155   buffer_param buffers, 113   buffer_param buffers,
156   std::stop_token token, 114   std::stop_token token,
157   std::error_code* ec, 115   std::error_code* ec,
158   std::size_t* bytes) override 116   std::size_t* bytes) override
159   { 117   {
HITCBC 160   209824 return get().write_some(h, ex, buffers, std::move(token), ec, bytes); 118   219993 return get().write_some(h, ex, buffers, std::move(token), ec, bytes);
161   } 119   }
162   120  
163   private: 121   private:
164   /// Return implementation downcasted to stream interface. 122   /// Return implementation downcasted to stream interface.
HITCBC 165   420402 implementation& get() const noexcept 123   440764 implementation& get() const noexcept
166   { 124   {
HITCBC 167   420402 return *static_cast<implementation*>(h_.get()); 125   440764 return *static_cast<implementation*>(h_.get());
168   } 126   }
169   }; 127   };
170   128  
171   } // namespace boost::corosio 129   } // namespace boost::corosio
172   130  
173   #endif 131   #endif