vlink::Logger Class Reference

Global singleton logger supporting three output styles and configurable log levels. More...

#include <logger.h>

Collaboration diagram for vlink::Logger:

Classes
struct	NoDetail
	Sentinel type indicating that no file/line detail is attached. More...
class	WrapperStream
	RAII stream wrapper that accumulates tokens and flushes on destruction. More...

Public Types
enum	Style : uint8_t { kStreamStyle = 0 , kFormatStyle = 1 , kCStyle = 2 }
	Output style selector (used internally by the print_* family). More...
enum	Level : uint8_t {   kTrace = 0 , kDebug = 1 , kInfo = 2 , kWarn = 3 ,   kError = 4 , kFatal = 5 , kOff = 6 }
	Severity level for log messages. More...
using	Callback = std::function<void(Level, std::string_view)>
	Callback type for custom console or file log handlers.
using	DetailInfo = std::pair<std::string_view, int>
	Carries the source file name and line number for detail annotation.

Static Public Member Functions
static void	init (const std::string &app_name="", const std::string &log_path="") noexcept
	Initialises the logger singleton.
static Logger &	get () noexcept
	Returns the logger singleton instance.
static void	flush () noexcept
	Flushes all buffered log messages to the active sinks.
static void	register_console_handler (Callback &&callback) noexcept
	Registers a custom handler for console log output.
static void	register_file_handler (Callback &&callback) noexcept
	Registers a custom handler for file log output.
static void	set_console_level (Level level) noexcept
	Sets the minimum level for the console sink.
static void	set_file_level (Level level) noexcept
	Sets the minimum level for the file sink.
static void	set_console_fmt_enable (bool enable) noexcept
	Enables or disables ANSI colour/format codes in console output.
static Level	get_console_level () noexcept
	Returns the current minimum level for the console sink.
static Level	get_file_level () noexcept
	Returns the current minimum level for the file sink.
static bool	get_console_fmt_enable () noexcept
	Returns whether ANSI colour/format codes are enabled for console output.
static void	set_stream_flag (std::ios_base::fmtflags flags) noexcept
	Sets std::ios_base format flags applied to stream-style messages.
static void	set_stream_precision (int precision) noexcept
	Sets the floating-point precision for stream-style messages.
static void	set_stream_width (int width) noexcept
	Sets the output field width for stream-style messages.
static std::ios_base::fmtflags	get_stream_flag () noexcept
	Returns the std::ios_base format flags currently applied to stream output.
static int	get_stream_precision () noexcept
	Returns the floating-point precision currently used for stream output.
static int	get_stream_width () noexcept
	Returns the field width currently used for stream output.
static void	enable_backtrace (size_t size) noexcept
	Enables a ring-buffer backtrace of the last size log messages.
static void	disable_backtrace () noexcept
	Disables backtrace collection and clears the ring buffer.
static void	dump_backtrace () noexcept
	Flushes the backtrace ring buffer to the active sinks.
static bool	is_busy () noexcept
	Returns true if the logger is currently busy writing a message.
static bool	is_writable (Level level) noexcept
	Returns true if a message at level would be written to at least one sink.
static constexpr std::string_view	extract_filename (std::string_view path) noexcept
	Extracts the file name component from a full path at compile time.
template<Level LevelT, typename DetailT, typename... ArgsT>
static void	print_stream_style (DetailT &&detail, ArgsT &&... args)
	Logs using stream-style composition (operator<<).
template<Level LevelT, typename DetailT, typename... ArgsT>
static void	print_format_style (DetailT &&detail, format::format_string< ArgsT... > format, ArgsT &&... args)
	Logs using {} placeholder format style.
template<Logger::Level LevelT, typename DetailT, typename FormatT, typename... ArgsT>
static void	print_c_style (DetailT &&detail, FormatT &&format, ArgsT &&... args)
	Logs using C-style printf format string.
template<Level LevelT, typename... ArgsT>
static void	print (ArgsT &&... args)
	Logs using stream style without file/line detail.

Static Public Attributes
static constexpr uint8_t	kMinimumLevel = kTrace
	Compile-time minimum log level.
static constexpr uint8_t	kDetailLevel = kWarn
	Threshold above which file and line information is appended to messages.
static constexpr int	kLocalBufferSize = 4096
	Size of the thread-local C-style format buffer in bytes.

Friends
template<Logger::Level LevelT>
class	WrapperStream

Detailed Description

Global singleton logger supporting three output styles and configurable log levels.

Construct the singleton with Logger::init() once at application startup. Use the VLOG_*, MLOG_*, CLOG_* or SLOG_* macros for logging.

Member Typedef Documentation

Callback

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

Callback type for custom console or file log handlers.

Registered handlers are called 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 detail annotation.

Created automatically by VLINK_LOG_GET_DETAIL when the message level is >= kDetailLevel.

Member Enumeration Documentation

Level

enum vlink::Logger::Level : uint8_t

Severity level for log messages.

Levels are ordered from least severe (kTrace) to most severe (kFatal). kOff disables the corresponding sink entirely.

