Coordinated binary read source with optional prefetch and cache. More...

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

Inheritance diagram for StormByte::Buffer::IO::BufferedReader:

[legend]

Classes
class	Parameters
	Reader knobs. More...

Public Member Functions
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.

Lifecycle
	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.

Session
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.

Read
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.

Position
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.

Size
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.

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

Policy
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	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 void	Setup ()
	Leaf policy hook.

virtual StormByte::Shared< StormByte::Buffer::ReadTelemetry >	CreateTelemetry () const
	Allocate the telemetry object this instance will keep.

Origin hooks
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 bool	OriginCanSeek () const noexcept=0
	Whether the device can seek.

virtual Result	OriginSeek (std::ptrdiff_t offset, Position mode)=0
	Seek the device.

virtual bool	OriginHasSize () const noexcept=0
	Whether the device reports a length.

virtual std::optional< StormByte::ByteSize >	OriginSize () const noexcept=0
	Device length in bytes.

Friends
class	StormByte::Buffer::Backend::IO::BufferedReader

Detailed Description

Coordinated binary read source with optional prefetch and cache.

Public base for byte origins. Callers take const BufferedReader&. Leaves implement only the Origin* hooks and may override Setup and CreateTelemetry. They do not override Read, Peek, Seek, Open, Close or Rewind.

Binary only: Octets only (StormByte::BinaryData / FIFO / std::span<std::byte>). No text mode.

Session: Construction leaves State::Unavailable. A successful Open moves to State::Idle (armed, ready to read until a pull proves otherwise). Close returns to State::Unavailable and is idempotent. Open is not idempotent: a second Open while Idle fails and leaves the state Idle. Close then Open is a valid round-trip.

operator bool is true only when the instance is prepared to read: State is Idle and not EoF.

Available: Available is the contiguous cached run at Tell. It does not call OriginPull or OriginSeek. Zero means the next Read must hit the origin (or is EoF).

Read / Peek: Wait for n bytes or origin end. MaxWait of 0ms waits without limit and never returns IO::Status::TryAgain. A positive MaxWait caps the wait; timeout yields IO::Status::TryAgain, destination untouched, state Idle. Origin failure during a pull is IO::Status::Error; the destination is not written; session state becomes State::Fault or State::Unavailable.

FIFO overloads: n == 0 serves the current cached span from Tell. Span overloads: dest.size() is the request; an empty span returns IO::Status::Ok and count 0 without consuming or pulling. There is no Read(n, span).

Destination: FIFO: overwritten on IO::Status::Ok or IO::Status::End with a non-zero count. Span: the first count bytes of dest are written; the remainder of the span is left as-is. Untouched on IO::Status::Failed, IO::Status::Error, IO::Status::TryAgain, or End with count 0.

Read vs Peek vs cache: Read advances Tell. Served bytes stay in the map until MaxMemory eviction. Peek does not move Tell.

Cache map: A seekable origin stores owned spans keyed by stream offset. Overlap and abutment merge, even past ReadAhead. MaxMemory is an approximate cap: overflow evicts the spans farthest from Tell, not the whole cache. MaxMemory of 0 stores no cache. A non-seekable origin keeps a single forward span.

Delayed seek: Seek moves only Tell. The device cursor is unchanged. Tell after Seek(x) is x; callers (AVIO included) must be able to trust that. Bytes delivered by the next Read are always stream[Tell, Tell+n), from the map and/or the origin.

Prefetch is suspended while Tell differs from the device cursor (a "fake seek"). The worker must not pull or OriginSeek in that window: that would either move the device (so a later catch-up is no longer sequential) or commit bytes at the wrong stream offset. Prefetch resumes when Tell meets the device again (the catch-up read is a plain OriginPull, not a seek) or when a hole forces a real OriginSeek.

A jump back into resident pages, then one or many Reads that stay in those pages, never seeks the origin. Reading past that window onto the old device position is still not a seek. Reading past a page whose hole is not the device cursor performs one OriginSeek to that hole.

