StormByte-Buffer 4.0.0
C++26 buffer module of the StormByte suite
Loading...
Searching...
No Matches
StormByte::Buffer::IO::BufferedLocationReader Class Referenceabstract

File-like BufferedReader. More...

#include <StormByte/buffer/io/buffered_location_reader.hxx>

Inheritance diagram for StormByte::Buffer::IO::BufferedLocationReader:
Collaboration diagram for StormByte::Buffer::IO::BufferedLocationReader:

Classes

class  Parameters
 Location-reader knobs. More...
struct  Unpacked
 Knobs after Parameters has been unpacked. More...

Public Member Functions

 BufferedLocationReader (const BufferedLocationReader &)=delete
 Copy constructor is deleted.
 BufferedLocationReader (BufferedLocationReader &&other) noexcept
 Move constructor.
virtual ~BufferedLocationReader () noexcept override
 Destructor.
BufferedLocationReader & operator= (const BufferedLocationReader &)=delete
 Copy assignment is deleted.
BufferedLocationReader & operator= (BufferedLocationReader &&other) noexcept
 Move assignment.
StormByte::Safe::Shared< StormByte::System::Device > Device () const
 Measurement of this location.
Public Member Functions inherited from StormByte::Buffer::IO::BufferedReader
const StormByte::Safe::String & Path () const noexcept
 Locator stored at construction.
enum Location Location () const noexcept
 Where Path points.
virtual operator bool () const noexcept final
 Whether the source is prepared to read.
virtual enum State State () const noexcept final
 Session state.
 BufferedReader (const BufferedReader &)=delete
 Copy constructor is deleted.
 BufferedReader (BufferedReader &&other) noexcept
 Move constructor.
virtual ~BufferedReader () noexcept
 Virtual destructor.
BufferedReader & operator= (const BufferedReader &)=delete
 Copy assignment is deleted.
BufferedReader & operator= (BufferedReader &&other) noexcept
 Move assignment.
virtual bool Open () final
 Arm the origin.
virtual Result Close () final
 Stop prefetch, drop caches, close the origin.
virtual bool Rewind () final
 Re-arm an open source: Close then Open.
virtual bool IsOpen () const noexcept final
 Whether Open succeeded and Close has not.
virtual bool IsReadable () const noexcept final
 Whether reads may be attempted.
virtual bool EoF () const noexcept final
 Whether no further bytes can be produced.
virtual StormByte::ByteSize Available () const noexcept final
 Cached bytes readable at Tell without touching the origin.
virtual Result Read (StormByte::ByteSize n, FIFO &dest) const final
 Read n bytes into dest, consuming cache / origin.
virtual Result Read (std::span< std::byte > dest) const final
 Read into dest, consuming cache / origin.
virtual Result Peek (StormByte::ByteSize n, FIFO &dest) const final
 Copy n bytes into dest without consuming cache.
virtual Result Peek (std::span< std::byte > dest) const final
 Copy into dest without consuming cache.
virtual Result Seek (std::ptrdiff_t offset, Position mode) const final
 Move the logical read cursor.
virtual StormByte::ByteSize Tell () const noexcept final
 Logical read offset in the stream.
virtual bool IsSeekable () const noexcept final
 Whether this instance can reposition the origin.
virtual bool IsSized () const noexcept final
 Whether the origin length is known.
virtual StormByte::Safe::Optional< StormByte::ByteSize > Size () const noexcept final
 Origin length in bytes when known.
const StormByte::Safe::Shared< StormByte::Buffer::ReadTelemetry > Telemetry () const noexcept
 Shared read counters.
StormByte::ByteSize ReadAhead () const noexcept
 Configured prefetch length in bytes.
StormByte::ByteSize ReadChunk () const noexcept
 Maximum request passed to the origin.
void ReadChunk (StormByte::ByteSize bytes)
 Replace the read maximum after active reads finish.
