Final BufferedLocationReader over a filesystem file. More...

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

Inheritance diagram for StormByte::Buffer::IO::BufferedFileReader:

[legend]

Collaboration diagram for StormByte::Buffer::IO::BufferedFileReader:

[legend]

Classes
class	Parameters
	File-reader knobs. More...

Public Member Functions
Lifecycle
STORMBYTE_FORCE_INLINE	BufferedFileReader (StormByte::String::String path, Parameters parameters={})
	Store the path and optional knobs.

	BufferedFileReader (const BufferedFileReader &)=delete
	Copy constructor is deleted.

	BufferedFileReader (BufferedFileReader &&other) noexcept
	Move constructor.

	~BufferedFileReader () noexcept override
	Destructor.

BufferedFileReader &	operator= (const BufferedFileReader &)=delete
	Copy assignment is deleted.

BufferedFileReader &	operator= (BufferedFileReader &&other) noexcept
	Move assignment.

Public Member Functions inherited from StormByte::Buffer::IO::BufferedLocationReader
	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::Shared< StormByte::System::Device >	OriginDevice () const override
	Device for the location probe.

Result	OriginOpen () override
	Open the file as a binary input and cache its size.

Result	OriginClose () override
	Close the file stream.

Result	OriginPull (StormByte::ByteSize n, FIFO &dest) override
	Read up to `n` bytes from the file into `dest`.

Result	OriginSeek (std::ptrdiff_t offset, Position mode) override
	Seek the file stream.

std::optional< StormByte::ByteSize >	OriginSize () const noexcept override
	Cached file size.

Protected Member Functions inherited from StormByte::Buffer::IO::BufferedLocationReader
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 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.

Detailed Description

Final BufferedLocationReader over a filesystem file.

Binary ifstream only. Hooks call SetState. Does not open in the constructor.

The device does not change after construction: ReadAhead is chosen once by BufferedLocationReader::Setup when the caller omitted that knob. Cache size (MaxMemory) stays dynamic.

Constructors: BufferedFileReader(path) and BufferedFileReader(path, {}) ask the location layer to probe Device at Setup. Initial MaxMemory is 1 MiB. BufferedFileReader(path, { ReadAhead(n), MaxMemory(m) }) stores those values and does not probe. ReadAhead 0 disables prefetch. MaxMemory 0 stores no cache.

Parameters is resolved in the caller (STORMBYTE_FORCE_INLINE). The DLL sees only numbers and the probe flag.

This leaf only opens, reads, seeks and reports the file length. OriginDevice builds a StormByte::System::Device from Location.

See also: BufferedLocationReader, State

Constructor & Destructor Documentation

◆ BufferedFileReader() [1/3]

STORMBYTE_FORCE_INLINE StormByte::Buffer::IO::BufferedFileReader::BufferedFileReader	(	StormByte::String::String	path,
		Parameters	parameters = `{}`
	)

inlineexplicit

Store the path and optional knobs.

Does not open.

Parameters

path	Local filesystem path. Stored once. Location is Location::Local.
parameters	Omitted knobs keep the current file defaults.

Omitted ReadAhead → Setup probes Device. Omitted MaxMemory → 1 MiB. Omitted MaxWait → 0 ms.

◆ BufferedFileReader() [2/3]

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

delete

Copy constructor is deleted.

◆ BufferedFileReader() [3/3]

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

noexcept

Move constructor.

Parameters

other Instance to take from.

◆ ~BufferedFileReader()

StormByte::Buffer::IO::BufferedFileReader::~BufferedFileReader ( )

overridenoexcept

Destructor.

Calls Close while the leaf vtable is live.

Member Function Documentation

◆ operator=() [1/2]

BufferedFileReader & StormByte::Buffer::IO::BufferedFileReader::operator= ( BufferedFileReader && other )

noexcept

Move assignment.

Parameters

other Instance to take from.

Returns: *this.

◆ operator=() [2/2]

BufferedFileReader & StormByte::Buffer::IO::BufferedFileReader::operator= ( const BufferedFileReader & )

delete

Copy assignment is deleted.

Returns: *this.

◆ OriginClose()

Result StormByte::Buffer::IO::BufferedFileReader::OriginClose ( )

overrideprotectedvirtual

Close the file stream.

Returns: IO::Status::Ok.

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

◆ OriginDevice()

StormByte::Shared< StormByte::System::Device > StormByte::Buffer::IO::BufferedFileReader::OriginDevice ( ) const

overrideprotectedvirtual

Device for the location probe.

Returns: Owner of a StormByte::System::Device on Path.

The base type is used as is, so usability is the real path probe.

Implements StormByte::Buffer::IO::BufferedLocationReader.

◆ OriginOpen()

Result StormByte::Buffer::IO::BufferedFileReader::OriginOpen ( )

overrideprotectedvirtual

Open the file as a binary input and cache its size.

Returns: IO::Status::Ok or IO::Status::Failed.

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

◆ OriginPull()

Result StormByte::Buffer::IO::BufferedFileReader::OriginPull	(	StormByte::ByteSize	n,
		FIFO &	dest
	)

overrideprotectedvirtual

Read up to n bytes from the file into dest.

Parameters

n	Maximum bytes.
dest	Base-owned FIFO.

Returns: Ok, End, Error or Failed.

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

◆ OriginSeek()

Result StormByte::Buffer::IO::BufferedFileReader::OriginSeek	(	std::ptrdiff_t	offset,
		Position	mode
	)

overrideprotectedvirtual

Seek the file stream.

Parameters

offset	Byte offset.
mode	Absolute from start or relative to the file cursor.

Returns: IO::Status::Ok or IO::Status::Failed.

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

◆ OriginSize()

std::optional< StormByte::ByteSize > StormByte::Buffer::IO::BufferedFileReader::OriginSize ( ) const

overrideprotectedvirtualnoexcept

Cached file size.

Returns: Size in bytes, or empty if not open.

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

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

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

Classes

Public Member Functions

Protected Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ BufferedFileReader() [1/3]

◆ BufferedFileReader() [2/3]

◆ BufferedFileReader() [3/3]

◆ ~BufferedFileReader()

Member Function Documentation

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ OriginClose()

◆ OriginDevice()

◆ OriginOpen()

◆ OriginPull()

◆ OriginSeek()

◆ OriginSize()