StormByte-Buffer 4.0.0
C++26 buffer module of the StormByte suite
Loading...
Searching...
No Matches
telemetry.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
47
48#include <chrono>
49#include <cstddef>
50
55namespace StormByte {
60 namespace Buffer {
65 namespace Backend {
70 namespace IO {
74 class BufferedReader;
78 class BufferedWriter;
79 }
80 }
81
86 namespace IO {
96 public:
100 ReadTelemetry() noexcept;
101
105 ReadTelemetry(const ReadTelemetry&) = delete;
106
111
115 virtual ~ReadTelemetry() noexcept override;
116
121 ReadTelemetry& operator=(const ReadTelemetry&) = delete;
122
127 ReadTelemetry& operator=(ReadTelemetry&&) = delete;
128
133 StormByte::ByteSize HitAhead() const noexcept;
134
139 StormByte::ByteSize HitBack() const noexcept;
140
145 StormByte::ByteSize Miss() const noexcept;
146
151 StormByte::ByteSize Origin() const noexcept;
152
157 StormByte::ByteSize Cached() const noexcept;
158
163 StormByte::ByteSize CachedPeak() const noexcept;
164
169 StormByte::ByteSize Cap() const noexcept;
170
175 std::size_t SeekLogical() const noexcept;
176
181 std::size_t SeekOrigin() const noexcept;
182
187 std::size_t SeekSavedFull() const noexcept;
188
193 std::size_t SeekSavedPartial() const noexcept;
194
199 std::size_t TryAgain() const noexcept;
200
205 std::size_t Saturated() const noexcept;
206
211 std::size_t Evicted() const noexcept;
212
217 std::chrono::nanoseconds WaitMin() const noexcept;
218
223 std::chrono::nanoseconds WaitMax() const noexcept;
224
229 std::chrono::nanoseconds WaitTotal() const noexcept;
230
235 std::size_t WaitSamples() const noexcept;
236
241 operator StormByte::Safe::String() const override;
242
243 protected:
245
277 mutable std::size_t m_seek_logical;
281 mutable std::size_t m_seek_origin;
285 mutable std::size_t m_seek_saved_full;
289 mutable std::size_t m_seek_saved_partial;
293 mutable std::size_t m_try_again;
297 mutable std::size_t m_saturated;
301 mutable std::size_t m_evicted;
305 mutable std::chrono::nanoseconds m_wait_min;
309 mutable std::chrono::nanoseconds m_wait_max;
313 mutable std::chrono::nanoseconds m_wait_total;
317 mutable std::size_t m_wait_samples;
318 };
319
329 public:
333 WriteTelemetry() noexcept;
334
339
344
348 virtual ~WriteTelemetry() noexcept override;
349
354 WriteTelemetry& operator=(const WriteTelemetry&) = delete;
355
360 WriteTelemetry& operator=(WriteTelemetry&&) = delete;
361
366 StormByte::ByteSize Behind() const noexcept;
367
372 StormByte::ByteSize Direct() const noexcept;
373
378 StormByte::ByteSize Origin() const noexcept;
379
384 StormByte::ByteSize Materialized() const noexcept;
385
390 StormByte::ByteSize HighWater() const noexcept;
391
396 StormByte::ByteSize HitAhead() const noexcept;
397
402 StormByte::ByteSize HitBack() const noexcept;
403
408 StormByte::ByteSize Miss() const noexcept;
409
414 StormByte::ByteSize Dirty() const noexcept;
415
420 StormByte::ByteSize DirtyPeak() const noexcept;
421
426 StormByte::ByteSize Cap() const noexcept;
427
432 std::size_t SeekLogical() const noexcept;
433
438 std::size_t SeekOrigin() const noexcept;
439
444 std::size_t SeekSavedFull() const noexcept;
445
450 std::size_t SeekSavedPartial() const noexcept;
451
456 std::size_t TryAgain() const noexcept;
457
462 std::size_t Saturated() const noexcept;
463
468 std::size_t Evicted() const noexcept;
469
474 std::chrono::nanoseconds WaitMin() const noexcept;
475
480 std::chrono::nanoseconds WaitMax() const noexcept;
481
486 std::chrono::nanoseconds WaitTotal() const noexcept;
487
492 std::size_t WaitSamples() const noexcept;
493
498 operator StormByte::Safe::String() const override;
499
500 protected:
502
550 mutable std::size_t m_seek_logical;
554 mutable std::size_t m_seek_origin;
558 mutable std::size_t m_seek_saved_full;
562 mutable std::size_t m_seek_saved_partial;
566 mutable std::size_t m_try_again;
570 mutable std::size_t m_saturated;
574 mutable std::size_t m_evicted;
578 mutable std::chrono::nanoseconds m_wait_min;
582 mutable std::chrono::nanoseconds m_wait_max;
586 mutable std::chrono::nanoseconds m_wait_total;
590 mutable std::size_t m_wait_samples;
591 };
592 }
593 }
594}
595
596STORMBYTE_DECLARE_MAYBE_SAFE(StormByte::Buffer::IO::ReadTelemetry);
597STORMBYTE_DECLARE_MAYBE_SAFE(StormByte::Buffer::IO::WriteTelemetry);
StormByte::ByteSize m_cached_peak
Maximum Cached.
Definition telemetry.hxx:269
std::size_t SeekOrigin() const noexcept
OriginSeek calls that reached the device.
std::size_t SeekSavedFull() const noexcept
Closed Seek epochs that never called OriginSeek after a cache hit.
std::chrono::nanoseconds WaitMax() const noexcept
Longest sampled Read/Peek wait.
std::size_t SeekSavedPartial() const noexcept
Closed Seek epochs that called OriginSeek after a cache hit.
StormByte::ByteSize m_origin
OriginPull octets this session.
Definition telemetry.hxx:261
std::size_t m_wait_samples
Sampled waits.
Definition telemetry.hxx:317
std::chrono::nanoseconds WaitMin() const noexcept
Shortest sampled Read/Peek wait.
StormByte::ByteSize m_cached
Resident cache now.
Definition telemetry.hxx:265
std::size_t TryAgain() const noexcept
Times Read / Peek returned TryAgain.
std::chrono::nanoseconds m_wait_max
Longest sampled wait.
Definition telemetry.hxx:309
StormByte::ByteSize m_hit_ahead
First-touch cache octets.
Definition telemetry.hxx:249
std::size_t m_seek_saved_full
Epochs with no OriginSeek after a hit.
Definition telemetry.hxx:285
StormByte::ByteSize m_cap
MaxMemory snapshot.
Definition telemetry.hxx:273
std::size_t m_saturated
Cache hit Cap.
Definition telemetry.hxx:297
std::size_t m_seek_saved_partial
Epochs that later needed OriginSeek.
Definition telemetry.hxx:289
std::size_t m_try_again
Read/Peek TryAgain.
Definition telemetry.hxx:293
ReadTelemetry() noexcept
Construct all counters at 0.
StormByte::ByteSize Miss() const noexcept
Of Delivered, octets pulled from the origin in that Read.
std::chrono::nanoseconds m_wait_total
Sum of sampled waits.
Definition telemetry.hxx:313
StormByte::ByteSize CachedPeak() const noexcept
Maximum Cached since construction.
StormByte::ByteSize HitAhead() const noexcept
Of Delivered, cache octets never consumed before.
StormByte::ByteSize m_miss
Pulled from the origin this Read.
Definition telemetry.hxx:257
std::size_t WaitSamples() const noexcept
Sampled waits (work or timed-out TryAgain).
std::size_t Evicted() const noexcept
Cache spans dropped by MaxMemory eviction.
std::size_t m_seek_origin
OriginSeek calls.
Definition telemetry.hxx:281
StormByte::ByteSize Origin() const noexcept
Octets transferred by OriginPull this session.
operator StormByte::Safe::String() const override
Flatten base and IO read counters.
std::size_t m_evicted
Spans dropped by MaxMemory.
Definition telemetry.hxx:301
StormByte::ByteSize Cap() const noexcept
MaxMemory at this snapshot.
std::chrono::nanoseconds WaitTotal() const noexcept
Sum of sampled waits.
StormByte::ByteSize HitBack() const noexcept
Of Delivered, cache octets already passed by Tell.
std::size_t Saturated() const noexcept
Times resident cache reached Cap while Cap > 0.
StormByte::ByteSize m_hit_back
Replay after Seek.
Definition telemetry.hxx:253
friend class StormByte::Buffer::Backend::IO::BufferedReader
Definition telemetry.hxx:244
std::size_t SeekLogical() const noexcept
Successful public Seek calls.
std::chrono::nanoseconds m_wait_min
Shortest sampled wait.
Definition telemetry.hxx:305
std::size_t m_seek_logical
Public Seek calls.
Definition telemetry.hxx:277
StormByte::ByteSize Cached() const noexcept
Resident cache octets now.
std::chrono::nanoseconds m_wait_max
Longest sampled Write wait.
Definition telemetry.hxx:582
StormByte::ByteSize m_behind
Accepted not pushed on the caller thread.
Definition telemetry.hxx:506
StormByte::ByteSize HitBack() const noexcept
Writes that landed in a resident page behind the high-water.
StormByte::ByteSize m_high_water
Max logical Tell since Open/Truncate.
Definition telemetry.hxx:522
StormByte::ByteSize m_dirty
Not yet on the origin.
Definition telemetry.hxx:538
std::size_t m_wait_samples
Sampled waits.
Definition telemetry.hxx:590
std::chrono::nanoseconds WaitMin() const noexcept
Shortest sampled Write wait.
std::size_t TryAgain() const noexcept
Times Write returned TryAgain.
std::size_t SeekOrigin() const noexcept
OriginSeek calls.
StormByte::ByteSize Miss() const noexcept
Writes that created or extended a page.
StormByte::ByteSize DirtyPeak() const noexcept
Maximum Dirty since construction.
std::chrono::nanoseconds m_wait_min
Shortest sampled Write wait.
Definition telemetry.hxx:578
std::size_t m_seek_origin
OriginSeek calls.
Definition telemetry.hxx:554
friend class StormByte::Buffer::Backend::IO::BufferedWriter
Definition telemetry.hxx:501
WriteTelemetry() noexcept
Construct all counters at 0.
std::size_t Saturated() const noexcept
Times Dirty reached Cap while Cap > 0.
std::size_t m_saturated
Dirty reached Cap.
Definition telemetry.hxx:570
StormByte::ByteSize m_cap
Ring cap, or 0 if off.
Definition telemetry.hxx:546
std::chrono::nanoseconds WaitTotal() const noexcept
Sum of sampled waits.
std::size_t m_seek_saved_partial
Epochs that later needed OriginSeek.
Definition telemetry.hxx:562
StormByte::ByteSize Behind() const noexcept
Of Accepted, octets that did not hit the origin on the caller thread.
StormByte::ByteSize m_origin
OriginPush octets.
Definition telemetry.hxx:514
StormByte::ByteSize Materialized() const noexcept
Durable origin length now.
std::size_t SeekLogical() const noexcept
Logical Seek calls (Tell only).
std::size_t m_try_again
Write TryAgain.
Definition telemetry.hxx:566
std::chrono::nanoseconds m_wait_total
Sum of sampled waits.
Definition telemetry.hxx:586
StormByte::ByteSize Dirty() const noexcept
Octets not yet on the origin.
std::chrono::nanoseconds WaitMax() const noexcept
Longest sampled Write wait.
std::size_t m_seek_saved_full
Epochs with no OriginSeek.
Definition telemetry.hxx:558
StormByte::ByteSize m_hit_back
Writes into a page behind high-water.
Definition telemetry.hxx:530
StormByte::ByteSize HitAhead() const noexcept
Writes that landed in a resident page at or after the previous high-water.
StormByte::ByteSize Direct() const noexcept
Of Accepted, octets pushed on the caller thread.
std::size_t SeekSavedPartial() const noexcept
Closed epochs that hit dirty pages and later needed OriginSeek.
StormByte::ByteSize Origin() const noexcept
Octets pushed through OriginPush since construction.
StormByte::ByteSize Cap() const noexcept
Ring cap in bytes at this snapshot.
StormByte::ByteSize m_materialized
Durable origin length now.
Definition telemetry.hxx:518
std::size_t Evicted() const noexcept
Times GC materialised a page because Dirty exceeded MaxMemory.
std::size_t m_evicted
GC materialised a page.
Definition telemetry.hxx:574
StormByte::ByteSize m_hit_ahead
Writes into a page at/after high-water.
Definition telemetry.hxx:526
StormByte::ByteSize m_miss
Writes that created or extended a page.
Definition telemetry.hxx:534
StormByte::ByteSize HighWater() const noexcept
Maximum logical Tell since Open / Truncate.
std::size_t SeekSavedFull() const noexcept
Closed epochs with no OriginSeek.
std::size_t WaitSamples() const noexcept
Sampled waits (accepted Write or timed OriginPush).
StormByte::ByteSize m_direct
Accepted pushed on the caller thread.
Definition telemetry.hxx:510
StormByte::ByteSize m_dirty_peak
Maximum Dirty.
Definition telemetry.hxx:542
std::size_t m_seek_logical
Logical Seek calls.
Definition telemetry.hxx:550
operator StormByte::Safe::String() const override
Flatten base and IO write counters.
Basic read counters.
Definition telemetry.hxx:242
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.
Root namespace of the StormByte C++ suite.
STL namespace.
#define STORMBYTE_BUFFER_PUBLIC
Definition visibility.h:54