StormByte::Logger::ThreadedLog Class Reference

Thread-safe logging facade. More...

#include <StormByte/logger/threaded_log.hxx>

Inheritance diagram for StormByte::Logger::ThreadedLog:

Collaboration diagram for StormByte::Logger::ThreadedLog:

Public Member Functions
	ThreadedLog (std::ostream &out, const Level &level=Level::Info, std::string_view format="[%L] %T")
	Construct a ThreadedLog writing to out.
	ThreadedLog (const ThreadedLog &)=default
	Copy constructor.
	ThreadedLog (ThreadedLog &&) noexcept=default
	Move constructor.
	~ThreadedLog () noexcept override
	Destructor.
ThreadedLog &	operator= (const ThreadedLog &)
	Copy assignment.
ThreadedLog &	operator= (ThreadedLog &&) noexcept
	Move assignment.
Log &	Color (const Level &level, const StormByte::Logger::Color &color) override
	Set a level color while holding the line lock.
StormByte::Logger::Color	Color (const Level &level) const override
	Get the configured color for a logging level.
Log &	Color (std::string_view component, const Level &level, const StormByte::Logger::Color &color) override
	Set a component color override under the line lock.
StormByte::Logger::Color	Color (std::string_view component, const Level &level) const override
	Get a component color, falling back along the path then to the general color.
Log &	Format (std::string_view format) override
	Set the header format under the line lock.
StormByte::String::String	Format () const override
	Get the effective current header format.
Log &	Format (std::string_view component, std::string_view format) override
	Set or remove a component-specific header format under the line lock.
StormByte::String::String	Format (std::string_view component) const override
	Get a component-specific format, falling back along the path then to general.
Log &	Throttle (const ThrottleSpec &spec) override
	Install a throttle rule under the line lock.
Log &	NoThrottle (const ThrottleSpec &spec) override
	Remove a throttle rule under the line lock.
Log &	Throttle (double rate, std::size_t burst) override
	Install a Drop rule.
Log &	Throttle (double rate, std::size_t burst, ThrottlePolicy policy, std::size_t value, std::size_t period=0) override
	Install a Sample or Window rule.
Log &	Throttle (const Level &level, double rate, std::size_t burst) override
	Install a level-scoped Drop rule.
Log &	Throttle (GroupManip group, double rate, std::size_t burst) override
	Install a group-scoped Drop rule.
Log &	Throttle (ComponentManip component, double rate, std::size_t burst) override
	Install a component-scoped Drop rule.
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
	Install an exact component/level/group rule.
Log &	NoThrottle () override
	Remove all throttle rules.
Log &	NoThrottle (const Level &level) override
	Remove a level-scoped rule.
Log &	NoThrottle (GroupManip group) override
	Remove a group-scoped rule.
Log &	NoThrottle (ComponentManip component) override
	Remove a component-scoped rule.
Log &	NoThrottle (ComponentManip component, const Level &level, GroupManip group) override
	Remove an exact component/level/group rule.
Log &	FlushThrottle () override
	Flush all dropped summaries under the line lock.
Log &	FlushThrottle (const ThrottleSpec &spec) override
	Flush matching dropped summaries under the line lock.
Public Member Functions inherited from StormByte::Logger::Log
	Log (std::ostream &out, const Level &level=Level::Info, std::string_view format="[%L] %T")
	Construct a Log writing to out.
	Log (const Log &)=default
	Copy constructor.
	Log (Log &&) noexcept=default
	Move constructor.
	~Log () noexcept override
	Destructor.
Log &	operator= (const Log &)
	Copy assignment.
Log &	operator= (Log &&) noexcept
	Move assignment.
PointerType	Scope (std::string_view path)
	Another facade on the same backend, with a sticky component path.
bool	Enabled (const Level &level) const noexcept
	Whether level would be emitted given the print floor.
template<typename T > requires ( (StormByte::Type::Arithmetic<std::decay_t<T>> && !StormByte::Type::SameAs<std::decay_t<T>, wchar_t>) || StormByte::Type::SameAs<std::decay_t<T>, std::string_view> || StormByte::Type::SameAs<std::decay_t<T>, const char*> || StormByte::Type::SameAs<std::decay_t<T>, char*> )
Log &	operator<< (const T &v)
	Stream a numeric or narrow-text payload.