SeekSavedFull / SeekSavedPartial close on the next Seek or Close. Full: the epoch started on a cache hit and never called OriginSeek. Partial: it did. Small Reads do not decide; the epoch does.

A non-seekable origin rejects Seek without the hook. Seek may block on prefetch cancellation.

ReadAhead: Applied after the synchronous request, and only while prefetch is not held by a fake seek. Prefetch uses OriginPull. Leaves must not buffer inside the hook.

Policy setters: ReadAhead, MaxMemory and MaxWait take effect immediately. They are not deferred to the next Read. Lowering ReadAhead or MaxMemory may drop cached bytes that no longer fit. The setter does not return until prefetch is cancelled and the cache is trimmed. That wait is blocking even though it is not an origin pull.

Telemetry: Telemetry returns a const StormByte::Shared of StormByte::Buffer::ReadTelemetry. The user cannot reseat the handle. The office updates the same object. The dynamic type is IO::ReadTelemetry unless a leaf overrides CreateTelemetry. Accumulators start at construction and do not reset on Close. MeanRate is the caller rate.

Movable, not copyable: Move transfers m_io. Moved-from is Unavailable.

See also: IO::Status, State, Result, FIFO

Constructor & Destructor Documentation

◆ BufferedReader() [1/4]

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

delete

Copy constructor is deleted.

◆ BufferedReader() [2/4]

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

noexcept

Move constructor.

Parameters

other Instance to take from. Left Unavailable.

◆ ~BufferedReader()

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

virtualnoexcept

Virtual destructor.

Stops the worker. Does not call Origin*.

Leaves must call Close in their destructor so OriginClose still runs on a live vtable.

◆ BufferedReader() [3/4]

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

inlineprotected

Construct an unopened coordinator (State::Unavailable).

Parameters

path	Locator. Stored once.
location	Location::Local or Location::Remote. Stored once.
parameters	Omitted knobs are 0 / 0 ms. Resolved in the caller.

◆ BufferedReader() [4/4]

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

protected

Construct an unopened coordinator (State::Unavailable).

Parameters

path	Locator. Stored once.
location	Location::Local or Location::Remote. Stored once.
read_ahead	Initial ReadAhead in bytes.
max_memory	Initial MaxMemory in bytes.
max_wait	Initial MaxWait. `0ms` = unlimited.

DLL boundary. Children that already resolved knobs call this.

Member Function Documentation

◆ Available()

virtual StormByte::ByteSize StormByte::Buffer::IO::BufferedReader::Available ( ) const

finalvirtualnoexcept

Cached bytes readable at Tell without touching the origin.

Returns: Contiguous readahead at the logical cursor. 0 if moved-from or closed.

Does not call OriginPull or OriginSeek. Does not wait for prefetch. Prefetch already in the map is counted; an in-flight pull is not.

◆ Close()

virtual Result StormByte::Buffer::IO::BufferedReader::Close ( )

finalvirtual

Stop prefetch, drop caches, close the origin.

Returns: IO::Status::Ok. Always succeeds at this layer.

Idempotent. Sets session state to State::Unavailable.

◆ CreateTelemetry()

virtual StormByte::Shared< StormByte::Buffer::ReadTelemetry > StormByte::Buffer::IO::BufferedReader::CreateTelemetry ( ) const

protectedvirtual

Allocate the telemetry object this instance will keep.

Returns: Shared handle. Default is IO::ReadTelemetry.

Called once, after the most-derived constructor, the first time telemetry is needed. A remote leaf returns a further-derived type. Must not return empty.

◆ EoF()

virtual bool StormByte::Buffer::IO::BufferedReader::EoF ( ) const

finalvirtualnoexcept

Whether no further bytes can be produced.

Returns: true when no cached byte remains at Tell and the origin is exhausted, or after Close.

◆ IsOpen()

