Global singleton logger with four formatting styles and independently configurable sinks. More...

#include <logger.h>

Collaboration diagram for vlink::Logger:

Classes
struct	NoDetail
	Sentinel type indicating no detail prefix is attached. More...

class	WrapperStream
	RAII helper backing `SLOG_*`; collects tokens and flushes on destruction. More...

Public Types
enum	Style : uint8_t { kStreamStyle = 0 , kFormatStyle = 1 , kCStyle = 2 }
	Internal output style tag used by the `print_*` family. More...

enum	Level : uint8_t { kTrace = 0 , kDebug = 1 , kInfo = 2 , kWarn = 3 , kError = 4 , kFatal = 5 , kOff = 6 }
	Message severity level. More...

using	Callback = MoveFunction< void(Level, std::string_view)>
	Signature for custom console / file sink callbacks. More...

using	DetailInfo = std::pair< std::string_view, int >
	Carries the source file name and line number for the detail prefix. More...

Public Member Functions
template<Logger::Level LevelT, typename DetailT , typename... ArgsT>
void	print_stream_style ([[maybe_unused]] DetailT &&detail, [[maybe_unused]] ArgsT &&... args)

template<Logger::Level LevelT, typename DetailT , typename... ArgsT>
void	print_format_style ([[maybe_unused]] DetailT &&detail, [[maybe_unused]] format::format_string< ArgsT... > format, [[maybe_unused]] ArgsT &&... args)

template<Logger::Level LevelT, typename DetailT , typename FormatT , typename... ArgsT>
void	print_c_style ([[maybe_unused]] DetailT &&detail, [[maybe_unused]] FormatT &&format, [[maybe_unused]] ArgsT &&... args)

template<Logger::Level LevelT, typename... ArgsT>
void	print ([[maybe_unused]] ArgsT &&... args)

Static Public Member Functions
static void	init (const std::string &app_name="", const std::string &log_path="") noexcept
	Initialises the logger singleton. More...

static Logger &	get () noexcept
	Returns the global logger instance. More...

static void	flush () noexcept
	Flushes every active sink. More...

static void	register_console_handler (Callback &&callback) noexcept
	Installs a custom console sink callback replacing the built-in console writer. More...

static void	register_file_handler (Callback &&callback) noexcept
	Installs a custom file sink callback replacing the built-in file writer. More...

static void	set_console_level (Level level) noexcept
	Sets the minimum severity for the console sink; pass `kOff` to mute it. More...

static void	set_file_level (Level level) noexcept
	Sets the minimum severity for the file sink; pass `kOff` to mute it. More...

static void	set_console_fmt_enable (bool enable) noexcept
	Enables or disables ANSI colour / formatting on the console sink. More...

static Level	get_console_level () noexcept
	Returns the current console sink severity threshold. More...

static Level	get_file_level () noexcept
	Returns the current file sink severity threshold. More...

static bool	get_console_fmt_enable () noexcept
	Returns whether ANSI colour codes are enabled on the console sink. More...

static void	set_stream_flag (std::ios_base::fmtflags flags) noexcept
	Sets `std::ios_base` format flags applied to stream-style records. More...

static void	set_stream_precision (int precision) noexcept
	Sets the floating-point precision for stream-style records. More...

static void	set_stream_width (int width) noexcept
	Sets the minimum field width for stream-style records. More...

static std::ios_base::fmtflags	get_stream_flag () noexcept
	Returns the stream format flags currently applied to stream-style records. More...

static int	get_stream_precision () noexcept
	Returns the floating-point precision used for stream-style records. More...

static int	get_stream_width () noexcept
	Returns the field width used for stream-style records. More...

static void	enable_backtrace (size_t size) noexcept
	Enables a ring-buffer backtrace of the most recent `size` records. More...

static void	disable_backtrace () noexcept
	Disables backtrace capture and discards the ring buffer. More...

static void	dump_backtrace () noexcept
	Flushes the backtrace ring buffer to the active sinks. More...

static bool	is_busy () noexcept
	Reports whether the logger is currently writing a record. More...

static bool	is_writable (Level level) noexcept
	Reports whether a record at `level` would currently be emitted. More...

static constexpr std::string_view	extract_filename (std::string_view path) noexcept
	Strips a path down to its final filename component at compile time. More...

template<Level LevelT, typename DetailT , typename... ArgsT>
static void	print_stream_style (DetailT &&detail, ArgsT &&... args)
	Stream-style entry point (used by `VLOG_*` / `print`). More...

