StormByte-Buffer 4.0.0
C++26 buffer module of the StormByte suite
Loading...
Searching...
No Matches
buffered_reader.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/optional.hxx>
54#include <StormByte/safe/pointers.hxx>
55#include <StormByte/safe/string.hxx>
56#include <StormByte/type_traits.hxx>
57
58#include <chrono>
59#include <cstddef>
60#include <memory>
61#include <span>
62#include <utility>
63
68namespace StormByte {
73 namespace Buffer {
78 namespace Backend {
83 namespace IO {
88 class BufferedReader;
89 }
90 }
91
96 namespace IO {
215 friend class StormByte::Buffer::Backend::IO::BufferedReader;
216
217 public:
226 public:
230 Parameters() = default;
231
237 template<typename... Knobs>
238 Parameters(Knobs... knobs): ReaderParameters(std::move(knobs)...) {}
239
244 Parameters(const Parameters& other) = default;
245
250 Parameters(Parameters&& other) noexcept = default;
251
255 ~Parameters() noexcept = default;
256
262 Parameters& operator=(const Parameters& other) = default;
263
269 Parameters& operator=(Parameters&& other) noexcept = default;
270 };
271
276
281
287
294 virtual ~BufferedReader() noexcept;
295
299 BufferedReader& operator=(const BufferedReader&) = delete;
300
306 BufferedReader& operator=(BufferedReader&& other) noexcept;
307
311
320 const StormByte::Safe::String& Path() const noexcept;
321
326 enum Location Location() const noexcept;
327
332 virtual explicit operator bool() const noexcept final;
333
338 virtual enum State State() const noexcept final;
339
344
353 virtual bool Open() final;
354
361 virtual Result Close() final;
362
368 virtual bool Rewind() final;
369
374 virtual bool IsOpen() const noexcept final;
375
380 virtual bool IsReadable() const noexcept final;
381
387 virtual bool EoF() const noexcept final;
388
397 virtual StormByte::ByteSize Available() const noexcept final;
398
402
407
414 virtual Result Read(StormByte::ByteSize n, FIFO& dest) const final;
415
425 virtual Result Read(std::span<std::byte> dest) const final;
426
433 virtual Result Peek(StormByte::ByteSize n, FIFO& dest) const final;
434
444 virtual Result Peek(std::span<std::byte> dest) const final;
445
449
454
472 virtual Result Seek(std::ptrdiff_t offset, Position mode) const final;
473
478 virtual StormByte::ByteSize Tell() const noexcept final;
479
484 virtual bool IsSeekable() const noexcept final;
485
489
494
499 virtual bool IsSized() const noexcept final;
500
505 virtual StormByte::Safe::Optional<StormByte::ByteSize> Size() const noexcept final;
506
510
515
524 const StormByte::Safe::Shared<StormByte::Buffer::ReadTelemetry> Telemetry() const noexcept;
525
529
534
539 StormByte::ByteSize ReadAhead() const noexcept;
540
545 StormByte::ByteSize ReadChunk() const noexcept;
546
553
559
566
571 TransferSnapshot Transfers() const noexcept;
572
582
587 StormByte::ByteSize MaxMemory() const noexcept;
588
597
602 std::chrono::milliseconds MaxWait() const noexcept;
603
611 void MaxWait(std::chrono::milliseconds wait);
612
616
617 protected:
625 Parameters parameters = {}):
626 BufferedReader(std::move(path), location, ReaderConfiguration{
627 parameters.ReadChunk().value_or(StormByte::ByteSize{64 * 1024}),
628 parameters.ReadAhead().value_or(StormByte::ByteSize{0}),
629 parameters.MaxMemory().value_or(StormByte::ByteSize{0}),
630 parameters.MaxWait().value_or(0)}) {}
631
641 ReaderConfiguration configuration);
642
650 void SetState(enum State state) noexcept;
651
658 virtual void Setup();
659
669
674
679 virtual Result OriginOpen() = 0;
680
685 virtual Result OriginClose() = 0;
686
698
703 virtual bool OriginCanSeek() const noexcept = 0;
704
714 virtual Result OriginSeek(std::ptrdiff_t offset, Position mode) = 0;
715
720 virtual bool OriginHasSize() const noexcept = 0;
721
726 virtual StormByte::Safe::Optional<StormByte::ByteSize> OriginSize() const noexcept = 0;
727
731
732 private:
736 std::unique_ptr<StormByte::Buffer::Backend::IO::BufferedReader> m_io;
737 };
738 }
739 }
740}
741
Private implementation of StormByte::Buffer::IO::BufferedReader.
Byte-oriented FIFO buffer with grow-on-demand and close/error support.
Definition fifo.hxx:86
Reader knobs.
Definition buffered_reader.hxx:225
Parameters(Knobs... knobs)
Store reader knobs in Safe-owned optional values.
Definition buffered_reader.hxx:238
Parameters()=default
Construct an empty Safe-owned parameter bag.
Parameters(Parameters &&other) noexcept=default
Transfer Safe-owned knobs.
~Parameters() noexcept=default
Release knobs through provider callbacks.
Parameters(const Parameters &other)=default
Copy Safe-owned knobs; may allocate and throw.
Coordinated binary read source with optional prefetch and cache.
Definition buffered_reader.hxx:214
void SetState(enum State state) noexcept
Publish session state from a leaf hook.
const StormByte::Safe::String & Path() const noexcept
Locator stored at construction.
StormByte::ByteSize ReadAhead() const noexcept
Configured prefetch length in bytes.
const StormByte::Safe::Shared< StormByte::Buffer::ReadTelemetry > Telemetry() const noexcept
Shared read counters.
virtual Result OriginClose()=0
Release the underlying device and SetState Unavailable.
BufferedReader(StormByte::Safe::String path, enum Location location, ReaderConfiguration configuration)
Construct an unopened coordinator (State::Unavailable).
virtual StormByte::ByteSize Tell() const noexcept final
Logical read offset in the stream.
virtual bool IsOpen() const noexcept final
Whether Open succeeded and Close has not.
virtual Result Close() final
Stop prefetch, drop caches, close the origin.
virtual StormByte::ByteSize Available() const noexcept final
Cached bytes readable at Tell without touching the origin.
virtual bool OriginCanSeek() const noexcept=0
Whether the device can seek.
virtual bool OriginHasSize() const noexcept=0
Whether the device reports a length.
virtual Result OriginPull(StormByte::ByteSize n, FIFO &dest)=0
Read up to n bytes from the device into dest.
virtual StormByte::Safe::Shared< StormByte::Buffer::ReadTelemetry > CreateTelemetry() const
Allocate the telemetry object this instance will keep.
enum Location Location() const noexcept
Where Path points.
virtual void Setup()
Leaf policy hook.
virtual enum State State() const noexcept final
Session state.
virtual StormByte::Safe::Optional< StormByte::ByteSize > OriginSize() const noexcept=0
Device length in bytes.
virtual bool Open() final
Arm the origin.
virtual Result Seek(std::ptrdiff_t offset, Position mode) const final
Move the logical read cursor.
StormByte::ByteSize MaxMemory() const noexcept
Configured cache memory cap in bytes.
virtual bool EoF() const noexcept final
Whether no further bytes can be produced.
virtual StormByte::Safe::Optional< StormByte::ByteSize > Size() const noexcept final
Origin length in bytes when known.
virtual bool Rewind() final
Re-arm an open source: Close then Open.
virtual bool IsSeekable() const noexcept final
Whether this instance can reposition the origin.
virtual Result Read(StormByte::ByteSize n, FIFO &dest) const final
Read n bytes into dest, consuming cache / origin.
friend class StormByte::Buffer::Backend::IO::BufferedReader
Definition buffered_reader.hxx:215
Result Configure(ReaderConfiguration configuration)
Cancel prefetch and apply a complete policy after active reads finish.
StormByte::ByteSize ReadChunk() const noexcept
Maximum request passed to the origin.
virtual bool IsReadable() const noexcept final
Whether reads may be attempted.
ReaderConfiguration Configuration() const noexcept
Read the complete policy without I/O.
virtual Result OriginOpen()=0
Arm the underlying device and SetState.
virtual Result OriginSeek(std::ptrdiff_t offset, Position mode)=0
Seek the device.
std::chrono::milliseconds MaxWait() const noexcept
Configured read wait limit.
TransferSnapshot Transfers() const noexcept
Read effective limits and real origin activity without I/O.
virtual Result Peek(StormByte::ByteSize n, FIFO &dest) const final
Copy n bytes into dest without consuming cache.
virtual bool IsSized() const noexcept final
Whether the origin length is known.
Reader counters on top of StormByte::Buffer::ReadTelemetry.
Definition telemetry.hxx:95
STORMBYTE_DECLARE_MAYBE_SAFE(class StormByte::System::Device::Access)
PIMPL coordinators for the public IO types.
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
Complete non-owning reader policy; scalar time crosses the DLL.
Definition parameters.hxx:234
Per-call status plus how many bytes this call transferred.
Definition typedefs.hxx:214
Non-I/O snapshot.
Definition parameters.hxx:256
#define STORMBYTE_BUFFER_PUBLIC
Definition visibility.h:54