StormByte-Buffer 4.0.0
C++26 buffer module of the StormByte suite
Loading...
Searching...
No Matches
StormByte::Buffer::Consumer Class Referencefinal

Read-oriented handle over a shared Ring. More...

#include <StormByte/buffer/consumer.hxx>

Inheritance diagram for StormByte::Buffer::Consumer:
Collaboration diagram for StormByte::Buffer::Consumer:

Public Member Functions

Constructors / destructor / assignment
 Consumer ()
 Create a Consumer and a new shared Ring.
 Consumer (const Consumer &other)
 Copy a Consumer.
 Consumer (Consumer &&other) noexcept
 Take a Consumer.
 ~Consumer () noexcept override
 Destroy the Consumer.
Consumer & operator= (const Consumer &other)
 Copy-assign a Consumer.
Consumer & operator= (Consumer &&other) noexcept
 Move-assign a Consumer.
Comparison
bool operator== (const Consumer &other) const noexcept
 Compare two Consumers.
bool operator!= (const Consumer &other) const noexcept
 Compare two Consumers.
Queries
StormByte::ByteSize Available () const noexcept override
 Bytes available from the current position.
const StormByte::Safe::Binary & Data () const noexcept override
 Snapshot of the underlying data.
bool Empty () const noexcept override
 Whether the shared Ring holds no stored bytes.
bool EoF () const noexcept override
 End-of-stream condition.
bool IsReadable () const noexcept override
 Whether the shared Ring can still be read.
bool IsWritable () const noexcept
 Whether the shared Ring still accepts writes.
bool HasError () const noexcept
 Whether the shared Ring is in a permanent error state.
StormByte::ByteSize Size () const noexcept override
 Total number of bytes stored in the shared Ring.
class Producer Producer () const
 Writer on the same Ring.
Maintenance / lifecycle
void Clean () noexcept override
 Discard already-consumed data up to the read position.
void Clear () noexcept override
 Clear stored bytes.
void Close () noexcept
 Close the shared Ring for further writes.
bool Drop (const StormByte::ByteSize &count) noexcept override
 Discard bytes from the current read position.
void Seek (const std::ptrdiff_t &offset, const Position &mode) const noexcept override
 Move the logical read position.
Extract (destructive read)
bool Extract (const StormByte::ByteSize &count, StormByte::Safe::Binary &out) noexcept override
 Extract bytes into owned storage.
bool Extract (const StormByte::ByteSize &count, WriteOnly &out) noexcept override
 Extract bytes into a writer.
void ExtractUntilEoF (StormByte::Safe::Binary &out) noexcept override
 Extract until EoF into owned storage.
void ExtractUntilEoF (WriteOnly &out) noexcept override
 Extract until EoF into a writer.
Read (non-destructive)
bool Read (const StormByte::ByteSize &count, StormByte::Safe::Binary &out) const noexcept override
 Read into owned storage and advance the cursor.
bool Read (const StormByte::ByteSize &count, WriteOnly &out) const noexcept override
 Read into a writer and advance the cursor.
void ReadUntilEoF (StormByte::Safe::Binary &out) const noexcept override
 Read until EoF into owned storage.
void ReadUntilEoF (WriteOnly &out) const noexcept override
 Read until EoF into a writer.
Peek
bool Peek (const StormByte::ByteSize &count, StormByte::Safe::Binary &out) const noexcept override
 Peek into owned storage.
bool Peek (const StormByte::ByteSize &count, WriteOnly &out) const noexcept override
 Peek into a writer.
Public Member Functions inherited from StormByte::Buffer::ReadOnly
 ReadOnly () noexcept
 Default constructor.
 ReadOnly (const ReadOnly &other) noexcept
 Copy constructor.
 ReadOnly (ReadOnly &&other) noexcept
 Move constructor.
virtual ~ReadOnly () noexcept
 Destructor.
ReadOnly & operator= (const ReadOnly &other) noexcept
 Copy assignment.
ReadOnly & operator= (ReadOnly &&other) noexcept
 Move assignment.
bool Extract (StormByte::Safe::Binary &outBuffer) noexcept
 Extract all available bytes into a StormByte::Safe::Binary.
bool Extract (WriteOnly &outBuffer) noexcept
 Extract all available bytes into a WriteOnly.
bool Read (StormByte::Safe::Binary &outBuffer) const noexcept
 Read all available bytes into a StormByte::Safe::Binary.
bool Read (WriteOnly &outBuffer) const noexcept
 Read all available bytes into a WriteOnly.
Public Member Functions inherited from StormByte::Buffer::Generic
 Generic () noexcept
 Default constructor.
 Generic (const Generic &other) noexcept
 Copy constructor.
 Generic (Generic &&other) noexcept
 Move constructor.
virtual ~Generic () noexcept=0
 Pure virtual destructor.
Generic & operator= (const Generic &other) noexcept
 Copy assignment.
Generic & operator= (Generic &&other) noexcept
 Move assignment.

Friends

class Producer

Additional Inherited Members