Log &	operator<< (const StormByte::CString &v)
	Stream owned UTF-8 bytes.
Log &	operator<< (const StormByte::String::String &v)
	Stream owned UTF-8 text.
Log &	operator<< (std::wstring_view v)
	Stream wide text.
Log &	operator<< (const wchar_t *v)
	Stream a wide C string.
Log &	operator<< (const StormByte::WCString &v)
	Stream owned wide bytes.
Log &	operator<< (const StormByte::String::WString &v)
	Stream owned wide text.
Log &	operator<< (std::span< const std::byte > v)
	Stream raw bytes.
Log &	operator<< (const StormByte::BinaryData &v)
	Stream owned bytes.
Log &	operator<< (const StormByte::Size &v)
	Stream a byte count.
Log &	operator<< (const StormByte::ByteSize &v)
	Stream an octet count.
Log &	operator<< (const Level &level)
	Set the level of the current line.
Log &	operator<< (std::ostream &(*manip)(std::ostream &))
	Apply a stream manipulator (e.g.
Log &	operator<< (Log &(*manip)(Log &) noexcept)
	Apply a Log manipulator.
Log &	operator<< (RedactManip m)
	Apply redaction policy.
Log &	operator<< (HexManip m)
	Dump subsequent payloads as hex bytes until nohex.
Log &	operator<< (NoHexManip m)
	Disable hex dumps.
Log &	operator<< (ColorManip manip)
	Apply a configured or explicit content color.
Log &	operator<< (NoColorManip manip)
	Disable color for subsequent content.
Log &	operator<< (FormatManip manip)
	Save the current format and activate a temporary format.
Log &	operator<< (PopFormatManip manip)
	Restore the most recently saved format.
Log &	operator<< (GroupManip manip)
	Set the producer group for the current line.
Log &	operator<< (ComponentManip manip)
	Push a component segment onto the current thread's stack.
Log &	operator<< (PopComponentManip manip)
	Pop one component segment from the current thread's stack.
Log &	operator<< (ResetComponentManip manip)
	Clear the current thread's component stack.

Protected Member Functions
PointerType	Clone () const override
	Deep-copy this facade into a StormByte::Shared.
PointerType	Move () override
	Move this facade into a StormByte::Shared.
bool	BeginPayload () override
	Admit a payload and take the line lock.
void	Write (std::wstring_view v) override
	Encode wide text before taking the line lock.
void	Write (const wchar_t *v) override
	Encode a wide C string before taking the line lock.
void	Write (std::span< const std::byte > v) override
	Format raw bytes before taking the line lock.
void	Write (const Level &level) override
	Forward a level change under the line lock.
void	Write (std::ostream &(*manip)(std::ostream &)) override
	Forward a stream manipulator; newline drops the line lock.
void	Write (Log &(*manip)(Log &) noexcept) override
	Forward a Log manipulator under the line lock.
void	Write (RedactManip m) override
	Apply redaction state under the line lock.
void	Write (HexManip m) override
	Apply hex-dump state under the line lock.
void	Write (NoHexManip m) override
	Disable hex dumps under the line lock.
void	Write (ColorManip manip) override
	Apply a color manipulator under the line lock.
void	Write (NoColorManip manip) override
	Apply a no-color manipulator under the line lock.
void	Write (FormatManip manip) override
	Apply a push-format manipulator under the line lock.
void	Write (PopFormatManip manip) override
	Apply a pop-format manipulator under the line lock.
	ThreadedLog (SinkWrite write, SinkManip manip, void *context, const Level &level, std::string_view format)
	Construct a threaded logger that emits through caller callbacks.
Protected Member Functions inherited from StormByte::Logger::Log
	Log (SinkWrite write, SinkManip manip, void *context, const Level &level, std::string_view format)
	Construct a logger that emits through caller callbacks.
bool	WillWrite () const noexcept
	Whether the current line level will be written.
bool	PrepareLine ()
	Decide throttle admission before a payload claims a line lock.
bool	HasOpenOutputLine () const noexcept
	Whether output has already started for the current line.
bool	LineDecided () const noexcept
	Whether throttle has already decided the current line.
bool	LineAdmitted () const noexcept
	Whether the decided current line is admitted.
template<typename T >
void	WriteValue (const T &v)
	Forward a payload after BeginPayload.
virtual void	Write (GroupManip manip)
	Forward a group manipulator.
virtual void	Write (ComponentManip manip)
	Forward a component push manipulator.
virtual void	Write (PopComponentManip manip)
	Forward a component pop manipulator.
virtual void	Write (ResetComponentManip manip)
	Forward a reset-component manipulator.
Protected Member Functions inherited from StormByte::Clonable< Log >
constexpr	Clonable ()=default
constexpr	Clonable (const Clonable &)=default
constexpr	Clonable (Clonable &&) noexcept=default
constexpr Clonable &	operator= (const Clonable &)=default
constexpr Clonable &	operator= (Clonable &&) noexcept=default
virtual constexpr	~Clonable () noexcept=default

Additional Inherited Members
Public Types inherited from StormByte::Logger::Log
using	PointerType = StormByte::Clonable< Log >::PointerType
	Owner returned by Clone, Move and Scope.
Protected Types inherited from StormByte::Clonable< Log >
typedef SmartPointer	PointerType
Static Protected Member Functions inherited from StormByte::Clonable< Log >
static PointerType	MakePointer (Args &&... args)
Protected Attributes inherited from StormByte::Logger::Log
std::shared_ptr< Engine >	m_engine
	Shared backend.
StormByte::String::String	m_scope_path
	Sticky component path; empty = root facade.

Detailed Description

Thread-safe logging facade.

Serializes logical lines (until a newline manipulator) so concurrent writers do not interleave. Filtered messages do not hold the line lock.

Payload operator<< is inherited from Log. Numeric and narrow-text payloads call Log::WriteValue, which uses BeginPayload. This class only overrides BeginPayload plus the Writes that must run work before the lock or that drop the lock on newline.

Scope clones this type and shares both the Engine and the line lock.

Constructor & Destructor Documentation

ThreadedLog() [1/4]

StormByte::Logger::ThreadedLog::ThreadedLog ( std::ostream &  out, const Level &  level = Level::Info, std::string_view  format = "[%L] %T"  )

inline

Construct a ThreadedLog writing to out.

Parameters

out	Output stream. Must outlive this logger.
level	Minimum Level that will be emitted.
format	Header format string (L, T, i, c, g).

ThreadedLog() [2/4]

StormByte::Logger::ThreadedLog::ThreadedLog ( const ThreadedLog &  )

default

Copy constructor.

Note

Shares the Engine and the line lock. Copies the sticky path.

ThreadedLog() [3/4]

StormByte::Logger::ThreadedLog::ThreadedLog ( ThreadedLog &&  )

defaultnoexcept

Move constructor.

~ThreadedLog()

StormByte::Logger::ThreadedLog::~ThreadedLog ( )

overridenoexcept

Destructor.

Defined out of line so the line lock is released inside the DLL.

ThreadedLog() [4/4]

StormByte::Logger::ThreadedLog::ThreadedLog ( SinkWrite  write, SinkManip  manip, void *  context, const Level &  level, std::string_view  format  )

protected

Construct a threaded logger that emits through caller callbacks.

Parameters

write	Receives raw bytes.
manip	Applies an ostream manipulator in the caller.
context	Passed back to the callbacks. Not owned.
level	Minimum Level that will be emitted.
format	Header format string.

Member Function Documentation

BeginPayload()

bool StormByte::Logger::ThreadedLog::BeginPayload ( )

overrideprotectedvirtual

Admit a payload and take the line lock.

Returns

false when the payload is filtered or throttled.

Reimplemented from StormByte::Logger::Log.

Clone()

PointerType StormByte::Logger::ThreadedLog::Clone ( ) const

overrideprotectedvirtual

Deep-copy this facade into a StormByte::Shared.

Returns

Pointer to a ThreadedLog that shares Engine and line lock.

Reimplemented from StormByte::Logger::Log.

Color() [1/4]

StormByte::Logger::Color StormByte::Logger::ThreadedLog::Color ( const Level &  level ) const

overridevirtual

Get the configured color for a logging level.

Parameters

level

Level whose color is requested.

Returns

Configured color.

Reimplemented from StormByte::Logger::Log.

Color() [2/4]

Log & StormByte::Logger::ThreadedLog::Color ( const Level &  level, const StormByte::Logger::Color &  color  )

overridevirtual

Set a level color while holding the line lock.

Parameters

level	Level whose color is changed.
color	Color to use for that level.

Returns

Reference to this logger.

Reimplemented from StormByte::Logger::Log.

Color() [3/4]

StormByte::Logger::Color StormByte::Logger::ThreadedLog::Color ( std::string_view  component, const Level &  level  ) const

overridevirtual

Get a component color, falling back along the path then to the general color.

Parameters

component	Component path.
level	Level whose color is requested.

Returns

Component override or general color.

Reimplemented from StormByte::Logger::Log.

Color() [4/4]

Log & StormByte::Logger::ThreadedLog::Color ( std::string_view  component, const Level &  level, const StormByte::Logger::Color &  color  )

overridevirtual

Set a component color override under the line lock.

Parameters

component	Component path.
level	Level whose color is changed.
color	Color to use for that component and level.

Returns

Reference to this logger.

Reimplemented from StormByte::Logger::Log.

FlushThrottle() [1/2]

Log & StormByte::Logger::ThreadedLog::FlushThrottle ( )

overridevirtual

Flush all dropped summaries under the line lock.

Returns

Reference to this logger.

Reimplemented from StormByte::Logger::Log.

FlushThrottle() [2/2]

Log & StormByte::Logger::ThreadedLog::FlushThrottle ( const ThrottleSpec &  spec )

overridevirtual

Flush matching dropped summaries under the line lock.

Parameters

spec	Selectors of the rules to flush.

Returns

Reference to this logger.

Reimplemented from StormByte::Logger::Log.

Format() [1/4]

StormByte::String::String StormByte::Logger::ThreadedLog::Format ( ) const

overridevirtual

Get the effective current header format.

Returns

Owned copy of the temporary, component-specific or general format.

Reimplemented from StormByte::Logger::Log.

Format() [2/4]

StormByte::String::String StormByte::Logger::ThreadedLog::Format ( std::string_view  component ) const

overridevirtual

Get a component-specific format, falling back along the path then to general.

Parameters

component

Component path.

Returns

Owned copy of the component format or general format.

Reimplemented from StormByte::Logger::Log.

Format() [3/4]

Log & StormByte::Logger::ThreadedLog::Format ( std::string_view  component, std::string_view  format  )

overridevirtual

Set or remove a component-specific header format under the line lock.

Parameters

component	Component path.
format	Format, or empty to remove the override.

Returns

Reference to this logger.

Reimplemented from StormByte::Logger::Log.

Format() [4/4]

Log & StormByte::Logger::ThreadedLog::Format ( std::string_view  format )

overridevirtual

Set the header format under the line lock.

Parameters

format

Format used by default, or for the sticky path on a scoped facade.

Returns

Reference to this logger.

Reimplemented from StormByte::Logger::Log.

Move()

PointerType StormByte::Logger::ThreadedLog::Move ( )

overrideprotectedvirtual

Move this facade into a StormByte::Shared.

Returns

Pointer to a ThreadedLog that shares Engine and line lock.

Reimplemented from StormByte::Logger::Log.

NoThrottle() [1/6]

Log & StormByte::Logger::ThreadedLog::NoThrottle ( )

overridevirtual

Remove all throttle rules.

Returns

Reference to this logger.

Reimplemented from StormByte::Logger::Log.

NoThrottle() [2/6]

Log & StormByte::Logger::ThreadedLog::NoThrottle ( ComponentManip  component )

overridevirtual

Remove a component-scoped rule.

Parameters

component

Component path.

Returns

Reference to this logger.

Reimplemented from StormByte::Logger::Log.

NoThrottle() [3/6]

Log & StormByte::Logger::ThreadedLog::NoThrottle ( ComponentManip  component, const Level &  level, GroupManip  group  )

overridevirtual

Remove an exact component/level/group rule.

Parameters

component	Component path used as-is.
level	Level selector.
group	Group selector.

Returns

Reference to this logger.

Reimplemented from StormByte::Logger::Log.

NoThrottle() [4/6]

Log & StormByte::Logger::ThreadedLog::NoThrottle ( const Level &  level )

overridevirtual

Remove a level-scoped rule.

Parameters

level

Level selector.

Returns

Reference to this logger.

Reimplemented from StormByte::Logger::Log.

NoThrottle() [5/6]

Log & StormByte::Logger::ThreadedLog::NoThrottle ( const ThrottleSpec &  spec )

overridevirtual

Remove a throttle rule under the line lock.

Parameters

spec	Selectors of the rule to remove.

Returns

Reference to this logger.

Reimplemented from StormByte::Logger::Log.

NoThrottle() [6/6]

Log & StormByte::Logger::ThreadedLog::NoThrottle ( GroupManip  group )

overridevirtual

Remove a group-scoped rule.

Parameters

group

Group selector.

Returns

Reference to this logger.

Reimplemented from StormByte::Logger::Log.

operator=() [1/2]

ThreadedLog & StormByte::Logger::ThreadedLog::operator=

(

const ThreadedLog &

)

Copy assignment.

Defined out of line so the previous line lock is released inside the DLL.

Returns

Reference to this logger.

Note

Shares the Engine and the line lock.

operator=() [2/2]

ThreadedLog & StormByte::Logger::ThreadedLog::operator= ( ThreadedLog &&  )

noexcept

Move assignment.

Defined out of line so the previous line lock is released inside the DLL.

Returns

Reference to this logger.

Throttle() [1/7]

Log & StormByte::Logger::ThreadedLog::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  )

