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

Inheritance diagram for StormByte::Buffer::IO::BufferedLocationWriter:

[legend]

Collaboration diagram for StormByte::Buffer::IO::BufferedLocationWriter:

Classes
class	Parameters
	Location-writer knobs. More...

Public Member Functions
	BufferedLocationWriter (const BufferedLocationWriter &)=delete
	Copy constructor is deleted.

	BufferedLocationWriter (BufferedLocationWriter &&other) noexcept
	Move constructor.

virtual	~BufferedLocationWriter () noexcept override
	Destructor.

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

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

StormByte::Shared< StormByte::System::Device >	Device () const
	Measurement of this location.

bool	IsSeekable () const noexcept
	This location can seek.

bool	IsSized () const noexcept
	This location has a length.

StormByte::ByteSize	Size () const noexcept final
	Length from the leaf.

Public Member Functions inherited from StormByte::Buffer::IO::BufferedWriter
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 sink is prepared to write.

virtual enum State	State () const noexcept final
	Session state.

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

	BufferedWriter (BufferedWriter &&other) noexcept
	Move constructor.

virtual	~BufferedWriter () noexcept
	Virtual destructor.

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

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

virtual bool	Open () final
	Arm the origin.

virtual bool	Close () final
	Flush then close the origin.

virtual bool	Rewind () final
	Re-arm: Close then Open when currently armed.

virtual bool	IsOpen () const noexcept final
	Whether Open succeeded and Close has not.

virtual Result	Flush () final
	Materialise every dirty page, drain the ring and OriginFlush.

virtual Result	Truncate () final
	Drop dirty pages and the ring, then truncate the origin.

virtual Result	Write (const FIFO &src) final
	Write every unread byte of `src`.

virtual Result	Write (FIFO &src) final
	Write every unread byte of `src`.

virtual Result	Write (std::span< const std::byte > src) final
	Write the whole span.

virtual StormByte::ByteSize	Tell () const noexcept
	Logical write offset.

virtual StormByte::ByteSize	Dirty () const noexcept
	Bytes not yet on the origin.

virtual Result	Seek (std::ptrdiff_t offset, Position mode)
	Move the write cursor.

const StormByte::Shared< StormByte::Buffer::WriteTelemetry >	Telemetry () const noexcept
	Shared write counters.

virtual StormByte::ByteSize	WriteChunk () const noexcept
	Configured origin push unit.

virtual void	WriteChunk (StormByte::ByteSize bytes)
	Set origin push unit.

virtual std::size_t	BackPressure () const noexcept
	Configured dirty cap in WriteChunk units.

virtual void	BackPressure (std::size_t chunks)
	Set dirty cap in WriteChunk units.

virtual StormByte::ByteSize	MaxMemory () const noexcept
	Byte budget for dirty pages that are not yet on the origin.

virtual void	MaxMemory (StormByte::ByteSize bytes)
	Set the dirty-page budget.

virtual std::chrono::milliseconds	MaxWait () const noexcept
	Wait cap for OriginPush.

