StormByte::Buffer::Bridge Class Reference

Manual bridge between two StormByte-Buffer ends. More...

#include <StormByte/buffer/bridge.hxx>

Public Types
enum class	Operation { Blocking , NonBlocking }
	Read-side wait policy for Passthrough. More...
enum class	State { Open , Closed , Failed }
	Session lifetime. More...

Public Member Functions
	Bridge (ReadOnly &in, WriteOnly &out) noexcept
	Two non-IO tips.
template<typename In , typename Out > requires (Type::DerivedFrom<std::remove_cvref_t<In>, IO::BufferedReader> && Type::DerivedFrom<std::remove_cvref_t<Out>, IO::BufferedWriter>)
STORMBYTE_FORCE_INLINE	Bridge (In &&in, Out &&out) noexcept
	Two IO leaves.
template<typename Out > requires Type::DerivedFrom<std::remove_cvref_t<Out>, IO::BufferedWriter>
STORMBYTE_FORCE_INLINE	Bridge (ReadOnly &in, Out &&out) noexcept
	Non-IO source, IO sink stolen.
template<typename In > requires Type::DerivedFrom<std::remove_cvref_t<In>, IO::BufferedReader>
STORMBYTE_FORCE_INLINE	Bridge (In &&in, WriteOnly &out) noexcept
	IO source stolen, non-IO sink.
	Bridge (const Bridge &)=delete
	Bridge (Bridge &&other) noexcept
	Move constructor.
	~Bridge () noexcept
	Destructor.
Bridge &	operator= (const Bridge &)=delete
Bridge &	operator= (Bridge &&other) noexcept
	Move assignment.
void	Close () noexcept
	Release owned tips.
bool	EoF () const noexcept
	Whether the read tip reports end-of-stream.
bool	Failed () const noexcept
	Whether a tip has failed for real.
bool	InputIsIO () const noexcept
	Whether the read tip is a stolen IO leaf.
bool	InputPullBlocking () const noexcept
	Whether Pumper must Blocking-pull this source.
enum State	State () const noexcept
	Session lifetime.
StormByte::ByteSize	Passthrough (StormByte::ByteSize n, Operation operation=Operation::Blocking)
	Move bytes from the read tip to the write tip.
const StormByte::Safe::Shared< StormByte::Buffer::ReadTelemetry >	ReadTelemetry () const noexcept
	Read counters.
const StormByte::Safe::Shared< StormByte::Buffer::WriteTelemetry >	WriteTelemetry () const noexcept
	Write counters.

Detailed Description

Manual bridge between two StormByte-Buffer ends.

Connects a read tip to a write tip. Bytes cross only when the caller invokes Passthrough. There is no worker and no occupancy cap at this layer. Continuous transfer is Pumper.

Ownership

Non-IO tips are ReadOnly / WriteOnly references. The buffers must outlive the Bridge. IO tips are taken by move as the concrete leaf so a second reader or writer cannot race Passthrough. Stolen leaves live in StormByte::Safe::Unique on Base's heap.

Lifecycle

A Bridge is one shot. State::Open while tips are attached. Close, a consumed source EoF and move-from go to State::Closed. A real tip fault goes to State::Failed. Failed is only that last case. There is no rewind and no seek on the session. After State::Closed or State::Failed the instance cannot be re-armed; construct a new Bridge to transfer again.

Close detaches non-IO tips and releases stolen IO leaves. IO destructors close the origin, so Windows can unlink the path. In-memory tips do not lock a file. Idempotent. Close does not set Failed. A session that is already State::Failed stays Failed and still drops the tips.

Passthrough

One call is one atomic transfer. TryAgain on the write tip is retried until the requested write completes or the tip fails. That is not the same as Operation::Blocking: Blocking applies only to the read side.

n == 0 is the current contents of the read tip (non-IO occupancy, or IO::BufferedReader::Available). Available on IO does not touch the origin.

If State is not State::Open, Passthrough returns 0 and does nothing. A NonBlocking call that yields zero bytes is not the end of the session.

A non-IO source that is not readable (ReadOnly::IsReadable is false, including after SetError) is a tip fault, not EoF. A closed empty source is EoF. Those two are not the same.

Telemetry

This Bridge always holds a Shared copy of the read and write counters. A non-IO tip uses a basic StormByte::Buffer::ReadTelemetry / StormByte::Buffer::WriteTelemetry created here. The Bridge updates those counters on each successful transfer. An IO tip donates the leaf handle at attach. The leaf updates that object; the Bridge only caches the handle so Close does not drop it. Survivors that copied the Shared keep the last values when *this dies.

See also

ReadOnly, WriteOnly, IO::BufferedReader, IO::BufferedWriter

Member Enumeration Documentation

Operation

enum class StormByte::Buffer::Bridge::Operation

strong

Read-side wait policy for Passthrough.

Enumerator
Blocking	Wait until N bytes or EoF.
NonBlocking	Take what is available now, up to N.

State

enum class StormByte::Buffer::Bridge::State

strong

Session lifetime.

Failed is a real tip fault only.

Enumerator
Open	Tips attached. Passthrough may run.
Closed	Close, consumed EoF or moved-from.
Failed	A tip failed. Sticky.

Constructor & Destructor Documentation

Bridge() [1/6]