overridevirtual

Install an exact component/level/group rule.

Parameters

component	Component path used as-is.
level	Level selector.
group	Group selector.
rate	Lines per second.
burst	Token capacity.
policy	Count policy.
value	SampleN or WindowKeep.
period	WindowPeriod when policy is Window.

Returns

Reference to this logger.

Reimplemented from StormByte::Logger::Log.

Throttle() [2/7]

Log & StormByte::Logger::ThreadedLog::Throttle ( ComponentManip  component, double  rate, std::size_t  burst  )

overridevirtual

Install a component-scoped Drop rule.

Parameters

component	Component path.
rate	Lines per second.
burst	Token capacity.

Returns

Reference to this logger.

Reimplemented from StormByte::Logger::Log.

Throttle() [3/7]

Log & StormByte::Logger::ThreadedLog::Throttle ( const Level &  level, double  rate, std::size_t  burst  )

overridevirtual

Install a level-scoped Drop rule.

Parameters

level	Level selector.
rate	Lines per second.
burst	Token capacity.

Returns

Reference to this logger.

Reimplemented from StormByte::Logger::Log.

Throttle() [4/7]

Log & StormByte::Logger::ThreadedLog::Throttle ( const ThrottleSpec &  spec )

overridevirtual

Install a throttle rule under the line lock.