template<Level LevelT, typename DetailT , typename... ArgsT>
static void	print_format_style (DetailT &&detail, format::format_string< ArgsT... > format, ArgsT &&... args)
	Placeholder-style entry point (used by `MLOG_*`). More...

template<Logger::Level LevelT, typename DetailT , typename FormatT , typename... ArgsT>
static void	print_c_style (DetailT &&detail, FormatT &&format, ArgsT &&... args)
	printf-style entry point (used by `CLOG_*`). More...

template<Level LevelT, typename... ArgsT>
static void	print (ArgsT &&... args)
	Convenience stream-style entry point without source location. More...

Static Public Attributes
static constexpr uint8_t	kMinimumLevel = kTrace
	Compile-time minimum severity level; messages below this are stripped. More...

static constexpr uint8_t	kDetailLevel = kWarn
	Severity threshold at and above which `{file:line}` is prepended to messages. More...

static constexpr int	kLocalBufferSize = 4096
	Size of the thread-local C-style format buffer in bytes. More...

Friends
template<Logger::Level LevelT>
class	WrapperStream

Detailed Description

Global singleton logger with four formatting styles and independently configurable sinks.

Construct exactly once via Logger::init; subsequent calls reconfigure the existing instance. The console sink is always enabled; the file sink activates when log_path is non-empty. Logging entry points are macros that wrap the public print_* templates and forward a compile-time Level so the bodies disappear when the level is below kMinimumLevel.

Member Typedef Documentation

◆ Callback

using vlink::Logger::Callback = MoveFunction<void(Level, std::string_view)>

Signature for custom console / file sink callbacks.

Invoked synchronously from the logging thread; the std::string_view is valid only for the duration of the call.

◆ DetailInfo

using vlink::Logger::DetailInfo = std::pair<std::string_view, int>

Carries the source file name and line number for the detail prefix.

Built automatically by VLINK_LOG_GET_DETAIL when the message level reaches kDetailLevel.

Member Enumeration Documentation

◆ Level

enum vlink::Logger::Level : uint8_t

Message severity level.

Lower numerical values are less severe. kOff is a sentinel that disables a sink.

Enumerator
kTrace	Verbose tracing.
kDebug	Developer diagnostics.
kInfo	Normal operational message.
kWarn	Recoverable but unusual condition.
kError	Recoverable error.
kFatal	Unrecoverable; throws `Exception::RuntimeError`.
kOff	Disable sink.

◆ Style

enum vlink::Logger::Style : uint8_t

Internal output style tag used by the print_* family.

Callers normally interact with styles via macros; the enum is exposed for completeness.

Enumerator
kStreamStyle	Stream composition via `FastStream` operator<<.
kFormatStyle	Brace placeholders via `vlink::format`.
kCStyle	printf-style formatting via `std::snprintf`.

Member Function Documentation

◆ disable_backtrace()

static void vlink::Logger::disable_backtrace ( )

staticnoexcept

Disables backtrace capture and discards the ring buffer.

◆ dump_backtrace()

static void vlink::Logger::dump_backtrace ( )

staticnoexcept

Flushes the backtrace ring buffer to the active sinks.

◆ enable_backtrace()

static void vlink::Logger::enable_backtrace ( size_t size )

staticnoexcept

Enables a ring-buffer backtrace of the most recent size records.

Parameters

size	Capacity of the backtrace ring buffer.

◆ extract_filename()

constexpr std::string_view vlink::Logger::extract_filename ( std::string_view path )

inlinestaticconstexprnoexcept

Strips a path down to its final filename component at compile time.

Details.

Parameters

path	Source path, typically `FILE`.

Returns: View covering the filename portion.

◆ flush()

static void vlink::Logger::flush ( )

staticnoexcept

Flushes every active sink.

Useful before abnormal termination. Invoked automatically before a kFatal message throws.

◆ get()

static Logger& vlink::Logger::get ( )

staticnoexcept

Returns the global logger instance.

Returns: Reference to the singleton.

◆ get_console_fmt_enable()

static bool vlink::Logger::get_console_fmt_enable ( )

staticnoexcept

Returns whether ANSI colour codes are enabled on the console sink.

Returns: true when ANSI escapes are emitted.

◆ get_console_level()

static Level vlink::Logger::get_console_level ( )

staticnoexcept

Returns the current console sink severity threshold.

Returns: Current level.

◆ get_file_level()

static Level vlink::Logger::get_file_level ( )

staticnoexcept

Returns the current file sink severity threshold.