Static Protected Member Functions inherited from StormByte::Buffer::Generic
template<Type::ByteInputRange Src>
static STORMBYTE_FORCE_INLINE Safe::Binary DataConvert (const Src &src) noexcept
 Convert an lvalue input range to StormByte::Safe::Binary.
template<Type::ByteInputRange Src>
static STORMBYTE_FORCE_INLINE Safe::Binary DataConvert (Src &&src) noexcept
 Convert an rvalue input range to StormByte::Safe::Binary.
static Safe::Binary DataConvert (std::string_view sv) noexcept
 Convert a string view to StormByte::Safe::Binary.
static Safe::Binary DataConvert (const char *s) noexcept
 Convert a C string to StormByte::Safe::Binary.

Detailed Description

Read-oriented handle over a shared Ring.

Several Consumer instances may share the same Ring. An empty Consumer creates its own Ring. Producer() then returns a writer on that Ring. A Consumer may also come from Producer::Consumer().

All operations are thread-safe and delegate to the shared Ring. Ring ownership is held by StormByte::Safe::Owner. Blocking semantics match Ring.

Consumer is a ReadOnly view and also exposes Close(), IsWritable() and HasError() so a reader can observe the shared lifecycle.

See also
Producer, Ring, ReadOnly

Constructor & Destructor Documentation

◆ Consumer() [1/3]

StormByte::Buffer::Consumer::Consumer ( )

Create a Consumer and a new shared Ring.

Exceptions
StormByte::Safe::AllocationErrorRing ownership cannot be allocated.

◆ Consumer() [2/3]

StormByte::Buffer::Consumer::Consumer ( const Consumer & other)

Copy a Consumer.

Both share the same Ring.

Parameters
otherSource.
Exceptions
StormByte::ExceptionThe shared owner cannot be retained.

◆ Consumer() [3/3]

StormByte::Buffer::Consumer::Consumer ( Consumer && other)
noexcept

Take a Consumer.

other is left valid and unspecified.

Parameters
otherSource.

◆ ~Consumer()

StormByte::Buffer::Consumer::~Consumer ( )
overridenoexcept

Destroy the Consumer.

Member Function Documentation

◆ Available()

StormByte::ByteSize StormByte::Buffer::Consumer::Available ( ) const
overridevirtualnoexcept

Bytes available from the current position.

Returns
Available byte count.

Implements StormByte::Buffer::ReadOnly.

◆ Clean()

void StormByte::Buffer::Consumer::Clean ( )
overridevirtualnoexcept

Discard already-consumed data up to the read position.

Implements StormByte::Buffer::ReadOnly.

◆ Clear()

void StormByte::Buffer::Consumer::Clear ( )
overridevirtualnoexcept

Clear stored bytes.

Does not clear closed or error flags on the shared Ring.

Implements StormByte::Buffer::ReadOnly.

◆ Close()

void StormByte::Buffer::Consumer::Close ( )
inlinenoexcept

Close the shared Ring for further writes.

Same effect as Producer::Close on this Ring. Readers may still drain.

◆ Data()

const StormByte::Safe::Binary & StormByte::Buffer::Consumer::Data ( ) const
overridevirtualnoexcept

Snapshot of the underlying data.

Returns
Owned snapshot.
Warning
Prefer Read or Extract under concurrent mutation.

Implements StormByte::Buffer::ReadOnly.

◆ Drop()

bool StormByte::Buffer::Consumer::Drop ( const StormByte::ByteSize & count)
overridevirtualnoexcept

Discard bytes from the current read position.

Parameters
countBytes to drop.
Returns
False if fewer bytes were available.

Implements StormByte::Buffer::ReadOnly.

◆ Empty()

bool StormByte::Buffer::Consumer::Empty ( ) const
overridevirtualnoexcept

Whether the shared Ring holds no stored bytes.

Returns
Whether storage is empty.
Note
With a non-zero read position this may be false while Available() is zero.

Implements StormByte::Buffer::ReadOnly.

◆ EoF()

bool StormByte::Buffer::Consumer::EoF ( ) const
overridevirtualnoexcept

End-of-stream condition.

Returns
Whether the Ring is closed or in error and nothing remains.

Implements StormByte::Buffer::ReadOnly.

◆ Extract() [1/2]

bool StormByte::Buffer::Consumer::Extract ( const StormByte::ByteSize & count,
StormByte::Safe::Binary & out )
overridevirtualnoexcept

Extract bytes into owned storage.

Parameters
countBytes to extract. 0 means all available.
outDestination. Appended to.
Returns
False on failure.

Implements StormByte::Buffer::ReadOnly.

◆ Extract() [2/2]

bool StormByte::Buffer::Consumer::Extract ( const StormByte::ByteSize & count,
WriteOnly & out )
overridevirtualnoexcept

Extract bytes into a writer.

Parameters
countBytes to extract. 0 means all available.
outDestination.
Returns
False on failure.

Implements StormByte::Buffer::ReadOnly.

◆ ExtractUntilEoF() [1/2]