virtual bool StormByte::Buffer::IO::BufferedReader::IsOpen ( ) const

finalvirtualnoexcept

Whether Open succeeded and Close has not.

Returns: true if the session is armed.

◆ IsReadable()

virtual bool StormByte::Buffer::IO::BufferedReader::IsReadable ( ) const

finalvirtualnoexcept

Whether reads may be attempted.

Returns: Same as operator bool.

◆ IsSeekable()

virtual bool StormByte::Buffer::IO::BufferedReader::IsSeekable ( ) const

finalvirtualnoexcept

Whether this instance can reposition the origin.

Returns: OriginCanSeek.

◆ IsSized()

virtual bool StormByte::Buffer::IO::BufferedReader::IsSized ( ) const

finalvirtualnoexcept

Whether the origin length is known.

Returns: OriginHasSize.

◆ Location()

enum Location StormByte::Buffer::IO::BufferedReader::Location ( ) const

noexcept

Where Path points.

Does not change.

Returns: Location::Local or Location::Remote. Location::Local if moved-from.

◆ MaxMemory() [1/2]

virtual StormByte::ByteSize StormByte::Buffer::IO::BufferedReader::MaxMemory ( ) const

virtualnoexcept

Configured cache memory cap in bytes.

Returns: Current cap. 0 means no cache and no prefetch.

◆ MaxMemory() [2/2]

virtual void StormByte::Buffer::IO::BufferedReader::MaxMemory ( StormByte::ByteSize bytes )

virtual

Set cache memory cap.

Takes effect immediately.

Parameters

bytes Approximate maximum resident cache. 0 drops all spans.

Cancels prefetch and evicts farthest spans before returning. Waits for the worker; not an origin pull.

◆ MaxWait() [1/2]

virtual std::chrono::milliseconds StormByte::Buffer::IO::BufferedReader::MaxWait ( ) const

virtualnoexcept

Configured read wait limit.

Returns: Wait cap. 0ms waits forever (never IO::Status::TryAgain).

◆ MaxWait() [2/2]

virtual void StormByte::Buffer::IO::BufferedReader::MaxWait ( std::chrono::milliseconds wait )

virtual

Set read wait limit.

Takes effect on the next Read / Peek.

Parameters

wait	`0ms` = unlimited. Positive = timeout then TryAgain.

Overridable so a leaf can clamp. Does not cancel an in-flight prefetch. Does not trim the cache.

◆ Open()

virtual bool StormByte::Buffer::IO::BufferedReader::Open ( )

finalvirtual

Arm the origin.

Returns: true if State is State::Idle afterwards.

Calls Setup then the backend Open. Not idempotent. A second call while Idle returns false and leaves the session Idle.

◆ operator bool()

virtual StormByte::Buffer::IO::BufferedReader::operator bool ( ) const

explicitfinalvirtualnoexcept

Whether the source is prepared to read.

Returns: true if State is State::Idle and not EoF.

◆ operator=() [1/2]

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

noexcept

Move assignment.

Parameters

other Instance to take from. Left Unavailable.

Returns: *this.

◆ operator=() [2/2]

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

delete

Copy assignment is deleted.

◆ OriginCanSeek()

virtual bool StormByte::Buffer::IO::BufferedReader::OriginCanSeek ( ) const

protectedpure virtualnoexcept

Whether the device can seek.

Returns: true if OriginSeek is usable.

Implemented in StormByte::Buffer::IO::BufferedLocationReader.

◆ OriginClose()

virtual Result StormByte::Buffer::IO::BufferedReader::OriginClose ( )

protectedpure virtual

Release the underlying device and SetState Unavailable.

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

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

◆ OriginHasSize()

virtual bool StormByte::Buffer::IO::BufferedReader::OriginHasSize ( ) const

protectedpure virtualnoexcept

Whether the device reports a length.

Returns: true if OriginSize has a value.