Returns: Current level.

◆ get_stream_flag()

static std::ios_base::fmtflags vlink::Logger::get_stream_flag ( )

staticnoexcept

Returns the stream format flags currently applied to stream-style records.

Returns: Format flags.

◆ get_stream_precision()

static int vlink::Logger::get_stream_precision ( )

staticnoexcept

Returns the floating-point precision used for stream-style records.

Returns: Precision value.

◆ get_stream_width()

static int vlink::Logger::get_stream_width ( )

staticnoexcept

Returns the field width used for stream-style records.

Returns: Width value.

◆ init()

static void vlink::Logger::init	(	const std::string &	app_name = `""`,
		const std::string &	log_path = `""`
	)

staticnoexcept

Initialises the logger singleton.

Must be invoked before any logging macros. Subsequent calls reconfigure the singleton. Provide a non-empty log_path to activate the file sink.

Parameters

app_name	Application name embedded in log output. Default: empty.
log_path	Absolute path for the file sink. Default: empty (no file sink).

◆ is_busy()

static bool vlink::Logger::is_busy ( )

staticnoexcept

Reports whether the logger is currently writing a record.

Returns: true while a write is in progress.

◆ is_writable()

static bool vlink::Logger::is_writable ( Level level )

staticnoexcept

Reports whether a record at level would currently be emitted.

Use the result to gate expensive argument computation before a macro call.

Parameters

level Severity level under test.

Returns: true when the level passes either sink threshold.

◆ print() [1/2]

template<Logger::Level LevelT, typename... ArgsT>

void vlink::Logger::print ( [[maybe_unused] ] ArgsT &&... args )

inline

◆ print() [2/2]

template<Level LevelT, typename... ArgsT>

static void vlink::Logger::print ( ArgsT &&... args )

static

Convenience stream-style entry point without source location.

Template Parameters

LevelT	Compile-time severity.
ArgsT	Stream argument types.

Parameters

args	Values to stream.

◆ print_c_style() [1/2]

template<Logger::Level LevelT, typename DetailT , typename FormatT , typename... ArgsT>

void vlink::Logger::print_c_style	(	[[maybe_unused] ] DetailT &&	detail,
		[[maybe_unused] ] FormatT &&	format,
		[[maybe_unused] ] ArgsT &&...	args
	)

inline

◆ print_c_style() [2/2]

template<Logger::Level LevelT, typename DetailT , typename FormatT , typename... ArgsT>

static void vlink::Logger::print_c_style	(	DetailT &&	detail,
		FormatT &&	format,
		ArgsT &&...	args
	)

static

printf-style entry point (used by CLOG_*).

Template Parameters

LevelT	Compile-time severity.
DetailT	Either `DetailInfo` or `NoDetail`.
FormatT	Format string type, typically `const` `char*`.
ArgsT	printf argument types.

Parameters

detail	Source location info or `NoDetail{}`.
format	printf-style format string.
args	printf arguments.

◆ print_format_style() [1/2]

template<Logger::Level LevelT, typename DetailT , typename... ArgsT>

void vlink::Logger::print_format_style	(	[[maybe_unused] ] DetailT &&	detail,
		[[maybe_unused] ] format::format_string< ArgsT... >	format,
		[[maybe_unused] ] ArgsT &&...	args
	)

inline

Here is the call graph for this function:

◆ print_format_style() [2/2]

template<Level LevelT, typename DetailT , typename... ArgsT>

static void vlink::Logger::print_format_style	(	DetailT &&	detail,
		format::format_string< ArgsT... >	format,
		ArgsT &&...	args
	)

static

Placeholder-style entry point (used by MLOG_*).

Template Parameters

LevelT	Compile-time severity.
DetailT	Either `DetailInfo` or `NoDetail`.
ArgsT	Format argument types.

Parameters

detail	Source location info or `NoDetail{}`.
format	Format string with `{}` placeholders.
args	Format arguments.

◆ print_stream_style() [1/2]

template<Logger::Level LevelT, typename DetailT , typename... ArgsT>

void vlink::Logger::print_stream_style	(	[[maybe_unused] ] DetailT &&	detail,
		[[maybe_unused] ] ArgsT &&...	args
	)

inline

◆ print_stream_style() [2/2]

template<Level LevelT, typename DetailT , typename... ArgsT>

static void vlink::Logger::print_stream_style	(	DetailT &&	detail,
		ArgsT &&...	args
	)

static

Stream-style entry point (used by VLOG_* / print).