ReaderConfiguration Configuration () const noexcept
 Read the complete policy without I/O.
Result Configure (ReaderConfiguration configuration)
 Cancel prefetch and apply a complete policy after active reads finish.
TransferSnapshot Transfers () const noexcept
 Read effective limits and real origin activity without I/O.
void ReadAhead (StormByte::ByteSize bytes)
 Set prefetch length.
StormByte::ByteSize MaxMemory () const noexcept
 Configured cache memory cap in bytes.
void MaxMemory (StormByte::ByteSize bytes)
 Set cache memory cap.
std::chrono::milliseconds MaxWait () const noexcept
 Configured read wait limit.
void MaxWait (std::chrono::milliseconds wait)
 Replace the read wait limit after active operations finish.

Protected Member Functions

 BufferedLocationReader (StormByte::Safe::String path, enum Location location, Unpacked knobs)
 Store the locator and the already-unpacked knobs.
virtual StormByte::Safe::Shared< StormByte::System::Device > OriginDevice () const =0
 Leaf measurement.
virtual bool OriginDeviceUsable (const StormByte::Safe::Shared< StormByte::System::Device > &device) const noexcept
 Whether Setup may read windows from device.
bool OriginCanSeek () const noexcept final
 A location can seek.
bool OriginHasSize () const noexcept final
 A location has a length.
void Setup () final
 Apply the device read window when the constructor asked for a probe.
Protected Member Functions inherited from StormByte::Buffer::IO::BufferedReader
STORMBYTE_FORCE_INLINE BufferedReader (StormByte::Safe::String path, enum Location location, Parameters parameters={})
 Construct an unopened coordinator (State::Unavailable).
 BufferedReader (StormByte::Safe::String path, enum Location location, ReaderConfiguration configuration)
 Construct an unopened coordinator (State::Unavailable).
void SetState (enum State state) noexcept
 Publish session state from a leaf hook.
virtual StormByte::Safe::Shared< StormByte::Buffer::ReadTelemetry > CreateTelemetry () const
 Allocate the telemetry object this instance will keep.
virtual Result OriginOpen ()=0
 Arm the underlying device and SetState.
virtual Result OriginClose ()=0
 Release the underlying device and SetState Unavailable.
virtual Result OriginPull (StormByte::ByteSize n, FIFO &dest)=0
 Read up to n bytes from the device into dest.
virtual Result OriginSeek (std::ptrdiff_t offset, Position mode)=0
 Seek the device.
virtual StormByte::Safe::Optional< StormByte::ByteSize > OriginSize () const noexcept=0
 Device length in bytes.

Detailed Description

File-like BufferedReader.

A location has a name, a cursor and a length. A file and anything that acts as a file inherit this. A byte stream that cannot seek or report a length inherits BufferedReader instead.

IsSeekable and IsSized are always true. The leaf does not implement those hooks.

Public Size stays optional on BufferedReader so a BufferedReader& is unchanged. On this type IsSized is true; the value is whatever OriginSize reports.

Path and Location live on BufferedReader. They are stored once and do not change. Path may be a filesystem path, socket://… or http://… . A file leaf passes Location::Local and its path is a local filesystem path.

Device is not virtual. OriginDevice is pure and hands out a StormByte::Safe::Shared owner, so a leaf may supply a StormByte::System::Device subclass and the dynamic type survives. Setup applies StormByte::System::Device::Window when the caller omitted ReadAhead and OriginDeviceUsable accepts the device.

The leaf implements OriginOpen, OriginClose, OriginPull, OriginSeek, OriginSize and OriginDevice. It does not touch the cache.

See also
BufferedReader, BufferedFileReader

Constructor & Destructor Documentation

◆ BufferedLocationReader() [1/3]

StormByte::Buffer::IO::BufferedLocationReader::BufferedLocationReader ( const BufferedLocationReader & )
delete

Copy constructor is deleted.

