TLA  Line data    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_IO_IO_READ_STREAM_HPP
      11                 : #define BOOST_COROSIO_IO_IO_READ_STREAM_HPP
      12                 : 
      13                 : #include <boost/corosio/detail/config.hpp>
      14                 : #include <boost/corosio/detail/op_base.hpp>
      15                 : #include <boost/corosio/io/io_object.hpp>
      16                 : #include <boost/corosio/detail/buffer_param.hpp>
      17                 : #include <boost/capy/io_result.hpp>
      18                 : #include <boost/capy/ex/executor_ref.hpp>
      19                 : #include <boost/capy/ex/io_env.hpp>
      20                 : 
      21                 : #include <coroutine>
      22                 : #include <cstddef>
      23                 : #include <stop_token>
      24                 : #include <system_error>
      25                 : 
      26                 : namespace boost::corosio {
      27                 : 
      28                 : /** Abstract base for streams that support async reads.
      29                 : 
      30                 :     Provides the `read_some` operation via a pure virtual
      31                 :     `do_read_some` dispatch point. Concrete classes override
      32                 :     `do_read_some` to route through their implementation.
      33                 : 
      34                 :     Uses virtual inheritance from @ref io_object so that
      35                 :     @ref io_stream can combine this with @ref io_write_stream
      36                 :     without duplicating the `io_object` base.
      37                 : 
      38                 :     @par Thread Safety
      39                 :     Distinct objects: Safe.
      40                 :     Shared objects: Unsafe.
      41                 : 
      42                 :     @see io_write_stream, io_stream, io_object
      43                 : */
      44                 : class BOOST_COROSIO_DECL io_read_stream : virtual public io_object
      45                 : {
      46                 : protected:
      47                 :     /// Awaitable for async read operations.
      48                 :     template<class MutableBufferSequence>
      49                 :     struct read_some_awaitable
      50                 :         : detail::bytes_op_base<read_some_awaitable<MutableBufferSequence>>
      51                 :     {
      52                 :         io_read_stream& ios_;
      53                 :         MutableBufferSequence buffers_;
      54                 : 
      55 HIT      203131 :         read_some_awaitable(
      56                 :             io_read_stream& ios, MutableBufferSequence buffers) noexcept
      57          203131 :             : ios_(ios)
      58          203131 :             , buffers_(std::move(buffers))
      59                 :         {
      60          203131 :         }
      61                 : 
      62                 :         std::coroutine_handle<>
      63          203131 :         dispatch(std::coroutine_handle<> h, capy::executor_ref ex) const
      64                 :         {
      65          406262 :             return ios_.do_read_some(
      66          609393 :                 h, ex, buffers_, this->token_, &this->ec_, &this->bytes_);
      67                 :         }
      68                 :     };
      69                 : 
      70                 :     /** Dispatch a read through the concrete implementation.
      71                 : 
      72                 :         @param h Coroutine handle to resume on completion.
      73                 :         @param ex Executor for dispatching the completion.
      74                 :         @param buffers Target buffer sequence.
      75                 :         @param token Stop token for cancellation.
      76                 :         @param ec Output error code.
      77                 :         @param bytes Output bytes transferred.
      78                 : 
      79                 :         @return Coroutine handle to resume immediately.
      80                 :     */
      81                 :     virtual std::coroutine_handle<> do_read_some(
      82                 :         std::coroutine_handle<>,
      83                 :         capy::executor_ref,
      84                 :         buffer_param,
      85                 :         std::stop_token,
      86                 :         std::error_code*,
      87                 :         std::size_t*) = 0;
      88                 : 
      89           10480 :     io_read_stream() noexcept = default;
      90                 : 
      91                 :     io_read_stream(io_read_stream&&) noexcept            = default;
      92                 :     io_read_stream& operator=(io_read_stream&&) noexcept = delete;
      93                 :     io_read_stream(io_read_stream const&)                = delete;
      94                 :     io_read_stream& operator=(io_read_stream const&)     = delete;
      95                 : 
      96                 : public:
      97                 :     /** Asynchronously read data from the stream.
      98                 : 
      99                 :         Suspends the calling coroutine and initiates a kernel-level
     100                 :         read. The coroutine resumes when at least one byte is read,
     101                 :         an error occurs, or the operation is cancelled.
     102                 : 
     103                 :         This stream must outlive the returned awaitable. The memory
     104                 :         referenced by @p buffers must remain valid until the operation
     105                 :         completes.
     106                 : 
     107                 :         A closed stream completes with `errc::bad_file_descriptor`.
     108                 : 
     109                 :         @param buffers The buffer sequence to read data into.
     110                 : 
     111                 :         @return An awaitable yielding `(error_code, std::size_t)`.
     112                 : 
     113                 :         @see io_stream::write_some
     114                 :     */
     115                 :     template<capy::MutableBufferSequence MB>
     116          203131 :     [[nodiscard]] auto read_some(MB const& buffers)
     117                 :     {
     118          203131 :         return read_some_awaitable<MB>(*this, buffers);
     119                 :     }
     120                 : };
     121                 : 
     122                 : } // namespace boost::corosio
     123                 : 
     124                 : #endif