Value	Name	Meaning
0	kTrace	Verbose tracing
1	kDebug	Developer diagnostics
2	kInfo	Normal operational messages
3	kWarn	Unusual but recoverable conditions
4	kError	Recoverable errors
5	kFatal	Throws RuntimeError after logging
6	kOff	Disable sink

Enumerator
kTrace
kDebug
kInfo
kWarn
kError
kFatal
kOff

Style

enum vlink::Logger::Style : uint8_t

Output style selector (used internally by the print_* family).

Determines how format arguments are converted to a string. Users interact with styles through macros rather than this enum directly.

Enumerator
kStreamStyle	operator<< stream composition via FastStream
kFormatStyle	Python-style {} placeholders via vlink::format.
kCStyle	printf-style d/s via std::snprintf

Member Function Documentation

disable_backtrace()

void vlink::Logger::disable_backtrace ( )

staticnoexcept

Disables backtrace collection and clears the ring buffer.

Here is the call graph for this function:

Here is the caller graph for this function:

dump_backtrace()

void vlink::Logger::dump_backtrace ( )

staticnoexcept

Flushes the backtrace ring buffer to the active sinks.

Emits all retained backtrace messages (if any) to the console and file sinks at their original log levels. Useful just before an abort or fatal handler.

Here is the call graph for this function:

Here is the caller graph for this function:

enable_backtrace()

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

staticnoexcept

Enables a ring-buffer backtrace of the last size log messages.

When enabled, the last size messages are retained in memory regardless of the current log level, and can be flushed with dump_backtrace().

Parameters

size	Number of messages to retain in the backtrace ring buffer.

Here is the call graph for this function:

Here is the caller graph for this function:

extract_filename()

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

inlinestaticnodiscardconstexprnoexcept

Extracts the file name component from a full path at compile time.

Details.

Searches for the last '/' or '\' and returns the substring after it. Used by the VLINK_LOG_GET_DETAIL macro to trim FILE.

Parameters

path	Full source file path (typically __FILE__).

Returns

string_view of just the filename portion.

Here is the call graph for this function:

Here is the caller graph for this function:

flush()

void vlink::Logger::flush ( )

staticnoexcept

Flushes all buffered log messages to the active sinks.

Useful before abnormal termination to ensure messages are not lost. Called automatically for kFatal messages.

Here is the call graph for this function:

Here is the caller graph for this function:

get()

Logger & vlink::Logger::get ( )

staticnoexcept

Returns the logger singleton instance.

The singleton is created on first use. It is safe to call get() from any thread after init() has been called.

Returns

Reference to the global Logger instance.

Here is the call graph for this function:

Here is the caller graph for this function:

get_console_fmt_enable()

bool vlink::Logger::get_console_fmt_enable ( )

staticnodiscardnoexcept

Returns whether ANSI colour/format codes are enabled for console output.

Returns

true if formatting is enabled.

Here is the call graph for this function:

Here is the caller graph for this function:

get_console_level()

Level vlink::Logger::get_console_level ( )

staticnodiscardnoexcept

Returns the current minimum level for the console sink.

Returns

Current console log level.

Here is the call graph for this function:

Here is the caller graph for this function:

get_file_level()

Level vlink::Logger::get_file_level ( )

staticnodiscardnoexcept

Returns the current minimum level for the file sink.

Returns

Current file log level.

Here is the call graph for this function:

Here is the caller graph for this function:

get_stream_flag()

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

staticnodiscardnoexcept

Returns the std::ios_base format flags currently applied to stream output.

Returns

Current stream format flags.

Here is the call graph for this function:

Here is the caller graph for this function:

get_stream_precision()

int vlink::Logger::get_stream_precision ( )

staticnodiscardnoexcept

Returns the floating-point precision currently used for stream output.

Returns

Current precision value.

Here is the call graph for this function:

Here is the caller graph for this function:

get_stream_width()

int vlink::Logger::get_stream_width ( )

staticnodiscardnoexcept

Returns the field width currently used for stream output.

Returns

Current field width.

Here is the call graph for this function:

Here is the caller graph for this function:

init()

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

staticnoexcept

Initialises the logger singleton.

Must be called before any log macros are invoked. Safe to call multiple times; subsequent calls reconfigure the logger. If log_path is non-empty, the file sink is opened at that path.

Parameters

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

is_busy()

bool vlink::Logger::is_busy ( )

staticnodiscardnoexcept

Returns true if the logger is currently busy writing a message.

Useful for asynchronous backends to check whether the logger can accept more work.

Returns

true if a write is in progress.

Here is the call graph for this function:

Here is the caller graph for this function:

is_writable()

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

staticnodiscardnoexcept

Returns true if a message at level would be written to at least one sink.

Checks both the console and file sink levels. kFatal always returns true. Call this before constructing expensive log arguments to avoid unnecessary work.

Parameters

level

Level to test.

Returns

true if the message would be emitted.

Here is the call graph for this function:

Here is the caller graph for this function:

print()

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

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