◆ BufferedLocationReader() [2/3]

StormByte::Buffer::IO::BufferedLocationReader::BufferedLocationReader ( BufferedLocationReader && other)
noexcept

Move constructor.

Transfers the location. Moved-from has none.

Parameters
otherInstance to take from.

◆ ~BufferedLocationReader()

virtual StormByte::Buffer::IO::BufferedLocationReader::~BufferedLocationReader ( )
overridevirtualnoexcept

Destructor.

Releases the location in this module.

◆ BufferedLocationReader() [3/3]

StormByte::Buffer::IO::BufferedLocationReader::BufferedLocationReader ( StormByte::Safe::String path,
enum Location location,
Unpacked knobs )
protected

Store the locator and the already-unpacked knobs.

Parameters
pathLocator. Forwarded. Stored once on BufferedReader.
locationLocation::Local or Location::Remote. Forwarded.
knobsResult of unpacking Parameters. Not a bag.

Not a delegating constructor. GCC would emit a reference to the complete-object constructor (C1) of an abstract class, and it does not emit that symbol. m_io is created in this module.

Member Function Documentation

◆ Device()

StormByte::Safe::Shared< StormByte::System::Device > StormByte::Buffer::IO::BufferedLocationReader::Device ( ) const

Measurement of this location.

Returns
Owner returned by OriginDevice. May be empty.

The dynamic type of the leaf device is preserved and the caller may keep the object alive.

◆ operator=() [1/2]

BufferedLocationReader & StormByte::Buffer::IO::BufferedLocationReader::operator= ( BufferedLocationReader && other)
noexcept

Move assignment.

Parameters
otherInstance to take from.
Returns
*this.

◆ operator=() [2/2]

BufferedLocationReader & StormByte::Buffer::IO::BufferedLocationReader::operator= ( const BufferedLocationReader & )
delete

Copy assignment is deleted.

Returns
*this.

◆ OriginCanSeek()

bool StormByte::Buffer::IO::BufferedLocationReader::OriginCanSeek ( ) const
finalprotectedvirtualnoexcept

A location can seek.

Returns
true.

Implements StormByte::Buffer::IO::BufferedReader.

◆ OriginDevice()

virtual StormByte::Safe::Shared< StormByte::System::Device > StormByte::Buffer::IO::BufferedLocationReader::OriginDevice ( ) const
protectedpure virtual

Leaf measurement.

Not necessarily a filesystem type.

Returns
Owner of the device built by the leaf. May be empty.

Build it with StormByte::Safe::Shared<StormByte::System::Device>::MakePointer so a StormByte::System::Device subclass keeps its overrides.

Implemented in StormByte::Buffer::IO::BufferedFileReader.

◆ OriginDeviceUsable()

virtual bool StormByte::Buffer::IO::BufferedLocationReader::OriginDeviceUsable ( const StormByte::Safe::Shared< StormByte::System::Device > & device) const
protectedvirtualnoexcept

Whether Setup may read windows from device.

Parameters
deviceOwner returned by OriginDevice. May be empty.
Returns
true when the device may be measured.

The default is a non-empty owner whose operator bool is true, which probes the stored path. A leaf whose identifier is not a filesystem path overrides this and never reaches that non-virtual probe. An empty owner is always unusable.

◆ OriginHasSize()

bool StormByte::Buffer::IO::BufferedLocationReader::OriginHasSize ( ) const
finalprotectedvirtualnoexcept

A location has a length.

Returns
true.

Implements StormByte::Buffer::IO::BufferedReader.

◆ Setup()

void StormByte::Buffer::IO::BufferedLocationReader::Setup ( )
finalprotectedvirtual

Apply the device read window when the constructor asked for a probe.

OriginDevice is called once. When OriginDeviceUsable rejects the owner, ReadAhead keeps its default.

Reimplemented from StormByte::Buffer::IO::BufferedReader.


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