void StormByte::Buffer::Consumer::ExtractUntilEoF ( StormByte::Safe::Binary & out)
overridevirtualnoexcept

Extract until EoF into owned storage.

Parameters
outDestination.

Implements StormByte::Buffer::ReadOnly.

◆ ExtractUntilEoF() [2/2]

void StormByte::Buffer::Consumer::ExtractUntilEoF ( WriteOnly & out)
overridevirtualnoexcept

Extract until EoF into a writer.

Parameters
outDestination.

Implements StormByte::Buffer::ReadOnly.

◆ HasError()

bool StormByte::Buffer::Consumer::HasError ( ) const
inlinenoexcept

Whether the shared Ring is in a permanent error state.

Returns
Whether any handle called SetError on this Ring.

◆ IsReadable()

bool StormByte::Buffer::Consumer::IsReadable ( ) const
overridevirtualnoexcept

Whether the shared Ring can still be read.

Returns
False in a permanent error state.

Implements StormByte::Buffer::ReadOnly.

◆ IsWritable()

bool StormByte::Buffer::Consumer::IsWritable ( ) const
inlinenoexcept

Whether the shared Ring still accepts writes.

Returns
False if closed or in error.

◆ operator!=()

bool StormByte::Buffer::Consumer::operator!= ( const Consumer & other) const
inlinenoexcept

Compare two Consumers.

Parameters
otherOther Consumer.
Returns
Whether the underlying Rings differ.

◆ operator=() [1/2]

Consumer & StormByte::Buffer::Consumer::operator= ( const Consumer & other)

Copy-assign a Consumer.

Both share the same Ring afterwards.

Parameters
otherSource.
Returns
This Consumer.
Exceptions
StormByte::ExceptionThe shared owner cannot be retained.

◆ operator=() [2/2]

Consumer & StormByte::Buffer::Consumer::operator= ( Consumer && other)
noexcept

Move-assign a Consumer.

Parameters
otherSource.
Returns
This Consumer.

◆ operator==()

bool StormByte::Buffer::Consumer::operator== ( const Consumer & other) const
noexcept

Compare two Consumers.

Parameters
otherOther Consumer.
Returns
Whether both refer to the same Ring.

◆ Peek() [1/2]

bool StormByte::Buffer::Consumer::Peek ( const StormByte::ByteSize & count,
StormByte::Safe::Binary & out ) const
overridevirtualnoexcept

Peek into owned storage.

Does not advance the cursor.

Parameters
countBytes to peek. 0 means all available.
outDestination. Appended to.
Returns
False on failure.

Implements StormByte::Buffer::ReadOnly.

◆ Peek() [2/2]

bool StormByte::Buffer::Consumer::Peek ( const StormByte::ByteSize & count,
WriteOnly & out ) const
overridevirtualnoexcept

Peek into a writer.

Does not advance the cursor.

Parameters
countBytes to peek. 0 means all available.
outDestination.
Returns
False on failure.

Implements StormByte::Buffer::ReadOnly.

◆ Producer()

class Producer StormByte::Buffer::Consumer::Producer ( ) const

Writer on the same Ring.

Returns
Producer that shares this store.

◆ Read() [1/2]

bool StormByte::Buffer::Consumer::Read ( const StormByte::ByteSize & count,
StormByte::Safe::Binary & out ) const
overridevirtualnoexcept

Read into owned storage and advance the cursor.

Parameters
countBytes to read. 0 means all available.
outDestination. Appended to.
Returns
False on failure.

Implements StormByte::Buffer::ReadOnly.

◆ Read() [2/2]

bool StormByte::Buffer::Consumer::Read ( const StormByte::ByteSize & count,
WriteOnly & out ) const
overridevirtualnoexcept

Read into a writer and advance the cursor.

Parameters
countBytes to read. 0 means all available.
outDestination.
Returns
False on failure.

Implements StormByte::Buffer::ReadOnly.

◆ ReadUntilEoF() [1/2]

void StormByte::Buffer::Consumer::ReadUntilEoF ( StormByte::Safe::Binary & out) const
overridevirtualnoexcept

Read until EoF into owned storage.

Parameters
outDestination.

Implements StormByte::Buffer::ReadOnly.

◆ ReadUntilEoF() [2/2]

void StormByte::Buffer::Consumer::ReadUntilEoF ( WriteOnly & out) const
overridevirtualnoexcept

Read until EoF into a writer.

Parameters
outDestination.

Implements StormByte::Buffer::ReadOnly.

◆ Seek()

void StormByte::Buffer::Consumer::Seek ( const std::ptrdiff_t & offset,
const Position & mode ) const
overridevirtualnoexcept

Move the logical read position.

Parameters
offsetOffset.
modeAbsolute or relative.

Implements StormByte::Buffer::ReadOnly.

◆ Size()

StormByte::ByteSize StormByte::Buffer::Consumer::Size ( ) const
overridevirtualnoexcept

Total number of bytes stored in the shared Ring.

Returns
Size in bytes.

Implements StormByte::Buffer::Generic.

◆ Producer

friend class Producer
friend

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