StormByte-Logger 3.0.0
C++26 logger module of the StormByte suite
Loading...
Searching...
No Matches
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
43#include <StormByte/byte_size.hxx>
46#include <StormByte/safe/binary.hxx>
47#include <StormByte/safe/callback.hxx>
48#include <StormByte/safe/clonable.hxx>
49#include <StormByte/safe/map.hxx>
50#include <StormByte/safe/optional.hxx>
51#include <StormByte/safe/string.hxx>
52#include <StormByte/safe/vector.hxx>
53#include <StormByte/safe/wstring.hxx>
54#include <StormByte/size.hxx>
55#include <StormByte/type_traits.hxx>
56#include <StormByte/type_traits/safe.hxx>
57
58#include <cstddef>
59#include <memory>
60#include <ostream>
61#include <span>
62#include <string>
63#include <string_view>
64
69namespace StormByte::Logger {
70 class Engine;
71
80 inline void OStreamWrite(void* context, const char* data, std::size_t size) {
81 if (context == nullptr || data == nullptr || size == 0)
82 return;
83 static_cast<std::ostream*>(context)->write(data, static_cast<std::streamsize>(size));
84 }
85
91 inline void OStreamManip(void* context, std::ostream& (*manip)(std::ostream&)) {
92 if (context == nullptr || manip == nullptr)
93 return;
94 *static_cast<std::ostream*>(context) << manip;
95 }
96
118 friend STORMBYTE_LOGGER_PUBLIC Log& noredact(Log& log) noexcept;
119
120 public:
125
135 Log(std::ostream& out, const Level& level = Level::Info, std::string_view format = "[%L] %T")
136 : Log(&OStreamWrite, &OStreamManip, &out, level, format) {}
137
144 Log(StormByte::Safe::Callback&& callback, const Level& level = Level::Info, std::string_view format = "[%L] %T");
145
152 Log(SinkFunction&& callback, const Level& level = Level::Info, std::string_view format = "[%L] %T");
153
158 Log(const Log&) = default;
159
163 Log(Log&&) noexcept = default;
164
168 ~Log() noexcept override;
169
175 Log& operator=(const Log&);
176
181 Log& operator=(Log&&) noexcept;
182
190 PointerType Scope(std::string_view path);
191
198 bool Enabled(const Level& level) const noexcept;
199
206 virtual Log& Color(const Level& level, const StormByte::Logger::Color& color);
207
213 virtual StormByte::Logger::Color Color(const Level& level) const;
214
222 virtual Log& Color(std::string_view component, const Level& level, const StormByte::Logger::Color& color);
223
230 virtual StormByte::Logger::Color Color(std::string_view component, const Level& level) const;
231
237 virtual Log& Format(std::string_view format);
238
243 virtual StormByte::Safe::String Format() const;
244
251 virtual Log& Format(std::string_view component, std::string_view format);
252
258 virtual StormByte::Safe::String Format(std::string_view component) const;
259
265 virtual Log& Throttle(const ThrottleSpec& spec);
266
272 virtual Log& NoThrottle(const ThrottleSpec& spec);
273
280 virtual Log& Throttle(double rate, std::size_t burst);
281
291 virtual Log& Throttle(double rate, std::size_t burst, ThrottlePolicy policy, std::size_t value, std::size_t period = 0);
292
300 virtual Log& Throttle(const Level& level, double rate, std::size_t burst);
301
309 virtual Log& Throttle(GroupManip group, double rate, std::size_t burst);
310
318 virtual Log& Throttle(ComponentManip component, double rate, std::size_t burst);
319
332 virtual 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);
333
338 virtual Log& NoThrottle();
339
345 virtual Log& NoThrottle(const Level& level);
346
353
360
369
374 virtual Log& FlushThrottle();
375
381 virtual Log& FlushThrottle(const ThrottleSpec& spec);
382
387
394 template <typename T>
395 inline Log& operator<<(const T& v)
396 requires (
397 (StormByte::Type::Arithmetic<std::decay_t<T>> && !StormByte::Type::SameAs<std::decay_t<T>, wchar_t>)
398 || StormByte::Type::SameAs<std::decay_t<T>, std::string_view>
399 || StormByte::Type::SameAs<std::decay_t<T>, const char*>
400 || StormByte::Type::SameAs<std::decay_t<T>, char*>
401 ) {
402 if (!WillWrite()) [[likely]]
403 return *this;
405 WriteValue(static_cast<const char*>(v));
406 else if constexpr (StormByte::Type::SameAs<std::decay_t<T>, std::string_view>)
407 WriteValue(v);
408 else
409 WriteValue(static_cast<std::decay_t<T>>(v));
410 return *this;
411 }
412
418 inline Log& operator<<(const std::string& v) {
419 if (!WillWrite()) [[likely]]
420 return *this;
421 WriteValue(std::string_view{v});
422 return *this;
423 }
424
431 if (!WillWrite()) [[likely]]
432 return *this;
433 WriteValue(static_cast<std::string_view>(v));
434 return *this;
435 }
436
442 inline Log& operator<<(std::wstring_view v) {
443 if (!WillWrite()) [[likely]]
444 return *this;
445 Write(v);
446 return *this;
447 }
448
454 inline Log& operator<<(const wchar_t* v) {
455 if (!WillWrite()) [[likely]]
456 return *this;
457 Write(v);
458 return *this;
459 }
460
467 if (!WillWrite()) [[likely]]
468 return *this;
469 Write(static_cast<std::wstring_view>(v));
470 return *this;
471 }
472
478 inline Log& operator<<(std::span<const std::byte> v) {
479 if (!WillWrite()) [[likely]]
480 return *this;
481 Write(v);
482 return *this;
483 }
484
491 if (!WillWrite()) [[likely]]
492 return *this;
493 Write(static_cast<std::span<const std::byte>>(v));
494 return *this;
495 }
496
502 inline Log& operator<<(const StormByte::Size& v) {
503 if (!WillWrite()) [[likely]]
504 return *this;
505 const std::string text = static_cast<std::string>(v);
506 WriteValue(std::string_view{text});
507 return *this;
508 }
509
516 if (!WillWrite()) [[likely]]
517 return *this;
518 const std::string text = static_cast<std::string>(v);
519 WriteValue(std::string_view{text});
520 return *this;
521 }
522
529 template <typename T>
532 if (value.has_value())
533 return *this << *value;
534 return *this << "(empty Safe::Optional)";
535 }
536
543 template <typename T>
546 *this << "[";
547 bool first_value = true;
548 for (const auto& value : values) {
549 if (!first_value)
550 *this << ", ";
551 *this << value;
552 first_value = false;
553 }
554 return *this << "]";
555 }
556
564 template <typename Key, typename Value>
567 *this << "{";
568 if (!values.empty()) {
569 *this << "\n";
570 bool first_entry = true;
571 for (const auto& entry : values) {
572 if (!first_entry)
573 *this << "\n";
574 *this << "\t" << entry.first << ": " << entry.second;
575 first_entry = false;
576 }
577 *this << "\n";
578 }
579 return *this << "}";
580 }
581
587 inline Log& operator<<(const Level& level) {
588 Write(level);
589 return *this;
590 }
591
597 inline Log& operator<<(std::ostream& (*manip)(std::ostream&)) {
598 Write(manip);
599 return *this;
600 }
601
607 inline Log& operator<<(Log& (*manip)(Log&) noexcept) {
608 Write(manip);
609 return *this;
610 }
611
618 Write(m);
619 return *this;
620 }
621
628 Write(m);
629 return *this;
630 }
631
638 Write(m);
639 return *this;
640 }
641
647 inline Log& operator<<(ColorManip manip) {
648 Write(manip);
649 return *this;
650 }
651
657 inline Log& operator<<(NoColorManip manip) {
658 Write(manip);
659 return *this;
660 }
661
667 inline Log& operator<<(FormatManip manip) {
668 Write(manip);
669 return *this;
670 }
671
678 Write(manip);
679 return *this;
680 }
681
687 inline Log& operator<<(GroupManip manip) {
688 Write(manip);
689 return *this;
690 }
691
698 Write(manip);
699 return *this;
700 }
701
708 Write(manip);
709 return *this;
710 }
711
718 Write(manip);
719 return *this;
720 }
721
723
724 protected:
733 Log(SinkWrite write, SinkManip manip, void* context, const Level& level, std::string_view format);
734
737
742 bool WillWrite() const noexcept;
743
749
754 bool HasOpenOutputLine() const noexcept;
755
760 bool LineDecided() const noexcept;
761
766 bool LineAdmitted() const noexcept;
767
772 virtual bool BeginPayload();
773
779 template <typename T>
780 void WriteValue(const T& v);
781
786 PointerType Clone() const override;
787
792 PointerType Move() override;
793
798 virtual void Write(std::wstring_view v);
799
804 virtual void Write(const wchar_t* v);
805
810 virtual void Write(std::span<const std::byte> v);
811
816 virtual void Write(const Level& level);
817
822 virtual void Write(std::ostream& (*manip)(std::ostream&));
823
828 virtual void Write(Log& (*manip)(Log&) noexcept);
829
834 virtual void Write(RedactManip m);
835
840 virtual void Write(HexManip m);
841
846 virtual void Write(NoHexManip m);
847
852 virtual void Write(ColorManip manip);
853
858 virtual void Write(NoColorManip manip);
859
864 virtual void Write(FormatManip manip);
865
870 virtual void Write(PopFormatManip manip);
871
876 virtual void Write(GroupManip manip);
877
882 virtual void Write(ComponentManip manip);
883
888 virtual void Write(PopComponentManip manip);
889
894 virtual void Write(ResetComponentManip manip);
895 };
896
898 extern template STORMBYTE_LOGGER_PUBLIC void Log::WriteValue<bool>(const bool& v);
899 extern template STORMBYTE_LOGGER_PUBLIC void Log::WriteValue<char>(const char& v);
900 extern template STORMBYTE_LOGGER_PUBLIC void Log::WriteValue<signed char>(const signed char& v);
901 extern template STORMBYTE_LOGGER_PUBLIC void Log::WriteValue<unsigned char>(const unsigned char& v);
902 extern template STORMBYTE_LOGGER_PUBLIC void Log::WriteValue<short>(const short& v);
903 extern template STORMBYTE_LOGGER_PUBLIC void Log::WriteValue<unsigned short>(const unsigned short& v);
904 extern template STORMBYTE_LOGGER_PUBLIC void Log::WriteValue<int>(const int& v);
905 extern template STORMBYTE_LOGGER_PUBLIC void Log::WriteValue<unsigned int>(const unsigned int& v);
906 extern template STORMBYTE_LOGGER_PUBLIC void Log::WriteValue<long>(const long& v);
907 extern template STORMBYTE_LOGGER_PUBLIC void Log::WriteValue<unsigned long>(const unsigned long& v);
908 extern template STORMBYTE_LOGGER_PUBLIC void Log::WriteValue<long long>(const long long& v);
909 extern template STORMBYTE_LOGGER_PUBLIC void Log::WriteValue<unsigned long long>(const unsigned long long& v);
910 extern template STORMBYTE_LOGGER_PUBLIC void Log::WriteValue<float>(const float& v);
911 extern template STORMBYTE_LOGGER_PUBLIC void Log::WriteValue<double>(const double& v);
912 extern template STORMBYTE_LOGGER_PUBLIC void Log::WriteValue<long double>(const long double& v);
913 extern template STORMBYTE_LOGGER_PUBLIC void Log::WriteValue<std::string_view>(const std::string_view& v);
914 extern template STORMBYTE_LOGGER_PUBLIC void Log::WriteValue<const char*>(const char* const& v);
916
926 template<typename Ptr>
927 concept LogPointer =
928 StormByte::Type::NullablePointer<Ptr>
929 && StormByte::Type::DerivedFrom<typename std::remove_cvref_t<Ptr>::element_type, Log>;
930
939 template <typename Ptr, typename T>
940 Ptr& operator<<(Ptr& logger, const T& value) noexcept
941 requires LogPointer<Ptr> {
942 if (logger)
943 *logger << value;
944 return logger;
945 }
946
954 template <typename Ptr>
955 Ptr& operator<<(Ptr& logger, const Level& level) noexcept
956 requires LogPointer<Ptr> {
957 if (logger)
958 *logger << level;
959 return logger;
960 }
961
972 template <typename Ptr>
973 Ptr& operator<<(Ptr& logger, std::ostream& (*manip)(std::ostream&)) noexcept
974 requires LogPointer<Ptr> {
975 if (logger)
976 *logger << manip;
977 return logger;
978 }
979}
980
Public streaming facade for the StormByte logger.
Definition log.hxx:114
Log & operator<<(std::span< const std::byte > v)
Stream raw bytes.
Definition log.hxx:478
bool LineAdmitted() const noexcept
Whether the decided current line is admitted.
virtual void Write(std::wstring_view v)
Forward wide text.
Log & operator<<(const StormByte::Safe::Binary &v)
Stream owned bytes.
Definition log.hxx:490
Log & operator<<(PopComponentManip manip)
Pop one component segment from the current thread's stack.
Definition log.hxx:707
Log & operator<<(const std::string &v)
Stream caller-owned narrow text without passing its std::string object across the DLL boundary.
Definition log.hxx:418
Log(SinkWrite write, SinkManip manip, void *context, const Level &level, std::string_view format)
Construct a logger that emits through caller callbacks.
Log & operator<<(const StormByte::Size &v)
Stream a byte count.
Definition log.hxx:502
Log(SinkFunction &&callback, const Level &level=Level::Info, std::string_view format="[%L] %T")
Construct a Log that emits through a typed creator-owned callback.
Log & operator<<(RedactManip m)
Apply redaction policy.
Definition log.hxx:617
bool LineDecided() const noexcept
Whether throttle has already decided the current line.
Log & operator<<(FormatManip manip)
Save the current format and activate a temporary format.
Definition log.hxx:667
Log & operator<<(NoHexManip m)
Disable hex dumps.
Definition log.hxx:637
bool HasOpenOutputLine() const noexcept
Whether output has already started for the current line.
StormByte::Safe::Shared< Engine > m_engine
Shared backend on Base's heap.
Definition log.hxx:735
Log & operator<<(ComponentManip manip)
Push a component segment onto the current thread's stack.
Definition log.hxx:697
PointerType Move() override
Move this facade into a StormByte::Safe::Shared.
Log & operator<<(std::wstring_view v)
Stream wide text.
Definition log.hxx:442
friend Log & humanreadable_bytes(Log &log) noexcept
Enable human-readable formatting for byte counts.
Log & operator<<(ResetComponentManip manip)
Clear the current thread's component stack.
Definition log.hxx:717
PointerType Clone() const override
Deep-copy this facade into a StormByte::Safe::Shared.
friend Log & humanreadable_number(Log &log) noexcept
Enable human-readable formatting for numeric values.
Log & operator<<(const StormByte::Safe::WString &v)
Stream owned wide text.
Definition log.hxx:466
friend Log & noredact(Log &log) noexcept
Disable redaction until the next redact / redact(n) / redact_first(n).
Log(StormByte::Safe::Callback &&callback, const Level &level=Level::Info, std::string_view format="[%L] %T")
Construct a Log that emits text through a Base-owned callback.
bool Enabled(const Level &level) const noexcept
Whether level would be emitted given the print floor.
Log(Log &&) noexcept=default
Move constructor.
Log & operator<<(ColorManip manip)
Apply a configured or explicit content color.
Definition log.hxx:647
Log & operator<<(PopFormatManip manip)
Restore the most recently saved format.
Definition log.hxx:677
Log & operator<<(const StormByte::Safe::String &v)
Stream owned UTF-8 text.
Definition log.hxx:430
Log & operator<<(GroupManip manip)
Set the producer group for the current line.
Definition log.hxx:687
Log & operator<<(std::ostream &(*manip)(std::ostream &))
Apply a stream manipulator (e.g.
Definition log.hxx:597
Log & operator<<(const wchar_t *v)
Stream a wide C string.
Definition log.hxx:454
virtual bool BeginPayload()
Admit a numeric or narrow-text payload.
StormByte::Safe::String m_scope_path
Sticky component path; empty = root facade.
Definition log.hxx:736
Log & operator<<(Log &(*manip)(Log &) noexcept)
Apply a Log manipulator.
Definition log.hxx:607
void WriteValue(const T &v)
Forward a payload after BeginPayload.
virtual Log & FlushThrottle()
Flush dropped summaries for all throttle rules.
bool WillWrite() const noexcept
Whether the current line level will be written.
friend Log & nohumanreadable(Log &log) noexcept
Disable human-readable formatting (raw numbers).
virtual Log & Color(const Level &level, const StormByte::Logger::Color &color)
Set the configured color for a logging level.
Log & operator<<(const StormByte::ByteSize &v)
Stream an octet count.
Definition log.hxx:515
Log & operator<<(HexManip m)
Dump subsequent payloads as hex bytes until nohex.
Definition log.hxx:627
PointerType Scope(std::string_view path)
Another facade on the same backend, with a sticky component path.
virtual Log & NoThrottle(const ThrottleSpec &spec)
Remove a throttle rule with the same selectors.
StormByte::Safe::Clonable< Log >::PointerType PointerType
Owner returned by Clone, Move and Scope.
Definition log.hxx:124
bool PrepareLine()
Decide throttle admission before a payload claims a line lock.
Log & operator<<(NoColorManip manip)
Disable color for subsequent content.
Definition log.hxx:657
virtual Log & Throttle(const ThrottleSpec &spec)
Install a throttle rule.
Log & operator<<(const StormByte::Safe::Vector< T > &values)
Stream Safe vector values in bracketed, comma-separated form.
Definition log.hxx:545
Log(const Log &)=default
Copy constructor.
Log & operator<<(const StormByte::Safe::Map< Key, Value > &values)
Stream Safe map entries on separate, indented lines.
Definition log.hxx:566
Log & operator<<(const StormByte::Safe::Optional< T > &value)
Stream a Safe optional value, or a marker when it is empty.
Definition log.hxx:531
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
Log & operator<<(const Level &level)
Set the level of the current line.
Definition log.hxx:587
virtual Log & Format(std::string_view format)
Set the header format.
bool empty() const noexcept
bool has_value() const noexcept
Pointer-like owner of Log or a derived logger.
Definition log.hxx:927
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
Ptr & operator<<(Ptr &logger, const T &value) noexcept
Stream a value into a smart pointer to Log or a derived logger.
Definition log.hxx:940
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
Pops one segment from the current thread's component stack.
Definition manipulators.hxx:188
Restores the most recently saved logger format.
Definition manipulators.hxx:208
Stateful redaction manipulator.
Definition manipulators.hxx:295
Clears the component associated with the current thread.
Definition manipulators.hxx:174
Immutable rule description used by Log::Throttle.
Definition manipulators.hxx:76
#define STORMBYTE_LOGGER_PUBLIC
Definition visibility.h:53