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

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

[legend]

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

Classes
class	Parameters
	Location-reader knobs. 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::Shared< StormByte::System::Device >	Device () const
	Measurement of this location.

Public Member Functions inherited from StormByte::Buffer::IO::BufferedReader
const StormByte::String::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 std::optional< StormByte::ByteSize >	Size () const noexcept final
	Origin length in bytes when known.

const StormByte::Shared< StormByte::Buffer::ReadTelemetry >	Telemetry () const noexcept
	Shared read counters.

virtual StormByte::ByteSize	ReadAhead () const noexcept
	Configured prefetch length in bytes.

virtual void	ReadAhead (StormByte::ByteSize bytes)
	Set prefetch length.

virtual StormByte::ByteSize	MaxMemory () const noexcept
	Configured cache memory cap in bytes.

virtual void	MaxMemory (StormByte::ByteSize bytes)
	Set cache memory cap.

virtual std::chrono::milliseconds	MaxWait () const noexcept
	Configured read wait limit.

virtual void	MaxWait (std::chrono::milliseconds wait)
	Set read wait limit.

Protected Member Functions
STORMBYTE_FORCE_INLINE	BufferedLocationReader (StormByte::String::String path, enum Location location, Parameters parameters={})
	Store the locator and resolve knobs in the caller.

	BufferedLocationReader (StormByte::String::String path, enum Location location, StormByte::ByteSize read_ahead, StormByte::ByteSize max_memory, std::chrono::milliseconds max_wait, bool probe)
	Store the locator and forward the cache knobs.

virtual StormByte::Shared< StormByte::System::Device >	OriginDevice () const =0
	Leaf measurement.

virtual bool	OriginDeviceUsable (const StormByte::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::String::String path, enum Location location, Parameters parameters={})
	Construct an unopened coordinator (State::Unavailable).

	BufferedReader (StormByte::String::String path, enum Location location, StormByte::ByteSize read_ahead, StormByte::ByteSize max_memory, std::chrono::milliseconds max_wait)
	Construct an unopened coordinator (State::Unavailable).

void	SetState (enum State state) noexcept
	Publish session state from a leaf hook.

virtual StormByte::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 std::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::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/4]

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

delete

Copy constructor is deleted.

◆ BufferedLocationReader() [2/4]

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

noexcept

Move constructor.

Transfers the location. Moved-from has none.

Parameters

other Instance to take from.

◆ ~BufferedLocationReader()

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

overridevirtualnoexcept

Destructor.

Releases the location in this module.

◆ BufferedLocationReader() [3/4]

STORMBYTE_FORCE_INLINE StormByte::Buffer::IO::BufferedLocationReader::BufferedLocationReader	(	StormByte::String::String	path,
		enum Location	location,
		Parameters	parameters = `{}`
	)

inlineprotected

Store the locator and resolve knobs in the caller.

Parameters

path	Locator. Forwarded. Stored once on BufferedReader.
location	Location::Local or Location::Remote. Forwarded.
parameters	Omitted ReadAhead → Setup probes Device. Omitted MaxMemory / MaxWait → 0 / 0 ms.

◆ BufferedLocationReader() [4/4]

StormByte::Buffer::IO::BufferedLocationReader::BufferedLocationReader	(	StormByte::String::String	path,
		enum Location	location,
		StormByte::ByteSize	read_ahead,
		StormByte::ByteSize	max_memory,
		std::chrono::milliseconds	max_wait,
		bool	probe
	)

protected

Store the locator and forward the cache knobs.

Parameters

path	Locator. Forwarded. Stored once on BufferedReader.
location	Location::Local or Location::Remote. Forwarded.
read_ahead	Initial ReadAhead. Ignored when `probe` is true.
max_memory	Initial MaxMemory.
max_wait	Initial MaxWait.
probe	When true, Setup replaces ReadAhead from Device.

DLL boundary. m_io is created here.

Member Function Documentation

◆ Device()

StormByte::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

other Instance 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::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::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::Shared< StormByte::System::Device > & device ) const

protectedvirtualnoexcept

Whether Setup may read windows from device.

Parameters

device Owner returned by OriginDevice. May be empty.

Returns: true when the device may be measured.

The default is a non-empty owner whose StormByte::System::Device::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:

lib/public/StormByte/buffer/io/buffered_location_reader.hxx

Classes

Public Member Functions

Protected Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ BufferedLocationReader() [1/4]

◆ BufferedLocationReader() [2/4]

◆ ~BufferedLocationReader()

◆ BufferedLocationReader() [3/4]

◆ BufferedLocationReader() [4/4]

Member Function Documentation

◆ Device()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ OriginCanSeek()

◆ OriginDevice()

◆ OriginDeviceUsable()

◆ OriginHasSize()

◆ Setup()