StormByte-Buffer 4.0.0
C++26 buffer module of the StormByte suite
Loading...
Searching...
No Matches
buffered_writer.hxx
Go to the documentation of this file.
1/*
2 * Copyright (C) 2024-2026 David C. Manuelda (StormBytePP)
3 *
4 * This file is part of StormByte-Buffer.
5 *
6 * StormByte-Buffer original source is dual-licensed:
7 *
8 * 1. GNU Lesser General Public License v3.0 (or later)
9 * You may redistribute and/or modify this file under the terms of the
10 * GNU Lesser General Public License as published by the Free Software
11 * Foundation, either version 3 of the License, or (at your option)
12 * any later version.
13 *
14 * 2. Commercial license
15 * Alternatively, this file may be used under the terms of a commercial
16 * license agreement with the copyright holder
17 * (David C. Manuelda <StormByte@gmail.com>).
18 *
19 * Both licenses apply only to original StormByte-Buffer source in this
20 * repository. They do not cover other StormByte modules or any third-party
21 * material shipped with this repository (including everything under
22 * thirdparty/, and in particular the bundled StormByte-Logger tree and
23 * the rest of the StormByte suite it vendors), which remains under its own
24 * license.
25 *
26 * Neither license grants any patent rights. Any patent licenses required
27 * to use this software or third-party components must be obtained separately
28 * from the patent holders.
29 *
30 * StormByte-Buffer is distributed in the hope that it will be useful,
31 * but WITHOUT ANY WARRANTY; without even the implied warranty of
32 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
33 * GNU Lesser General Public License for more details.
34 *
35 * You should have received a copy of the GNU Lesser General Public License
36 * version 3 along with StormByte-Buffer. If not, see
37 * <https://www.gnu.org/licenses/lgpl-3.0.html>.
38 *
39 * SPDX-License-Identifier: LGPL-3.0-or-later OR LicenseRef-StormByte-Commercial
40 */
41
42#pragma once
43
44#include <StormByte/type_traits/safe.hxx>
45
53#include <StormByte/safe/pointers.hxx>
54#include <StormByte/safe/string.hxx>
55#include <StormByte/type_traits.hxx>
56
57#include <chrono>
58#include <cstddef>
59#include <memory>
60#include <span>
61#include <utility>
62
67namespace StormByte {
72 namespace Buffer {
77 namespace Backend {
82 class Bridge;
83
88 namespace IO {
93 class BufferedWriter;
94 }
95 }
96
101 namespace IO {
235 friend class StormByte::Buffer::Backend::IO::BufferedWriter;
236 friend class StormByte::Buffer::Backend::Bridge;
237
238 public:
247 public:
251 Parameters() = default;
252
258 template<typename... Knobs>
259 Parameters(Knobs... knobs): WriterParameters(std::move(knobs)...) {}
260
265 Parameters(const Parameters& other) = default;
266
271 Parameters(Parameters&& other) noexcept = default;
272
276 ~Parameters() noexcept = default;
277
283 Parameters& operator=(const Parameters& other) = default;
284
290 Parameters& operator=(Parameters&& other) noexcept = default;
291 };
292
297
302
308
314 virtual ~BufferedWriter() noexcept;
315
320 BufferedWriter& operator=(const BufferedWriter&) = delete;
321
327 BufferedWriter& operator=(BufferedWriter&& other) noexcept;
328
332
341 const StormByte::Safe::String& Path() const noexcept;
342
347 enum Location Location() const noexcept;
348
353 virtual explicit operator bool() const noexcept final;
354
359 virtual enum State State() const noexcept final;
360
365
373 virtual bool Open() final;
374
383 virtual bool Close() final;
384
389 virtual bool Rewind() final;
390
395 virtual bool IsOpen() const noexcept final;
396
405 virtual Result Flush() final;
406
413 virtual Result Truncate() final;
414
418
423
429 virtual Result Write(const FIFO& src) final;
430
436 virtual Result Write(FIFO& src) final;
437
443 virtual Result Write(std::span<const std::byte> src) final;
444
448
453
458 virtual StormByte::ByteSize Tell() const noexcept;
459
464 virtual StormByte::ByteSize Dirty() const noexcept;
465
474 virtual StormByte::ByteSize Size() const noexcept;
475
488 virtual Result Seek(std::ptrdiff_t offset, Position mode);
489
493
498
506 const StormByte::Safe::Shared<StormByte::Buffer::WriteTelemetry> Telemetry() const noexcept;
507
511
516
521 StormByte::ByteSize WriteChunk() const noexcept;
522
528
535
541
548
554
562
567 TransferSnapshot Transfers() const noexcept;
568
578
583 std::size_t BackPressure() const noexcept;
584
592 void BackPressure(std::size_t chunks);
593
600 StormByte::ByteSize MaxMemory() const noexcept;
601
610
615 std::chrono::milliseconds MaxWait() const noexcept;
616
624 void MaxWait(std::chrono::milliseconds wait);
625
629
630 protected:
638 Parameters parameters = {}):
639 BufferedWriter(std::move(path), location, WriterConfiguration{
640 parameters.WriteChunk().value_or(StormByte::ByteSize{0}),
641 parameters.BackPressure().value_or(0),
642 parameters.MaxWait().value_or(0),
643 parameters.MaxMemory().value_or(StormByte::ByteSize{0}),
644 parameters.WriteTransfer().value_or(StormByte::ByteSize{0}),
645 parameters.WriteThreshold().value_or(StormByte::ByteSize{0})}) {}
646
656 WriterConfiguration configuration);
657
662 void SetState(enum State state) noexcept;
663
668 void SetTell(StormByte::ByteSize offset) noexcept;
669
676 virtual void Setup();
677
686
696 virtual bool WillWrite(StormByte::ByteSize n) const;
697
702
707 virtual Result OriginOpen() = 0;
708
713 virtual Result OriginClose() = 0;
714
721 virtual Result OriginPush(std::span<const std::byte> data) = 0;
722
730 virtual Result OriginFlush() = 0;
731
736 virtual Result OriginTruncate() = 0;
737
747
751
752 private:
756 std::unique_ptr<StormByte::Buffer::Backend::IO::BufferedWriter> m_io;
757 };
758 }
759 }
760}
761
Private pump for StormByte::Buffer::Bridge.
Private implementation of StormByte::Buffer::IO::BufferedWriter.
Byte-oriented FIFO buffer with grow-on-demand and close/error support.
Definition fifo.hxx:86
Writer knobs.
Definition buffered_writer.hxx:246
Parameters(Parameters &&other) noexcept=default
Transfer Safe-owned knobs.
Parameters(Knobs... knobs)
Store writer knobs in Safe-owned optional values.
Definition buffered_writer.hxx:259
~Parameters() noexcept=default
Release knobs through provider callbacks.
Parameters()=default
Construct an empty Safe-owned parameter bag.
Parameters(const Parameters &other)=default
Copy Safe-owned knobs; may allocate and throw.
Coordinated binary write sink with optional chunked write-behind and a delayed-seek page map.
Definition buffered_writer.hxx:234
BufferedWriter(StormByte::Safe::String path, enum Location location, WriterConfiguration configuration)
Construct an unopened coordinator (State::Unavailable).
TransferSnapshot Transfers() const noexcept
Read effective limits and real origin activity without I/O.
void SetTell(StormByte::ByteSize offset) noexcept
Publish the logical write offset from a leaf Seek.
virtual Result Flush() final
Materialise every dirty page, drain the ring and OriginFlush.
StormByte::ByteSize WriteThreshold() const noexcept
Page drain high watermark.
virtual StormByte::ByteSize Tell() const noexcept
Logical write offset.
WriterConfiguration Configuration() const noexcept
Read the complete policy without I/O.
virtual enum State State() const noexcept final
Session state.
virtual Result OriginFlush()=0
Make accepted bytes visible on the device.
virtual bool Rewind() final
Re-arm: Close then Open when currently armed.
virtual bool Close() final
Flush then close the origin.
friend class StormByte::Buffer::Backend::IO::BufferedWriter
Definition buffered_writer.hxx:235
virtual Result OriginPush(std::span< const std::byte > data)=0
Write data to the device.
virtual Result OriginClose()=0
Release the device and SetState Unavailable.
StormByte::ByteSize MaxMemory() const noexcept
Byte budget for dirty pages that are not yet on the origin.
virtual Result Write(const FIFO &src) final
Write every unread byte of src.
virtual void Setup()
Leaf policy hook.
virtual StormByte::ByteSize Size() const noexcept
Logical sink length in bytes.
virtual Result OriginTruncate()=0
Discard origin contents.
virtual StormByte::Safe::Shared< StormByte::Buffer::WriteTelemetry > CreateTelemetry() const
Allocate the telemetry object this instance will keep.
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.
std::size_t BackPressure() const noexcept
Configured dirty cap in WriteChunk units.
virtual Result OriginSeek(StormByte::ByteSize absolute)
Seek the origin to absolute.
StormByte::ByteSize WriteChunk() const noexcept
Configured ring unit and drain trigger, not a transfer maximum.
void SetState(enum State state) noexcept
Publish session state from a leaf hook.
virtual Result Truncate() final
Drop dirty pages and the ring, then truncate the origin.
Result Configure(WriterConfiguration configuration)
Flush old policy and atomically replace it, including ring capacity.
std::chrono::milliseconds MaxWait() const noexcept
Wait cap for OriginPush.
const StormByte::Safe::String & Path() const noexcept
Locator stored at construction.
const StormByte::Safe::Shared< StormByte::Buffer::WriteTelemetry > Telemetry() const noexcept
Shared write counters.
virtual Result OriginOpen()=0
Arm the device and SetState.
virtual bool WillWrite(StormByte::ByteSize n) const
Whether n more bytes can be accepted now.
enum Location Location() const noexcept
Where Path points.
StormByte::ByteSize WriteTransfer() const noexcept
Maximum origin request in every mode.
virtual bool IsOpen() const noexcept final
Whether Open succeeded and Close has not.
virtual bool Open() final
Arm the origin.
Writer counters on top of StormByte::Buffer::WriteTelemetry.
Definition telemetry.hxx:328
STORMBYTE_DECLARE_MAYBE_SAFE(class StormByte::System::Device::Access)
PIMPL coordinators for public Buffer types that are not IO.
Buffered binary sources and sinks.
Buffer module of the StormByte suite.
Position
Forward declaration of the WriteOnly interface.
Definition typedefs.hxx:74
Root namespace of the StormByte C++ suite.
STL namespace.
#define STORMBYTE_FORCE_INLINE
Per-call status plus how many bytes this call transferred.
Definition typedefs.hxx:214
Non-I/O snapshot.
Definition parameters.hxx:256
Complete non-owning writer policy; Configure applies all fields together.
Definition parameters.hxx:244
#define STORMBYTE_BUFFER_PUBLIC
Definition visibility.h:54