Implemented in StormByte::Buffer::IO::BufferedLocationReader.

◆ OriginOpen()

virtual Result StormByte::Buffer::IO::BufferedReader::OriginOpen ( )

protectedpure virtual

Arm the underlying device and SetState.

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

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

◆ OriginPull()

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

protectedpure virtual

Read up to n bytes from the device into dest.

Parameters

n	Maximum bytes to transfer.
dest	Implementation FIFO (not the user destination).

Returns: IO::Status::Ok, IO::Status::End, IO::Status::Error or IO::Status::Failed.

On IO::Status::Error call SetState with State::Fault or State::Unavailable.

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

◆ OriginSeek()

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

protectedpure virtual

Seek the device.

Parameters

offset	Byte offset.
mode	Absolute or relative to the device cursor.

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

May be slow. Called from a pull when the device cursor is not already at the requested offset.

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

◆ OriginSize()

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

protectedpure virtualnoexcept

Device length in bytes.

Returns: Length, or empty when unknown.

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

◆ Path()

const StormByte::String::String & StormByte::Buffer::IO::BufferedReader::Path ( ) const

noexcept

Locator stored at construction.

Does not change.

A file path, socket://… or http://… . A file leaf's path is always a local filesystem path.

Returns: Owned text. Empty if moved-from.

◆ Peek() [1/2]

virtual Result StormByte::Buffer::IO::BufferedReader::Peek ( std::span< std::byte > dest ) const

finalvirtual

Copy into dest without consuming cache.

Parameters

dest	Caller span. Request size is `dest.size()`.

Returns: Status and byte count written to the front of dest.

An empty span returns IO::Status::Ok and count 0 without pulling. The first count bytes of dest are written; the tail is left unchanged.

◆ Peek() [2/2]

virtual Result StormByte::Buffer::IO::BufferedReader::Peek	(	StormByte::ByteSize	n,
		FIFO &	dest
	)		const

finalvirtual

Copy n bytes into dest without consuming cache.

Parameters

n	Byte count. Zero copies the current span from Tell.
dest	Caller FIFO. Overwritten on Ok / End with count > 0.

Returns: Status and byte count written to dest.

◆ Read() [1/2]

virtual Result StormByte::Buffer::IO::BufferedReader::Read ( std::span< std::byte > dest ) const

finalvirtual

Read into dest, consuming cache / origin.

Parameters

dest	Caller span. Request size is `dest.size()`.

Returns: Status and byte count written to the front of dest.

An empty span returns IO::Status::Ok and count 0 without consuming or pulling. The first count bytes of dest are written; the tail is left unchanged.

◆ Read() [2/2]

virtual Result StormByte::Buffer::IO::BufferedReader::Read	(	StormByte::ByteSize	n,
		FIFO &	dest
	)		const

finalvirtual

Read n bytes into dest, consuming cache / origin.

Parameters

n	Byte count. Zero serves the current cached span from Tell.
dest	Caller FIFO. Overwritten on Ok / End with count > 0.

Returns: Status and byte count written to dest.

◆ ReadAhead() [1/2]

virtual StormByte::ByteSize StormByte::Buffer::IO::BufferedReader::ReadAhead ( ) const

virtualnoexcept

Configured prefetch length in bytes.

Returns: Current ReadAhead. 0 disables prefetch.

◆ ReadAhead() [2/2]

virtual void StormByte::Buffer::IO::BufferedReader::ReadAhead ( StormByte::ByteSize bytes )

virtual

Set prefetch length.

Takes effect immediately.

Parameters

bytes Bytes to hold ahead of the cursor after a Read.

Cancels in-flight prefetch and may trim the cache before returning. Does not pull from the origin. Still waits for the worker.

◆ Rewind()

virtual bool StormByte::Buffer::IO::BufferedReader::Rewind ( )

finalvirtual

Re-arm an open source: Close then Open.

Returns: true if session state is Idle afterwards. false if not currently armed.

◆ Seek()

virtual Result StormByte::Buffer::IO::BufferedReader::Seek	(	std::ptrdiff_t	offset,
		Position	mode
	)		const

finalvirtual

Move the logical read cursor.

Parameters

offset	Byte offset.
mode	Position::Absolute or Position::Relative.

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

Does not call OriginSeek. The device is realigned on a later pull only if that pull's offset is not the current device cursor. Non-seekable origins return Failed without invoking the hook. Negative absolute offsets and relative steps before offset 0 fail. Not currently armed also fails.

Latency: Not O(1). May block on prefetch cancellation. Immediate return is not part of the contract.

◆ SetState()

void StormByte::Buffer::IO::BufferedReader::SetState ( enum State state )

protectednoexcept

Publish session state from a leaf hook.

Parameters

state New State.

Called from OriginOpen, OriginClose and OriginPull. Not for user code.

◆ Setup()

virtual void StormByte::Buffer::IO::BufferedReader::Setup ( )

protectedvirtual

Leaf policy hook.

Called from Open before the origin.

Default does nothing. File uses it for the path-only ctor. The most-derived vtable is live.

Reimplemented in StormByte::Buffer::IO::BufferedLocationReader.

◆ Size()

virtual std::optional< StormByte::ByteSize > StormByte::Buffer::IO::BufferedReader::Size ( ) const

finalvirtualnoexcept

Origin length in bytes when known.

Returns: Length, or empty if IsSized is false.

◆ State()

virtual enum State StormByte::Buffer::IO::BufferedReader::State ( ) const

finalvirtualnoexcept

Session state.

Returns: Current State.

◆ Telemetry()

const StormByte::Shared< StormByte::Buffer::ReadTelemetry > StormByte::Buffer::IO::BufferedReader::Telemetry ( ) const

noexcept

Shared read counters.

Same instance for the life of this reader.

Returns: Const handle. Empty if moved-from.

The user cannot reseat the handle. The office updates the same object. Survivors keep the last values. A leaf may store a wider dynamic type via CreateTelemetry.

◆ Tell()

virtual StormByte::ByteSize StormByte::Buffer::IO::BufferedReader::Tell ( ) const

finalvirtualnoexcept

Logical read offset in the stream.

Returns: Bytes from the origin start (0 after Open / Rewind).

Friends And Related Symbol Documentation

◆ StormByte::Buffer::Backend::IO::BufferedReader

friend class StormByte::Buffer::Backend::IO::BufferedReader

friend

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

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

Classes

Public Member Functions

Protected Member Functions

Friends

Detailed Description

Constructor & Destructor Documentation

◆ BufferedReader() [1/4]

◆ BufferedReader() [2/4]

◆ ~BufferedReader()

◆ BufferedReader() [3/4]

◆ BufferedReader() [4/4]

Member Function Documentation

◆ Available()

◆ Close()

◆ CreateTelemetry()

◆ EoF()

◆ IsOpen()

◆ IsReadable()

◆ IsSeekable()

◆ IsSized()

◆ Location()

◆ MaxMemory() [1/2]

◆ MaxMemory() [2/2]

◆ MaxWait() [1/2]

◆ MaxWait() [2/2]

◆ Open()

◆ operator bool()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ OriginCanSeek()

◆ OriginClose()

◆ OriginHasSize()

◆ OriginOpen()

◆ OriginPull()

◆ OriginSeek()

◆ OriginSize()

◆ Path()

◆ Peek() [1/2]

◆ Peek() [2/2]

◆ Read() [1/2]

◆ Read() [2/2]

◆ ReadAhead() [1/2]

◆ ReadAhead() [2/2]

◆ Rewind()

◆ Seek()

◆ SetState()

◆ Setup()

◆ Size()

◆ State()

◆ Telemetry()

◆ Tell()

Friends And Related Symbol Documentation

◆ StormByte::Buffer::Backend::IO::BufferedReader