Parameters

spec	Rule to install.

Returns

Reference to this logger.

Reimplemented from StormByte::Logger::Log.

Throttle() [5/7]

Log & StormByte::Logger::ThreadedLog::Throttle ( double  rate, std::size_t  burst  )

overridevirtual

Install a Drop rule.

Parameters

rate	Lines per second.
burst	Token capacity.

Returns

Reference to this logger.

Reimplemented from StormByte::Logger::Log.

Throttle() [6/7]

Log & StormByte::Logger::ThreadedLog::Throttle ( double  rate, std::size_t  burst, ThrottlePolicy  policy, std::size_t  value, std::size_t  period = 0  )

overridevirtual

Install a Sample or Window rule.

Parameters

rate	Lines per second.
burst	Token capacity.
policy	Sample or Window.
value	SampleN or WindowKeep.
period	WindowPeriod when policy is Window.

Returns

Reference to this logger.

Reimplemented from StormByte::Logger::Log.

Throttle() [7/7]

Log & StormByte::Logger::ThreadedLog::Throttle ( GroupManip  group, double  rate, std::size_t  burst  )

overridevirtual

Install a group-scoped Drop rule.

Parameters

group	Group selector.
rate	Lines per second.
burst	Token capacity.

Returns

Reference to this logger.

Reimplemented from StormByte::Logger::Log.

