. /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 - /** Platform stream with read/write operations. 28 + /** Reads and writes bytes through a platform I/O backend.
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 32 + operations are inherited from the base classes and dispatch through
33 - through `do_read_some` / `do_write_some`, which this class 33 + `do_read_some` / `do_write_some`. This class implements those by
34 - implements by forwarding to the platform `implementation`. 34 + 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 "platform implementation 42 + Functions taking `io_stream&` signal that platform implementation
43 - required" - use this when you need actual kernel I/O rather than 43 + is 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 - /** Platform-specific stream implementation interface. 64 + /** Declares the read and write operations a platform backend
  65 + must implement.
65   66  
66   Derived classes implement this interface to provide kernel-level 67   Derived classes implement this interface to provide kernel-level
67   read and write operations for each supported platform (IOCP, 68   read and write operations for each supported platform (IOCP,
68   epoll, kqueue, io_uring). 69   epoll, kqueue, io_uring).
69   */ 70   */
70   struct implementation : io_object::implementation 71   struct implementation : io_object::implementation
71   { 72   {
72 - /// Initiate platform read operation. 73 + /** 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 + */
73   virtual std::coroutine_handle<> read_some( 84   virtual std::coroutine_handle<> read_some(
74 - std::coroutine_handle<>, 85 + std::coroutine_handle<> h,
75 - capy::executor_ref, 86 + capy::executor_ref ex,
76 - buffer_param, 87 + buffer_param buffers,
77 - std::stop_token, 88 + std::stop_token token,
78 - std::error_code*, 89 + std::error_code* ec,
79 - std::size_t*) = 0; 90 + std::size_t* bytes) = 0;
80   91  
81 - /// Initiate platform write operation. 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 +
  101 + @return Coroutine handle to resume immediately.
  102 + */
82   virtual std::coroutine_handle<> write_some( 103   virtual std::coroutine_handle<> write_some(
83 - std::coroutine_handle<>, 104 + std::coroutine_handle<> h,
84 - capy::executor_ref, 105 + capy::executor_ref ex,
85 - buffer_param, 106 + buffer_param buffers,
86 - std::stop_token, 107 + std::stop_token token,
87 - std::error_code*, 108 + std::error_code* ec,
88 - std::size_t*) = 0; 109 + std::size_t* bytes) = 0;
89   }; 110   };
90   111  
91   protected: 112   protected:
  113 + /// Default construct; the handle is supplied through @ref io_object.
HITCBC 92   10088 io_stream() noexcept = default; 114   7142 io_stream() noexcept = default;
93   115  
94   /// Construct stream from a handle. 116   /// Construct stream from a handle.
95   explicit io_stream(handle h) noexcept : io_object(std::move(h)) {} 117   explicit io_stream(handle h) noexcept : io_object(std::move(h)) {}
96   118  
97 - /// Dispatch read through implementation vtable. 119 + /** 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 98   201973 std::coroutine_handle<> do_read_some( 130   198254 std::coroutine_handle<> do_read_some(
99   std::coroutine_handle<> h, 131   std::coroutine_handle<> h,
100   capy::executor_ref ex, 132   capy::executor_ref ex,
101   buffer_param buffers, 133   buffer_param buffers,
102   std::stop_token token, 134   std::stop_token token,
103   std::error_code* ec, 135   std::error_code* ec,
104   std::size_t* bytes) override 136   std::size_t* bytes) override
105   { 137   {
HITCBC 106   201973 return get().read_some(h, ex, buffers, std::move(token), ec, bytes); 138   198254 return get().read_some(h, ex, buffers, std::move(token), ec, bytes);
107   } 139   }
108   140  
109 - /// Dispatch write through implementation vtable. 141 + /** 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 110   201190 std::coroutine_handle<> do_write_some( 152   197515 std::coroutine_handle<> do_write_some(
111   std::coroutine_handle<> h, 153   std::coroutine_handle<> h,
112   capy::executor_ref ex, 154   capy::executor_ref ex,
113   buffer_param buffers, 155   buffer_param buffers,
114   std::stop_token token, 156   std::stop_token token,
115   std::error_code* ec, 157   std::error_code* ec,
116   std::size_t* bytes) override 158   std::size_t* bytes) override
117   { 159   {
HITCBC 118   201190 return get().write_some(h, ex, buffers, std::move(token), ec, bytes); 160   197515 return get().write_some(h, ex, buffers, std::move(token), ec, bytes);
119   } 161   }
120   162  
121   private: 163   private:
122   /// Return implementation downcasted to stream interface. 164   /// Return implementation downcasted to stream interface.
HITCBC 123   403163 implementation& get() const noexcept 165   395769 implementation& get() const noexcept
124   { 166   {
HITCBC 125   403163 return *static_cast<implementation*>(h_.get()); 167   395769 return *static_cast<implementation*>(h_.get());
126   } 168   }
127   }; 169   };
128   170  
129   } // namespace boost::corosio 171   } // namespace boost::corosio
130   172  
131   #endif 173   #endif