virtual void	MaxWait (std::chrono::milliseconds wait)
	Set wait cap for OriginPush.

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

	BufferedLocationWriter (StormByte::String::String path, enum Location location, StormByte::ByteSize write_chunk, std::size_t back_pressure, std::chrono::milliseconds max_wait, StormByte::ByteSize max_memory, bool probe)
	Forward the locator and the sink 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`.

virtual StormByte::ByteSize	OriginSize () const noexcept=0
	Length the leaf can answer.

virtual Result	OriginSeek (StormByte::ByteSize absolute)=0
	Seek the origin to an absolute offset.

void	Setup () final
	Apply the device write window when the constructor asked for a probe.

Protected Member Functions inherited from StormByte::Buffer::IO::BufferedWriter
STORMBYTE_FORCE_INLINE	BufferedWriter (StormByte::String::String path, enum Location location, Parameters parameters={})
	Construct an unopened coordinator (State::Unavailable).

	BufferedWriter (StormByte::String::String path, enum Location location, StormByte::ByteSize write_chunk, std::size_t back_pressure, std::chrono::milliseconds max_wait, StormByte::ByteSize max_memory)
	Construct an unopened coordinator (State::Unavailable).

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

void	SetTell (StormByte::ByteSize offset) noexcept
	Publish the logical write offset from a leaf Seek.

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

virtual bool	WillWrite (StormByte::ByteSize n) const
	Whether `n` more bytes can be accepted now.

virtual Result	OriginOpen ()=0
	Arm the device and SetState.

virtual Result	OriginClose ()=0
	Release the device and SetState Unavailable.

virtual Result	OriginPush (std::span< const std::byte > data)=0
	Write `data` to the device.

virtual Result	OriginFlush ()=0
	Make accepted bytes visible on the device.

virtual Result	OriginTruncate ()=0
	Discard origin contents.

Detailed Description

File-like BufferedWriter.

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 BufferedWriter instead.

IsSeekable and IsSized are always true. Size is OriginSize. The leaf does not override Size. OriginSeek is pure: the base default that only fails is not enough.

Path and Location live on BufferedWriter. 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, backpressure 4 and 1 MiB of MaxMemory when the caller omitted WriteChunk, BackPressure and MaxMemory, and OriginDeviceUsable accepts the device.

The leaf implements OriginOpen, OriginClose, OriginPush, OriginFlush, OriginTruncate, OriginSeek, OriginSize and OriginDevice.

See also: BufferedWriter, BufferedFileWriter

Constructor & Destructor Documentation

◆ BufferedLocationWriter() [1/4]

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

delete

Copy constructor is deleted.

◆ BufferedLocationWriter() [2/4]

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

noexcept

Move constructor.

Transfers the location. Moved-from has none.

Parameters

other Instance to take from.

◆ ~BufferedLocationWriter()

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

overridevirtualnoexcept

Destructor.

Releases the location in this module.

◆ BufferedLocationWriter() [3/4]

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

inlineprotected

Store the locator and resolve knobs in the caller.

Parameters

path	Locator. Stored once on BufferedWriter.
location	Location::Local or Location::Remote. Stored once.
parameters	Omitted WriteChunk, BackPressure and MaxMemory → Setup probes the device. Omitted MaxWait → 0 ms.

◆ BufferedLocationWriter() [4/4]

StormByte::Buffer::IO::BufferedLocationWriter::BufferedLocationWriter	(	StormByte::String::String	path,
		enum Location	location,
		StormByte::ByteSize	write_chunk,
		std::size_t	back_pressure,
		std::chrono::milliseconds	max_wait,
		StormByte::ByteSize	max_memory,
		bool	probe
	)

protected

Forward the locator and the sink knobs.

Parameters

path	Locator. Stored once on BufferedWriter.
location	Location::Local or Location::Remote. Stored once.
write_chunk	Initial WriteChunk. Ignored when `probe` is true.
back_pressure	Initial BackPressure.
max_wait	Initial MaxWait.
max_memory	Initial MaxMemory. Ignored when `probe` is true.
probe	When true, Setup replaces chunk, backpressure and MaxMemory.

DLL boundary. m_io is created here.

Member Function Documentation

◆ Device()

StormByte::Shared< StormByte::System::Device > StormByte::Buffer::IO::BufferedLocationWriter::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.

◆ IsSeekable()

bool StormByte::Buffer::IO::BufferedLocationWriter::IsSeekable ( ) const

noexcept

This location can seek.

Returns: true.

◆ IsSized()

bool StormByte::Buffer::IO::BufferedLocationWriter::IsSized ( ) const

noexcept

This location has a length.

Returns: true.

◆ operator=() [1/2]

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

noexcept

Move assignment.

Parameters

other Instance to take from.

Returns: *this.

◆ operator=() [2/2]

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

delete

Copy assignment is deleted.

Returns: *this.

◆ OriginDevice()

virtual StormByte::Shared< StormByte::System::Device > StormByte::Buffer::IO::BufferedLocationWriter::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::BufferedFileWriter.

◆ OriginDeviceUsable()

virtual bool StormByte::Buffer::IO::BufferedLocationWriter::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.

◆ OriginSeek()

virtual Result StormByte::Buffer::IO::BufferedLocationWriter::OriginSeek ( StormByte::ByteSize absolute )

protectedpure virtual

Seek the origin to an absolute offset.

Required.

Parameters

absolute Byte offset from the start.

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

Reimplemented from StormByte::Buffer::IO::BufferedWriter.

Implemented in StormByte::Buffer::IO::BufferedFileWriter.

◆ OriginSize()

virtual StormByte::ByteSize StormByte::Buffer::IO::BufferedLocationWriter::OriginSize ( ) const

protectedpure virtualnoexcept

Length the leaf can answer.

Not optional.

Returns: Byte length. A missing target is 0.

Implemented in StormByte::Buffer::IO::BufferedFileWriter.

◆ Setup()

void StormByte::Buffer::IO::BufferedLocationWriter::Setup ( )

finalprotectedvirtual

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

OriginDevice is called once. When OriginDeviceUsable rejects the owner, WriteChunk, BackPressure and MaxMemory keep their defaults.

Reimplemented from StormByte::Buffer::IO::BufferedWriter.

◆ Size()

StormByte::ByteSize StormByte::Buffer::IO::BufferedLocationWriter::Size ( ) const

finalvirtualnoexcept

Length from the leaf.

Returns: OriginSize.

Reimplemented from StormByte::Buffer::IO::BufferedWriter.

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

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

Classes

Public Member Functions

Protected Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ BufferedLocationWriter() [1/4]

◆ BufferedLocationWriter() [2/4]

◆ ~BufferedLocationWriter()

◆ BufferedLocationWriter() [3/4]

◆ BufferedLocationWriter() [4/4]

Member Function Documentation

◆ Device()

◆ IsSeekable()

◆ IsSized()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ OriginDevice()

◆ OriginDeviceUsable()

◆ OriginSeek()

◆ OriginSize()

◆ Setup()

◆ Size()