StormByte-Logger 3.0.0
C++26 logger module of the StormByte suite
Loading...
Searching...
No Matches
threaded_log.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-Logger.
5 *
6 * StormByte-Logger 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-Logger 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-String tree and
23 * the StormByte Base tree it vendors), which remains under its own license.
24 *
25 * Neither license grants any patent rights. Any patent licenses required
26 * to use this software or third-party components must be obtained separately
27 * from the patent holders.
28 *
29 * StormByte-Logger is distributed in the hope that it will be useful,
30 * but WITHOUT ANY WARRANTY; without even the implied warranty of
31 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
32 * GNU Lesser General Public License for more details.
33 *
34 * You should have received a copy of the GNU Lesser General Public License
35 * version 3 along with StormByte-Logger. If not, see
36 * <https://www.gnu.org/licenses/lgpl-3.0.html>.
37 *
38 * SPDX-License-Identifier: LGPL-3.0-or-later OR LicenseRef-StormByte-Commercial
39 */
40
41#pragma once
42
44#include <StormByte/thread_lock.hxx>
45
46#include <memory>
47#include <ostream>
48#include <span>
49#include <string_view>
50#include <StormByte/type_traits/safe.hxx>
51
56namespace StormByte::Logger {
72 public:
79 ThreadedLog(std::ostream& out, const Level& level = Level::Info, std::string_view format = "[%L] %T")
80 : ThreadedLog(&OStreamWrite, &OStreamManip, &out, level, format) {}
81
88 ThreadedLog(StormByte::Safe::Callback&& callback, const Level& level = Level::Info, std::string_view format = "[%L] %T");
89
96 ThreadedLog(SinkFunction&& callback, const Level& level = Level::Info, std::string_view format = "[%L] %T");
97
102 ThreadedLog(const ThreadedLog&) = default;
103
107 ThreadedLog(ThreadedLog&&) noexcept = default;
108
112 ~ThreadedLog() noexcept override;
113
119 ThreadedLog& operator=(const ThreadedLog&);
120
125 ThreadedLog& operator=(ThreadedLog&&) noexcept;
126
133 Log& Color(const Level& level, const StormByte::Logger::Color& color) override;
134
140 StormByte::Logger::Color Color(const Level& level) const override;
141
149 Log& Color(std::string_view component, const Level& level, const StormByte::Logger::Color& color) override;
150
157 StormByte::Logger::Color Color(std::string_view component, const Level& level) const override;
158
164 Log& Format(std::string_view format) override;
165
170 StormByte::Safe::String Format() const override;
171
178 Log& Format(std::string_view component, std::string_view format) override;
179
185 StormByte::Safe::String Format(std::string_view component) const override;
186
192 Log& Throttle(const ThrottleSpec& spec) override;
193
199 Log& NoThrottle(const ThrottleSpec& spec) override;
200
207 Log& Throttle(double rate, std::size_t burst) override;
208
218 Log& Throttle(double rate, std::size_t burst, ThrottlePolicy policy, std::size_t value, std::size_t period = 0) override;
219
227 Log& Throttle(const Level& level, double rate, std::size_t burst) override;
228
236 Log& Throttle(GroupManip group, double rate, std::size_t burst) override;
237
245 Log& Throttle(ComponentManip component, double rate, std::size_t burst) override;
246
259 Log& Throttle(ComponentManip component, const Level& level, GroupManip group, double rate, std::size_t burst, ThrottlePolicy policy = ThrottlePolicy::Drop, std::size_t value = 0, std::size_t period = 0) override;
260
265 Log& NoThrottle() override;
266
272 Log& NoThrottle(const Level& level) override;
273
280
287
296
301 Log& FlushThrottle() override;
302
308 Log& FlushThrottle(const ThrottleSpec& spec) override;
309
310 protected:
315 PointerType Clone() const override;
316
321 PointerType Move() override;
322
327 bool BeginPayload() override;
328
333 void Write(std::wstring_view v) override;
334
339 void Write(const wchar_t* v) override;
340
345 void Write(std::span<const std::byte> v) override;
346
351 void Write(const Level& level) override;
352
357 void Write(std::ostream& (*manip)(std::ostream&)) override;
358
363 void Write(Log& (*manip)(Log&) noexcept) override;
364
369 void Write(RedactManip m) override;
370
375 void Write(HexManip m) override;
376
381 void Write(NoHexManip m) override;
382
387 void Write(ColorManip manip) override;
388
393 void Write(NoColorManip manip) override;
394
399 void Write(FormatManip manip) override;
400
405 void Write(PopFormatManip manip) override;
406
407 protected:
416 ThreadedLog(SinkWrite write, SinkManip manip, void* context, const Level& level, std::string_view format);
417
418 private:
419 StormByte::Safe::Shared<ThreadLock> m_lock;
420 };
421}
422
StormByte::Safe::Clonable< Log >::PointerType PointerType
Owner returned by Clone, Move and Scope.
Definition log.hxx:124
Log(std::ostream &out, const Level &level=Level::Info, std::string_view format="[%L] %T")
Construct a Log writing to out.
Definition log.hxx:135
PointerType Move() override
Move this facade into a StormByte::Safe::Shared.
void Write(std::wstring_view v) override
Encode wide text before taking the line lock.
ThreadedLog(std::ostream &out, const Level &level=Level::Info, std::string_view format="[%L] %T")
Construct a ThreadedLog writing to out.
Definition threaded_log.hxx:79
ThreadedLog(SinkFunction &&callback, const Level &level=Level::Info, std::string_view format="[%L] %T")
Construct a ThreadedLog that emits through a typed creator-owned callback.
Log & Throttle(const ThrottleSpec &spec) override
Install a throttle rule under the line lock.
Log & Color(const Level &level, const StormByte::Logger::Color &color) override
Set a level color while holding the line lock.
Log & Format(std::string_view format) override
Set the header format under the line lock.
ThreadedLog(const ThreadedLog &)=default
Copy constructor.
PointerType Clone() const override
Deep-copy this facade into a StormByte::Safe::Shared.
ThreadedLog(ThreadedLog &&) noexcept=default
Move constructor.
Log & FlushThrottle() override
Flush all dropped summaries under the line lock.
ThreadedLog(StormByte::Safe::Callback &&callback, const Level &level=Level::Info, std::string_view format="[%L] %T")
Construct a ThreadedLog that emits through a Base-owned callback.
Log & NoThrottle(const ThrottleSpec &spec) override
Remove a throttle rule under the line lock.
bool BeginPayload() override
Admit a payload and take the line lock.
STORMBYTE_DECLARE_MAYBE_SAFE(StormByte::Logger::Exception)
Logger module of the StormByte suite.
void(*)(void *context, std::ostream &(*manip)(std::ostream &)) SinkManip
Caller-side application of an std::ostream manipulator.
Definition typedefs.hxx:130
void OStreamWrite(void *context, const char *data, std::size_t size)
Write raw bytes into an std::ostream owned by the caller.
Definition log.hxx:80
ThrottlePolicy
Count policy applied before the optional rate bucket.
Definition manipulators.hxx:63
StormByte::Safe::Function< void(const StormByte::Safe::String &)> SinkFunction
Typed text callback whose context is released in its creator module.
Definition typedefs.hxx:135
const ColorManip color
Restore the configured color for the current level.
Definition manipulators.hxx:264
Level
Severity levels used by the logger.
Definition typedefs.hxx:89
@ Info
Informational messages.
Definition typedefs.hxx:94
ComponentManip component(const char *name)
Select the component associated with subsequent log lines on this thread.
Definition manipulators.hxx:145
void(*)(void *context, const char *data, std::size_t size) SinkWrite
Caller-side write of raw bytes into the sink.
Definition typedefs.hxx:122
void OStreamManip(void *context, std::ostream &(*manip)(std::ostream &))
Apply an std::ostream manipulator in the caller's module.
Definition log.hxx:91
GroupManip group(const char *name)
Set the producer group for the current line.
Definition manipulators.hxx:102
STL namespace.
Temporarily selects a configured or explicit content color.
Definition manipulators.hxx:248
Selects the sticky component for the current thread.
Definition manipulators.hxx:133
Temporarily replaces the logger format and saves the previous one.
Definition manipulators.hxx:200
Labels the current logging line with a producer group.
Definition manipulators.hxx:92
Dump subsequent payloads as hex bytes until nohex.
Definition manipulators.hxx:346
Disables color for subsequent content until changed.
Definition manipulators.hxx:270
Disable hex dumps and restore default payload formatting.
Definition manipulators.hxx:368
Restores the most recently saved logger format.
Definition manipulators.hxx:208
Stateful redaction manipulator.
Definition manipulators.hxx:295
Immutable rule description used by Log::Throttle.
Definition manipulators.hxx:76
#define STORMBYTE_LOGGER_PUBLIC
Definition visibility.h:53