Phosphor
Qt6 / Wayland library suite for window-management tools
Loading...
Searching...
No Matches
PhosphorChannel::Stream Class Reference

#include <PhosphorChannel/Stream.h>

Classes

struct  Options

Public Member Functions

 Stream (int readFd, int writeFd, Options options)
 Takes readFd and writeFd (the same fd for a socket), makes them non-blocking, and queues the hello.
 Stream (int fd)
 ~Stream ()
 Stream (const Stream &)=delete
Stream & operator= (const Stream &)=delete
StreamWriter * openWriter (std::uint32_t id, std::string codec, std::string *error)
 Opens channel id for writing.
StreamReader * reader (std::uint32_t id)
 The channel id that the other end opened, or nullptr.
int readFd () const
int writeFd () const
 -1 once the stream gave back an output fd separate from its input: after shutdown() got past its flush and ended the output, or after a failure that it tried to report to the other end.
bool wantsWrite () const
bool readable ()
 Reads what the fd has, up to a budget, and handles it.
bool writable ()
 Writes what waits. False when the stream failed.
bool pump (int timeoutMs)
 One round of poll on readFd(), and on writeFd() while wantsWrite(), up to timeoutMs.
bool flush (int timeoutMs)
 Writes until nothing waits, up to timeoutMs, and reads meanwhile.
bool shutdown (int timeoutMs)
 Ends the stream cleanly: flushes, ends this end's output, and reads until the other end ends too, up to timeoutMs.
bool ready () const
 The hello of the other end arrived, with this end's version.
bool open () const
 The stream works: no failure and no end of its input.
const std::string & error () const
 Why the stream failed. Empty while it works, and after a clean end.

Public Attributes

std::function< void(StreamReader &)> onReader
 The other end opened a channel.
std::function< void(StreamReader &)> onReadable
 A frame arrived on a reader, its writer closed it, or the stream ended or failed: read it until read() returns something other than Frame.
std::function< void(StreamWriter &)> onWritable
 A writer that returned WouldBlock may write again.

Static Public Attributes

static constexpr std::size_t FrameCost = 64
 What a frame costs against the window on top of its size, so that a window also bounds the number of small frames that wait.
static constexpr std::size_t MinWindow = 1024
 The smallest window.

Constructor & Destructor Documentation

◆ Stream() [1/3]

PhosphorChannel::Stream::Stream ( int readFd,
int writeFd,
Options options )

Takes readFd and writeFd (the same fd for a socket), makes them non-blocking, and queues the hello.

The non-blocking flag lives in the open file description, which other processes may share, as a shell shares its terminal: hand in fds that nothing else uses. Destruction restores the flag and closes the fds, except that it points a taken fd 0, 1 or 2 at /dev/null, so that the number stays taken.

◆ Stream() [2/3]

PhosphorChannel::Stream::Stream ( int fd)
inlineexplicit

◆ ~Stream()

PhosphorChannel::Stream::~Stream ( )

◆ Stream() [3/3]

PhosphorChannel::Stream::Stream ( const Stream & )
delete

Member Function Documentation

◆ error()

const std::string & PhosphorChannel::Stream::error ( ) const
inline

Why the stream failed. Empty while it works, and after a clean end.

◆ flush()

bool PhosphorChannel::Stream::flush ( int timeoutMs)

Writes until nothing waits, up to timeoutMs, and reads meanwhile.

False on a failure or the timeout: error() is empty after a timeout.

◆ open()

bool PhosphorChannel::Stream::open ( ) const
inline

The stream works: no failure and no end of its input.

After the other end ends its output, this end may still write until it fails.

◆ openWriter()

StreamWriter * PhosphorChannel::Stream::openWriter ( std::uint32_t id,
std::string codec,
std::string * error )

Opens channel id for writing.

The ids of each direction are apart: the other end may write on the same id. Nullptr with error for an id that is open or still closing, an id at or past the other end's maxChannelId, a bad codec, more channels than the other end takes, or a stream that cannot write. Before ready() the other end's limits are unknown: a writer opened then past one of them fails the stream when the hello comes. Opening an id again after its channel ended invalidates the old writer.

◆ operator=()

Stream & PhosphorChannel::Stream::operator= ( const Stream & )
delete

◆ pump()

bool PhosphorChannel::Stream::pump ( int timeoutMs)

One round of poll on readFd(), and on writeFd() while wantsWrite(), up to timeoutMs.

False when the stream failed, or its input ended and nothing waits to go out.

◆ readable()

bool PhosphorChannel::Stream::readable ( )

Reads what the fd has, up to a budget, and handles it.

Poll again while the fd stays readable. False when the input ended or the stream failed: error() says which.

◆ reader()

StreamReader * PhosphorChannel::Stream::reader ( std::uint32_t id)

The channel id that the other end opened, or nullptr.

◆ readFd()

int PhosphorChannel::Stream::readFd ( ) const
inline

◆ ready()

bool PhosphorChannel::Stream::ready ( ) const
inline

The hello of the other end arrived, with this end's version.

◆ shutdown()

bool PhosphorChannel::Stream::shutdown ( int timeoutMs)

Ends the stream cleanly: flushes, ends this end's output, and reads until the other end ends too, up to timeoutMs.

False on a failure or the timeout. Once it ended the output, no writer can write.

◆ wantsWrite()

bool PhosphorChannel::Stream::wantsWrite ( ) const

◆ writable()

bool PhosphorChannel::Stream::writable ( )

Writes what waits. False when the stream failed.

◆ writeFd()

int PhosphorChannel::Stream::writeFd ( ) const
inline

-1 once the stream gave back an output fd separate from its input: after shutdown() got past its flush and ended the output, or after a failure that it tried to report to the other end.

It reports every failure except one of its output, a closed fd that pump()'s poll found, the other end's own stop, and a refusal of the fds in the constructor. With one fd for both, as for a socket, this stays that fd. Otherwise the fd stays open until the stream is destroyed. Stop watching the old number once this is -1: it may be reused.

Member Data Documentation

◆ FrameCost

std::size_t PhosphorChannel::Stream::FrameCost = 64
staticconstexpr

What a frame costs against the window on top of its size, so that a window also bounds the number of small frames that wait.

◆ MinWindow

std::size_t PhosphorChannel::Stream::MinWindow = 1024
staticconstexpr

The smallest window.

◆ onReadable

std::function<void(StreamReader&)> PhosphorChannel::Stream::onReadable

A frame arrived on a reader, its writer closed it, or the stream ended or failed: read it until read() returns something other than Frame.

A failure in the owner's own call sets error() at once: tryWrite() returns Closed and openWriter() nullptr, while read() still returns the frame that it took. Its onReadable comes with the next readable() or pump(), which run it even while readFd() is quiet: an owner with its own poll calls readable() once error() is set, without waiting for readFd().

◆ onReader

std::function<void(StreamReader&)> PhosphorChannel::Stream::onReader

The other end opened a channel.

◆ onWritable

std::function<void(StreamWriter&)> PhosphorChannel::Stream::onWritable

A writer that returned WouldBlock may write again.


The documentation for this class was generated from the following file:
  • phosphor-channel/include/PhosphorChannel/Stream.h