StormByte::Buffer::Bridge::Bridge ( ReadOnly &  in, WriteOnly &  out  )

noexcept

Two non-IO tips.

Referenced, not owned.

Parameters

in	Source. Must outlive *this.
out	Sink. Must outlive *this.

Bridge() [2/6]

template<typename In , typename Out >
requires (Type::DerivedFrom<std::remove_cvref_t<In>, IO::BufferedReader> && Type::DerivedFrom<std::remove_cvref_t<Out>, IO::BufferedWriter>)

STORMBYTE_FORCE_INLINE StormByte::Buffer::Bridge::Bridge ( In &&  in, Out &&  out  )

inlinenoexcept

Two IO leaves.

Stolen by move.

Template Parameters

In	Concrete IO::BufferedReader leaf.
Out	Concrete IO::BufferedWriter leaf.

Parameters

in	Source. Moved-from is empty.
out	Sink. Moved-from is empty.

Bridge() [3/6]

template<typename Out >
requires Type::DerivedFrom<std::remove_cvref_t<Out>, IO::BufferedWriter>

STORMBYTE_FORCE_INLINE StormByte::Buffer::Bridge::Bridge ( ReadOnly &  in, Out &&  out  )

inlinenoexcept

Non-IO source, IO sink stolen.

Template Parameters

Out	Concrete IO::BufferedWriter leaf.

Parameters

in	Source. Must outlive *this.
out	Sink. Moved-from is empty.

Bridge() [4/6]

template<typename In >
requires Type::DerivedFrom<std::remove_cvref_t<In>, IO::BufferedReader>

STORMBYTE_FORCE_INLINE StormByte::Buffer::Bridge::Bridge ( In &&  in, WriteOnly &  out  )

inlinenoexcept

IO source stolen, non-IO sink.

Template Parameters

In	Concrete IO::BufferedReader leaf.

Parameters

in	Source. Moved-from is empty.
out	Sink. Must outlive *this.

Bridge() [5/6]

StormByte::Buffer::Bridge::Bridge ( const Bridge &  )

delete

Bridge() [6/6]

StormByte::Buffer::Bridge::Bridge ( Bridge &&  other )

noexcept

Move constructor.

Moved-from is State::Closed and empty.

Parameters

other

Instance to take from.

~Bridge()

StormByte::Buffer::Bridge::~Bridge ( )

noexcept

Destructor.

Releases stolen IO tips.

Member Function Documentation

Close()

void StormByte::Buffer::Bridge::Close ( )

noexcept

Release owned tips.

Mark State::Closed if it was Open.

Detaches non-IO tips and drops stolen IO leaves. IO destructors close the origin. Idempotent. Does not set Failed. A State::Failed session stays Failed and still drops the tips. After State::Closed construct a new Bridge to transfer again.

EoF()

bool StormByte::Buffer::Bridge::EoF ( ) const

noexcept

Whether the read tip reports end-of-stream.

Returns

true on EoF, if State is not Open, or if there is no read tip.

Failed()

bool StormByte::Buffer::Bridge::Failed ( ) const

noexcept

Whether a tip has failed for real.

Returns

true only when State is State::Failed.

InputIsIO()

bool StormByte::Buffer::Bridge::InputIsIO ( ) const

noexcept

Whether the read tip is a stolen IO leaf.

Returns

true if the source is IO. Used by Pumper HighWater default.

InputPullBlocking()

bool StormByte::Buffer::Bridge::InputPullBlocking ( ) const

noexcept

Whether Pumper must Blocking-pull this source.

Returns

true when the stolen reader has IO::BufferedReader::ReadAhead of 0.

Non-IO sources return false. Snapshotted at attach; later IO::BufferedReader::ReadAhead setters on a moved-from leaf do not change it.

operator=() [1/2]

Bridge & StormByte::Buffer::Bridge::operator= ( Bridge &&  other )

noexcept

Move assignment.

Moved-from is State::Closed and empty.

Parameters

other

Instance to take from.

Returns

*this.

operator=() [2/2]

Bridge & StormByte::Buffer::Bridge::operator= ( const Bridge &  )

delete

Passthrough()

StormByte::ByteSize StormByte::Buffer::Bridge::Passthrough	(	StormByte::ByteSize	n,
		Operation	operation = Operation::Blocking
	)

Move bytes from the read tip to the write tip.

Parameters

n	Requested bytes. Zero means current contents.
operation	Read-side wait policy.

Returns

Bytes actually moved. Zero if not State::Open or empty.

ReadTelemetry()

const StormByte::Safe::Shared< StormByte::Buffer::ReadTelemetry > StormByte::Buffer::Bridge::ReadTelemetry ( ) const

noexcept

Read counters.

Always the cached Shared handle.

Returns

Const shared handle. Empty if moved-from.

State()

enum State StormByte::Buffer::Bridge::State ( ) const

noexcept

Session lifetime.

Returns

Current State.

WriteTelemetry()

const StormByte::Safe::Shared< StormByte::Buffer::WriteTelemetry > StormByte::Buffer::Bridge::WriteTelemetry ( ) const

noexcept

Write counters.

Always the cached Shared handle.

Returns

Const shared handle. Empty if moved-from.

---

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

• lib/public/StormByte/buffer/bridge.hxx