Final BufferedLocationWriter over a filesystem file. More...

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

Inheritance diagram for StormByte::Buffer::IO::BufferedFileWriter:

[legend]

Collaboration diagram for StormByte::Buffer::IO::BufferedFileWriter:

[legend]

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

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

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

	BufferedFileWriter (BufferedFileWriter &&other) noexcept
	Move constructor.

	~BufferedFileWriter () noexcept override
	Destructor.

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

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

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

StormByte::ByteSize	OriginSize () const noexcept override
	On-disk size or the write cursor, whichever is larger.

Result	OriginOpen () override
	Open the path for binary random-access write.

Result	OriginClose () override
	Close the file stream.

Result	OriginPush (std::span< const std::byte > data) override
	Write `data` to the file.

Result	OriginFlush () override
	Make written bytes visible to later readers of the path.

Result	OriginTruncate () override
	Resize the file to zero bytes.

Result	OriginSeek (StormByte::ByteSize absolute) override
	Seek the file stream to an absolute byte offset.

bool	WillWrite (StormByte::ByteSize n) const override
	Whether the volume looks able to accept `n` more bytes.

Protected Member Functions inherited from StormByte::Buffer::IO::BufferedLocationWriter
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 bool	OriginDeviceUsable (const StormByte::Shared< StormByte::System::Device > &device) const noexcept
	Whether Setup may read windows from `device`.

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.

Detailed Description

Final BufferedLocationWriter over a filesystem file.

Binary file, random-access. Open creates the file when missing and leaves existing content. Overwrite is Truncate. Does not open in the constructor. Does not create parent directories.

The device does not change after construction. Chunk, backpressure and MaxMemory come from BufferedLocationWriter::Setup when those knobs are omitted.

Constructors: BufferedFileWriter(path) and BufferedFileWriter(path, {}) ask the location layer to probe. BufferedFileWriter(path, { WriteChunk(n), BackPressure(k) }) stores those values and leaves MaxMemory at 0. Adding MaxMemory(m) stores the page budget too. A zero chunk or backpressure disables the ring. A zero MaxMemory stores no pages.

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

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

See also: BufferedLocationWriter, State

Constructor & Destructor Documentation

◆ BufferedFileWriter() [1/3]

STORMBYTE_FORCE_INLINE StormByte::Buffer::IO::BufferedFileWriter::BufferedFileWriter	(	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.

All of WriteChunk, BackPressure and MaxMemory omitted → Setup probes the device. Any of those set → explicit: omitted MaxMemory is 0, omitted chunk / backpressure is 0. Omitted MaxWait → 0 ms.

◆ BufferedFileWriter() [2/3]

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

delete

Copy constructor is deleted.

◆ BufferedFileWriter() [3/3]

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

noexcept

Move constructor.

Parameters

other Instance to take from.

◆ ~BufferedFileWriter()

StormByte::Buffer::IO::BufferedFileWriter::~BufferedFileWriter ( )

overridenoexcept

Destructor.

Calls Close while the leaf vtable is live.

Member Function Documentation

◆ operator=() [1/2]

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

noexcept

Move assignment.

Parameters

other Instance to take from.

Returns: *this.

◆ operator=() [2/2]

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

delete

Copy assignment is deleted.

Returns: *this.

◆ OriginClose()

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

overrideprotectedvirtual

Close the file stream.

Returns: Status::Ok.

Implements StormByte::Buffer::IO::BufferedWriter.

◆ OriginDevice()

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

◆ OriginFlush()

Result StormByte::Buffer::IO::BufferedFileWriter::OriginFlush ( )

overrideprotectedvirtual

Make written bytes visible to later readers of the path.

Returns: Status::Ok, Error or Failed.

Implements StormByte::Buffer::IO::BufferedWriter.

◆ OriginOpen()

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

overrideprotectedvirtual

Open the path for binary random-access write.

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

Creates the file when missing. Does not truncate an existing file.

Implements StormByte::Buffer::IO::BufferedWriter.

◆ OriginPush()

Result StormByte::Buffer::IO::BufferedFileWriter::OriginPush ( std::span< const std::byte > data )

overrideprotectedvirtual

Write data to the file.

Parameters

data	Contiguous octets.

Returns: Ok with bytes written, Error or Failed.

Implements StormByte::Buffer::IO::BufferedWriter.

◆ OriginSeek()

Result StormByte::Buffer::IO::BufferedFileWriter::OriginSeek ( StormByte::ByteSize absolute )

overrideprotectedvirtual

Seek the file stream to an absolute byte offset.

Parameters

absolute Byte offset from the start of the file.

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

Implements StormByte::Buffer::IO::BufferedLocationWriter.

◆ OriginSize()

StormByte::ByteSize StormByte::Buffer::IO::BufferedFileWriter::OriginSize ( ) const

overrideprotectedvirtualnoexcept

On-disk size or the write cursor, whichever is larger.

Returns: Byte length. 0 when the path cannot be stated.

Implements StormByte::Buffer::IO::BufferedLocationWriter.

◆ OriginTruncate()

Result StormByte::Buffer::IO::BufferedFileWriter::OriginTruncate ( )

overrideprotectedvirtual

Resize the file to zero bytes.

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

Implements StormByte::Buffer::IO::BufferedWriter.

◆ WillWrite()

bool StormByte::Buffer::IO::BufferedFileWriter::WillWrite ( StormByte::ByteSize n ) const

overrideprotectedvirtual

Whether the volume looks able to accept n more bytes.

Parameters

n	Candidate write.

Returns: false when the base writer refuses or free space is short.

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

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

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

Classes

Public Member Functions

Protected Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ BufferedFileWriter() [1/3]

◆ BufferedFileWriter() [2/3]

◆ BufferedFileWriter() [3/3]

◆ ~BufferedFileWriter()

Member Function Documentation

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ OriginClose()

◆ OriginDevice()

◆ OriginFlush()

◆ OriginOpen()

◆ OriginPush()

◆ OriginSeek()

◆ OriginSize()

◆ OriginTruncate()

◆ WillWrite()