StormByte-Buffer 4.0.0
C++26 buffer module of the StormByte suite
Loading...
Searching...
No Matches
StormByte::Buffer::IO::BufferedLocationWriter Class Referenceabstract

File-like BufferedWriter. More...

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

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

Classes

class  Parameters
 Location-writer knobs. More...
struct  Unpacked
 Knobs after Parameters has been unpacked. 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::Safe::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::Safe::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::Safe::Shared< StormByte::Buffer::WriteTelemetry > Telemetry () const noexcept
 Shared write counters.
StormByte::ByteSize WriteChunk () const noexcept
 Configured ring unit and drain trigger, not a transfer maximum.
StormByte::ByteSize WriteTransfer () const noexcept
 Maximum origin request in every mode.
void WriteTransfer (StormByte::ByteSize bytes)
 Flush the old policy and replace the origin maximum.
StormByte::ByteSize WriteThreshold () const noexcept
 Page drain high watermark.
void WriteThreshold (StormByte::ByteSize bytes)
 Flush the old policy and replace the page watermark.
WriterConfiguration Configuration () const noexcept
 Read the complete policy without I/O.
Result Configure (WriterConfiguration configuration)
 Flush old policy and atomically replace it, including ring capacity.
TransferSnapshot Transfers () const noexcept
 Read effective limits and real origin activity without I/O.
void WriteChunk (StormByte::ByteSize bytes)
 Set origin push unit.
std::size_t BackPressure () const noexcept
 Configured dirty cap in WriteChunk units.
void BackPressure (std::size_t chunks)
 Set dirty cap in WriteChunk units.
StormByte::ByteSize MaxMemory () const noexcept
 Byte budget for dirty pages that are not yet on the origin.
void MaxMemory (StormByte::ByteSize bytes)
 Set the dirty-page budget.
std::chrono::milliseconds MaxWait () const noexcept
 Wait cap for OriginPush.
void MaxWait (std::chrono::milliseconds wait)
 Set wait cap for OriginPush.

Protected Member Functions

 BufferedLocationWriter (StormByte::Safe::String path, enum Location location, Unpacked knobs)
 Store the locator and the already-unpacked knobs.
virtual StormByte::Safe::Shared< StormByte::System::Device > OriginDevice () const =0
 Leaf measurement.
virtual bool OriginDeviceUsable (const StormByte::Safe::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.
Result OriginSeek (StormByte::ByteSize absolute) override=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::Safe::String path, enum Location location, Parameters parameters={})
 Construct an unopened coordinator (State::Unavailable).
 BufferedWriter (StormByte::Safe::String path, enum Location location, WriterConfiguration configuration)
 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::Safe::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::Safe::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/3]

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

Copy constructor is deleted.

◆ BufferedLocationWriter() [2/3]

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

Move constructor.

Transfers the location. Moved-from has none.

Parameters
otherInstance to take from.

◆ ~BufferedLocationWriter()

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

Destructor.

Releases the location in this module.

◆ BufferedLocationWriter() [3/3]

StormByte::Buffer::IO::BufferedLocationWriter::BufferedLocationWriter ( StormByte::Safe::String path,
enum Location location,
Unpacked knobs )
protected

Store the locator and the already-unpacked knobs.

Parameters
pathLocator. Stored once on BufferedWriter.
locationLocation::Local or Location::Remote. Stored once.
knobsResult of unpacking Parameters. Not a bag.

Not a delegating constructor. GCC would emit a reference to the complete-object constructor (C1) of an abstract class, and it does not emit that symbol. m_io is created in this module.

Member Function Documentation

◆ Device()

StormByte::Safe::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
otherInstance 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::Safe::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::Safe::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::Safe::Shared< StormByte::System::Device > & device) const
protectedvirtualnoexcept

Whether Setup may read windows from device.

Parameters
deviceOwner returned by OriginDevice. May be empty.
Returns
true when the device may be measured.

The default is a non-empty owner whose 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()

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

Seek the origin to an absolute offset.

Required.

Parameters
absoluteByte 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: