uvco::StreamBase Class Reference

A plain stream, permitting reading, writing, and closing. More...

#include <stream.h>

Inheritance diagram for uvco::StreamBase:

Classes
struct	InStreamAwaiter_
struct	OutStreamAwaiter_
struct	ShutdownAwaiter_

Public Member Functions
template<typename Stream >
	StreamBase (std::unique_ptr< Stream > stream)
	StreamBase (const StreamBase &)=delete
	StreamBase (StreamBase &&)=default
StreamBase &	operator= (const StreamBase &)=delete
StreamBase &	operator= (StreamBase &&)=default
virtual	~StreamBase ()
Promise< std::optional< std::string > >	read (size_t maxSize=defaultMaxReadSize)
Promise< size_t >	read (std::span< char > buffer)
Promise< size_t >	write (std::string buf)
Promise< void >	shutdown ()
Promise< void >	close ()
const uv_stream_t *	underlying () const
	Return the underlying UV stream object.

Static Public Attributes
static constexpr size_t	defaultMaxReadSize = 4096

Protected Member Functions
uv_stream_t &	stream ()
void	destroyStream ()

Private Attributes
std::unique_ptr< uv_stream_t, UvHandleDeleter >	stream_
std::optional< std::coroutine_handle<> >	reader_
std::optional< std::coroutine_handle<> >	writer_

Detailed Description

A plain stream, permitting reading, writing, and closing.

Constructor & Destructor Documentation

StreamBase() [1/3]

template<typename Stream >

uvco::StreamBase::StreamBase ( std::unique_ptr< Stream >  stream )

inlineexplicit

      : stream_{(uv_stream_t *)stream.release()} {}

StreamBase() [2/3]

uvco::StreamBase::StreamBase ( const StreamBase &  )

delete

StreamBase() [3/3]

uvco::StreamBase::StreamBase ( StreamBase &&  )

default

~StreamBase()

uvco::StreamBase::~StreamBase ( )

virtual

                        {
  // close() MUST be called and awaited before dtor.
  if (stream_) {
    fmt::print(stderr, "StreamBase::~StreamBase(): closing stream in dtor; "
                       "this will leak memory. "
                       "Please co_await stream.close() if possible.\n");
    // Asynchronously close handle. It's better to leak memory than file
    // descriptors.
    closeHandle(stream_.release());
  }
}

Member Function Documentation

close()

Promise< void > uvco::StreamBase::close

(

)

The result of close() must be co_awaited; otherwise memory may be leaked. (this is not an issue just before termination of a process)

Informs pending readers and writers of the close and causes them to return an empty optional.

                                {
  auto stream = std::move(stream_);
  co_await closeHandle(stream.get());
  if (reader_) {
    const auto reader = *reader_;
    reader_.reset();
    Loop::enqueue(reader);
  }
  if (writer_) {
    const auto writer = *writer_;
    writer_.reset();
    Loop::enqueue(writer);
  }
}

destroyStream()

void uvco::StreamBase::destroyStream ( )

inlineprotected

                       {
    BOOST_ASSERT(stream_);
    stream_.reset();
  }

operator=() [1/2]

StreamBase & uvco::StreamBase::operator= ( const StreamBase &  )

delete

operator=() [2/2]

StreamBase & uvco::StreamBase::operator= ( StreamBase &&  )

default

read() [1/2]

Promise< std::optional< std::string > > uvco::StreamBase::read

(

size_t

maxSize = defaultMaxReadSize

)

Read available data (up to maxSize bytes) from stream. Returns std::nullopt on EOF or closed handle (close()).

Throws UvcoException on error.

NOTE: Consider using read(std::span<char>) for better performance.

NOTE: only one reader is allowed to be active at a time. If a read is started while another is still active, uvco will abort the process (in Debug mode), or ignore the first read (in Release mode).

                                                               {
  // This is a promise root function, i.e. origin of a promise.
  std::string buf(maxSize, '\0');
  InStreamAwaiter_ awaiter{*this, buf};
  const size_t nRead = co_await awaiter;
  if (nRead == 0) {
    // EOF.
    co_return std::nullopt;
  }
  buf.resize(nRead);
  co_return buf;
}

read() [2/2]

Promise< size_t > uvco::StreamBase::read

(

std::span< char >

buffer

)

Read available data (up to buffer.size() bytes) from stream. Returns the number of bytes read, or 0 on EOF or closed handle (close()).

Only one read() coroutine may be active at a time.

Throws UvcoException on error.

                                                     {
  InStreamAwaiter_ awaiter{*this, buffer};
  size_t n = co_await awaiter;
  co_return n;
}

shutdown()

Promise< void > uvco::StreamBase::shutdown

(

)

Shut down stream for writing. This is a half-close; the other side can still write. The result of shutdown() must be co_awaited.

                                   {
  uv_shutdown_t shutdownReq;
  ShutdownAwaiter_ awaiter;
 
  shutdownReq.data = &awaiter;
  uv_shutdown(&shutdownReq, &stream(),
              StreamBase::ShutdownAwaiter_::onShutdown);
  co_await awaiter;
  co_return;
}

stream()

uv_stream_t & uvco::StreamBase::stream ( )

inlineprotected

                        {
    BOOST_ASSERT(stream_);
    return *stream_;
  }

underlying()

const uv_stream_t * uvco::StreamBase::underlying ( ) const

inline

Return the underlying UV stream object.

{ return stream_.get(); }

write()

Promise< size_t > uvco::StreamBase::write

(

std::string

buf

)

Write a buffer to the stream. A copy of buf is taken because it is undetermined when the actual write will occur. Await the result if the status is important; the write will be executed even without awaiting (as long as the process keeps running).

NOTE: only one writer is allowed to be active at a time. If two writes are started simultaneously, the process will be aborted in Debug mode, or the first write() coroutine will not return in Release mode.

                                               {
  OutStreamAwaiter_ awaiter{*this, std::move(buf)};
  uv_status status = co_await awaiter;
  if (status < 0) {
    throw UvcoException{status, "StreamBase::write() encountered error"};
  }
  co_return static_cast<size_t>(status);
}

Member Data Documentation

defaultMaxReadSize

constexpr size_t uvco::StreamBase::defaultMaxReadSize = 4096

staticconstexpr

reader_

std::optional<std::coroutine_handle<> > uvco::StreamBase::reader_

private

stream_

std::unique_ptr<uv_stream_t, UvHandleDeleter> uvco::StreamBase::stream_

private

writer_

std::optional<std::coroutine_handle<> > uvco::StreamBase::writer_

private

---

The documentation for this class was generated from the following files:

• uvco/stream.h
• uvco/stream.cc