Write() [1/13]

void StormByte::Logger::ThreadedLog::Write ( ColorManip  manip )

overrideprotectedvirtual

Apply a color manipulator under the line lock.

Parameters

manip

Color manipulator.

Reimplemented from StormByte::Logger::Log.

Write() [2/13]

void StormByte::Logger::ThreadedLog::Write ( const Level &  level )

overrideprotectedvirtual

Forward a level change under the line lock.

Parameters

level

Level of the current line.

Reimplemented from StormByte::Logger::Log.

Write() [3/13]

void StormByte::Logger::ThreadedLog::Write ( const wchar_t *  v )

overrideprotectedvirtual

Encode a wide C string before taking the line lock.

Parameters

v	Text to write; may be null.

Reimplemented from StormByte::Logger::Log.

Write() [4/13]

void StormByte::Logger::ThreadedLog::Write ( FormatManip  manip )

overrideprotectedvirtual

Apply a push-format manipulator under the line lock.

Parameters

manip

Format manipulator.

Reimplemented from StormByte::Logger::Log.

Write() [5/13]

void StormByte::Logger::ThreadedLog::Write ( HexManip  m )

overrideprotectedvirtual

Apply hex-dump state under the line lock.

Parameters

m	Hex manipulator.

Reimplemented from StormByte::Logger::Log.