inlinestatic

Logs using stream style without file/line detail.

Convenience wrapper that passes NoDetail{} to print_stream_style.

Template Parameters

LevelT	Compile-time log level.
ArgsT	Types of the stream arguments.

Parameters

args	Values to stream.

Here is the call graph for this function:

Here is the caller graph for this function:

print_c_style()

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

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

inlinestatic

Logs using C-style printf format string.

Called by the CLOG_* macros. Formats using std::snprintf into a 4096-byte thread-local buffer. Messages exceeding the buffer are truncated.

Template Parameters

LevelT	Compile-time log level.
DetailT	Either DetailInfo or NoDetail.
FormatT	Type of the format string (typically const char*).
ArgsT	Types of the printf arguments.

Parameters

detail	File/line info or NoDetail{}.
format	printf-style format string.
args	printf arguments.

Here is the call graph for this function:

Here is the caller graph for this function:

print_format_style()

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

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

inlinestatic

Logs using {} placeholder format style.

Called by the MLOG_* macros. Formats the message using format::format_to_n into a 4096-byte thread-local buffer. Messages exceeding the buffer are truncated.

Template Parameters

LevelT	Compile-time log level.
DetailT	Either DetailInfo or NoDetail.
ArgsT	Types of the format arguments.

Parameters

detail	File/line info or NoDetail{}.
format	Format string with {} placeholders.
args	Format arguments.

Here is the call graph for this function:

Here is the caller graph for this function:

print_stream_style()

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

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

inlinestatic

Logs using stream-style composition (operator<<).

Called by the VLOG_* macros. Checks should_log() first; returns immediately if the level is disabled. Uses a thread-local FastStream to avoid heap allocations.

Template Parameters

LevelT	Compile-time log level.
DetailT	Either DetailInfo (with file/line) or NoDetail.
ArgsT	Types of the stream arguments.

Parameters

detail	File/line info or NoDetail{}.
args	Values streamed into the message via operator<<.

Here is the call graph for this function:

Here is the caller graph for this function:

register_console_handler()

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

staticnoexcept

Registers a custom handler for console log output.

When set, the provided callback is invoked instead of (or in addition to) the built-in console sink. Replaces any previously registered console handler.

Parameters

callback

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

Here is the call graph for this function:

Here is the caller graph for this function:

register_file_handler()

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

staticnoexcept

Registers a custom handler for file log output.

When set, the provided callback is invoked instead of (or in addition to) the built-in file sink. Replaces any previously registered file handler.

Parameters

callback

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

Here is the call graph for this function:

Here is the caller graph for this function:

set_console_fmt_enable()

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

staticnoexcept

Enables or disables ANSI colour/format codes in console output.

Parameters

enable

true to enable formatting codes (default), false for plain text.

Here is the call graph for this function:

Here is the caller graph for this function:

set_console_level()

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

staticnoexcept

Sets the minimum level for the console sink.

Messages with level < level are not written to the console. Pass kOff to disable the console sink entirely.

Parameters

level

New minimum console output level.

Here is the call graph for this function:

Here is the caller graph for this function:

set_file_level()

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

staticnoexcept

Sets the minimum level for the file sink.

Messages with level < level are not written to the log file. Pass kOff to disable the file sink entirely.

Parameters

level

New minimum file output level.

Here is the call graph for this function:

Here is the caller graph for this function:

set_stream_flag()

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

staticnoexcept

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

The flags are applied to the thread-local FastStream before each message. For example, pass std::ios::hex to print integers in hexadecimal.

Parameters

flags

Format flags to set.

Here is the call graph for this function:

Here is the caller graph for this function:

set_stream_precision()

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

staticnoexcept

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

Parameters

precision

Number of significant digits (or decimal places depending on format flag).

Here is the call graph for this function:

Here is the caller graph for this function:

set_stream_width()

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

staticnoexcept

Sets the output field width for stream-style messages.

Parameters

width

Minimum field width in characters.

Here is the call graph for this function:

Here is the caller graph for this function:

Friends And Related Symbol Documentation

WrapperStream

template<Logger::Level LevelT>

friend class WrapperStream

friend

Member Data Documentation

kDetailLevel

uint8_t vlink::Logger::kDetailLevel = kWarn

staticconstexpr

Threshold above which file and line information is appended to messages.

When the message level >= kDetailLevel, the macro prepends {file:line} to the log string. Override by defining VLINK_LOG_DETAIL_LEVEL. Defaults to kWarn.

kLocalBufferSize

int vlink::Logger::kLocalBufferSize = 4096

staticconstexpr

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

Used by print_c_style() and print_format_style(). Messages longer than kLocalBufferSize - 1 characters are silently truncated.

kMinimumLevel

uint8_t vlink::Logger::kMinimumLevel = kTrace

staticconstexpr

Compile-time minimum log level.

Messages with level < kMinimumLevel are compiled away completely. Override by defining VLINK_LOG_LEVEL before including this header. Defaults to kTrace (all messages enabled).

---

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

• include/vlink/base/logger.h