StormByte 3.0.0
C++26 foundation 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 is the base for StormByte Suite libraries.
5 *
6 * StormByte 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 source in this repository.
20 * They do not cover other StormByte modules or any third-party material
21 * shipped with this repository (including everything under thirdparty/),
22 * which remains under its own license.
23 *
24 * Neither license grants any patent rights. Any patent licenses required
25 * to use this software or third-party components must be obtained separately
26 * from the patent holders.
27 *
28 * StormByte is distributed in the hope that it will be useful,
29 * but WITHOUT ANY WARRANTY; without even the implied warranty of
30 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
31 * GNU Lesser General Public License for more details.
32 *
33 * You should have received a copy of the GNU Lesser General Public License
34 * version 3 along with StormByte. If not, see
35 * <https://www.gnu.org/licenses/lgpl-3.0.html>.
36 *
37 * SPDX-License-Identifier: LGPL-3.0-or-later OR LicenseRef-StormByte-Commercial
38 */
39
40#pragma once
41
43#include <StormByte/platform.h>
46
47#include <chrono>
48#include <cstdint>
49#include <mutex>
50#include <string>
51#include <string_view>
52#include <type_traits>
53
58namespace StormByte {
68 class STORMBYTE_PUBLIC Clock final {
69 private:
74 struct State;
75
76 public:
81 struct Values {
82 std::uint64_t Count{};
83 std::chrono::microseconds Time{};
84 std::chrono::microseconds MeanDuration{};
85 };
86
98 public:
102 Sample() noexcept = default;
103
108 Sample(const Sample& other) = delete;
109
115 Sample& operator=(const Sample& other) = delete;
116
121 Sample(Sample&& other) noexcept;
122
128 Sample& operator=(Sample&& other) noexcept;
129
133 ~Sample() noexcept;
134
139 bool Active() const noexcept;
140
146 STORMBYTE_FORCE_INLINE std::chrono::microseconds Stop() noexcept {
147 return std::chrono::microseconds{StopCount()};
148 }
149
150 private:
151 friend class Clock;
152
157 explicit Sample(Safe::Shared<State> state) noexcept;
158
163 std::int64_t StopCount() noexcept;
164
165 Safe::Shared<State> m_state;
166 std::chrono::steady_clock::time_point m_start{};
167 std::chrono::microseconds m_elapsed{};
168 bool m_active{false};
169 };
170
174 Clock() noexcept;
175
179 Clock(const Clock&) = delete;
180
184 Clock(Clock&&) noexcept;
185
190 Clock& operator=(const Clock&) = delete;
191
196 Clock& operator=(Clock&&) noexcept;
197
201 ~Clock() noexcept;
202
208
214 const Counts raw = ReadCounts();
215 return Values{
216 raw.count,
217 std::chrono::microseconds{raw.time},
218 std::chrono::microseconds{raw.mean}
219 };
220 }
221
226 std::uint64_t Count() const noexcept;
227
232 STORMBYTE_FORCE_INLINE std::chrono::microseconds Time() const noexcept {
233 return GetValues().Time;
234 }
235
240 STORMBYTE_FORCE_INLINE std::chrono::microseconds MeanDuration() const noexcept {
241 return GetValues().MeanDuration;
242 }
243
244 private:
248 struct Counts {
249 std::uint64_t count{};
250 std::int64_t time{};
251 std::int64_t mean{};
252 };
253
258 Counts ReadCounts() const noexcept;
259
260 mutable std::mutex m_state_lock;
261 Safe::Shared<State> m_state;
262 };
263
274 public:
278 virtual ~Telemetry() noexcept;
279
284 virtual operator Safe::String() const = 0;
285
290 STORMBYTE_FORCE_INLINE operator std::string() const {
291 return static_cast<std::string>(static_cast<Safe::String>(*this));
292 }
293
294 protected:
298 Telemetry() noexcept;
299
303 Telemetry(const Telemetry&) = delete;
304
309 Telemetry(Telemetry&& other) noexcept;
310
315 Telemetry& operator=(const Telemetry&) = delete;
316
322 Telemetry& operator=(Telemetry&& other) noexcept;
323
331 class Clock& Clock(std::string_view name);
332
340 class Clock::Sample MeasureClock(std::string_view name) noexcept;
341
347 const class Clock& Clock(std::string_view name) const;
348
349 private:
350 struct Store;
351 Safe::Unique<Store> m_store;
352 };
353}
354
359namespace StormByte {
364 namespace Type {
368 template<> struct IsSafe<Clock::Values>: std::true_type {};
369
373 template<> struct IsMaybeSafe<Clock::Sample>: std::true_type {};
374 }
375}
One independently timed interval contributing to a shared Clock.
Definition telemetry.hxx:97
Sample() noexcept=default
Construct an empty, inactive sample token.
friend class Clock
Definition telemetry.hxx:151
STORMBYTE_FORCE_INLINE std::chrono::microseconds Stop() noexcept
Complete and record this sample once.
Definition telemetry.hxx:146
bool Active() const noexcept
Whether this token owns a measurement that will be recorded.
Thread-safe aggregate of independently timed operation samples.
Definition telemetry.hxx:68
Clock() noexcept
Construct zeroed shared clock state.
std::uint64_t Count() const noexcept
Number of completed samples.
STORMBYTE_FORCE_INLINE Values GetValues() const noexcept
Read Count, Time and MeanDuration under one lock.
Definition telemetry.hxx:213
STORMBYTE_FORCE_INLINE std::chrono::microseconds Time() const noexcept
Cumulative duration of completed samples.
Definition telemetry.hxx:232
STORMBYTE_FORCE_INLINE std::chrono::microseconds MeanDuration() const noexcept
Mean duration across completed samples.
Definition telemetry.hxx:240
Sample Measure()
Start an independent interval sample.
Forward declaration of shared ownership.
Definition pointers.hxx:133
Owned UTF-8 text.
Definition string.hxx:113
virtual operator Safe::String() const =0
Flatten counters into an owned StormByte Safe::String.
class Clock::Sample MeasureClock(std::string_view name) noexcept
Start an independent sample on a named aggregate clock.
Telemetry() noexcept
Construct an empty telemetry drawer.
class Clock & Clock(std::string_view name)
Access or create a named clock in the drawer.
virtual ~Telemetry() noexcept
Virtual destructor.
Owned values that cross a DLL without the caller's CRT.
Root namespace of the StormByte suite.
Octet count. Defined in byte_size.hxx. Forwarded so Type::Numeral can name it.
STL namespace.
#define STORMBYTE_FORCE_INLINE
Definition platform.h:134
Coherent snapshot of completed measurements.
Definition telemetry.hxx:81
std::chrono::microseconds Time
Sum of completed sample durations.
Definition telemetry.hxx:83
std::uint64_t Count
Number of completed samples.
Definition telemetry.hxx:82
std::chrono::microseconds MeanDuration
Mean duration, or zero when empty.
Definition telemetry.hxx:84
Recognizes types whose DLL-boundary safety depends on documented provider requirements.
Definition safe.hxx:262
Recognizes Base Safe components, not universal ABI compatibility.
Definition safe.hxx:138
#define STORMBYTE_PUBLIC
Definition visibility.h:52