Write() [6/13]

void StormByte::Logger::ThreadedLog::Write ( Log &(*)(Log &) noexcept  manip )

overrideprotectedvirtual

Forward a Log manipulator under the line lock.

Parameters

manip

Logger manipulator.

Reimplemented from StormByte::Logger::Log.

Write() [7/13]

void StormByte::Logger::ThreadedLog::Write ( NoColorManip  manip )

overrideprotectedvirtual

Apply a no-color manipulator under the line lock.

Parameters

manip

No-color manipulator.

Reimplemented from StormByte::Logger::Log.

Write() [8/13]

void StormByte::Logger::ThreadedLog::Write ( NoHexManip  m )

overrideprotectedvirtual

Disable hex dumps under the line lock.

Parameters

m	No-hex manipulator.

Reimplemented from StormByte::Logger::Log.

Write() [9/13]

void StormByte::Logger::ThreadedLog::Write ( PopFormatManip  manip )

overrideprotectedvirtual

Apply a pop-format manipulator under the line lock.

Parameters

manip

Pop-format manipulator.

Reimplemented from StormByte::Logger::Log.

Write() [10/13]

void StormByte::Logger::ThreadedLog::Write ( RedactManip  m )

overrideprotectedvirtual

Apply redaction state under the line lock.

Parameters

m	Redaction manipulator.

Reimplemented from StormByte::Logger::Log.

Write() [11/13]

void StormByte::Logger::ThreadedLog::Write ( std::ostream &(*)(std::ostream &)  manip )

overrideprotectedvirtual

Forward a stream manipulator; newline drops the line lock.

Parameters

manip

Stream manipulator.

Reimplemented from StormByte::Logger::Log.

Write() [12/13]

void StormByte::Logger::ThreadedLog::Write ( std::span< const std::byte >  v )

overrideprotectedvirtual

Format raw bytes before taking the line lock.

Parameters

v	Contiguous bytes to format as Base64 or hex.

Reimplemented from StormByte::Logger::Log.

Write() [13/13]

void StormByte::Logger::ThreadedLog::Write ( std::wstring_view  v )

overrideprotectedvirtual

Encode wide text before taking the line lock.

Parameters

v	Text to write.

Reimplemented from StormByte::Logger::Log.

---

The documentation for this class was generated from the following file:

• lib/public/StormByte/logger/threaded_log.hxx