Returns immediately when should_log<LevelT>() is false. Otherwise streams args into a thread-local FastStream and hands the resulting view to the sinks.

Template Parameters

LevelT	Compile-time severity.
DetailT	Either `DetailInfo` or `NoDetail`.
ArgsT	Stream argument types.

Parameters

detail	Source location info or `NoDetail{}`.
args	Values to stream.

◆ register_console_handler()

static void vlink::Logger::register_console_handler ( Callback && callback )

staticnoexcept

Installs a custom console sink callback replacing the built-in console writer.

Parameters

callback Handler called with (level, message_view) for each record.

◆ register_file_handler()

static void vlink::Logger::register_file_handler ( Callback && callback )

staticnoexcept

Installs a custom file sink callback replacing the built-in file writer.

Parameters

callback Handler called with (level, message_view) for each record.

◆ set_console_fmt_enable()

static void vlink::Logger::set_console_fmt_enable ( bool enable )

staticnoexcept

Enables or disables ANSI colour / formatting on the console sink.

Parameters

enable true to keep ANSI escapes (default), false for plain text.

◆ set_console_level()

static void vlink::Logger::set_console_level ( Level level )

staticnoexcept

Sets the minimum severity for the console sink; pass kOff to mute it.

Parameters

level Minimum output level.

◆ set_file_level()

static void vlink::Logger::set_file_level ( Level level )

staticnoexcept

Sets the minimum severity for the file sink; pass kOff to mute it.

Parameters

level Minimum output level.

◆ set_stream_flag()

static void vlink::Logger::set_stream_flag ( std::ios_base::fmtflags flags )

staticnoexcept

Sets std::ios_base format flags applied to stream-style records.

Parameters

flags Stream format flags.

◆ set_stream_precision()

static void vlink::Logger::set_stream_precision ( int precision )

staticnoexcept

Sets the floating-point precision for stream-style records.

Parameters

precision Precision passed to std::setprecision.

◆ set_stream_width()

static void vlink::Logger::set_stream_width ( int width )

staticnoexcept

Sets the minimum field width for stream-style records.

Parameters

width Field width passed to std::setw.

Friends And Related Function Documentation

◆ WrapperStream

template<Logger::Level LevelT>

friend class WrapperStream

friend

Member Data Documentation

◆ kDetailLevel

constexpr uint8_t vlink::Logger::kDetailLevel = kWarn

staticconstexpr

Severity threshold at and above which {file:line} is prepended to messages.

Override by defining VLINK_LOG_DETAIL_LEVEL before including this header. Defaults to kWarn.

◆ kLocalBufferSize

constexpr int vlink::Logger::kLocalBufferSize = 4096

staticconstexpr

Size of the thread-local C-style format buffer in bytes.

Messages longer than kLocalBufferSize - 1 characters are silently truncated.

◆ kMinimumLevel

constexpr uint8_t vlink::Logger::kMinimumLevel = kTrace

staticconstexpr

Compile-time minimum severity level; messages below this are stripped.

Override by defining VLINK_LOG_LEVEL before including this header. Defaults to kTrace so every level is emitted by default.

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

include/vlink/base/logger.h

Classes

Public Types

Public Member Functions

Static Public Member Functions

Static Public Attributes

Friends

Detailed Description

Member Typedef Documentation

◆ Callback

◆ DetailInfo

Member Enumeration Documentation

◆ Level

◆ Style

Member Function Documentation

◆ disable_backtrace()

◆ dump_backtrace()

◆ enable_backtrace()

◆ extract_filename()

◆ flush()

◆ get()

◆ get_console_fmt_enable()

◆ get_console_level()

◆ get_file_level()

◆ get_stream_flag()

◆ get_stream_precision()

◆ get_stream_width()

◆ init()

◆ is_busy()

◆ is_writable()

◆ print() [1/2]

◆ print() [2/2]

◆ print_c_style() [1/2]

◆ print_c_style() [2/2]

◆ print_format_style() [1/2]

◆ print_format_style() [2/2]

◆ print_stream_style() [1/2]

◆ print_stream_style() [2/2]

◆ register_console_handler()

◆ register_file_handler()

◆ set_console_fmt_enable()

◆ set_console_level()

◆ set_file_level()

◆ set_stream_flag()

◆ set_stream_precision()

◆ set_stream_width()

Friends And Related Function Documentation

◆ WrapperStream

Member Data Documentation

◆ kDetailLevel

◆ kLocalBufferSize

◆ kMinimumLevel